The ds_version( ) call negotiates features of the directory interface. These features are collected into packages that define the scope of the service. Packages define such things as object identifiers for directory and OM classes and OM attributes, enumerated types, structures, and OM object constants.
XDS API defines the following packages in separate header files as part of the XDS API software product:
· Directory service package
The directory service package contains the OM classes and OM attributes used to interact with the directory service. This package is contained in the xds.h header file.
· Basic directory contents package
The basic directory contents package contains OM classes and OM attributes that represent values of selected attributes and selected objects defined in the X.500 standard. This package is contained in the xdsbdcp.h header file.
· Strong authentication package
The strong authentication package contains OM classes and OM attributes that represent values of security attributes and objects defined in the X.500 standard. This package is contained in the xdssap.h header file.
· GDS package
The GDS package contains the OM classes and OM attributes that are required for GDS. This package is contained in the xdsgds.h header file.
· MHS directory user package
The MHS (message handling system) directory user package contains the OM classes and OM attributes that are required for electronic mail support. This package is contained in the xdsmdup.h header file.
The application program, which is the client, uses ds_version( ) to negotiate the scope of the services the directory service will provide to the client. A ds_version( ) function call includes a list of features (or packages) that the client wants to include as part of the interface. The features are object identifiers that represent packages supported by the DCE XDS API. The service returns a list of Boolean values to indicate whether or not the package was successfully negotiated.
These features are assigned to the workspace that an application program initialized (as described in The ds_initialize( ) Function Call). In addition, an application program must include the header files for the appropriate packages as part of the source code.
It is not necessary to negotiate the directory service package. It is a mandatory requirement for XDS API, and as such it is included by default. The other packages listed previously are optional and require negotiation by using ds_version( ).
The following code fragment from acl.h shows how an application builds up an array of object identifiers for the optional packages to be negotiated: the basic directory contents package and the GDS package.
static DS_feature features[] = {
{ OM_STRING(OMP_O_DS_BASIC_DIR_CONTENTS_PKG), OM_TRUE },
{ OM_STRING(OMP_O_DSX_GDS_PKG), OM_TRUE },
{0}
};
The OM_STRING macro is provided for creating a data value of data type OM_string for octets strings and characters. The array of object identifiers is stored in features, the input parameter to ds_version( ), as shown in the following code fragment from acl.c:
/* Negotiate the use of the BDCP and GDS packages. */
if (ds_version(features,workspace) != DS_SUCCESS)
printf("ds_version() error\n");