The Open Group Directory Service API (XDS)

This chapter identifies the conformance requirements of The Open Group Directory Services (XDS) API implementations for the DCE. For the full Open Group XDS API, see the referenced XDS specification.

The XDS interface comprises a number of functions, together with OM classes of OM objects, which are used as the arguments and results of the functions. Both the functions and the OM objects are based on the Abstract Service specified in the ISO 9594-3 standard.

The interface models the directory interactions as service requests made through a number of interface functions, which take a number of input arguments. Each valid request causes an operation to be performed by the directory service, which eventually returns a status and any result of the operation.

All interactions between the user and the directory service belong to a session, which is represented by an OM object passed as the first argument to most interface functions.

The other arguments to the functions include a context and various service-specific arguments.

XDS Conformance

DCE XDS is characterised by the following:

• It supports a synchronous interface. Asynchronous operations within the same thread are not supported.

• It supports all synchronous interface functions. The two asynchronous-specific functions are handled as follows:

  ds_abandon

  
  Calling this routine does not cause a directory service abandon operation to be performed; instead, the routine returns a [DS_C_ABANDON_FAILED] ([DS_E_TOO_LATE]) error.

  ds_receive_result

  
  If there are any outstanding operations (when multiple threads issue XDS calls in parallel), this functions returns [DS_SUCCESS], with the completion_flag_return argument set to a value of DS_OUTSTANDING_OPERATIONS. If no XDS calls are outstanding, then this function returns [DS_SUCCESS], and the completion_flag_return argument is set to a value of DS_NO_OUTSTANDING_OPERATION.

• Automatic connection management is not provided. The ds_bind () and ds_unbind () functions always try to set up or release directory service connections immediately.

• Support for local strings. XDS supports the mapping to/from local string formats. String mapping is supported by the following XDS/XOM functions:

  • dsX_extract_attr_values ()

  • omX_object_to_string ()

  • omX_string_to_object ()

  • om_get ()

  • om_read ()

  String mapping is requested by setting the local_strings boolean parameter to OM_TRUE. Currently supported mappings are:

  • T.61 String to/from ISO 8859-1 (Latin-1)

DCE XDS supports five packages, one of which is mandatory and the other four of which are optional. Use of the optional packages is negotiated through the ds_version () routine. The packages are as follows:

• The Directory Service Package (as defined in the XDS specification) is mandatory. This also includes the directory service errors.

• The Basic Directory Contents Package (as defined in the XDS specification) is optional.

• The Strong Authentication Package (as defined in the XDS specification) is optional.

• The MHS Directory User Package (as defined in the XDS specification) is optional.

• The Global Directory Service Package (as defined in Global Directory Service Package ) is optional.

None of the OM classes defined in these packages are encodable. As a result, DCE XDS application programmers do not require the use of the XOM functions om_encode () and om_decode (), which are not supported by the DCE XOM API.

XDS Functions

The OSI Directory Service standards define Abstract Services that requestors use to interact with the directory. Each of these Abstract Services maps to a single function call, and the detailed specifications of the calls are given in the XDS reference pages in the XDS specification. The services, and the function calls to which they map, are as follows:

DirectoryBind

Maps to ds_bind ().

DirectoryUnbind

Maps to ds_unbind ().

Read

Maps to ds_read ().

Compare

Maps to ds_compare ().

Abandon

Maps to ds_abandon ().

List

Maps to ds_list ().

Search

Maps to ds_search ().

AddEntry

Maps to ds_add_entry ().

RemoveEntry

Maps to ds_remove_entry ().

ModifyEntry

Maps to ds_modify_entry ().

ModifyRDN

Maps to ds_modify_rdn ().

The XDS function ds_receive_result (), which is used with asynchronous operations, has no counterpart in the Abstract Service.

The ds_initialize (), ds_shutdown () and ds_version () functions are used to control the XDS API, and do not initiate any directory operations.

The interface functions are summarised in XDS Interface Functions .

Function	Description
ds_abandon ()	Abandons the result of a pending asynchronous operation. This function is not supported.
ds_add_entry ()	Adds a leaf entry to the DIT (Directory Information Tree).
ds_bind ()	Opens a session with a Directory User Agent (DUA), which in turn connects to a Directory Service Agent (DSA).
ds_compare ()	Compares a purported attribute value with the attribute value stored in the Directory Information Base (DIB) for a particular entry.
ds_initialize ()	Initialises the XDS interface.
ds_list ()	Enumerates the names of the immediate subordinates of a particular directory entry.
ds_modify_entry ()	Atomically performs modification of a directory entry.
ds_modify_rdn ()	Changes the Relative Distinguished Name (RDN) of a leaf entry.
ds_read ()	Queries information on a particular directory entry by name.
ds_receive_result ()	Retrieves the result of an asynchronously executed function. This function is not supported.
ds_remove_entry ()	Removes a leaf entry from the DIT.
ds_search ()	Finds entries of interest in a portion of the directory information tree.
ds_shutdown ()	Discards a workspace.
ds_unbind ()	Unbinds from a directory session.
ds_version ()	Negotiates features of the interface and service.

The XDS interface functions are fully specified in the XDS specification. The following sections specify the extensions made for the DCE XDS API for each of the interface functions.

ds_abandon()

The DCE XDS interface does not support asynchronous operations. Thus, ds_abandon () and ds_receive_result () are redundant. A ds_abandon () call always returns a [DS_C_ABANDON_FAILED] ([DS_E_TOO_LATE]) error.

ds_add_entry()

Note the following in regard to the ds_add_entry () operation:

• Only leaf objects (that is, objects that are not CDS directory objects) can be added to CDS through the XDS interface.

• Only the DS_A_COMMON_NAME and DS_A_MEMBER attributes are valid for the DS_O_GROUP_OF_NAMES object in CDS.

• GDS-structured attribute types are not supported by CDS. If an attempt is made to add a GDS-structured attribute type to CDS, ds_add_entry () returns a [DS_C_ATTRIBUTE_ERROR] ([DS_E_CONSTRAINT_VIOLATION]) error.

Since CDS does not support the X.500 schema rules, some CDS objects may not contain GDS-mandatory attributes, such as object class and so on.

ds_bind()

In order to use CDS when GDS is not active, ds_bind () must be called with the value of the session argument set to DS_DEFAULT_SESSION.

ds_compare()

Note the following in regard to the ds_compare () operation:

• In CDS, the naming attribute of an object is not stored in the object's attribute list. Thus, in CDS, an attempted ds_compare () of a naming attribute value with the naming attribute value of the directory object always fails to yield a match.

• GDS-structured types are not supported by CDS. If a GDS-structured attribute type is used as an argument to a ds_compare () on a CDS object, the call returns the error [DS_C_ATTRIBUTE_ERROR] ([DS_E_CONSTRAINT_VIOLATION]).

• In CDS, ds_compare () can only be used on leaf objects; if it is called with a non-leaf object, it returns a [DS_C_NAME_ERROR] ([DS_E_NO_SUCH_OBJECT]) error.

ds_initialize()

No modifications apply.

ds_list()

For CDS, enumeration can be performed only on directories (that is, entries that are not leaf objects); if enumeration of a leaf object is attempted, the call returns a [DS_C_NAME_ERROR] ([DS_E_NO_SUCH_OBJECT]) error.

ds_modify_entry()

Note the following in regard to the ds_modify_entry () operation:

• X.500 naming schema rules do not apply in CDS. Thus, the following attribute errors are never returned from CDS operations:

  • [DS_E_NO_SUCH_ATTRIBUTE_OR_VALUE]

  • [DS_E_ATTRIBUTE_OR_VALUE_EXISTS].

• Naming operations that would normally return these errors in GDS succeed when executed in CDS. In particular, attempting to add an attribute that already exists does not cause an error with a CDS object. Instead, the values of the attribute to be added are combined with the values of the existing attribute.

• GDS-structured attribute types are not supported by CDS. If a GDS-structured attribute type is used as an argument to a ds_modify_entry () call on a CDS object, the routine returns a [DS_C_ATTRIBUTE_ERROR] ([DS_E_CONSTRAINT_VIOLATION]) error.

• In CDS, ds_modify_entry () can be used only on leaf objects; otherwise, it returns a [DS_C_NAME_ERROR] ([DS_E_NO_SUCH_OBJECT]) error.

ds_modify_rdn()

CDS does not support the ds_modify_rdn () operation. Attempting this operation on a CDS object results in an error return of [DS_C_SERVICE_ERROR] ([DS_E_UNWILLING_TO_PERFORM]).

ds_read()

Note the following in regard to the ds_read() operation:

• Since CDS does not support the X.500 schema rules, some CDS objects may not contain GDS-mandatory attributes, such as object class, and so on. In CDS, an attempted read of a CDS alias object fails if the DS_A_ALIASED_OBJECT_NAME does not exist in the object. Instead, ds_read () returns a [DS_C_NAME_ERROR] ([DS_E_NO_SUCH_OBJECT]) error.

• In CDS, the naming attribute of an object is not stored in the object's attribute list. Thus, a ds_read () of a CDS object does not return this attribute in the object's attribute list.

ds_receive_result()

The DCE XDS interface does not support asynchronous operations. Thus, ds_abandon () and ds_receive_result () are redundant. A ds_receive_result () function call always returns with DS_status set to [DS_SUCCESS], and the completion_flag_return argument set to DS_NO_OUTSTANDING_OPERATION.

ds_remove_entry()

No modifications apply.

ds_search()

CDS does not support the ds_search () operation. An attempt to perform a ds_search () in CDS results in an error of [DS_C_SERVICE_ERROR] ([DS_E_UNWILLING_TO PERFORM]) being returned.

ds_shutdown()

No modifications apply.

ds_unbind()

No modifications apply.

ds_version()

No modifications apply.

XDS Function Call Results

All XDS functions, with the exception of ds_initialize(), return a value of type DS_status, which is the C function result of the call. If the function is successful, then DS_status returns with a value of [DS_SUCCESS]. If the function does not complete successfully, then DS_status takes either the error [DS_NO_WORKSPACE] or a private error object.

Most XDS functions also return data in an invoke_id_return argument, which identifies the particular invocation; and each of the interrogation operations returns data in a result_return argument. The invoke_id_return and result_return values are returned using pointers that are supplied as arguments of the C function.

These three types of function results are described in the XDS specification.

invoke_id_return Parameter

All interface functions that invoke a directory service operation return an invoke_id_return argument, which is an integer that identifies the particular invocation of an operation. This information is meaningful only if asynchronous operations are supported. Since DCE XDS does not support asynchronous operations, the invoke_id_return value is meaningless in DCE XDS.

The affected interface functions are:

• ds_add_entry ()

• ds_compare ()

• ds_list ()

• ds_modify_entry ()

• ds_modify_rdn ()

• ds_read ()

• ds_remove_entry ()

• ds_search ().

DCE application programmers must still supply this argument, as described in the XDS reference pages (see the XDS specification), but the value returned therein should be ignored.

Synchronous Operations

In synchronous mode, all functions wait until the operation is complete before returning. The thread of control is blocked within the interface during the time which elapses between the calling of a function and its return, and the function result can be used immediately after the function returns.

Implementations may define a limit on the number of asynchronous operations that can be outstanding at any one time in any one session. The limit is defined by the implementation-defined constant DS_MAX_OUTSTANDING_OPERATIONS. In DCE XDS this constant always has the value 0 (zero), because asynchronous operations are not supported.

All errors occurring during a synchronous request are reported when the function returns.

The DS_FILE_DESCRIPTOR OM attribute of DS_C_SESSION is not used by the DCE XDS API. It is always set to DS_NO_VALID_FILE_DESCRIPTOR.

Security and XDS

The XDS specification does not define a security interface in order to avoid possibly constraining the security features of existing directory implementations.

DCE GDS proves an extension to the XDS API for security support. This is achieved at the XDS API level through a new DSX_C_GDS_SESSION session object which contains information on the security mechanism that should be used. Simple authentication through the use of name and password, and external authentication based on DCE security are supported. (See Global Directory Service Package for additional information.)

Automatic Connection Management

A directory service implementation can provide automatic management of the association or connection between the user and the directory service, making and releasing connections at its discretion.

DCE XDS does not support automatic connection management. A DSA connection is established when ds_bind () is successfully called, and released when ds_unbind () is successfully called.

Global Directory Service Package

The object identifier associated with the GDSP is:

 

{iso(1) identified-organisation(3) icd-ecma(0012) member-company(2)\
 siemens-units(1107) sni(1) directory(3) xds-api(100) gdsp(0)}

It has the following encoding:

 

\x2B\xC\x2\x88\x53\x1\x3\x64\x0

The GDSP object identifier is represented by the constant DSX_GDS_PKG. This constant, together with the other C constants associated with the package, are contained in the <xdsgds.h> header file (see XDS/XOM Header Files ).

In the following sections, the GDSP's attribute types are introduced first; descriptions of its object classes follow. Finally, the OM class hierarchy and OM class definitions required to support the new attribute types are described.

GDSP Attribute Types

Object Identifiers for GDSP Attribute Types shows the names of the GDSP attribute types, together with the BER encoding of the object identifiers associated with each of them. The third column of the table shows the hexadecimal values of the octets of the BER encoding of the object identifier in hexadecimal representation. All these object identifiers are derived from the root:

 

{iso(1) identified-organisation(3) icd-ecma(0012) member-company(2)
 siemens-units(1107) sni(1) directory(3) attribute-type(4)}

		Object Identifier BER
Package	Attribute Type	(Hexadecimal Value)
GDSP	DSX_A_ACL	\x2B\x0C\x02\x88\x53\x01\x03\x04\x01
GDSP	DSX_A_AT	\x2B\x0C\x02\x88\x53\x01\x03\x04\x06
GDSP	DSX_A_CDS_CELL	\x2B\x0C\x02\x88\x53\x01\x03\x04\x0D
GDSP	DSX_A_CDS_REPLICA	\x2B\x0C\x02\x88\x53\x01\x03\x04\x0E
GDSP	DSX_A_CLIENT	\x2B\x0C\x02\x88\x53\x01\x03\x04\x0A
GDSP	DSX_A_DEFAULT_DSA	\x2B\x0C\x02\x88\x53\x01\x03\x04\x08
GDSP	DSX_A_DNLIST	\x2B\x0C\x02\x88\x53\x01\x03\x04\x0B
GDSP	DSX_A_LOCAL_DSA	\x2B\x0C\x02\x88\x53\x01\x03\x04\x09
GDSP	DSX_A_MASTER_KNOWLEDGE	\x2B\x0C\x02\x88\x53\x01\x03\x04\x00
GDSP	DSX_A_OCT	\x2B\x0C\x02\x88\x53\x01\x03\x04\x05
GDSP	DSX_A_SHADOWED_BY	\x2B\x0C\x02\x88\x53\x01\x03\x04\x03
GDSP	DSX_A_SHADOWING_JOB	\x2B\x0C\x02\x88\x53\x01\x03\x04\x0C
GDSP	DSX_A_SRT	\x2B\x0C\x02\x88\x53\x01\x03\x04\x04
GDSP	DSX_A_TIME_STAMP	\x2B\x0C\x02\x88\x53\x01\x03\x04\x02

Values for GDSP Attribute Types shows the names of the attribute types, together with the OM value syntax used in the interface to represent each attribute's values. The table also indicates: the range of lengths in octets permitted for the string types; whether the attribute can be multi-valued; and which matching rules are provided for the syntax.

		Value	Multi-	Matching
Attribute Type	OM Value Syntax	Length	Valued	Rules
DSX_A_ACL	Object (DSX_C_GDS_ACL)	-	no	E
DSX_A_AT	String (OM_S_PRINTABLE_STRING)	1-101	yes	E,S
DSX_A_CDS_CELL	String (OM_S_OCTET_STRING)	1-284	no	E
DSX_A_CDS_REPLICA	String (OM_S_OCTET_STRING)	1-905	yes	E
DSX_A_CLIENT	Only a cache attribute	-	-	-
DSX_A_DEFAULT_DSA	Only a cache attribute	-	-	-
DSX_A_DNLIST	Object (DS_C_DS_DN)	-	yes	E,S
DSX_A_LOCAL_DSA	Only a cache attribute	-	-	-
DSX_A_MASTER_KNOWLEDGE	Object (DS_C_DS_DN)	-	no	E,S
DSX_A_OCT	String (OM_S_PRINTABLE_STRING)	1-397	yes	E,S
DSX_A_SHADOWED_BY	Not used yet	-	-	-
DSX_A_SHADOWING_JOB	Not used yet	-	-	-
DSX_A_SRT	String (OM_S_PRINTABLE_STRING)	1-29	yes	E,S
DSX_A_TIME_STAMP	String (OM_S_UTC_TIME_STRING)	11-17	no	E,O

In the Matching Rules column, the abbreviations have the following meanings:

E

The matching rule determines whether two values are equal.

S

The matching rule identifies one value as a substring of the other.

O

The matching rule determines the ordering of two values.

Descriptions of GDSP Attribute Types

DSX_A_ACL

The contents of this attribute describe the access rights for one or more directory service users.

DSX_A_AT

The contents of this attribute describe the attribute types permitted in GDS.

DSX_A_CDS_CELL and DSX_A_CDS_REPLICA

The contents of these attributes consist of the information necessary for contacting a remote DCE cell. These two attributes always exist together in the same object. See Cell Registration in Global Name Space for its representation.

DSX_A_CLIENT

This attribute applies only to the cache. It identifies the entry which holds the DUA's Presentation Address. Its OM syntax is OM_S_PRINTABLE_STRING and its value is CLIENT.

DSX_A_DEFAULT_DSA

This attribute applies only to the cache. It identifies an entry which holds the Distinguished Name (DN) of the DUA's default DSA. Its OM syntax is OM_S_PRINTABLE_STRING and its value is DEFAULT-DSA.

DSX_A_DNLIST

The contents of this attribute are used internally by the GDS DSA.

DSX_A_LOCAL_DSA

This attribute applies only to the cache. It identifies an entry which holds the Distinguished Name (DN) of the DUA's local DSA. Its OM syntax is OM_S_PRINTABLE_STRING and its value is LOCAL-DSA.

DSX_A_MASTER_KNOWLEDGE

The contents of this attribute consist of the Distinguished Name (DN) of the DSA that holds the master copy of this entry.

DSX_A_OCT

The contents of this attribute consist of a description of the object classes supported by the DSA.

DSX_A_SHADOWED_BY and DSX_A_SHADOWING_JOB

These two GDSP attributes are intended for future use.

DSX_A_SRT

The contents of this attribute consist of a description of the structure of the DNs (Distinguished Names) permitted in GDS.

DSX_A_TIME_STAMP

This attribute is part of the DSX_O_SCHEMA object. It contains the creation time of the DSX_O_SCHEMA object.

GDSP Object Classes

The third column of the table shows the hexadecimal values of the octets of the BER encoding of the object identifier in hexadecimal representation. This object identifier is derived from the root:

 

{iso(1) identified-organisation(3) icd-ecma(0012) member-company(2)
 siemens-units(1107) sni(1) directory(3) object-class(6)}

		Object Identifier BER
Package	Attribute Type	(Hexadecimal Value)
GDSP	DSX_O_SCHEMA	\x2B\x0C\x02\x88\x53\x01\x03\x06\x00

GDS OM Class Hierarchy

OM_C_OBJECT (defined in the OM package)
	DS_C_SESSION (defined in the Directory Service Package)
		DSX_C_GDS_SESSION
	DS_C_CONTEXT (defined in the Directory Service Package)
		DSX_C_GDS_CONTEXT
	DSX_C_GDS_ACL
	DSX_C_GDS_ACL_ITEM

None of the OM classes in the preceding list are encodable using om_encode () and om_decode ().

DSX_C_GDS_ACL

An instance of OM class DSX_C_GDS_ACL describes up to five categories of rights for one or more directory users.

An instance of this OM class has the OM attributes of its superclass, OM_C_OBJECT, in addition to the OM attributes listed in OM Attributes of DSX_C_GDS_ACL .

		Value	Value	Value
OM Attribute	Value Syntax	Length	Number	Initially
DSX_MODIFY_PUBLIC	Object (DSX_C_GDS_ACL_ITEM)	-	0-4	-
DSX_READ_STANDARD	Object (DSX_C_GDS_ACL_ITEM)	-	0-4	-
DSX_MODIFY_STANDARD	Object (DSX_C_GDS_ACL_ITEM)	-	0-4	-
DSX_READ_SENSITIVE	Object (DSX_C_GDS_ACL_ITEM)	-	0-4	-
DSX_MODIFY_SENSITIVE	Object (DSX_C_GDS_ACL_ITEM)	-	0-4	-

The OM attributes of DSX_C_GDS_ACL are as follows:

DSX_MODIFY_PUBLIC

This attribute specifies the user, or subtree of users, that can modify attributes classified as public attributes.

DSX_READ_STANDARD

This attribute specifies the user, or subtree of users, that can read attributes classified as standard attributes.

DSX_MODIFY_STANDARD

This attribute specifies the user, or subtree of users, that can modify attributes classified as standard attributes.

DSX_READ_SENSITIVE

This attribute specifies the user, or subtree of users, that can read attributes classified as sensitive attributes.

DSX_MODIFY_SENSITIVE

This attribute specifies the user, or subtree of users, that can modify attributes classified as sensitive attributes.

DSX_C_GDS_ACL_ITEM

An instance of OM class DSX_C_GDS_ACL_ITEM is a component of an instance of OM class DSX_C_GDS_ACL. It specifies the user, or subtree of users, to whom an access right applies.

An instance of this OM class has the OM attributes of its superclass, OM_C_OBJECT, in addition to the OM attributes listed in OM Attributes of DSX_C_GDS_ACL_ITEM .

		Value	Value	Value
OM Attribute	Value Syntax	Length	Number	Initially
DSX_INTERPRETATION	Enum (DSX_Interpretation)	-	1	-
DSX_USER	Object(DS_C_DS_DN)	-	1	-

The OM attributes of a DSX_C_GDS_ACL_ITEM are as follows:

DSX_INTERPRETATION

This attribute specifies the scope of the access right. It can have one of the following values:

• DSX_SINGLE_OBJECT indicates that the access right is granted to the user specified in the DSX_USER OM attribute.

• DSX_ROOT_OF_SUBTREE indicates that the access right is granted to all users in the subtree below the name specified in the DSX_USER OM attribute.

DSX_USER

This attribute contains the Distinguished Name of the user, or subtree of users, to whom an access right applies.

DSX_C_GDS_CONTEXT

An instance of this OM class has the OM attributes of its superclasses, OM_C_OBJECT and DS_C_CONTEXT, in addition to the OM attributes listed in OM Attributes of DSX_C_GDS_CONTEXT .

		Value	Value	Value
OM Attribute	Value Syntax	Length	Number	Initially
Service Controls
DSX_DUAFIRST	OM_S_BOOLEAN	-	1	OM_FALSE
DSX_DONT_STORE	OM_S_BOOLEAN	-	1	OM_TRUE
DSX_NORMAL_CLASS	OM_S_BOOLEAN	-	1	OM_FALSE
DSX_PRIV_CLASS	OM_S_BOOLEAN	-	1	OM_FALSE
DSX_RESIDENT_CLASS	OM_S_BOOLEAN	-	1	OM_FALSE
DSX_USEDSA	OM_S_BOOLEAN	-	1	OM_TRUE
DSX_DUA_CACHE	OM_S_BOOLEAN	-	1	OM_FALSE
DSX_PREFER_ADM_FUNCS	OM_S_BOOLEAN	-	1	OM_FALSE
DSX_SIGN_MECHANISM	Enum(DSX_Sign_Mechanism)	-	0-1	-
DSX_PROT_REQUEST	Enum(DSX_Prot_Request)	-	0-1	-

The OM attributes of the DSX_C_GDS_CONTEXT OM class are as follows:

DSX_DUAFIRST

The value of this attribute defines whether the DUA cache or the DSA needs to be read first for query operations. The default value is OM_FALSE; that is, search the DSA first, if not found then search the DUA cache.

DSX_DONT_STORE

The value of this attribute specifies whether the information read from the DSAs by the query functions also needs to be stored in the DUA cache. When this service control is set to OM_TRUE (the default value), nothing is stored in the DUA cache.

When the value of this attribute is set to OM_FALSE, the information read is stored in the DUA cache, and the objects returned by ds_list () and ds_compare () are stored in the cache without their associated attribute information. The objects returned by ds_read () and ds_search () are stored in the cache with all their attributes that are capable of being stored in the cache; these are public attributes, except for the ACL attribute. This information is stored in the cache only when a list of requested attributes is supplied. If all attributes are requested, then nothing is stored in the cache.

The DUA cache categorises the information stored into three different memory classes. The user specifies the category with the following service control attributes:

DSX_NORMAL_CLASS

If this attribute is set to OM_TRUE, the entry in the DUA cache is assigned to the class of normal objects. When the number of entries in this class exceeds a maximum value, the entry that has not been addressed for the longest period of time is removed from the DUA cache.

DSX_PRIV_CLASS

If this attribute is set to OM_TRUE, the entry in the DUA cache is assigned to the class of privileged objects. Such entries can be removed from the class in the same way as normal objects. By using this memory sparingly, the user can protect entries from deletion.

DSX_RESIDENT_CLASS

If this attribute is set to OM_TRUE, the entry in the DUA cache is assigned to the class of resident objects. An entry in this memory class is never removed automatically; it can only be removed by a call to ds_remove_entry (). The number of entries is limited; if this limit is exceeded, ds_add_entry () reports an error.

Note:

Only one of the above service control attributes can be OM_TRUE at one time. Also, the ds_add_entry () function also evaluates these service control bits if it is used on the DUA cache.

DSX_DUA_CACHE and DSX_USEDSA

These attributes define whether the entries in the DUA cache or in the DSA, or both, need to be used when providing the service specified in the operation. Depending on the values of these attributes, the following situations can arise:

• If DSX_DUA_CACHE and DSX_USEDSA are both OM_TRUE, the ds_add_entry () and ds_remove_entry () functions report an error.

  The query functions evaluate the service controls DS_DONT_USE_COPY and DSX_DUAFIRST. If DS_DONT_USE_COPY is OM_FALSE, then the value of DSX_DUAFIRST determines whether the DUA cache or the DSA is read first. If DS_DONT_USE_COPY is OM_TRUE, information from the DSA only is read.

• If DSX_DUA_CACHE is OM_TRUE and DSX_USEDSA is OM_FALSE, the ds_add_entry () and ds_remove_entry () functions, as well as the query functions, go only to the DUA cache.

• If DSX_DUA_CACHE is OM_FALSE and DSX_USEDSA is OM_TRUE, the ds_add_entry () and ds_remove_entry () functions, as well as the query functions, go only to the DSA.

• If DSX_DUA_CACHE and DSX_USEDSA are both OM_FALSE, the ds_add_entry () and ds_remove_entry () functions, and the query functions, report an error.

All other functions always operate on the currently connected DSA.

DSX_PREFER_ADM_FUNCS

The value of this attribute specifies whether the three following optional attributes are returned in an operation:

• DSX_A_MASTER_KNOWLEDGE, which contains the Distinguished Name of the DSA that holds the master copy of an entry

• DSX_A_ACL, which is used for GDS access control

• DS_A_USER_PASSWORD is an attribute of the DS_O_DSA object class, which is used by the GDS shadowing mechanism.

The DSX_A_MASTER_KNOWLEDGE and DSX_A_ACL attributes are present in every GDS entry.

When an application requests that all attributes be returned in an operation, it can prevent any of the above three optional attributes from being returned by setting the value of DSX_PREFER_ADM_FUNCS to OM_FALSE.

If GDS applications (for example, GDS administration) require these attributes, they are obtained by setting this service control to OM_TRUE.

DSX_SIGN_MECHANISM

This attribute is reserved for future use.

DSX_PROT_REQUEST

This attribute is reserved for future use.

Applications can assume that an object of OM class DSX_C_GDS_CONTEXT, created with default values for all its OM attributes, works with all interface functions. Note that an application can supply the constant DS_DEFAULT_CONTEXT as the context argument to GDS functions instead of creating a DSX_C_GDS_CONTEXT OM object with all default values.

The default form of DSX_C_GDS_CONTEXT is described in Default DSX_C_GDS_CONTEXT .

DSX_C_GDS_SESSION

• specify an authentication mechanism for an authenticated bind

• specify the GDS directory identifier.

DSX_C_GDS_SESSION can be passed as an argument to ds_bind ().

An instance of this OM class has the OM attributes of its superclasses, OM_C_OBJECT and DS_C_SESSION, in addition to the OM attributes listed in OM Attributes of DSX_C_GDS_SESSION .

		Value	Value	Value
OM Attribute	Value Syntax	Length	Number	Initially
DSX_PASSWORD	String(OM_S_OCTET_STRING)	-	0 or 1	-
DSX_DIR_ID	OM_S_INTEGER	-	1	1
DSX_AUTH_MECHANISM	Enum(DSX_Auth_Mechanism)	-	0-1	-
DSX_AUTH_INFO	String(OM_S_OCTET_STRING)	-	0-1	-

The OM attributes of DSX_C_GDS_SESSION are as follows:

DSX_PASSWORD

The contents of this attribute consist of the password for the user credentials.

DSX_DIR_ID

The contents of this attribute are an identifier for distinguishing between several configurations of the directory service within a GDS installation. The valid range for this value is from 1 to 20.

DSX_AUTH_MECHANISM

This attribute, if present, identifies the authentication mechanism that the application requests. If it is absent or has the value DSX_NONE_AT_ALL, then a ds_bind() without credentials (anonymous bind) is requested. This attribute can take the following values:

• DSX_NONE_AT_ALL requests that no authentication mechanism be used.

• DSX_DEFAULT requests the default authentication mechanism, DCE authentication (DSX_DCE_AUTH). The value for DSX_DEFAULT can be modified through the XDS_DEF_AUTH_MECH environment variable. This variable is checked by XDS following a ds_initialize() function call.

• DSX_SIMPLE requests simple authentication by using the DS_REQUESTOR and DSX_PASSWORD attributes of the DSX_C_GDS_SESSION object.

• DSX_SIMPLE_PROT1 is reserved for future use.

• DSX_SIMPLE_PROT2 is reserved for future use.

• DSX_DCE_AUTH requests the use of the DCE authentication mechanism.

• DSX_STRONG is reserved for future use.

If an authentication mechanism is selected that is not currently supported, ds_bind() returns a [DS_E_NOT_SUPPORTED] error. If the selected authentication mechanism requires the user's credentials that cannot be assembled, then a [DS_E_NO_INFO] error is returned.

DSX_AUTH_INFO

This attribute is reserved for future use.

Applications can assume that an object of OM class DSX_C_GDS_SESSION, created with default values for all its OM attributes, works with all interface functions. Note that an application can supply the constant DS_DEFAULT_SESSION as the session argument to ds_bind () to create a default session (instead of creating a DSX_C_GDS_SESSION OM object with all the default values), having already negotiated the GDS package.

Default DSX_C_GDS_SESSION describes DS_DEFAULT_SESSION.

Please note that the html version of this specification may contain formatting aberrations. The definitive version is available as an electronic publication on CD-ROM from The Open Group.