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 IMAPISupport::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 MAPI s 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.
{bmc bm4.MRB} To use a particular template for adding a new entry to a
modifiable container
1. Call IMAPISupport::OpenEntry to open the destination
container, setting the lpEntryID parameter to the entry identifier of
the container.
2. 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.
3. 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.
4. 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.
See Also