ADRLIST
Applies to: Office 2010 | Outlook 2010 | Visual Studio
Describes zero or more properties that belong to one or more recipients.
Header file: |
Mapidefs.h |
Related macros: |
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. This means that it is lacking an entry identifier in its array of property values. A resolved recipient means that the PR_ENTRYID (PidTagEntryId) property is included. Typically, resolved recipients also have an e-mail address the PR_EMAIL_ADDRESS (PidTagEmailAddress) 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 illustration shows the layout of an ADRLIST structure.
ADRLIST components
.gif "ADRLIST components")
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 this situation.
For more information about how to allocate memory for ADRENTRY structures, see Managing Memory for ADRLIST and SRowSet Structures.