Recall that RDNs are built from AVAs, and a distinguished name is built from a series of RDNs. In a typical application program, several AVAs are defined in descriptor lists as public objects. These public objects are incorporated into descriptor lists that represent corresponding RDNs. Finally, the RDNs are incorporated into one descriptor list that represents the distinguished name of an object in the directory, as shown in the following figure. This descriptor list is included as one of the input parameters to a directory service function.
The Distinguished Name of ''Peter Piper'' in the DIT
The following code fragment from example.c shows how a distinguished name is built as a public object. The public object is the name parameter for a subsequent read operation call to the directory. The representation of a distinguished name in the DIT is shown in the figure above.
The first section of code defines the four AVAs. These AVAs make the assertion to the directory service that the attribute values in the distinguished name of Peter Piper are valid and can therefore be read from the directory. The country name is US, the organization name is Acme Pepper Co, the organizational unit name is Research, and the common name is Peter Piper.
/*
* Public Object ("Descriptor List") for Name parameter to
* ds_read().
* Build the Distinguished-Name of Peter Piper
*/
static OM_descriptor country[] = {
OM_OID_DESC(OM_CLASS, DS_C_AVA),
OM_OID_DESC(DS_ATTRIBUTE_TYPE, DS_A_COUNTRY_NAME),
{ DS_ATTRIBUTE_VALUES,OM_S_PRINTABLE_STRING,OM_STRING("US") },
OM_NULL_DESCRIPTOR
};
static OM_descriptor organization[] = {
OM_OID_DESC(OM_CLASS, DS_C_AVA),
OM_OID_DESC(DS_ATTRIBUTE_TYPE, DS_A_ORG_NAME),
{ DS_ATTRIBUTE_VALUES,OM_S_TELETEX_STRING,
OM_STRING("Acme Pepper Co") },
OM_NULL_DESCRIPTOR
};
static OM_descriptor organizational_unit[] = {
OM_OID_DESC(OM_CLASS, DS_C_AVA),
OM_OID_DESC(DS_ATTRIBUTE_TYPE, DS_A_ORG_UNIT_NAME),
{ DS_ATTRIBUTE_VALUES,OM_S_TELETEX_STRING, OM_STRING("Research") },
OM_NULL_DESCRIPTOR
};
static OM_descriptor common_name[] = {
OM_OID_DESC(OM_CLASS, DS_C_AVA),
OM_OID_DESC(DS_ATTRIBUTE_TYPE, DS_A_COMMON_NAME),
{ DS_ATTRIBUTE_VALUES,OM_S_TELETEX_STRING, OM_STRING("Peter Piper") },
OM_NULL_DESCRIPTOR
};
The next section of code is nested one level above the previously defined AVAs. Each RDN has a descriptor with OM attribute type DS_AVAS (indicating that it is OM attribute type AVA), a syntax of OM_S_OBJECT, and a value of the name of the descriptor array defined in the previous section of code for an AVA. The rdn1 descriptor contains the descriptor list for the AVA country, the rdn2 descriptor contains the descriptor list for the AVA organization, and so on.
OM_S_OBJECT is a syntax that indicates that its value is a subobject. For example, the value for DS_AVAS is the previously defined object country. In this manner, a hierarchy of linked objects and subobjects can be constructed.
static OM_descriptor rdn1[] = {
OM_OID_DESC(OM_CLASS, DS_C_DS_RDN),
{ DS_AVAS, OM_S_OBJECT, { 0, country } },
OM_NULL_DESCRIPTOR
};
static OM_descriptor rdn2[] = {
OM_OID_DESC(OM_CLASS, DS_C_DS_RDN),
{ DS_AVAS, OM_S_OBJECT, { 0, organization } },
OM_NULL_DESCRIPTOR
};
static OM_descriptor rdn3[] = {
OM_OID_DESC(OM_CLASS, DS_C_DS_RDN),
{ DS_AVAS, OM_S_OBJECT, { 0, organizational_unit } },
OM_NULL_DESCRIPTOR
};
static OM_descriptor rdn4[] = {
OM_OID_DESC(OM_CLASS, DS_C_DS_RDN),
{ DS_AVAS, OM_S_OBJECT, { 0, common_name } },
OM_NULL_DESCRIPTOR
};
The next section of code contains the RDNs that make up the distinguished name, which is stored in the array of descriptors called name. It is made up of the OM class DS_C_DS_DN (representing a distinguished name) and four RDNs of OM attribute type DS_RDNS and syntax OM_S_OBJECT.
OM_descriptor name[] = {
OM_OID_DESC(OM_CLASS, DS_C_DS_DN),
{ DS_RDNS, OM_S_OBJECT, { 0, rdn1 } },
{ DS_RDNS, OM_S_OBJECT, { 0, rdn2 } },
{ DS_RDNS, OM_S_OBJECT, { 0, rdn3 } },
{ DS_RDNS, OM_S_OBJECT, { 0, rdn4 } },
OM_NULL_DESCRIPTOR
};
In summary, the distinguished name for Peter Piper is stored in the array of descriptors called name, which is composed of three nested levels of arrays of descriptors (see the following figure). The definitions for the AVAs are at the innermost level, the definitions for RDNs are at the next level up, and the distinguished name is at the top level.
Building a Distinguished Name
The following figure shows a more general view of the structure distinguished name.
A Simplified View of the Structure of a Distinguished Name
The name descriptor defines a public object that is provided as the name parameter required by the XDS API read function call, ds_read( ), as follows (XDS API function calls are described in detail in XDS Programming):
CHECK_DS_CALL(ds_read(session, DS_DEFAULT_CONTEXT,
name, selection, &result, &invoke_id));
The result of the ds_read( ) function call is in a private implementation-specific format; it is stored in a workspace and pointed to by result. The application program must use XOM function calls (described in OM Function Calls) to interpret the data and extract the information. This extraction process involves uncovering the nested data structures in a series of XOM function calls.