HOWTO: Creating a One-Off Address

ID: Q170319

The information in this article applies to:

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

SUMMARY

This article explains how to programmatically call the CreateOneOff method of the IAddrBook::IMAPIProp interface and attach the newly created address to an existing message object.

MORE INFORMATION

Most address book providers support the ability to create temporary e-mail addresses so that users can send mail to a one-time recipient or to recipients that do not appear in a read-only list or a Global Address List.

Messaging Application Programming Interface (MAPI) clients that want to facilitate this feature should follow these steps and use similar code to incorporate this feature. (NOTE: The following code segments assume an existing connection to a MAPI session exists):

   HRESULT TestAddress(LPMESSAGE pMsg)
   {
     HRESULT hRes   = S_OK;      // Status code of MAPI calls
     LPADRLIST pAdrList   = NULL;  // ModifyRecips takes LPADRLIST

     enum {NAME,
       ADDR,
       EMAIL,
       RECIP,
       EID,
       NUM_RECIP_PROPS
     };
     SizedSPropTagArray(NUM_RECIP_PROPS, sRecipProps) =
     {
       NUM_RECIP_PROPS,  // number of columns (properties)
       {
         PR_DISPLAY_NAME,
         PR_ADDRTYPE,
         PR_EMAIL_ADDRESS,
         PR_RECIPIENT_TYPE,
         PR_ENTRYID
       }
     };

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

   // 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(
       NUM_RECIP_PROPS * sizeof(SPropValue),
       (LPVOID*) &(pAdrList->aEntries[0].rgPropVals));
   if (FAILED(hRes)) goto Quit;

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

   // Setup the One Time recipient by indicating how many
   // recipients and how many properties will be set on each // recipient.

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

   // Set the SPropValue members == the desired values.
    pAdrList->aEntries[0].rgPropVals[NAME].ulPropTag =     PR_DISPLAY_NAME;
    pAdrList->aEntries[0].rgPropVals[NAME].Value.lpszA =
       "<Display Name>";

    pAdrList->aEntries[0].rgPropVals[ADDR].ulPropTag =
       PR_ADDRTYPE;
    pAdrList->aEntries[0].rgPropVals[ADDR].Value.lpszA =
       "SMTP";

    pAdrList->aEntries[0].rgPropVals[EMAIL].ulPropTag =
       PR_EMAIL_ADDRESS;
    pAdrList->aEntries[0].rgPropVals[EMAIL].Value.lpszA =
       "<email address>";

    pAdrList->aEntries[0].rgPropVals[RECIP].ulPropTag =
       PR_RECIPIENT_TYPE;
    pAdrList->aEntries[0].rgPropVals[RECIP].Value.l =
       MAPI_TO;

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

   // Create the One-off address and get an EID for it.
     hRes = m_pAddrBook->CreateOneOff(
       pAdrList-> aEntries[0].rgPropVals[NAME].Value.lpszA,
       pAdrList-> aEntries[0].rgPropVals[ADDR].Value.lpszA,
       pAdrList-> aEntries[0].rgPropVals[EMAIL].Value.lpszA,
       0,
       &pAdrList->aEntries[0].rgPropVals[EID].Value.bin.cb,
       (LPENTRYID*)
       (&pAdrList->aEntries[0].rgPropVals[EID].Value.bin.lpb));
     if (FAILED(hRes)) goto Quit;

     hRes = m_pAddrBook->ResolveName(
       0L,
       0L,
       NULL,
       pAdrList );
     if (FAILED(hRes)) goto Quit;

   // If everything goes right, add the new recipient to the
   // message object passed into us.
     hRes = pMsg->ModifyRecipients(MODRECIP_ADD,pAdrList);
     if (FAILED(hRes)) goto Quit;

     hRes = pMsg->SaveChanges(FORCE_SAVE);
     if (FAILED(hRes)) goto Quit;

   Quit:
   // Always release any newly created objects and
   // allocated memory.
     FreePadrlist(pAdrList);

     return hRes;
   }

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

Last Reviewed: January 9, 1999