ADRLIST

The ADRLIST structure describes zero or more properties belonging to one or more recipients.

Quick Info

typedef struct _ADRLIST  
{  
     ULONG      cEntries;  
     ADRENTRY   aEntries[MAPI_DIM];  
} ADRLIST, FAR *LPADRLIST; 
 

Members

cEntries

Count of entries in the array specified by the aEntries member.

aEntries

Array of ADRENTRY structures, one structure for each recipient.

Remarks

An ADRLIST structure contains one or more ADRENTRY structures, each describing the properties of a recipient. A recipient can be unresolved, meaning that it is lacking an entry identifier in its array of property values, or resolved, meaning that the PR_ENTRYID property is included. Typically, resolved recipients also have an e-mail address — the PR_EMAIL_ADDRESS property. However, the e-mail address is not required. ADRLIST structures are used, for example, to describe the recipient list for an outgoing message and by MAPI to display the entries in the address book.

ADRLIST structures resemble SRowSet structures — the structures used for representing rows in tables. In fact, these two structures are designed so that they can be used interchangeably. Both contain an array of structures describing a group of properties and a count of the values in the array. Whereas in the ADRLIST structure, the array contains ADRENTRY structures, in the SRowSet structure the array contains SRow structures. ADRENTRY structures and SRow structures are identical in layout. Because ADRLIST and SRowSet structures follow the same allocation rules, an SRowSet structure that is retrieved from the contents table of an address book container can be cast to an ADRLIST structure and used as is.

The following diagram illustrates the layout of an ADRLIST structure.

The ADRENTRY and SPropValue portions in an ADRLIST structure must be allocated and freed independently of the other parts. That is, each SPropValue structure must be allocated individually after memory for the ADRENTRY structure has been allocated and freed before the ADRENTRY structure is freed. This independence in handling memory allows recipients and individual recipient properties to be freely added or deleted from the address list.

The MAPIAllocateBuffer and MAPIFreeBuffer functions must be used to allocate and free the ADRLIST structure and all its parts.

If a recipient list is too large to fit in memory, clients can call the IMessage::ModifyRecipients method to work with a subset of the list. Clients should not use the address book common dialog boxes in such a situation.

For more information on allocating memory for ADRENTRY structures, see Managing Memory for ADRLIST and SRowSet Structures.

See Also

Address Structures, ADRENTRY, CbNewADRLIST, IMessage::ModifyRecipients, SRowSet