The XDS interface defines an API that application programs can use to access the functionality of the underlying directory service. The DCE XDS API conforms to the X/Open CAE Specification, API to directory services (XDS) (November 1991).
The DCE XDS implementation supports the following features:
· A synchronous interface. Asynchronous functionality can be achieved by using threads as described in Using Threads With The XDS/XOM API.
· All synchronous interface functions are supported. The two asynchronous-specific functions are handled as follows:
- ds_abandon( )
This call does not issue a directory service abandon operation. It returns with a DS_C_ABANDON_FAILED (DS_E_TOO_LATE) error. For details on abandoning operations see Section 10.10.3.
- ds_receive_result( )
If there are any outstanding operations (when multiple threads issue XDS calls in parallel), this function returns DS_SUCCESS with the completion_flag_return parameter set to DS_OUTSTANDING_OPERATIONS. If no XDS calls are outstanding, this function returns DS_SUCCESS with the completion_flag_return parameter set to DS_NO_OUTSTANDING_OPERATION.
· Automatic connection management is not provided. The ds_bind( ) and ds_unbind( ) functions always try, respectively, to set up and release directory service connections immediately.
· The DS_FILE_DESCRIPTOR attribute of the DS_C_SESSION object is not used.
· The default values for OM attributes in the DS_C_CONTEXT and DS_C_SESSION objects are described in XDS Class Definitions.
· Support for local strings. XDS supports the mapping from/to local string formats. The programmer can request this feature when using the following XDS/XOM functions:
- dsX_extract_attr_values( )
- omX_extract( )
- omX_object_to_string( )
- omX_string_to_object( )
- om_get( )
- om_read( )
The programmer controls this mapping through the local_strings boolean parameter. To request conversion, set this parameter to OM_TRUE. The mappings currently supported are as follows:
- T.61 String to/from ISO 8859-1 (that is, LATIN-1)
For details on these mappings refer to the Appendixes D and F of the OSF DCE GDS Administration Guide and Reference.
On input, when requesting conversion of LATIN-1 characters to T.61 format, you should only use the T.61 subset; otherwise an error is returned.
DCE XDS supports five packages, of which one is mandatory and four are optional. Use of the optional packages is negotiated by using ds_version( ). The packages are as follows:
· The directory service package (as defined in XDS Class Definitions), which also includes the errors. This package is mandatory.
· The basic directory contents package (as defined in Basic Directory Contents Package). This package is optional.
· The strong authentication package (as defined in Strong Authentication Package). This package is optional.
· The message handling system directory user package (as defined in MHS Directory User Package). This package is optional.
· The GDS package (as defined in GDS Package). This package is optional.
None of the OM classes defined in these five packages are encodable. Thus, 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.