IAddrBook::NewEntry
Applies to: Office 2010 | Outlook 2010 | Visual Studio
Adds a new recipient to an address book container or to the recipient list of an outgoing message.
HRESULT NewEntry(
ULONG_PTR ulUIParam,
ULONG ulFlags,
ULONG cbEIDContainer,
LPENTRYID lpEIDContainer,
ULONG cbEIDNewEntryTpl,
LPENTRYID lpEIDNewEntryTpl,
ULONG FAR * lpcbEIDNewEntry,
LPENTRYID FAR * lppEIDNewEntry
);
Parameters
ulUIParam
[in] A handle to the parent window for the dialog box.ulFlags
[in] A bitmask of flags that controls the type of the text that is used. The following flag can be set:- MAPI_UNICODE
The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.
- MAPI_UNICODE
cbEIDContainer
[in] The byte count in the entry identifier pointed to by the lpEIDContainer parameter.lpEIDContainer
[in] A pointer to the entry identifier of the container where the new recipient is to be added. If the cbEIDContainer parameter is zero, the NewEntry method returns a recipient entry identifier and a list of templates as if the IAddrBook::CreateOneOff method was called.cbEIDNewEntryTpl
[in] The byte count in the entry identifier pointed to by the lpEIDNewEntryTpl parameter.lpEIDNewEntryTpl
[in] A pointer to a one-off template that will be used to create the new recipient. If cbEIDNewEntryTpl is zero and lpEIDNewEntryTpl is NULL, NewEntry displays a dialog box with which the user can select from a list of templates for adding new entries.lpcbEIDNewEntry
[out] A pointer to the byte count in the entry identifier pointed to by the lppEIDNewEntry parameter.lppEIDNewEntry
[out] A pointer to a pointer to the new recipient's entry identifier.
Return Value
- S_OK
The new address book entry was successfully created.
Remarks
The NewEntry method creates a new address book entry, to be added directly into a container or to be used to address an outgoing message.
Notes to Callers
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 zero.
If you want to allow the user of a client application to select the type of entry to be created, pass zero in cbEIDNewEntryTpl and NULL in lpEIDNewEntryTpl. The NewEntry method displays the MAPI one-off table, a list of templates supported by MAPI and by each address book provider in the session. 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 IMAPISession::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 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 the NewEntry method, and set lpEIDNewEntryTpl to the entry identifier of the selected template. The entry identifier will be the PR_ENTRYID (PidTagEntryId) column from the template's row in the one-off table. Pass zero 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.