Microsoft KB Archive/194954

From BetaArchive Wiki
Knowledge Base


How To Create a Mailbox Using DAPI

Article ID: 194954

Article Last Modified on 6/29/2004



APPLIES TO

  • Microsoft Exchange Development Kit 5.5
  • Microsoft Exchange Server 2003 Software Development Kit



This article was previously published under Q194954

SUMMARY

Creating a mailbox programmatically is something that can be required in large organizations where the administrator wants to create the NT account and the mailbox at the same time without going into the User Manager. This article addresses creating an Exchange mailbox programmatically. It accomplishes this using DAPI (Directory API).

MORE INFORMATION

There are five attributes required to set up an Exchange mailbox; they are Obj-Class, Home-Server, Assoc-NT-Account, Display Name, and Common-Name. The Obj-Class for a mailbox is Mailbox and will be the same for all of the mailboxes you add. The other attributes will change for each mailbox you create. The code shown below demonstrates how to create the mailbox using DAPI.

The following additional libraries are required to compile this example:

  • mapi32.lib
  • dapi.lib
  • advapi32.lib

NOTE: In order to run this code, the executable file must be on an Exchange Server or on a Windows NT Server that is configured to support DAPI.

For additional information on configuring a Windows NT Server to support DAPI, please see the following article(s) in the Microsoft Knowledge Base:

169551 INFO: Items Required to Use DAPI


Before building and running this code, be sure to change the items indicated by "TODO" in the code comments.

    #include <windows.h>
    #include <stdio.h>
    #include <string.h>
    #include <lmcons.h>
    #include <dapi.h>

    void CreateMB(DAPI_HANDLE hDAPISession, char* pszComputerName,
                  char* pszAlias, char* pszNTAcct);

    void ReportDAPIEvent(DAPI_EVENT* pDAPIEvent);

    void main(int argc, char* argv[])
    {
       DAPI_HANDLE hDAPISession;
       DAPI_EVENT* pDAPIEvent = NULL;
       DAPI_PARMS DAPIParms = {0};
       char szAccount[UNLEN + MAX_COMPUTERNAME_LENGTH + 2];
       DWORD dwAccountLength = UNLEN + MAX_COMPUTERNAME_LENGTH + 1;

       if (4 > argc) {
         printf("\nDAPITest Domain ExchangeServerName DN OwnerNTAcct");
         printf("\n      DN = ");
         printf("\"/O=org/OU=site/CN=RECIPIENTS/CN=AliasName\"");
         return;
       }

       strcpy(szAccount,argv[1]);
       strcat(szAccount,"\\");
       strcat(szAccount,argv[4]);

       printf("\nExchange Server: %s", argv[2]);
       printf("\nDN \"%s\"\nNTAcct: %s", argv[3], szAccount);

       // Start DAPI for this session
       // Initialize the DAPI Parms structure and
       // the DAPI operation session
       DAPIParms.dwDAPISignature = DAPI_SIGNATURE;
       DAPIParms.dwFlags = DAPI_EVENT_ALL |
               DAPI_MODIFY_REPLACE_PROPERTIES | DAPI_RESTRICT_ACCESS ;
       DAPIParms.pszDSAName = argv[2];
       DAPIParms.pszBasePoint = NULL;
       DAPIParms.pszContainer = NULL;
       DAPIParms.pszNTDomain = argv[1];
       DAPIParms.pszCreateTemplate = NULL;
       DAPIParms.pAttributes = NULL;

       pDAPIEvent = DAPIStart(&hDAPISession, &DAPIParms);

       if(pDAPIEvent)
       {
         // ReportDAPIEvent(pDAPIEvent);
         printf("\nDAPIStart() ERROR %08x - check app eventlog",
                pDAPIEvent->dwDAPIError);
         ReportDAPIEvent(pDAPIEvent);
         //DAPIFreeMemory(pDAPIEvent);
       }
       else
         printf("\nDAPIStart() was successful");

       // argv[2] is the server; argv[3] is the DN
       CreateMB(hDAPISession, argv[2], argv[3], szAccount);

       DAPIEnd(&hDAPISession);

       printf("\nEND PROGRAM");
    }

    void CreateMB(DAPI_HANDLE hDAPISession, char* pszComputerName,
                  char* pszAlias, char* pszNTAcct)
    {
      DAPI_EVENT* pDAPIEvent = NULL;
      DAPI_ENTRY Attributes;
      DAPI_ENTRY Values;
      ATT_VALUE AttName[5];
      ATT_VALUE AttValue[5];

      printf("\nIN CreateMB()");

      //set up the account information to create
      AttName[0].DapiType = DAPI_STRING8;
      AttName[0].Value.pszValue = "Obj-Class";
      AttName[0].size = strlen(AttName[0].Value.pszValue);
      AttName[0].pNextValue = NULL;

      AttName[1].DapiType = DAPI_STRING8;
      AttName[1].Value.pszValue = "Common-Name";
      AttName[1].size = strlen(AttName[1].Value.pszValue);
      AttName[1].pNextValue = NULL;

      AttName[2].DapiType = DAPI_STRING8;
      AttName[2].Value.pszValue = "Home-Server";
      AttName[2].size = strlen(AttName[2].Value.pszValue);
      AttName[2].pNextValue = NULL;

      AttName[3].DapiType = DAPI_STRING8;
      AttName[3].Value.pszValue = "Assoc-NT-Account";
      AttName[3].size = strlen(AttName[3].Value.pszValue);
      AttName[3].pNextValue = NULL;

      AttName[4].DapiType = DAPI_STRING8;
      AttName[4].Value.pszValue = "Display Name";
      AttName[4].size = strlen(AttName[4].Value.pszValue);
      AttName[4].pNextValue = NULL;

      Attributes.unAttributes = 5;                  //# of attributes
      Attributes.ulEvalTag = TEXT_VALUE_ARRAY;      //Value Type
      Attributes.rgEntryValues = (ATT_VALUE*)&AttName;

      AttValue[0].DapiType = DAPI_STRING8;
      AttValue[0].Value.pszValue = "Mailbox";
      AttValue[0].size = strlen(AttValue[0].Value.pszValue);
      AttValue[0].pNextValue = NULL;

      printf("\nCommon-Name: \"%s\"",pszAlias);

      AttValue[1].DapiType = DAPI_STRING8;
      AttValue[1].Value.pszValue = pszAlias;
      AttValue[1].size = strlen(AttValue[1].Value.pszValue);
      AttValue[1].pNextValue = NULL;

      printf("\nHome Server: %s", pszComputerName);

      AttValue[2].DapiType = DAPI_STRING8;
      AttValue[2].Value.pszValue = pszComputerName;
      AttValue[2].size = strlen(AttValue[2].Value.pszValue);
      AttValue[2].pNextValue = NULL;

      printf("\nAccount: %s",pszNTAcct);

      AttValue[3].DapiType = DAPI_STRING8;
      AttValue[3].Value.pszValue = pszNTAcct;
      AttValue[3].size = strlen(AttValue[3].Value.pszValue);
      AttValue[3].pNextValue = NULL;

      // TODO: Change "Johnny Quest" to be the text you want for
      // the display name on the mailbox.
      AttValue[4].DapiType = DAPI_STRING8;
      AttValue[4].Value.pszValue = "Jonny Quest";
      AttValue[4].size = strlen(AttValue[4].Value.pszValue);
      AttValue[4].pNextValue = NULL;

      Values.unAttributes = 5;                        //# of attributes
      Values.ulEvalTag = TEXT_VALUE_ARRAY;            //Value Type
      Values.rgEntryValues = (ATT_VALUE*)&AttValue;

      // Create the new Exchange mailbox
      pDAPIEvent = DAPIWrite(hDAPISession, DAPI_WRITE_CREATE,
                             &Attributes, &Values, NULL,
                             NULL, NULL);

      if(pDAPIEvent)
      {
        // create FAILED
        printf("\nDAPIWrite ERROR %08x check app eventlog",
               pDAPIEvent->dwDAPIError);
        ReportDAPIEvent(pDAPIEvent);
        //       DAPIFreeMemory(pDAPIEvent);
      }
      else
        printf("\nDAPIWrite() was successful");

    }

    void ReportDAPIEvent(DAPI_EVENT* pDAPIEvent)
    {
      HANDLE hDAPIEventSource =
           RegisterEventSource(NULL, TEXT("MSExchangeDSImp"));

      ReportEvent(
         hDAPIEventSource, (WORD)EVENTLOG_ERROR_TYPE, 0,
         pDAPIEvent->dwDAPIError, NULL, (WORD)pDAPIEvent->unSubst,
         0, (LPCSTR *)pDAPIEvent->rgpszSubst, NULL);

      DAPIFreeMemory(pDAPIEvent);

      DeregisterEventSource(hDAPIEventSource);
    }
                

Keywords: kbhowto kbmsg KB194954