Global Address List

Exchange Server Global Address List (GAL) is a MAPI address book container that holds recipients for a whole organization. It is typically available to all messaging clients in this organization. Clients usually can't modify GAL. It is important to know how to work with GAL.

EDK provides a useful function to locate Global Address List. It is called HrFindExchangeGlobalAddressList:

HRESULT HrFindExchangeGlobalAddressList(LPADRBOOK lpAdrBook,
ULONG * lpcbeid,
LPENTRYID * lppeid);

The first parameter points to an IAddrBook interface, which contains GAL (as explained below), lpcbeid points to the number of bytes in the resulting entry identifier, and lppeid points to the pointer where entry identifier is actually stored. The function allocates memory for entry ID. You need to release it.

The following algorithm may be used to locate and open GAL:

Start a MAPI session.
Open the address book by using IMAPISession::OpenAddressBook.
Locate GAL by calling HrFindExchangeGlobalAddressList and using the LPADRBOOK pointer from previous step.
Open GAL by using the IMAPISession::OpenEntry method.

Here is a little code example (GAL/OpenGAL) showing how you can use it:

#include <afxwin.h>
#include <mapix.h>
#include <addrlkup.h>

int main()
{
HRESULT hRes;
LPMAPISESSION pSession = NULL;

    // Initialize MAPI
    hRes = MAPIInitialize(NULL);
    if (FAILED(hRes)) throw -1;

    // Obtain MAPI session
    hRes = MAPILogonEx(0,    // Handle to parent window
          "MS Exchange Settings", // Profile name
          NULL,   // Password
          MAPI_NEW_SESSION |
          MAPI_EXTENDED |
          MAPI_LOGON_UI, // Logon flags
          &pSession); // Resulting MAPI session
    if (FAILED(hRes)) throw -1;

    // Open the address book
    LPADRBOOK pAdrBook = NULL;
    hRes = pSession->OpenAddressBook(0, 0, MAPI_ACCESS_MODIFY, &pAdrBook);
    if (FAILED(hRes)) throw -1;

    // Locate GAL
    ULONG cbGalEid = 0;   // Count of bytes in GAL entry ID
    LPENTRYID pGalEid = NULL; // GAL entry ID
    hRes = HrFindExchangeGlobalAddressList(pAdrBook, &cbGalEid, &pGalEid);
    if (FAILED(hRes)) throw -1;

    // Open GAL
    ULONG ulObjType = 0;
    LPUNKNOWN pGal = NULL;
    hRes = pSession->OpenEntry(cbGalEid, // Count of bytes in entry ID
        pGalEid, // Entry ID
        NULL,   // Pointer to IID we want
        MAPI_MODIFY, // Access flags
        &ulObjType, // Object type
        &pGal);   // Resulting pointer
    if (FAILED(hRes)) throw -1;

    // Display success string.
    MessageBox(NULL, "Successfully opened GAL. Now exiting...", "Success",
        MB_OK | MB_ICONINFORMATION);

    // Clean up and exit
    if (pGal)
      pGal->Release();
    if (pGalEid)
      MAPIFreeBuffer(pGalEid);
    if (pAdrBook)
      pAdrBook->Release();
    if (pSession)
      pSession->Release();

MAPIUninitialize();
return 0;
}

This code is straightforward. I open Exchange GAL and then clean up. Next section describes something more interesting you can do with GAL.

[ Contents | Home ]