Manipulation Operations

Protocols manipulate messages-e.g., add and strip headers, fragment and reassemble packets-using the following set of operations.

msgLen

Returns the number of bytes of data in message this.

long msgLen (Msg * this);

msgTruncate

Truncates the data in the message this to the given length. Attempts 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* this, long newLength);

msgChopOff

Removes data from the message this and assign it to the message head. 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.

3.1 Compatibility notes: The 3.1 version of this was msg_break, but the arguments were reversed.

void msgChopOff (Msg* this, Msg* head, long len);

msgJoin

Assigns (in the same sense as msgAssign) to this message the concatenation of messages m1 to the front of m2. 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.

void msgJoin (Msg* this, Msg* m1, Msg* m2);

Example of using non-unique arguments:

msgJoin ( this, this, MessageTail);

msgPush

Prepends data pointed to by hdr to the front of message this. The supplied function store will be called with the hdr pointer, a pointer to the message data area where the header data can be copied, the hdrLen value indicating the length of the data, and the arg pointer. The last argument is not interpreted by the msgPush function; its semantics are determined entirely by the user store function.

void msgPush (Msg* this, MStoreFun store, void * hdr, long hdrLen, void * arg);

Function store typically converts the header to network byte order and stores it in a potentially unaligned buffer; len is the number of bytes to be read and arg is an arbitrary argument passed through from msgPush.

typedef void (*MStoreFun )(void * hdr, char * des, long len, void * arg);

Example Declaration: void copypush(void * src, char * dst, long count, void * type))

msgPop

Removes data from the front of message this. After making the requested data contiguous, msgPop calls the function load with the hdr argument, a pointer to the start of the contiguous data, hdrLen, and the arg pointer. Function load should return an integer representing the amount data that should be popped off the message. In optimized code, no validity check is done on this number. This function returns TRUE if successful, FALSE if the message is shorter than hdrLen bytes.

bool msgPop (Msg* this, MLoadFun load, void * hdr, long hdrLen, void * arg);

Function load loads the header from a potentially unaligned buffer and converts it to machine byte order. The len is the number of bytes guaranteed contiguous and arg is an arbitrary argument passed through from msgPop. This function should return the number of bytes to be actually popped from the message. This information is used by msgPop to update the internal message structure.

typedef long (*MLoadFun )(void * hdr, char * src, long len, void * arg);

Example declaration: long copypop( void * dst, char * src, long count, void * type))

msgPopDiscard

Discards len bytes from the front of message this. Returns TRUE if successful.

bool msgPopDiscard (Msg * this, long len)

msgAppend

Appends data pointed to by tail to the end of message this. The supplied function store will be called with the tail pointer, a pointer to the message data area where the data can be copied, the tailLen value indicating the length in bytes fo the data, and the arg pointer. If it is necessary to allocate new space to hold the data, the newlength parameter designates the minimum amount of space for the allocation. See msgConstructAppend, also.

void msgAppend (Msg* this, MStoreFun store, void * tail, long tailLen, void * arg, long newlength);

msgSetAttr

Associates an attribute of len bytes with name and attaches it to message this. 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.

xkern_return_t msgSetAttr (Msg * this, int name, void * attribute, int len);

msgGetAttr

Retrieves an attribute previously attached to message this with name. If no attribute has been associated with name, 0 will be returned.

void * msgGetAttr (Msg * this, int name );

msgForEach

For each contiguous data area in the message, invokes the function f with three arguments: the address of the data, the length of the data, and a user supplied argument arg. The iteration stops when f does not return TRUE.

void msgForEach (Msg * this, XCharFun f, void * arg);

typedef bool (*XCharFun )(char * ptr, long len, void * arg);