Directory Services Reference

Overview

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

Functions by Task

Open Directory Client Functions

• dsAddAttribute
• dsAddAttributeValue
• dsAddChildPIDToReference
• dsAllocAttributeValueEntry
• dsAppendStringToListAlloc
• dsBuildListFromNodesAlloc
• dsBuildFromPath
• dsBuildListFromPathAlloc
• dsBuildListFromStrings
• dsBuildListFromStringsAlloc
• dsBuildListFromStringsAllocV
• dsCloseAttributeList
• dsCloseAttributeValueList
• dsCloseDirNode
• dsCloseDirService
• dsCloseRecord
• dsCreateRecord
• dsCreateRecordAndOpen
• dsDataBufferAllocate
• dsDataBufferDeAllocate
• dsDataListAllocate
• dsDataListCopyList
• dsDataListDeallocate
• dsDataListGetNodeAlloc
• dsDataListGetNodeCount
• dsDataListInsertAfter
• dsDataListMergeListAfter
• dsDataListDeleteThisNode
• dsDataNodeAllocateBlock
• dsDataNodeAllocateString
• dsDataNodeDeAllocate
• dsDataNodeGetSize
• dsDataNodeGetLength
• dsDataNodeSetLength
• dsDeallocAttributeEntry
• dsDeallocAttributeValueEntry
• dsDeallocRecordEntry
• dsDeleteRecord
• dsDoAttributeValueSearch
• dsDoAttributeValueSearchWithData
• dsDoDirNodeAuth
• dsDoDirNodeAuthOnRecordType
• dsDoMultipleAttributeValueSearch
• dsDoMultipleAttributeValueSearchWithData
• dsDoPlugInCustomCall
• dsFindDirNodes
• dsFlushRecord
• dsGetAttributeEntry
• dsGetAttributeValue
• dsGetDataLength
• dsGetDirNodeCount
• dsGetDirNodeCountWithInfo
• dsGetDirNodeInfo
• dsGetDirNodeList
• dsGetDirNodeName
• dsGetPathFromList
• dsGetRecordAttributeInfo
• dsGetRecordAttributeValueByID
• dsGetRecordAttributeValueByIndex
• dsGetRecordAttributeValueByValue
• dsGetRecordEntry
• dsGetRecordList
• dsGetRecordReferenceInfo
• dsGetRecordNameFromEntry
• dsGetRecordTypeFromEntry
• dsIsDirServiceRunning
• dsOpenDirNode
• dsOpenDirService
• dsOpenDirServiceProxy
• dsOpenRecord
• dsReleaseContinueData
• dsRemoveAttribute
• dsRemoveAttributeValue
• dsSetAttributeValue
• dsSetAttributeValues
• dsSetRecordName
• dsSetRecordType
• dsVerifyDirRefNum

Open Directory Plug-in Functions

• Initialize
• PeriodicTask
• ProcessRequest
• SetPluginState
• Shutdown
• Validate

Functions

dsAddAttribute

Adds an attribute to a record.

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

dsAddAttributeValue

Adds a value to an attribute.

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

dsAddChildPIDToReference

Allows the specified process to use a node reference.

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

dsAllocAttributeValueEntry

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

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

dsAppendStringToListAlloc

Appends a string to a data list.

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

dsBuildFromPath

Builds a data list from a pathname.

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

dsBuildListFromNodesAlloc

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

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

dsBuildListFromPathAlloc

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

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

dsBuildListFromStrings

Builds a data list from strings.

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

dsBuildListFromStringsAlloc

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

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

dsBuildListFromStringsAllocV

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

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

dsCloseAttributeList

Disposes of an attribute list reference.

tDirStatus dsCloseAttributeList (
   tAttributeListRef inAttributeListRef
);

dsCloseAttributeValueList

Disposes of an attribute value list reference.

tDirStatus dsCloseAttributeValueList (
   tAttributeValueListRef inAttributeValueListRef
);

dsCloseDirNode

Closes a session with a node.

tDirStatus dsCloseDirNode (
   tDirNodeReference inDirNodeReference
);

dsCloseDirService

Closes an Open Directory session.

tDirStatus dsCloseDirService (
   tDirReference inDirReference
);

dsCloseRecord

Closes a open record.

tDirStatus dsCloseRecord (
   tRecordReference inRecordReference
);

dsCreateRecord

Creates a record.

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

dsCreateRecordAndOpen

Creates a record and opens it.

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

dsDataBufferAllocate

Allocates an Open Directory data buffer.

tDataBufferPtr dsDataBufferAllocate (
   tDirReference inDirReference,
   UInt32 inBufferSize
);

dsDataBufferDeAllocate

Deallocates an Open Directory data buffer.

tDirStatus dsDataBufferDeAllocate (
   tDirReference inDirReference,
   tDataBufferPtr inDataBufferPtr
);

dsDataListAllocate

Allocates a data list.

tDataListPtr dsDataListAllocate (
   tDirReference inDirReference
);

dsDataListCopyList

Copies a data list.

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

dsDataListDeallocate

Deallocates a data list.

tDirStatus dsDataListDeallocate (
   tDirReference inDirReference,
   tDataListPtr inDataList
);

dsDataListDeleteThisNode

Deletes a data node from a data list.

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

dsDataListGetNodeAlloc

Gets a data node from a data list.

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

dsDataListGetNodeCount

Gets the number of data nodes in a data list.

UInt32 dsDataListGetNodeCount (
   const tDataList *inDataList
);

dsDataListInsertAfter

Inserts a data node in a data list.

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

dsDataListMergeListAfter

Merges two data lists.

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

dsDataNodeAllocateBlock

Allocates an Open Directory data node.

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

dsDataNodeAllocateString

Allocates an Open Directory data node using a string.

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

dsDataNodeDeAllocate

Deallocates a data node.

tDirStatus dsDataNodeDeAllocate (
   tDirReference inDirReference,
   tDataNodePtr inDataNodePtr
);

dsDataNodeGetLength

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

UInt32 dsDataNodeGetLength (
   tDataNodePtr inDataNodePtr
);

dsDataNodeGetSize

Gets the size of a data node’s buffer.

UInt32 dsDataNodeGetSize (
   tDataNodePtr inDataNodePtr
);

dsDataNodeSetLength

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

tDirStatus dsDataNodeSetLength (
   tDataNodePtr inDataNodePtr,
   UInt32 inDataNodeLength
);

dsDeallocAttributeEntry

Deallocates an attribute entry structure.

tDirStatus dsDeallocAttributeEntry (
   tDirReference inDirRef,
   tAttributeEntryPtr inAttrEntry
);

dsDeallocAttributeValueEntry

Deallocates an attribute value entry structure.

tDirStatus dsDeallocAttributeValueEntry (
   tDirReference inDirRef,
   tAttributeValueEntryPtr inAttrValueEntry
);

dsDeallocRecordEntry

Deallocates a record entry structure.

tDirStatus dsDeallocRecordEntry (
   tDirReference inDirRef,
   tRecordEntryPtr inRecEntry
);

dsDeleteRecord

Deletes a record.

tDirStatus dsDeleteRecord (
   tRecordReference inRecordReference
);

dsDoAttributeValueSearch

Searches a node for records by attribute value.

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

dsDoAttributeValueSearchWithData

Searches for records by attribute type and attribute value.

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

dsDoDirNodeAuth

Performs authentication with a node.

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

dsDoDirNodeAuthOnRecordType

Performs authentication using a record type.

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

dsDoMultipleAttributeValueSearch

Uses multiple attribute values to search a node for records.

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

dsDoMultipleAttributeValueSearchWithData

Searches for records by attribute type and multiple attribute values.

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

dsDoPlugInCustomCall

Exchanges custom information with an Open Directory plug-in.

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

dsFindDirNodes

Finds the registered node names that match a pattern.

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

dsFlushRecord

Writes a record.

tDirStatus dsFlushRecord (
   tRecordReference inRecordReference
);

dsGetAttributeEntry

Gets an attribute entry from a data buffer.

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

dsGetAttributeValue

Gets the value of an attribute from a data buffer.

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

dsGetDataLength

Gets the length of data in a data list.

UInt32 dsGetDataLength (
   const tDataList *inDataList
);

dsGetDirNodeCount

Gets the total number of registered nodes.

tDirStatus dsGetDirNodeCount (
   tDirReference inDirReference,
   UInt32 *outDirectoryNodeCount
);

dsGetDirNodeCountWithInfo

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

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

dsGetDirNodeInfo

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

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

dsGetDirNodeList

Gets the names of registered nodes.

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

dsGetDirNodeName

Gets node names from a buffer.

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

dsGetPathFromList

Gets the path from a data list.

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

dsGetRecordAttributeInfo

Gets information about a record’s attribute.

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

dsGetRecordAttributeValueByID

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

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

dsGetRecordAttributeValueByIndex

Uses an index to get the value of an attribute.

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

dsGetRecordAttributeValueByValue

Verifies the existence of an attribute value within a record.

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

dsGetRecordEntry

Gets the next record from a data buffer.

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

dsGetRecordList

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

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

dsGetRecordNameFromEntry

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

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

dsGetRecordReferenceInfo

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

tDirStatus dsGetRecordReferenceInfo (
   tRecordReference inRecordReference,
   tRecordEntryPtr *outRecordInfo
);

dsGetRecordTypeFromEntry

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

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

dsIsDirServiceRunning

Checks to see if Open Directory is running.

tDirStatus dsIsDirServiceRunning

dsOpenDirNode

Opens a session with a node.

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

dsOpenDirService

Opens an Open Directory session.

tDirStatus dsOpenDirService (
   tDirReference *outDirReference
);

dsOpenDirServiceProxy

Opens a remote Open Directory session.

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

dsOpenRecord

Opens a record.

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

dsReleaseContinueData

Releases memory allocated for continuation data.

tDirStatus dsReleaseContinueData (
   tDirReference inDirReference,
   tContextData inContinueData
);

dsRemoveAttribute

Removes an attribute from a record.

tDirStatus dsRemoveAttribute (
   tRecordReference inRecordReference,
   tDataNodePtr inAttribute
);

dsRemoveAttributeValue

Removes an attribute value.

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

dsSetAttributeValue

Sets the value of an attribute.

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

dsSetAttributeValues

Sets multiple values for an attribute.

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

dsSetRecordName

Sets the name of a record.

tDirStatus dsSetRecordName (
   tRecordReference inRecordReference,
   tDataNodePtr inNewRecordName
);

dsSetRecordType

Sets the type of a record.

tDirStatus dsSetRecordType (
   tRecordReference inRecordReference,
   tDataNodePtr inNewRecordType
);

dsVerifyDirRefNum

Verifies that a tDirReference is valid.

tDirStatus dsVerifyDirRefNum (
   tDirReference inDirReference
);

Initialize

Initializes the plug-in.

virtual void Initialize(void)

PeriodicTask

Performs a periodic task.

SInt32 PeriodicTask (void);

ProcessRequest

Processes requests.

SInt32 ProcessRequest (void *inData);

SetPluginState

Sets the plug-in’s state.

SInt32 SetPluginState (UInt32 inNewState);

Shutdown

Prepares the plug-in for shut down.

SInt32 Shutdown (void);

Validate

Validates the plug-in.

SInt32 Validate (UInt32 inSignature);

Callbacks

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

DSDebugLog

Writes information in the log file.

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

DSRegisterNode

Registers a node.

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

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

DSUnregisterNode

Unregisters a node.

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

Data Types

Open Directory Structures

This section describes structures used by the Open Directory client.

tAttributeEntry

A structure used to store information about an attribute.

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

tAttributeValueEntry

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

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.

tDataBuffer

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

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.

tDataList

An ordered list of tDataNode structures.

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.

tRecordEntry

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

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.

Other Open Directory Data Types

Data types used by the Open Directory Client.

tAttributeEntryPtr

A pointer to a tAttributeEntry structure.

typedef tAttributeEntry *tAttributeEntryPtr;

tAttributeListRef

A reference used to get attribute entries.

typedef UInt32 tAttributeListRef;

tAttributeValueEntryPtr

A pointer to a tAttributeValueEntry structure.

typedef tAttributeValueEntry *tAttributeValueEntryPtr;

tAttributeValueListRef

A reference used to get attribute value entries.

typedef UInt32 tAttributeValueListRef;

tBuffer

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

typedef void *tBuffer;

tContextData

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

typedef UInt32 tContextData;

tDataBufferPtr

A pointer to a value of type tDataBuffer.

typedef tDataBuffer *tDataBufferPtr;

tDataListPtr

A pointer to a value of type tDataList.

typedef tDataList *tDataListPtr;

tDataNode

A value of type tDataBuffer.

typedef tDataBuffer tDataNode;

tDataNodePtr

A pointer to a value of type tDataNode.

typedef tDataNode *tDataNodePtr;

tDirNodeReference

A value returned when a node is opened.

typedef UInt32 tDirNodeReference;

tDirReference

A value returned when an Open Directory session is opened.

typedef UInt32 tDirReference;

tRecordEntryPtr

A pointer to a value of type tRecordEntry.

typedef tRecordEntry *tRecordEntryPtr;

tRecordReference

A value returned when a record is opened.

typedef UInt32 tRecordReference;

Request Structures

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

sAddAttribute

Structure received when an Open Directory client calls dsAddAttribute.

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

Fields

fType

Always kAddAttribute.

fResult

Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to add the attribute. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”

fInRecRef

Value of type tRecordReference representing the record to which the attribute is to be added. The record must have been previously opened when the plug-in’s routine for processing sOpenRecord structures was called.

fInNewAttr

Value of type tDataNodePtr that points to a value of type tDataNode containing the name of the attribute that is to be added.

fInNewAttrAccess

Reserved for this release. Client applications are advised to set this value to NULL. For this release, plug-ins should ignore the value of this field.

fInFirstAttrValue

Value of type tDataListPtr that points to a value of type tDataNode containing the first value of the attribute that is being added. The tDataNode may contain an empty string or fInFirsAttrValue may be NULL to indicate that the client application does not want to set the attribute’s value.

sAddAttributeValue

Structure when an Open Directory client calls dsAddAttributeValue.

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

Fields

fType

Always kAddAttributeValue.

fResult

Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to add the value to the attribute. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”

fInRecRef

Value of type tRecordReference representing the record for which a value is to be add to an attribute.

fInAttrType

Value of type tDataNodePtr that points to a value of type tDataNode containing the type of the attribute to which a value is to be added.

fInAttrValue

Value of type tDataNodePtr that points to a value of type tDataNode containing the value that is to be added.

sCloseAttributeList

Structure received when an Open Directory client calls dsCloseAttributeList.

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

Fields

fType

Always kCloseAttributeList.

fResult

Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to close the specified attribute list reference. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”

fInAttributeListRef

Value of type tAttributeListRef representing the attribute list reference that is to be closed.

sCloseAttributeValueList

Structure received when an Open Directory client calls dsCloseAttributeValueList.

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

Fields

fType

Always kCloseAttributeValueList.

fResult

Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to close the specified attribute value list reference. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”

fInAttributeValueListRef

Value of type tAttributeValueListRef representing the attribute value list reference that is to be closed.

sCloseDirNode

Structure received when an Open Directory client calls dsCloseDirNode.

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

Fields

fType

Always kCloseDirNode.

fResult

Value of type sInt32s that the plug-in sets to eDSNoErr before returning to indicate that it was able to close the directory node session specified by fInNodeRef. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”

fInNodeRef

Value of type tDirReference that identifies the directory node session that is to be closed. The directory node reference was created when the client application opened the directory node session that is to be closed.

sCloseRecord

Structure received when an Open Directory client application calls dsCloseRecord.

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

Fields

fType

Always kCloseRecord.

fResult

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

fInRecRef

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

sCreateRecord

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

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

Fields

fType

Always kCreateRecord or kCreateRecordAndOpen.

fResult

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

fInNodeRef

Value of type tDirNodeReference that identifies the directory node in which the record is to be created. The directory node reference was created when the client application opened a session with the directory node.

fInRecType

Value of type tDataNodePtr that points to a tDataNode structure containing the type that is to be assigned to the created record.

fInRecName

Value of type tDataNodePtr that points to a tDataNode structure containing the name that is to be assigned to the record that is created.

fInOpen

Boolean whose value is TRUE if the client application wants to create the record and open it. Otherwise, the value of fInOpen is FALSE to indicate that the client application wants to create the record without opening it.

fOutRecRef

Value of type tRecordReference assigned by the DirectoryService daemon and that the plug-in associates with the internal structure the plug-in uses to maintain information about the reference.

sDeleteRecord

Structure received when an Open Directory client calls dsDeleteRecord.

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

Fields

fType

Always kDeleteRecord.

fResult

Value of type uInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to delete the record. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”

fInRecRef

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

sDoAttrValueSearch

Structure received when an Open Directory client calls dsDoAttributeValueSearch.

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

Fields

fType

Always kDoAttributeValueSearch.

fResult

Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to search for the attribute values. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.” If no matches are found, the plug-in should set fResult to eDSNoErr, fInOutMatchRecordCount to zero, and fIOContinueData to NULL.

fInNodeRef

Value of type tDirNodeReference that identifies the directory node for which the search is to be conducted. The directory node reference was created when the client application opened the directory node session.

fOutDataBuff

Value of type tDataBufferPtr that points to the tDataBuffer structure in which the plug-in is to place search results.

fInRecTypeList

Value of type tDataListPtr pointing to a tDataList structure containing the record types that are to be searched. See Standard Record Types and Meta Record Type Constants for possible values. If NULL, set fResult to eDSEmptyRecordTypeList and return.

fInAttrType

Value of type tDataNodePtr pointing to a tDataNode structure containing the attribute types that are to be searched for. See the attribute constants described in the “Constants” section for possible values. If NULL, set fResult to eDSEmptyAttributeType and return.

fInPattMatchType

Value of type tDirPatternMatch that describes the way in which the pattern specified by fInPatt2Match is to be matched. The pattern match type can be a value that the plug-in and application agree upon or a constant defined by Open Directory, as described in the section Pattern Matching Constants.

fInPatt2Match

Value of type tDataNodePtr pointing to a tDataNode structure containing the pattern that is to be matched.

fInOutMatchRecordCount

Value of type unsigned long. The first time the client application calls dsDoAttributeValueSearch, fInOutMatchRecordCount is zero to receive all matching records or is a positive integer value that specifies the total number of records the client application wants to receive across what may be a series of dsDoAttributeValueSearch calls. If the latter, the plug-in should use the initial input value of fInOutMatchRecordCount to limit the total number of matching records it returns. Before returning, the plug-in should set fInOutMatchRecordCount to the number of records it has placed in the buffer pointed to by fOutDataBuff. The plug-in should ignore the input value of fInOutMatchRecordCount whenever it is processing a sDoAttrValueSearch structure that has an fIOContinueData field that is not NULL.

fIOContinueData

Value of type tContextData containing continuation data. For the first in a series of calls to dsDoAttributeValueSearch, the input value is 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.

sDoAttrValueSearchWithData

Structure received when an Open Directory client calls dsDoAttributeValueSearchWithData.

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

Fields

fType

Always kDoAttributeValueSearchWithData.

fResult

Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to search for the attribute values. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.” If no matches are found, the plug-in should set fResult to eDSNoErr, fInOutMatchRecordCount to zero, and fIOContinueData to 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.

sDoDirNodeAuth

Structure received when an Open Directory client calls dsDoDirNodeAuth.

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

Fields

fType

Always kDoDirNodeAuth.

fResult

Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to authenticate the session. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”

fInNodeRef

Value of type tDirNodeReference that identifies the directory node session that is to be authenticated. The directory node reference was created when the client application opened the session with the directory node.

fInAuthMethod

Value of type tDataNodePtr that points to a tDataNode structure containing the authentication task that is to be performed.Examples include kDSStdAuthSetPasswd, kDSStdAuthSetPasswdAsRoot, and kDSStdAuthChangePasswd to set or change a password and kDSStdAuthClearText and kDSStdAuth2WayRandom to authenticate a user for a directory node session. See the attribute constants described in the “Constants” section for possible values.

fInDirNodeAuthOnlyFlag

Boolean value that is TRUE if the client application does not want the result of this authentication to be used to grant or deny access for subsequent operations pertaining to this node. When the value of fInDirNodeAuthOnlyFlag is FALSE, the client application wants the result of this authentication to be applied to other operations that pertain to this directory node.

fInAuthStepData

Value of type tDataBufferPtr pointing to a tDataBuffer structure that contains a value that identifies the step in the authentication process for which the plug-in ProcessRequest routine has been called.

fOutAuthStepDataResponse

Value of type tDataBufferPtr that points to the tDataBuffer structure in which the plug-in is to place its response.

fIOContinueData

Value of type tContextData. If this the first step in the authentication process, fIOContinueData is 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.

sDoMultiAttrValueSearch

Structure received when an Open Directory client calls dsDoMultipleAttributeValueSearch.

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

Fields

fType

Always kDoMultipleAttributeValueSearch.

fResult

Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to search for the attribute values. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.” If no matches are found, the plug-in should set fResult to eDSNoErr, fInOutMatchRecordCount to zero, and fIOContinueData to 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.

sDoMultiAttrValueSearchWithData

Structure received when an Open Directory client calls dsDoMultipleAttributeValueSearch.

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

Fields

fType

Always kDoMultipleAttributeValueSearchWithData.

fResult

Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to search for the attribute values. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.” If no matches are found, the plug-in should set fResult to eDSNoErr, fInOutMatchRecordCount to zero, and fIOContinueData to 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.

sDoPluginCustomCall

Structure received when an Open Directory client calls dsDoPluginCustomCall.

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

Fields

fType

Always kDoPlugInCustomCall.

fResult

Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that the plug-in responded without error when it processed the sDoPluginCustomCall structure. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”

fInNodeRef

Value of type tDirNodeReference that identifies the directory node session to which fInRequestCode and fInRequestData apply.

fInRequestCode

Value of type unsigned long that contains a request code that has significance to the plug-in.

fInRequestData

Value of type tDataBufferPtr that points to a tDataBuffer structure containing data sent by the client application to the plug-in.

fOutRequestResponse

Value of type tDataBufferPtr that points to a tDataBuffer structure in which the plug-in places data that is to be returned to the client application.

sFlushRecord

Structure received when an Open Directory client calls dsFlushRecord.

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

Fields

fType

Always kFlushRecord.

fResult

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

fInRecRef

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

sGetAttributeEntry

Structure received when an Open Directory client calls dsGetAttributeEntry.

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

Fields

fType

Always kGetAttributeEntry.

fResult

Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to get the requested attribute information. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”

fInNodeRef

Value of type tDirNodeReference that identifies the directory node of the record whose attribute information is to be obtained. The directory node reference was created when the client application opened the directory node session.

fInOutDataBuff

Value of type tDataBufferPtr that points to the tDataBuffer structure from which the attribute information is to be obtained.

fInAttrListRef

Value of type tAttributeListRef that refers to an attribute list that the plug-in returned to the client application when it processed a sGetDirNodeInfo or a sGetRecordEntry structure or that the plug-in returned to the client application when it previously called dsGetAttributeEntry. The plug-in uses the attribute list reference to locate the attribute information in the buffer pointed to by fInOutDataBuff.

fInAttrInfoIndex

Value of type unsigned long that specifies the one-based index number of the attribute whose information is to be obtained from the buffer pointed to by fInOutDataBuff.

fOutAttrValueListRef

Value of type tAttributeValueListRef assigned by the DirectoryService daemon and that the plug-in associates with the internal structure the plug-in uses to maintain information about the reference.

fOutAttrInfoPtr

Pointer to a value of type tAttributeValueEntryPtr that points to a tAttributeEntry structure in which the plug-in is to place the attribute information.

sGetAttributeValue

Structure received when an Open Directory client calls dsGetAttributeValue.

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

Fields

fType

Always kGetAttributeValue.

fResult

Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to get the requested attribute value. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”

fInNodeRef

Value of type tDirNodeReference that identifies the directory node of the record whose attribute value is to be obtained. The directory node reference was created when the client application opened the directory node session.

fInOutDataBuff

Value of type tDataBufferPtr pointing to the tDataBuffer structure containing information previously obtained when the plug-in responded to an sGetRecordList, sDoAttrValueSearch, sDoAttrValueSearchWithData, sDoMultiAttrValueSearch, or sDOMultiAttrValueSearchWithData request from the client application.

fInAttrValueIndex

Value of type unsigned long containing a one-based index that specifies which attribute value to get. A value of 1 specifies the first value, a value of 2 specifies the second value, and so on.

fInAttrValueListRef

Value of type tAttributeValueListRef created by the plug-in when its routine for processing sGetAttributeEntry structures was called. The reference contains information that the plug-in uses to locate the attribute value in the data buffer pointed to by fInOutDataBuff.

fOutAttrValue

Value of type tAttributeValueEntryPtr pointing to the tAttributeValueEntry structure in which the plug-in is to place the value of the attribute specified by the fInAttrValueIndex field.

sGetDirNodeInfo

Structure received when an Open Directory client application calls dsGetDirNodeInfo.

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

Fields

fType

Always kGetDirNodeInfo.

fResult

Value of type sInt32 that the plug-in sets to eDSNoErr before returning to indicate that it was able to get information about the directory node identified by fInNodeRef. If an error occurs, the plug-in sets fResult to a value listed in “Result Codes.”

fInNodeRef

Value of type tDirNodeReference that identifies the directory node for which information is to be obtained. The directory node reference was created when the client application opened the directory node.

fInDirNodeInfoTypeList

Value of type tDataListPtr that points to a tDataList structure containing the attribute types for which information is being requested.

fOutDataBuff

Value of type tDataBufferPtr pointing to a tDataBuffer structure. If the plug-in obtains the requested information, it puts the information in the data buffer pointed to by fOutDataBuff.

fInAttrInfoOnly

Boolean value set to TRUE if the plug-in is only to provide information about attributes or set to FALSE if the plug-in is to provide the values of the attributes as well as information about the attributes.

fOutAttrInfoCount

On return, fOutAttrInfoCount contains the number of attribute types the plug-in has placed in the buffer pointed to by fOutDataBuff.

fOutAttrListRef

Value of type tAttributeListRef assigned by the DirectoryService daemon and that the plug-in associates with the internal structure the plug-in uses to maintain information about the reference.

fOutContinueData

Value of type tContextData that represents continuation data. If this is the first call in what may be a series of calls for this value of fInNodeRef, the input value of fOutContinueData is 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.