Mac Developer Library

Developer

DirectoryService Framework Reference Directory Services Reference

Options
Deployment Target:

On This Page
Language:

Directory Services Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import DirectoryService

Objective-C

@import DirectoryService;

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

Functions

  • Adds an attribute to a record.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Adds a value to an attribute.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Allows the specified process to use a node reference.

    Declaration

    Objective-C

    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 SInt32 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 UInt32 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

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

    Declaration

    Objective-C

    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 UInt32 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Appends a string to a data list.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

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

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Builds a data list from a pathname.

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

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

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Builds a data list from strings.

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

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

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Disposes of an attribute list reference.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Disposes of an attribute value list reference.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Closes a session with a node.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Closes an Open Directory session.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Closes a open record.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Creates a record.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Creates a record and opens it.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Allocates an Open Directory data buffer.

    Declaration

    Objective-C

    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 UInt32 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Deallocates an Open Directory data buffer.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Allocates a data list.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Copies a data list.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Deallocates a data list.

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Gets a data node from a data list.

    Declaration

    Objective-C

    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 UInt32 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Gets the number of data nodes in a data list.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Inserts a data node in a data list.

    Declaration

    Objective-C

    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 UInt32 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Merges two data lists.

    Declaration

    Objective-C

    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 UInt32 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Deletes a data node from a data list.

    Declaration

    Objective-C

    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 UInt32 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Allocates an Open Directory data node.

    Declaration

    Objective-C

    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 UInt32 that specifies the size of inDataNodeBuffer.

    inDataNodeLength

    On input, a value of type UInt32 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Allocates an Open Directory data node using a string.

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Deallocates a data node.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Gets the size of a data node’s buffer.

    Declaration

    Objective-C

    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 UInt32 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

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

    Declaration

    Objective-C

    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 UInt32 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

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

    Declaration

    Objective-C

    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 UInt32 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Deallocates an attribute entry structure.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Deallocates an attribute value entry structure.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Deallocates a record entry structure.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Deletes a record.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Searches a node for records by attribute value.

    Declaration

    Objective-C

    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 UInt32 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 variable of type tContextData, set to 0. On output, if the value pointed to by inOutContinueData is not 0, get more matching records by calling this function again and pass the value pointed to by inOutContinueData. If on output, the variable pointed to by inOutContinueData is zero, there are no more records to get. If the value pointed to by inOutContinueData is nonzero 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 this value is zero, you do not need to call this function again. If this value is nonzero 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 nonzero 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 zero and the value returned by this function is zero, more results may be available. Continue calling this function until the variable pointed to by inOutContinueData contains zero.

    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 nonzero 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Searches for records by attribute type and attribute value.

    Declaration

    Objective-C

    tDirStatus dsDoAttributeValueSearchWithData ( tDirNodeReference inDirNodeReference, tDataBufferPtr inOutDataBuffer, tDataListPtr inRecordTypeList, tDataNodePtr inAttributeMatchType, tDirPatternMatch inPatternMatchType, tDataNodePtr inPatternToMatch, tDataListPtr inAttributeTypeRequestList, int 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 UInt32 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 variable of type tContextData set to zero. On output, if the value pointed to by inOutContinueData is zero, there are no new results in the buffer. If the value pointed to by inOutContinueData is nonzero 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.

    If there are too many records to fit in a single buffer, this function returns a nonzero 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.

    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.

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

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Performs authentication with a node.

    Declaration

    Objective-C

    tDirStatus dsDoDirNodeAuth ( tDirNodeReference inDirNodeReference, tDataNodePtr inDirNodeAuthName, int 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 variable of type tContextData and set to zero. On output, if the value pointed to by inOutContinueData is zero, there are no more steps in the authentication process. If inOutContinueData is nonzero 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 nonzero 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Performs authentication using a record type.

    Declaration

    Objective-C

    tDirStatus dsDoDirNodeAuthOnRecordType ( tDirNodeReference inDirNodeReference, tDataNodePtr inDirNodeAuthName, int 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 variable of type tContextData set to zero. On output, if the value pointed to by inOutContinueData is zero, there are no more steps in the authentication process. If the value is nonzero 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 nonzero 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.6.

  • Uses multiple attribute values to search a node for records.

    Declaration

    Objective-C

    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 UInt32 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 variable of type tContextData set to zero. On output, if the value pointed to by inOutContinueData is nonzero, get more matching records by calling this function again and pass the value pointed to by inOutContinueData. If, on output, the variable pointed to by inOutContinueData contains zero, there are no more records to get. If the varibale is nonzero 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.

    On output, the variable pointed to by inOutContinueData indicates whether you should call this function again to obtain more matching records. If the value of this variable is zero; you do not need to call this function again. If the value is nonzero 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 nonzero 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.

    On return, if the value of the variable pointed to by inOutContinueData is nonzero and the value returned by this function is zero, more results may be available. Continue calling this function until the value in this variable is zero.

    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.

    On return, if the value in the variable pointed to by inOutContinueData is nonzero 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.6.

  • Searches for records by attribute type and multiple attribute values.

    Declaration

    Objective-C

    tDirStatus dsDoMultipleAttributeValueSearchWithData ( tDirNodeReference inDirNodeReference, tDataBufferPtr inOutDataBuffer, tDataListPtr inRecordTypeList, tDataNodePtr inAttributeMatchType, tDirPatternMatch inPatternMatchType, tDataListPtr inPatternsToMatch, tDataListPtr inAttributeTypeRequestList, int 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 UInt32 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 variable of type tContextData set to zero. On output, if the variable pointed to by inOutContinueData contains zero, there are no new results in the buffer. If its value is nonzero 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.

    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.

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

    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.

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

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.6.

  • Exchanges custom information with an Open Directory plug-in.

    Declaration

    Objective-C

    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 UInt32, 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Finds the registered node names that match a pattern.

    Declaration

    Objective-C

    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 UInt32 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 variable of type tContextData set to zero. On output, if the value of the variable pointed to by inOutContinueData is zero, there is no more response data to get. If the value is nonzero, there is more response data, which you can get by calling this function again and passing the context data pointed to by inOutContinueData. If the value is nonzero 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 the value pointed to by inOutContinueData is nonzero, 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Writes a record.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Gets an attribute entry from a data buffer.

    Declaration

    Objective-C

    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 UInt32. 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Gets the value of an attribute from a data buffer.

    Declaration

    Objective-C

    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 UInt32. 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Gets the length of data in a data list.

    Declaration

    Swift

    func dsGetDataLength(_ inDataList: UnsafePointer<tDataList>) -> UInt32

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Swift

    import DirectoryService

    Availability

    Available in OS X v10.0 and later.

  • Gets the total number of registered nodes.

    Declaration

    Objective-C

    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 UInt32 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.6.

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

    Declaration

    Objective-C

    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 UInt32 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 UInt32 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

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

    Declaration

    Objective-C

    tDirStatus dsGetDirNodeInfo ( tDirNodeReference inDirNodeReference, tDataListPtr inDirNodeInfoTypeList, tDataBufferPtr inOutDataBuffer, int 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 UInt32 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 variable of type tContextData set to zero. On output, if the value of the variable pointed to by inOutContinueData is zero, there is no more response data to get. If the value is nonzero, there is more response data, which you can get by calling this function again and passing the context data pointed to by inOutContinueData. If the value is nonzero 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Gets the names of registered nodes.

    Declaration

    Objective-C

    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 UInt32 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 variable of type tContextData set to zero. On output, if the value of the variable pointed to by inOutContinueData is zero, there is no more response data to get. If the value is nonzero, there is more response data, which you can get by calling this function again and passing the context data pointed to by inOutContinueData. If the value is nonzero 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 the value pointed to by inOutContinueData is nonzero, 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Gets node names from a buffer.

    Declaration

    Objective-C

    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 UInt32. 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Gets the path from a data list.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Gets information about a record’s attribute.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

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

    Declaration

    Objective-C

    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 UInt32 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Uses an index to get the value of an attribute.

    Declaration

    Objective-C

    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 UInt32 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Verifies the existence of an attribute value within a record.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.6.

  • Gets the next record from a data buffer.

    Declaration

    Objective-C

    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 UInt32 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

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

    Declaration

    Objective-C

    tDirStatus dsGetRecordList ( tDirNodeReference inDirNodeReference, tDataBufferPtr inOutDataBuffer, tDataListPtr inRecordNameList, tDirPatternMatch inPatternMatchType, tDataListPtr inRecordTypeList, tDataListPtr inAttributeTypeList, int 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 UInt32 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 variable of type tContextData set to zero. On output, if the value of this variable is zero, there are no more records to get. If the value is nonzero, 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.

    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.

    If there are too many records to fit in the data buffer pointed to by inOutDataBuffer, the variable pointed to by inOutContinueData contains a nonzero 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 the variable pointed to by inOutContinueData contains a zero value.

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

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Checks to see if Open Directory is running.

    Declaration

    Objective-C

    tDirStatus dsIsDirServiceRunning ( void );

    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 OS X v10.2, Open Directory did not start until when an application called dsOpenDirService. With OS X v10.2, Open Directory starts up when the system starts up and is always running.

    Applications that run on OS X v10.0 and OS X v10.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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Opens a session with a node.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Opens an Open Directory session.

    Declaration

    Objective-C

    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 OS X v10.2, Open Directory starts up when the system starts up and is always running. Prior to OS X v10.2, the DirectoryService daemon was not started until an application called this function for the first time. Applications that run on OS X v10.0 and OS X v10.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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Opens a remote Open Directory session.

    Declaration

    Objective-C

    tDirStatus dsOpenDirServiceProxy ( tDirReference *outDirRef, const char *inHostOrIPAddress, 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 UInt32 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 variable of type tContextData set to zero. On output, if the value of the variable pointed to by inOutContinueData is zero, there are no more steps in the authentication process. If the value is nonzero, 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 is nonzero 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 OS X v10.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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • dsOpenRecord dsOpenRecord (OS X v10.6)

    Opens a record.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Releases memory allocated for continuation data.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Removes an attribute from a record.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Removes an attribute value.

    Declaration

    Objective-C

    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 UInt32 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Sets the value of an attribute.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Sets multiple values for an attribute.

    Declaration

    Objective-C

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

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.6.

  • Sets the name of a record.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Sets the type of a record.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.2.

  • Verifies that a tDirReference is valid.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Initializes the plug-in.

    Declaration

    Objective-C

    virtual void Initialize(void)

    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.

  • Performs a periodic task.

    Declaration

    Objective-C

    SInt32 PeriodicTask (void);

    Parameters

    return result

    Value of type SInt32. 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.

  • Processes requests.

    Declaration

    Objective-C

    SInt32 ProcessRequest (void *inData);

    Parameters

    inData

    Pointer to an arbitrary value containing the request that is to be processed.

    return result

    Value of type SInt32. 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.

  • Sets the plug-in’s state.

    Declaration

    Objective-C

    SInt32 SetPluginState (UInt32 inNewState);

    Parameters

    inNewState

    A value of type UInt32 that describes the plug-in’s new state. See the ePluginState Constants enumeration for appropriate values.

    return result

    Value of type SInt32. 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.

  • Prepares the plug-in for shut down.

    Declaration

    Objective-C

    SInt32 Shutdown (void);

    Parameters

    return result

    Value of type SInt32. 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.

  • Validates the plug-in.

    Declaration

    Objective-C

    SInt32 Validate (UInt32 inSignature);

    Parameters

    inSignature

    Value of type UInt32 that uniquely identifies the plug-in.

    return result

    Value of type SInt32. 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.

Callbacks

  • Writes information in the log file.

    Declaration

    Objective-C

    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.

  • Registers a node.

    Declaration

    Objective-C

    SInt32 DSRegisterNode ( const UInt32 inSignature, tDataList *inNode, eDirNodeType inNodeType);

    Parameters

    inSignature

    Value of type const UInt32 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 SInt32. 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.

  • Unregisters a node.

    Declaration

    Objective-C

    SInt32 DSUnregisterNode ( const UInt32 inSignature, tDataList *inNode);

    Parameters

    inSignature

    Value of type UInt32 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 SInt32. 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.

  • A structure used to store information about an attribute.

    Declaration

    Swift

    struct tAttributeEntry { var fReserved1: UInt32 var fReserved2: tAccessControlEntry var fAttributeValueCount: UInt32 var fAttributeDataSize: UInt32 var fAttributeValueMaxSize: UInt32 var fAttributeSignature: tDataNode init() init(fReserved1 fReserved1: UInt32, fReserved2 fReserved2: tAccessControlEntry, fAttributeValueCount fAttributeValueCount: UInt32, fAttributeDataSize fAttributeDataSize: UInt32, fAttributeValueMaxSize fAttributeValueMaxSize: UInt32, fAttributeSignature fAttributeSignature: tDataNode) }

    Objective-C

    typedef struct { UInt32 fReserved1; tAccessControlEntry fReserved2; UInt32 fAttributeValueCount; UInt32 fAttributeDataSize; UInt32 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 OS X v10.0 and later.

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

    Declaration

    Swift

    struct tAttributeValueEntry { var fAttributeValueID: UInt32 var fAttributeValueData: tDataNode init() init(fAttributeValueID fAttributeValueID: UInt32, fAttributeValueData fAttributeValueData: tDataNode) }

    Objective-C

    typedef struct { UInt32 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 OS X v10.0 and later.

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

    Declaration

    Swift

    struct tDataBuffer { var fBufferSize: UInt32 var fBufferLength: UInt32 var fBufferData: (Int8) init() init(fBufferSize fBufferSize: UInt32, fBufferLength fBufferLength: UInt32, fBufferData fBufferData: (Int8)) }

    Objective-C

    typedef struct { UInt32 fBufferSize; UInt32 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 OS X v10.0 and later.

  • An ordered list of tDataNode structures.

    Declaration

    Swift

    struct tDataList { var fDataNodeCount: UInt32 var fDataListHead: tDataNodePtr init() init(fDataNodeCount fDataNodeCount: UInt32, fDataListHead fDataListHead: tDataNodePtr) }

    Objective-C

    typedef struct { UInt32 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.

    See also tDataListPtr.

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    struct tRecordEntry { var fReserved1: UInt32 var fReserved2: tAccessControlEntry var fRecordAttributeCount: UInt32 var fRecordNameAndType: tDataNode init() init(fReserved1 fReserved1: UInt32, fReserved2 fReserved2: tAccessControlEntry, fRecordAttributeCount fRecordAttributeCount: UInt32, fRecordNameAndType fRecordNameAndType: tDataNode) }

    Objective-C

    typedef struct { UInt32 fReserved1; tAccessControlEntry fReserved2; UInt32 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 OS X v10.0 and later.

Other Open Directory Data Types

Data types used by the Open Directory Client.

  • A pointer to a tAttributeEntry structure.

    Declaration

    Swift

    typealias tAttributeEntryPtr = UnsafeMutablePointer<tAttributeEntry>

    Objective-C

    typedef tAttributeEntry *tAttributeEntryPtr;

    Import Statement

    Objective-C

    @import DirectoryService;

    Swift

    import DirectoryService

    Availability

    Available in OS X v10.0 and later.

  • A reference used to get attribute entries.

    Declaration

    Swift

    typealias tAttributeListRef = UInt32

    Objective-C

    typedef UInt32 tAttributeListRef;

    Discussion

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

    Import Statement

    Objective-C

    @import DirectoryService;

    Swift

    import DirectoryService

    Availability

    Available in OS X v10.0 and later.

  • A pointer to a tAttributeValueEntry structure.

    Declaration

    Swift

    typealias tAttributeValueEntryPtr = UnsafeMutablePointer<tAttributeValueEntry>

    Objective-C

    typedef tAttributeValueEntry *tAttributeValueEntryPtr;

    Import Statement

    Objective-C

    @import DirectoryService;

    Swift

    import DirectoryService

    Availability

    Available in OS X v10.0 and later.

  • A reference used to get attribute value entries.

    Declaration

    Swift

    typealias tAttributeValueListRef = UInt32

    Objective-C

    typedef UInt32 tAttributeValueListRef;

    Discussion

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

    Import Statement

    Objective-C

    @import DirectoryService;

    Swift

    import DirectoryService

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    typealias tBuffer = UnsafeMutablePointer<Void>

    Objective-C

    typedef void *tBuffer;

    Discussion

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

    Import Statement

    Objective-C

    @import DirectoryService;

    Swift

    import DirectoryService

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    typealias tContextData = UInt32

    Objective-C

    typedef UInt32 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Swift

    import DirectoryService

    Availability

    Available in OS X v10.0 and later.

  • A pointer to a value of type tDataBuffer.

    Declaration

    Swift

    typealias tDataBufferPtr = UnsafeMutablePointer<tDataBuffer>

    Objective-C

    typedef tDataBuffer *tDataBufferPtr;

    Import Statement

    Objective-C

    @import DirectoryService;

    Swift

    import DirectoryService

    Availability

    Available in OS X v10.0 and later.

  • A pointer to a value of type tDataList.

    Declaration

    Swift

    typealias tDataListPtr = UnsafeMutablePointer<tDataList>

    Objective-C

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

    Import Statement

    Objective-C

    @import DirectoryService;

    Swift

    import DirectoryService

    Availability

    Available in OS X v10.0 and later.

  • A value of type tDataBuffer.

    Declaration

    Swift

    typealias tDataNode = tDataBuffer

    Objective-C

    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.

    See also tDataNodePtr.

    Import Statement

    Objective-C

    @import DirectoryService;

    Swift

    import DirectoryService

    Availability

    Available in OS X v10.0 and later.

  • A pointer to a value of type tDataNode.

    Declaration

    Swift

    typealias tDataNodePtr = UnsafeMutablePointer<tDataNode>

    Objective-C

    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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Swift

    import DirectoryService

    Availability

    Available in OS X v10.0 and later.

  • A value returned when a node is opened.

    Declaration

    Swift

    typealias tDirNodeReference = UInt32

    Objective-C

    typedef UInt32 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Swift

    import DirectoryService

    Availability

    Available in OS X v10.0 and later.

  • A value returned when an Open Directory session is opened.

    Declaration

    Swift

    typealias tDirReference = UInt32

    Objective-C

    typedef UInt32 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.

    Import Statement

    Objective-C

    @import DirectoryService;

    Swift

    import DirectoryService

    Availability

    Available in OS X v10.0 and later.

  • A pointer to a value of type tRecordEntry.

    Declaration

    Swift

    typealias tRecordEntryPtr = UnsafeMutablePointer<tRecordEntry>

    Objective-C

    typedef tRecordEntry *tRecordEntryPtr;

    Import Statement

    Objective-C

    @import DirectoryService;

    Swift

    import DirectoryService

    Availability

    Available in OS X v10.0 and later.

  • A value returned when a record is opened.

    Declaration

    Swift

    typealias tRecordReference = UInt32

    Objective-C

    typedef UInt32 tRecordReference;

    Discussion

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

    Import Statement

    Objective-C

    @import DirectoryService;

    Swift

    import DirectoryService

    Availability

    Available in OS X v10.0 and later.

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.

  • Structure received when an Open Directory client calls dsAddAttribute.

    Declaration

    Objective-C

    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.

  • Structure when an Open Directory client calls dsAddAttributeValue.

    Declaration

    Objective-C

    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.

  • Structure received when an Open Directory client calls dsCloseAttributeList.

    Declaration

    Objective-C

    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.

  • Structure received when an Open Directory client calls dsCloseAttributeValueList.

    Declaration

    Objective-C

    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.

  • Structure received when an Open Directory client calls dsCloseDirNode.

    Declaration

    Objective-C

    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.

  • Structure received when an Open Directory client application calls dsCloseRecord.

    Declaration

    Objective-C

    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.

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

    Declaration

    Objective-C

    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.

  • Structure received when an Open Directory client calls dsDeleteRecord.

    Declaration

    Objective-C

    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.

  • Structure received when an Open Directory client calls dsDoAttributeValueSearch.

    Declaration

    Objective-C

    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 zero. If the plug-in can store all of the matching records in the buffer pointed to by fOutDataBuff, it sets fIOContinueData to zero 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 zero. 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 zero 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 zero.

    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 zero. 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 zero, sets fResult to eDSNoErr, and returns.

  • Structure received when an Open Directory client calls dsDoAttributeValueSearchWithData.

    Declaration

    Objective-C

    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 zero.

    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 zero.

    fIOContinueData

    Value of type tContextData containing continuation data. For the first in a series of calls to dsDoAttributeValueSearchWithData, the input value is zero. If the plug-in can store all of the matching records in the buffer pointed to by fOutDataBuff, it sets fIOContinueData to zero 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 zero. 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 zero 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 zero.

    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 zero. These settings indicate to the client application that it should call dsDoAttributeValueSearchWithData again to get the search results.

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

  • Structure received when an Open Directory client calls dsDoDirNodeAuth.

    Declaration

    Objective-C

    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 zero. 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 zero.

    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 zero, and returns.

  • Structure received when an Open Directory client calls dsDoMultipleAttributeValueSearch.

    Declaration

    Objective-C

    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 zero.

    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 zero. If the plug-in can store all of the matching records in the buffer pointed to by fOutDataBuff, it sets fIOContinueData to zero 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 zero. 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 zero 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 zero.

    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 zero. 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 zero, sets fResult to eDSNoErr, and returns.

  • Structure received when an Open Directory client calls dsDoMultipleAttributeValueSearch.

    Declaration

    Objective-C

    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 zero.

    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 zero.

    fIOContinueData

    Value of type tContextData containing continuation data. For the first in a series of calls to dsDoAttributeValueSearch, the input value is zero. If the plug-in can store all of the matching records in the buffer pointed to by fOutDataBuff, it sets fIOContinueData to zero 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 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 zero. 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 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 zero 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 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 zero.

    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 zero. 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 zero, sets fResult to eDSNoErr, and returns.

  • Structure received when an Open Directory client calls dsDoPluginCustomCall.

    Declaration

    Objective-C

    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.

  • Structure received when an Open Directory client calls dsFlushRecord.

    Declaration

    Objective-C

    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.

  • Structure received when an Open Directory client calls dsGetAttributeEntry.

    Declaration

    Objective-C

    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.

  • Structure received when an Open Directory client calls dsGetAttributeValue.

    Declaration

    Objective-C

    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.

  • Structure received when an Open Directory client application calls dsGetDirNodeInfo.

    Declaration

    Objective-C

    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 zero. If all of the directory node information fits in the buffer pointed to by fOutDataBuff, the plug-in sets fOutContinueData to zero. 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 zero, sets fOutAttrInfoCount to zero, and returns.

  • Structure received when an Open Directory client calls dsGetRecordAttributeInfo.

    Declaration

    Objective-C

    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.

  • Structure received when an Open Directory client calls dsGetRecordAttributeValueByID.

    Declaration

    Objective-C

    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.

  • Structure received when an Open Directory client calls dsGetRecordAttributeValueByIndex.

    Declaration

    Objective-C

    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.

  • Structure received when an Open Directory client calls dsGetRecordAttributeValueByValue.

    Declaration

    Objective-C

    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.

  • Structure received when an Open Directory client calls dsGetRecordEntry.

    Declaration

    Objective-C

    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.

  • Structure called when an Open Directory client calls dsGetRecordList.

    Declaration

    Objective-C

    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 zero.

    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 zero.

    fIOContinueData

    Value of type tContextData containing continuation data. For the first in a series of calls to dsGetRecordList, the input value is zero. If the plug-in can store all of the matching records in the buffer pointed to by fInDataBuff, it sets fIOContinueData to zero 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 zero 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 zero.

    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 zero. 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 zero, and fResult to eDSNoErr, and returns.

  • Structure received when an Open Directory client calls dsGetRecordReferenceInfo.

    Declaration

    Objective-C

    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.

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

    Declaration

    Objective-C

    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.

  • Structure received when an Open Directory client calls dsOpenDirNode.

    Declaration

    Objective-C

    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.

  • Structure received when an Open Directory client calls dsOpenRecord.

    Declaration

    Objective-C

    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.

  • Structure received when an Open Directory client calls dsReleaseContinueData.

    Declaration

    Objective-C

    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.

  • Structure received when an Open Directory client calls dsRemoveAttribute.

    Declaration

    Objective-C

    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.

  • Structure received when an Open Directory client calls dsRemoveAttributeValue.

    Declaration

    Objective-C

    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.

  • Structure received when an Open Directory client calls dsSetAttributeValue.

    Declaration

    Objective-C

    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.

  • Structure received when an Open Directory client calls dsSetAttributeValues.

    Declaration

    Objective-C

    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 that points to a tAttributeValueEntry structure containing the attribute ID of the attribute whose values are to be replaced and a list of the replacement values.

    Discussion

    The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sSetAttributeValues structure when an Open Directory client calls dsSetAttributeValues to replace multiple values for the specified attribute. If the attribute does not exist, the plug-in creates the attribute and sets it to the values specified by fInAttrValueList.

    The plug-in uses the fInRecRef field of the sSetAttributeValues 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 for which values are to be set. The fInAttrValueList field points to a tDataList structure containing a list of values that are to be set for the attribute.

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

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

  • Structure received when an Open Directory client calls dsSetRecordName.

    Declaration

    Objective-C

    typedef struct { uInt32 fType; sInt32 fResult; tRecordReferencefInRecRef; tDataNodePtr fInNewRecName; } sSetRecordName;

    Fields

    fType

    Always kSetRecordName.

    fResult

    Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to set the record’s name. If an error occurs, the plug-in sets fResult to a value listed in Result Codes.

    fInRecRef

    Value of type tRecordReference representing the record whose name is to be set. The plug-in created the value of fInRecRef when it was called to process a request to open the record.

    fInNewRecName

    Value of type tDataNodePtr that points to a tDataNode structure containing the name in UTF-8 encoding that is to be set.

    Discussion

    The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sSetRecordName structure when an Open Directory client calls dsSetRecordName to set the name of a record.

    The plug-in uses the fInRecRef field of the sSetRecordName structure to determine the record whose name is to be set.

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

    If the plug-in cannot set the new name, it sets fResult to an appropriate result code as described in Result Codes and returns.

  • Structure received when an Open Directory client application calls dsSetRecordType.

    Declaration

    Objective-C

    typedef struct { uInt32 fType; sInt32 fResult; tRecordReference fInRecRef; tDataNodePtr fInNewRecType; } sSetRecordType;

    Fields

    fType

    Always kSetRecordType.

    fResult

    Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to set the record’s type. If an error occurs, the plug-in sets fResult to a value listed in Result Codes.

    fInRecRef

    Value of type tRecordReference representing the record whose type is to be set. The plug-in created the value of fInRecRef when it was called to process a request to open the record.

    fInNewRecType

    Value of type tDataNodePtr that points to a tDataNode structure containing the type that is to be set.

    Discussion

    The DirectoryService daemon calls a plug-in’s ProcessRequest entry point and passes an sSetRecordType structure when an Open Directory client calls dsSetRecordType to set a record’s type.

    The plug-in uses the fInRecRef field of the sSetRecordType structure to determine the record whose type is to be set.

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

    If the plug-in cannot set the new type, it sets fResult to an appropriate result code as described in Result Codes and returns.

    Note that this structure is deprecated in OS X v10.3 and later and is not supported on LDAP.

Constants

  • Authentication constants.

    Declaration

    Objective-C

    #define kDSStdAuthMethodPrefix "dsAuthMethodStandard:" #define kDSNativeAuthMethodPrefix “dsAuthMethodNative:” #define kDSSetPasswordBestOf “dsSetPasswdBestOf” #define kDSValueAuthAuthorityDefault "kDSValueAuthAuthorityBasic” #define kDSValueAuthAuthorityBasic ";basic;" #define kDSTagAuthorityBasic ";basic;" #define kDSValueAuthAuthorityLocalWindowsHash ";LocalWindowsHash;" #define kDSTagAuthAuthorityLocalWindowsHash "LocalWindowsHash" #define kDSValueAuthAuthorityShadowHash ";ShadowHash;" #define kDSTagAuthAuthoridyShadowHash "ShadowHash" #define kDSTagAuthAuthorityBetterHashOnly "BetterHashOnly" #define kDSValueAuthAuthorityPasswordServerPrefix ";ApplePasswordServer;" #define kDSTagAuthAuthorityPasswordServer "ApplePasswordServer" #define kDSValueAuthAuthorityKerberosv5 ";Kerberosv5;" #define kDSTagAuthAuthorityKerberosv5 "Kerberosvr5" #define kDSValueAuthAuthorityLocalCachedUser ";LocalCachedUser;" #define kDSTagAuthAuthorityLocalCachedUser "LocalCachedUser" #define kDSValueAuthAuthorityDisabledUser ";DisabledUser;" #define kDSTagAuthAuthorityDisabledUser "DisabledUser" #define kDSValueNonCryptPasswordMarker "********"

    Constants

    • kDSStdAuthMethodPrefix

      kDSStdAuthMethodPrefix

      Prefix defined for standard authentication methods.

    • kDSNativeAuthMethodPrefix

      kDSNativeAuthMethodPrefix

      Prefix defined for native authentication methods.

    • kDSSetPasswdBestOf

      kDSSetPasswdBestOf

      Not used; retained for backward compatibility only.

    • kDSValueAuthAuthorityDefault

      kDSValueAuthAuthorityDefault

      The default value to use for the kDSNAttrAuthenticationAuthority attribute. Set this attribute before creating a user record. By default, the value of this attribute is kDSValueAuthAuthorityBasic.

    • kDSValueAuthAuthorityBasic

      kDSValueAuthAuthorityBasic

      Standard authentication authority value for basic (crypt) authentication.

    • kDSTagAuthAuthorityBasic

      kDSTagAuthAuthorityBasic

      Standard center tag data of the authentication authority value for basic (crypt) authentication.

      Available in OS X v10.2 and later.

    • kDSValueAuthAuthorityLocalWindowsHash

      kDSValueAuthAuthorityLocalWindowsHash

      Standard authentication authority value for Local Windows Hash authentication; retained for backward compatibility only.

    • kDSTagAuthAuthorityLocalWindowsHash

      kDSTagAuthAuthorityLocalWindowsHash

      Standard center tag data of the authentication authority value for Local Windows Hash authentication. Available in OS X v10.2 and later but retained for backward compatibility only in OS X v10.3 and later.

    • kDSValueAuthAuthorityShadowHash

      kDSValueAuthAuthorityShadowHash

      Standard authentication authority value for ShadowHash authentication.

      Available in OS X v10.2 and later.

    • kDSTagAuthAuthorityShadowHash

      kDSTagAuthAuthorityShadowHash

      Standard center tag data of the authentication authority value for ShadowHash authentication.

      Available in OS X v10.3 and later.

    • kDSTagAuthAuthorityBetterHashOnly

      kDSTagAuthAuthorityBetterHashOnly

      Used as authentication authority data with Shadow Hash authentication authority. Available in OS X v10.3 and later. Superseded in Mac OX X version 10.4 by specifying customized hash lists. For details, see the section “Shadow Hash Authentication” in Chapter 1, “Concepts.”

    • kDSValueAuthAuthorityPasswordServerPrefix

      kDSValueAuthAuthorityPasswordServerPrefix

      Standard authentication authority value for Apple Password Server authentication.

    • kDSTagAuthAuthorityPasswordServer

      kDSTagAuthAuthorityPasswordServer

      Standard center tag data of the authentication authority value for Apple Password Server authentication.

      Available in OS X v10.3 and later.

    • kDSValueAuthAuthorityKerberosv5

      kDSValueAuthAuthorityKerberosv5

      Standard authentication authority value for Kerberos version 5 authentication.

      Available in OS X v10.3 and later.

    • kDSTagAuthAuthorityKerberosv5

      kDSTagAuthAuthorityKerberosv5

      Tag form of the Kerberos version 5 authentication type.

      Available in OS X v10.3 and later.

    • kDSValueAuthAuthorityLocalCachedUser

      kDSValueAuthAuthorityLocalCachedUser

      Standard authentication authority value for Local Cached User authentication.

      Available in OS X v10.3 and later.

    • kDSTagAuthAuthorityLocalCachedUser

      kDSTagAuthAuthorityLocalCachedUser

      Standard center tag data of the authentication authority value for Local Cached User authentication.

      Available in OS X v10.3 and later.

    • kDSValueAuthAuthorityDisabledUser

      kDSValueAuthAuthorityDisabledUser

      Standard authentication authority value for Disabled User authentication.

      Available in OS X v10.2 and later.

    • kDSTagAuthAuthorityDisabledUser

      kDSTagAuthAuthorityDisabledUser

      Standard center tag data of the authentication authority value for Disabled User authentication.

      Available in OS X v10.2 and later.

    • kDSValueNonCryptPasswordMarker

      kDSValueNonCryptPasswordMarker

      Marker used for password attribute value to indicate non-crypt authentication.

  • Constants defined for authentication methods.

    Declaration

    Objective-C

    #define kDSStdAuth2WayRandom "dsAuthMethodStandard:dsAuth2WayRandom" #define kDSStdAuth2WayRandomChangePasswd "dsAuthMethodStandard:dsAuth2WayRandomChangePasswd" #define kDSStdAuthAPOP "dsAuthMethodStandard:dsAuthAPOP" #define kDSStdAuthCHAP "dsAuthMethodStandard:dsAuthCHAP" #define kDSStdAuthCRAM_MD5 "dsAuthMethodStandard:dsAuthNodeCRAM-MD5" #define kDSStdAuthChangePasswd "dsAuthMethodStandard:dsAuthChangePasswd" #define kDSStdAuthClearText "dsAuthMethodStandard:dsAuthClearText" #define kDSStdAuthCrypt "dsAuthMethodStandard:dsAuthCrypt" #define kDSStdAuthDIGEST_MD5 "dsAuthMethodStandard:dsAuthNodeDIGEST-MD5" #define kDSStdAuthDeleteUser "dsAuthMethodStandard:dsAuthDeleteUser" #define kDSStdAuthGetEffectivePolicy "dsAuthMethodStandard:dsAuthGetEffectivePolicy" #define kDSStdAuthGetGlobalPolicy "dsAuthMethodStandard:dsAuthGetGlobalPolicy" #define kDSStdAuthGetKerberosPrincipal "dsAuthMethodStandard:dsAuthGetKerberosPrincipal" #define kDSStdAuthGetPolicy "dsAuthMethodStandard:dsAuthGetPolicy" #define kDSStdAuthGetUserData "dsAuthMethodStandard:dsAuthGetUserData" #define kDSStdAuthGetUserName "dsAuthMethodStandard:dsAuthGetUserName" #define kDSStdAuthMASKE_A "dsAuthMethodStandard:dsAuthMASKE-A"