The distinguished name for Peter Piper is an entry in the directory that the application is designed to access. The selection parameter of the ds_read( ) function call tailors its results to obtain just part of the required entry. Information on all attributes, no attributes, or a specific group of attributes can be chosen. Attribute types are always returned, but the attribute values need not be.
The value of the parameter is a public object (descriptor list) that is an instance of OM class DS_C_ENTRY_INFO_SELECTION, as shown in the following code fragment from example.c:
/*
* Public Object ("Descriptor List") for
* Entry-Information-Selection
* parameter to ds_read().
*/
OM_descriptor selection[] = {
OM_OID_DESC(OM_CLASS, DS_C_ENTRY_INFO_SELECTION),
{ DS_ALL_ATTRIBUTES, OM_S_BOOLEAN, { OM_FALSE, NULL } },
OM_OID_DESC(DS_ATTRIBUTES_SELECTED, DS_A_PHONE_NBR),
{ DS_INFO_TYPE,OM_S_ENUMERATION,
{ DS_TYPES_AND_VALUES,NULL } },
OM_NULL_DESCRIPTOR
};
DS_C_ENTRY_INFO_SELECTION is a subclass of OM_C_OBJECT. (This information is supplied in the description of this class in XDS Class Definitions.) As such, DS_C_ENTRY_INFO_SELECTION inherits the OM attributes of OM_C_OBJECT. The only OM attribute of OM_C_OBJECT is OM_CLASS. OM_CLASS identifies an object's class, which in this case is DS_C_ENTRY_INFO_SELECTION. DS_C_ENTRY_INFO_SELECTION identifies information to be extracted from a directory entry and has the following OM attributes:
· OM_C_CLASS (inherited from OM_C_OBJECT)
· DS_ALL_ATTRIBUTES
· DS_ATTRIBUTES_SELECTED
· DS_INFO_TYPE
As part of a ds_read( ) or ds_search( ) function call, DS_ALL_ATTRIBUTES specifies to the directory service which attributes of a directory entry are relevant to the application program. It can take the values OM_TRUE or OM_FALSE. These values are defined to be of syntax OM_S_BOOLEAN. The value OM_TRUE indicates that information is requested on all attributes in the directory entry. The value OM_FALSE, used in the preceding sample code fragment, indicates that information is only requested on those attributes that are listed in the OM attribute DS_ATTRIBUTES_SELECTED.
DS_ATTRIBUTES_SELECTED lists the types of attributes in the entry from which information is to be extracted. The syntax of the value is specified as OM_S_OBJECT_IDENTIFIER_STRING.
OM_S_OBJECT_IDENTIFIER_STRING contains an octet string of BER-encoded integers, which are decimal representations of object identifiers of the types of attributes in the attribute list. In the preceding code fragment, the string value is the attribute name DS_A_PHONE_NBR because the purpose of the read call is to read a list of telephone numbers from the directory.
DS_INFO_TYPE identifies what information is to be extracted from each attribute identified. The syntax of the value is specified as Enum(DS_Information_Type). DS_INFO_TYPE is an enumerated type that has two possible values: DS_TYPES_ONLY and DS_TYPES_AND_VALUES. DS_TYPES_ONLY indicates that only the attribute types of the selected attributes in the entry are returned by the directory service operation. DS_TYPES_AND_VALUES indicates that both the attribute types and the attribute values of the selected attributes in the entry are returned. The code fragment from example.c shown previously defines the value of DS_INFO_TYPE as DS_TYPES_AND_VALUES because the program wants to get the actual telephone numbers.