Retrieve information associated with a directory object.
CS_RETCODE ct_ds_objinfo(ds_object, action, infotype,
number, buffer, buflen,
outlen)
CS_DS_OBJECT *ds_object;
CS_INT action;
CS_INT infotype;
CS_INT number;
CS_VOID *buffer;
CS_INT buflen;
CS_INT *outlen;
A pointer to a CS_DS_OBJECT structure. An application receives a directory object pointer as an input parameter to its directory callback.
Must be CS_GET.
The type of information to retrieve into *buffer. For a description of the available types, see Table 3-22.
When infotype is CS_DS_ATTRIBUTE or CS_DS_ATTRVALS, number specifies the number of the attribute to retrieve. Attribute numbers start at 1.
For other values of infotype, pass number as CS_UNUSED.
The address of the buffer that holds the requested information. Table 3-22 lists the *buffer datatypes for values of infotype.
The length of *buffer, in bytes.
If this argument is supplied, *outlen is set to the length of the value returned in *buffer. This argument is optional and can be passed as NULL.
ct_ds_objinfo returns the following values:
Return value: |
Meaning |
|---|---|
CS_SUCCEED |
The routine completed successfully |
CS_FAIL |
The routine failed |
For an explanation of the steps in this example, see Chapter 9, “Using Directory Services,” in the Open Client Client-Library/C Programmer’s Guide.
The following table summarizes ct_ds_objinfo call syntax when action is CS_GET:
infotype value |
number value |
*buffer datatype |
Value written to *buffer |
|---|---|---|---|
CS_DS_CLASSOID |
CS_UNUSED |
CS_OID structure |
The OID of the directory object class. |
CS_DS_DIST_NAME |
CS_UNUSED |
CS_CHAR array |
Fully qualified (distinguished) directory name of the object, to 512 bytes. The output name is null-terminated. If outlen is not NULL, Client-Library puts the number of bytes written to *buffer (not including the null-terminator) in *outlen. |
CS_DS_NUMATTR |
CS_UNUSED |
CS_INT variable |
Number of attributes associated with the object. |
CS_DS_ATTRIBUTE |
A positive integer |
CS_ATTRIBUTE structure. |
A CS_ATTRIBUTE structure that contains metadata for the attribute specified by the value of number. See “Retrieving object attributes and attribute values” for a description of the CS_ATTRVALUE and CS_ATTRIBUTE data structures. |
CS_DS_ATTRVALS |
A positive integer |
An array of CS_ATTRVALUE unions. The array must be long enough for the number of values indicated by the CS_ATTRIBUTE structure. |
The values of the attribute specified by the value of number. See “Retrieving object attributes and attribute values” for a description of the CS_ATTRVALUE and CS_ATTRIBUTE data structures. |
ct_ds_lookup, ct_ds_objinfo, and the connection’s directory callback routine provide a mechanism for Client-Library applications to view directory entries. The typical process is as follows:
The application installs a directory callback to handle the search results.
(Network-based directories only.) The application sets the CS_DS_DITBASE connection property to specify the subtree to be searched.
(Network-based directories only.) The application sets any other necessary connection properties to constrain the search.
The application calls ct_ds_lookup to initiate the directory search.
Client-Library calls the application’s directory callback once for each found directory entry. Each invocation of the callback receives a CS_DS_OBJECT pointer, which provides an abstract view of the directory entry’s contents.
The application examines each object by calling ct_ds_objinfo as many times as necessary. This can be done in the callback, in mainline code, or both.
When the application is finished with the directory objects returned by the search, it frees the memory associated with them by calling ct_ds_dropobj.
The physical structure of a directory varies between directory service providers. Client-Library maps physical directory entries onto the contents of the CS_DS_OBJECT hidden structure. This minimizes an application’s dependencies on any particular physical directory structure.
An application uses ct_ds_objinfo to inspect the contents of the CS_DS_OBJECT hidden structure.
A typical application calls ct_ds_objinfo several time to inspect the contents of the object. The steps below show a typical call sequence:
The application retrieves the OID that gives the object class of the directory entry by calling ct_ds_objinfo with infotype as CS_DS_CLASSOID and buffer as the address of a CS_OID structure. This step is optional and can be skipped if the application already knows the object class.
The application retrieves the fully qualified name of the entry by calling ct_ds_objinfo with infotype as CS_DS_DISTNAME and buffer as the address of a character string.
The application retrieves the number of attributes present in the object by calling ct_ds_objinfo with infotype as CS_DS_NUMATTR and buffer as the address of a CS_INT variable.
The application retrieves the metadata for each attribute present in the object by calling ct_ds_objinfo with infotype as CS_DS_NUMATTR and buffer as the address of a CS_ATTRIBUTE structure.
The application determines if it wants the attribute’s values by checking the OID specified by the attribute.attr_type field of the CS_ATTRIBUTE structure. If the application wants the values, it allocates an array of CS_ATTRVALUE unions of size attribute.attr_numvals. It then retrieves the values by calling ct_ds_objinfo with infotype as CS_DS_ATTRVALS and buffer as the address of the array.
The application repeats steps d and e for each attribute.
To identify the directory object class being returned, call ct_ds_objinfo with infotype as CS_DS_CLASSOID and buffer as the address of a CS_OID structure.
ct_ds_objinfo sets the fields of the CS_OID to specify the OID of the directory entries object class.
In the returned CS_OID structure, the oid−>oid_buffer field contains the OID string for the object class. The oid−>oid_length contains the length of the string, not counting any null-terminator.
The oid_buffer field can be compared to the OID string constant for the expected object class.
To retrieve the fully qualified directory name of the object, call ct_ds_objinfo with infotype as CS_DS_DIST_NAME and buffer as the address of a CS_CHAR string.
The name string is null-terminated.
For server (CS_OID_OBJSERVER) class objects, the application can pass the object’s fully qualified name to ct_connect to open a connection to the server represented by the object.
The attributes of a directory object are available as a numbered set. However, the position of individual attributes within the set may vary depending on the directory service provider, and some directory providers do not guarantee that attribute orders are invariant. Also, Sybase may add new attributes to a directory object class between versions.
For the above reasons, applications should be coded to work independently of the number and order of object attributes.
ct_ds_objinfo uses a CS_ATTRIBUTE structure to define the metadata for attribute values, and returns the values themselves in an array of CS_ATTRVALUE unions.
The CS_ATTRIBUTE structure is used with ct_ds_objinfo to describe the attributes of a directory object.
typedef struct
{
CS_OID attr_type;
CS_INT attr_syntax;
CS_INT attr_numvals;
} CS_ATTRIBUTE;
where:
attr_type is a CS_OID structure that uniquely describes the type of the attribute. This field tells the application which of an object’s attributes it has received.
The definition of the directory object class determines the attribute types that an object can contain.
attr_syntax is a syntax specifier that tells how the attribute value is expressed. Attribute values are passed within a CS_ATTRVALUE union, and the syntax specifier tells which member of the union to use.
attr_numvals tells how many values the attribute contains. This information can be used to size an array of CS_ATTRVALUE unions to hold the attribute values.
Attribute values are returned to the application in a CS_ATTRVALUE union. This union contains a members for each possible data type needed to represent attribute values. The declaration looks like this:
typedef union _cs_attrvalue
{
CS_STRING value_string;
CS_BOOL value_boolean;
CS_INT value_enumeration;
CS_INT value_integer;
CS_TRANADDR value_tranaddr;
CS_OID value_oid;
} CS_ATTRVALUE;
Attribute values are retrieved by ct_ds_objinfo into an array of CS_ATTRVALUE unions. The array size should match the attr_numvals field of the CS_ATTRIBUTE structure. The value should be taken as the union member designated by the attr_syntax field of the CS_ATTRIBUTE structure. Table 3-23 shows the correspondence between attribute syntax specifiers and the members of CS_ATTRVALUE.
Attribute syntax specifier |
Union member |
|---|---|
CS_ATTR_SYNTAX_STRING |
value_string String values are represented by a CS_STRING structure, which is described under String values below. |
CS_ATTR_SYNTAX_BOOLEAN |
value_boolean Boolean values are represented as CS_BOOL. |
CS_ATTR_SYNTAX_ENUMERATION |
value_enumeration Enumerated values are represented as CS_INT. |
CS_ATTR_SYNTAX_INTEGER |
value_integer Integer values are represented as CS_INT. |
CS_ATTR_SYNTAX_TRANADDR |
value_tranaddr Transport addresses are represented as a CS_TRANADDR structure, which is described under Transport address values below. |
CS_ATTR_SYNTAX_OID |
value_oid OID values are represented as CS_OID structure, which is explained on page §. |
The CS_STRING structure is defined as follows:
typedef struct _cs_string
{
CS_INT str_length;
CS_CHAR str_buffer[CS_MAX_DS_STRING];
} CS_STRING;
The contents of str_buffer are null-terminated. str_length does not count the null-terminator in the length.
Transport addresses are encoded in a Sybase-specific format within the CS_TRANADDR structure shown below.
typedef struct _cs_tranaddr
{
CS_INT addr_accesstype;
CS_STRING addr_trantype;
CS_STRING addr_tranaddress;
} CS_TRANADDR;
ct_ds_lookup, ct_ds_dropobj, “Directory services”, “Server directory object”
