Callout contexts

From Messaging Server Technical Reference Wiki
Jump to: navigation, search

When using the MTA API in a reentrant way a callout routine cannot depend on static variables. While threat-specific data provides one means of passing such data to a callout routine, the overhead is fairly high and also assumes that an API context is bound to a particular thread, which may not be the case.

The 1024 octet length limit on mapping probes can be an issue in some cases: The MTA may have information useful to some callout routines that exceeds this limit, consists of binary data, or both.

MS introduces a new context passing mechanism that addresses both of these issues. A callout routine can now call the MTA API routine declared in apidef.h:

    result = PMDFgetCalloutContext(PMDF_nq *context, int index,
                                   void **data, int64_t *length);

Here context is the context passed to the callout routine and index is the index of the context to fetch. On successful completion data will be filled in with the address of the context data and length will be the length.

At present only two indices are defined:

Used to obtain user context data provided by the PMDFsetCalloutContext routine.
Used to obtain mapping-specific information that won't fit or is otherwise unsuitable for inclusion in the mapping probe itself.

PMDF_USER_CALLOUT_CONTEXT is reserved for applications making use of the MTA API. In order to set the context, after initializing an enqueue context applications can call the routine:

    result = PMDFsetCalloutContext(PMDF_nq **context, int index,
                                   void *data, int64_t length);

with index set to PMDF_USER_CALLOUT_CONTEXT.

The PMDF_LONGSTRING_CALLOUT_CONTEXT is currently reserved for use by the MTA to pass additional information to various mappings. Most notably, the current list of conversion tags is passed to various mappings using this mechanism so that include_conversiontag doesn't need to be set for the callout to access conersion tag information.