IMAPISupport::NewEntry

The IMAPISupport::NewEntry adds a new recipient directly to an address book container or to the recipient list of an outgoing message.

Quick Info

See IMAPISupport : IUnknown.

HRESULT NewEntry(
  ULONG ulUIParam,            
  ULONG ulFlags,              
  ULONG cbEIDContainer,       
  LPENTRYID lpEIDContainer,   
  ULONG cbEIDNewEntryTpl,     
  LPENTRYID lpEIDNewEntryTpl,   
  ULONG FAR * lpcbEIDNewEntry,   
  LPENTRYID FAR * lppEIDNewEntry  
);

Parameters

ulUIParam: [in] Handle of the parent window for the dialog box.
ulFlags: Reserved; must be zero.
cbEIDContainer: [in] Count of bytes in the entry identifier pointed to by the lpEIDContainer parameter.
lpEIDContainer: [in] Pointer to the entry identifier of the container to receive the new entry. If cbEIDContainer is zero and lpEIDContainer is NULL, NewEntry creates a one-off entry identifier that is the same type as is generated by a call to IMAPISupport::CreateOneOff.
cbEIDNewEntryTpl: [in] Count of bytes in the entry identifier pointed to by the lpEIDNewEntryTpl parameter.
lpEIDNewEntryTpl: [in] Pointer to the entry identifier of the template to be used to create the new entry. If cbEIDNewEntryTpl is zero and lpEIDNewEntryTpl is NULL, NewEntry displays a dialog box enabling the user to select from a list of templates for adding new entries.
lpcbEIDNewEntry: [out] Pointer to the count of bytes in the entry identifier pointed to by the lppEIDNewEntry parameter.
lppEIDNewEntry: [out] Pointer to a pointer to the entry identifier of the newly created entry.

Return Values

S_OK: The new entry was successfully created.

Remarks

The IMAPISupport::NewEntry method is implemented for address book provider support objects. Address book providers call NewEntry to create 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 count of bytes 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. NewEntry displays the MAPI one-off table — a listing of templates supported by MAPI and by each of the address book providers 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 have finished with it by calling the MAPIFreeBuffer function.

To use a particular template for adding a new entry to a modifiable container

Call IMAPISupport::OpenEntry to open the destination container, setting the lpEntryID parameter to the entry identifier of the container.
Call the destination container's IMAPIProp::OpenProperty method and set ulPropTag to PR_CREATE_TEMPLATES and lpiid to IID_IMAPITable. The container will return a one-off table listing 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 column indicates the address type that is supported by the template.
Call IMAPISupport::NewEntry and set lpEIDNewEntryTpl to the entry identifier of the selected template. This will be the PR_ENTRYID 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.