Published: July 16, 2012
Adds a new recipient directly to an address book container or to the recipient list of an outgoing message.
If you want the new entry to be added to a specific container, set lpEIDContainer to the container's entry identifier and cbEIDContainer to the byte count in the entry identifier.
If you want the new entry to be added to the recipient list of an outgoing message, set lpEIDContainer to NULL and cbEIDContainer to 0.
If you want to allow the user of a client application to select the type of entry to be created, pass 0 in cbEIDNewEntryTpl and NULL in lpEIDNewEntryTpl. NewEntry displays the MAPI one-off table, a list of templates that MAPI and each of the address book providers in the session support. Each template can create a recipient entry for one or more address types.
If you want to retain the entry identifier of the new entry, pass valid pointers in the lpcbEIDNewEntry and lppEIDNewEntry parameters. You are responsible for freeing this entry identifier when you are finished with it by calling the MAPIFreeBuffer function.
To use a particular template to add a new entry to a modifiable container, use the following procedure:
Call the IMAPISupport::OpenEntry method to open the destination container, and set the lpEntryID parameter to the entry identifier of the container.
Call the destination container's IMAPIProp::OpenProperty method, and set the ulPropTag parameter to PR_CREATE_TEMPLATES (PidTagCreateTemplates) and the lpiid parameter to IID_IMAPITable. The container will return a one-off table that lists all of the templates that it supports for creating new entries.
Retrieve the row that represents the template for the particular type of entry you want to create. The PR_ADDRTYPE (PidTagAddressType) column indicates the address type that is supported by the template.
Call IMAPISupport::NewEntry and set the lpEIDNewEntryTpl parameter to the entry identifier of the selected template. The entry identifier is the PR_ENTRYID (PidTagEntryId) column from the template's row in the one-off table. Pass 0 in cbEIDContainer and NULL in lpEIDContainer. Pass a valid pointer in the lppEIDNewEntry parameter if you want to retain the new entry's entry identifier.