-*- emacs-wiki -*-

* Objects
** [[message_digest]] object
** [[pb_stream]]
** [[state]] object
** [[connection]] object
** [[state_microcode]] object

* paramaters and return values

All the callout functions will be passed objects by reference. These 
objects will map directly to pluto internals, and changes to them will be
reflected in the object directly (they are value/result parameters).

The callout functions will return strings, which must be from the following
set:

** ignore

The message is ignored.

** stolen

The message is ignored, but will not be freed. It is assumed that a 
reference has been kept. 

** continue

Continue processing the message.

** modified

The payloads have been adjusted, the structures will need to be adjusted
again.

** stf_*

Change the result code to the given stf_ value.

** drop

Do not send any outgoing message.

* callout functions

** proc recvRawMessage

This proceedure is called as soon as the packet has been received and
demarshalled. An object represending the message header is provided, as
well as a [[pb_stream]] of the raw message. Both may be changed.

** proc recvMessage

This proceedure is called after the message has been decrypted (if it was
encrypted), and each of the payloads has been broken off into seperate
pieces.

This routine will be provided with the following objects:

*** [[state]] object
*** [[connection]] object
*** [[message_digest]] object
*** [[state_microcode]] object

This routine may return an additional return value of "ignore-hash", which
means to continue, but if the hash does not match, processing will still
continue. If the routine wishes to purposely break the hash, it shold simply
damage the hash payload.

** proc changeState

This proceedure is called prior to invoking the state specific function.
It is provided with a copy of the [[state_microcode]] object. It may modify
the object if it wishes, causing a different state transition to occur.

** proc adjustFailure

This proceedure is called after the state specific function, but before any
additional post-processing. It is provided the [[state]] object and the
[[stf_status]] code (a string). It may return a different [[stf_status]] code.

** proc avoidEmitting

This proceedure is called just prior to sending the outgoing message. The
message may already have been encrypted. The proceedure may return "drop" or
"continue" to cause the message to be sent or not.

This proceedure is called with a [[pb_stream]] object of the outgoing message,
and the [[state]] object to which it applies.

** proc outgoingClearText

This proceedure is called within the encrypt packet routine. It is provided
with a [[pb_stream]] of the cleartext of the message that is about to be
encrypted. It may modify this stream in any way that it likes.

It may also return "stolen" which cause a copy of the resulting packet to be
made. The packet may still be sent unless avoidEmitting decides not to send
the packet.

** proc sixtySeconds

This proceedure is called every sixty seconds. It may return a previously
stolen [[pb_stream]] and [[state object]], and the packet will be encrypted
and sent. 

Tcl Mode causes some TclModeProcesses.