ct_ds_objinfo

Description

Retrieve information associated with a directory object.

Syntax

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;

Parameters

Returns

ct_ds_objinfo returns the following values:

Examples

Example 1

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.

Usage

The following table summarizes ct_ds_objinfo call syntax when action is CS_GET:

• 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:

  1. The application installs a directory callback to handle the search results.

  2. (Network-based directories only.) The application sets the CS_DS_DITBASE connection property to specify the subtree to be searched.

  3. (Network-based directories only.) The application sets any other necessary connection properties to constrain the search.

  4. The application calls ct_ds_lookup to initiate the directory search.

  5. 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.

  6. 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.

  7. 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:

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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;

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;

See also