How to Work with DAPI_EVENT Structure

Perhaps you have noticed in the samples described previously that a few DAPI functions such as DAPIStart and DAPIRead return pointer to a DAPI_EVENT structure. If the function is successful, it returns NULL pointer, otherwise a DAPI_EVENT structure is allocated and its pointer is returned to the caller. This structure contains error information. This topic describes how to deal with it.

First of all, a few words of caution. If the structure is allocated you must eventually free it with DAPIFreeMemory call - that's what Microsoft recommends. My two illustrative samples in previous subsections don't do that, but production code perhaps should. I use the opportunity to emphasize here again, that the samples in this work are "illustrative". They show how you could accomplish certain tasks, but they are obviously not rock-solid.

Here is the definition of DAPI_EVENT structure:

typedef struct _DAPI_EVENT
{
    DWORD    dwDAPIError;    // Message ID for event log
    LPSTR    rgpszSubst[DAPI_MAX_SUBST];    // Event message substitution array
    UINT    unSubst;    // Number of substitution strings
    LPSTR    pszAttribute;    // Name of attribute specifically affected
    LPSTR    pszHoldLine;    // Pointer to buffer containing copy of current import line
    HINSTANCE    hinstDAPI;    // Instance of DAPI DLL
    struct _DAPI_EVENT *pNextEvent;    // Pointer to next event
} DAPI_EVENT, * PDAPI_EVENT;

The most important component of this structure is its first element - message identifier. This number identifies an error message string. The last element of the structure is also very useful. It hosts a pointer to the next related event. A function returning DAPI_EVENT may in fact report "many" errors. Suppose you want to modify a directory object with the DAPIWrite function and supply invalid arguments. For example, you may supply "read-only" attributes, and omit a required one. In such case the DAPI_EVENT will individually report each error (quite a nice feature!) in a list of related DAPI_EVENTs. You may easily traverse this list and view it during debugging in the Watch window.

Our major concern here is how to deal with errors. How can we obtain text description of an error? There are a few ways of doing this.

Examining DAPIMSG.H file

The simplest thing to do is to open the DAPIMSG.H file, find message ID there, and look at text description of an error. For example, for dwDAPIError being equal to 0xC0000081 you should be able to find the following fragment in this file:

//
// MessageId: DAPI_E_BAD_HANDLE
//
// MessageText:
//
// A bad DAPI handle supplied to call.
//
#define DAPI_E_BAD_HANDLE 0xC0000081L

Take a look at text description of the error preceding #define statement. Obviously, a bad handle was used with the call. This is exactly what happened with me when I mistakenly supplied address of DAPI handle instead of real handle to the DAPIRead function.

DAPIMSG.H file may be found in the Include directory of your Platform SDK.

Using the FormatMessage Function

Second way of dealing with DAPI_EVENT error codes is to use the FormatMessage Win32 function. In fact, it is a very useful general-purpose function. For example, here is the sample showing how you can display Win32 error codes, obtained via the GetLastError():

LPVOID lpMsgBuf;
::FormatMessage(
    FORMAT_MESSAGE_ALLOCATE_BUFFER |
    FORMAT_MESSAGE_FROM_SYSTEM |
    FORMAT_MESSAGE_IGNORE_INSERTS,
    NULL,
    GetLastError(),
    MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), // Default language
    (LPTSTR) &lpMsgBuf,
    0,
    NULL
);
// Display the string.
MessageBox( NULL, (char *) lpMsgBuf, "Error", MB_OK | MB_ICONINFORMATION );
// Free the buffer.
LocalFree( lpMsgBuf );

The above sample may be found in Dir/FormatMessage directory of my collection of sample code.

In our particular case of DAPI errors, we need to use slightly different parameters. First of all, we need to change FORMAT_MESSAGE_FROM_SYSTEM flag to FORMAT_MESSAGE_FROM_HMODULE, pass DAPI.DLL handle in second parameter, and error ID in the third. The following sample demonstrates how you can use it. Notice that I call DAPIRead without first calling DAPIStart, this causes it to fail with invalid handle error. Notice the use of DAPIFreeMemory for DAPI_EVENT structure as well. The sample below is located in Dir/FormatMessageDAPI subdirectory.

#include <afxwin.h>
#include <dapi.h>

int main( void )
{
PDAPI_EVENT pDAPIEvent = NULL;
DAPI_HANDLE hDAPISession = NULL;

    DAPI_ENTRY * pdeValues = NULL;
    DAPI_ENTRY * pdeAttributes = NULL;
    pDAPIEvent = ::DAPIRead( hDAPISession,
        DAPI_READ_ALL_ATTRIBUTES,
        "/o=Rydex Industries Corporation/ou=DEV/cn=Configuration/cn=Addressing/cn=Address-Types/cn=EDK:i386",
        NULL,
        &pdeValues,
        &pdeAttributes );

if ( pDAPIEvent ) {

        LPVOID lpMsgBuf;
        ::FormatMessage( FORMAT_MESSAGE_ALLOCATE_BUFFER |
            FORMAT_MESSAGE_FROM_HMODULE |
            FORMAT_MESSAGE_IGNORE_INSERTS,
            pDAPIEvent->hinstDAPI,
            pDAPIEvent->dwDAPIError,
            MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), // Default language
            (LPTSTR) &lpMsgBuf,
            0,
            NULL );

        // Display the string.
        ::MessageBox( NULL, (char *) lpMsgBuf, "Error", MB_OK | MB_ICONINFORMATION );
        // Free the buffer.
        ::LocalFree( lpMsgBuf );

        ::DAPIFreeMemory( pDAPIEvent );
        return ( -1 );
    }

return ( 0 );
}

For many application working co-operatively with MS Exchange server it would be more appropriate to log messages to Windows NT event log, rather than displaying them on the desktop. Once you have collected the message with the FormatMessage function as described above, you can log it into Event log by either using standard Win32 event logging techniques or a collection of functions in Exchange Development Kit (such as EventLogMsg).

[ Contents | Home ]