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
SH_NAME_TO is used to specify which nodes in the tree will receive the BMessage. (Here, "receive" is used in the sense that the BMessage is processed on the receiving nodes--as distinguished from the alternate situation, where a BMessages "passes through" a node in the tree and is forwarded onward, without being "received" by that node)
The SH_NAME_TO field in a BMessage is not read by SockHop nodes per se; but it is read by SHWi1dPathSorters. And since every SockHop node starts up with an SHWi1dPathSorter object running as the default sorter, SH_NAME_TO will be parsed out of all BMessages where you don't explicitely specify that another SHSorter be used to route the BMessage.
SH_NAME_TOWORKERS can be used to specify, for each node that the BMessage is processed on, which SHWorkers should be given a copy of the BMessage. The SH_NAME_TOWORKERS field should be a string, or array of strings, each specifying either the name of an SHWorker, or a regular expression that specifies a set of SHWorker names. If the SH_NAME_TOWORKERS field is not included in a BMessage, then the BMessage will be given to all interested SHWorkers on each receiving node.
Note that in order for an SHWorker to receive a BMessage, two things must be true: the SHSorter must be willing to give it the BMessage, and the SHWorker must be interested in the BMessage. For the SHWi1dPathSorter that is the default SockHop message router, this SH_NAME_TOWORKERS field determines the former condition. The SHWorker subclass determines the other.
Note also that the SH_NAME_TOWORKERS field, like the SH_NAME_TO field,
is actually meaningful only to the SHWi1dPathSorter,
not to the SockHop message distribution code itself. Thus, if you
specify a different SHSorter to use, this field
may not have any effect.
Click here for examples of how to use SH_NAME_TOWORKERS.
This field may contain an array of one or BMessages. When a node decides that the operation represented by this BMessage has succeeded for that node, it will post all the BMessages in this field to the SockHop network. Thus, if you want to be notified if and when an operation has succeeded, you can add one or more BMessages to this field. You will want to add SH_NAME_TO fields to each "success message" in the array to indicate where that BMessage should be sent. Note that in many cases you will get multiple copies of your "success messages" back (one copy of each BMessage in the SH_NAME_ONSUCCESS array per receiving node per success event).
What it means for a BMessage to "succeed" a node depends on the type of the BMessage. Here is a table showing what processing event triggers a "success event" (and thus a posting of all success messages from that node) for each message 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_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.
This field also may contain an array of BMessages, however it behaves quite differently than the fields documented above. The BMessages contained in this field are guaranteed to be posted exactly once, by the same node that this BMessage was originally posted to, and they are guaranteed to not be posted until the operation represented by this BMessage is "complete".
Now, what does "complete" mean? In general, it means that all the "success messages" and "failure messages" that were requested in the same BMessage as the SH_NAME_WHENDONE field have already been sent--no more will arrive after the "done messages" have been received. This is handy, since it lets you know when can stop waiting for "on success" and "on failure" messages and proceed to the next step in your setup process.
There is an exception to the above rule, however. The exception is this: if your BMessage is an SH_COMMAND_ADDCOMPONENTS BMessage that contains an SH_NAME_CHILDREN field (and thus will have the effect of connecting new nodes to the tree), then it is possible that you will "failure messages" for this BMessage even after you received your "done messages". The reason for this is that child nodes can be all successfully set up (causing the "done messages" to be sent), and then at some later time the TCP connection to them may be closed (by a network glitch, computer crash, or because the nodes themselves decided to terminate)--causing a "failure message" to be sent to notify you of the disappearance of the child node.
This field may contain a single string, and allows you to specify the name of the SHSorter to be used to route this BMessage. If this field is not specified, each SockHop node will automatically use its default SHSorter to route the BMessage. Unless you have used SH_COMMAND_SETPARAMETERS to change the default SHSorter on a node, the default sorter used will be an SHWi1dPathSorter (whose name, in case you feel the need to specify it explicitely, is "wi1dpath").
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.