IABContainer.c File Reference

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

#include "libmapi/libmapi.h"
#include "libmapi/libmapi_private.h"

Functions

_PUBLIC_ enum MAPISTATUS GetABRecipientInfo (struct mapi_session *session, const char *username, struct SPropTagArray *pPropTags, struct PropertyRowSet_r **ppRowSet)
 
_PUBLIC_ enum MAPISTATUS GetGALTable (struct mapi_session *session, struct SPropTagArray *SPropTagArray, struct PropertyRowSet_r **rowsetp, uint32_t count, uint8_t ulFlags)
 
_PUBLIC_ enum MAPISTATUS GetGALTableCount (struct mapi_session *session, uint32_t *totalRecs)
 
_PUBLIC_ enum MAPISTATUS ResolveNames (struct mapi_session *session, const char **usernames, struct SPropTagArray *props, struct PropertyRowSet_r **rowset, struct PropertyTagArray_r **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 PropertyRowSet_r **  ppRowSet 
)

Retrieve Address Book information for a given recipient

Parameters
sessionpointer to the MAPI session context
usernamepointer to the username to retrieve information from
pPropTagspointer to the property tags array to lookup
ppRowSetpointer 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_PropertyValue_PropertyRowSet_data(), 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 PropertyRowSet_r **  rowsetp,
uint32_t  count,
uint8_t  ulFlags 
)

Retrieve the global address list

The Global Address List is the full list of email addresses (and other account-type things, such as "rooms" and distribution lists) accessible on the server. A user will usually have access to both a personal address book, and to the Global Address List. Public Address Book is another name for Global Address List.

You access the Global Address List by setting the list of things that you want to retrieve from the Global Address List as property names in the SPropTagArray argument, and then calling this function. The results are returned in SRowSet.

You can get a convenient output of the results using mapidump_PAB_entry() for each row returned.

Parameters
sessionpointer to the MAPI session context
SPropTagArraypointer to an array of MAPI properties we want to fetch
SRowSetpointer to the rows of the table returned
countthe number of rows we want to fetch
ulFlagsspecify 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

The Global Address List may be quite large (tens of thousands of entries in a large deployment), so you usually call this function with ulFlags set to TABLE_START the first time, and then subsequent calls will be made with TABLE_CUR to progress through the table.

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, mapidump_PAB_entry

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

_PUBLIC_ enum MAPISTATUS GetGALTableCount ( struct mapi_session session,
uint32_t *  totalRecs 
)

Retrieve the total number of records in the global address list

The Global Address List is the full list of email addresses (and other account-type things, such as "rooms" and distribution lists) accessible on the server. A user will usually have access to both a personal address book, and to the Global Address List. Public Address Book is another name for Global Address List.

Parameters
sessionpointer to the MAPI session context
totalRecspointers to the total number of records in the global address list returned
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

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

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

Resolve user names against the Windows Address Book Provider

Parameters
sessionpointer to the MAPI session context
usernameslist of user names to resolve
rowsetresulting list of user details
propsresulting list of resolved names
flaglistresulting list of resolution status (see below)
flagsif 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 responsibility to call MAPIFreeBuffer on rowset and flaglist once they have finished to use them.

See Also
MAPILogonProvider, GetLastError

References mapi_provider::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().


Creative Commons License
Creative Commons Attribution icon Creative Commons Share Alike icon
This content is licensed under the Creative Commons
Attribution ShareAlike License v. 3.0:
http://creativecommons.org/licenses/by-sa/3.0/