Using CMC Data Extensions

The data structures and functions defined by CMC can be expanded through the use of data extensions to add members to data structures and parameters to function calls.

Data extensions have two roles in CMC messaging. First, they are a mechanism to provide features not common across all messaging systems. Second, they enable extension of CMC in the future while also minimizing backward-compatibility issues. Use caution when using data extensions to take advantage of features specific to a messaging system. Reliance on specific features limits the portability of your client across messaging systems; also, such features might not be preserved properly when a message passes through multiple gateways in a mixed messaging network. If you do use data extensions, your code should test for the presence of the extensions and gracefully handle the absence of the extensions. Doing so will make your client portable to other CMC implementations.

Data extensions are grouped into extension sets. Extension sets have unique identifiers (defined constants) assigned to them that represent the set as a whole and that represent the individual extensions in the set. These identifiers are assigned by the X.400 API Association, which guarantees that there are no conflicts between identifiers in officially recognized extension sets. There are also provisions for allowing a CMC implementation to define its own data extensions without obtaining identifiers from the X.400 API Association. If this is done, clients that use those extensions might not be portable to other CMC implementations.

The CMC common extension set contains the function and data extensions that are common to most messaging systems but are not in the CMC base specification. The common extension set is identified by the CMC_XS_COM constant. Individual extensions in the common extension set are identified by constants with names that start with CMC_X_COM. For a full list of common extensions, see Data Extensions.

A generic data structure, CMC_extension, is the base from which these extensions are created. A CMC_extension structure consists of an item_code member identifying the extension, an item_data member containing the length of the extension data or the data itself, an item_reference member pointing to the location where the extension value is stored or that is NULL if there is no related item storage, and an extension_flags member containing a bitmask of extension flags. The item_code member identifies a particular extension and determines the meanings of values in the other members.

Extensions that are additional parameters to a function call can be either input or output parameters. That is, an extension can be passed either as an input parameter from your client application to CMC or as an output parameter from CMC to your client. If an extension is an input parameter, allocate memory for the extension structure and any other structures associated with the extension. If an extension is an output parameter, CMC allocates the memory for the extension result, if necessary, and you must free the allocated memory with a call to the cmc_free function.

To use a data extension

1. Create a CMC_extension structure and fill in the members according to the extension you want to use.
2. Pass a pointer to that structure in a call to a CMC function which can use it. The CMC function will use the information in the extension structure to enable additional functionality beyond the functionality defined for that CMC function in the X.400 API Association's CMC specification. The exact nature of the additional functionality is described in the documentation for the extension set you are using, which should be obtained from the extension set vendor.
3. Retrieve any return values from the members of the CMC_extension structure if the CMC function uses the structure to pass values back to your client.