HOWTO: Getting the Details of a Recipient

• Extended Messaging Application Programming Interface (MAPI), version 1.0

SUMMARY

This article demonstrates code that calls IAddrBook::Details to display the address book details page for a given recipient. There are two necessary steps to displaying the details page:

1. Call IAddrBook::ResolveName to resolve the recipient to one and only one unique recipient.

2. Call IAddrBook::Details to display the details page for the unique recipient.

MORE INFORMATION

The following code is broken into two main functionality sections that match the steps necessary to show the details page of an address book for a given recipient.

The first function, GetDetails(), takes an in parameter, which is a string that represents either the display name or email alias of the recipient you are interested in. GetDetails calls the second function, ResolveName(), which takes an in parameter and an out parameter. The in parameter is a copy of the parameter passed to the GetDetails function. The out parameter is an LPADRLIST type that is passed back to you for use in the IAddrBook::Details method.

This code assumes the presence of an active MAPI session and an open Address book object. For more information on starting a MAPI session, see "Starting a MAPI Session" in the Microsoft Developer Network (MSDN) Library CD. For more information on opening an address book see "Opening the Address Book" in the MSDN Library CD.

   HRESULT GetDetails ( LPSTR lpszFriendlyName )
   {
       HRESULT hRes = S_OK;
       ULONG   ulUIParam = 0;
       LPADRLIST lpAdrList = NULL;
       ULONG cbEID = 0L;
       LPBYTE lpEID = NULL;

       hRes = ResolveName ( lpszFriendlyName, &lpAdrList );

       if ( SUCCEEDED ( hRes ) )
       {
           // Step through the rows of properties in lpAdrList. When we
           // find the PR_ENTRYID, stop and call the IAddrBook::Details
           // method to show  the information stored in the address book
           // about the requested recipient.
           for ( ULONG i = 0; i < lpAdrList -> aEntries -> cValues; i++ )
           {
               if ( PR_ENTRYID ==
                    lpAdrList -> aEntries -> rgPropVals[i].ulPropTag )
               {
                   // These next two assignments are unnecessary but make
                   // the code more readable below.
                   cbEID=lpAdrList->aEntries->rgPropVals[i].Value.bin.cb;
                   lpEID=lpAdrList->aEntries->rgPropVals[i].Value.bin.lpb;

                   hRes = m_pAddrBook -> Details ( &ulUIParam,
                                                   NULL, NULL,
                                                   cbEID,
                                                   (LPENTRYID) lpEID,
                                                   NULL, NULL, NULL,
                                                   DIALOG_MODAL );
                   break;
               }
           }
       }

       MAPIFreeBuffer ( lpAdrList );
       return hRes;
   }

   HRESULT ResolveName ( LPSTR lpszName, LPADRLIST *lpAdrList )
   {
       // NOTE: Callers of this function MUST release lpAdrList when done
       // with it using MAPIFreeBuffer.

       HRESULT hRes = S_OK;
       LPADRLIST pAdrList = NULL;

       // Allocate memory for new SRowSet structure.
       hRes = MAPIAllocateBuffer(CbNewSRowSet(1),(LPVOID*) &pAdrList);

       // If memory allocation fails, quit.
       if ( FAILED ( hRes ) )
        return hRes;

       // Zero out allocated memory.
       ZeroMemory ( pAdrList, CbNewSRowSet(1));

       // Allocate memory for SPropValue structure that indicates what
       // recipient properties will be set. NUM_RECIP_PROPS == 5.
       hRes = MAPIAllocateBuffer( 1 * sizeof(SPropValue),
                         (LPVOID*) &(pAdrList->aEntries[0].rgPropVals));

       // If memory allocation fails, quit.
       if ( FAILED ( hRes ) )
           hRes;

       // Zero out allocated memory.
       ZeroMemory ( pAdrList -> aEntries[0].rgPropVals,
                    sizeof(SPropValue) );

       // How many recipients.
       pAdrList->cEntries = 1;

       // How many properties per recipient.
       pAdrList->aEntries[0].cValues    = 1;

       // Set the SPropValue members == the desired values.
       pAdrList->aEntries[0].rgPropVals[0].ulPropTag = PR_DISPLAY_NAME;
       pAdrList->aEntries[0].rgPropVals[0].Value.lpszA =  lpszName;

       // ResolveName is kind enough to redimension the ADRLIST that we
       // pass to it and give us back a fully qualified ADRLIST structure
       // that contains all the recipient information the address book
       // decided to give us back.
       if ( SUCCEEDED (
          hRes = m_pAddrBook -> ResolveName ( (ULONG) m_hWnd,
                                               0L, NULL, pAdrList ) ) )
       *lpAdrList = pAdrList;

       return hRes;
   }

Keywords          : EMAPI
Version           : WINDOWS:1.0
Platform          : WINDOWS
Issue type        : kbhowto
Solution Type     : kbworkaround