The object identifier associated with the GDSP is
{iso(1) identified-organisation(3) icd-ecma(0012) member-company(2) siemens-units(1107) sni(1) directory(3) xdsapi(100) gdsp(0)}with the following encoding:
\x2B\xC\x2\x88\x53\x1\x3\x64\x0
The identifier is represented by the constant DSX_GDS_PKG. The C constants associated with this package are contained in the xdsgds.h header file.
The concepts and notation used are first mentioned in Section 11.1. They are also fully explained in Chapters 17 through 19. The attribute types are introduced first, followed by the object classes. Next, the OM class hierarchy and OM class definitions required to support the new attribute types are described.
This section contains two tables that are used to indicate the object identifiers for GDSP attribute types (see Table 15-1), and the values for GDSP attribute types (see Table 15-2), respectively. Following these two tables is a brief description of each attribute. (See Section 12.1 for information on general matching rules.)
Table 15-1 shows the names of the GDSP attribute types, together with the BER encoding of the object identifiers associated with each of them.
Note: The third column of Table 15-1 contains the contents octets of the BER encoding of the object identifier in hexadecimal. All these object identifiers stem from the root {iso(1) identified-organization(3) idc-ecma(0012) member-company(2) siemens-units(1107) sni(1) directory(3) attribute-type(4)}.
| Package | Attribute Type | Object Identifier BER Hexdecimal |
|---|---|---|
| GDSP | DSX_A_ACL | \x2B\x0C\x02\x88\x53\x01\x03\x04\x01 |
| GDSP | DSX_A_AT | \x2B\x0C\x02\x88\x53\x01\x03\x04\x06 |
| GDSP | DSX_A_CDS_CELL | \x2B\x0C\x02\x88\x53\x01\x03\x04\x0D |
| GDSP | DSX_A_CDS_REPLICA | \x2B\x0C\x02\x88\x53\x01\x03\x04\x0E |
| GDSP | DSX_A_CLIENT | \x2B\x0C\x02\x88\x53\x01\x03\x04\x0A |
| GDSP | DSX_A_DEFAULT_DSA | \x2B\x0C\x02\x88\x53\x01\x03\x04\x08 |
| GDSP | DSX_A_DNLIST | \x2B\x0C\x02\x88\x53\x01\x03\x04\x0B |
| GDSP | DSX_A_LOCAL_DSA | \x2B\x0C\x02\x88\x53\x01\x03\x04\x09 |
| GDSP | DSX_A_MASTER_KNOWLEDGE | \x2B\x0C\x02\x88\x53\x01\x03\x04\x00 |
| GDSP | DSX_A_OCT | \x2B\x0C\x02\x88\x53\x01\x03\x04\x05 |
| GDSP | DSX_A_SHADOWED_BY | \x2B\x0C\x02\x88\x53\x01\x03\x04\x03 |
| GDSP | DSX_A_SHADOWING_JOB | \x2B\x0C\x02\x88\x53\x01\x03\x04\x0C |
| GDSP | DSX_A_SRT | \x2B\x0C\x02\x88\x53\x01\x03\x04\x04 |
| GDSP | DSX_A_TIME_STAMP | \x2B\x0C\x02\x88\x53\x01\x03\x04\x02 |
Table 15-2 shows the names of the attribute types, together with the OM value syntax used in the interface to represent values of that attribute type. The table also includes the range of lengths permitted for the string types, indicates whether the attribute can be multivalued, and lists which matching rules are provided for the syntax.
| Attribute Type | OM Value Syntax | Value Length | Multi-valued | nRules |
|---|---|---|---|---|
| DSX_A_ACL | Object(DSX_C_GDS_ACL) | -- | no | E |
| DSX_A_AT | String(OM_S_PRINTABLE_STRING) | 1-101 | yes | E,S |
| DSX_A_CDS_CELL | String(OM_S_OCTET_STRING) | 1-284 | no | E |
| DSX_A_CDS_REPLICA | String(OM_S_OCTET_STRING) | 1-905 | yes | E |
| DSX_A_CLIENT | Only a cache attribute | -- | -- | -- |
| DSX_A_DEFAULT_DSA | Only a cache attribute | -- | -- | -- |
| DSX_A_DNLIST | Object(DS_C_DS_DN) | -- | yes | E,S |
| DSX_A_LOCAL_DSA | Only a cache attribute | -- | -- | -- |
| DSX_A_MASTER_KNOWLEDGE | Object(DS_C_DS_DN) | -- | no | E,S |
| DSX_A_OCT | String(OM_S_PRINTABLE_STRING) | 1-397 | yes | E,S |
| DSX_A_SHADOWED_BY | Not used yet | -- | -- | -- |
| DSX_A_SHADOWING_JOB | Not used yet | -- | -- | -- |
| DSX_A_SRT | String(OM_S_PRINTABLE_STRING) | 1-29 | yes | E,S |
| DSX_A_TIME_STAMP | String(OM_S_UTC_TIME_STRING) | 11-17 | no | E,O |
Note: With the exception of the DSX_A_ACL attribute, the GDSP attributes in Table 15-2 are only to be manipulated through the GDS administration interface (see the OSF DCE GDS Administration Guide and Reference.)
Descriptions of the GDSP attributes follow:
This attribute describes the access rights for one or more Directory Service users.
This attribute describes the attribute types permitted in GDS. For further information, see the OSF DCE GDS Administration Guide and Reference.
These two attributes always exist together in the same object. They describe the information necessary for contacting a remote DCE cell.
This attribute only applies to the cache. It identifies an entry that holds the DUA's presentation address. Its OM syntax is OM_S_PRINTABLE_STRING and it's value is CLIENT.
This attribute only applies to the cache. It identifies an entry that holds the Distinguished Name (DN) of the DUA's default DSA. Its OM syntax is OM_S_PRINTABLE_STRING and its value is DEFAULT-DSA.
This attribute is used internally by the GDS DSA.
This attribute only applies to the cache. It identifies an entry that holds the DN of the DUA's local DSA. Its OM syntax is OM_S_PRINTABLE_STRING and it's value is LOCAL-DSA.
This attribute contains the DN of the DSA that holds the master copy of this entry.
This attribute describes the object classes supported by the GDS DSA. For further information, see the OSF DCE GDS Administration Guide and Reference.
These two GDSP attributes are intended for future use.
This attribute describes the structure of the DNs permitted in GDS.
This attribute is part of the DSX_O_SCHEMA object. It contains the creation time of the DSX_O_SCHEMA object.
The only additional GDSP object class is DSX_O_SCHEMA (see Table 15-3). It is stored in GDS as an object directly under root. The most important attributes of the DSX_O_SCHEMA object are the three recurring attributes DSX_A_OCT, DSX_A_AT, and DSX_A_SRT. These three objects describe the GDS DIT structure. For a more detailed explanation of the GDSP DSX_O_SCHEMA object, see the OSF DCE GDS Administration Guide and Reference.
Note: The third column of Table 15-3 contains the contents octets of the BER encoding of the object identifier in hexadecimal. This object identifier stems from the root {iso(1) identified-organization(3) idc-ecma(0012) member-company(2) siemens-units(1107) sni(1) directory(3) object-class(6)}.
| Package | Attribute Type | Object Identifier BER Hexdecimal |
|---|---|---|
| GDSP | DSX_O_SCHEMA | \x2B\x0C\x02\x88\x53\x01\x03\x06\x00 |
OM_C_OBJECT (defined in the OM package)
None of the OM classes in the preceding list are encodable by using om_encode and om_decode.
An instance of this OM class has the OM attributes of its superclass, OM_C_OBJECT, in addition to the OM attributes listed in Table 15-4.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DSX_MODIFY_PUBLIC | Object(DSX_C_GDS_ACL_ITEM) | -- | 0-4 | -- |
| DSX_READ_STANDARD | Object(DSX_C_GDS_ACL_ITEM) | -- | 0-4 | -- |
| DSX_MODIFY_STANDARD | Object(DSX_C_GDS_ACL_ITEM) | -- | 0-4 | -- |
| DSX_READ_SENSITIVE | Object(DSX_C_GDS_ACL_ITEM) | -- | 0-4 | -- |
| DSX_MODIFY_SENSITIVE | Object(DSX_C_GDS_ACL_ITEM | -- | 0-4 | -- |
The OM attributes of DSX_C_GDS_ACL are as follows:
This attribute specifies the user, or subtree of users, that can modify attributes classified as public attributes.
This attribute specifies the user, or subtree of users, that can read attributes classified as standard attributes.
This attribute specifies the user, or subtree of users, that can modify attributes classified as standard attributes.
This attribute specifies the user, or subtree of users, that can read attributes classified as sensitive attributes.
This attribute specifies the user, or subtree of users, that can modify attributes classified as sensitive attributes.
An instance of this OM class has the OM attributes of its superclass, OM_C_OBJECT, in addition to the OM attributes listed in Table 15-5.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DSX_INTERPRETATION | Enum(DSX_Interpretation) | -- | 1 | -- |
| DSX_USER | Object(DS_C_DS_DN) | -- | 1 | -- |
The OM attributes of a DSX_C_GDS_ACL_ITEM are as follows:
This attribute specifies the scope of the access right. It can have one of the following values:
This attribute is the DN of the user, or subtree of users, to whom an access right applies.
An instance of this OM class has the OM attributes of its superclasses, OM_C_OBJECT and DS_C_CONTEXT, in addition to the OM attributes listed in Table 15-6.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| Service Controls | ||||
| DSX_DUAFIRST | OM_S_BOOLEAN | -- | 1 | OM_FALSE |
| DSX_DONT_STORE | OM_S_BOOLEAN | -- | 1 | OM_TRUE |
| DSX_NORMAL_CLASS | OM_S_BOOLEAN | -- | 1 | OM_FALSE |
| DSX_PRIV_CLASS | OM_S_BOOLEAN | -- | 1 | OM_FALSE |
| DSX_RESIDENT_CLASS | OM_S_BOOLEAN | -- | 1 | OM_FALSE |
| DSX_USEDSA | OM_S_BOOLEAN | -- | 1 | OM_TRUE |
| DSX_DUA_CACHE | OM_S_BOOLEAN | -- | 1 | OM_FALSE |
| DSX_PREFER_ADM_FUNCS | OM_S_BOOLEAN | -- | 1 | OM_FALSE |
| DSX_SIGN_MECHANISM | Enum(DSX_Sign_Mechanism | -- | 0-1 | -- |
| DSX_PROT_REQUEST | Enum(DSX_Prot_Request | -- | 0-1 | -- |
The OM attributes of the DSX_C_GDS_CONTEXT OM class are as follows:
This attribute defines whether the DUA cache or the DSA needs to be read first for query operations. The default value is OM_FALSE; that is, search the DSA first, if not found then search the DUA cache.
This attribute specifies whether the information read from the DSAs by the query functions also needs to be stored in the DUA cache. When this service control is set to OM_TRUE (default value), nothing is stored in the DUA cache.
When this service control is set to OM_FALSE, the information read is stored in the DUA cache. The objects returned by ds_list() and ds_compare() are stored in the cache without their associated attribute information. The objects returned by ds_read() and ds_search() are stored in the cache with all their ``cacheable'' attributes; these are all public attributes that do not exceed 4Kbytes in length.
This information is only cached when a list of requested attributes is supplied. If all attributes are requested, then nothing is stored in the cache.
The DUA cache categorizes the information stored into three different memory classes. The user specifies the category with the following service controls:
If this attribute is set to OM_TRUE, the entry in the DUA cache is assigned to the class of normal objects. If the number of entries in this class exceeds a maximum value, the entry that is not addressed for the longest period of time is removed from the DUA cache.
If this attribute is set to OM_TRUE, the entry in the DUA cache is assigned to the class of privileged objects. Entries can be removed from the class in the same way as normal objects. By using this memory sparingly, the user can protect entries from deletion.
If this attribute is set to OM_TRUE, the entry in the DUA cache is assigned to the class of resident objects. An entry in this memory class is never removed automatically; instead,it can only be removed with ds_remove_entry(). The number of entries is limited; if this limit is exceeded, ds_add_entry() reports an error.
Only the service control of one memory class can be set. The ds_add_entry() function also evaluates these service control bits if the function is used on the DUA cache.
These attributes define whether the entries in the DUA cache or in the DSA, or both, need to be used when providing the service. Depending on the values of these attributes, the following situations can arise:
The ds_add_entry() and ds_remove_entry() functions report an error.
The query functions evaluate the service controls DS_DONT_USE_COPY and DSX_DUAFIRST. When DS_DONT_USE_COPY is OM_FALSE, then DSX_DUAFIRST determines whether the DUA cache or the DSA is read first. When DS_DONT_USE_COPY is OM_TRUE, information from the DSA only is read.
The ds_add_entry() and ds_remove_entry() functions and the query functions only go to the DUA cache.
The ds_add_entry() and ds_remove_entry() functions and the query functions only go to the DSA.
The ds_add_entry() and ds_remove_entry() functions and the query functions report an error.
All other functions always operate on the DSA currently connected.
GDS uses the three following optional attributes:
The DSX_A_MASTER_KNOWLEDGE and DSX_A_ACL attributes are present in every GDS entry.
When an application requests all attributes, it can prevent any of these three optional attributes from being returned by setting this service control to OM_FALSE.
If GDS applications (for example, GDS administration) require these attributes, they are obtained by setting this service control to OM_TRUE.
This attribute is reserved for future use.
This attribute is reserved for future use.
Applications can assume that an object of OM class DSX_C_GDS_CONTEXT, created with default values of all its OM attributes, works with all the interface functions. The constant DS_DEFAULT_CONTEXT can be used as an argument to functions instead of creating an OM object with default values.
The default DSX_C_GDS_CONTEXT is defined in Table 15-7.
| OMAttribute | Default Value |
|---|---|
| Common Arguments | |
| DS_OPERATION_PROGRESS | DS_OPERATION_NOT_STARTED |
| DS_ALIASED_RDNS | 0 |
| Service Controls | |
| DS_CHAINING_PROHIB | OM_TRUE |
| DS_DONT_DEREFERENCE_ALIASES | OM_FALSE |
| DS_DONT_USE_COPY | OM_TRUE |
| DS_LOCAL_SCOPE | OM_FALSE |
| DS_PREFER_CHAINING | OM_FALSE |
| DS_PRIORITY | DS_MEDIUM |
| Local Controls | |
| DS_ASYNCHRONOUS | OM_FALSE |
| DS_AUTOMATIC_CONTINUATION | OM_TRUE |
| Private Extensions | |
| DSX_DUAFIRST | OM_FALSE |
| DSX_DONT_STORE | OM_TRUE |
| DSX_NORMAL_CLASS | OM_FALSE |
| DSX_PRIV_CLASS | OM_FALSE |
| DSX_RESIDENT_CLASS | OM_FALSE |
| DSX_USEDSA | OM_TRUE |
| DSX_DUA_CACHE | OM_FALSE |
| DSX_PREFER_ADM_FUNCS | OM_FALSE |
| DSX_SIGN_MECHANISM | Absent |
| DSX_PROT_REQUEST | Absent |
An instance of this OM class has the OM attributes of its superclasses, OM_C_OBJECT and DS_C_SESSION, in addition to the OM attributes listed in Table 15-8.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DSX_PASSWORD | String(OM_S_OCTET_STRING) | -- | 0 or 1 | -- |
| DSX_DIR_ID | OM_S_INTEGER | -- | 1 | 1 |
| DSX_AUTH_MECHANISM | Enum(DSX_Auth_Mechanism) | -- | 0-1 | -- |
| DSX_AUTH_INFO | String(OM_S_OCTET_STRING | -- | 0-1 | -- |
The OM attributes of DSX_C_GDS_SESSION are as follows:
This attribute indicates the password for the user credentials.
This attribute contains an identifier for distinguishing between several configurations of the Directory Service within a GDS installation. The valid range is from 1 to
If this attribute is present, then it identifies the authentication mechanism that the application requests. If it is absent or has the value DSX_NONE_AT_ALL, then a ds_bind() without credentials (anonymous bind) is requested. The values which this attribute can take are as follows:
If an authentication mechanism is selected that is not currently supported, then ds_bind() returns a DS_E_NOT_SUPPORTED error. If the selected authentication mechanism requires the user's credentials that cannot be assembled, then a DS_E_NO_INFO error is returned.
This attribute is Reserved for future use.
Applications can assume that an object of OM class DSX_C_GDS_SESSION, created with default values of all its OM attributes, works with all the interface functions. Such a session can be created by passing the constant DS_DEFAULT_SESSION as an argument to ds_bind(), having already negotiated the GDS package.
Table 15-9 defines DSX_C_GDS_SESSION.
| OM Attribute | Value Syntax | Value Length | Value Number | Value Initially |
|---|---|---|---|---|
| DS_DSA_ADDRESS | Value obtained from the cache or absent | |||
| DS_DSA_NAME | Value obtained from the cache or absent | |||
| DS_FILE_DESCRIPTOR | DS_NO_VALID_FILE_DESCRIPTOR | |||
| DSX_DIR_ID | 1 | |||
| DSX_AUTH_MECHANISM | Absent | |||
| DSX_AUTH_INFO | Absent |
Note: The values of DS_DSA_ADDRESS and DS_DSA_NAME are taken from the cache of Directory ID 1.