libmapi/nspi.c File Reference

Name Service Provider (NSPI) stack functions. More...

#include <libmapi/libmapi.h>

Functions

_PUBLIC_ struct nspi_contextnspi_bind (TALLOC_CTX *parent_ctx, struct dcerpc_pipe *p, struct cli_credentials *cred, uint32_t codepage, uint32_t language, uint32_t method)
_PUBLIC_ enum MAPISTATUS nspi_CompareMIds (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, uint32_t MId1, uint32_t MId2, uint32_t *plResult)
int nspi_disconnect_dtor (void *data)
_PUBLIC_ enum MAPISTATUS nspi_DNToMId (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, struct StringsArray_r *pNames, struct SPropTagArray **ppMIds)
_PUBLIC_ enum MAPISTATUS nspi_GetIDsFromNames (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, bool VerifyNames, uint32_t cNames, struct PropertyName_r *ppNames, struct SPropTagArray **ppPropTags)
_PUBLIC_ enum MAPISTATUS nspi_GetMatches (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, struct SPropTagArray *pPropTags, struct Restriction_r *Filter, struct SRowSet **ppRows, struct SPropTagArray **ppOutMIds)
_PUBLIC_ enum MAPISTATUS nspi_GetNamesFromIDs (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, struct FlatUID_r *lpGuid, struct SPropTagArray *pPropTags, struct SPropTagArray **ppReturnedPropTags, struct PropertyNameSet_r **ppNames)
_PUBLIC_ enum MAPISTATUS nspi_GetPropList (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, bool WantObject, uint32_t dwMId, struct SPropTagArray **ppPropTags)
_PUBLIC_ enum MAPISTATUS nspi_GetProps (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, struct SPropTagArray *pPropTags, struct SPropTagArray *MId, struct SRowSet **SRowSet)
_PUBLIC_ enum MAPISTATUS nspi_GetSpecialTable (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, uint32_t Type, struct SRowSet **ppRows)
_PUBLIC_ enum MAPISTATUS nspi_GetTemplateInfo (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, uint32_t dwFlags, uint32_t ulType, char *pDN, struct SRow **ppData)
_PUBLIC_ enum MAPISTATUS nspi_ModLinkAtt (struct nspi_context *nspi_ctx, bool Delete, uint32_t ulPropTag, uint32_t MId, struct BinaryArray_r *lpEntryIds)
_PUBLIC_ enum MAPISTATUS nspi_ModProps (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, uint32_t MId, struct SPropTagArray *pPropTags, struct SRow *pRow)
_PUBLIC_ enum MAPISTATUS nspi_QueryColumns (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, bool WantUnicode, struct SPropTagArray **ppColumns)
_PUBLIC_ enum MAPISTATUS nspi_QueryRows (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, struct SPropTagArray *pPropTags, struct SPropTagArray *MIds, uint32_t count, struct SRowSet **ppRows)
_PUBLIC_ enum MAPISTATUS nspi_ResolveNames (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, const char **usernames, struct SPropTagArray *pPropTags, struct SRowSet ***pppRows, struct SPropTagArray ***pppMIds)
_PUBLIC_ enum MAPISTATUS nspi_ResolveNamesW (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, const char **usernames, struct SPropTagArray *pPropTags, struct SRowSet ***pppRows, struct SPropTagArray ***pppMIds)
_PUBLIC_ enum MAPISTATUS nspi_ResortRestriction (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, enum TableSortOrders SortType, struct SPropTagArray *pInMIds, struct SPropTagArray **ppMIds)
_PUBLIC_ enum MAPISTATUS nspi_SeekEntries (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, enum TableSortOrders SortType, struct SPropValue *pTarget, struct SPropTagArray *pPropTags, struct SPropTagArray *pMIds, struct SRowSet **pRows)
_PUBLIC_ enum MAPISTATUS nspi_unbind (struct nspi_context *nspi_ctx)
_PUBLIC_ enum MAPISTATUS nspi_UpdateStat (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, uint32_t *plDelta)

Detailed Description

Name Service Provider (NSPI) stack functions.


Function Documentation

_PUBLIC_ struct nspi_context* nspi_bind ( TALLOC_CTX *  parent_ctx,
struct dcerpc_pipe *  p,
struct cli_credentials *  cred,
uint32_t  codepage,
uint32_t  language,
uint32_t  method 
) [read]

Initiates a session between a client and the NSPI server.

Parameters:
parent_ctx pointer to the memory context
p pointer to the DCERPC pipe
cred pointer to the user credentials
codepage the code to set in the STAT structure
language the language to set in the STAT structure
method the method to set in the STAT structure
Returns:
Allocated pointer to a nspi_context structure on success, otherwise NULL

References nspi_context::cred, nspi_context::mem_ctx, nspi_context::pStat, nspi_context::rpc_connection, and nspi_context::version.

Referenced by Logon().

_PUBLIC_ enum MAPISTATUS nspi_CompareMIds ( struct nspi_context nspi_ctx,
TALLOC_CTX *  mem_ctx,
uint32_t  MId1,
uint32_t  MId2,
uint32_t *  plResult 
)

Compares the position in an address book container of two objects identified by MId and returns the value of the comparison

Parameters:
nspi_ctx pointer to the NSPI connection context
mem_ctx pointer to the memory context
MId1 the first MId to compare
MId2 the second MId to compare
plResult pointer to the value of the comparison
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.

References nspi_context::handle, OPENCHANGE_RETVAL_IF, nspi_context::pStat, and nspi_context::rpc_connection.

int nspi_disconnect_dtor ( void *  data  ) 

Destructor for the NSPI context. Call the NspiUnbind function.

Parameters:
data generic pointer to data with mapi_provider information
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.

References mapi_provider::ctx, and nspi_unbind().

Referenced by MapiLogonProvider().

_PUBLIC_ enum MAPISTATUS nspi_DNToMId ( struct nspi_context nspi_ctx,
TALLOC_CTX *  mem_ctx,
struct StringsArray_r *  pNames,
struct SPropTagArray **  ppMIds 
)

Maps a set of DN to a set of MId

Parameters:
nspi_ctx pointer to the NSPI connection context
mem_ctx pointer to the memory context
pNames pointer to a StringsArray_r structure with the DN to map
ppMIds pointer on pointer to the returned list of MIds
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error

References nspi_context::handle, OPENCHANGE_RETVAL_IF, and nspi_context::rpc_connection.

Referenced by GetABRecipientInfo(), and ProcessNetworkProfile().

_PUBLIC_ enum MAPISTATUS nspi_GetIDsFromNames ( struct nspi_context nspi_ctx,
TALLOC_CTX *  mem_ctx,
bool  VerifyNames,
uint32_t  cNames,
struct PropertyName_r *  ppNames,
struct SPropTagArray **  ppPropTags 
)

Retrieve the Property IDs associated with property names from the NSPI server.

Parameters:
nspi_ctx pointer on the NSPI connection context
mem_ctx pointer to the memoty context
VerifyNames boolean value defining whether the NSPI server must verify that all client specified names are recognized by the server
cNames count of PropertyName_r entries
ppNames pointer to a PropertyName_r structure with the list of property tags supplied by the client
ppPropTags pointer on pointer to the list of proptags returned by the server
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error

References nspi_context::handle, OPENCHANGE_RETVAL_IF, and nspi_context::rpc_connection.

_PUBLIC_ enum MAPISTATUS nspi_GetMatches ( struct nspi_context nspi_ctx,
TALLOC_CTX *  mem_ctx,
struct SPropTagArray *  pPropTags,
struct Restriction_r *  Filter,
struct SRowSet **  ppRows,
struct SPropTagArray **  ppOutMIds 
)

Returns an explicit table.

Parameters:
nspi_ctx pointer to the NSPI connection context
mem_ctx pointer to the memory context
pPropTags pointer to an array of property tags of columns
Filter pointer to the Restriction to apply to the table
ppRows pointer to pointer to a SRowSet structure holding the rows returned by the server
ppOutMIds pointer to pointer to a list of MId that comprise a restricted address book container
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.

References nspi_context::handle, OPENCHANGE_RETVAL_IF, nspi_context::pStat, and nspi_context::rpc_connection.

Referenced by ProcessNetworkProfile().

_PUBLIC_ enum MAPISTATUS nspi_GetNamesFromIDs ( struct nspi_context nspi_ctx,
TALLOC_CTX *  mem_ctx,
struct FlatUID_r *  lpGuid,
struct SPropTagArray *  pPropTags,
struct SPropTagArray **  ppReturnedPropTags,
struct PropertyNameSet_r **  ppNames 
)

Returns a list of property names for a set of proptags

Parameters:
nspi_ctx pointer on the NSPI connection text
mem_ctx pointer to the memory context
lpGuid the property set about which the client is requesting information
pPropTags pointer to the proptags list
ppReturnedPropTags pointer on pointer to the list of all the proptags in the property set specified in lpGuid
ppNames pointer on pointer to the list of property names returned by the server
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error

References nspi_context::handle, OPENCHANGE_RETVAL_IF, and nspi_context::rpc_connection.

_PUBLIC_ enum MAPISTATUS nspi_GetPropList ( struct nspi_context nspi_ctx,
TALLOC_CTX *  mem_ctx,
bool  WantObject,
uint32_t  dwMId,
struct SPropTagArray **  ppPropTags 
)

Returns a list of all the properties that have values on the specified object

Parameters:
nspi_ctx pointer to the NSPI connection context
mem_ctx pointer to the memory context
WantObject boolean value defining whether we want the server to include properties with the type set to PT_OBJECT
dwMId the MId of the specified object
ppPropTags pointer on pointer to the list of property tags associated to the object.
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.

References nspi_context::handle, OPENCHANGE_RETVAL_IF, nspi_context::pStat, and nspi_context::rpc_connection.

_PUBLIC_ enum MAPISTATUS nspi_GetProps ( struct nspi_context nspi_ctx,
TALLOC_CTX *  mem_ctx,
struct SPropTagArray *  pPropTags,
struct SPropTagArray *  MId,
struct SRowSet **  SRowSet 
)

Returns an address book row containing a set of the properties and values that exists on an object

Parameters:
nspi_ctx pointer to the NSPI connection context
mem_ctx pointer to the memory context
pPropTags pointer to the list of property tags that the client wants to be returned
MId pointer to the MId of the record
SRowSet pointer on pointer to the row returned by the server
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error

References nspi_context::handle, OPENCHANGE_RETVAL_IF, nspi_context::pStat, and nspi_context::rpc_connection.

Referenced by GetABRecipientInfo(), and ProcessNetworkProfile().

_PUBLIC_ enum MAPISTATUS nspi_GetSpecialTable ( struct nspi_context nspi_ctx,
TALLOC_CTX *  mem_ctx,
uint32_t  Type,
struct SRowSet **  ppRows 
)

Returns the rows of a special table to the client. The special table can be a Hierarchy Table or an Address Creation Table

Parameters:
nspi_ctx pointer to the NSPI connection context
mem_ctx pointer to the memory context
Type bitmap of flags defining the type of the special table
ppRows pointer on pointer to the rows returned by the server

Possible values for Type:

  1. NspiAddressCreationTemplates to access an Address Creation Table
  2. NspiUnicodeStrings for strings to be returned in Unicode

If NspiAddressCreationTemplates is not set, then NspiGetSpecialTable will automatically fetch the Hierarchy Table.

If NspiAddressCreationTemplates is set, then NspiUnicodeStrings is ignored.

Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.

References nspi_context::handle, OPENCHANGE_RETVAL_IF, nspi_context::pStat, nspi_context::rpc_connection, and nspi_context::version.

Referenced by ProcessNetworkProfile().

_PUBLIC_ enum MAPISTATUS nspi_GetTemplateInfo ( struct nspi_context nspi_ctx,
TALLOC_CTX *  mem_ctx,
uint32_t  dwFlags,
uint32_t  ulType,
char *  pDN,
struct SRow **  ppData 
)

Returns information about template objects in the address book.

Parameters:
nspi_ctx pointer to the NSPI memory context
mem_ctx pointer to the memory context
dwFlags set of bit flags
ulType specifies the display type of the template
pDN the DN of the template requested
ppData pointer on pointer to the data requested

Possible values for dwFlags:

  1. TI_TEMPLATE to return the template
  2. TI_SCRIPT to return the script associated to the template
  3. TI_EMT to return the e-mail type associated to the template
  4. TI_HELPFILE_NAME to return the help file associated to the template
  5. TI_HELPFILE_CONTENTS to return the contents of the help file associated to the template
    Returns:
    MAPI_E_SUCCESS on success, otherwise MAPI error.

References nspi_context::handle, OPENCHANGE_RETVAL_IF, nspi_context::pStat, and nspi_context::rpc_connection.

_PUBLIC_ enum MAPISTATUS nspi_ModLinkAtt ( struct nspi_context nspi_ctx,
bool  Delete,
uint32_t  ulPropTag,
uint32_t  MId,
struct BinaryArray_r *  lpEntryIds 
)

Modifies the values of a specific property of a specific row in the address book. This function only applies only to rows that support the PT_OBJECT Property Type.

Parameters:
nspi_ctx pointer to the NSPI connection context
Delete boolean value defining whether the server must remove all values specified by the input parameter lpEntryIDs from the property specified by ulPropTag
ulPropTag property tag of the property the client wishes to modify
MId the MId of the address book object
lpEntryIds array of BinaryArray_r structures intended to be modified or deleted
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error

References nspi_context::handle, nspi_context::mem_ctx, OPENCHANGE_RETVAL_IF, PT_OBJECT, and nspi_context::rpc_connection.

_PUBLIC_ enum MAPISTATUS nspi_ModProps ( struct nspi_context nspi_ctx,
TALLOC_CTX *  mem_ctx,
uint32_t  MId,
struct SPropTagArray *  pPropTags,
struct SRow *  pRow 
)

Modify the properties of an object in the address book

Parameters:
nspi_ctx pointer to the NSPI connection context
mem_ctx pointer to the memory context
MId the MId of the address book object
pPropTags pointer to the list of properties to be modified on the object
pRow Contains an address book row
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error

References nspi_context::handle, OPENCHANGE_RETVAL_IF, nspi_context::pStat, and nspi_context::rpc_connection.

_PUBLIC_ enum MAPISTATUS nspi_QueryColumns ( struct nspi_context nspi_ctx,
TALLOC_CTX *  mem_ctx,
bool  WantUnicode,
struct SPropTagArray **  ppColumns 
)

Returns a list of all the properties the NSPI server is aware off.

Parameters:
nspi_ctx pointer to the NSPI connection context
mem_ctx pointer to the memory context
WantUnicode whether we want UNICODE properties or not
ppColumns pointer on pointer to a property tag array
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error.

References nspi_context::handle, OPENCHANGE_RETVAL_IF, and nspi_context::rpc_connection.

_PUBLIC_ enum MAPISTATUS nspi_QueryRows ( struct nspi_context nspi_ctx,
TALLOC_CTX *  mem_ctx,
struct SPropTagArray *  pPropTags,
struct SPropTagArray *  MIds,
uint32_t  count,
struct SRowSet **  ppRows 
)

Returns a number of Rows from a specified table.

Parameters:
nspi_ctx pointer to the NSPI connection context
mem_ctx pointer to the memory context
pPropTags pointer to the list of proptags that the client requires to be returned for each row.
MIds pointer to a list of values representing an Explicit table
count the number of rows requested
ppRows pointer on pointer to the the rows returned by the server
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error

References nspi_context::handle, OPENCHANGE_RETVAL_IF, nspi_context::pStat, and nspi_context::rpc_connection.

Referenced by GetGALTable(), and ProcessNetworkProfile().

_PUBLIC_ enum MAPISTATUS nspi_ResolveNames ( struct nspi_context nspi_ctx,
TALLOC_CTX *  mem_ctx,
const char **  usernames,
struct SPropTagArray *  pPropTags,
struct SRowSet ***  pppRows,
struct SPropTagArray ***  pppMIds 
)

Takes a set of string values in an 8-bit character set and performs ANR on those strings

Parameters:
nspi_ctx pointer on the NSPI connection context
mem_ctx pointer to the memory context
usernames pointer on pointer to the list of values we want to perform ANR on
pPropTags pointer on the property tags list we want for each row returned
pppRows pointer on pointer on pointer to the rows returned by the server
pppMIds pointer on pointer on pointer to the MIds matching the array of strings
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error

References nspi_context::handle, OPENCHANGE_RETVAL_IF, nspi_context::pStat, and nspi_context::rpc_connection.

Referenced by ResolveNames().

_PUBLIC_ enum MAPISTATUS nspi_ResolveNamesW ( struct nspi_context nspi_ctx,
TALLOC_CTX *  mem_ctx,
const char **  usernames,
struct SPropTagArray *  pPropTags,
struct SRowSet ***  pppRows,
struct SPropTagArray ***  pppMIds 
)

Takes a set of string values in the Unicode character set and performs ANR on those strings

Parameters:
nspi_ctx pointer on the NSPI connection context
mem_ctx pointer to the memory context
usernames pointer on pointer to the list of values we want to perform ANR on
pPropTags pointer on the property tags list we want for each row returned
pppRows pointer on pointer on pointer to the rows returned by the server
pppMIds pointer on pointer on pointer to the MIds matching the array of strings
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error

References nspi_context::handle, OPENCHANGE_RETVAL_IF, nspi_context::pStat, and nspi_context::rpc_connection.

Referenced by ResolveNames().

_PUBLIC_ enum MAPISTATUS nspi_ResortRestriction ( struct nspi_context nspi_ctx,
TALLOC_CTX *  mem_ctx,
enum TableSortOrders  SortType,
struct SPropTagArray *  pInMIds,
struct SPropTagArray **  ppMIds 
)

Applies a sort order to the objects in a restricted address book container

Parameters:
nspi_ctx pointer to the NSPI connection context
mem_ctx pointer to the memory context
SortType the table sort order to use
pInMIds pointer on a list of MIds that comprise a restricted addess book container
ppMIds pointer on pointer to the returned list of MIds that comprise a restricted addess book container.

SortType can take the following values:

  1. SortTypeDisplayName
  2. SortTypePhoneticDisplayName
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error

References nspi_context::handle, OPENCHANGE_RETVAL_IF, nspi_context::pStat, and nspi_context::rpc_connection.

_PUBLIC_ enum MAPISTATUS nspi_SeekEntries ( struct nspi_context nspi_ctx,
TALLOC_CTX *  mem_ctx,
enum TableSortOrders  SortType,
struct SPropValue *  pTarget,
struct SPropTagArray *  pPropTags,
struct SPropTagArray *  pMIds,
struct SRowSet **  pRows 
)

Searches for and sets the logical position in a specific table to the first entry greater than or equal to a specified value. Optionally, it might also return information about rows in the table.

Parameters:
nspi_ctx pointer to the NSPI connection context
mem_ctx pointer to the memory context
SortType the table sort order to use
pTarget SPropValue struct holding the value being sought
pPropTags pointer to an array of property tags of columns that the client wants to be returned for each row returned.
pMIds pointer to a list of Mid that comprise a restricted address book container
pRows pointer to pointer to a SRowSet structure holding the rows returned by the server

SortType can take the following values:

  1. SortTypeDisplayName
  2. SortTypePhoneticDisplayName

If pTarget property tag is not set accordingly to SortType, the function returns MAPI_E_INVALID_PARAMETER. Possible values are:

  1. SortType set to SortTypeDisplayName and pTarget property tag set to PR_DISPLAY_NAME or PR_DISPLAY_UNICODE
  2. SortType set to SortTypePhoneticDisplayName and pTarget property tag set to PR_EMS_AB_PHONETIC_DISPLAY_NAME or PR_EMS_AB_PHONETIC_DISPLAY_NAME_UNICODE
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error

References nspi_context::handle, OPENCHANGE_RETVAL_IF, PR_DISPLAY_NAME, PR_DISPLAY_NAME_UNICODE, PR_EMS_AB_PHONETIC_DISPLAY_NAME, PR_EMS_AB_PHONETIC_DISPLAY_NAME_UNICODE, nspi_context::pStat, and nspi_context::rpc_connection.

_PUBLIC_ enum MAPISTATUS nspi_unbind ( struct nspi_context nspi_ctx  ) 

Destroys the context handle

Parameters:
nspi_ctx pointer to the NSPI connection context
Returns:
return 1 on success or 2 if the input context is NULL

References nspi_context::handle, MAPI_STATUS_IS_OK, nspi_context::mem_ctx, OPENCHANGE_RETVAL_IF, and nspi_context::rpc_connection.

Referenced by nspi_disconnect_dtor().

_PUBLIC_ enum MAPISTATUS nspi_UpdateStat ( struct nspi_context nspi_ctx,
TALLOC_CTX *  mem_ctx,
uint32_t *  plDelta 
)

Updates the STAT block representing position in a table to reflect positioning changes requested by the client.

Parameters:
nspi_ctx pointer to the NSPI connection context
mem_ctx pointer to the memory context
plDelta pointer to an unsigned long indicating movement within the address book container specified by the input parameter pStat.
Returns:
MAPI_E_SUCCESS on success, otherwise MAPI error

References nspi_context::handle, OPENCHANGE_RETVAL_IF, nspi_context::pStat, and nspi_context::rpc_connection.


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/