Convenience Functions

When defining custom datatypes, programs have the option to also define convenience functions for the new type. In general, layer 4 convenience functions rely on layer 3 generic field functions to do most of their work, packing or unpacking the field structure as appropriate. You can choose to implement up to three convenience functions:

•

Get a value of the custom datatype from a message.

•

Add a value of the custom datatype to a message.

•

Update an existing field in a message with a new value of the custom datatype.

Get

The get function must fulfill these responsibilities:

•

Call tibrvMsg_GetField() to find the field in the message.

•

Check that tibrvMsg_GetField() did not return an error code.

•

Check that the type of the field matches the target datatype of the convenience function.

—

If the conversion is illegal, return an error code.

—

If it matches, then return, passing back the data directly.

—

Otherwise, convert the data to the target datatype. Pass back the converted data. (In most cases, converter functions associated with the actual datatype are unable to convert it to a custom type, so either the convenience function must convert it, or declare the conversion illegal.)

Add and Update

The add and update functions must fulfill these responsibilities:

•

Validate the integrity of the data.

•

Create a field object (tibrvMsgField) on the stack, and set all six of its parts to describe the data.

•

Store it in the message:

—

Add calls tibrvMsg_AddField() to add the field object to the message.

—

Update calls tibrvMsg_UpdateField() to update an existing field in the message with the data from the new field object.