The Unmanaged API

The unmanaged API provides a set of DLL-resident functions that are called in the same way as the native Windows API.  During development you may want to add a build event to copy the appropriate DXL-MSG unmanaged DLL to your executable's directory.  For working in an environment with a 32-bit edition of Outlook, you need "DXL-MSG_u32.dll".  For use with a 64-bit Outlook, you need "DXL-MSG_u64.dll".  The associated import libraries are "DXL-MSG_u32.lib" and "DXL-MSG_u64.lib". Note that the DLL name was changed with release 1.60 of the product.  In release 1.83 we subtly changed some of the parameter types for the API functions, altering all ULONGs to UINT32s; these changes should require no recompilation by customers.

All API functions return 0 on success and a non-zero error code on failure.  Prototypes for the functions along with error codes are defined in the "DXL-MSG API.h" header file.  Note that all strings are passed in Unicode.

We are happy to provide sample C/C++ code for using this API.  Just ask.

The API comprises the following 5 functions described with C-language prototypes:

int __stdcall DXL_MSG_Initialize(

 UINT32 u32Options)   // [in] initialization options (DXL_MAPI_INIT_xxx)

This function must be called once and once only before any other function in the API.  We suggest calling it from the main thread of your application as part of its initialization sequence.  (It must not be called from a DllMain.)  The function performs several preparatory operations such as loading the MAPI subsystem.  The single argument is used for options, as listed below.  If no options are pertinent, please pass 0.

Currently the only initialization option is:

DXL_MAPI_INIT_SERVICE     notifies the API that the application is running as a Windows Service

int __stdcall DXL_MSG_CreateSession(

 UINT32 u32MapiInitFlags,     // [in] flags to be passed to MAPIInitialize()

 UINT32 u32ConverterOptions, // [in] converter options

 HANDLE *lphSession)         // [out] session handle

Call this to create a DXL-MSG converter session.  The first argument is used to provide flags that are passed on to MAPI's MAPIInitialize() function.  Please view Microsoft's documentation (for example here)  for this function to determine what flags, if any, you may need to use.  The only flag that DXL-MSG users are likely  to need is MAPI_NO_COINIT.  (Do not worry about MAPI_NT_SERVICE; if you called DXL_MSG_Initialize with the DXL_MAPI_INIT_SERVICE flag then the API will automatically set this when appropriate).

The second argument is reserved for session options, none of which are currently defined:  Please pass 0.

The last parameter outputs a session handle that you then pass in to other API functions.

It is fine to create multiple converter sessions however each session must be created and used exclusively by a single thread.  Do not create a new session for each conversion; please create a pool of sessions (up to maybe 8) and let each run multiple conversions.

int __stdcall DXL_MSG_DeleteSession(

 HANDLE hSession)                        // [in] session handle

Call this to delete and clean up each DXL-MSG session.

int __stdcall DXL_MSG_EstablishLogger(

 LPCWSTR lpwszLogFilePath,   // [in] full path for log file

 UINT32 u32LoggerOptions)   // [in] options for logging (see list below)

Each session records its activity and any errors it encounters to a log.  By default, all sessions share a single log file named "DXL-MSG.log" and placed in the current Windows directory.  You can change the path of the log file by calling this function.

Logger options are:

int __stdcall DXL_MSG_Convert(

 HANDLE hSession,             // [in] session handle

 LPCWSTR lpwszDxlFilePath,     // [in] path of DXL file

 LPCWSTR lpwszMsgFilePath,     // [in] path for MSG file (or NULL)

 LPCWSTR lpwszEmlFilePath,     // [in] path for EML file (or NULL)

 UINT32 u32ConversionOptions) // [in] DXL-MAPI conversion options

This is the function that does the real work.  Each call performs the conversion of one DXL document to MSG and/or EML.  The first argument carries the handle of the DXL-MSG session.  The second is the path of the DXL file.  The third is the path of or for the MSG file; it can be NULL if you need just an EML.  The fourth argument is the path for an EML file if you want one and NULL otherwise.  If an MSG or EML with the name already exists, it is overwritten.  The last argument is for conversion options, listed below.  Pass 0 if no options are required.

 DXL_MAPI_DDB64        doubly decode base64-encoded attachments that appear to be doubly encoded  (See note here)

int __stdcall DXL_MSG_GetVersion(

 UINT32 *lpuMajorVersion,   // [out] the Major Version number of the DXL-MSG core

 UINT32 *lpulMinorVersion)   // [out] the Minor Version number of the DXL-MSG core

This function allows you to retrieve the version number of the core DXL-MSG converter.