nspi.c File Reference

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

#include "libmapi/libmapi.h"
#include "libmapi/libmapi_private.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 PropertyTagArray_r **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, uint32_t ulRequested, struct PropertyRowSet_r **ppRows, struct PropertyTagArray_r **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 PropertyTagArray_r *MId, struct PropertyRowSet_r **SRowSet)
 
_PUBLIC_ enum MAPISTATUS nspi_GetSpecialTable (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, uint32_t Type, struct PropertyRowSet_r **ppRows)
 
_PUBLIC_ enum MAPISTATUS nspi_GetTemplateInfo (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, uint32_t dwFlags, uint32_t ulType, char *pDN, struct PropertyRow_r **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 PropertyRow_r *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 PropertyTagArray_r *MIds, uint32_t count, struct PropertyRowSet_r **ppRows)
 
_PUBLIC_ enum MAPISTATUS nspi_ResolveNames (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, const char **usernames, struct SPropTagArray *pPropTags, struct PropertyRowSet_r ***pppRows, struct PropertyTagArray_r ***pppMIds)
 
_PUBLIC_ enum MAPISTATUS nspi_ResolveNamesW (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, const char **usernames, struct SPropTagArray *pPropTags, struct PropertyRowSet_r ***pppRows, struct PropertyTagArray_r ***pppMIds)
 
_PUBLIC_ enum MAPISTATUS nspi_ResortRestriction (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, enum TableSortOrders SortType, struct PropertyTagArray_r *pInMIds, struct PropertyTagArray_r **ppMIds)
 
_PUBLIC_ enum MAPISTATUS nspi_SeekEntries (struct nspi_context *nspi_ctx, TALLOC_CTX *mem_ctx, enum TableSortOrders SortType, struct PropertyValue_r *pTarget, struct SPropTagArray *pPropTags, struct PropertyTagArray_r *pMIds, struct PropertyRowSet_r **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 
)

Initiates a session between a client and the NSPI server.

Parameters
parent_ctxpointer to the memory context
ppointer to the DCERPC pipe
credpointer to the user credentials
codepagethe code to set in the STAT structure
languagethe language to set in the STAT structure
methodthe 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::handle, 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_ctxpointer to the NSPI connection context
mem_ctxpointer to the memory context
MId1the first MId to compare
MId2the second MId to compare
plResultpointer 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
datageneric 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 PropertyTagArray_r **  ppMIds 
)

Maps a set of DN to a set of MId

Parameters
nspi_ctxpointer to the NSPI connection context
mem_ctxpointer to the memory context
pNamespointer to a StringsArray_r structure with the DN to map
ppMIdspointer 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_ctxpointer on the NSPI connection context
mem_ctxpointer to the memoty context
VerifyNamesboolean value defining whether the NSPI server must verify that all client specified names are recognized by the server
cNamescount of PropertyName_r entries
ppNamespointer to a PropertyName_r structure with the list of property tags supplied by the client
ppPropTagspointer 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,
uint32_t  ulRequested,
struct PropertyRowSet_r **  ppRows,
struct PropertyTagArray_r **  ppOutMIds 
)

Returns an explicit table.

Parameters
nspi_ctxpointer to the NSPI connection context
mem_ctxpointer to the memory context
pPropTagspointer to an array of property tags of columns
Filterpointer to the Restriction to apply to the table
ulRequestedThe upper limit for returned rows
ppRowspointer to pointer to a SRowSet structure holding the rows returned by the server
ppOutMIdspointer to pointer to a list of MId that comprise a restricted address book container
Returns
MAPI_E_SUCCESS on success, otherwise MAPI error. If the resulting table rows count will be greater than ulRequested, then an error MAPI_E_TABLE_TOO_BIG is returned. Note, this error can be also returned when server limits for table size are exceeded.

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

Referenced by DuplicateProfile(), and 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_ctxpointer on the NSPI connection text
mem_ctxpointer to the memory context
lpGuidthe property set about which the client is requesting information
pPropTagspointer to the proptags list
ppReturnedPropTagspointer on pointer to the list of all the proptags in the property set specified in lpGuid
ppNamespointer 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_ctxpointer to the NSPI connection context
mem_ctxpointer to the memory context
WantObjectboolean value defining whether we want the server to include properties with the type set to PT_OBJECT
dwMIdthe MId of the specified object
ppPropTagspointer 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 PropertyTagArray_r *  MId,
struct PropertyRowSet_r **  SRowSet 
)

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

Parameters
nspi_ctxpointer to the NSPI connection context
mem_ctxpointer to the memory context
pPropTagspointer to the list of property tags that the client wants to be returned
MIdpointer to the MId of the record
SRowSetpointer 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 PropertyRowSet_r **  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_ctxpointer to the NSPI connection context
mem_ctxpointer to the memory context
Typebitmap of flags defining the type of the special table
ppRowspointer 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 DuplicateProfile(), and ProcessNetworkProfile().

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

Returns information about template objects in the address book.

Parameters
nspi_ctxpointer to the NSPI memory context
mem_ctxpointer to the memory context
dwFlagsset of bit flags
ulTypespecifies the display type of the template
pDNthe DN of the template requested
ppDatapointer 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_ctxpointer to the NSPI connection context
Deleteboolean value defining whether the server must remove all values specified by the input parameter lpEntryIDs from the property specified by ulPropTag
ulPropTagproperty tag of the property the client wishes to modify
MIdthe MId of the address book object
lpEntryIdsarray 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 PropertyRow_r *  pRow 
)

Modify the properties of an object in the address book

Parameters
nspi_ctxpointer to the NSPI connection context
mem_ctxpointer to the memory context
MIdthe MId of the address book object
pPropTagspointer to the list of properties to be modified on the object
pRowContains 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_ctxpointer to the NSPI connection context
mem_ctxpointer to the memory context
WantUnicodewhether we want UNICODE properties or not
ppColumnspointer 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 PropertyTagArray_r *  MIds,
uint32_t  count,
struct PropertyRowSet_r **  ppRows 
)

Returns a number of Rows from a specified table.

Parameters
nspi_ctxpointer to the NSPI connection context
mem_ctxpointer to the memory context
pPropTagspointer to the list of proptags that the client requires to be returned for each row.
MIdspointer to a list of values representing an Explicit table
countthe number of rows requested
ppRowspointer 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(), GetGALTableCount(), and ProcessNetworkProfile().

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

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

Parameters
nspi_ctxpointer on the NSPI connection context
mem_ctxpointer to the memory context
usernamespointer on pointer to the list of values we want to perform ANR on
pPropTagspointer on the property tags list we want for each row returned
pppRowspointer on pointer on pointer to the rows returned by the server
pppMIdspointer 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 PropertyRowSet_r ***  pppRows,
struct PropertyTagArray_r ***  pppMIds 
)

Takes a set of string values in the Unicode character set and performs ambiguous name resolution (ANR) on those strings

Parameters
nspi_ctxpointer on the NSPI connection context
mem_ctxpointer to the memory context
usernamespointer on pointer to the list of values we want to perform ANR on
pPropTagspointer on the property tags list we want for each row returned
pppRowspointer on pointer on pointer to the rows returned by the server
pppMIdspointer 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 PropertyTagArray_r *  pInMIds,
struct PropertyTagArray_r **  ppMIds 
)

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

Parameters
nspi_ctxpointer to the NSPI connection context
mem_ctxpointer to the memory context
SortTypethe table sort order to use
pInMIdspointer on a list of MIds that comprise a restricted address book container
ppMIdspointer on pointer to the returned list of MIds that comprise a restricted address 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 PropertyValue_r *  pTarget,
struct SPropTagArray *  pPropTags,
struct PropertyTagArray_r *  pMIds,
struct PropertyRowSet_r **  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_ctxpointer to the NSPI connection context
mem_ctxpointer to the memory context
SortTypethe table sort order to use
pTargetPropertyValue_r struct holding the value being sought
pPropTagspointer to an array of property tags of columns that the client wants to be returned for each row returned.
pMIdspointer to a list of Mid that comprise a restricted address book container
pRowspointer 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_ctxpointer 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_ctxpointer to the NSPI connection context
mem_ctxpointer to the memory context
plDeltapointer 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/