IDistList::GetPropList
Internet Explorer Address Book Interfaces

IDistList::GetPropList


HRESULT GetPropList(
    ULONG  ulFlags,
    LPSPropTagArray FAR *  lppPropTagArray
);

Retrieves a list of the property tags on the object.

ulFlags
Must be zero for Internet Explorer Address Book.
lppPropTagArray
Returned property tag array. Must be freed by the caller if a non-NULL value is returned.

IDistList::GetProps

HRESULT GetProps(
    LPSPropTagArray lpPropTagArray,
    ULONG ulFlags,
    ULONG FAR * lpcValues,
    LPSPropValue FAR * lppPropArray
);

Retrieves the property tag information for the distribution list items.

lpPropTagArray
Address of an SPropTagArray structure of properties whose values are to be retrieved. A NULL value specifies that all properties should be retrieved.
ulFlags
MAPI_UNICODE flag. Not supported by Internet Explorer Address Book.
lpcValues
Returned value that represents the number of property values returned. If lppPropArray is NULL, the contents of the lpcValues parameter is zero.
lppPropArray
Returned SPropValue array. Must be freed by the caller.

IDistList::GetSearchCriteria

Currently not implemented by Internet Explorer Address Book.

IDistList::OpenEntry

HRESULT OpenEntry(
    ULONG cbEntryID,
    LPENTRYID lpEntryID,
    LPCIID lpInterface,
    ULONG ulFlags,
    ULONG FAR * lpulObjType,
    LPUNKNOWN FAR * lppUnk
);

Opens an entry contained in the distribution list and returns a pointer to the object to provide further access.

cbEntryID
Value that represents the number of bytes contained in the entry identifier to open.
lpEntryID
Address of an entry identifier of the object to open.
lpInterface
Address of an interface identifier (IID) for the object to open. Pass NULL to specify the standard interface for the object.
ulFlags
Bitmask containing object access flags. The default is read access only. The following flags can be used for modifications:
MAPI_BEST_ACCESS Specifies to open with best available access rights.
MAPI_MODIFY Requests read/write access.
MAPI_DEFERRED_ERRORS Currently not supported by Internet Explorer Address Book.
lpulObjType
Address of the object type of the opened entry.
lppUnk
Returned object pointer to the opened entry.

IDistList::OpenProperty

Currently not implemented by Internet Explorer Address Book.

IDistList::ResolveNames

Currently not implemented by Internet Explorer Address Book.

IDistList::SaveChanges

HRESULT SaveChanges(
    ULONG ulFlags
);

Provides the ability to save changes to the open distribution list object.

ulFlags
Bitmask of flags that control what happens to the object when the SaveChanges method is called. The following flags can be set:
FORCE_SAVE Writes changes to the object and closes it. Read-write access must have been set for the operation to succeed. This flag forces saving only if MAPI_E_OBJECT_CHANGED was returned from a preceding SaveChanges call. FORCE_SAVE overrides the previous changes made to the object.
KEEP_OPEN_READONLY Indicates the client requests changes be committed and the object be kept open for reading. This flag informs the provider that the object should not be modified and that the calling implementation will not call SaveChanges again. If the provider cannot keep the object open for read-only access, the entire call fails, changes are not saved, and MAPI_E_NO_ACCESS is returned.
KEEP_OPEN_READWRITE Indicates the client requests changes be committed and the object be kept open for read-write access. This flag is usually set when the object was initially opened for read-write access. After calling SaveChanges, the client can make further changes to the object if this flag is passed. If the provider cannot keep the object open for read-write access, the entire call fails, changes are not saved, and MAPI_E_NO_ACCESS is returned.
MAPI_DEFERRED_ERRORS Not supported by Internet Explorer Address Book.

IDistList::SetProps

HRESULT SetProps(
    ULONG cValues,
    LPSPropValue lpPropArray,
    LPSPropProblemArray FAR * lppProblems
);

Sets property values on a distribution list object.

cValues
Count of property values to be set. This parameter must not be zero.
lpPropArray
Address of an array of SPropValue structures containing the properties to set.
lppProblems
Returned problem array. Must be freed by the caller if a non-NULL value is returned.

IDistList::SetSearchCriteria

Currently not implemented by Internet Explorer Address Book.

IMailUser

The IMailUser interface is implemented by messaging user objects. IMailUser inherits from the IMAPIProp interface and has no unique methods of its own. The IMailUser interface provides access to the many properties that are associated with messaging users. The organization of the method list for IMailUser is arranged in v-table order.

IMailUser methods
GetLastError
SaveChanges
GetProps
GetPropList
OpenProperty
SetProps
DeleteProps
CopyTo
CopyProps
GetNamesFromIDs
GetIDsFromNames

IMailUser::CopyProps

Currently not implemented by Internet Explorer Address Book.

IMailUser::CopyTo

Currently not implemented by Internet Explorer Address Book.

IMailUser::DeleteProps

HRESULT DeleteProps(
    LPSPropTagArray  lpPropTagArray,
    LPSPropProblemArray FAR *  lppProblems
);

Deletes property values from a mail user object.

lpPropTagArray
Address of an array of property tags indicating the properties to delete. The cValues member of the SPropTagArray structure pointed to by lpPropTagArray must not be zero, and the lpPropTagArray parameter itself must not be NULL.
lppProblems
Returned problem array. Must be freed by the caller if a non-NULL value is returned.

IMailUser::GetIDsFromNames

HRESULT GetIDsFromNames(
    ULONG  cPropNames,
    LPMAPINAMEID FAR *  lppPropNames,
    ULONG  ulFlags,
    LPSPropTagArray FAR *  lppPropTags
);

Registers named properties with the mail user object.

cPropNames
Count of names to register. If lppPropNames is NULL, the cPropNames parameter must be zero.
lppPropNames
MAPINAMEID structure containing the names and their globally unique identifiers (GUIDs).
ulFlags
Bitmask of flags that indicate how the property identifiers should be returned. The following flag can be set:
MAPI_CREATE Creates a property identifier for any name not already mapped. The default is to fail those non-existent property names.
lppPropTags
Returned SPropTagArray of property tags. Must be freed by the caller.

IMailUser::GetLastError

Currently not implemented by Internet Explorer Address Book.

IMailUser::GetNamesFromIDs

Currently not implemented by Internet Explorer Address Book.

IMailUser::GetPropList

HRESULT GetPropList(
    ULONG   ulFlags,
    LPSPropTagArray FAR *  lppPropTagArray
);

Gets a list of the property tags on the object.

ulFlags
Must be zero for Internet Explorer Address Book.
lppPropTagArray
Returned property tag array. Must be freed by the caller if a non-NULL value is returned.

IMailUser::GetProps

HRESULT GetProps(
    LPSPropTagArray lpPropTagArray,
    ULONG ulFlags,
    ULONG FAR * lpcValues,
    LPSPropValue FAR * lppPropArray
);

Gets property values from a mail user object.

lpPropTagArray
SPropTagArray of properties to be retrieved. A NULL value specifies that all properties should be retrieved.
ulFlags
MAPI_UNICODE flag. Currently not supported by Internet Explorer Address Book.
lpcValues
Returned count of property values returned. This pointer can be NULL if the caller does not want the count of the returned property values.
lppPropArray
Returned SPropValue array. Must be freed by the caller.

IMailUser::OpenProperty

Currently not implemented by Internet Explorer Address Book.

IMailUser::SaveChanges

HRESULT SaveChanges(
    ULONG  ulFlags
);

Saves changes to the open mail user object. Note that the following properties may be calculated and changed at SaveChanges:
PR_DISPLAY_NAME
PR_GIVEN_NAME
PR_SURNAME
PR_LAST_MODIFICATION_TIME

ulFlags
Bitmask of flags that control what happens to the object when the SaveChanges method is called. The following flags can be set:
FORCE_SAVE Writes changes to the object and closes it. Read-write access must have been set for the operation to succeed. This flag forces saving only if MAPI_E_OBJECT_CHANGED was returned from a preceding SaveChanges call. FORCE_SAVE overrides the previous changes made to the object.
KEEP_OPEN_READONLY Indicates the client requests changes be committed and the object be kept open for reading. This flag informs the provider that the object should not be modified and that the calling implementation will not call SaveChanges again. If the provider cannot keep the object open for read-only access, the entire call fails, changes are not saved, and MAPI_E_NO_ACCESS is returned.
KEEP_OPEN_READWRITE Indicates the client requests changes be committed and the object be kept open for read-write access. This flag is usually set when the object was initially opened for read-write access. After calling SaveChanges, the client can make further changes to the object if this flag is passed. If the provider cannot keep the object open for read-write access, the entire call fails, changes are not saved, and MAPI_E_NO_ACCESS is returned.
MAPI_DEFERRED_ERRORS Currently not supported by Internet Explorer Address Book.

IMailUser::SetProps

HRESULT SetProps(
    ULONG  cValues,
    LPSPropValue  lpPropArray,
    LPSPropProblemArray FAR *   pProblems
);

Sets the property values on a mail user object.

cValues
Count of property values to be set.
lpPropArray
Array of SPropValue structures containing the properties to set.
pProblems
Returned problem array. Must be freed by the caller if a non-NULL value is returned.

IWABObject

The Internet Explorer Address Book object contains function pointers to memory allocation functions and database maintenance functions. The organization of the method list for IWABObject is arranged in v-table order.

IWABObject methods
GetLastError
AllocateBuffer
AllocateMore
FreeBuffer
Backup
Import
Find
VCardDisplay
LDAPUrl
VCardCreate
VCardRetrieve
GetMe
SetMe

IWABObject::AllocateBuffer

HRESULT AllocateBuffer(
    ULONG  cbSize,
    LPVOID FAR *  lppBuffer
);

Allocates a memory for a buffer. This is the allocation routine that should be used for buffers passed to Internet Explorer Address Book methods. The buffer should be freed with FreeBuffer and can be reallocated with AllocateMore.

cbSize
Specified size, in bytes, of the buffer to be allocated.
lppBuffer
Returned buffer pointer.

IWABObject::AllocateMore

HRESULT AllocateMore(
    ULONG           cbSize,
    LPVOID          lpObject,
    LPVOID FAR *    lppBuffer
);

Allocates a memory buffer that is linked to another buffer previously allocated with the AllocateBuffer function.

cbSize
Size, in bytes, of the buffer to be allocated.
lpObject
Existing buffer object allocated using AllocateBuffer.
lppBuffer
Returned buffer pointer; this buffer is linked to lpObject.

The only way to release a buffer allocated with AllocateMore is to pass the buffer pointer specified in the lpObject parameter to the FreeBuffer function. The link between the memory buffers allocated with AllocateBuffer and AllocateMore enables FreeBuffer to release both buffers with a single call.

IWABObject::Backup

Currently not implemented in Internet Explorer Address Book.

IWABObject::Find

HRESULT Find(
    HWnd
);

Launches the address book's Find dialog box. (Internet Explorer 4.0 only)

HWnd
HWND of the parent for the Find dialog box. Can be NULL.

IWABObject::FreeBuffer

HRESULT FreeBuffer(
    LPVOID lpBuffer
);

Frees memory allocated with AllocateBuffer or any of the Internet Explorer Address Book methods.

lpBuffer
Address of the buffer to free.

IWABObject::GetLastError

Currently not implemented in Internet Explorer Address Book.

IWABObject::GetMe

Currently not implemented in Internet Explorer Address Book.

IWABObject::Import

Currently not implemented in Internet Explorer Address Book.

IWABObject::LDAPUrl

HRESULT IWABObject::LDAPUrl (
    HWND  hWnd, 
    ULONG ulFlags, 
    LPTSTR  lpszLDAPURL, 
    LPMailUser * lppMailUser
);

This method processes a given LDAP Url and displays corresponding results. If the URL only contains a server name, the method will display the WAB Find dialog with the server name filled in, enabling the user to manually search the server. If the URL contains an explicit LDAP query, this method performs a search based on the query. If the query produces a single result, the method shows details on the single result, else if the query has multiple results, the method shows the WAB Find dialog with multiple search results filled in. If WABOBJECT_LDAPURL_RETURN_MAILUSER is specified in the ulFlags parameter, the method returns a IMailUser object, if the query returns a single specific result, else returns a MAPI_E_AMBIGUOUS_RECIP if the query returns multiple hits.

hWnd
HWND of the parent for displayed dialogs.
ulFlags
Flags specifying behavior. Can be zero, or WABOBJECT_LDAPURL_RETURN_MAILUSER.
lpszLDAPUrl
URL string, starting with ldap://. (Format for LDAP URLs is specified in RFC-1959)
lppMailUser
Returned IMailUser object, if requested. Null otherwise.

IWABObject::SetMe

Currently not implemented in Internet Explorer Address Book.

IWABObject::VCardCreate

HRESULT VCardCreate(
    lpAdrBook,
    lpFileName,
    lpMailUser
);

Translates the properties of an IMailUser object into a business card (vCard) file. (The vCard file format is an Internet standard for exchanging contact information through text based files).

The complete file name must be specified. If the file already exists, it will be overwritten.

Warning! This API is in development at this time, and is subject to change.

lpAdrBook
Address of an IAddrBook object.
lpFileName
Address of a string containing the complete path of the file to create.
lpMailUser
Address of a IMailUser object whose properties will be written into the file.

IWABObject::VCardDisplay

HRESULT VCardDisplay(
    lpAdrBook,
    hWnd,
    lpFileName
);

Displays the contents of a business card (vCard) file. The complete file name must be specified.

Warning! This API is in development at this time, and is subject to change.

lpAdrBook
Address of an IADRBOOK object.
hWnd
HWND of the parent for displayed dialog boxes.
lpFileName
Full path of vCard file to display. Fails if the file does not exist.

IWABObject::VCardRetrieve

HRESULT VCardRetrieve(
    lpAdrBook,
    lpFileName,
    lppMailUser
);

Reads a vCard file and creates a MailUser object containing the vCard properties.

lpAdrBook
Address of an IADRBOOK object.
lpFileName
Address of a string containing the complete path of the file to read. Fails if the file is not found.
lppMailUser
Returned MailUser object created containing the properties in the vCard file.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.