HOWTO: Creating a Custom Recipient Programmatically

ID: Q165931

The information in this article applies to:

SUMMARY

Creating a custom recipient programmatically requires the use of the DAPI functions. Using DAPIStart to create a DAPI session is the first step to making this work. Once the session is created, use DAPIWrite to send the custom recipient information to the Exchange Server.

MORE INFORMATION

This example is not a complete program. It assumes that MAPIInitialize has been called. The additional include files required to make this code work are Dapi.h and Edk.h.

1. Populate the DAPIParms structure. This structure must be created in 

   order to call DAPIStart:

      sDAPIParms.pszDSAName = "EXCHANGE_SERVER";
      sDAPIParms.pszBasePoint = NULL;
      sDAPIParms.pszContainer = NULL;
      sDAPIParms.pszNTDomain = "EXCHANGE_SERVER";
      sDAPIParms.dwFlags = DAPI_MODIFY_REPLACE_PROPERTIES;
      sDAPIParms.dwDAPISignature = DAPI_SIGNATURE;
2. Create a DAPI session using the DAPIStart function. Check the value 
   returned to make sure you have a DAPI session created:

      pDAPIEvent = DAPIStart(
                &hDAPISession,
                &sDAPIParms);

      if (pDAPIEvent != NULL)
         goto cleanup;
3. Allocate memory for the DAPI_ENTRY structure that will store the custom 
   recipient information. Check for the success of the memory allocation
   and clear the memory:

      hr = MAPIAllocateBuffer(sizeof(DAPI_ENTRY), (LPVOID*) &pValues);
      if (FAILED(hr))
         {
         goto cleanup;
         }
      ZeroMemory(pValues, sizeof(DAPI_ENTRY));
4. Allocate memory for the DAPI_ENTRY structure that will store the header 
   information for the recipient properties. Check for the success of the
   memory allocation and clear the memory:

      hr = MAPIAllocateBuffer(sizeof(DAPI_ENTRY), (LPVOID*) &pAttributes);
      if (FAILED(hr))
        {
        goto cleanup;
        }
      ZeroMemory(pAttributes, sizeof(DAPI_ENTRY));
5. Set the attributes to set for the custom recipient. The memory is 
   cleared and then the values are set:

      pAttributes->unAttributes = 1;
      pAttributes->ulEvalTag = TEXT_LINE;

      hr = MAPIAllocateMore(
        cDAPIArrayElements * sizeof(ATT_VALUE),
        pAttributes,
        (LPVOID*) &pAttributes->rgEntryValues);
      if (FAILED(hr))
         {
         goto cleanup;
         }
      ZeroMemory(
        pAttributes->rgEntryValues,
        cDAPIArrayElements * sizeof(ATT_VALUE));
      pAttributes->rgEntryValues[0].DapiType = DAPI_TEXT;
      pAttributes->rgEntryValues[0].Value.pszValue = "Obj-Class,
         E-mail address,Directory Name,Alias Name,obj-container,
         Display name,First Name,Last Name";
      pAttributes->rgEntryValues[0].size =
         strlen(pAttributes->rgEntryValues[0].Value.pszValue);
6. Fill the DAPI_ENTRY structure with the values to create the custom 
   recipient:

      pValues->unAttributes = 1;
      pValues->ulEvalTag = TEXT_LINE;

      hr = MAPIAllocateMore(
           cDAPIArrayElements * sizeof(ATT_VALUE),
           pValues,
           (LPVOID*) &pValues->rgEntryValues);
      if (FAILED(hr))
        {
        goto cleanup;
        }
      ZeroMemory(
           pValues->rgEntryValues,
           cDAPIArrayElements * sizeof(ATT_VALUE));
      pValues->rgEntryValues[0].DapiType = DAPI_TEXT;
      pValues->rgEntryValues[0].Value.pszValue =
          "Remote,SMTP:USER1@cate.com,usertest,usertest,Recipients,
          User Test,User,Test";
      pValues->rgEntryValues[0].size =
          strlen(pValues->rgEntryValues[0].Value.pszValue);
7. Write the data to the Exchange directory. To determine if the write 
   was successful, check the value of DAPIEvent and the USN:

      ulNewUSN = 0;
      pDAPIEvent = DAPIWrite(
                   hDAPISession,
                   dwWriteFlags,
                   pAttributes,
                   pValues,
                   &ulNewUSN,
                   NULL,
                   NULL);
8. Release the memory allocated to the DAPI_ENTRY structures: 

      MAPIFREEBUFFER(pValues);
      MAPIFREEBUFFER(pAttributes);
9. End the DAPI session: 

      DAPIEnd(hDAPISession);
NOTE: This example can run from a machine other than an Exchange Server. In order to accomplish this, the following DLLs must be present on the machine: Dapi.dll, Exchmem.dll, and Libxds.dll. If errors referring to the $first name$ occur when trying to run the code, install the Exchange Administrator on the machine and the errors should disappear. 

Keywords          : kbcode kbAPI kbEDK kbMsg 
Version           : 1.0
Platform          : WINDOWS
Issue type        : kbhowto

Last Reviewed: July 11, 1998