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	Open Directory Programming Guide Open Directory Plug-in Programming Guide

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

Available in Mac OS X v10.0 and later.

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

Available in Mac OS X v10.0 and later.

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

Available in Mac OS X v10.0 and later.

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

Available in Mac OS X v10.0 and later.

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

Available in Mac OS X v10.0 and later.

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

Available in Mac OS X v10.0 and later.

Related Sample Code

NetworkAuthentication

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

Available in Mac OS X v10.0 and later.

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

Available in Mac OS X v10.0 and later.

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

Available in Mac OS X v10.0 and later.

Related Sample Code

NetworkAuthentication

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

Available in Mac OS X v10.0 and later.

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

Available in Mac OS X v10.0 and later.

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

Available in Mac OS X v10.0 and later.

Related Sample Code

NetworkAuthentication

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

Available in Mac OS X v10.0 and later.

Related Sample Code

NetworkAuthentication

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

Available in Mac OS X v10.0 and later.

Related Sample Code

NetworkAuthentication

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

Available in Mac OS X v10.0 and later.

Related Sample Code

NetworkAuthentication

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

Available in Mac OS X v10.0 and later.

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

Available in Mac OS X v10.0 and later.

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

Available in Mac OS X v10.0 and later.

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

Available in Mac OS X v10.0 and later.

Related Sample Code

NetworkAuthentication

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

Available in Mac OS X v10.0 and later.

Related Sample Code

NetworkAuthentication

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

Available in Mac OS X v10.0 and later.

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

Available in Mac OS X v10.0 and later.

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

Available in Mac OS X v10.0 and later.

Related Sample Code

NetworkAuthentication

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

Available in Mac OS X v10.0 and later.

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

Available in Mac OS X v10.0 and later.

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

Available in Mac OS X v10.0 and later.

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

Available in Mac OS X v10.0 and later.

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

Available in Mac OS X v10.0 and later.

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

Available in Mac OS X v10.0 and later.

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

Available in Mac OS X v10.0 and later.

Related Sample Code

NetworkAuthentication

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

Available in Mac OS X v10.0 and later.

Related Sample Code

NetworkAuthentication

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

Available in Mac OS X v10.0 and later.

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

Available in Mac OS X v10.0 and later.

Declared In

DirServicesUtils.h

dsDataNodeSetLength

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

tDirStatus dsDataNodeSetLength (
   tDataNodePtr inDataNodePtr,
   UInt32 inDataNodeLength
);

Parameters

inDataNodePtr: On input, a value of type tDataNodePtr that points to the data node whose buffer size is to be set.
inDataNodeLength: On input, a value of type unsigned long that specifies the length of valid data in the buffer.
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 sets the length of valid data in the buffer of the data node pointed to by inDataNodePtr.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServicesUtils.h

dsDeallocAttributeEntry

Deallocates an attribute entry structure.

tDirStatus dsDeallocAttributeEntry (
   tDirReference inDirRef,
   tAttributeEntryPtr inAttrEntry
);

Parameters

inDirRef: On input, a value of type tDirReference obtained by calling dsOpenDirService representing the Open Directory session associated with the attribute entry structure that is to be deallocated, or zero.
inAttrEntry: On input, a value of type tAttributeEntryPtr that points to the tAttributeValueEntry structure that is to be deallocated.
function result: A value of type tDirStatus indicating success or failure.

Discussion

This utility function deallocates an attribute entry structure and the pointer to it that were allocated in order to call dsGetAttributeEntry or dsGetRecordAttributeInfo.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

NetworkAuthentication

Declared In

DirServicesUtils.h

dsDeallocAttributeValueEntry

Deallocates an attribute value entry structure.

tDirStatus dsDeallocAttributeValueEntry (
   tDirReference inDirRef,
   tAttributeValueEntryPtr inAttrValueEntry
);

Parameters

inDirRef: On input, a value of type tDirReference obtained by calling dsOpenDirService representing the Open Directory session associated with the attribute value entry structure that is to be deallocated, or zero.
inAttrValueEntry: On input, a value of type tAttributeValueEntryPtr that points to the tAttributeValueEntry structure that is to be deallocated.
function result: A value of type tDirStatus indicating success or failure.

Discussion

This utility function deallocates an attribute value entry structure that was previously allocated by calling dsGetAttributeValue, dsGetRecordAttributeValueByID, dsGetRecordAttributeValueByIndex, or dsGetRecordAttributeValueByValue.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

NetworkAuthentication

Declared In

DirServicesUtils.h

dsDeallocRecordEntry

Deallocates a record entry structure.

tDirStatus dsDeallocRecordEntry (
   tDirReference inDirRef,
   tRecordEntryPtr inRecEntry
);

Parameters

inDirRef: A value of type tDirReference obtained by previously calling dsOpenDirService that identifies the Open Directory session for the record entry structure that is to be deallocated, or zero.
inRecEntry: On input, a value of type tRecordEntryPtr that points to the tRecordEntry 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 the specified record entry structure that was allocated by a previous call to dsGetRecordEntry or dsGetRecordReferenceInfo.

You should always deallocate record entry structures when you no longer need them.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

NetworkAuthentication

Declared In

DirServicesUtils.h

dsDeleteRecord

Deletes a record.

tDirStatus dsDeleteRecord (
   tRecordReference inRecordReference
);

Parameters

inRecordReference: On input, a value of type tRecordReference obtained by previously calling dsOpenRecord or dsCreateRecordAndOpenthat represents the record that is to be deleted.
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 deletes the specified record. Deleting the record invalidates the record reference. Therefore, before deleting a record, be sure to call dsCloseAttributeList and dsCloseAttributeValueList to close any attribute list references and attribute value list references that may have been allocated.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServices.h

dsDoAttributeValueSearch

Searches a node for records by attribute value.

tDirStatus dsDoAttributeValueSearch (
   tDirNodeReference inDirNodeReference,
   tDataBufferPtr inOutDataBuffer,
   tDataListPtr inRecordTypeList,
   tDataNodePtr inAttributeType,
   tDirPatternMatch inPatternMatchType,
   tDataNodePtr inPattern2Match,
   UInt32 *inOutMatchRecordCount,
   tContextData *inOutContinueData
);

Parameters

inDirNodeReference: On input, a value of type tDirNodeReference, obtained by calling dsOpenDirNode, that identifies the node that is to be searched.
inOutDataBuffer: On input, a value of type tDataBufferPtr created by calling dsDataBufferAllocate that points to the tDataBuffer structure in which this function is to place search results. On output, if inOutMatchRecordCount points to a value greater than zero, call dsGetRecordEntry, dsGetAttributeEntry, and dsGetAttributeValue to get the records, attributes, and attribute values from the data buffer.
inRecordTypeList: On input, a value of type tDataListPtr pointing to a tDataList structure allocated by calling dsDataListAllocate that contains a list of record types to search. Set the record type to kDSStdRecordTypeAll to search all records. See Standard Record Types for other possible values.
inAttributeType: On input, a value of type tDataNodePtr that points to a tDataNode structure allocated by calling dsDataNodeAllocateBlock or dsDataNodeAllocateString that contains an attribute type to search for. To search all attribute types, set the attribute type to kDSAttributesAll. See the attribute constants described in the “Constants” section for other possible values.
inPatternMatchType: On input, a value of type tDirPatternMatch specifying a pattern type that controls the way in which the pattern specified by inPattern2Match is compared with attribute values. See Pattern Matching Constants for possible values. The pattern type may also be defined by the Open Directory plug-in that handles the directory service represented by inDirNodeReference.
inPattern2Match: On input, a value of type tDataNodePtr that points to a tDataNode structure allocated by calling dsDataNodeAllocateBlock or dsDataNodeAllocateString that contains the pattern to match.
inOutMatchRecordCount: On input, a pointer to a value of type unsigned long that specifies the total number of matching records to get across multiple calls to this function. Set this value to zero to get all matching records. On output, inOutRecordMatchCount points to the number of records in the data buffer pointed to by inOutDataBuffer. Once you start a series of dsDoAttributeValueSearch calls, inOutMatchRecordCount is ignored as an input parameter.
inOutContinueData: On input, a pointer to a value of type tContextData and set to NULL. On output, if the value pointed to by inOutContinueData is not NULL, get more matching records by calling this function again and pass the value pointed to by inOutContinueData. If on output inOutContinueData is NULL, there are no more records to get. If inOutContinueData is not NULL and an error occurs or you don’t want to get any more matching records, you must call dsReleaseContinueData to release the memory associated with inOutContinueData.
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 works across multiple calls to obtain a list of all records having attributes whose values match the specified pattern. Set inOutRecordMatchCount to zero to get all matching records. If you want to limit the number of matching records that this function returns, set inOutRecordMatchCount to a positive integer value that specifies the limit.

On output, matching records are returned in the buffer pointed to by inOutDataBuffer with the number of records in that buffer indicated by the value pointed to by inOutMatchRecordCount.

On output, the value pointed to by inOutContinueData indicates whether you should call this function again to obtain more matching records. If inOutContinueData is NULL; you do not need to call this function again. If inOutContinueData is not NULL and you do not want to continue the search, you must call dsReleaseContinueData to deallocate the memory that is associated with inOutContinueData.

If there are too many records to fit in a single buffer, this function returns a non-null value in the value pointed to by inOutContinueData. To get more records, call this function again, passing the pointer to inOutContinueData that was returned by the previous call to this function.

If this function returns eDSBufferTooSmall, the buffer is too small for a record that is to be returned. You should allocate a larger buffer and try again. When this function returns eDSBufferTooSmall, inOutContinueData is also set.

If the value pointed to by inOutContinueData is not NULL and the value returned by this function is zero, more results may be available. Continue calling this function until inOutContinueData points to a NULL value.

To get a record from the data buffer pointed to by inOutDataBuffer, call dsGetRecordEntry. To get information about the record’s attributes, call dsGetAttributeEntry. To get the value of a record’s attribute, call dsGetAttributeValue.

If inOutContinueData is not NULL and you no longer need it, call dsReleaseContinueData to release the memory associated with it.

Special Considerations

In a series of calls to this function, the value of inOutRecordEntryCount must be set by the first call. Its value is ignored in the next calls in the series.

See dsDoAttributeValueSearchWithData to get information about other attribute types and their values.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServices.h

dsDoAttributeValueSearchWithData

Searches for records by attribute type and attribute value.

tDirStatus dsDoAttributeValueSearchWithData (
   tDirNodeReference inDirNodeReference,
   tDataBufferPtr inOutDataBuffer,
   tDataListPtr inRecordTypeList,
   tDataNodePtr inAttributeMatchType,
   tDirPatternMatch inPatternMatchType,
   tDataNodePtr inPatternToMatch,
   tDataListPtr inAttributeTypeRequestList,
   dsBool inAttributeInfoOnly,
   UInt32 *inOutMatchRecordCount,
   tContextData *inOutContinueData
);

Parameters

inDirNodeReference: On input, a value of type tDirNodeReference, obtained by calling dsOpenDirNode, that identifies the node that is to be searched.
inOutDataBuffer: On input, a value of type tDataBufferPtr created by calling dsDataBufferAllocate that points to the tDataBuffer structure in which this function is to place search results. On output, if inOutMatchRecordCount points to a value greater than zero, call dsGetRecordEntry, dsGetAttributeEntry, and dsGetAttributeValue to get the records, attributes, and attribute values from the data buffer.
inRecordTypeList: On input, a value of type tDataListPtr pointing to a tDataList structure allocated by calling dsDataListAllocate that contains a list of the record types to search for. Set the record type to kDSStdRecordTypeAll to search all records. For other possible values, see Standard Record Types.
inAttributeMatchType: On input, a value of type tDataNodePtr that points to a tDataNode structure allocated by calling dsDataNodeAllocateBlock or dsDataNodeAllocateString that contains an attribute type to search for. To search all attribute types, set the attribute type to kDSAttributesAll. For other possible values, see the attribute constants described in the “Constants” section for other possible values.
inPatternMatchType: On input, a value of type tDirPatternMatch specifying a pattern type that controls the way in which the pattern specified by inPattern2Match is compared with attribute values. See Pattern Matching Constants for possible values. The pattern type may also be defined by the Open Directory plug-in that handles the directory service represented by inDirNodeReference.
inPatternToMatch: On input, a value of type tDataNodePtr that points to a tDataNode structure allocated by calling dsDataNodeAllocateBlock or dsDataNodeAllocateString that contains the pattern to match.
inAttributeTypeRequestList: On input, a value of type tDataListPtr pointing to a tDataList structure allocated by calling dsDataListAllocate that specifies the record attribute types that are to be returned.
inAttributeInfoOnly: On input, a value of type dsBool set to TRUE if the calling application only wants information about attributes. To get the values of the attributes as well as information about the attributes, set inAttributeInfoOnly to FALSE.
inOutMatchRecordCount: On input, a pointer to a value of type long that specifies the number of matching records to get. On output, inOutRecordEntryCount points to the number of records in the data buffer pointed to by inOutDataBuffer; the number may be less than the requested number if there were not enough matching records to fill the buffer. The caller cannot change the value of inOutRecordEntryCount across multiple calls to this function using the value pointed to by inOutContinueData.
inOutContinueData: On input, a pointer to a value of type tContextData and set to NULL. On output, if the value pointed to by inOutContinueData is NULL, there are no new results in the buffer. If the value pointed to by inOutContinueData is not NULL on output, pass the value pointed to by inOutContinueData to this function again to get the next entries. You must call dsReleaseContinueData if you don’t want to get the remaining 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 stores in the data buffer pointed to by inOutDataBuffer a list of records having attributes of the type specified by the inAttributeMatchType parameter whose values match the specified pattern.

Set inOutRecordEntryCount to point to a positive integer value that represents the number of records that are to be returned. You cannot change the value pointed to by inOutRecordEntryCount if you call this function with inOutContinueData pointing to context data returned by a previous call to this function.

When you no longer need inOutContinueData, call dsReleaseContinueData to release the memory associated with it.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServices.h

dsDoDirNodeAuth

Performs authentication with a node.

tDirStatus dsDoDirNodeAuth (
   tDirNodeReference inDirNodeReference,
   tDataNodePtr inDirNodeAuthName,
   dsBool inDirNodeAuthOnlyFlag,
   tDataBufferPtr inAuthStepData,
   tDataBufferPtr outAuthStepDataResponse,
   tContextData *inOutContinueData
);

Parameters

inDirNodeReference: On input, a value of type tDirNodeReference obtained by previously calling dsOpenDirNode that representing the node that is to be authenticated.
inDirNodeAuthName: On input, a value of type tDataNodePtr pointing to a tDataNode structure allocated by calling dsDataNodeAllocateBlock or dsDataNodeAllocateString containing the authentication method to use. Authentication methods vary from user to user. Examples include kDSStdAuthSetPasswd, kDSStdAuthSetPasswdAsRoot, and kDSStdAuthChangePasswd to set or change a password and kDSStdAuthNodeNativeNoClearText to authenticate a user. If changes will be made to the node after authentication, the value of the inDirNodeAuthOnlyFlag parameter should be FALSE. For other possible values, see Authentication Constants.
inDirNodeAuthOnlyFlag: On input, a value of type dsBool that indicates whether the result of authentication will be used in the future. A file server that is only authenticating a user should set this parameter to TRUE to indicate that once the user is authenticated, the result will not be used in the future. An application that might make changes to the node after authentication would set this parameter to FALSE to indicate that the result may be used in the future.
inAuthStepData: On input, this parameter contains the data necessary for this step in the authentication process. This parameter is a value of type tDataBufferPtr created by calling dsDataBufferAllocate that points to a tDataBuffer structure.
outAuthStepDataResponse: On output, this parameter contains the plug-in’s response. If the authentication was not successful, the buffer contains a plug-in–defined value. If there are more steps in the authentication process, the buffer contains a plug-in–defined value that is used in the next step of the authentication process. This parameter is a value of type tDataBufferPtr created by calling dsDataBufferAllocate pointing to a tDataBuffer structure.
inOutContinueData: On input, a pointer to a value of type tContextData and set to NULL. On output, if the value pointed to by inOutContinueData is NULL, there are no more steps in the authentication process. If inOutContinueData is not NULL on output, there are more steps to complete. Call this function again and pass to it the value pointed to by inOutContinueData. Call dsReleaseContinueData if the value pointed to by inOutContinueData is not NULL and you do not want to complete the authentication process.
function result: A value of type tDirStatus indicating successful authentication (eDSNoErr) or an error, such as eDSAuthFailed. Other authentication result codes include eDSAuthMethodNotSupported, eDSAuthInBuffFormatError, eDSAuthNoSuchEntity, eDSAuthBadPassword, eDSAuthContinueDataBad, eDSAuthUnknownUser, eDSAuthCannotRecoverPasswd, eDSAuthFailedClearTextOnly, eDSAuthNoAuthServerFound, eDSAuthServerError, eDSAuthNewPasswordRequired, eDSAuthPasswordExpired, eDSAuthPasswordQualityCheckFailed, eDSAuthAccountDisabled, eDSAuthAccountExpired, and eDSAuthAccountInactive. For an explanation of these result codes, see “Result Codes.”

Discussion

This function performs a variety of authentication tasks, such as authenticating a user, setting a password, and changing a password, depending on the value of the inDirNodeAuthName parameter.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

NetworkAuthentication

Declared In

DirServices.h

dsDoDirNodeAuthOnRecordType

Performs authentication using a record type.

tDirStatus dsDoDirNodeAuthOnRecordType (
   tDirNodeReference inDirNodeReference,
   tDataNodePtr inDirNodeAuthName,
   dsBool inDirNodeAuthOnlyFlag,
   tDataBufferPtr inAuthStepData,
   tDataBufferPtr outAuthStepDataResponse,
   tContextData *inOutContinueData,
   tDataNodePtr inRecordType
);

Parameters

inDirNodeReference: On input, a value of type tDirNodeReference obtained by previously calling dsOpenDirNode that representing the node that is to be authenticated.
inDirNodeAuthName: On input, a value of type tDataNodePtr pointing to a tDataNode structure allocated by calling dsDataNodeAllocateBlock or dsDataNodeAllocateString containing the authentication method to use. Authentication methods vary from record to record. Examples include kDSStdAuthSetPasswd, kDSStdAuthSetPasswdAsRoot, and kDSStdAuthChangePasswd to set or change a password and kDSStdAuthNodeNativeNoClearText to authenticate a user. If changes will be made to the node after authentication, the value of the inDirNodeAuthOnlyFlag parameter should be FALSE. For other possible values, see Authentication Constants.
inDirNodeAuthOnlyFlag: On input, a value of type dsBool that indicates whether the result of authentication will be used in the future. A file server that is only authenticating a user should set this parameter to TRUE to indicate that once the user is authenticated, the result will not be used in the future. An application that might make changes to the node after authentication would set this parameter to FALSE to indicate that the result may be used in the future.
inAuthStepData: On input, this parameter contains the data necessary for this step in the authentication process. This parameter is a value of type tDataBufferPtr created by calling dsDataBufferAllocate that points to a tDataBuffer structure.
outAuthStepDataResponse: On output, this parameter contains the plug-in’s response. If the authentication was not successful, the buffer contains a plug-in–defined value. If there are more steps in the authentication process, the buffer contains a plug-in–defined value that is used in the next step of the authentication process. This parameter is a value of type tDataBufferPtr created by calling dsDataBufferAllocate pointing to a tDataBuffer structure.
inOutContinueData: On input, a pointer to a value of type tContextData and set to NULL. On output, if the value pointed to by inOutContinueData is NULL, there are no more steps in the authentication process. If inOutContinueData is not NULL on output, there are more steps to complete. Call this function again and pass to it the value pointed to by inOutContinueData. Call dsReleaseContinueData if the value pointed to by inOutContinueData is not NULL and you do not want to complete the authentication process.
inRecordType: On input, a value of type tDataNodePtr that points to a tDataBuffer structure allocated by calling dsDataBufferAllocate containing the type of the record to use for authentication. Currently, the only record types that are allowed are kDSStdRecordTypeComputers and kDSStdRecordTypeUsers.If this parameter is NULL, dsDoDirNodeAuth is called and a record type of kDSStdRecordTypeUsers is used.
function result: A value of type tDirStatus indicating successful authentication (eDSNoErr) or an error, such as eDSAuthFailed. Other authentication result codes include eDSAuthMethodNotSupported, eDSAuthInBuffFormatError, eDSAuthNoSuchEntity, eDSAuthBadPassword, eDSAuthContinueDataBad, eDSAuthUnknownUser, eDSAuthCannotRecoverPasswd, eDSAuthFailedClearTextOnly, eDSAuthNoAuthServerFound, eDSAuthServerError, eDSAuthNewPasswordRequired, eDSAuthPasswordExpired, eDSAuthPasswordQualityCheckFailed, eDSAuthAccountDisabled, eDSAuthAccountExpired, and eDSAuthAccountInactive. For an explanation of these result codes, see “Result Codes.”

Discussion

This function uses a record type of kDDStdRecordTypeUsers or kDSStdRecordTypeComputers to perform authentication. Specifying a record type of kDSStdRecordTypeUsers is equivalent to calling dsDoDirNodeAuth. Records of type kDSStdRecordTypeUsers and kDSStdRecordTypeComputers are the only records that can be used for authentication.

Version Notes

Introduced in Mac OS X v10.3.

Availability

Available in Mac OS X v10.3 and later.

Declared In

DirServices.h

dsDoMultipleAttributeValueSearch

Uses multiple attribute values to search a node for records.

tDirStatus dsDoMultipleAttributeValueSearch (
   tDirNodeReference inDirNodeReference,
   tDataBufferPtr inOutDataBuffer,
   tDataListPtr inRecordTypeList,
   tDataNodePtr inAttributeType,
   tDirPatternMatch inPatternMatchType,
   tDataListPtr inPatterns2Match,
   UInt32 *inOutMatchRecordCount,
   tContextData *inOutContinueData
);

Parameters

inDirNodeReference: On input, a value of type tDirNodeReference, obtained by calling dsOpenDirNode, that identifies the node that is to be searched.
inOutDataBuffer: On input, a value of type tDataBufferPtr created by calling dsDataBufferAllocate that points to the tDataBuffer structure in which this function is to place search results. On output, if inOutMatchRecordCount points to a value greater than zero, call dsGetRecordEntry, dsGetAttributeEntry, and dsGetAttributeValue to get the records, attributes, and attribute values from the data buffer.
inRecordTypeList: On input, a value of type tDataListPtr pointing to a tDataList structure allocated by calling dsDataListAllocate that contains a list of record types to search. Set the record type to kDSStdRecordTypeAll to search all records. See Standard Record Types for other possible values.
inAttributeType: On input, a value of type tDataNodePtr that points to a tDataNode structure allocated by calling dsDataNodeAllocateBlock or dsDataNodeAllocateString that contains an attribute type to search for. To search all attribute types, set the attribute type to kDSAttributesAll. See the attribute constants described in the “Constants” section for other possible values.
inPatternMatchType: On input, a value of type tDirPatternMatch specifying a pattern type that controls the way in which the pattern specified by inPattern2Match is compared with attribute values. See Pattern Matching Constants for possible values. The pattern type may also be defined by the Open Directory plug-in that handles the directory service represented by inDirNodeReference.
inPatterns2Match: On input, a value of type tDataListPtr that points to a list of patterns to match.
inOutMatchRecordCount: On input, a pointer to a value of type unsigned long that specifies the total number of matching records to get across multiple calls to this function. Set this value to zero to get all matching records. On output, inOutRecordMatchCount points to the number of records in the data buffer pointed to by inOutDataBuffer. Once you start a series of dsDoMultipleAttributeValueSearch calls, inOutMatchRecordCount is ignored as an input parameter.
inOutContinueData: On input, a pointer to a value of type tContextData and set to NULL. On output, if the value pointed to by inOutContinueData is not NULL, get more matching records by calling this function again and pass the value pointed to by inOutContinueData. If on output inOutContinueData is NULL, there are no more records to get. If inOutContinueData is not NULL and an error occurs or you don’t want to get any more matching records, you must call dsReleaseContinueData to release the memory associated with inOutContinueData.
function result: A value of type tDirStatus indicating success (eDSNoErr) or an error. A result code of eDSBufferTooSmall indicates you should allocate a larger buffer and call this function again. For a list of possible result codes, see “Result Codes.”

Discussion

This function works across multiple calls to obtain a list of all records having an attribute whose value matches one of the patterns specified by inPatters2Match. Set inOutRecordMatchCount to zero to get all matching records. If you want to limit the number of matching records that this function returns, set inOutRecordMatchCount to a positive integer value that specifies the limit.

On output, matching records are returned in the buffer pointed to by inOutDataBuffer with the number of records in that buffer indicated by the value pointed to by inOutDataBuffer.

If inOutContinueData is not NULL and you no longer need it, call dsReleaseContinueData to release the memory associated with it.

Special Considerations

In a series of calls to this function, the value of inOutRecordEntryCount must be set by the first call. Its value is ignored in the next calls in the series.

See dsDoAttributeValueSearchWithData to get information about other attribute types and their values.

Version Notes

Introduced in Mac OS X v10.4.

Availability

Available in Mac OS X v10.4 and later.

Declared In

DirServices.h

dsDoMultipleAttributeValueSearchWithData

Searches for records by attribute type and multiple attribute values.

tDirStatus dsDoMultipleAttributeValueSearchWithData (
   tDirNodeReference inDirNodeReference,
   tDataBufferPtr inOutDataBuffer,
   tDataListPtr inRecordTypeList,
   tDataNodePtr inAttributeMatchType,
   tDirPatternMatch inPatternMatchType,
   tDataListPtr inPatternsToMatch,
   tDataListPtr inAttributeTypeRequestList,
   dsBool inAttributeInfoOnly,
   UInt32 *inOutMatchRecordCount,
   tContextData *inOutContinueData
);

Parameters

inDirNodeReference: On input, a value of type tDirNodeReference, obtained by calling dsOpenDirNode, that identifies the node that is to be searched.
inOutDataBuffer: On input, a value of type tDataBufferPtr created by calling dsDataBufferAllocate that points to the tDataBuffer structure in which this function is to place search results. On output, if inOutMatchRecordCount points to a value greater than zero, call dsGetRecordEntry, dsGetAttributeEntry, and dsGetAttributeValue to get the records, attributes, and attribute values from the data buffer.
inRecordTypeList: On input, a value of type tDataListPtr pointing to a tDataList structure allocated on the stack or by calling dsDataListAllocate that contains a list of the record types to search for. Set the record type to kDSStdRecordTypeAll to search all records. For other possible values, see Standard Record Types.
inAttributeMatchType: On input, a value of type tDataNodePtr that points to a tDataNode structure allocated by calling dsDataNodeAllocateBlock or dsDataNodeAllocateString that contains the attribute type to search for. To search all attribute types, set the attribute type to kDSAttributesAll. See the attribute constants described in the “Constants” section for other possible values.
inPatternMatchType: On input, a value of type tDirPatternMatch specifying a pattern type that controls the way in which the pattern specified by inPattern2Match is compared with attribute values. See Pattern Matching Constants for possible values. The pattern type may also be defined by the Open Directory plug-in that handles the directory service represented by inDirNodeReference.
inPatternsToMatch: On input, a value of type tDataListPtr that points to a list of patterns to match.
inAttributeTypeRequestList: On input, a value of type tDataListPtr pointing to a tDataList structure allocated by calling dsDataListAllocate that specifies the record attribute types that are to be returned.
inAttributeInfoOnly: On input, a value of type dsBool set to TRUE if the calling application only wants information about attributes. To get the values of the attributes as well as information about the attributes, set inAttributeInfoOnly to FALSE.
inOutMatchRecordCount: On input, a pointer to a value of type long that specifies the number of matching records to get. On output, inOutRecordEntryCount points to the number of records in the data buffer pointed to by inOutDataBuffer; the number may be less than the requested number if there were not enough matching records to fill the buffer. The caller cannot change the value of inOutRecordEntryCount across multiple calls to this function using the value pointed to by inOutContinueData.
inOutContinueData: On input, a pointer to a value of type tContextData and set to NULL. On output, if the value pointed to by inOutContinueData is NULL, there are no new results in the buffer. If the value pointed to by inOutContinueData is not NULL on output, pass the value pointed to by inOutContinueData to this function again to get the next entries. You must call dsReleaseContinueData if you don’t want to get the remaining records.
function result: A value of type tDirStatus indicating success (eDSNoErr) or an error. A result code of eDSBufferTooSmall indicates you should allocate a larger buffer and call this function again. For a list of possible result codes, see “Result Codes.”

Discussion

This function stores in the data buffer pointed to by inOutDataBuffer a list of records having attributes of the type specified by the inAttributeMatchTypes parameter whose values match the specified pattern.

When you no longer need inOutContinueData, call dsReleaseContinueData to release the memory associated with it.

Version Notes

Introduced in Mac OS X v10.4.

Availability

Available in Mac OS X v10.4 and later.

Declared In

DirServices.h

dsDoPlugInCustomCall

Exchanges custom information with an Open Directory plug-in.

tDirStatus dsDoPlugInCustomCall (
   tDirNodeReference inDirNodeReference,
   UInt32 inCustomRequestCode,
   tDataBufferPtr inCustomRequestData,
   tDataBufferPtr outCustomRequestResponse
);

Parameters

inDirNodeReference: On input, a value of type tDirNodeReference, obtained by calling dsOpenDirNode, that identifies the open node for which custom information is to be exchanged.
inCustomRequestCode: On input, a value of type unsigned long, containing a request code that is to be sent to the plug-in.
inCustomRequestData: On input, a value of type tDataBufferPtr created by calling dsDataBufferAllocate that points to a tDataBuffer structure containing data that is to be sent to the plug-in.
outCustomRequestResponse: On input, a value of type tDataBufferPtr created by calling dsDataBufferAllocate that points to a tDataBuffer structure. On output, the buffer contains the plug-in’s response to the information that was sent.
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 exchanges custom information with the Open Directory plug-in for the node represented by inDirNodeReference.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServices.h

dsFindDirNodes

Finds the registered node names that match a pattern.

tDirStatus dsFindDirNodes (
   tDirReference inDirReference,
   tDataBufferPtr inOutDataBufferPtr,
   tDataListPtr inNodeNamePattern,
   tDirPatternMatch inPatternMatchType,
   UInt32 *outDirNodeCount,
   tContextData *inOutContinueData
);

Parameters

inDirReference: On input, a value of type tDirReference obtained by calling dsOpenDirService.
inOutDataBufferPtr: On input, a value of type tDataBufferPtr created by calling dsDataBufferAllocate that points to a tDataBuffer structure in which the results are to be returned. On output, call dsGetDirNodeName to extract the results from the data buffer pointed to by inOutDataBufferPtr.
inNodeNamePattern: On input, a value of type tDataListPtr pointing to a tDataList structure containing the pattern that is to be matched. Set this parameter to NULL and inPatternMatchType to the appropriate constant to get the contacts search node (eDSContactsSearchNodeName), network search node (eDSNetworkSearchNodeName), authentication search node (eDSAuthenticationSearchNodeName), the node for the local NetInfo domain (eDSLocalNodeNames), or locally hosted nodes (eDSLocalHostedNodes).
inPatternMatchType: On input, a value of type tDirPatternMatch specifying a pattern type that controls the way in which the pattern specified by inNodeNamePattern is compared with registered node names. See Pattern Matching Constants for possible values.
outDirNodeCount: On output, a pointer to a value of type unsigned long in which this function has stored the number of registered node names in the data buffer pointed to by inOutDataBufferPtr.
inOutContinueData: On input, a pointer to a value of type tContextData and set to NULL. On output, if inOutContinueData points to a value that is NULL, there is no more response data to get. If inOutContinueData points to a value that is not NULL, there is more response data, which you can get by calling this function again and passing the context data pointed to by inOutContinueData. If inOutContinueData points to a value that is not NULL and you do not want to get the remaining response data, you must call dsReleaseContinueData to deallocate the memory associated with inOutContinueData.
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 searches the list of nodes that have been registered by Open Directory plug-ins for the directory service represented by inDirReference for names that match a pattern. It places the names that match the pattern in the data buffer pointed to by inOutDataBufferPtr. Use the inNodeNamePattern parameter to specify pattern to match and the inPatternMatchType parameter to specify how the pattern is to be matched or to specify that a search node is to be found.

On output, outDirNodeCount contains the number of matching registered node names that this function has found. Call dsGetDirNodeName to extract the names from the data buffer.

On output, if inOutContinueData points to a value that is not NULL, there are more matching registered node names for this function to find even if outDirNodeCount points to a zero value. To get another buffer of matching registered node names, call this function again and pass to it the context data pointed to by inOutContinueData. If you do not want to get another buffer of matching node names, you must call dsReleaseContinueData to deallocate the context data pointed to by inOutContinueData.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

NetworkAuthentication

Declared In

DirServices.h

dsFlushRecord

Writes a record.

tDirStatus dsFlushRecord (
   tRecordReference inRecordReference
);

Parameters

inRecordReference: On input, value of type tRecordReference obtained by previously calling dsOpenRecord.
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 requests the directory service to write the record. The directory service may comply with the request or may choose to ignore it.

The value returned by this function does not reflect whether the record was actually written.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServices.h

dsGetAttributeEntry

Gets an attribute entry from a data buffer.

tDirStatus dsGetAttributeEntry (
   tDirNodeReference inDirNodeReference,
   tDataBufferPtr inOutDataBuffer,
   tAttributeListRef inAttributeListRef,
   UInt32 inAttributeInfoIndex,
   tAttributeValueListRef *outAttributeValueListRef,
   tAttributeEntryPtr *outAttributeInfoPtr
);

Parameters

inDirNodeReference: On input, a value of type tDirNodeReference obtained by calling dsOpenDirNode representing the node associated with the data in the buffer pointed to by inOutDataBuffer.
inOutDataBuffer: On input, a value of type tDataBufferPtr pointing to a tDataBuffer structure containing data returned, for example, by a previous call to dsGetDirNodeInfo or dsGetRecordList.
inAttributeListRef: On input, a value of type tAttributeListRef obtained by previously calling dsGetDirNodeInfo or dsGetRecordEntry.
inAttributeInfoIndex: On input, a value of type unsigned long. Set inAttributeInfoIndex to 1 to get the first attribute entry. Set inAttributeInfoIndex to 2 to get the second attribute entry, and so on.
outAttributeValueListRef: On output, a pointer to a value of type tAttributeValueListRef. Pass the pointer to outAttributeValueListRef to dsGetAttributeValue to get the value of the attribute.
outAttributeInfoPtr: On output, a pointer to a value of type tAttributeEntryPtr that points to a tAttributeEntry structure in which this function stores information about the attribute specified by inAttributeInfoIndex. The information includes the number of attribute values, the maximum size of the attribute’s value, and the attribute’s signature.
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 uses an attribute list reference to extract an attribute entry from a data buffer previously obtained by calling dsGetDirNodeInfo or dsGetRecordEntry. The function stores the information in the tAttributeEntry structure pointed to by outAttributeInfoPtr.

To get the value(s) of the attribute, call dsGetAttributeValue and pass to it the data buffer pointed to by inOutDataBuffer and the attribute value list reference pointed to by outAttributeValueListRef.

When you no longer need the attribute value list pointed to by outAttributeValueListRef, call dsCloseAttributeValueList.

When you no longer need the outAttributeInfoPtr parameter, call dsDeallocAttributeEntry to deallocate the tAttributeEntry structure and its pointer.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

NetworkAuthentication

Declared In

DirServices.h

dsGetAttributeValue

Gets the value of an attribute from a data buffer.

tDirStatus dsGetAttributeValue (
   tDirNodeReference inDirNodeReference,
   tDataBufferPtr inOutDataBuffer,
   UInt32 inAttributeValueIndex,
   tAttributeValueListRef inAttributeValueListRef,
   tAttributeValueEntryPtr *outAttributeValue
);

Parameters

inDirNodeReference: On input, a value of type tDirNodeReference obtained by calling dsOpenDirNode that represents the node for which the search was conducted.
inOutDataBuffer: On input, a value of type tDataBufferPtr pointing to a tDataBuffer structure that was previously filled in, for example, by calling dsDoAttributeValueSearch, dsGetDirNodeInfo, or dsGetRecordList.
inAttributeValueIndex: On input, a value of type unsigned long. Set inAttributeValueIndex to 1 to get the first attribute value. Set inAttributeValueIndex to 2 to get the second attribute value, and so on.
inAttributeValueListRef: On input, a value of type tAttributeValueListRef obtained by calling dsGetAttributeEntry that represents a tAttributeValueEntry structure containing an attribute value ID and the value of the attribute represented by the attribute value ID.
outAttributeValue: On output, a pointer to a value of type tAttributeValueEntryPtr that points to an application-allocated tAttributeValueEntry structure containing the attribute value ID and the value of the attribute.
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 obtains the value of an attribute from a data buffer previously filled in, for example, by calling dsDoAttributeValueSearch or dsGetRecordList, and stores the value in a tAttributeValueEntry structure.

When you no longer need the attribute value list pointed to by inAttributeValueListRef, call dsCloseAttributeValueList. When you no longer need outAttributeValue, call dsDeallocAttributeValueEntry.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

NetworkAuthentication

Declared In

DirServices.h

dsGetDataLength

Gets the length of data in a data list.

UInt32 dsGetDataLength (
   const tDataList *inDataList
);

Parameters

inDataListPtr: On input, a pointer to a value of type tDataList whose length is to be obtained.
function result: The length of data in the specified data list or an error code. For a list of possible result codes, see “Result Codes.”

Discussion

This utility function obtains the length in bytes of data in a data list.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServicesUtils.h

dsGetDirNodeCount

Gets the total number of registered nodes.

tDirStatus dsGetDirNodeCount (
   tDirReference inDirReference,
   UInt32 *outDirectoryNodeCount
);

Parameters

inDirReference: A value of type tDirReference obtained by previously calling dsOpenDirService or dsOpenDirServiceProxy.
outDirectoryNodeCount: On output, a pointer to a value of type unsigned long containing the total number of registered nodes that are available to the Open Directory session represented by inDirReference.
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 gets the total number of registered nodes that are available to the Open Directory session represented by inDirReference. If you need to know whether directory names have changed even if the count has not changed, see dsGetDirNodeCountWithInfo.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServices.h

dsGetDirNodeCountWithInfo

Gets the total number of registered nodes and a change token.

tDirStatus dsGetDirNodeCountWithInfo (
   tDirReference inDirReference,
   UInt32 *outDirectoryNodeCount,
   UInt32 *outDirectoryNodeChangeToken
);

Parameters

inDirReference: A value of type tDirReference obtained by previously calling dsOpenDirService or dsOpenDirServiceProxy.
outDirectoryNodeCount: On output, a pointer to a value of type unsigned long containing the total number of registered nodes that are available to the Open Directory session represented by inDirReference.
outChangeToken: On output, a pointer to a value of type unsigned long containing the change token. Save the value pointed to by outChangeToken and compare it with the next value received when you call this function again to see if there has been a change.
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 gets the total number of registered nodes that are available to the Open Directory session represented by inDirReference, as well as a change token. To learn whether the node names have changed even though the number of registered nodes remains the same, call this function and get another change token. Compare the original and the new change token. The two change tokens will not be equal if there has been a change in the name of a registered node or to the number of registered nodes. If the change tokens are not equal, you may want to call dsGetDirNodeList to get a new list of registered nodes.

The change token is only guaranteed to be different if the node names have changed. Do not assume that the new change token will be incremented or decremented relative to the value of the original change token.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServices.h

dsGetDirNodeInfo

Gets information about a node’s attribute types and attribute values.

tDirStatus dsGetDirNodeInfo (
   tDirNodeReference inDirNodeReference,
   tDataListPtr inDirNodeInfoTypeList,
   tDataBufferPtr inOutDataBuffer,
   dsBool inAttributeInfoOnly,
   UInt32 *outAttributeInfoCount,
   tAttributeListRef *outAttributeListRef,
   tContextData *inOutContinueData
);

Parameters

inDirNodeReference: On input, a value of type tDirNodeReference, obtained by previously calling dsOpenDirNode, that identifies the node for which information is to be obtained.
inDirNodeInfoTypeList: On input, a value of type tDataListPtr pointing to a tDataList structure containing the attribute types for which information is requested. To get information about all attribute types, pass a tDataList structure whose list is kDSAttributesAll.
inOutDataBuffer: On input, a value of type tDataBufferPtr created by calling dsDataBufferAllocate that points to a tDataBuffer structure. On output, the tDataBuffer structure contains the requested attribute type information for the specified node. If the input value of inAttributeInfoOnly is FALSE, the data buffer also contains attribute values. Call dsGetAttributeEntry to extract attribute information from the buffer. Then call dsGetAttributeValue to get the value of an attribute.
inAttributeInfoOnly: On input, a value of type dsBool set to TRUE if you only want attribute information. To get the values of the requested attributes as well as information about the attributes, set inAttributeInfoOnly to FALSE.
outAttributeInfoCount: On output, a pointer to a value of type unsigned long containing the number of attribute types in the data buffer pointed to by inOutDataBuffer.
outAttributeListRef: On input, a pointer to a value of type tAttributeListRef. When this function returns, use the attribute list reference pointed to by outAttributeListRef to call dsGetAttributeEntry to get the attribute type information. Use information provided by calling dsGetAttributeEntry to call dsGetAttributeValue to get the value of an attribute.
inOutContinueData: On input, a pointer to a value of type tContextData and set to NULL. On output, if inOutContinueData points to a value that is NULL, there is no more response data to get. If inOutContinueData points to a value that is not NULL, there is more response data, which you can get by calling this function again and passing the context data pointed to by inOutContinueData. If inOutContinueData points to a value that is not NULL and you do not want to get the remaining response data, you must call dsReleaseContinueData to deallocate the memory associated with inOutContinueData.
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 gets attribute type information about a node, which may include attribute types for storing the authentication methods the node supports, the types of records the node contains, kDS1AttrReadOnlyNode, which indicates whether the node supports write operations, kDSNAttrNodePath, which indicates the node’s name, and kDSNAttrSubNodes, which indicates nodes that are children of this node in the hierarchy.

You should call dsCloseAttributeList when you no longer need the attribute list reference pointed to by outAttributeListRef.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServices.h

dsGetDirNodeList

Gets the names of registered nodes.

tDirStatus dsGetDirNodeList (
   tDirReference inDirReference,
   tDataBufferPtr inOutDataBufferPtr,
   UInt32 *outDirNodeCount,
   tContextData *inOutContinueData
);

Parameters

inDirReference: On input, a value of type tDirReference obtained by previously calling dsOpenDirService or dsOpenDirServiceProxy.
inOutDataBufferPtr: On input, a value of type tDataBufferPtr created by calling dsDataBufferAllocate that points to a tDataBuffer structure. On output, the tDataBuffer structure contains the requested list of registered node names. Call dsGetDirNodeName to get a name from the buffer.
outDirNodeCount: On output, a pointer to a value of type unsigned long in which this function has stored the number of registered directory names in the data buffer pointed to by inOutDataBufferPtr.
inOutContinueData: On input, a pointer to a value of type tContextData and set to NULL. On output, if inOutContinueData points to a value that is NULL, there is no more response data to get. If inOutContinueData points to a value that is not NULL, there is more response data, which you can get by calling this function again and passing the context data pointed to by inOutContinueData. If inOutContinueData points to a value that is not NULL and you do not want to get the remaining response data, you must call dsReleaseContinueData to deallocate the memory associated with inOutContinueData.
function result: A value of type tDirStatus indicating success (eDSNoErr) or an error. A result code of eDSBufferTooSmall indicates you should allocate a larger buffer and call this function again. For a list of possible result codes, see “Result Codes.”

Discussion

This function fills a data buffer with the names of registered nodes. Call dsGetDirNodeName to extract the names from the buffer.

On output, if inOutContinueData points to a value that is not NULL, there are more registered node names to get even if outDirNodeCount points to a zero value. To get another buffer of registered node names, call this function again and pass to it the context data pointed to by inOutContinueData.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServices.h

dsGetDirNodeName

Gets node names from a buffer.

tDirStatus dsGetDirNodeName (
   tDirReference inDirReference,
   tDataBufferPtr inOutDataBuffer,
   UInt32 inDirNodeIndex,
   tDataListPtr *inOutDataList
);

Parameters

inDirReference: On input, a value of type tDirReference obtained by previously calling dsOpenDirService or dsOpenDirServiceProxy.
inOutDataBuffer: On input, a value of type tDataBufferPtr that points to a tDataBuffer structure containing the results of calling dsFindDirNodes or dsGetDirNodeList.
inDirNodeIndex: On input, a value of type unsigned long. Set inDirNodeIndex to 1 to get the first name. Set inDirNodeIndex to 2 to get the second name, and so on.
inOutDataList: On input, a value of type tDataListPtr pointing to a value that is NULL or that can be overwritten. On output, the data list contains the full pathname of the node specified by inDirNodeIndex. You can reuse the data list for other purposes, but when you no longer need the data list, call dsDataListDeallocate to deallocate it. The data list is heap-based, you also need to call free().
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 parses a buffer of node names obtained by calling dsFindDirNodes or dsGetDirNodeList.

The inOutDataBuffer parameter points to the data buffer that contains node names. The inDirNodeIndex parameter specifies which node name to get, and the inOutDataList parameter specifies the address of the application-defined tDataList structure in which this function is to place the node name.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

NetworkAuthentication

Declared In

DirServices.h

dsGetPathFromList

Gets the path from a data list.

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

Parameters

inDirReference: On input, a value of type tDirReference obtained by calling dsOpenDirService or dsOpenDirServiceProxy representing the Open Directory session associated with the data list from which a path is to be obtained, or zero.
inDataList: On input, a pointer to a value of type tDataList containing the path to get.
inDelimiter: On input, a pointer to a character string containing the character that delimits the components of the path in the data list pointed to by the inDataList parameter.
function result: A pointer to a character string that contains the path that was obtained from the data list.

Discussion

This utility function gets the path from a data list. The path is in UTF-8 format.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServicesUtils.h

dsGetRecordAttributeInfo

Gets information about a record’s attribute.

tDirStatus dsGetRecordAttributeInfo (
   tRecordReference inRecordReference,
   tDataNodePtr inAttributeType,
   tAttributeEntryPtr *outAttributeInfoPtr
);

Parameters

inRecordReference: On input, a value of type tRecordReference obtained by previously calling dsOpenRecord representing the record for which the record’s attribute type information is to be obtained.
inAttributeType: On input, a value of type tDataNodePtr that points to a tDataBuffer structure allocated by calling dsDataBufferAllocate containing the attribute type for which information is to be obtained. Call dsGetRecordList to find out the record’s attribute types.
outAttributeInfoPtr: On output, a pointer to a value of type tAttributeEntryPtr that points to an application-allocated tAttributeEntry structure containing the information about the attribute pointed to by inAttributeType.
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 gets information about a record’s attribute. The information consists of the number of attribute values, data size, maximum value size, and signature.

When you no longer need the outAttributeInfoPtr parameter, call dsDeallocAttributeEntry to deallocate the tAttributeValueEntry structure and its pointer.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServices.h

dsGetRecordAttributeValueByID

Uses an attribute value ID to obtain the value of an attribute.

tDirStatus dsGetRecordAttributeValueByID (
   tRecordReference inRecordReference,
   tDataNodePtr inAttributeType,
   UInt32 inValueID,
   tAttributeValueEntryPtr *outEntryPtr
);

Parameters

inRecordReference: On input, a value of type tRecordReference obtained by previously calling dsOpenRecord representing the record that has an attribute whose value is to be obtained.
inAttributeType: On input, a value of type tDataNodePtr pointing to a tDataNode structure allocated by calling dsDataNodeAllocateBlock or dsDataNodeAllocateString that contains the type of the attribute whose value is to be obtained.
inValueID: On input, a value of type unsigned long containing the attribute value ID of the value to get. Call dsGetAttributeEntry to get an attribute value ID.
outEntryPtr: On output, a pointer to a value of type tAttributeValueEntryPtr that points to a tAttributeValueEntry structure allocated by calling dsAllocAttributeValueEntry containing the requested attribute value.
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 uses an attribute value ID to obtain the value of an attribute for the record represented by inRecordReference.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServices.h

dsGetRecordAttributeValueByIndex

Uses an index to get the value of an attribute.

tDirStatus dsGetRecordAttributeValueByIndex (
   tRecordReference inRecordReference,
   tDataNodePtr inAttributeType,
   UInt32 inValueIndex,
   tAttributeValueEntryPtr *outEntryPtr
);

Parameters

inRecordReference: On input, a value of type tRecordReference obtained by previously calling dsOpenRecord representing the record that has an attribute whose value is to be obtained.
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 whose value is to be obtained.
inValueIndex: On input, a value of type unsigned long that specifies the index of the attribute value that is to be obtained. Call dsGetRecordAttributeInfo to find out how many values the attribute has. Set inValueID to 1 to get the first value; set inValueID to 2 to get the second value, and so on.
outEntryPtr: On output, a value of type tAttributeValueEntryPtr that points to a tAttributeValueEntry structure containing the requested attribute value.
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 uses an index to obtain the value of an attribute for the record represented by inRecordReference.

To determine whether an attribute can have multiple values, call dsGetRecordAttributeInfo, which returns a value that points to the attribute’s value count.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServices.h

dsGetRecordAttributeValueByValue

Verifies the existence of an attribute value within a record.

tDirStatus dsGetRecordAttributeValueByValue (
   tRecordReference inRecordReference,
   tDataNodePtr inAttributeType,
   tDataNodePtr inAttributeValue,
   tAttributeValueEntryPtr *outEntryPtr
);

Parameters

inRecordReference: On input, a value of type tRecordReference obtained by previously calling dsOpenRecord representing the record that has an attribute whose value is to be obtained.
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 whose value is to be obtained.
inValueValue: On input, a value of type tDataNodePtr that specifies the value that is to be verified.
outEntryPtr: On output, a value of type tAttributeValueEntryPtr that points to a tAttributeValueEntry structure containing the attribute value.
function result: A value of type tDirStatus indicating that the value was obtained (eDSNoErr); any value other than eDSNoErr indicates failure. For a list of possible result codes, see “Result Codes.”

Discussion

This function verifies the existence the specified attribute value for the record specified by inRecordReference. It also returns the value’s ID, which is useful if you want to remove this value by calling dsRemoveAttributeValue or change it by calling dsSetAttributeValue.

Version Notes

Introduced in Mac OS X v10.4.

Availability

Available in Mac OS X v10.4 and later.

Declared In

DirServices.h

dsGetRecordEntry

Gets the next record from a data buffer.

tDirStatus dsGetRecordEntry (
   tDirNodeReference inDirNodeReference,
   tDataBufferPtr inOutDataBuffer,
   UInt32 inRecordEntryIndex,
   tAttributeListRef *outAttributeListRef,
   tRecordEntryPtr *outRecordEntryPtr
);

Parameters

inDirNodeReference: On input, a value of type tDirNodeReference, obtained by calling dsOpenDirNode, that identifies the node in which the record specified by inRecordEntryIndex resides.
inOutDataBuffer: On input, a value of type tDataBufferPtr that points to a tDataBuffer structure containing data obtained by previously calling dsGetRecordList, dsDoAttributeValueSearch, dsDoAttributeValueSearchWithData, dsDoMultipleAttributeValueSearch, or dsDoMultipleAttributeValueSearchWithData.
inRecordEntryIndex: On input, a value of type unsigned long that specifies the next record to get. Set inRecordEntryIndex to 1 to get the first record. Set inRecordEntryIndex to 2 to get the second record, and so on.
outAttributeListRef: On input, a pointer to a value of type tAttributeListRef. On output, to get information about the record’s attributes, pass the value pointed to by outAttributeListRef as a parameter when calling dsGetAttributeEntry.
outRecordEntryPtr: On output, outRecordEntryPtr points to a tRecordEntry structure that contains the record entry specified by the inRecordEntryIndex. When you no longer need the record entry structure, call dsDeallocRecordEntry.
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 gets the name, type and number of attribute types for a record from the data buffer pointed to by inOutDataBuffer and puts it in the tRecordEntry structure pointed to by outRecordEntryPtr.

This function also returns a pointer to an attribute list reference that can be used to get information about a record’s attributes by calling dsGetAttributeEntry. Calling dsGetAttributeEntry returns an attribute value list reference that can be used to call dsGetAttributeValue to get the value of an attribute.

You should call dsCloseAttributeList when you no longer need the attribute list reference pointed to by outAttributeListRef. You should call dsDeallocRecordEntry when you no longer need the record entry structure pointed to by outRecordEntryPtr.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

NetworkAuthentication

Declared In

DirServices.h

dsGetRecordList

Gets a list of records and puts it in a data buffer.

tDirStatus dsGetRecordList (
   tDirNodeReference inDirNodeReference,
   tDataBufferPtr inOutDataBuffer,
   tDataListPtr inRecordNameList,
   tDirPatternMatch inPatternMatchType,
   tDataListPtr inRecordTypeList,
   tDataListPtr inAttributeTypeList,
   dsBool inAttributeInfoOnly,
   UInt32 *inOutRecordEntryCount,
   tContextData *inOutContinueData
);

Parameters

inDirNodeReference: On input, a value of type tDirNodeReference obtained by calling dsOpenDirNode.
inOutDataBuffer: On input, a value of type tDataBufferPtr created by calling dsDataBufferAllocate that points to a tDataBuffer structure into which this function is to place the requested list of records. If inOutRecordEntryCount points to a positive value greater than zero when this function returns, parse the records in the buffer pointed to by inOutDataBuffer by calling dsGetRecordEntry.
inRecordNameList: On input, a value of type tDataListPtr specifying the record names to get.
inPatternMatchType: On input, a value of type tDirPatternMatch specifying a pattern type that controls the way in which the pattern specified by inRecordNameList is compared with record names. See Pattern Matching Constants for possible values. The pattern type may also be defined by the Open Directory plug-in that handles the directory service represented by inDirNodeReference. The inPatternMatchType parameter is ignored if inRecordNameList is set to get all records.
inRecordTypeList: On input, a value of type tDataListPtr pointing to an tDataList structure containing the types of records to get. One way to allocate the data list is to call dsDataListAllocate.
inAttributeTypeList: On input, a value of type tDataListPtr pointing to a tDataList structure that contains the attribute types of the records that are to be obtained. If you want all attribute types, create the data list using kDSAttributesAll. To get all standard attribute types, create the data list using kDSAttributesStandardAll. To get all native attribute types, create the data list using kDSAttributesNativeAll.
inAttributeInfoOnly: On input, a value of type dsBool. Set inAttributeInfoOnly to TRUE if you only want attribute type information. To get attribute type information as well as attribute values, set inAttributeInfoOnly to FALSE.
inOutRecordEntryCount: On input, a pointer to a value of type unsigned long that specifies the total number of records to get across what may be multiple calls to this function in order to get the complete list of records, or zero if you want to get all matching records. On output, inOutRecordEntryCount points to the number of records this function has stored in the data buffer pointed to by inOutDataBufferPtr. Once you start a series of dsGetRecordList calls, inOutMatchRecordCount is ignored as an input parameter.
inOutContinueData: On input, a pointer to a value of type tContextData and set to NULL. On output, if the value pointed to by inOutContinueData is NULL, there are no more records to get. On output, if the value pointed to by inOutContinueData is not NULL, fill the data buffer pointed to by inOutDataBuffer with the next records by calling this function again and passing the context data pointed to by inOutContinueData. If you don’t want to get the remaining records, you must call dsReleaseContinueData to deallocate the memory pointed to by inOutContinueData.
function result: A value of type tDirStatus indicating success (eDSNoErr) or an error. An result code of eDSBufferTooSmall occurs if the buffer is too small to fit the first record to be returned. In this case, call this function again after allocating a larger buffer. For a list of other possible result codes, see “Result Codes.”

Discussion

This function stores in the data buffer pointed to by inOutDataBuffer a list of records having the specified data types and values. Call dsGetRecordEntry to parse the records in the buffer.

If there are too many records to fit in the data buffer pointed to by inOutDataBuffer, inOutContinueData points to a non-null value when this function returns. To get more records, call this function again, passing the pointer to the inOutContinueData parameter that was returned by the previous call to this function. To get all records, continue calling this function until inOutContinueData points to a null value.

If the value pointed to by inOutContinueData is not NULL and you do not want to get more records, call dsReleaseContinueData to release the memory associated with inOutContinueData.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

NetworkAuthentication

Declared In

DirServices.h

dsGetRecordNameFromEntry

Gets the name of a record from a record entry structure.

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

Parameters

inRecEntryPtr: On input, a value of type tRecordEntryPtr that points to the tRecordEntry structure that contains the name that is to be obtained.
outRecName: On output, a pointer to a value that points to a character string containing the record’s name in UTF-8 format.
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 gets the name of the record in a record entry structure.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServicesUtils.h

dsGetRecordReferenceInfo

Gets a record’s name and type and the number of attributes the record has.

tDirStatus dsGetRecordReferenceInfo (
   tRecordReference inRecordReference,
   tRecordEntryPtr *outRecordInfo
);

Parameters

inRecordReference: On input, value of type tRecordReference obtained by previously calling dsOpenRecord that represents the record reference information is to be obtained.
outRecordInfo: On output, a pointer to a value of type tRecordEntryPtr that points to a tRecordEntry structure containing the record information for the specified record. Call dsDeallocRecordEntry when you no longer need the record entry structure.
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 gets information about the record represented by inRecordReference and stores it in the tRecordEntry structure pointed to by outRecordInfo.

The information includes the number of attributes the record has and the name and type of the record.

You should call dsDeallocRecordEntry when you no longer need the record entry structure pointed to by outRecordInfo.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServices.h

dsGetRecordTypeFromEntry

Gets the type of a record from a record entry structure.

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

Parameters

inRecEntryPtr: On input, a value of type tRecordEntryPtr that points to the tRecordEntry structure that contains the type that is to be obtained.
outRecType: On output, a pointer to a value that points to a character string containing the record’s type.
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 gets the type of the record in a record entry structure.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServicesUtils.h

dsIsDirServiceRunning

Checks to see if Open Directory is running.

tDirStatus dsIsDirServiceRunning

Parameters

function result: A value of type tDirStatus indicating that Open Directory is running (eDSNoErr) or that Open Directory is not running (eServerNotRunning).

Discussion

This function checks to see if Open Directory is running.

Prior to Mac OS X 10.2, Open Directory did not start until when an application called dsOpenDirService. With Mac OS X 10.2, Open Directory starts up when the system starts up and is always running.

Applications that run on Mac OS X 10.0 and Mac OS X 10.1 should call this function before calling dsOpenDirService. If Open Directory is not running, you can display a progress indicator to assure the user that your application is still running while Open Directory starts up, and then call dsOpenDirService.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServices.h

dsOpenDirNode

Opens a session with a node.

tDirStatus dsOpenDirNode (
   tDirReference inDirReference,
   tDataListPtr inDirNodeName,
   tDirNodeReference *outDirNodeReference
);

Parameters

inDirReference: On input, a value of type tDirReference obtained by previously calling dsOpenDirService or dsOpenDirServiceProxy.
inDirNodeName: On input, a value of type tDataListPtr that points to a tDataList structure containing the name of the node to open. You can get the name of the node by calling dsGetDirNodeList or by calling, for example, dsBuildListFromStrings to construct the name yourself.
outDirNodeReference: On input, a pointer to a value of type tDirNodeReference. On output, the value pointed to by outDirNodeReference is a node reference that represents the session context for the contents of the opened node. Provide it as a parameter to Open Directory functions that manipulate nodes, such as dsGetDirNodeInfo, dsDoDirNodeAuth, dsGetRecordList, dsGetRecordEntry, dsOpenRecord, and 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 opens a session with the node whose name is specified in the tDataList structure pointed to by the inDirNodeName parameter. Opening a session with a node allows you to perform operations on the opened node, such as creating, listing, and deleting records.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

NetworkAuthentication

Declared In

DirServices.h

dsOpenDirService

Opens an Open Directory session.

tDirStatus dsOpenDirService (
   tDirReference *outDirReference
);

Parameters

outDirReference: On input, a pointer to a value of type tDirReference. On output, the value pointed to by outDirReference identifies this session and is passed as a parameter to many Open Directory functions.
function result: A value of type tDirStatus indicating success (eDSNoErr) or an error. For a list of possible result codes, see “Result Codes.”

Discussion

When this function returns, use the value pointed to by outDirReference when calling Open Directory functions that require an Open Directory reference as a parameter.

With Mac OS X 10.2, Open Directory starts up when the system starts up and is always running. Prior to Mac OS X 10.2, the DirectoryService daemon was not started until an application called this function for the first time. Applications that run on Mac OS X 10.0 and Mac OS X 10.1 should call dsIsDirServiceRunning to learn whether Open Directory is running. If it’s not running, you can display a progress indicator while Open Directory starts up and then call this function.

Special Considerations

You can establish multiple Open Directory sessions by calling this function multiple times.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

NetworkAuthentication

Declared In

DirServices.h

dsOpenDirServiceProxy

Opens a remote Open Directory session.

tDirStatus dsOpenDirServiceProxy (
   tDirReference *outDirRef,
   const char *inIPAddress,
   UInt32 inIPPort,
   tDataNodePtr inAuthMethod,
   tDataBufferPtr inAuthStepData,
   tDataBufferPtr outAuthStepDataResponse,
   tContextData *ioContinueData
);

Parameters

outDirRef: On input, a pointer to a value of type tDirReference. On output, the value pointed to by outDirReference identifies this session and is passed as a parameter to many Open Directory functions.
inIPAddress: On input, a pointer to a null-terminated string contain the fully qualified domain name or the IP address in dotted decimal format of the Open Directory machine with which a TCP/IP connection is to be established.
inIPPort: On input, a value of type unsigned long containing the port number on which the connection is to be made, or zero which allows the default port number to be used. The default port number is 625.
inAuthMethod: On input, a value of type tDataNodePtr pointing to a tDataNode structure allocated by calling dsDataNodeAllocateBlock or dsDataNodeAllocateString containing the authentication method to use. You can expect these authentication methods to be supported by any plug-in that handles authentication: kDSStdAuthNodeNativeNoClearText and kDSStdAuthNodeNativeClearTextOK. For other possible values, see Authentication Constants.
inAuthStepData: On input, a value of type tDataBufferPtr created by calling dsDataBufferAllocate pointing to a tDataBuffer structure that contains the data necessary for this step in the authentication process. For the first step in the authentication process, inAuthStepData typically consists of four bytes specifying the length of a username, followed by the user name in UTF-8 encoding, followed by four bytes specifying the length of the password, followed by the password in UTF-8 encoding.
outAuthStepDataResponse: On output, a value of type tDataBufferPtr created by calling dsDataBufferAllocate pointing to a tDataBuffer structure that contains the authentication response.
inOutContinueData: On input, a pointer to a value of type tContextData and set to NULL. On output, if the value pointed to by inOutContinueData is NULL, there are no more steps in the authentication process. If inOutContinueData is not NULL on output, there are more steps to complete. Call this function again and pass to it the value pointed to by inOutContinueData. Call dsReleaseContinueData if the value pointed to by inOutContinueData is not NULL and you do not want to complete the authentication process.
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 opens a remote Open Directory session on another machine running Mac OS X 10.2 or later. When the authentication process completes successfully, this function returns an Open Directory reference that can be used for all subsequent calls to Open Directory functions, such as dsOpenDirNode and dsFindDirNodes, on the remote machine. These calls will be dispatched automatically over the TCP connection to the remote DirectoryService daemon. Any calls using child references obtained by calling functions such as dsFindDirNodes will also be sent to the remote DirectoryService daemon.

Special Considerations

You can establish multiple remote Open Directory sessions by calling this function multiple times.

Version Notes

Available in Mac OS X v10.2 and later.

Availability

Available in Mac OS X v10.2 and later.

Declared In

DirServices.h

dsOpenRecord

Opens a record.

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

Parameters

inDirNodeReference: On input, a node reference obtained by calling dsOpenDirNode.
inRecordType: On input, a value of type tDataNodePtr that points to a tDataBuffer structure allocated by calling dsDataBufferAllocate containing the type of the record to open. For possible values, see Standard Record Types.
inRecordName: On input, a value of type tDataNodePtr that points to a tDataBuffer structure allocated by calling dsDataBufferAllocate containing the name in UTF-8 format of the record to open.
outRecordReference: On output, a pointer to a value of type tRecordReference that you can pass to other Open Directory functions that operate on records, such as dsGetRecordReferenceInfo, dsFlushRecord, dsSetRecordName, and dsCloseRecord.
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 opens a record and returns in the value pointed to by the outRecordReference parameter a record reference that you can use in subsequent calls to Open Directory functions that manipulate records.

A record must be open before you can perform operations on the record, such as setting its name, adding attributes, setting attribute values, and deleting the record.

To close an open record, call dsCloseRecord.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServices.h

dsReleaseContinueData

Releases memory allocated for continuation data.

tDirStatus dsReleaseContinueData (
   tDirReference inDirReference,
   tContextData inContinueData
);

Parameters

inDirReference: On input, a value of type tDirReference if the inContinueData parameter was generated by, for example, dsGetRecordList, dsGetDirNodeInfo, dsDoAttributeValueSearch, or dsDoAttributeValueSearchWithData. This parameter is a value of type tDirReference if the inContinueData parameter was generated by, for example, dsGetDirNodeList or dsFindDirNodes.
inContinueData: On input, a value of type tContextData that is to be released.
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 releases the memory allocated for continuation data. Continuation data is returned when any Open Directory function cannot return all of the requested information in one call, such as dsDoDirNodeAuth, dsFindDirNodes, dsGetDirNodeInfo, dsGetDirNodeList, dsGetRecordList, dsDoAttributeValueSearch, or dsDoAttributeValueSearchWithData.

If your application does not call again the function that returned the continuation data and provide to it the continuation data, your application should call dsReleaseContinueData to free the memory allocated to the continuation data.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

NetworkAuthentication

Declared In

DirServices.h

dsRemoveAttribute

Removes an attribute from a record.

tDirStatus dsRemoveAttribute (
   tRecordReference inRecordReference,
   tDataNodePtr inAttribute
);

Parameters

inRecordReference: On input, a value of type tRecordReference obtained by previously calling dsOpenRecord.
inAttribute: 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 removed.
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 removes the specified attribute from the specified record. Any attribute value list references, attribute value entry structures, and attribute entry structures that have been created for this attribute are still valid because they use a buffer that has already been filled with data. Calling dsGetRecordAttributeValueByID, dsGetRecordAttributeValueByIndex, or dsGetRecordAttributeValueByValue after the attribute has been removed generates an error because the attribute no longer exists.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServices.h

dsRemoveAttributeValue

Removes an attribute value.

tDirStatus dsRemoveAttributeValue (
   tRecordReference inRecordReference,
   tDataNodePtr inAttributeType,
   UInt32 inAttributeValueID
);

Parameters

inRecordReference: On input, a value of type tRecordReference obtained by previously calling dsOpenRecord that represents the record having an attribute whose value is to be removed.
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 whose value is to be removed.
inAttributeValueID: On input, a value of type unsigned long that specifies the attribute value ID of the attribute whose value is to be removed. Call dsGetAttributeValue to get the attribute value ID.
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 removes the value of the attribute that has the type specified by the data node pointed to by inAttributeType and the attribute value ID specified by inAttributeValueID for the record represented by inRecordReference. Any attribute value list references, attribute value entry structures, and attribute entry structures that have been created for the removed attribute are still valid because they manage offsets into a buffer that already contains data. Calling dsGetRecordAttributeValueByID, dsGetRecordAttributeValueByIndex, or dsGetRecordAttributeValueByValue after the attribute has been removed generates an error because the attribute no longer exists.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServices.h

dsSetAttributeValue

Sets the value of an attribute.

tDirStatus dsSetAttributeValue (
   tRecordReference inRecordReference,
   tDataNodePtr inAttributeType,
   tAttributeValueEntryPtr inAttributeValuePtr
);

Parameters

inRecordReference: On input, value of type tRecordReference obtained by previously calling dsOpenRecord representing the record that has an attribute whose value is to be set.
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 whose value is to be set.
inAttributeValuePtr: On input, a value of type tAttributeValueEntryPtr that points to a tAttributeValueEntry structure created by calling dsAllocAttributeValueEntry that contains the value that is to be set and its attribute value ID. The attribute value ID is the ID of an existing value of this attribute for the record specified by inRecordReference obtained by calling dsGetRecordAttributeValueByIndex, dsGetRecordAttributeValueByValue, or dsGetAttributeValue.
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 uses an attribute value ID to replace an existing attribute value with a new value. If the attribute is a multi-value attribute, this function sets only the value of the attribute specified by the attribute value ID without affecting any other values. Unlike dsSetAttributeValues, this function does not create an attribute if it does not already exist.

The inAttributeType parameter points to a data node that specifies the type of the attribute whose value is to be set, and inAttributeValuePtr points to an attribute entry structure that contains the value that is to be set and the value’s attribute value ID.

When you no longer need inAttributeValuePtr, you should call dsDeallocAttributeValueEntry to release the memory associated with it.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServices.h

dsSetAttributeValues

Sets multiple values for an attribute.

tDirStatus dsSetAttributeValues (
   tRecordReference inRecordReference,
   tDataNodePtr inAttributeType,
   tDataListPtr inAttributeValuesPtr
);

Parameters

inRecordReference: On input, value of type tRecordReference obtained by previously calling dsOpenRecord representing the record whose values are to be set.
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 whose values are to be set.
inAttributeValuesPtr: On input, a value of type tDataListPtr that points to the list of values that are to be set.
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 sets multiple values for the attribute specified by inAttributeType for the record specified by inRecordReference. This function replaces all of the values of the attribute with a new list of values. If the attribute does not exist, it is created with the specified list of values.

The inAttributeType parameter points to a data node that specifies the type of the attribute whose values are to be set, and inAttributeValuesPtr points to a list of values that are to be set.

You should call dsDeallocAttributeValueEntry to release the memory associated with inAttributeValuesPtr when you no longer need it.

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

Version Notes

Introduced in Mac OS X v10.4.

Availability

Available in Mac OS X v10.4 and later.

Declared In

DirServices.h

dsSetRecordName

Sets the name of a record.

tDirStatus dsSetRecordName (
   tRecordReference inRecordReference,
   tDataNodePtr inNewRecordName
);

Parameters

inRecordReference: On input, value of type tRecordReference obtained by previously calling dsOpenRecord or dsCreateRecordAndOpen that represents the record whose name is to be set.
inNewRecordName: On input, a value of type tDataNodePtr that points to a tDataNode structure allocated by calling dsDataNodeAllocateBlock or dsDataNodeAllocateString containing the record name in UTF-8 format that is to be set.
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 sets the name of a record.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServices.h

dsSetRecordType

Sets the type of a record.

tDirStatus dsSetRecordType (
   tRecordReference inRecordReference,
   tDataNodePtr inNewRecordType
);

Parameters

inRecordReference: On input, value of type tRecordReference obtained by previously calling dsOpenRecord that represents the record whose type is to be set.
inNewRecordType: On input, a value of type tDataNodePtr that points to a tDataNode structure allocated by calling dsDataNodeAllocateBlock or dsDataNodeAllocateString containing the record type that is to be set.
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 deprecated function sets a record’s type. For record type constants, see Pattern Matching Constants. Not all plug-ins support setting a record’s type.

Version Notes

Deprecated in Mac OS X v10.2.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.2.

Declared In

DirServices.h

dsVerifyDirRefNum

Verifies that a tDirReference is valid.

tDirStatus dsVerifyDirRefNum (
   tDirReference inDirReference
);

Parameters

inRecordReference: On input, the tDirReference that is to be verified.
function result: A value of type tDirStatus indicating that the tDirReference is valid (eDSNoErr) or an error. For a list of possible result codes, see “Result Codes.”

Discussion

This function verifies that a tDirReference is valid.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServices.h

Initialize

Initializes the plug-in.

ComponentResult ADD_IMAGECODEC_BASENAME() Initialize

Parameters

return result: Value of type long. If the Initialize routine completes successfully, it should return eDSNoErr. If it encounters an error, it should return ePlugInInitError.

Discussion

The DirectoryService daemon calls a plug-in’s Initialize entry point so that the plug-in can initialize and prepare itself to run. The plug-in might, for example, open network ports and any files it requires.

An Open Directory plug-in’s Initialize routine is called only once after all Open Directory plug-ins that can be loaded are loaded. If the plug-in cannot initialize itself and returns ePlugInInitError, the plug-in remains in the “failed to init” state.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ImageCodec.k.h

PeriodicTask

Performs a periodic task.

long PeriodicTask (void);

Parameters

return result: Value of type long. If the PeriodicTask routine completes successfully, it should return eDSNoErr. If it encounters an error, it should return ePlugInPeriodicTaskError.

Discussion

The DirectoryService daemon calls a plug-in’s PeriodicTask entry point every two minutes. The plug-in can use its PeriodicTask routine to perform tasks that need to be performed on a recurring basis. If a plug-in has no tasks for its PeriodicTask routine to perform, the PeriodicTask routine should immediately return a result code of eDSNoErr.

Plug-ins that do not implement their own thread management may want to use the PeriodicTask routine to perform a task on a regular basis.

For another way of setting timers, see sHeader.

ProcessRequest

Processes requests.

long ProcessRequest (void *inData);

Parameters

inData: Pointer to an arbitrary value containing the request that is to be processed.
return result: Value of type long. If the ProcessRequest routine completes successfully, it should return eDSNoErr. If it encounters an error, it should return an appropriate result code as described in “Result Codes.”

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point when Open Directory client applications make requests for directory service. The inData parameter points to the request, which consists of a structure whose first byte always identifies the type of request. The remaining fields of the structure vary depending on the request type.

SetPluginState

Sets the plug-in’s state.

long SetPluginState (unsigned long inNewState);

Parameters

inNewState: A value of type unsigned long that describes the plug-in’s new state. See the ePluginState Constants enumeration for appropriate values.
return result: Value of type long. If the SetPluginState routine completes successfully, it should return eDSNoErr. If it encounters an error, it should return an appropriate result code as described in “Result Codes.”

Discussion

The DirectoryService daemon calls a plug-in’s SetPluginState entry point to inform the plug-in that its state has changed to the state specified by the inNewState parameter.

Shutdown

Prepares the plug-in for shut down.

long Shutdown (void);

Parameters

return result: Value of type long. If the Shutdown routine completes successfully, it should return eDSNoErr. If it encounters an error, it should return an appropriate result code as described in “Result Codes.”

Discussion

The DirectoryService daemon calls a plug-in’s Shutdown entry point so that the plug-in can prepare itself for shut down. The plug-in should close any files that it opened, close network connections that it opened, and deallocate memory that it allocated for its use while it was running.

Validate

Validates the plug-in.

ComponentResult ADD_GRAPHICSIMPORT_BASENAME() Validate

Parameters

inSignature: Value of type unsigned long that uniquely identifies the plug-in.
return result: Value of type long. If the Validate routine completes successfully, it should return eDSNoErr. If it encounters an error, it should return an appropriate result code as described in “Result Codes.”

Discussion

The DirectoryService daemon calls a plug-in’s Validate routine after the plug-in loads in order to pass to the plug-in a unique signature. The plug-in uses the signature to identify itself when it calls any of the Open Directory callback routines, which are described in the section PeriodicTask.

Availability

Available in Mac OS X v10.1 and later.

Declared In

ImageCompression.k.h

Callbacks

This section describes Open Directory callback routines that Open Directory plug-ins can call.

DSDebugLog

Writes information in the log file.

sInt32 DSDebugLog (
   const char *inFormat,
   va_list inArgs);

Parameters

inFormat: Pointer to a character array that specifies the format that is to be used to write the data. For additional information, see sprintf(3).
inArgs: Value of type va_list that specifies the values that are to be written in the format specified by inFormat.
return result: Value of type sInt32. If the DSDebugLog callback routine completes successfully, it returns eDSNoErr. If the DSDebugLog callback routine cannot complete successfully, it returns an appropriate result code as described in “Result Codes.”

Discussion

The DSDebugLog callback routine writes the data specified by inArgs using the format specified by inFormat in the Open Directory log file, /Library/Logs/DirectoryService/DirectoryService.debug.log.

A wrapper function, CShared:LogIt, is also available writing to the log file. See the sample code for an example of its use.

DSRegisterNode

Registers a node.

long DSRegisterNode (
   unsigned long inSignature,
   tDataList *inNode,
   eDirNodeType inNodeType);

Parameters

inSignature: Value of type unsigned long obtained by the plug-in when its Validate routine was called and that uniquely identifies the plug-in.
inNode: Pointer to a value of type tDataList that specifies the name of the node that is to be registered.
inNodeType: Value of type eDirNodeType that specifies the type of the node that is to be registered. See the Discussion section below for possible values.
return result: Value of type unsigned long. If the DSRegisterNode callback routine completes successfully, it returns eDSNoErr. If the DSRegisterNode callback routine cannot complete successfully (for example, if the specified node is already registered or if inNode contains a node name that has invalid characters), it returns an appropriate result code as described in “Result Codes.”

Discussion

The DSRegisterNode callback routine registers the specified node.

The eDirNodeType enumeration defines values for the inNodeType parameter:

typedef enum {     kUnknownNodeType= 0x00000000,     kDirNodeType    = 0x00000001,     kLocalNodeType  = 0x00000002 } eDirNodeType;

The local node (kLocalNodeType) is queried by default in response to an Open Directory request and is always the first node that is queried. Only one node can be registered as the local node at any one time. A directory node (kDirNodeType) is any other node that is to be registered for Open Directory.

Registrations are valid for the period of time that Open Directory is running. If Open Directory stops and is started again, the node must be registered again.

The plug-in is responsible for keeping the list of registered nodes accurate. It can use the PeriodicTask entry point to update the list on a regular basis.

DSUnregisterNode

Unregisters a node.

long DSUnregisterNode (
   unsigned long inSignature,
   tDataList *inNode);

Parameters

inSignature: Value of type unsigned long obtained by the plug-in when its Validate routine was called and that uniquely identifies the plug-in.
inNode: Pointer to a value of type tDataList that specifies the name of the node that is to be unregistered.
result: Value of type unsigned long. If the DSUnregisterNode callback routine completes successfully, it returns eDSNoErr. If the DSUnregisterNode callback routine cannot complete successfully, it returns an error.

Discussion

The DSUnregisterNode callback routine unregisters the specified node.

Data Types

Open Directory Structures

This section describes structures used by the Open Directory client.

tAttributeEntry

A structure used to store information about an attribute.

typedef struct
{
unsigned long fReserved1;
tAccessControlEntry fReserved2;
unsigned long fAttributeValueCount;
unsigned long fAttributeDataSize;
unsigned long fAttributeValueMaxSize;
tDataNode fAttributeSignature;
} tAttributeEntry;
typedef tAttributeEntry *tAttributeEntryPtr;

Fields

fReserved1: Reserved.
fReserved2: Reserved.
fAttributeValueCount: Number of values associated with this attribute.
fAttributeDataSize: Total byte count of all attribute values.
fAttributeValueMaxSize: Maximum size of a value of this attribute type.
fAttributeSignature: Byte sequence that uniquely represents this attribute type. The byte sequence is typically a collection of Unicode characters.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServicesTypes.h

tAttributeValueEntry

A structure used to get and set the value of an attribute by attribute value ID.

typedef struct
{
unsigned long fAttributeValueID;
tDataNode fAttributeValueData;
} tAttributeValueEntry;

Fields

fAttributeValueID: Unique ID for this attribute value.
fAttributeValueData: Value of type tDataNode containing the value of this attribute.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServicesTypes.h

tDataBuffer

A structure that provides a standard format for passing information between Open Directory and applications.

typedef struct
{
unsigned long fBufferSize;
unsigned long fBufferLength;
char fBufferData[1];
} tDataBuffer;

Fields

fBufferSize: Number of bytes allocated for this structure. The value of fBufferSize should be set when tDataBuffer is created.
fBufferLength: Number of meaningful bytes in fBufferData. You should call dsDataNodeSetLength to adjust this value each time you change the value of the fBufferData field.
fBufferData: Array of characters.

Discussion

A tDataBuffer structure is typically used to exchange strings, node names, and attribute types. Call dsDataBufferAllocate to allocate a data buffer. Call dsDataBufferDeAllocate to release the memory associated with a data buffer when it is no longer needed.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServicesTypes.h

tDataList

An ordered list of tDataNode structures.

typedef struct
{
unsigned long fDataNodeCount;
tDataNodePtr fDataListHead;
} tDataList;

Fields

fDataNodeCount: Number of data nodes in this data list structure.
fDataListHead: First pointer to a data node in this data list structure.

Discussion

This structure is used to represent lists of items, such as nodes, full pathnames, attribute type lists, and lists of record names. All items in a data list must be in UTF-8 format.

Do not manipulate tDataList structures directly. Instead, use the data list utility functions such as dsBuildFromPath, dsDataListAllocate, dsDataListGetNodeAlloc, dsAppendStringToListAlloc, and dsDataListDeallocate.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServicesTypes.h

tRecordEntry

A structure used to store information about a record, including its name, type, and number of attributes.

typedef struct
{
unsigned long fReserved1;
tAccessControlEntry fReserved2;
unsigned long fRecordAttributeCount;
tDataNode fRecordNameAndType;
}   tRecordEntry;

Fields

fReserved1: Reserved.
fReserved2: Reserved.
fRecordAttributeCount: Number of attribute types.
fRecordNameAndType: Value of type tDataNode containing the record’s primary name in UTF-8 format and its type.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServicesTypes.h

Other Open Directory Data Types

Data types used by the Open Directory Client.

tAttributeEntryPtr

A pointer to a tAttributeEntry structure.

typedef tAttributeEntry *tAttributeEntryPtr;

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServicesTypes.h

tAttributeListRef

A reference used to get attribute entries.

typedef unsigned long tAttributeListRef;

Discussion

You receive a tAttributeListRef by calling dsGetDirNodeInfo or dsGetRecordEntry.Pass the reference to dsGetAttributeEntry. Dispose of the reference by calling dsCloseAttributeList.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServicesTypes.h

tAttributeValueEntryPtr

A pointer to a tAttributeValueEntry structure.

typedef tAttributeValueEntry *tAttributeValueEntryPtr;

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServicesTypes.h

tAttributeValueListRef

A reference used to get attribute value entries.

typedef unsigned long tAttributeValueListRef;

Discussion

You receive a tAttributeValueListRef when you call dsGetAttributeEntry. Pass the reference to dsGetAttributeValue. Dispose of the reference by calling dsCloseAttributeValueList.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServicesTypes.h

tBuffer

A pointer to an arbitrary value used to create data nodes.

typedef void * tBuffer;

Discussion

The tBuffer data type is used by dsDataNodeAllocateBlock to create data nodes.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServicesTypes.h

tContextData

A pointer to an arbitrary value used to exchange continuation data.

typedef void * tContextData;

Discussion

When the results of calling an Open Directory function exceed the size of the response buffer, the function returns a value of type tContextData. Your application can get the next buffer of results by calling the function again and passing the continuation data as a parameter.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServicesTypes.h

tDataBufferPtr

A pointer to a value of type tDataBuffer.

typedef tDataBuffer *tDataBufferPtr;

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServicesTypes.h

tDataListPtr

A pointer to a value of type tDataList.

typedef tDataList *tDataListPtr;

Discussion

To allocate a data list, call dsDataListAllocate. To build a data list from one or more data nodes, call dsBuildListFromNodesAlloc; to build a data list from one or more C strings, call dsBuildListFromStrings. Or copy a data list by calling dsDataListCopyList.

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

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServicesTypes.h

tDataNode

A value of type tDataBuffer.

typedef tDataBuffer tDataNode;

Discussion

The tDataNode data type provides a standard format for passing information to Open Directory functions. It is typically used to contain strings, nodes, and attribute types that are exchanged between Open Directory and an Open Directory client.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServicesTypes.h

tDataNodePtr

A pointer to a value of type tDataNode.

typedef tDataNode tDataNodePtr;

Discussion

Call dsDataNodeAllocateBlock or dsDataNodeAllocateString to allocate a data node.

Call dsDataNodeDeAllocate to release the memory associated with a data node when it is no longer needed.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServicesTypes.h

tDirNodeReference

A value returned when a node is opened.

typedef unsigned long tDirNodeReference;

Discussion

Open Directory functions that operate on nodes, records, and attributes require a tDirNodeReference as a parameter. Call dsOpenDirNode to open a node. Call dsCloseDirNode to close the node and dispose of the reference when you no longer need it.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServicesTypes.h

tDirReference

A value returned when an Open Directory session is opened.

typedef unsigned long tDirReference;

Discussion

You receive a tDirReference by calling by dsOpenDirService or dsOpenDirServiceProxy to open an Open Directory session. You call dsCloseDirService to close the session and dispose of the reference when you no longer need it.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServicesTypes.h

tRecordEntryPtr

A pointer to a value of type tRecordEntry.

typedef tRecordEntry *tRecordEntryPtr;

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServicesTypes.h

tRecordReference

A value returned when a record is opened.

typedef unsigned long tRecordReference;

Discussion

You receive a tRecordReference by calling dsCreateRecordAndOpen or dsOpenRecord. Closing the record causes the record reference to be invalidated.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DirServicesTypes.h

Request Structures

This section describes the structures that Open Directory passes to a plug-in’s ProcessRequest entry point in order to work with directory nodes.

sAddAttribute

Structure received when an Open Directory client calls dsAddAttribute.

typedef struct {
uInt32              fType;
sInt32              fResult;
tRecordReference    fInRecRef;
tDataNodePtr        fInNewAttr;
tAccessControlEntryPtrfInNewAttrAccess;
tDataNodePtr        fInFirstAttrValue;
} sAddAttribute;

Fields

fType: Always kAddAttribute.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to add the attribute. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”
fInRecRef: Value of type tRecordReference representing the record to which the attribute is to be added. The record must have been previously opened when the plug-in’s routine for processing sOpenRecord structures was called.
fInNewAttr: Value of type tDataNodePtr that points to a value of type tDataNode containing the name of the attribute that is to be added.
fInNewAttrAccess: Reserved for this release. Client applications are advised to set this value to NULL. For this release, plug-ins should ignore the value of this field.
fInFirstAttrValue: Value of type tDataListPtr that points to a value of type tDataNode containing the first value of the attribute that is being added. The tDataNode may contain an empty string or fInFirsAttrValue may be NULL to indicate that the client application does not want to set the attribute’s value.

Discussion

When an Open Directory plug-in receives an sAddAttribute structure, it uses the fInRecRef field of the sAddAttribute structure to determine the record to which an attribute is to be added, the fInNewAttr field to obtain the name of the attribute that is to be added, and the fInFirstAttrValue field as the added attribute’s first value.

If the plug-in can the add the attribute, it adds the attribute, sets its first value, sets fResult to eDSNoErr, and returns.

If the plug-in cannot add the attribute, it sets fResult to an appropriate result code as described in “Result Codes” and returns.

sAddAttributeValue

Structure when an Open Directory client calls dsAddAttributeValue.

typedef struct {
uInt32          fType;
sInt32          fResult;
tRecordReferencefInRecRef;
tDataNodePtr    fInAttrType;
tDataNodePtr    fInAttrValue;
} sAddAttributeValue;

Fields

fType: Always kAddAttributeValue.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to add the value to the attribute. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”
fInRecRef: Value of type tRecordReference representing the record for which a value is to be add to an attribute.
fInAttrType: Value of type tDataNodePtr that points to a value of type tDataNode containing the type of the attribute to which a value is to be added.
fInAttrValue: Value of type tDataNodePtr that points to a value of type tDataNode containing the value that is to be added.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sAddAttributeValue structure when an Open Directory client calls dsAddAttributeValue.

The plug-in should verify that the attribute is capable of having multiple values. It then uses the fInRecRef field of the sAddAttributeValue structure to determine the record that has the attribute to which a value is to be added, the fInAttrType field to determine the type of the attribute to which a value is to be added, and the fInAttrValue field to get the value to that is to be added.

If the plug-in can add the specified value to the specified attribute, it adds the value and creates a unique attribute value ID for it, sets fResult to eDSNoErr, and returns.

If the plug-in cannot add the value to the attribute, it sets fResult to an appropriate result code as described in “Result Codes” and returns.

sCloseAttributeList

Structure received when an Open Directory client calls dsCloseAttributeList.

typedef struct {
uInt32          fType;
sInt32          fResult;
tAttributeListReffInAttributeListRef;
} sCloseAttributeList;

Fields

fType: Always kCloseAttributeList.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to close the specified attribute list reference. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”
fInAttributeListRef: Value of type tAttributeListRef representing the attribute list reference that is to be closed.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sCloseAttributeList structure when an Open Directory client calls dsCloseAttributeList to dispose of an attribute list reference.

If the attribute value list is valid, the plug-in disposes of it, sets fResult to eDSNoErr, and returns. If the attribute list reference is invalid, the plug-in sets fResult to an appropriate result code as described in “Result Codes” and returns.

sCloseAttributeValueList

Structure received when an Open Directory client calls dsCloseAttributeValueList.

typedef struct {
uInt32                  fType;
sInt32                  fResult;
tAttributeValueListReff InAttributeValueListRef;
} sCloseAttributeValueList;

Fields

fType: Always kCloseAttributeValueList.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to close the specified attribute value list reference. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”
fInAttributeValueListRef: Value of type tAttributeValueListRef representing the attribute value list reference that is to be closed.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sCloseAttributeValueList structure when an Open Directory client calls dsCloseAttributeValueList to dispose of an attribute value list reference.

If the attribute value list reference is valid, the plug-in disposes of it, sets fResult to eDSNoErr, and returns. If the attribute value list reference is invalid, the plug-in sets fResult to an appropriate result code as described in “Result Codes” and returns.

sCloseDirNode

Structure received when an Open Directory client calls dsCloseDirNode.

typedef struct {
uInt32          fType;
sInt32          fResult;
tDirReference   fInNodeRef;
} sCloseDirNode;

Fields

fType: Always kCloseDirNode.
fResult: Value of type sInt32s that the plug-in sets to eDSNoErr before returning to indicate that it was able to close the directory node session specified by fInNodeRef. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”
fInNodeRef: Value of type tDirReference that identifies the directory node session that is to be closed. The directory node reference was created when the client application opened the directory node session that is to be closed.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sCloseDirNode structure when an Open Directory client calls dsCloseDirNode to close a session with a directory node.

When an Open Directory plug-in receives a request to close a directory node session, it uses the fInNodeRef field to determine whether fInNodeRef represents a valid directory node that the client application has opened.

If the directory node reference is valid, the plug-in invalidates all record references, attribute references, attribute value references, and continuation data values that are associated with the directory node reference specified by fInNodeRef. The plug-in sets fResult to eDSNoErr and returns.

If the plug-in cannot close the node (for example, because it is invalid), it sets fResult to an appropriate result code as described in “Result Codes” and returns.

sCloseRecord

Structure received when an Open Directory client application calls dsCloseRecord.

typedef struct {
uInt32          fType;
sInt32          fResult;
tRecordReferencefInRecRef;
} sCloseRecord;

Fields

fType: Always kCloseRecord.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to close the record. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”
fInRecRef: Value of type tRecordReference representing the record that is to be closed. The plug-in created the value of fInRecRef when it was called to process a request to open the record.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sCloseRecord structure when an Open Directory client calls dsCloseRecord to close a record.

If the record can be closed, the plug-in ensures that any changes for the record that are cached in memory are saved to disk, invalidates the record reference specified in the fInRecRef field, invalidates any attribute list references and any attribute value list references associated with the record, sets fResult to eDSNoErr, and returns.

If the plug-in cannot close the record, it sets fResult to an appropriate result code as described in “Result Codes” and returns.

sCreateRecord

Structure received when an Open Directory client calls dsCreateRecord or dsCreateRecordAndOpen.

typedef struct {
uInt32              fType;
sInt32              fResult;
tDirNodeReference   fInNodeRef;
tDataNodePtr        fInRecType;
tDataNodePtr        fInRecName;
bool                fInOpen;
tRecordReference    fOutRecRef;
} sCreateRecord;

Fields

fType: Always kCreateRecord or kCreateRecordAndOpen.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to create the record. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”
fInNodeRef: Value of type tDirNodeReference that identifies the directory node in which the record is to be created. The directory node reference was created when the client application opened a session with the directory node.
fInRecType: Value of type tDataNodePtr that points to a tDataNode structure containing the type that is to be assigned to the created record.
fInRecName: Value of type tDataNodePtr that points to a tDataNode structure containing the name that is to be assigned to the record that is created.
fInOpen: Boolean whose value is TRUE if the client application wants to create the record and open it. Otherwise, the value of fInOpen is FALSE to indicate that the client application wants to create the record without opening it.
fOutRecRef: Value of type tRecordReference assigned by the DirectoryService daemon and that the plug-in associates with the internal structure the plug-in uses to maintain information about the reference.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sCreateRecord structure when an Open Directory client calls dsCreateRecordor dsCreateRecordAndOpen to create a record.

The plug-in uses the fInNodeRef field of the sCreateRecord structure to determine the directory node in which the record is to be created, the fInRecType field to set the type of the record that is to be created, and the fInRecName field to set the name of the record that is to be created.

If the plug-in can create the new record, it sets fResult to eDSNoErr, and returns.

If the plug-in cannot create the new record, it sets fResult to an appropriate result code as described in “Result Codes” and returns.

sDeleteRecord

Structure received when an Open Directory client calls dsDeleteRecord.

typedef struct {
uInt32          fType
sInt32          fResult;
tRecordReferencefInRecRef;
} sDeleteRecord;

Fields

fType: Always kDeleteRecord.
fResult: Value of type uInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to delete the record. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”
fInRecRef: Value of type tRecordReference representing the record that is to be deleted. The plug-in created the value of fInRecRef when it was called to process a request to open the record.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sDeleteRecord structure when an Open Directory client calls dsDeleteRecord to delete a record.

The plug-in uses the fInRecRef field of the sDeleteRecord structure to determine the record that is to be deleted. If the plug-in can delete the record, it invalidates the record reference specified by the fInRecRef field, invalidates any attribute list references and any attribute value list references associated with the record, sets fResult to eDSNoErr, and returns.

If the plug-in cannot delete the record, it sets fResult to an appropriate result code as described in “Result Codes” and returns.

sDoAttrValueSearch

Structure received when an Open Directory client calls dsDoAttributeValueSearch.

typedef struct {
uInt32          fType;
sInt32          fResult;
tDirNodeReferencefInNodeRef;
tDataBufferPtr  fOutDataBuff;
tDataListPtr    fInRecTypeList;
tDataNodePtr    fInAttrType;
tDirPatternMatchfInPattMatchType;
tDataNodePtr    fInPatt2Match;
unsigned long   fInOutMatchRecordCount;
tContextData    fIOContinueData;
} sDoAttrValueSearch;

Fields

fType: Always kDoAttributeValueSearch.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to search for the attribute values. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.” If no matches are found, the plug-in should set fResult to eDSNoErr, fInOutMatchRecordCount to zero, and fIOContinueData to NULL.
fInNodeRef: Value of type tDirNodeReference that identifies the directory node for which the search is to be conducted. The directory node reference was created when the client application opened the directory node session.
fOutDataBuff: Value of type tDataBufferPtr that points to the tDataBuffer structure in which the plug-in is to place search results.
fInRecTypeList: Value of type tDataListPtr pointing to a tDataList structure containing the record types that are to be searched. See Standard Record Types and Meta Record Type Constants for possible values. If NULL, set fResult to eDSEmptyRecordTypeList and return.
fInAttrType: Value of type tDataNodePtr pointing to a tDataNode structure containing the attribute types that are to be searched for. See the attribute constants described in the “Constants” section for possible values. If NULL, set fResult to eDSEmptyAttributeType and return.
fInPattMatchType: Value of type tDirPatternMatch that describes the way in which the pattern specified by fInPatt2Match is to be matched. The pattern match type can be a value that the plug-in and application agree upon or a constant defined by Open Directory, as described in the section Pattern Matching Constants.
fInPatt2Match: Value of type tDataNodePtr pointing to a tDataNode structure containing the pattern that is to be matched.
fInOutMatchRecordCount: Value of type unsigned long. The first time the client application calls dsDoAttributeValueSearch, fInOutMatchRecordCount is zero to receive all matching records or is a positive integer value that specifies the total number of records the client application wants to receive across what may be a series of dsDoAttributeValueSearch calls. If the latter, the plug-in should use the initial input value of fInOutMatchRecordCount to limit the total number of matching records it returns. Before returning, the plug-in should set fInOutMatchRecordCount to the number of records it has placed in the buffer pointed to by fOutDataBuff. The plug-in should ignore the input value of fInOutMatchRecordCount whenever it is processing a sDoAttrValueSearch structure that has an fIOContinueData field that is not NULL.
fIOContinueData: Value of type tContextData containing continuation data. For the first in a series of calls to dsDoAttributeValueSearch, the input value is NULL. If the plug-in can store all of the matching records in the buffer pointed to by fOutDataBuff, it sets fIOContinueData to NULL before returning. If there more records than can be stored in the buffer, the plug-in stores as much data as possible and sets fIOContinueData to a plug-in–defined value that the plug-in can use when the client application calls dsDoAttributeValueSearch again to get another buffer of data. You may want to include a timestamp in the continuation data and return an error if you determine that fOutContinueData is out of date.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sDoAttrValueSearch structure when an Open Directory client calls dsDoAttributeValueSearch to search for records that have attributes whose values match a pattern.

The plug-in uses the fInNodeRef field of the sDoAttrValueSearch structure to determine the directory node in which the search is to be conducted, the fInRecTypeList field to determine the record types that are to be searched, the fInAttrType field to determine the attribute types that are to be searched, the fInPatt2Match field to get the pattern to match, and the fInPattMatchType field to determine the way in which the pattern is to be compared. If this is the first in what may be a series of calls to get the complete search results, the fIOContinueData field is NULL. Otherwise, fIOContinueData contains a plug-in–defined value that the plug-in uses to provide the context required to resume filling the buffer pointed to by fOutDataBuff with search results.

Depending on the size of the data buffer pointed to by fOutDataBuff and the length of the search results, the plug-in’s routine for processing sDoAttrValueSearch structures may be called multiple times in order to return all of the search results. The first time the plug-in’s routine for processing sDoAttrValueSearch structures is called, the input value of fIOContinueData is NULL and input value of fInOutRecEntryCount specifies the total number of records that the plug-in should return even if the plug-in’s routine for processing sDoAttrValueSearch structures must be called more than once.

If there are records that match the search criteria specified by fInRecTypeList, fInAttrType, fInPattMatchType, and fInPatt2Match, the plug-in puts the record entries, attribute entries, and attribute values in the buffer pointed to by fOutDataBuff. It also sets fInOutMatchRecordCount to the number of records that have been placed in fOutDataBuff and sets fResult to eDSNoErr. If the buffer pointed to by fOutDataBuff is too small to hold all of the data, the plug-in sets fIOContinueData to a plug-in–defined value that the plug-in can use when the client application calls dsDoAttributeValueSearch again to get another buffer of data. If the buffer pointed to by fOutDataBuff contains all of the records or contains the last records in the record list, the plug-in sets fIOContinueData to NULL.

If the plug-in returns before it gets search results to place in the buffer pointed to by fOutDataBuff, it should set fInOutMatchRecordCount to zero, set fResult to eDSNoErr, and set fIOContinueData to a plug-in–defined value that is not NULL. These settings indicate to the client application that it should call dsDoAttributeValueSearch again to get the search results.

If there are no matching records, the plug-in sets fInOutMatchRecordCount to zero, fIOContinueData to NULL, sets fResult to eDSNoErr, and returns.

sDoAttrValueSearchWithData

Structure received when an Open Directory client calls dsDoAttributeValueSearchWithData.

typedef struct {
uInt32          fType;
sInt32          fResult;
tDirNodeReferencefInNodeRef;
tDataBufferPtr  fOutDataBuff;
tDataListPtr    fInRecTypeList;
tDataNodePtr    fInAttrType;
tDirPatternMatchfInPattMatchType;
tDataNodePtr    fInPatt2Match;
unsigned long   fInOutMatchRecordCount;
tContextData    fIOContinueData;
tDataListPtr    fInAttrTypeRequestList;
bool            fInAttrInfoOnly;
} sDoAttrValueSearchWithData;

Fields

fType: Always kDoAttributeValueSearchWithData.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to search for the attribute values. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.” If no matches are found, the plug-in should set fResult to eDSNoErr, fInOutMatchRecordCount to zero, and fIOContinueData to NULL.
fInNodeRef: Value of type tDirNodeReference that identifies the directory node for which the search is to be conducted. The directory node reference was created when the client application opened the directory node session.
fOutDataBuff: Value of type tDataBufferPtr that points to the tDataBuffer structure in which the plug-in is to place search results.
fInRecTypeList: Value of type tDataListPtr pointing to a tDataList structure containing the record types that are to be searched. See Standard Record Types and Meta Record Type Constants for possible values. If NULL, set fResult to eDSEmptyRecordTypeList and return.
fInAttrType: Value of type tDataNodePtr pointing to a tDataNode structure containing the attribute types that are to be searched for. See the attribute constants described in the “Constants” section for possible values. If NULL, set fResult to eDSEmptyAttributeType and return.
fInPattMatchType: Value of type tDirPatternMatch that describes the way in which the pattern specified by fInPatt2Match is to be matched. The pattern match type can be a value that the plug-in and application agree upon or a constant defined by Open Directory, as described in the section Pattern Matching Constants.
fInPatt2Match: Value of type tDataNodePtr pointing to a tDataNode structure containing the pattern that is to be matched.
fInOutMatchRecordCount: Value of type unsigned long. The first time the client application calls dsDoAttributeValueSearchWithData, fInOutMatchRecordCount is zero to receive all matching records or is a positive integer value that specifies the total number of records the client application wants to receive across what may be a series of dsDoAttributeValueSearchWithData calls. If the latter, the plug-in should use the initial input value o ffInOutMatchRecordCount to limit the total number of matching records it returns. Before returning, the plug-in should set fInOutMatchRecordCount to the number of records it has placed in the buffer pointed to by fOutDataBuff. The plug-in should ignore the input value of fInOutMatchRecordCount whenever it is processing a sDoAttributeValueSearchWithData structure that has an fIOContinueData field that is not NULL.
fIOContinueData: Value of type tContextData containing continuation data. For the first in a series of calls to dsDoAttributeValueSearchWithData, the input value is NULL. If the plug-in can store all of the matching records in the buffer pointed to by fOutDataBuff, it sets fIOContinueData to NULL before returning. If there more records than can be stored in the buffer, the plug-in stores as much data as possible and sets fIOContinueData to a plug-in–defined value that the plug-in can use when the client application calls dsDoAttributeValueSearchWithData again to get another buffer of data. You may want to include a timestamp in the continuation data and return an error if you determine that fOutContinueData is out of date.
fInAttrTypeRequestList: Value of type tDataListPtr pointing to a tDataList structure containing attribute types that are to be returned if matches are found. See the attribute constants described in the “Constants” section for possible values. If NULL, set fResult to eDSEmptyAttributeTypeList and return.
fInAttrInfoOnly: Boolean value set to TRUE if the plug-in is only to provide information about attributes or set to FALSE if the plug-in is to provide the values of the attributes as well as information about the attributes.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sDoAttrValueSearchWithData structure when an Open Directory client calls dsDoAttributeValueSearchWithData to search for records. Matches are based on the value of fInAttrType, fInPattMatchType, and fInPatt2Match. For records that match, the fInAttrTypeRequestList field determines which attributes to return.

The plug-in uses the fInNodeRef field of the sDoAttrValueSearchWithData structure to determine the directory node in which the search is to be conducted, the fInRecTypeList field to determine the record types that are to be searched, the fInAttrType field to determine the attribute types that are to be searched, the fInPatt2Match field to get the pattern to match, and the fInPattMatchType field to determine the way in which the pattern is to be compared. If this is the first in what may be a series of calls to get the complete search results, the fIOContinueData field is NULL. Otherwise, fIOContinueData contains a plug-in–defined value that the plug-in uses to provide the context required to resume filling the buffer pointed to by fOutDataBuff with search results.

The sDoAttrValueSearchWithData structure differs from the sDoAttrValueSearch structure in that the sDoAttrValueSearchWithData structure has two additional fields: fInAttrTypeRequestList, which specifies the type of attributes for which information is to be returned when a match is found, and fInAttrInfoOnly, which indicates whether attribute information or attribute information and attribute values are to be returned when a match is found.

Depending on the size of the data buffer pointed to by fOutDataBuff and the length of the search results, the plug-in’s routine for processing sDoAttrValueSearchWithData structures may be called multiple times in order to return all of the search results. The first time the plug-in’s routine for processing sDoAttrValueSearchWithData structures is called, the input value of fIOContinueData is NULL and input value of fInOutRecEntryCount specifies the total number of records that the plug-in should return even if the plug-in’s routine for processing sDoAttrValueSearchWithData structures must be called more than once.

If there are records that match the search criteria specified by fInRecTypeList, fInAttrType, fInPattMatchType, and fInPatt2Match, plug-in puts the record entries, attribute entries, and attribute values in the buffer pointed to by fOutDataBuff. It also sets fInOutMatchRecordCount to the number of records that have been placed in fOutDataBuff and sets fResult to eDSNoErr. If the buffer pointed to by fOutDataBuff is too small to hold all of the data, the plug-in sets fIOContinueData to a plug-in–defined value that the plug-in can use when the client application calls dsDoAttributeValueSearchWithData again to get another buffer of data. If the buffer pointed to by fOutDataBuff contains all of the records or contains the last records in the record list, the plug-in sets fIOContinueData to NULL.

If there are no matching records, the plug-in sets fInOutMatchRecordCount to zero, fIOContinueData to NULL, sets fResult to eDSNoErr, and returns.

sDoDirNodeAuth

Structure received when an Open Directory client calls dsDoDirNodeAuth.

typedef struct {
uInt32              fType;
sInt32              fResult;
tDirNodeReference   fInNodeRef;
tDataNodePtr        fInAuthMethod;
bool                fInDirNodeAuthOnlyFlag;
tDataBufferPtr      fInAuthStepData;
tDataBufferPtr      fOutAuthStepDataResponse;
tContextData        fIOContinueData;
} sDoDirNodeAuth;

Fields

fType: Always kDoDirNodeAuth.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to authenticate the session. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”
fInNodeRef: Value of type tDirNodeReference that identifies the directory node session that is to be authenticated. The directory node reference was created when the client application opened the session with the directory node.
fInAuthMethod: Value of type tDataNodePtr that points to a tDataNode structure containing the authentication task that is to be performed.Examples include kDSStdAuthSetPasswd, kDSStdAuthSetPasswdAsRoot, and kDSStdAuthChangePasswd to set or change a password and kDSStdAuthClearText and kDSStdAuth2WayRandom to authenticate a user for a directory node session. See the attribute constants described in the “Constants” section for possible values.
fInDirNodeAuthOnlyFlag: Boolean value that is TRUE if the client application does not want the result of this authentication to be used to grant or deny access for subsequent operations pertaining to this node. When the value of fInDirNodeAuthOnlyFlag is FALSE, the client application wants the result of this authentication to be applied to other operations that pertain to this directory node.
fInAuthStepData: Value of type tDataBufferPtr pointing to a tDataBuffer structure that contains a value that identifies the step in the authentication process for which the plug-in ProcessRequest routine has been called.
fOutAuthStepDataResponse: Value of type tDataBufferPtr that points to the tDataBuffer structure in which the plug-in is to place its response.
fIOContinueData: Value of type tContextData. If this the first step in the authentication process, fIOContinueData is NULL. If this is any other step, fIOContinueData should contain a value that the plug-in returned to the client application when the client previously called dsDoDirNodeAuth. The plug-in can use fIOContinueData to maintain context information about the authentication process as it progresses through the various steps required by the authentication method. You may want to include a timestamp in fIOContinueData and fail the next step in the authentication process if fIOContinueData is too old.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sDoDirNoteAuth structure when an Open Directory client calls dsDoDirNodeAuth to perform an authentication task.

The plug-in uses the fInNodeRef field of the sDoDirNodeAuth structure to determine the directory node for which the authentication task is to be perform and the fInAuthMethod field to determine the authentication task. The plug-in also uses the fInDirNodeAuthOnlyFlag field to determine whether to apply the results of the authentication to other Open Directory calls the client application may make, and the fInAuthStepData field indicates the current step in the authentication process.

If this step in the authentication process is successful, the plug-in sets fResult to eDSNoErr. If there are additional steps in the authentication process, the plug-in sets fOutAuthStepDataResponse to a value that is appropriate for this authentication method and sets fIOContinueData to a plug-in–defined value before returning. If this is the last step in the authentication process, the plug-in sets fIOContinueData to NULL.

If this step in the authentication process was not successful, the plug-in sets fResult to an appropriate result code as described in “Result Codes,” sets fIOContinueData to NULL, and returns.

sDoMultiAttrValueSearch

Structure received when an Open Directory client calls dsDoMultipleAttributeValueSearch.

typedef struct {
uInt32          fType;
sInt32          fResult;
tDirNodeReferencefInNodeRef;
tDataBufferPtr  fOutDataBuff;
tDataListPtr    fInRecTypeList;
tDataNodePtr    fInAttrType;
tDirPatternMatchfInPattMatchType;
tDataListPtr    fInPatterns2MatchList;
unsigned long   fInOutMatchRecordCount;
tContextData    fIOContinueData;
} sDoMultiAttrValueSearch;

Fields

fType: Always kDoMultipleAttributeValueSearch.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to search for the attribute values. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.” If no matches are found, the plug-in should set fResult to eDSNoErr, fInOutMatchRecordCount to zero, and fIOContinueData to NULL.
fInNodeRef: Value of type tDirNodeReference that identifies the directory node for which the search is to be conducted. The directory node reference was created when the client application opened the directory node session.
fOutDataBuff: Value of type tDataBufferPtr that points to the tDataBuffer structure in which the plug-in is to place search results.
fInRecTypeList: Value of type tDataListPtr pointing to a tDataList structure containing the record types that are to be searched. See Standard Record Types and Meta Record Type Constants for possible values. If NULL, set fResult to eDSEmptyRecordTypeList and return.
fInAttrType: Value of type tDataNodePtr pointing to a tDataNode structure containing the attribute types that are to be searched for. See the attribute constants described in the “Constants” section for possible values. If NULL, set fResult to eDSEmptyAttributeType and return.
fInPattMatchType: Value of type tDirPatternMatch that describes the way in which the pattern specified by fInPatt2Match is to be matched. The pattern match type can be a value that the plug-in and application agree upon or a constant defined by Open Directory, as described in the section Pattern Matching Constants.
fInPatterns2MatchList: Value of type tDataListPtr pointing to a tDataList structure containing a list of patterns to be matched.
fInOutMatchRecordCount: Value of type unsigned long. The first time the client application calls dsDoAttributeValueSearch, fInOutMatchRecordCount is zero to receive all matching records or is a positive integer value that specifies the total number of records the client application wants to receive across what may be a series of dsDoAttributeValueSearch calls. If the latter, the plug-in should use the initial input value of fInOutMatchRecordCount to limit the total number of matching records it returns. Before returning, the plug-in should set fInOutMatchRecordCount to the number of records it has placed in the buffer pointed to by fOutDataBuff. The plug-in should ignore the input value of fInOutMatchRecordCount whenever it is processing a sDoMultiAttrValueSearch structure that has anfIOContinueData field that is not NULL.
fIOContinueData: Value of type tContextData containing continuation data. For the first in a series of calls to dsDoAttributeValueSearch, the input value is NULL. If the plug-in can store all of the matching records in the buffer pointed to by fOutDataBuff, it sets fIOContinueData to NULL before returning. If there more records than can be stored in the buffer, the plug-in stores as much data as possible and sets fIOContinueData to a plug-in–defined value that the plug-in can use when the client application calls dsDoAttributeValueSearch again to get another buffer of data. You may want to include a timestamp in the continuation data and return an error if you determine that fOutContinueData is out of date.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sDoMultiAttrValueSearch structure when an Open Directory client calls dsDoMultipleAttributeValueSearch to search for records that have attributes whose values match one of multiple specified patterns.

The plug-in uses the fInNodeRef field of the sDoMultiAttrValueSearch structure to determine the directory node in which the search is to be conducted, the fInRecTypeList field to determine the type of records that are to be searched, the fInAttrType field to determine the attributes that are to be searched, the fInPatterns2MatchList field to get the patterns to match, and the fInPattMatchType field to determine the way in which the patterns are to be compared. If this is the first in what may be a series of calls to get the complete search results, the fIOContinueData field is NULL. Otherwise, fIOContinueData contains a plug-in–defined value that the plug-in uses to provide the context required to resume filling the buffer pointed to by fOutDataBuff with search results.

Depending on the size of the data buffer pointed to by fOutDataBuff and the length of the search results, the plug-in’s routine for processing sDoMultiAttrValueSearch structures may be called multiple times in order to return all of the search results. The first time the plug-in’s routine for processing the sDoMultiAttrValueSearch structure is called, the input value of fIOContinueData is NULL and input value of fInOutRecEntryCount specifies the total number of records that the plug-in should return even if the plug-in’s routine for processing sDoMultiAttrValueSearch structures must be called more than once.

If there are records that match the search criteria specified by fInRecTypeList, fInAttrType, fInPattMatchType, and fInPattern2MatchList, the plug-in puts the record entries, attribute entries, and attribute values in the buffer pointed to by fOutDataBuff. It also sets fInOutMatchRecordCount to the number of records that have been placed in fOutDataBuff and sets fResult to eDSNoErr. If the buffer pointed to by fOutDataBuff is too small to hold all of the data, the plug-in sets fIOContinueData to a plug-in–defined value that the plug-in can use when the client application calls dsDoMultipleAttributeValueSearch again to get another buffer of data. If the buffer pointed to by fOutDataBuff contains all of the records or contains the last records in the list of records, the plug-in sets fIOContinueData to NULL.

If the plug-in returns before it gets search results to place in the buffer pointed to by fOutDataBuff, it should set fInOutMatchRecordCount to zero, set fResult to eDSNoErr, and set fIOContinueData to a plug-in–defined value that is not NULL. These settings indicate to the client that it should call dsDoMultipleAttributeValueSearch again to get the search results.

If there are no matching records, the plug-in sets fInOutMatchRecordCount to zero, fIOContinueData to NULL, sets fResult to eDSNoErr, and returns.

sDoMultiAttrValueSearchWithData

Structure received when an Open Directory client calls dsDoMultipleAttributeValueSearch.

typedef struct {
uInt32          fType;
sInt32          fResult;
tDirNodeReferencefInNodeRef;
tDataBufferPtr  fOutDataBuff;
tDataListPtr    fInRecTypeList;
tDataNodePtr    fInAttrType;
tDirPatternMatchfInPattMatchType;
tDataListPtr    fInPatterns2MatchList;
unsigned long   fInOutMatchRecordCount;
tContextData    fIOContinueData;
tDataListPtr    fInAttrTypeRequestList;
bool            fInAttrInfoOnly;
} sDoMultiAttrValueSearchWithData;

Fields

fType: Always kDoMultipleAttributeValueSearchWithData.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to search for the attribute values. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.” If no matches are found, the plug-in should set fResult to eDSNoErr, fInOutMatchRecordCount to zero, and fIOContinueData to NULL.
fInNodeRef: Value of type tDirNodeReference that identifies the directory node for which the search is to be conducted. The directory node reference was created when the client application opened the directory node session.
fOutDataBuff: Value of type tDataBufferPtr that points to the tDataBuffer structure in which the plug-in is to place search results.
fInRecTypeList: Value of type tDataListPtr pointing to a tDataList structure containing the record types that are to be searched. See Standard Record Types and Meta Record Type Constants for possible values. If NULL, set fResult to eDSEmptyRecordTypeList and return.
fInAttrType: Value of type tDataNodePtr pointing to a tDataNode structure containing the attribute types that are to be searched for. See the attribute constants described in the “Constants” section for possible values. If NULL, set fResult to eDSEmptyAttributeType and return.
fInPattMatchType: Value of type tDirPatternMatch that describes the way in which the pattern specified by fInPatt2Match is to be matched. The pattern match type can be a value that the plug-in and application agree upon or a constant defined by Open Directory, as described in the section Pattern Matching Constants.
fInPatterns2MatchList: Value of type tDataListPtr pointing to a tDataList structure containing a list of patterns to be matched.
fInOutMatchRecordCount: Value of type unsigned long. The first time the client application calls dsDoAttributeValueSearch, fInOutMatchRecordCount is zero to receive all matching records or is a positive integer value that specifies the total number of records the client application wants to receive across what may be a series of dsDoAttributeValueSearch calls. If the latter, the plug-in should use the initial input value of fInOutMatchRecordCount to limit the total number of matching records it returns. Before returning, the plug-in should set fInOutMatchRecordCount to the number of records it has placed in the buffer pointed to by fOutDataBuff. The plug-in should ignore the input value of fInOutMatchRecordCount whenever it is processing a sDoMultiAttrValueSearchWithData structure that has an fIOContinueData field that is not NULL.
fIOContinueData: Value of type tContextData containing continuation data. For the first in a series of calls to dsDoAttributeValueSearch, the input value is NULL. If the plug-in can store all of the matching records in the buffer pointed to by fOutDataBuff, it sets fIOContinueData to NULL before returning. If there more records than can be stored in the buffer, the plug-in stores as much data as possible and sets fIOContinueData to a plug-in–defined value that the plug-in can use when the client application calls dsDoAttributeValueSearch again to get another buffer of data. You may want to include a timestamp in the continuation data and return an error if you determine that fOutContinueData is out of date.
fInAttrTypeRequestList: Value of type tDataListPtr pointing to a tDataList structure containing the types of attribute that are to be returned if matches are found. See the attribute constants described in the “Constants” section for possible values. If NULL, set fResult to eDSEmptyAttributeTypeList and return.
fInAttrInfoOnly: Boolean value set to TRUE if the plug-in is only to provide information about attributes or set to FALSE if the plug-in is to provide the values of the attributes as well as information about the attributes.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sDoMultiAttrValueSearchWithData structure when an Open Directory client calls dsDoMultipleAttributeValueSearchWithData to search for records that have attributes whose values match one of multiple specified patterns and return the values of the attributes specified by fInAttrTypeRequestList when a match occurs.

The sDoMultiAttrValueSearchWithData structure differs from the sDoMultiAttrValueSearch structure in that the sDoMultiAttrValueSearchWithData structure has two additional fields: fInAttrTypeRequestList, which specifies the type of attributes for which information is to be returned when a match is found, and fInAttrInfoOnly, which indicates whether attribute information or attribute information and attribute values are to be returned when a match is found.

Depending on the size of the data buffer pointed to by fOutDataBuff and the length of the search results, the plug-in’s routine for processing sDoMultiAttrValueSearchWithData structures may be called multiple times in order to return all of the search results. The first time the plug-in’s routine for processing the sDoMultiAttrValueSearchWithData structure is called, the input value of fIOContinueData is NULL and input value of fInOutRecEntryCount specifies the total number of records that the plug-in should return even if the plug-in’s routine for processing sDoMultiAttrValueSearchWithData structures must be called more than once.

If the plug-in returns before it gets search results to place in the buffer pointed to by fOutDataBuff, it should set fInOutMatchRecordCount to zero, set fResult to eDSNoErr, and set fIOContinueData to a plug-in–defined value that is not NULL. These settings indicate to the client that it should call dsDoMultipleAttributeValueSearch again to get the search results.

If there are no matching records, the plug-in sets fInOutMatchRecordCount to zero, fIOContinueData to NULL, sets fResult to eDSNoErr, and returns.

sDoPluginCustomCall

Structure received when an Open Directory client calls dsDoPluginCustomCall.

typedef struct {
uInt32          fType;
sInt32          fResult;
tDirNodeReferencefInNodeRef;
unsigned long   fInRequestCode;
tDataBufferPtr  fInRequestData;
tDataBufferPtr  fOutRequestResponse;
} sDoPlugInCustomCall;

Fields

fType: Always kDoPlugInCustomCall.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that the plug-in responded without error when it processed the sDoPluginCustomCall structure. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”
fInNodeRef: Value of type tDirNodeReference that identifies the directory node session to which fInRequestCode and fInRequestData apply.
fInRequestCode: Value of type unsigned long that contains a request code that has significance to the plug-in.
fInRequestData: Value of type tDataBufferPtr that points to a tDataBuffer structure containing data sent by the client application to the plug-in.
fOutRequestResponse: Value of type tDataBufferPtr that points to a tDataBuffer structure in which the plug-in places data that is to be returned to the client application.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sDoPluginCustomCall structure when an Open Directory client calls dsDoPluginCustomCall to send custom data to the plug-in.

The plug-in verifies that the directory node reference stored in fInNodeRef is valid. It then interprets the value of the fInRequestCode field, parses the value pointed to by the fInRequestData field, and performs an action that is appropriate for the request code. If the plug-in needs to return data to the client application, it stores the data in the tDatabuffer structure pointed to by fOutRequestResponse.

If the plug-in performs the action without error, it sets fResult to eDSNoErr; otherwise, it sets fResult to an appropriate result code as described in “Result Codes.”

sFlushRecord

Structure received when an Open Directory client calls dsFlushRecord.

typedef struct {
uInt32          fType;
sInt32          fResult;
tRecordReferencefInRecRef;
} sFlushRecord;

Fields

fType: Always kFlushRecord.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to flush the record. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”
fInRecRef: Value of type tRecordReference representing the record that is to be flushed. The plug-in created the value of fInRecRef when it was called to process a request to open the record.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sFlushRecord structure when an Open Directory client calls dsFlushRecord.

The plug-in uses the fInRecRef field of the sFlushRecord structure to determine the record that is to be flushed. If the plug-in can write the record, it does so and sets fResult to eDSNoErr, and returns. If the plug-in cannot flush the record, it sets fResult to an appropriate result code as described in “Result Codes” and returns.

sGetAttributeEntry

Structure received when an Open Directory client calls dsGetAttributeEntry.

typedef struct {
uInt32                  fType;
sInt32                  fResult;
tDirNodeReference       fInNodeRef;
tDataBufferPtr          fInOutDataBuff;
tAttributeListRef       fInAttrListRef;
unsigned long           fInAttrInfoIndex;
tAttributeValueListRef  fOutAttrValueListRef;
tAttributeEntryPtr      fOutAttrInfoPtr;
} sGetAttributeEntry;

Fields

fType: Always kGetAttributeEntry.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to get the requested attribute information. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”
fInNodeRef: Value of type tDirNodeReference that identifies the directory node of the record whose attribute information is to be obtained. The directory node reference was created when the client application opened the directory node session.
fInOutDataBuff: Value of type tDataBufferPtr that points to the tDataBuffer structure from which the attribute information is to be obtained.
fInAttrListRef: Value of type tAttributeListRef that refers to an attribute list that the plug-in returned to the client application when it processed a sGetDirNodeInfo or a sGetRecordEntry structure or that the plug-in returned to the client application when it previously called dsGetAttributeEntry. The plug-in uses the attribute list reference to locate the attribute information in the buffer pointed to by fInOutDataBuff.
fInAttrInfoIndex: Value of type unsigned long that specifies the one-based index number of the attribute whose information is to be obtained from the buffer pointed to by fInOutDataBuff.
fOutAttrValueListRef: Value of type tAttributeValueListRef assigned by the DirectoryService daemon and that the plug-in associates with the internal structure the plug-in uses to maintain information about the reference.
fOutAttrInfoPtr: Pointer to a value of type tAttributeValueEntryPtr that points to a tAttributeEntry structure in which the plug-in is to place the attribute information.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sGetAttributeEntry structure when an Open Directory client calls dsGetAttributeEntry to get information about an attribute from the buffer pointed to by fInOutDataBuff.

The plug-in uses the fInNodeRef field to determine the directory node of the record for which attribute information is requested and the fInAttrInfoIndex field to determine the attribute for which attribute information is requested. The information includes the number of values the attribute has, the total number of bytes the values use, the maximum size of a value for the specified attribute, and the attribute’s unique signature.

If the plug-in can get the requested information from fInOutDataBuff, it puts the attribute information in the attribute entry structure pointed to by fOutAttrInfoPtr, sets fOutAttrValueListRef to a value that the plug-in can use to locate the attribute’s value if its routine for processing sGetAttributeValue structures is called, sets fResult to eDSNoErr, and returns.

If the plug-in cannot provide the requested attribute information, it sets fOutAttrValueListRef to NULL, sets fResult to an appropriate result code as described in “Result Codes” and returns.

For information on parsing the data buffer, see the section “Client Side Buffer Parsing” in Chapter 1.

sGetAttributeValue

Structure received when an Open Directory client calls dsGetAttributeValue.

typedef struct {
uInt32                  fType;
sInt32                  fResult;
tDirNodeReference       fInNodeRef;
tDataBufferPtr          fInOutDataBuff;
unsigned long           fInAttrValueIndex;
tAttributeValueListRef  fInAttrValueListRef;
tAttributeValueEntryPtr fOutAttrValue;
} sGetAttributeValue;

Fields

fType: Always kGetAttributeValue.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to get the requested attribute value. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”
fInNodeRef: Value of type tDirNodeReference that identifies the directory node of the record whose attribute value is to be obtained. The directory node reference was created when the client application opened the directory node session.
fInOutDataBuff: Value of type tDataBufferPtr pointing to the tDataBuffer structure containing information previously obtained when the plug-in responded to an sGetRecordList, sDoAttrValueSearch, sDoAttrValueSearchWithData, sDoMultiAttrValueSearch, or sDOMultiAttrValueSearchWithData request from the client application.
fInAttrValueIndex: Value of type unsigned long containing a one-based index that specifies which attribute value to get. A value of 1 specifies the first value, a value of 2 specifies the second value, and so on.
fInAttrValueListRef: Value of type tAttributeValueListRef created by the plug-in when its routine for processing sGetAttributeEntry structures was called. The reference contains information that the plug-in uses to locate the attribute value in the data buffer pointed to by fInOutDataBuff.
fOutAttrValue: Value of type tAttributeValueEntryPtr pointing to the tAttributeValueEntry structure in which the plug-in is to place the value of the attribute specified by the fInAttrValueIndex field.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sGetAttributeValue structure when an Open Directory client calls dsGetAttributeValue.

The plug-in uses the fInNodeRef field of the sGetAttributeValue structure to determine the directory node of the record for which an attribute value is being obtained.

If the plug-in can get the requested value from the data buffer pointed to by fInOutDataBuff, it puts the value in the attribute value entry structure pointed to by fOutAttrValue, sets fResult to eDSNoErr, and returns.

If the plug-in cannot get the requested value, it sets fResult to an appropriate result code as described in “Result Codes” and returns.

For information on parsing the data buffer, see the section “Client Side Buffer Parsing” in Chapter 1.

sGetDirNodeInfo

Structure received when an Open Directory client application calls dsGetDirNodeInfo.

typedef struct {
uInt32              fType;
sInt32              fResult;
tDirNodeReference   fInNodeRef;
tDataListPtr        fInDirNodeInfoTypeList;
tDataBufferPtr      fOutDataBuff;
bool                fInAttrInfoOnly;
unsigned long       fOutAttrInfoCount;
tAttributeListRef   fOutAttrListRef;
tContextData        fOutContinueData;
} sGetDirNodeInfo;

Fields

fType: Always kGetDirNodeInfo.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to get information about the directory node identified by fInNodeRef. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”
fInNodeRef: Value of type tDirNodeReference that identifies the directory node for which information is to be obtained. The directory node reference was created when the client application opened the directory node.
fInDirNodeInfoTypeList: Value of type tDataListPtr that points to a tDataList structure containing the attribute types for which information is being requested.
fOutDataBuff: Value of type tDataBufferPtr pointing to a tDataBuffer structure. If the plug-in obtains the requested information, it puts the information in the data buffer pointed to by fOutDataBuff.
fInAttrInfoOnly: Boolean value set to TRUE if the plug-in is only to provide information about attributes or set to FALSE if the plug-in is to provide the values of the attributes as well as information about the attributes.
fOutAttrInfoCount: On return, fOutAttrInfoCount contains the number of attribute types the plug-in has placed in the buffer pointed to by fOutDataBuff.
fOutAttrListRef: Value of type tAttributeListRef assigned by the DirectoryService daemon and that the plug-in associates with the internal structure the plug-in uses to maintain information about the reference.
fOutContinueData: Value of type tContextData that represents continuation data. If this is the first call in what may be a series of calls for this value of fInNodeRef, the input value of fOutContinueData is NULL. If all of the directory node information fits in the buffer pointed to by fOutDataBuff, the plug-in sets fOutContinueData to NULL. If there is more information than can fit in the buffer, set fOutContinueData to a plug-in–defined value.Your routine for processing sGetDirNodeInfo structures will be called again, and the fOutContinueData field will contain the continuation data that you previously returned to the client application. Therefore, the continuation data should be a value that you can use to determine which directory node information to place in the data buffer the next time your routine for processing sGetDirNodeInfo structures is called for this value of fInNodeRef. You may want to include a timestamp in the continuation data and return an error if you determine that fOutContinueData is out of date.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sGetDirNodeInfo structure when an Open Directory client calls dsGetDirNodeInfo.

The plug-in uses the fInNodeRef field of the sGetDirNodeInfo structure to determine the directory node for which information is requested, the data list pointed to by fInDirNodeInfoTypeList to determine the type of information that is requested, and fInAttrInfoOnly to determine whether to also return attribute values.

If the plug-in can get attribute information for the specified directory node, it puts the requested information in the buffer pointed to by fOutDataBuff. If fOutDataBuff is too small to hold all of the information, the plug-in sets fOutContinueData to a plug-in–defined value. If all of the information fits in the buffer, the plug-in sets fOutDataBuff to NULL. Before returning, the plug-in sets fOutAttrInfoCount to the number of attributes types that have been placed in the buffer.

If the plug-in cannot get the requested information, it sets fResult to an appropriate result code as described in “Result Codes,” sets fOutContinueData to NULL, sets fOutAttrInfoCount to zero, and returns.

sGetRecAttribInfo

Structure received when an Open Directory client calls dsGetRecordAttributeInfo.

typedef struct {
uInt32              fType;
sInt32              fResult;
tRecordReference    fInRecRef;
tDataNodePtr        fInAttrType;
tAttributeEntryPtr  fOutAttrInfoPtr;
} sGetRecAttribInfo;

Fields

fType: Always kGetRecordAttributeInfo.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to get information about the attribute of the record referred to by fInRecRef. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”
fInRecRef: Value of type tRecordReference that represents the record for which information about an attribute is to be obtained. The plug-in created the value of fInRecRef when it was called to process a request to open the record.
fInAttrType: Value of type tDataNodePtr that points to a tDataNode structure containing the attribute type for which information is requested.
fOutAttrInfoPtr: Value of type tAttributeValueEntryPtr that points to an tAttributeEntry structure containing the requested attribute information.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sGetRecAttribInfo structure when an Open Directory client calls dsGetRecordAttributeInfo.

The plug-in uses the fInRecRef field of the sGetRecAttribInfo structure to determine the record for which information about an attribute is to be obtained and the fInAttrType field to determine the attribute type for which attribute information is to be obtained. The information includes the number of values the attribute has, the total number of bytes the values use, the maximum size of a value for the specified attribute, and the attribute’s unique signature.

If the plug-in can get the attribute information, it places the information in the attribute entry structure pointed to by fOutAttrInfoPtr, sets fResult to eDSNoErr, and returns.

If the plug-in cannot get the attribute’s information, it sets fResult to an appropriate result code as described in “Result Codes” and returns.

sGetRecordAttributeValueByID

Structure received when an Open Directory client calls dsGetRecordAttributeValueByID.

typedef struct {
uInt32                  fType;
sInt32                  fResult;
tRecordReference        fInRecRef;
tDataNodePtr            fInAttrType;
unsigned long           fInAttrValueID;
tAttributeValueEntryPtr fOutEntryPtr;
} sGetRecordAttributeValueByID;

Fields

fType: Always kGetRecordAttributeValueByID.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to get the value of the attribute. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”
fInRecRef: Value of type tRecordReference that represents the record for which an attribute value is to be obtained. The plug-in created the value of fInRecRef when it was called to process a request to open the record.
fInAttrType: Value of type tDataNodePtr that points to a tDataNode structure containing the type of attribute for which an attribute value is requested.
fInAttrValueID: Value of type unsigned long that specifies the attribute value ID of the attribute value that is to be obtained.
fOutEntryPtr: Value of type tAttributeValueEntryPtr that points to an tAttributeValueEntry structure in which the plug-in places the requested attribute value.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sGetRecordAttributeValueByID structure when an Open Directory client calls dsGetRecordAttributeValueByID to get the value of an attribute by it attribute value ID.

The plug-in uses the fInRecRef field of the sGetRecordAttributeValueByID structure to determine the record for which the value of an attribute is to be obtained, the fInAttrType field to determine the type of the attribute whose value is to be obtained, and the fInAttrValueID field to determine the ID of the attribute value to get.

If the plug-in can get the specified attribute value, it places the value in the attribute value entry structure pointed to by fOutEntryPtr, sets fResult to eDSNoErr, and returns.

If the plug-in cannot get the attribute’s value, it sets fResult to an appropriate result code as described in “Result Codes” and returns.

sGetRecordAttributeValueByIndex

Structure received when an Open Directory client calls dsGetRecordAttributeValueByIndex.

typedef struct {
uInt32                  fType;
sInt32                  fResult;
tRecordReference        fInRecRef;
tDataNodePtr            fInAttrType;
unsigned long           fInAttrValueIndex;
tAttributeValueEntryPtr fOutEntryPtr;
} sGetRecordAttributeValueByIndex;

Fields

fType: Always kGetRecordAttributeValueByIndex.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to get the value of the attribute. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”
fInRecRef: Value of type tRecordReference that represents the record whose attribute value is to be obtained. The plug-in created the value of fInRecRef when it was called to process a request to open the record.
fInAttrType: Value of type tDataNodePtr that points to a tDataNode structure containing the type of the attribute whose value is requested.
fInAttrValueIndex: Value of type unsigned long that specifies the attribute for which information is to be obtained, using a one-based index.
fOutEntryPtr: Value of type tAttributeValueEntryPtr that points to an tAttributeValueEntry in which the plug-in is to place the attribute’s value.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sGetRecordAttributeValueByIndex structure when an Open Directory client calls dsGetRecordAttributeValueByIndex to get the value of an attribute by its attribute index.

The plug-in uses the fInRecRef field of the sGetRecordAttributeValueByIndex structure to determine the record for which the value of an attribute is to be obtained, the fInAttrType field to determine the type of the attribute whose value is to be obtained, and the fInAttrValueIndex field to determine which attribute value to obtain.

If the plug-in can get the specified attribute value, it places the value in the attribute value entry structure pointed to by fOutEntryPtr, sets fResult to eDSNoErr, and returns.

If the plug-in cannot get the attribute’s value, it sets fResult to an appropriate result code as described in “Result Codes” and returns.

sGetRecordAttributeValueByValue

Structure received when an Open Directory client calls dsGetRecordAttributeValueByValue.

typedef struct {
uInt32                  fType;
sInt32                  fResult;
tRecordReference        fInRecRef;
tDataNodePtr            fInAttrType;
tDataNodePtr            fInAttrValue;
tAttributeValueEntryPtr fOutEntryPtr;
} sGetRecordAttributeValueByValue;

Fields

fType: Always kGetRecordAttributeValueByValue.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to get the value of the attribute. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”
fInRecRef: Value of type tRecordReference that represents the record whose attribute value is to be obtained. The plug-in created the value of fInRecRef when it was called to process a request to open the record.
fInAttrType: Value of type tDataNodePtr that points to a tDataNode structure containing the type of the attribute whose value is requested.
fInAttrValue: Value of type tDataNodePtr that specifies the value that is to be obtained.
fOutEntryPtr: Value of type tAttributeValueEntryPtr that points to an tAttributeValueEntry in which the plug-in is to place the attribute’s value.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sGetRecordAttributeValueByValue structure when an Open Directory client calls dsGetRecordAttributeValueByValue to get the value of an attribute by its value.

The plug-in uses the fInRecRef field of the sGetRecordAttributeValueByValue structure to determine the record for which the value of an attribute is to be obtained, the fInAttrType field to determine the type of the attribute whose value is to be obtained, and the fInAttrValue field to determine which attribute value to obtain.

If the plug-in can get the specified attribute value, it places the value in the attribute value entry structure pointed to by fOutEntryPtr, sets fResult to eDSNoErr, and returns.

If the plug-in cannot get the attribute’s value, it sets fResult to an appropriate result code as described in “Result Codes” and returns.

sGetRecordEntry

Structure received when an Open Directory client calls dsGetRecordEntry.

typedef struct {
uInt32              fType;
sInt32              fResult;
tDirNodeReference   fInNodeRef;
tDataBufferPtr      fInOutDataBuff;
unsigned long       fInRecEntryIndex;
tAttributeListRef   fOutAttrListRef;
tRecordEntryPtr     fOutRecEntryPtr;
} sGetRecordEntry;

Fields

fType: Always kGetRecordEntry.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to get the record entries for the directory node identified by fInNodeRef. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”
fInNodeRef: Value of type tDirNodeReference that identifies the directory node for which the record entry is to be obtained. The directory node reference was created when the client application opened the directory node.
fInOutDataBuff: Value of type tDataBufferPtr that points to the tDataBuffer structure from which the record entry is to be obtained.
fInRecEntryIndex: Value of type unsigned long that specifies the record to get. The fInRecEntryIndex field contains a value that is a one-based index.
fOutAttrListRef: Value of type tAttributeListRef assigned by the DirectoryService daemon and that the plug-in associates with the internal structure the plug-in uses to maintain information about the reference.
fOutRecEntryPtr: Value of type tRecordEntryPtr that points to a tRecordEntry structure containing the requested record.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sGetRecordEntry structure when an Open Directory client calls dsGetRecordEntry to get information about a record.

The plug-in gets information about the record from the buffer pointed to by fInOutDataBuff. The record information consists of the record’s name, type, and number of attributes. The buffer pointed to by fInOutDataBuff was previously filled in by the plug-in when the plug-in’s ProcessRequest routine responded to the receipt of an sGetRecordList structure.

The plug-in verifies that the directory node reference provided in the fInNodeRef field is valid. If the directory node reference is valid, the plug-in uses the fInRecEntryIndex field to determine the record for which record information is to be obtained, places the information in the record entry structure pointed to by the fOutRecEntryPtr field, and places the record’s attribute information in the attribute list referred to by tOutAttrListRef. Before returning, the plug-in sets fResult to eDSNoErr.

If the plug-in cannot get the requested information, it sets fResult to an appropriate result code as described in “Result Codes” and returns.

For information on parsing the data buffer, see the section “Client Side Buffer Parsing” in Chapter 1.

sGetRecordList

Structure called when an Open Directory client calls dsGetRecordList.

typedef struct {
uInt32              fType;
sInt32              fResult;
tDirNodeReference   fInNodeRef;
tDataBufferPtr      fInDataBuff;
tDataListPtr        fInRecNameList;
tDirPatternMatch    fInPatternMatch;
tDataListPtr        fInRecTypeList;
tDataListPtr        fInAttribTypeList;
bool                fInAttribInfoOnly;
unsigned long       fOutRecEntryCount;
tContextData        fIOContinueData;
} sGetRecordList;

Fields

fType: Always kGetRecordList.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to get the requested list of records for the node identified by fInNodeRef. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.” If no matches are found, the plug-in should set fResult to eDSNoErr, fOutRecEntryCount to zero, and fIOContinueData to NULL.
fInNodeRef: Value of type tDirNodeReference that identifies the directory node for which the record list is to be obtained. The directory node reference was created when the client application opened the directory node.
fInDataBuff: Value of type tDataBufferPtr pointing to the tDataBuffer structure in which the plug-in is to return the record list.
fInRecNameList: Value of type tDataListPtr that points to a tDataList structure containing patterns in UTF-8 encoding that are to be compared with record names. If fInRecNameList is kDSRecordsAll, the plug-in should ignore fInPatternMatch and include all records for the directory node identified by fInNodeRef.
fInPatternMatch: Value of type tDirPatternMatch that describes the way in which the patterns specified by fInRecNameList are to be compared. See Pattern Matching Constants for possible constants. The pattern match type may also be a type defined by the Open Directory plug-in that handles the directory system represented by inDirReference.
fInRecTypeList: Value of type tDataListPtr that points to atDataList structure containing the types of records to get. See Standard Record Types and Meta Record Type Constants for possible values.
fInAttribTypeList: Value of type tDataListPtr that points to a tDataList structure containing the attribute types of records to get. See the attribute constants described in the “Constants” section for possible values.
fInAttribInfoOnly: Value of type bool. If fInAttribInfoOnly is TRUE, the plug-in should include in the buffer pointed to by fInDataBuff attribute information for matching records. If fInAttribInfoOnly is FALSE, the plug-in should include in the buffer pointed to by fInDataBuff attribute information as well as attribute values for matching records.
fOutRecEntryCount: Value of type unsigned long. The first time the client application calls dsGetRecordList, fOutRecEntryCount is zero to receive all matching records or is a positive integer value that specifies the total number of records the client application wants to receive across what may be a series of dsGetRecordList calls. If the latter, the plug-in should use the initial input value of fOutRecEntryCount to limit the total number of matching records it returns. Before returning, the plug-in should set fOutRecEntryCount to the number of records it has placed in the buffer pointed to by fInDataBuff. The plug-in should ignore the input value of fOutRecEntryCount whenever it is processing a sGetRecordList structure that has an fIOContinueData field that is not NULL.
fIOContinueData: Value of type tContextData containing continuation data. For the first in a series of calls to dsGetRecordList, the input value is NULL. If the plug-in can store all of the matching records in the buffer pointed to by fInDataBuff, it sets fIOContinueData to NULL before returning. If there more records than can be stored in the buffer, the plug-in stores as much data as possible and sets fIOContinueData to a plug-in–defined value that the plug-in can use when the client application calls dsGetRecordList again to get another buffer of data. You may want to include a timestamp in the continuation data and return an error if you determine that fOutContinueData is out of date.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sGetRecordList structure when an Open Directory client calls dsGetRecordList to get a list of records for a directory node.

The plug-in uses the fInNodeRef field of the sGetRecordList structure to determine the directory node for which the record list is requested, the data list pointed to by fInRecNameList to get the names of records for which information is requested, the data list pointed to by fInRecTypeList to determine the types of records for which information is requested, and the data list pointed to by fInAttributeTypeList to determine the attributes for which information is requested. The plug-in should return only those records whose names match the pattern specified by fInRecNameList. The value of the fInAttributeInfoOnly field determines whether the plug-in should also return attribute values.

Depending on the size of the data buffer pointed to by fInDataBuff and the length of the list of records, the plug-in’s routine for processing sGetRecordList structures may be called multiple times in order to return the complete list. The first time the plug-in’s routine for processing sGetRecordList structures is called, the input value of fIOContinueData is NULL and input value of fInOutRecEntryCount specifies the total number of records that the plug-in should return even if the plug-in’s routine for processing sGetRecordList structures must be called more than once.

If there are records that match the criteria specified by fInRecNameList, fInPatternMatch, fInRecTypeList, and fInAttributeTypeList, plug-in puts the record entries, attribute entries, and attribute values (if fInAttributeInfoOnly is FALSE) in the buffer pointed to by fInDataBuff. It also sets fInOutRecEntryCount to the number of records that have been placed in fInDataBuff and sets fResult to eDSNoErr. If the buffer pointed to by fInDataBuff is too small to hold all of the records, the plug-in sets fIOContinueData to a plug-in–defined value that the plug-in can use when the client application calls dsGetRecordList again to get another buffer of data. If the buffer pointed to by fInDataBuff contains all of the records or contains the last records in the record list, the plug-in sets fIOContinueData to NULL.

If the plug-in returns before it can get records to place in the buffer pointed to by fInDataBuff, it should set fOutRecEntryCount to zero, set fResult to eDSNoErr, set fIOContinueData to a plug-in–defined value that is not NULL. These settings indicate to the client application that it should call dsGetRecordList again to get the records.

If there are no matching records, the plug-in sets fOutRecEntryCount to zero, fIOContinueData to NULL, and fResult to eDSNoErr, and returns.

sGetRecRefInfo

Structure received when an Open Directory client calls dsGetRecordReferenceInfo.

typedef struct {
uInt32              fType;
sInt32              fResult;
tRecordReference    fInRecRef;
tRecordEntryPtr     fOutRecInfo;
} sGetRecRefInfo;

Fields

fType: Always kGetRecordRefInfo.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to get information for the record reference specified by fInRecRef. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”
fInRecRef: Value of type tRecordReference that specifies the record for which information is to be obtained. The plug-in created the value of fInRecRef when it was called to process a request to open the record.
fOutRecInfo: Value of type tRecordEntryPtr that points to a tRecordEntry structure containing the requested information.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sGetRecRefInfo structure when an Open Directory client calls dsGetRecordReferenceInfo to get information about a record.

The plug-in uses the fInRecRef field of the sGetRecRefInfo structure to determine the record for information is to be obtained. The information consists of the record’s name, type, and the number of attributes the record has.

If the plug-in can get the record’s information, it places the information in the record entry structure pointed to by fOutRecInfo, sets fResult to eDSnoErr, and returns.

If the plug-in cannot get the record’s information, it sets fResult to an appropriate result code as described in “Result Codes” and returns.

sHeader

Structure for passing the DirectoryService daemon’s run loop and the Kerberos mutex.

typedef struct {
uInt32              fType;
sInt32              fResult;
tContextData        fContextData;
} sHeader;

Fields

fType: kServerRunLoop or kKerberosMutex.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”
fContextData: Value of type tContextData containing the run loop or the Kerberos mutex.

Discussion

The DirectoryService daemon calls the plug-in’s ProcessRequest entry point once after the plug-in has been loaded and initialized to pass in the fContextData field the CFRunloop for the currently executing process. You can use the run loop to set up timers as an alternative to using the PeriodicTask entry point for setting timers.

Here is an example that gets the run loop from the fContextData field:

if ( ((sHeader *)inData)->fType == kServerRunLoop)

    if ( (((sHeader *)inData)->fContextData) != nil )

        fServerRunLoop = (CFRunLoopRef)(((sHeader *)inData)->fContextData);

The sHeader structure is also used to pass the Kerberos mutex, a value of type DSMutexSempaphore, immediately after the run loop is passed.

sOpenDirNode

Structure received when an Open Directory client calls dsOpenDirNode.

typedef struct {
uInt32          fType;
sInt32          fResult;
tDirReference   fInDirRef;
tDataListPtr    fInDirNodeName;
tDirNodeReferencefOutNodeRef;
uid_t           fInUID;
uid_t           fInEffectiveUID;
} sOpenDirNode;

Fields

fType: Always kOpenDirNode.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to open the directory node specified by fInDirNodeName. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”
fInDirRef: Value of type tDirReference that was created when the client application opened the Open Directory session for which this directory node is to be opened.
fInDirNodeName: Value of type tDataListPtr pointing to a tDataList structure containing the name of the directory node that is to be opened.
fOutNodeRef: Value of type tDirNodeReference assigned by the DirectoryService daemon and that the plug-in associates with the internal structure the plug-in uses to maintain information about the reference.
fInUID: Value of type uid_t containing the UID of the calling process. Your plug-in can use the value of fInUID and fInEffectiveUID to determine whether to allow a process to perform certain activities without requiring authentication.
fInEffectiveUID: Value of type uid_t containing the effective UID of the calling process. Your plug-in can use the value of fInEffectiveUID and fInUID to determine whether to allow a process to perform certain activities without requiring authentication.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sOpenDirNode structure when an Open Directory client calls dsOpenDirNode to open a directory node.

The plug-in uses the fInDirNodeName field to determine the name of the directory node to open.

If the plug-in can open the specified directory node, it sets fResult to eDSNoErr and returns.

If the plug-in cannot open the directory node or if the Open Directory reference is invalid, the plug-in sets fResult to an appropriate result code as described in “Result Codes” and returns.

sOpenRecord

Structure received when an Open Directory client calls dsOpenRecord.

typedef struct {
uInt32              fType;
sInt32              fResult;
tDirNodeReference   fInNodeRef;
tDataNodePtr        fInRecType;
tDataNodePtr        fInRecName;
tRecordReference    fOutRecRef;
} sOpenRecord;

Fields

fType: Always kOpenRecord.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to open the specified record. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”
fInNodeRef: Value of type tDirNodeReference that identifies the directory node of the record that is to be opened. The directory node reference was created when the client application opened the directory node.
fInRecType: Value of type tDataNodePtr that points to a tDataNode structure containing the type of the record that is to be opened.
fInRecName: Value of type tDataNodePtr that points to a tDataNode structure containing the name of the record that is to be opened.
fOutRecRef: Value of type tRecordReference assigned by the DirectoryService daemon and that the plug-in associates with the internal structure the plug-in uses to maintain information about the reference.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sOpenRecord structure when an Open Directory client calls dsOpenRecord.

The plug-in uses the fInNodeRef field of the sOpenRecord structure to determine the directory node of the record that is to be opened, the fInRecType field to determine the type of the record that this is to be opened, and the fInRecName field to determine the name of the record that is to be opened.

If the plug-in can open the record, it sets fResult to eDSNoErr, and returns. Later, when the client application calls Open Directory functions that operate on the opened record, the record reference will be passed to the plug-in, which should use the record reference to identify the record.

If the plug-in cannot open the record, it should set fResult to an appropriate result code as described in “Result Codes” and return.

sReleaseContinueData

Structure received when an Open Directory client calls dsReleaseContinueData.

typedef struct {
uInt32          fType;
sInt32          fResult;
tDirReference   fInDirReference;
tContextData    fInContinueData;
} sReleaseContinueData;

Fields

fType: Always kReleaseContinueData.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to deallocate the memory associated with fInContinueData. If an error occurs, the plug-in set fResult to a value listed in “Result Codes.”
fInDirReference: Value of type tDirReference or of type tDirNodeReference, depending on the type of reference that was used in the call that created the continue data that is to be released.
fInContinueData: Value of type tContextData that points to memory that is to be released.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sReleaseContinueData structure when an Open Directory client calls dsReleaseContinueData.

The plug-in deallocates the memory associated with fInContinueData, sets fResult to eDSNoErr, and returns.

If the plug-in cannot deallocate the memory associated with fInContinueData, it sets fResult to an appropriate result code as described in “Result Codes” and returns.

sRemoveAttribute

Structure received when an Open Directory client calls dsRemoveAttribute.

typedef struct {
uInt32          fType;
sInt32          fResult;
tRecordReferencefInRecRef;
tDataNodePtr    fInAttribute;
} sRemoveAttribute;

Fields

fType: Always kRemoveAttribute.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to remove the attribute. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”
fInRecRef: Value of type tRecordReference representing the record from which the attribute is to be removed.
fInAttribute: Value of type tDataNodePtr that points to a tDataNode structure containing the name of the attribute that is to be removed.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sRemoveAttribute structure when an Open Directory client calls dsRemoveAttribute to remove an attribute from a record.

The plug-in uses the fInRecRef field of the sRemoveAttribute structure to determine the record from which an attribute is to be removed and the fInAttribute field to determine the name of the attribute that is to be removed.

If the plug-in can remove the attribute, it removes the attribute and all of its values, invalidates any attribute list references that may be active for this attribute, sets fResult to eDSNoErr, and returns. After returning, the plug-in responds with an error to any calls of its ProcessRequest entry point that provide a pointers to an attribute entry structure or an attribute value entry structure for the removed attribute.

If the plug-in cannot remove the attribute, it sets fResult to an appropriate result code as described in “Result Codes” and returns.

sRemoveAttributeValue

Structure received when an Open Directory client calls dsRemoveAttributeValue.

typedef struct {
uInt32              fType;
sInt32              fResult;
tRecordReference    fInRecRef;
tDataNodePtr        fInAttrType;
unsigned long       fInAttrValueID;
} sRemoveAttributeValue;

Fields

fType: Always kRemoveAttributeValue.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to remove the value from the attribute. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”
fInRecRef: Value of type tRecordReference representing the record for which a value is to be removed to an attribute.
fInAttrType: Value of type tDataNodePtr that points to a tDataNode structure containing the type the attribute from which a value is to be removed.
fInAttrValueID: Value of type unsigned long that specifies the ID of the value that is to be removed.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sRemoveAttributeValue structure when an Open Directory client calls dsRemoveAttributeValue to remove a value from an attribute.

The plug-in uses the fInRecRef field of the sRemoveAttributeValue structure to determine the record for which a value is to be removed from an attribute, the fInAttrType field to determine the type of the attribute from which a value is to be removed, and the fInAttrValueID field to determine which attribute value to remove.

If the plug-in can remove the specified value from the specified attribute, it removes the attribute, invalidates any attribute value list references for the removed value, sets fResult to eDSNoErr, and returns. After returning, the plug-in responds with an error to any calls of its ProcessRequest entry point that provide a pointer to an attribute value entry structure for the removed attribute value.

If the plug-in cannot add the attribute value, it sets fResult to an appropriate result code as described in “Result Codes” and returns.

sSetAttributeValue

Structure received when an Open Directory client calls dsSetAttributeValue.

typedef struct {
uInt32                  fType;
sInt32                  fResult;
tRecordReference        fInRecRef;
tDataNodePtr            fInAttrType;
tAttributeValueEntryPtr fInAttrValueEntry;
} sSetAttributeValue;

Fields

fType: Always kSetAttributeValue.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to set the specified value in the attribute. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”
fInRecRef: Value of type tRecordReference representing the record for which a value is to be set in an attribute. The record reference was created when the plug-in processed an sOpenRecord structure.
fInAttrType: Value of type tDataNodePtr that points to a tDataNode structure containing the type the attribute whose value is to be set.
fInAttrValueEntry: Value of type tAttributeValueEntryPtr that points to a tAttributeValueEntry structure containing the value that is to be set and its attribute value ID.

Discussion

The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sSetAttributeValue structure when an Open Directory client calls dsSetAttributeValue to set an attribute’s value.

The plug-in uses the fInRecRef field of the sSetAttributeValue structure to determine the record for which an attribute value is to be set and the fInAttrType field to determine the type of the attribute whose value is to be set. The fInAttrValueEntry field contains a pointer to a tAttributeValueEntry structure whose fAttributeValueID field identifies which value is to be replaced and whose fAttributeValueData field contains the new value.

If the plug-in can set the attribute value, it sets the value, sets fResult to eDSNoErr, and returns.

If the plug-in cannot set the attribute value, it sets fResult to an appropriate result code as described in “Result Codes” and returns.

sSetAttributeValues

Structure received when an Open Directory client calls dsSetAttributeValues.

typedef struct {
uInt32              fType;
sInt32              fResult;
tRecordReference    fInRecRef;
tDataNodePtr        fInAttrType;
tDataListPtr        fInAttrValueList;
} sSetAttributeValues;

Fields

fType: Always kSetAttributeValues.
fResult: Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to set the specified value in the attribute. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”
fInRecRef: Value of type tRecordReference representing the record for which a value is to be set in an attribute. The record reference was created when the plug-in processed an sOpenRecord structure.
fInAttrType: Value of type tDataNodePtr that points to a tDataNode structure containing the type the attribute whose value is to be set.
fInAttrValueList: Value of type tAttributeValueEntryPtr