DirServicesUtils.h

Includes:
<stdarg.h>
<AvailabilityMacros.h>
<DirectoryService/DirServicesTypes.h>
<CoreFoundation/CoreFoundation.h>

Overview

Use the links in the table of contents to the left to access the documentation.


Functions

dsAllocAttributeValueEntry
dsAllocStringsFromList
dsAppendAuthBuffer

Appends a list of items to an existing buffer.

dsAppendAuthBufferWithAuthorityAttribute

Inserts a user name with authentication authority data into an existing buffer.

dsAppendAuthBufferWithAuthorityStrings

Inserts a user name with authentication authority data into an existing buffer.

dsAppendStringToListAlloc
dsBuildFromPath
dsBuildListFromNodesAlloc
dsBuildListFromPathAlloc
dsBuildListFromStrings
dsBuildListFromStringsAlloc
dsBuildListFromStringsAllocV
dsCopyDirStatusName
dsDataBufferAllocate
dsDataBufferDeAllocate
dsDataListAllocate
dsDataListCopyList
dsDataListDeallocate
dsDataListDeAllocate
dsDataListDeleteThisNode
dsDataListGetNodeAlloc
dsDataListGetNodeCount
dsDataListInsertAfter
dsDataListMergeListAfter
dsDataNodeAllocateBlock
dsDataNodeAllocateString
dsDataNodeDeAllocate
dsDataNodeGetLength
dsDataNodeGetSize
dsDataNodeSetLength
dsDeallocAttributeEntry
dsDeallocAttributeValueEntry
dsDeallocRecordEntry
dsFillAuthBuffer

Fills a buffer with a list of items.

dsGetDataLength
dsGetPathFromList
dsGetRecordNameFromEntry
dsGetRecordTypeFromEntry
dsParseAuthAuthority
dsServiceInformationAllocate

Allocate a buffer that contains the xml plist form of a CFDictionary.

dsAllocAttributeValueEntry

tAttributeValueEntryPtr dsAllocAttributeValueEntry (
    tDirReference inDirRef, 
    UInt32 inAttrValueID, 
    void *inAttrValueData, 
    UInt32 inAttrValueDataLen ) ;

Availability
Deprecated in Mac OS X v10.6.

dsAllocStringsFromList

char** dsAllocStringsFromList(
    tDirReference inDirRef,
    const tDataList *inDataList ) ;
Discussion

Provides a char** of the strings contained within a tDataList.

Availability
Introduced in Mac OS X v10.4, but later deprecated in Mac OS X v10.6.

dsAppendAuthBuffer

Appends a list of items to an existing buffer. 

tDirStatus dsAppendAuthBuffer (
    tDataBufferPtr inOutAuthBuffer, 
    UInt32 inCount, 
    UInt32 inLen, 
    const void *inData,
    ... ) ;
Parameters
inOutAuthBuffer

pass in a preallocated buffer.

inCount

the number of length/data pairs on the stack

inLen

the length of one buffer item

inData

a pointer to inLen bytes of data

Discussion

Use this function as a convenient way to compose the buffer for calls to dsDoDirNodeAuth().

Availability
Introduced in Mac OS X v10.5, but later deprecated in Mac OS X v10.6.

dsAppendAuthBufferWithAuthorityAttribute

Inserts a user name with authentication authority data into an existing buffer. 

tDirStatus dsAppendAuthBufferWithAuthorityAttribute (
    tDirNodeReference inNodeRef, 
    tDataBufferPtr inRecordListBuffPtr, 
    tAttributeEntryPtr inAttributePtr, 
    tAttributeValueListRef inValueRef, 
    const char *inUserName, 
    tDataBufferPtr inOutAuthBuffer ) ;
Parameters
inNodeRef

a node reference for the record to parse

inRecordListBuffPtr

the data returned from dsGetDataList

inAttributePtr

an attribute with authentication authority data

inValueRef

the reference for the kDSNAttrAuthenticationAuthority attribute.

inUserName

the name of the user to authenticate

inOutAuthBuffer

pass in a preallocated buffer, returns with the user data appended.

Return Value

tDirStatus code

Discussion

Use this function for authentication methods that contain user or authenticator names and the authentication authority attribute has already been retrieved.

Availability
Introduced in Mac OS X v10.5, but later deprecated in Mac OS X v10.6.

dsAppendAuthBufferWithAuthorityStrings

Inserts a user name with authentication authority data into an existing buffer. 

tDirStatus dsAppendAuthBufferWithAuthorityStrings (
    const char *inUserName, 
    const char *inAuthAuthority[], 
    tDataBufferPtr inOutAuthBuffer ) ;
Parameters
inUserName

the name of the user to authenticate

inAuthAuthority

a NULL terminated array of C strings

inOutAuthBuffer

pass in a preallocated buffer, returns with the user data appended.

Return Value

tDirStatus code

Discussion

Use this function for authentication methods that contain user or authenticator names and the authentication authority attribute has already been retrieved.

Availability
Introduced in Mac OS X v10.5, but later deprecated in Mac OS X v10.6.

dsAppendStringToListAlloc

tDirStatus dsAppendStringToListAlloc (
    tDirReference inDirReferences, 
    tDataListPtr inDataList, 
    const char * inCString ) ;

Availability
Deprecated in Mac OS X v10.6.

dsBuildFromPath

tDataListPtr dsBuildFromPath (
    tDirReference inDirReference, 
    const char *inPathCString, 
    const char *inPathSeparatorCString ) ;

Availability
Deprecated in Mac OS X v10.6.

dsBuildListFromNodesAlloc

tDirStatus dsBuildListFromNodesAlloc (
    tDirReference inDirReferences, 
    tDataListPtr inDataList, 
    tDataNodePtr in1stDataNodePtr, 
    ... ) ;

Availability
Deprecated in Mac OS X v10.6.

dsBuildListFromPathAlloc

tDirStatus dsBuildListFromPathAlloc (
    tDirReference inDirReference, 
    tDataListPtr inDataList, 
    const char *inPathCString, 
    const char *inPathSeparatorCString ) ;

Availability
Deprecated in Mac OS X v10.6.

dsBuildListFromStrings

tDataListPtr dsBuildListFromStrings (
    tDirReference inDirReference, 
    const char *in1stCString, 
    ... ) ;

Availability
Deprecated in Mac OS X v10.6.

dsBuildListFromStringsAlloc

tDirStatus dsBuildListFromStringsAlloc (
    tDirReference inDirReferences, 
    tDataListPtr inDataList, 
    const char *in1stCString, 
    ... ) ;

Availability
Deprecated in Mac OS X v10.6.

dsBuildListFromStringsAllocV

tDirStatus dsBuildListFromStringsAllocV (
    tDirReference inDirRef, 
    tDataList *inDataList, 
    const char *in1stCString, 
    va_list args ) ;

Availability
Deprecated in Mac OS X v10.6.

dsCopyDirStatusName

char* dsCopyDirStatusName (
    SInt32 inDirStatus ) ;
Discussion

Pass in the tDirStatus enum and receive the string of the enum name. Memory for the char* is the responsibility of the client and can be cleaned up using free().

Availability
Introduced in Mac OS X v10.4, but later deprecated in Mac OS X v10.6.

dsDataBufferAllocate

tDataBufferPtr dsDataBufferAllocate (
    tDirReference inDirReference, 
    UInt32 inBufferSize ) ;

Availability
Deprecated in Mac OS X v10.6.

dsDataBufferDeAllocate

tDirStatus dsDataBufferDeAllocate (
    tDirReference inDirReference, 
    tDataBufferPtr inDataBufferPtr ) ;

Availability
Deprecated in Mac OS X v10.6.

dsDataListAllocate

tDataListPtr dsDataListAllocate (
    tDirReference inDirReference ) ;

Availability
Deprecated in Mac OS X v10.6.

dsDataListCopyList

tDataListPtr dsDataListCopyList (
    tDirReference inDirReference, 
    const tDataList *inDataListSource ) ;

Availability
Deprecated in Mac OS X v10.6.

dsDataListDeallocate

tDirStatus dsDataListDeallocate (
    tDirReference inDirReference, 
    tDataListPtr inDataList ) ;
Discussion

Note that if the tDataListPtr is a heap based tDataList rather than stack based, that you must also call free() to release the memory for the head of the list after calling dsDataListDeallocate().

Availability
Deprecated in Mac OS X v10.6.

dsDataListDeAllocate

tDirStatus dsDataListDeAllocate (
    tDirReference inDirReference, 
    tDataListPtr inDataList, 
    dsBool inDeAllocateNodesFlag ) ;
Discussion

Included only for backward compatibility. Equivalent to dsDataListDeallocate.

Availability
Deprecated in Mac OS X v10.6.

dsDataListDeleteThisNode

tDirStatus dsDataListDeleteThisNode (
    tDirReference inDirReference, 
    tDataListPtr inDataList, 
    UInt32 inNodeIndex ) ;

Availability
Deprecated in Mac OS X v10.6.

dsDataListGetNodeAlloc

tDirStatus dsDataListGetNodeAlloc (
    tDirReference inDirReference, 
    const tDataList *inDataListPtr, 
    UInt32 inNodeIndex, 
    tDataNodePtr *outDataNode ) ;

Availability
Deprecated in Mac OS X v10.6.

dsDataListGetNodeCount

UInt32 dsDataListGetNodeCount (
    const tDataList *inDataList ) ;

Availability
Deprecated in Mac OS X v10.6.

dsDataListInsertAfter

tDirStatus dsDataListInsertAfter (
    tDirReference inDirReferences, 
    tDataListPtr inDataList, 
    tDataNodePtr inInsertDataNode, 
    const UInt32 inNodeIndex ) ;
Parameters
inNodeIndex

One-based index of the existing node to insert the new node after. If inNodeIndex is 0, then it is inserted at the head of the list.

Discussion

The datanode is copied into the datalist. The caller owns the original datanode, therefore must deallocate after adding to the list.

Availability
Deprecated in Mac OS X v10.6.

dsDataListMergeListAfter

tDirStatus dsDataListMergeListAfter (
    tDataListPtr inTargetList, 
    tDataListPtr inSourceList, 
    const UInt32 inNodeIndex ) ;

Availability
Deprecated in Mac OS X v10.6.

dsDataNodeAllocateBlock

tDataNodePtr dsDataNodeAllocateBlock (
    tDirReference inDirReference, 
    UInt32 inDataNodeSize, 
    UInt32 inDataNodeLength, 
    tBuffer inDataNodeBuffer ) ;

Availability
Deprecated in Mac OS X v10.6.

dsDataNodeAllocateString

tDataNodePtr dsDataNodeAllocateString (
    tDirReference inDirReference, 
    const char *inCString ) ;

Availability
Deprecated in Mac OS X v10.6.

dsDataNodeDeAllocate

tDirStatus dsDataNodeDeAllocate (
    tDirReference inDirReference, 
    tDataNodePtr inDataNodePtr ) ;

Availability
Deprecated in Mac OS X v10.6.

dsDataNodeGetLength

UInt32 dsDataNodeGetLength (
    tDataNodePtr inDataNodePtr ) ;

Availability
Deprecated in Mac OS X v10.6.

dsDataNodeGetSize

UInt32 dsDataNodeGetSize (
    tDataNodePtr inDataNodePtr ) ;

Availability
Deprecated in Mac OS X v10.6.

dsDataNodeSetLength

tDirStatus dsDataNodeSetLength (
    tDataNodePtr inDataNodePtr, 
    UInt32 inDataNodeLength ) ;

Availability
Deprecated in Mac OS X v10.6.

dsDeallocAttributeEntry

tDirStatus dsDeallocAttributeEntry (
    tDirReference inDirRef, 
    tAttributeEntryPtr inAttrEntry ) ;

Availability
Deprecated in Mac OS X v10.6.

dsDeallocAttributeValueEntry

tDirStatus dsDeallocAttributeValueEntry (
    tDirReference inDirRef, 
    tAttributeValueEntryPtr inAttrValueEntry ) ;

Availability
Deprecated in Mac OS X v10.6.

dsDeallocRecordEntry

tDirStatus dsDeallocRecordEntry (
    tDirReference inDirRef, 
    tRecordEntryPtr inRecEntry ) ;

Availability
Deprecated in Mac OS X v10.6.

dsFillAuthBuffer

Fills a buffer with a list of items. 

tDirStatus dsFillAuthBuffer (
    tDataBufferPtr inOutAuthBuffer, 
    UInt32 inCount, 
    UInt32 inLen, 
    const void *inData,
    ... ) ;
Parameters
inOutAuthBuffer

pass in a preallocated buffer to be filled.

inCount

the number of length/data pairs on the stack

inLen

the length of one buffer item

inData

a pointer to inLen bytes of data

Discussion

Use this function as a convenient way to compose the buffer for calls to dsDoDirNodeAuth().

Availability
Introduced in Mac OS X v10.5, but later deprecated in Mac OS X v10.6.

dsGetDataLength

UInt32 dsGetDataLength (
    const tDataList *inDataList );

dsGetPathFromList

char* dsGetPathFromList (
    tDirReference inDirReference, 
    const tDataList *inDataList, 
    const char *inDelimiter ) ;

Availability
Deprecated in Mac OS X v10.6.

dsGetRecordNameFromEntry

tDirStatus dsGetRecordNameFromEntry (
    tRecordEntryPtr inRecEntryPtr,
    char **outRecName ) ;
Parameters
outRecName

Used to return the record name to the client. Client is responsible for freeing the resulting string.

Availability
Deprecated in Mac OS X v10.6.

dsGetRecordTypeFromEntry

tDirStatus dsGetRecordTypeFromEntry (
    tRecordEntryPtr inRecEntryPtr,
    char **outRecType ) ;
Parameters
outRecType

Used to return the record name to the client. Client is responsible for freeing the resulting string.

Availability
Deprecated in Mac OS X v10.6.

dsParseAuthAuthority

tDirStatus dsParseAuthAuthority (
    const char *inAuthAuthority,
    char **outVersion,
    char **outAuthTag,
    char **outAuthData ) ;
Discussion

Pass in a complete authentication authority attribute format is version;tag;data retrieve version, tag, and data as separate strings Memory for the char** parameters is the responsibility of the client and can be cleaned up using free().

Availability
Introduced in Mac OS X v10.4, but later deprecated in Mac OS X v10.6.

dsServiceInformationAllocate

Allocate a buffer that contains the xml plist form of a CFDictionary. 

tDirStatus dsServiceInformationAllocate (
    CFDictionaryRef inServiceInfo, 
    UInt32 inBufferSize, 
    tDataBufferPtr *outPackedServiceInfo ) ;
Parameters
inServiceInfo

A dictionary that contains context information from a service

inBufferSize

The desired size of the buffer. It is expanded if necessary to fit the context information. The buffer must be large enough to hold the data returned by the authentication method used.

outPackedServiceInfo

A constructed buffer containing the data from inServiceInfo.

Return Value

tDirStatus code

Discussion

Services can use this function to obtain a buffer suitable for providing additional information to dsDoDirNodeAuth(). This buffer is also used to return data from an authentication method, so it needs to be large enough to handle the context information and the data returned by the authentication method.

Availability
Introduced in Mac OS X v10.5, but later deprecated in Mac OS X v10.6.

 

Last Updated: 2009-08-12