CMC_extension

A CMC_extension structure contains a CMC data extension for use by the CMC API functions and data structures. A CMC data extension adds parameters to functions or members to data structures.

Quick Info

typedef struct { 
     CMC_uint32 item_code; 
     CMC_uint32 item_data; 
     CMC_buffer item_reference; 
     CMC_flags extension_flags; 
} CMC_extension; 
 

Members

item_code

Code that uniquely identifies an extension to a function or data structure. The item_code member is the mechanism for specifying the extension to be invoked. The client application puts the extension code in this member before calling CMC functions that use extensions. The possible extensions are:

CMC_X_COM_ATTACH_CHARPOS	CMC_X_COM_CAN_SEND_RECIP
CMC_X_COM_CONFIG_DATA	CMC_X_COM_PRIORITY
CMC_X_COM_RECIP_ID	CMC_X_COM_SAVE_MESSAGE
CMC_X_COM_SENT_MESSAGE	CMC_X_COM_SUPPORT_EXT
CMC_X_COM_TIME_RECEIVED	CMC_X_MS_ADDRESS_UI
CMC_X_MS_ATTACH_DATA	CMC_X_MS_FUNCTION_FLAGS
CMC_X_MS_MESSAGE_DATA	CMC_X_MS_SESSION_FLAGS

These extensions are identified by the extension identifiers CMC_XS_COM and CMC_XS_MS. For definitions of these extensions, see Data Extensions.

item_data

Item data for the extension. Depending on the value of item_code, the item_data member might contain the length of the item value, the item value itself, or other information about the item. The specification of the extension describes the interpretation of this member.

item_reference

The item reference for the extension. This value is a pointer to the storage location of the item value. It is NULL if there is no related item storage. The specification of the extension describes the interpretation of this member.

extension_flags

Bitmask of extension flags. The following flags can be set:

CMC_EXT_LAST_ELEMENT

The last structure in an array of CMC_extension structures. The structure with this flag set must be at the end of the array. If this flag is set to zero for any structure, that structure is not the last array element.

CMC_EXT_OUTPUT

For an output extension, the extension structure contains a pointer to implementation-allocated memory that the client application must release with the cmc_free function. If this flag is set to zero, the implementation has not allocated memory for the extension that the application needs to free. This flag is always set to zero for structure extensions.

CMC_EXT_REQUIRED

An error value is returned if this extension cannot be supported. If this flag is set to zero, it enables the CMC implementation to provide any level of support, including no support, for the extension.

Remarks

Extensions are used to add functionality to the CMC API. For example, a client application can implement the cmc_act_on function to allow saving a partially completed message in the receive folder (the Inbox) for later updating and sending. To pass the structure defining this partially completed message to CMC and receive back the resulting message reference, the client application can use the CMC_X_COM_SAVE_MESSAGE extension.

An extension can be either an input extension or an output extension; that is, it can be passed either as input from a client application to CMC or as output from CMC to a client application. Whether the information contained in an extension is input or output is implied by the semantics of the particular extension in question and by the presence or absence of CMC_EXT_OUTPUT in the extension's extension_flags member after a call to a CMC function. For input extensions, the client application in question allocates memory for the extension structure and any other structures associated with the extension. For output extensions, storage for the extension result, if necessary, is allocated by a CMC function.

For output extensions, a client application must free storage allocated by CMC with calls to the cmc_free function. For each CMC_extension structure in the array, the caller must call cmc_free for the pointer in the item_reference member of the structure.

CMC does not require explicit release of a data extension structure, because CMC releases such structures along with the structures that contain them. For example, CMC implicitly releases the message extension array created by the cmc_read function when calling cmc_free for the enclosing CMC_message structure.

See Also

cmc_act_on, cmc_free, CMC_message, cmc_read