Yet another IExchangeManageStore incarnation

Article
03/29/2006

Yep, that's right: IExchangeManageStore5 is upon us. And this is the coolest one yet!

I'm intrigued...what does it do?

The cool new feature in this interface is the ability to retrieve a mailbox table (or public folder table) that contains only mailboxes in a particular information store. Prior versions of the IExchangeManageStore interfaces would always return a table that contained all mailboxes (or public folders) across all stores on a particular server.

Big deal...I can query the Active Directory to find out what store a mailbox is in. Why should I care about this new interface?

Well, if avoiding the AD lookup isn't enough, there's one scenario where an AD lookup won't help you: the Recovery Storage Group. We recently documented how to connect to mailboxes in the RSG with MAPI. The kicker here is that when you have an RSG mounted, and you call one of the earlier GetMailboxTable variations, you would get two entries for mailboxes that existed in both the real storage group and the recovery storage group, with no way to tell them apart! (Yes, you can detect there are two identical entries and then assume that means the mailbox exists in the RSG, but all that table processing could get tedious)

Ok...I'm sold. How does it work?

The IExchangeManageStore5 interface includes 2 new functions.

IExchangeManageStore5::GetMailboxTableEx

The GetMailboxTableEx method obtains information about all of the mailboxes on a server in a particular store.

 HRESULT GetMailboxTableEx(
  LPSTR lpszServerName,   
  LPGUID lpguidMdb,    
  LPMAPITABLE FAR * lppTable,  
  ULONG ulFlags,
  UINT uOffset
);

Parameters

lpszServerName
   Input parameter. Points to a string that contains the distinguished name (DN) of the server.
lpguidMdb
   Input parameter. Points to a GUID that contains the value of the objectGUID attribute of the information store.
lppTable
   Output parameter. Points to a MAPI IMAPITable interface containing the information about all of the mailboxes on the server specified in lpszServerName.
ulFlags
   Input parameter. A defined value that specifies whether the server name is Unicode:
      MAPI_UNICODE
      The server name is in Unicode format.
      0
      (Zero) The server name is in ASCII format.
uOffset
   Input parameter. Indicates the offset to start the table from. This is used for stores that have over 64K mailboxes in them.

IExchangeManageStore5::GetPublicFolderTableEx

The GetPublicFolderTableEx method obtains information about all of the public folders on a server in a particular store.

 HRESULT GetPublicFolderTableEx(
  LPSTR lpszServerName,   
  LPGUID lpguidMdb,    
  LPMAPITABLE FAR * lppTable,  
  ULONG ulFlags,
  UINT uOffset
);

Parameters

lpszServerName
   Input parameter. Points to a string that contains the distinguished name (DN) of the server.
lpguidMdb
   Input parameter. Points to a GUID that contains the value of the objectGUID attribute of the information store.
lppTable
   Output parameter. Points to a MAPI IMAPITable interface containing the information about all of the public folders on the server specified in lpszServerName.
ulFlags
   Input parameter. A defined value that specifies whether the server name is Unicode:
      MAPI_UNICODE
      The server name is in Unicode format.
      0
      (Zero) The server name is in ASCII format.
uOffset
   Input parameter. Indicates the offset to start the table from. This is used for stores that have over 64K public folders in them.

Sweet! Where do I get this new interface from?

It's only available in Exchange 2003's version of EMSMDB32.DLL. You'll need Exchange 2003 Service Pack 2 installed, and the hotfix documented in Knowledge Base article 908072. (As of this posting, this article is not yet available on https://support.microsoft.com. You can still contact MS support and request the hotfix by referencing the article number though)

Once you have the hotfix, you'll need the interface definition and IID. These aren't in the headers yet, so you'll need to add them yourself.

In edkmdb.h, add:

 /*------------------------------------------------------------------------
 *
 *    "IExchangeManageStore5" Interface Declaration
 *
 *   Used for store management functions.
 *
 *-----------------------------------------------------------------------*/

#define EXCHANGE_IEXCHANGEMANAGESTORE5_METHODS(IPURE)                  \
   MAPIMETHOD(GetMailboxTableEx)           \
       (THIS_  LPSTR       lpszServerName,   \
         LPGUID      lpguidMdb,        \
         LPMAPITABLE FAR *   lppTable,            \
          ULONG       ulFlags,             \
          UINT        uOffset) IPURE; \
   MAPIMETHOD(GetPublicFolderTableEx)          \
       (THIS_  LPSTR       lpszServerName, \
           LPGUID      lpguidMdb,  \
           LPMAPITABLE FAR *   lppTable,       \
           ULONG       ulFlags,        \
           UINT        uOffset) IPURE; \

#undef      INTERFACE
#define        INTERFACE  IExchangeManageStore5
DECLARE_MAPI_INTERFACE_(IExchangeManageStore5, IUnknown)
{
  MAPI_IUNKNOWN_METHODS(PURE)
 EXCHANGE_IEXCHANGEMANAGESTORE_METHODS(PURE)
 EXCHANGE_IEXCHANGEMANAGESTORE2_METHODS(PURE)
    EXCHANGE_IEXCHANGEMANAGESTORE3_METHODS(PURE)
    EXCHANGE_IEXCHANGEMANAGESTORE4_METHODS(PURE)
    EXCHANGE_IEXCHANGEMANAGESTORE5_METHODS(PURE)
};
#undef    IMPL
#define IMPL

DECLARE_MAPI_INTERFACE_PTR(IExchangeManageStore5, LPEXCHANGEMANAGESTORE5);

In edkguid.h, add:

 DEFINE_GUID(IID_IExchangeManageStore5,0x7907dd18, 0xf141, 0x4676, 0xb1, 0x02, 0x37, 0xc9, 0xd9, 0x36, 0x34, 0x30);

Then you should be all set. Enjoy!

(Edit: fixed cut/paste typo in GetPublicFolderTableEx description)

Yet another IExchangeManageStore incarnation

Additional resources