Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

Open Directory Reference

Framework
DirectoryService
Declared in
DirServices.h
DirServicesTypes.h
DirServicesUtils.h
ImageCodec.k.h
ImageCompression.k.h
Companion guides

Overview

This document describes the Open Directory functions, constants and data types for retrieving information stored in directories.

Functions by Task

Open Directory Client Functions

Open Directory Plug-in Functions

Functions

dsAddAttribute

Adds an attribute to a record.

tDirStatus dsAddAttribute (
   tRecordReference inRecordReference,
   tDataNodePtr inNewAttribute,
   tAccessControlEntryPtr inNewAttributeAccess,
   tDataNodePtr inFirstAttributeValue
);

Parameters
inRecordReference

On input, a value of type tRecordReference obtained by previously calling dsOpenRecord or dsCreateRecordAndOpen that represents the record to which an attribute is to be added.

inNewAttribute

On input, a value of type tDataNodePtr that points to a tDataNode structure allocated by calling dsDataNodeAllocateBlock or dsDataNodeAllocateString that contains the name of the attribute that is to be added.

inNewAttributeAccess

Reserved for this release. On input, set inNewAttributeAccess to NULL.

inFirstAttributeValue

On input, a value of type tDataNodePtr that points to a tDataNode structure allocated by calling dsDataNodeAllocateBlock or dsDataNodeAllocateString that contains the value of the attribute that is to be added. If you don’t want to set a value, this parameter can be NULL.

function result

A value of type tDirStatus indicating success (eDSNoErr) or an error. For a list of possible result codes, see “Result Codes.”

Discussion

This function adds to the specified record an attribute having the name specified by the inNewAttribute parameter and the value pointed to by the inFirstAttributeValue parameter.

To change the value of an attribute, call dsSetAttributeValue or dsSetAttributeValues.

Availability
Declared In
DirServices.h

dsAddAttributeValue

Adds a value to an attribute.

tDirStatus dsAddAttributeValue (
   tRecordReference inRecordReference,
   tDataNodePtr inAttributeType,
   tDataNodePtr inAttributeValue
);

Parameters
inRecordReference

On input, value of type tRecordReference obtained by previously calling dsOpenRecord that represents the record having an attribute to which a value is to be appended.

inAttributeType

On input, a value of type tDataNodePtr that points to a tDataNode structure allocated by calling dsDataNodeAllocateBlock or dsDataNodeAllocateString that contains the type of the attribute to which a value is to be added.

inAttributeValue

On input, a value of type tDataNodePtr that points to a tDataNode structure allocated by calling dsDataNodeAllocateBlock or dsDataNodeAllocateString that contains the value that is to be added.

function result

A value of type tDirStatus indicating success (eDSNoErr) or an error. For a list of possible result codes, see “Result Codes.”

Discussion

This function adds the specified value to the specified attribute. The attribute must be capable of having more than one value.

To change the value of an attribute, call dsSetAttributeValue or dsSetAttributeValues.

Availability
Declared In
DirServices.h

dsAddChildPIDToReference

Allows the specified process to use a node reference.

tDirStatus dsAddChildPIDToReference (
   tDirReference inDirRef,
   SInt32 inValidChildPID,
   UInt32 inValidAPIReferenceToGrantChild
);

Parameters
inDirRef

A value of type tDirReference obtained by previously calling dsOpenDirService that identifies the Open Directory session.

inValidChildPID

A value of type long that specifies the child process ID that is to be granted permission to use the Open Directory reference specified by inDirReference.

inValidAPIReferenceToGrantChild

A value of type unsigned long containing a node reference obtained by previously calling dsOpenDirNode.

function result

A value of type tDirStatus indicating success (eDSNoErr) or an error. For a list of possible result codes, see “Result Codes.”

Discussion

This function allows the child process specified by inValidChildPID to use the node reference specified by the inValidAPIReferenceToGrantChild parameter. Calling this function allows a child process that your application forks to use a node reference that the parent process has already acquired.

Availability
Declared In
DirServices.h

dsAllocAttributeValueEntry

Allocates an attribute value entry structure having the specified attribute value.

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

Parameters
inDirRef

On input, a value of type tDirReference obtained by calling dsOpenDirService representing the Open Directory session that is to be associated with the attribute value entry structure, or zero.

inAttrValueID

On input, a value of type unsigned long containing an attribute value ID.

inAttrValueData

On input, a pointer an arbitrary value containing the value that is to be incorporated in the attribute value entry structure as an attribute value.

inAttrValueDataLen

On input, the length of valid data in the value pointed to by inAttrValueData.

function result

A value of type tAttributeEntryPtr that points to the new tAttributeValueEntry structure.

Discussion

This utility function allocates a structure of type tAttributeValueEntry and returns a pointer to it. The resulting structure can be used to set the value of the attribute identified by inAttrValueID by calling dsSetAttributeValue and passing to it the attribute value entry pointer returned by this function.

The allocated structure contains the attribute value ID specified by inAttrValueID and the attribute value pointed to by inAttrValueData.

To release the memory associated with tAttributeValueEntryPtr, call dsDeallocAttributeValueEntry.

Availability
Declared In
DirServicesUtils.h

dsAppendStringToListAlloc

Appends a string to a data list.

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

Parameters
inDirReference

On input, a value of type tDirReference obtained by calling dsOpenDirService or dsOpenDirServiceProxy representing the Open Directory session that is associated with this data list, or zero.

inDataList

On input, a value of type tDataListPtr that points to the data list to which the string specified by inCString is to be appended.

inCString

On input, a pointer to a null-terminated string containing the value in UTF-8 format that is to be appended to the data list.

function result

A value of type tDirStatus indicating success (eDSNoErr) or an error. For a list of possible result codes, see “Result Codes.”

Discussion

This utility function appends a string to a data list.

Availability
Declared In
DirServicesUtils.h

dsBuildFromPath

Builds a data list from a pathname.

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

Parameters
inDirReference

On input, a value of type tDirReference obtained by calling dsOpenDirService or dsOpenDirServiceProxy that represents the Open Directory session for which the data list is to be built, or zero.

inPathCString

On input, a pointer to a null-terminated string containing a pathname in UTF-8 format.

inPathSeparatorCString

On input, a pointer to a null-terminated string containing the character that delimits the components of the pathname pointed to by inPathCString.

function result

A value of type tDataListPtr that points to the new data list.

Discussion

This utility function uses a pathname to build a null-terminated data list and returns a pointer to it. Many Open Directory functions take a pointer to a data list as a parameter. For example, you can pass the resulting data list pointer as a parameter to dsOpenDirNode.

When you no longer need the data list, call dsDataListDeallocate to release the memory associated with it. If the data list is a heap-based data list, you also need to call free().

Availability
Declared In
DirServicesUtils.h

dsBuildListFromNodesAlloc

Fills in a previously allocated data list using one or more data nodes.

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

Parameters
inDirReference

On input, a value of type tDirReference obtained by calling dsOpenDirService or dsOpenDirServiceProxy representing the Open Directory session that is associated with the specified data list, or zero.

inDataList

On input, a value of type tDataListPtr that points to a data list allocated by calling dsDataListAllocate.

in1stDataNodePtr

On input, a value of type tDataNodePtr that points to a data node containing data in UTF-8 format. The in1stDataNodePtr parameter may be followed by one or more parameters of type tDataNodePtr, each pointing to a data node. Each data node may have been allocated by calling dsDataNodeAllocateBlock or dsDataNodeAllocateString.

function result

A value of type tDirStatus indicating success (eDSNoErr) or an error. For a list of possible result codes, see “Result Codes.”

Discussion

This utility function uses information from one or more data nodes to fill in a previously allocated data list. The resulting data list is null-terminated.

When you no longer need the data list, call dsDataListDeallocate to release the memory associated with it. If the data list is a heap-based data list, you also need to call free().

Availability
Declared In
DirServicesUtils.h

dsBuildListFromPathAlloc

Builds a data list from a pathname using a data list that has already been allocated.

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

Parameters
inDirReference

On input, a value of type tDirReference obtained by calling dsOpenDirService or dsOpenDirServiceProxy that represents the Open Directory session for which the data list is to be built, or zero.

inDataList

On input, a value of type tDataListPtr that points to a data list allocated by calling dsDataListAllocate.

inPathCString

On input, a pointer to a null-terminated string containing a pathname in UTF-8 format.

inPathSeparatorCString

On input, a pointer to a null-terminated string containing the character that delimits the components of the pathname pointed to by inPathCString.

function result

A value of type tDirStatus indicating success (eDSNoErr) or an error. For a list of possible result codes, see “Result Codes.”

Discussion

This utility function uses previously allocated data list and a pathname to build a null-terminated data list and returns a pointer to it. Many Open Directory functions take a pointer to a data list as a parameter. For example, you can pass the resulting data list pointer as a parameter to dsOpenDirNode.

When you no longer need the data list, call dsDataListDeallocate to release the memory associated with it. If the data list is a heap-based data list, you also need to call free().

Availability
Declared In
DirServicesUtils.h

dsBuildListFromStrings

Builds a data list from strings.

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

Parameters
inDirReference

On input, a value of type tDirReference obtained by calling dsOpenDirService or dsOpenDirServiceProxy representing the Open Directory session for which the data list is being built, or zero.

in1stCString

On input, a pointer to a null-terminated string containing data in UTF-8 format that is to be added to the data list. The in1stCString parameter may be followed by one or more parameters of type char *, each pointing to a C string containing data in UTF-8 format that is to be added to the data list.

function result

A value of type tDataListPtr that points to the tDataList structure that has been created.

Discussion

This utility function uses one or more null-terminated strings to build a data list and returns a pointer to it.

When you no longer need the data list, call dsDataListDeallocate t o release the memory associated with it. If the data list is a heap-based data list, you also need to call free().

Availability
Declared In
DirServicesUtils.h

dsBuildListFromStringsAlloc

Fills in a previously allocated data list using data from strings.

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

Parameters
inDirReference

On input, a value of type tDirReference obtained by calling dsOpenDirService or dsOpenDirServiceProxy representing the Open Directory session that is associated with the specified data list, or zero.

inDataList

On input, a value of type tDataListPtr that points to a data list allocated by calling dsDataListAllocate.

in1stCString

On input, a pointer to a character string that specifies the name of a data node to add to the data list. The in1stCString parameter may be followed by one or more additional parameters of type char *, each pointing to a C string containing data that is to be added to the data list.

function result

A value of type tDirStatus indicating success (eDSNoErr) or an error. For a list of possible result codes, see “Result Codes.”

Discussion

This utility function fills in a data list using the data in UTF-8 format contained by the specified null-terminated strings.

When you no longer need the data list, call dsDataListDeallocate to release the memory associated with it. If the data list is a heap-based data list, you also need to call free().

Availability
Declared In
DirServicesUtils.h

dsBuildListFromStringsAllocV

Fills in a previously allocated data list using data from a list of type va_list.

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

Parameters
inDirRef

On input, a value of type tDirReference obtained by calling dsOpenDirService representing the Open Directory session that is associated with the specified data list, or zero.

inDataList

On input, a pointer to a value of type tDataList allocated by calling dsDataListAllocate.

in1stCString

On input, a pointer to a character string that specifies the name of a data node to add to the data list. The in1stCString parameter may be followed by one or more additional parameters of type char *, each pointing to a C string containing data that is to be added to the data list.

args

On input, a value of type va_list with additional C strings containing data that is to be added to the date list.

function result

A value of type tDirStatus indicating success (eDSNoErr) or an error. For a list of possible result codes, see “Result Codes.”

Discussion

This utility function fills in a data list using the data in UTF-8 format contained by the specified null-terminated string and additional strings in the va_list parameter.

When you no longer need the data list, call dsDataListDeallocate to release the memory associated with it.

Availability
Declared In
DirServicesUtils.h

dsCloseAttributeList

Disposes of an attribute list reference.

tDirStatus dsCloseAttributeList (
   tAttributeListRef inAttributeListRef
);

Parameters
inAttributeListRef

On input, a value of type tAttributeListRef obtained by a previous call to dsGetDirNodeInfo or dsGetRecordEntry.

function result

A value of type tDirStatus indicating success (eDSNoErr) or an error. For a list of possible result codes, see “Result Codes.”

Discussion

This function disposes of an attribute list reference that was obtained by a previous call to dsGetDirNodeInfo or dsGetRecordList. You should dispose of an attribute list reference when it is no longer needed.

Availability
Declared In
DirServices.h

dsCloseAttributeValueList

Disposes of an attribute value list reference.

tDirStatus dsCloseAttributeValueList (
   tAttributeValueListRef inAttributeValueListRef
);

Parameters
inAttributeValueListRef

On input, a value of type tAttributeValueListRef that was obtained by a previous call to dsGetAttributeEntry.

function result

A value of type tDirStatus indicating success (eDSNoErr) or an error. For a list of possible result codes, see “Result Codes.”

Discussion

This function disposes of an attribute value list reference that was obtained by a previous call to dsGetAttributeEntry. You should dispose of an attribute value list reference when it is no longer needed.

Availability
Declared In
DirServices.h

dsCloseDirNode

Closes a session with a node.

tDirStatus dsCloseDirNode (
   tDirNodeReference inDirNodeReference
);

Parameters
inDirNodeReference

On input, a value of type tDirNodeReference obtained by previously calling dsOpenDirNode or dsOpenDirServiceProxy that identifies the node session that is to be closed.

function result

A value of type tDirStatus indicating success (eDSNoErr) or an error. such as eDSInvalidReference if the tDirNodeReference is invalid. For a list of other possible result codes, see “Result Codes.”

Discussion

This function closes a session with the node represented by inDirNodeReference.

When the session with the node is closed, inDirNodeReference becomes invalid and cannot be used with any other Open Directory function that takes a node reference as a parameter. Any references that were created with inDirNodeReference as a parameter, such as record references, attribute list references, and attribute value references become invalid when the session represented by inDirNodeReference is closed.

Availability
Declared In
DirServices.h

dsCloseDirService

Closes an Open Directory session.

tDirStatus dsCloseDirService (
   tDirReference inDirReference
);

Parameters
inDirReference

A value of type tDirReference obtained by previously calling dsOpenDirService or dsOpenDirServiceProxy that identifies the Open Directory session that is to be closed.

function result

A value of type tDirStatus indicating success (eDSNoErr) or an error. For a list of possible result codes, see “Result Codes.”

Discussion

This function closes the Open Directory session represented by inDirReference. Continuation data and child references, such as node, record, attribute list, and attribute value list references, that were created using inDirReference become invalid when the session is closed and are released implicitly when this function is called. You must deallocate data lists, data nodes, and data buffers yourself by calling dsDataListDeallocate, dsDataNodeDeAllocate, and dsDataBufferDeAllocate respectively.

Availability
Declared In
DirServices.h

dsCloseRecord

Closes a open record.

tDirStatus dsCloseRecord (
   tRecordReference inRecordReference
);

Parameters
inRecordReference

On input, value of type tRecordReference obtained by previously calling dsOpenRecord that identifies the record that is to be closed.

function result

A value of type tDirStatus indicating success (eDSNoErr) or an error. For a list of possible result codes, see “Result Codes.”

Discussion

This function closes a record that was previously opened by calling dsOpenRecord. Closing the record invalidates the inRecordReference parameter so that it cannot be used as a parameter to any other Open Directory function. Any pending changes to the record are flushed at this time.

Availability
Declared In
DirServices.h

dsCreateRecord

Creates a record.

tDirStatus dsCreateRecord (
   tDirNodeReference inDirNodeReference,
   tDataNodePtr inRecordType,
   tDataNodePtr inRecordName
);

Parameters
inDirNodeReference

On input, a value of type tDirNodeReference, obtained by previously calling dsOpenDirNode that identifies the node in which the record is to be created.

inRecordType

On input, a value of type tDataNodePtr that points to a tDataNode structure allocated by calling dsDataNodeAllocateBlock or dsDataNodeAllocateString that contains the record type for the record that is to be created. For record type constants, see Standard Record Types.

inRecordName

On input, a value of type tDataNodePtr that points to a tDataNode structure allocated by calling dsDataNodeAllocateBlock or dsDataNodeAllocateString that contains the name in UTF-8 format for the record that is to be created.

function result

A value of type tDirStatus indicating success (eDSNoErr) or an error. For a list of possible result codes, see “Result Codes.”

Discussion

This function creates in the node represented by inDirNodeReference a record having the name and type specified by the data nodes pointed to by the inRecordType and inRecordName parameters.

To add attributes to the new record, call dsAddAttribute.

This function does not open the created record. To create a record and open it in one step, call dsCreateRecordAndOpen.

Availability
Declared In
DirServices.h

dsCreateRecordAndOpen

Creates a record and opens it.

tDirStatus dsCreateRecordAndOpen (
   tDirNodeReference inDirNodeReference,
   tDataNodePtr inRecordType,
   tDataNodePtr inRecordName,
   tRecordReference *outRecordReference
);

Parameters
inDirNodeReference

On input, a value of type tDirReference, obtained by calling dsOpenDirNode that identifies the node in which the record is to be created.

inRecordType

On input, a value of type tDataNodePtr that points to a tDataNode structure allocated by calling dsDataNodeAllocateBlock or dsDataNodeAllocateString that contains the record type for the record that is to be created. For record type constants, see Standard Record Types.

inRecordName

On input, a value of type tDataNodePtr that points to a tDataNode structure allocated by calling dsDataNodeAllocateBlock or dsDataNodeAllocateString that contains the name in UTF-8 format for the record that is to be created.

outRecordReference

On input, a pointer to a value of type tRecordReference. On output, outRecordReference points to a record reference for the created record and that can be provided as a parameter to Open Directory functions that operate on opened records.

function result

A value of type tDirStatus indicating success (eDSNoErr) or an error. For a list of possible result codes, see “Result Codes.”

Discussion

This function creates a record and opens it. On output the outRecordReference parameter is a reference to the newly created record that can be passed as a parameter to Open Directory functions that operate on open records.

To add attributes to the new record, call dsAddAttribute.

To create a record without opening it, call dsCreateRecord.

Availability
Declared In
DirServices.h

dsDataBufferAllocate

Allocates an Open Directory data buffer.

tDataBufferPtr dsDataBufferAllocate (
   tDirReference inDirReference,
   UInt32 inBufferSize
);

Parameters
inDirReference

On input, a value of type tDirReference obtained by calling dsOpenDirService or dsOpenDirServiceProxy, or zero.

inBufferSize

On input, a value of type unsigned long that specifies the length of the buffer that is to be allocated.

function result

A value of type tDataBufferPtr that points to the allocated tDataBuffer structure.

Discussion

The utility function allocates an Open Directory data buffer of the specified size and returns a value that points to the allocated buffer.

Open Directory data buffers are used by many Open Directory functions to exchange information between an Open Directory client application and an Open Directory plug-in.

When you no longer need the data buffer, call dsDataBufferDeAllocate to deallocate the memory that is associated with it.

Availability
Declared In
DirServicesUtils.h

dsDataBufferDeAllocate

Deallocates an Open Directory data buffer.

tDirStatus dsDataBufferDeAllocate (
   tDirReference inDirReference,
   tDataBufferPtr inDataBufferPtr
);

Parameters
inDirReference

On input, a value of type tDirReference obtained by calling dsOpenDirService or dsOpenDirServiceProxy for which a data buffer is to be deallocated, or zero.

inDataBufferPtr

A value of type tDataBufferPtr that points to the tDataBuffer structure that is to be deallocated.

function result

A value of type tDirStatus indicating success (eDSNoErr) or an error. For a list of possible result codes, see “Result Codes.”

Discussion

This utility function appends the specified string to the specified data list.

Availability
Declared In
DirServicesUtils.h

dsDataListAllocate

Allocates a data list.

tDataListPtr dsDataListAllocate (
   tDirReference inDirReference
);

Parameters
inDirReference

On input, a value of type tDirReference obtained by calling dsOpenDirService or dsOpenDirServiceProxy representing the Open Directory session for which the data list is to be allocated, or zero.

function result

A value of type tDataListPtr that points to the allocated tDataList structure. If this function cannot allocate the data list, it returns NULL.

Discussion

This utility function allocates an empty data list and returns a value of type tDataListPtr that points to it.

Many Open Directory functions return information in a data list and receive information in a data list, such as dsFindDirNodes, dsGetDirNodeInfo, dsGetRecordList, and dsDoAttributeValueSearch.

To add data to the data list, call dsBuildListFromNodesAlloc or dsBuildListFromStringsAlloc.

When you no longer need the data list, call dsDataListDeallocate to release the memory associated with it.

Availability
Declared In
DirServicesUtils.h

dsDataListCopyList

Copies a data list.

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

Parameters
inDirReference

On input, a value of type tDirReference obtained by calling dsOpenDirService or dsOpenDirServiceProxy representing the Open Directory session that is associated with the specified data list, or zero.

inDataListSource

On input, a pointer to a tDataList structure for the data list that is to be copied.

function result

A value of type tDataListPtr that points to the copy of the data list. If this function cannot copy the list, it returns NULL.

Discussion

This utility function copies a data list and returns a pointer to the copy of the data list.

Availability
Declared In
DirServicesUtils.h

dsDataListDeallocate

Deallocates a data list.

tDirStatus dsDataListDeallocate (
   tDirReference inDirReference,
   tDataListPtr inDataList
);

Parameters
inDirReference

On input, a value of type tDirReference obtained by calling dsOpenDirService or dsOpenDirServiceProxy representing the Open Directory session for which the data list is to be deallocated, or zero.

inDataList

On input, a value of type tDataListPtr pointing to the tDataList structure that is to be deallocated.

function result

A value of type tDirStatus indicating success (eDSNoErr) or an error. For a list of possible result codes, see “Result Codes.”

Discussion

This utility function deallocates a data list previously created by calling dsBuildListFromNodesAlloc, dsBuildFromPath, dsBuildListFromStrings, or dsDataListCopyList.

This utility function does not clean up the header structure associated with the inDataList parameter, so if the inDataList parameter is a true pointer and not the address of a stack variable, you need to call free(inDataList).

Availability
Declared In
DirServicesUtils.h

dsDataListDeleteThisNode

Deletes a data node from a data list.

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

Parameters
inDirReference

On input, a value of type tDirReference obtained by calling dsOpenDirService or dsOpenDirServiceProxy representing the Open Directory session that is associated with the specified data list, or zero.

inDataList

On input, a value of type tDataListPtr pointing to the data list from which a data node is to be removed.

inNodeIndex

On input, a value of type unsigned long that identifies the data node to remove. Set inNodeIndex to 1 to remove the first node. Set inNodeIndex to 2 to remove the second node, and so on.

function result

A value of type tDirStatus indicating success (eDSNoErr) or an error. For a list of possible result codes, see “Result Codes.”

Discussion

This utility function removes a data node from a data list. The inNodeIndex parameter specifies the index of the data node that is to be removed.

Availability
Declared In
DirServicesUtils.h

dsDataListGetNodeAlloc

Gets a data node from a data list.

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

Parameters
inDirReference

On input, a value of type tDirReference obtained by calling dsOpenDirService or dsOpenDirServiceProxy representing the Open Directory session that is associated with the specified data list, or zero.

inDataListPtr

On input, a pointer to a tDataList structure of the data list from which a data node is to be obtained.

inNodeIndex

On input, a value of type unsigned long that identifies the data node to obtain. Set inNodeIndex to 1 to get the first node. Set inNodeIndex to 2 to get the second node, and so on.

outDataNode

On output, a value of type tDataNodePtr that points to the data node obtained from the data list.

function result

A value of type tDirStatus indicating success (eDSNoErr) or an error. For a list of possible result codes, see “Result Codes.”

Discussion

This utility function obtains a data node from a data list.

Availability
Declared In
DirServicesUtils.h

dsDataListGetNodeCount

Gets the number of data nodes in a data list.

UInt32 dsDataListGetNodeCount (
   const tDataList *inDataList
);

Parameters
inDataListPtr

On input, a pointer to a value of type tDataList containing the data nodes that are to be counted.

function result

The number of data nodes in the data list or an error code. For a list of possible result codes, see “Result Codes.”

Discussion

This utility function returns the number of data nodes in a data list.

Availability
Declared In
DirServicesUtils.h

dsDataListInsertAfter

Inserts a data node in a data list.

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

Parameters
inDirReference

On input, a value of type tDirReference obtained by calling dsOpenDirService or dsOpenDirServiceProxy representing the Open Directory session that is associated with the specified data list, or zero.

inDataList

On input, a value of type tDataListPtr pointing to a data list containing a list of nodes.

inInsertDataNode

On input, a value of type tDataNodePtr pointing to a data node.

inNodeIndex

On input, a value of type const unsigned long that specifies the data node in the list after which the data node specified by inInsertDataNode is to be inserted. If inNodeIndex is zero, the data node is inserted at the beginning of the data list.

function result

A value of type tDirStatus indicating success (eDSNoErr) or an error. For a list of possible result codes, see “Result Codes.”

Discussion

This utility function inserts a node into a list of nodes in a data list.

Availability
Declared In
DirServicesUtils.h

dsDataListMergeListAfter

Merges two data lists.

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

Parameters
inTargetList

On input, a value of type tDataListPtr pointing to a data list containing data nodes. When this function returns, inTargetList contains the data nodes it contained before this function was called as well as the data nodes contained by the data list pointed to by inSourceList.

inSourceList

On input, a value of type tDataListPtr pointing to a data list containing data nodes that are to be merged with the data nodes in the data list specified by inTargetList.

inNodeIndex

On input, a value of type const unsigned long that specifies the index of the node in the data list pointed to by inTargetList after which the data nodes in the list pointed to by inSourceList are to be inserted. If inNodeIndex is zero, the data nodes are inserted at the beginning of the list.

function result

A value of type tDirStatus indicating success (eDSNoErr) or an error. For a list of possible result codes, see “Result Codes.”

Discussion

This utility function merges two data lists. The data nodes in the data list pointed by the inSourceList parameter are merged with the data nodes in the data list pointed to by the inTargetList parameter after the data node indicated by the inNodeIndex parameter.

Availability
Declared In
DirServicesUtils.h

dsDataNodeAllocateBlock

Allocates an Open Directory data node.

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

Parameters
inDirReference

On input, a value of type tDirReference obtained by calling dsOpenDirService or dsOpenDirServiceProxy representing the Open Directory session for which the data node is to be allocated, or zero.

inDataNodeSize

On input, a value of type unsigned long that specifies the size of inDataNodeBuffer.

inDataNodeLength

On input, a value of type unsigned long that specifies the length of valid data in inDataNodeBuffer.

inDataNodeBuffer

On input, a value of type tBuffer containing the value the data node is to contain.

function result

A value of type tDataNodePtr that points to the allocated data node and that can be passed as a parameter to Open Directory functions that require such a value as a parameter. If this function cannot allocate the data node, it returns NULL.

Discussion

This utility function allocates an Open Directory data node and returns a pointer to it. Use the data node as a convenient way to pass data, such as record names and authentication types, to Open Directory functions.

To release the memory associated with a data node, call dsDataNodeDeAllocate.

To use a C string to allocate a data node, call dsDataNodeAllocateString.

Availability
Declared In
DirServicesUtils.h

dsDataNodeAllocateString

Allocates an Open Directory data node using a string.

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

Parameters
inDirReference

On input, a value of type tDirReference obtained by calling dsOpenDirService or dsOpenDirServiceProxy representing the Open Directory session for which the data node is to be allocated. The value of this parameter is actually ignored in Mac OS X.

inCString

A pointer to a value of type char that specifies the value the data node is to contain.

function result

A value of type tDataNodePtr that points to the allocated data node and that can be passed as a parameter to Open Directory functions that require such a value as a parameter. If this function cannot allocate the data node, it returns NULL.

Discussion

This utility function uses a C string to allocate an Open Directory data node and returns a pointer to the allocated data node. Use the data node as a convenient way to pass data, such as record names and authentication types, to Open Directory functions.

To release the memory associated with a data node, call dsDataNodeDeAllocate.

Availability
Declared In
DirServicesUtils.h

dsDataNodeDeAllocate

Deallocates a data node.

tDirStatus dsDataNodeDeAllocate (
   tDirReference inDirReference,
   tDataNodePtr inDataNodePtr
);

Parameters
inDirReference

On input, a value of type tDirReference obtained by calling dsOpenDirService or dsOpenDirServiceProxy, or zero.

inDataNodePtr

On input, a value of type tDataNodePtr that points to the tDataBuffer structure that is to be deallocated.

function result

A value of type tDirStatus indicating success (eDSNoErr) or an error. For a list of possible result codes, see “Result Codes.”

Discussion

This utility function deallocates an Open Directory data node that was created by previously calling dsDataNodeAllocateBlock or dsDataNodeAllocateString.

Availability
Declared In
DirServicesUtils.h

dsDataNodeGetLength

Gets the length of valid data in a data node’s buffer.

UInt32 dsDataNodeGetLength (
   tDataNodePtr inDataNodePtr
);

Parameters
inDataNodePtr

On input, a value of type tDataNodePtr that points to the data node for which the length of valid data in the data node’s buffer is to be obtained.

function result

A value of type unsigned long that contains the length of valid data in the data node’s buffer. If this function cannot obtain the length, it returns zero.

Discussion

This utility function gets the length of valid data in the buffer of the data node pointed to by inDataNodePtr.

Availability
Declared In
DirServicesUtils.h

dsDataNodeGetSize

Gets the size of a data node’s buffer.

UInt32 dsDataNodeGetSize (
   tDataNodePtr inDataNodePtr
);

Parameters
inDataNodePtr

On input, a value of type tDataNodePtr that points to the tDataBuffer structure whose buffer size is to be obtained.

function result

A value of type unsigned long that contains the size of the buffer. If this function cannot obtain the buffer’s size, it returns zero.

Discussion

This utility function obtains the size of a data node’s buffer.

Availability
Declared In
DirServicesUtils.h

dsDataNodeSetLength

Sets the length of valid data in a data node’s buffer.

tDirStatus dsDataNo