Protocols manipulate messages (e.g., add and strip headers, fragment and reassemble packets) using the following set of operations.
Returns the number of bytes of data in message.
int msgLength(Msg *message)
Truncates the data in message to the given length. An attempt to to reduce the length to less than zero will result in no change to the message. No storage is freed as a result of truncation. This operation is used to strip trailers from a message.
void msgTruncate(Msg *message, int newLength)
Removes length bytes from the front of original_msg and assigns them to fragment_msg. No copying is done. This operation is used to fragment a message into smaller pieces. Both messages must be valid at the time of the call.
void msgBreak(Msg *original_msg, Msg *fragment_msg, int length)
Assigns (in the same sense as msgAssign) to new_msg the concatenation of message fragment1 to the front of fragment2. This operation is used to reassemble fragments into a larger message. The first argument must be a valid message. The arguments need not refer to distinct messages. One common use of msgJoin is to attach a fragment to the end of a larger message, in which case the first two arguments are the same (the larger message) and the third argument is the fragment.
void msgJoin(Msg *new_msg, Msg *fragment1, Msg *fragment2)
Used to prepend space for a header to the front of a message. Returns a pointer to contiguous buffer of length bytes that is logically attached to the front of message. Typically, a header is then copied into this buffer.
char *msgPush(Msg *message, int length)
Used to remove a header from the front of a message. Returns a pointer to a contiguous buffer of length bytes that contains the data that was at the front of message and removes length bytes from the front of the message.
char *msgPop(Msg *message, int length)
Used to examine a header at the front of a message. Returns a pointer to a contiguous buffer of length bytes that contains the data at the front of message. The message remains unchanged.
char *msgPeek(Msg *message, int length)
Used to remove and discard a header of length length from the front of a message. msgDiscard is faster than msgPop since it doesn't have to worry about making the returned buffer contiguous.
void msgDiscard(Msg *message, int length)
Associates an attribute of length bytes with name and attaches it to message message. Setting an attribute overrides any previous attribute with the same name. Message attributes are used to communicate ancillary properties of messages from a protocol to a session, or between protocols.
The only name supported at this time is 0. Attempting to set an attribute with another name will result in an XK_FAILURE return value.
XkReturn msgSetAttr(Msg *message, int name, void *attribute, int length)
Retrieves an attribute previously attached to message message with name. If no attribute has been associated with name, 0 will be returned.
void *msgGetAttr(Msg *message, int name)
Intializes the context cxt for message, as required by msgWalk.
void msgWalkInit(MsgWalk *cxt, Msg *message)
Walks the tree structure of buffers that hold the message data, and returns a pointer to the next chunk of data in the message. Also sets length to the number of bytes in that chunk. Argument cxt maintains the context for the message traversal, so that msgWalk knows how far through the tree it got on the last invocation.
char *msgWalkNext(MsgWalk *cxt, int *length)
Destroys the context cxt used by msgWalkNext.
void msgCleanUp(Msg *message)
Frees unnecessary resources allocated to message.
void msgCleanUp(Msg *message)
Shows information about message. Only valid when compiling in DEBUG mode.
void msgShow(Msg *message)
Prints statistics about message. Only valid when compiling with OPTION_MSG_STATISTICS defined.
void msgStats(MsgWalk *message)