DOCUMENT:Q203858  26-SEP-2001  [exchange]
TITLE   :HOWTO: Use the HrMailboxLogon Function
PRODUCT :Microsoft Exchange
PROD/VER::5.5
OPER/SYS:
KEYWORDS:kbdocfix kbEDK kbMsg kbVC kbEDK550 kbGrpDSMsg kbDSupport

======================================================================
-------------------------------------------------------------------------------
The information in this article applies to:

 - Microsoft Exchange Server, version 5.5 
-------------------------------------------------------------------------------

SUMMARY
=======

The Exchange Development Kit (EDK) HrMailboxLogon function takes a pair of
parameters for both the server name and the mailbox name. The documentation on
the HrMailboxLogon function is misleading.

According to the documentation on the HrMailboxLogon function, both the message
store (lpszMsgStoreDN) and the mailbox (lpszMailboxDN) parameters are
distinguished names, in the form of the following:

   /O=Organization/OU=Site/CN=Servers/CN=ServerName/CN=NULL
   /O=Organization/OU=Site/CN=Container/CN=MailboxName

However, the last leaf of the message store name parameter cannot be a NULL
value. If the HrMailboxLogon function is executed as the documentation suggests,
it fails with the following error message:

   0x80004005: Unspecified Error

MORE INFORMATION
================

To work around this behavior, the last leaf of the message store must have a
string that identifies the store name to be used (for example, "Microsoft
Private MDB" or "Microsoft Public MDB"). The lpszMsgStoreDn must be in the
following form:

   /O=Organization/OU=Site/CN=Servers/CN=ServerName/CN=Microsoft Private MDB
   or
   /O=Organization/OU=Site/CN=Servers/CN=ServerName/CN=Microsoft Public MDB

The following code demonstrates how to use the HrMailboxLogon to log on a user's
mailbox, and then return a pointer to this store.

Sample Code
-----------

In the following code, it is assumed that you have a valid lpSession and pointer
to the default message store lpmdbDefault (the user's inbox), and that
szMailboxDN is already set.

      (...)
      // Gets server distinguished name from current session - from edkutils.h
      hr = HrGetServerDN( lpSession, &lpszServerDN );
      if ( hr != S_OK ) {
          goto CleanUp;
      }
      strcpy(szServerDN, lpszServerDN);
      strcat(szServerDN, "/cn=Microsoft Private MDB");
      // Open user's mailbox using distinguished names
      hr = HrMailboxLogon(
              lpSession,
              lpmdbDefault,
              szServerDN,
              szMailboxDN,
              &lpmdbMailbox);
      if ( hr != S_OK ) {
          goto CleanUp;
      }
      (...)

REFERENCES
==========

For additional information about HrMailboxLogon code samples, click the article
numbers below to view the articles in the Microsoft Knowledge Base:

   Q194627 HOWTO: Open Mailboxes with Privileged Access

   Q200160 HOWTO: Loop Through Mailboxes on Exchange Using GetMailboxTable

Additional query words:

======================================================================
Keywords          : kbdocfix kbEDK kbMsg kbVC kbEDK550 kbGrpDSMsg kbDSupport 
Technology        : kbExchangeSearch kbExchange550 kbZNotKeyword2
Version           : :5.5
Issue type        : kbhowto

=============================================================================

THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS
PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.  MICROSOFT DISCLAIMS
ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  IN NO
EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR
ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL,
CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF
MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.  SOME STATES DO NOT ALLOW THE EXCLUSION
OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES
SO THE FOREGOING LIMITATION MAY NOT APPLY.

Copyright Microsoft Corporation 2001.