HOWTO: Resolve a Recipient Using IAddrBook::ResolveName

ID: Q171426

The information in this article applies to:

Extended Messaging Application Programming Interface (MAPI), version 1.0
on the following platforms: NT, Win95, x86

SUMMARY

This article demonstrates code necessary to effectively call the IAddrBook::ResolveName method to retrieve a valid recipient given a specific display name.

MORE INFORMATION

The ResolveName method takes a long pointer to a string as input that represents the display name and passes back a fully qualified pointer to an LPADRLIST array that can be used in other calls that require such a parameter or pieces thereof:


   HRESULT ResolveName ( LPSTR lpszDisplayName LPADRLIST *lpAdrList
   LPADRBOOK pAddrBook)
   {
       HRESULT hRes = S_OK;
       ULONG   ulUIParam = 0;
       ULONG   cbEID = 0L;
       LPBYTE   lpEID = NULL;
       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. To resolve a name that
       // already exists in the Address book, this will always be 1.
       hRes = MAPIAllocateBuffer( 1 * sizeof(SPropValue),
                          (LPVOID*) &(pAdrList->aEntries[0].rgPropVals));

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

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

       // Resolve name will take as many entries in the ADRLIST as you
       // want to resolve, but each entry (ADRENTRY) can have only one
       // property previously set by the client - this is usually
       // PR_DISPLAY_NAME.

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

       // As far as I can tell this must always be 1L and will always
       // equal the multiplier in the MAPIAllocateBuffer call above.
       pAdrList->aEntries[0].cValues = 1L;

       // Set the SPropValue members == the desired values. This should
       // be PR_DISPLAY_NAME. You can substitute a display name with an
       // alias to search for. You can search by alias and display names
       // interchangeably in most address books.

       pAdrList->aEntries[0].rgPropVals[0].ulPropTag = PR_DISPLAY_NAME;
       pAdrList->aEntries[0].rgPropVals[0].Value.lpszA =  lpszDisplayName;

       // pAdrList->aEntries[0].rgPropVals[1].ulPropTag = PR_ENTRYID;

       // ResolveName is kind enough to redimension this array for us and
       // give back a fully filled out ADRLIST and ADRENTRY structures.

       hRes = m_pAddrBook -> ResolveName ( (ULONG) m_hWnd,
                                            0L, NULL, pAdrList );

       if ( SUCCEEDED ( hRes ) )
           *lpAdrList = pAdrList;

       return hRes;

It is important to note that when calling IAddrBook::ResolveName, it is necessary to allocate memory for only one property in the rgPropVals member of the aEntries member of the ADRLIST parameter. Trying to set or allocate memory larger than one property can have unexpected results. In most cases ResolveName simply returns MAPI_E_INVALID_PARAMETER, but under certain conditions, it can result in access violations.

Additional query words:

Keywords : kbMsg kbMAPI100
Version : WINDOWS:1.0
Platform : WINDOWS
Issue type : kbhowto