libmapi/IABContainer.c File Reference

Provides access to address book containers -- Used to perform name resolution. More...

#include <libmapi/libmapi.h>

Functions
_PUBLIC_ enum MAPISTATUS	GetABRecipientInfo (struct mapi_session *session, const char *username, struct SPropTagArray *pPropTags, struct SRowSet **ppRowSet)
_PUBLIC_ enum MAPISTATUS	GetGALTable (struct mapi_session *session, struct SPropTagArray *SPropTagArray, struct SRowSet **SRowSet, uint32_t count, uint8_t ulFlags)
_PUBLIC_ enum MAPISTATUS	ResolveNames (struct mapi_session *session, const char **usernames, struct SPropTagArray *props, struct SRowSet **rowset, struct SPropTagArray **flaglist, uint32_t flags)

---

Detailed Description

Provides access to address book containers -- Used to perform name resolution.

---

Function Documentation

_PUBLIC_ enum MAPISTATUS GetABRecipientInfo	(	struct mapi_session *	session,
		const char *	username,
		struct SPropTagArray *	pPropTags,
		struct SRowSet **	ppRowSet
	)

Retrieve Address Book information for a given recipient

Parameters:

session	pointer to the MAPI session context
username	pointer to the username to retrieve information from
pPropTags	pointer to the property tags array to lookup
ppRowSet	pointer on pointer to the results

Note that if pPropTags is NULL, then GetABNameInfo will fetch the following default property tags:

1. PR_ADDRTYPE_UNICODE
2. PR_EMAIL_ADDRESS_UNICODE
3. PR_DISPLAY_NAME_UNICODE
4. PR_OBJECT_TYPE

Returns:

MAPI_E_SUCCESS on success, otherwise MAPI error.

Note:

Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:

1. MAPI_E_NOT_INITIALIZED if MAPI subsystem is not initialized
2. MAPI_E_SESSION_LIMIT if the NSPI session is unavailable
3. MAPI_E_INVALID_PARAMETER if a function parameter is invalid
4. MAPI_E_NOT_FOUND if the username to lookup doesn't match any records

See also:

nspi_DNToMId, nspi_GetProps

References mapi_provider::ctx, get_SPropValue_SRowSet_data(), global_mapi_ctx, MAPI_RESOLVED, MAPI_UNICODE, MAPIFreeBuffer(), nspi_context::mem_ctx, mapi_session::nspi, nspi_DNToMId(), nspi_GetProps(), OPENCHANGE_RETVAL_IF, PR_7BIT_DISPLAY_NAME_UNICODE, PR_ADDRTYPE_UNICODE, PR_DISPLAY_NAME_UNICODE, PR_DISPLAY_TYPE, PR_EMAIL_ADDRESS_UNICODE, PR_ENTRYID, PR_OBJECT_TYPE, PR_SEARCH_KEY, PR_SEND_INTERNET_ENCODING, PR_SEND_RICH_INFO, PR_SMTP_ADDRESS_UNICODE, PR_TRANSMITTABLE_DISPLAY_NAME_UNICODE, mapi_session::profile, ResolveNames(), and set_SPropTagArray().

Referenced by GetUserFreeBusyData().

_PUBLIC_ enum MAPISTATUS GetGALTable	(	struct mapi_session *	session,
		struct SPropTagArray *	SPropTagArray,
		struct SRowSet **	SRowSet,
		uint32_t	count,
		uint8_t	ulFlags
	)

Retrieve the global address list

Parameters:

session	pointer to the MAPI session context
SPropTagArray	pointer on an array of MAPI properties we want to fetch
SRowSet	pointer on the rows returned
count	the number of rows we want to fetch
ulFlags	specify the table cursor location

Possible value for ulFlags:

1. TABLE_START: Fetch rows from the beginning of the table
2. TABLE_CUR: Fetch rows from current table location

Returns:

MAPI_E_SUCCESS on success, otherwise MAPI error.

Note:

Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:

1. MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
2. MAPI_E_SESSION_LIMIT: No session has been opened on the provider
3. MAPI_E_INVALID_PARAMETER: if a function parameter is invalid
4. MAPI_E_CALL_FAILED: A network problem was encountered during the transaction

See also:

MapiLogonEx, MapiLogonProvider

References mapi_provider::ctx, global_mapi_ctx, nspi_context::mem_ctx, mapi_session::nspi, nspi_QueryRows(), OPENCHANGE_RETVAL_IF, nspi_context::pStat, and TABLE_START.

_PUBLIC_ enum MAPISTATUS ResolveNames	(	struct mapi_session *	session,
		const char **	usernames,
		struct SPropTagArray *	props,
		struct SRowSet **	rowset,
		struct SPropTagArray **	flaglist,
		uint32_t	flags
	)

Resolve user names against the Windows Address Book Provider

Parameters:

session	pointer to the MAPI session context
usernames	list of user names to resolve
rowset	resulting list of user details
props	resulting list of resolved names
flaglist	resulting list of resolution status (see below)
flags	if set to MAPI_UNICODE then UNICODE MAPITAGS can be used, otherwise only UTF8 encoded fields may be returned.

Possible flaglist values are:

1. MAPI_UNRESOLVED: could not be resolved
2. MAPI_AMBIGUOUS: resolution match more than one entry
3. MAPI_RESOLVED: resolution matched a single entry

Returns:

MAPI_E_SUCCESS on success, otherwise MAPI error.

Note:

Developers may also call GetLastError() to retrieve the last MAPI error code. Possible MAPI error codes are:

1. MAPI_E_NOT_INITIALIZED: MAPI subsystem has not been initialized
2. MAPI_E_SESSION_LIMIT: No session has been opened on the provider
3. MAPI_E_NOT_ENOUGH_RESOURCES: MAPI subsystem failed to allocate the necessary resources to operate properly
4. MAPI_E_NOT_FOUND: No suitable profile database was found in the path pointed by profiledb
5. MAPI_E_CALL_FAILED: A network problem was encountered during the transaction

It is the developer responsability to call MAPIFreeBuffer on rowset and flaglist once they have finished to use them.

See also:

MAPILogonProvider, GetLastError

References mapi_provider::ctx, global_mapi_ctx, MAPI_UNICODE, nspi_context::mem_ctx, mapi_session::nspi, nspi_ResolveNames(), nspi_ResolveNamesW(), and OPENCHANGE_RETVAL_IF.

Referenced by AddUserPermission(), GetABRecipientInfo(), ModifyUserPermission(), and RemoveUserPermission().