Previous section.
DCE 1.1: Directory Services
Copyright © 1997 The Open Group
XDS/XOM Convenience Functions
This chapter describes functions which are available to XDS/XOM programmers
to help simplify and speed up the development of XDS applications. The
convenience functions target two main areas:
-
Filling, comparing and extracting objects
-
Converting objects to and from local string formats.
String Handling
The convenience functions provide the ability to specify OM objects
in string format by means of abbreviations.
X.500 attribute types can be specified either as abbreviations or object
identifier strings. The mapping of the attribute abbreviations and object
identifier strings to BER encoded object identifiers and the associated
attribute syntaxes is determined by the XOM object information module.
The convenience functions are able to handle strings with special
syntax. The strings can be broadly classified into the following:
-
strings representing GDS attribute information
-
strings representing structured GDS attribute information
-
strings representing a structured GDS attribute value
-
strings representing a Distinguished Name (DN)
-
strings representing expressions.
Convenience Functions
Convenience Functions
lists the convenience functions interfaces.
| Function
| Description
|
|---|
| dsX_extract_attr_values ()
| Extracts attribute values from an object.
|
| omX_extract ()
| Creates an exact, independent copy of an existing subobject.
|
| omX_fill ()
| Initializes an OM_descriptor structure.
|
| omX_fill_oid ()
| Initializes an OM_descriptor with an object identifier value.
|
| omX_object_to_string ()
| Converts an OM_object to string format.
|
| omX_string_to_object ()
| Converts a string to a new private object.
|
Table: Convenience Functions
The purpose and range of capabilities of the convenience functions
are described in the following sections.
dsX_extract_attr_values()
Extracts the attribute values associated with the specified attribute type
from an OM object. The OM object must be of type DS_C_ATTRIBUTE_LIST
or DS_C_ENTRY_INFO. This function returns an object containing an
array of OM descriptors.
omX_extract()
Creates a new public object, that is an exact but independent copy of an
existing subobject in a private object. It is similiar to the
om_get() function but includes an additional parameter,
navigation_path, which contains directions to the required object
to be extracted. The client can request certain exclusions, each of
which reduces the copy to a part of the original.
omX_fill()
Initializes an OM_descriptor structure with user-supplied values
for the structure's type, syntax, and value.
omX_fill_oid()
Initializes an OM_descriptor structure with user-supplied values for
the structures type and value. The syntax of the OM_descriptor
is always set to OM_S_OBJECT_IDENTIFIER_STRING.
omX_object_to_string()
Converts an object into a string format. The object can either be a
client-generated or service-generated public or private object.
omX_string_to_object()
Creates a new private object, which is built from the string
and class input parameters.
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.