SockHop Universal Field Names

Whenever a BMessage is posted into the SockHop processing tree, it is scanned for certain standard field names.  These field names are used to determine how the BMessage should be handled.  Each of these field names starts with the letters 'sh', followed by a capital letter and then possibly some more letters.  To avoid conflicts, please do not use similarly named fields for other purposes in BMessages you send over SockHop.  These standard field names are enumerated in the file <sockhop/SockHopConstants.h>.

Note that all the SH_NAME_* fields listed here are optional;  no BMessage is required to include any of them.

Listing of SH_NAME string constants




 
Success event triggers for each BMessage type
SH_COMMAND_ADDCOMPONENTS Whenever a node has created and connected to a child node, instantiated and added an SHSorter or SHWorker, or cached a file as requested by this BMessage.  Success BMessages may have a string, SHNodeSpec or SHFileSpec added to their SH_NAME_REGARDING field to assist you in determining which action succeeded.
SH_COMMAND_SETPARAMETERS Whenever a parameter was successfully set to a value contained in this BMessage.  The name/value pair that was successfully set will be added to the reply BMessage to let you know which action succeeded.
SH_COMMAND_GETPARAMETERS As soon as this BMessage is received.  Success BMessages will have parameter name/value pairs added to them before they are posted.
SH_COMMAND_QUIT Will not cause a success message to be sent.
(all other message types) Immediately, whenever the BMessage arrives at a target (e.g. receiving) node.  The success message will be sent regardless of whether any SHWorkers actually process the BMessage, and regardless of what they do with it.
 
Click here for examples of how to use SH_NAME_ONSUCCESS.


SH_NAME_ONFAILURE  
Failure event triggers for each BMessage type
SH_COMMAND_ADDCOMPONENTS Whenever a node has failed to create and connect to a child node, or the connection to a child node has been severed, or an SHWorker or SHSorter could not be instantiated, or a requested file could not be cached.  Failure BMessages may have a SHNodeSpec or SHFileSpec added to their SH_NAME_REGARDING field to assist you in determining which action failed.
SH_COMMAND_SETPARAMETERS Whenever a parameter specified in this BMessage could not be set.  Failure BMessages will have the name/value pair of the offending parameter added to them to assist you in determining which parameter set failed.
SH_COMMAND_GETPARAMETERS Whenever a parameter specified in this BMessage did not exist.  The name of the non-existent parameter will be added to the Failure BMessages to tell you which parameter could not be found.
SH_COMMAND_QUIT Should never fail.
(all other message types) Never (user messages always succeed on any node they arrive at)

       Click here for examples of how to use SH_NAME_ONFAILURE.




Fields added by SockHop to reply BMessages

Sometimes SockHop nodes will add one of the following fields to a BMessage before posting it back into the network.  You are not meant to put these fields into BMessages that you give to SockHop, rather you can read them out of BMessages you get from SockHop.