IAddrBook::NewEntry
The IAddrBook::NewEntry
method adds a new recipient directly to an address book container or to the
recipient list of an outgoing message..
Quick Info
See IAddrBook
: IMAPIProp.
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 where the new recipient is to be
added. If the cbEIDContainer parameter is zero, NewEntry returns
a recipient entry identifier and a list of templates as if the IAddrBook::CreateOneOff method was called.
cbEIDNewEntryTpl
[in] Count of
bytes in the entry identifier pointed to by the lpEIDNewEntryTpl
parameter.
lpEIDNewEntryTpl
[in] Pointer
to a one-off template to be used to create the new recipient. 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 is returned.
lppEIDNewEntry
[out] Pointer
to a pointer to the new recipient s entry identifier.
Return Values
S_OK
The new
address book entry was successfully created.
Remarks
The IAddrBook::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 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:
Call IMAPISession::OpenEntry to open the destination
container, setting the lpEntryID parameter to the entry identifier of
the container.
1. Call the destination container s IMAPIProp::OpenProperty method
and set ulPropTag to PR_CREATE_TEMPLATES1J2KQUP 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.
2. 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.
3. Call IAddrBook::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