DirServicesUtils

Overview

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.

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

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.

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.

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.

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.

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

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

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

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

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

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

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

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.

tDataBufferPtr dsDataBufferAllocate (
    tDirReference inDirReference, 
    UInt32 inBufferSize );  

tDirStatus dsDataBufferDeAllocate (
    tDirReference inDirReference, 
    tDataBufferPtr inDataBufferPtr );  

tDataListPtr dsDataListAllocate (
    tDirReference inDirReference );  

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

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().

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

Discussion

Included only for backward compatibility. Equivalent to dsDataListDeallocate.

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

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

UInt32 dsDataListGetNodeCount (
    const tDataList *inDataList );  

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.

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

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

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

tDirStatus dsDataNodeDeAllocate (
    tDirReference inDirReference, 
    tDataNodePtr inDataNodePtr );  

UInt32 dsDataNodeGetLength (
    tDataNodePtr inDataNodePtr );  

UInt32 dsDataNodeGetSize (
    tDataNodePtr inDataNodePtr );  

tDirStatus dsDataNodeSetLength (
    tDataNodePtr inDataNodePtr, 
    UInt32 inDataNodeLength );  

tDirStatus dsDeallocAttributeEntry (
    tDirReference inDirRef, 
    tAttributeEntryPtr inAttrEntry );  

tDirStatus dsDeallocAttributeValueEntry (
    tDirReference inDirRef, 
    tAttributeValueEntryPtr inAttrValueEntry );  

tDirStatus dsDeallocRecordEntry (
    tDirReference inDirRef, 
    tRecordEntryPtr inRecEntry );  

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.

UInt32 dsGetDataLength (
    const tDataList *inDataList );  

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

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.

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.

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.

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.

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-03-11