DCE 1.1: Directory Services - IDL Notation of CDS Operations

DCE 1.1: Directory Services
Copyright © 1997 The Open Group

IDL Notation of CDS Operations

This chapter contains specifications for the RPC interfaces used by CDS clerks and servers.

The RPC interfaces are specified in IDL (Interface Definition Language). Part of the information in these IDL declarations is symbolic and need not be preserved identically. For example, the names of procedures and parameters are a local matter. The information that must be identical for a conforming implementation is as follows:

the interface identifier, composed of UUID and version
the order of procedures within the interface definition (see CDS IDL Definitions )
the order and number of parameters in procedure signatures
the types of parameters and procedures
the attributes of parameters and procedures.

The following sections contain the interface specifications for CDS remote operations.

cds_Advertise()

[broadcast,maybe] void cds_Advertise(
        [in] handle_t        h,
        [in] cds_FullName_t  *cellname_p,
        [in] uuid_t          cell_diruid,
        [in] cds_CH_t        *nscle_p
        );

cds_Advertise () advertises the CDS server's availability and the availability of each of its running clearinghouses. CDS servers send advertisements when one of the following is true:

The advertisement timer expires.
A solicitation request (operation cds_Solicit ()) is received.

The advertisement intervals for CDS server advertisements are implementation-dependent. A recommended default for advertisement intervals is five minutes. Implementations should apply jitter to this timeout value within a cell name space that is running replicated servers to avoid synchronised broadcasts.

No permission is required for the operation.

Input Parameters

The input parameters for cds_Advertise () are:

h: RPC binding handle.
cellname_p: The fully-qualified global name of the local cell.
cell_diruid: The UUID of the cell.
nscle_p: The list of available clearinghouses at the server, including its UUIDs, fully-qualified global names, and exported protocol towers. The rp_type flag of this data structure determines the replica type.

cds_CreateChild()

error_status_t cds_CreateChild(
        [in] handle_t             h,
        [in,out] cds_Progress_t   *Progress_p,
        [in,ptr] sec_id_foreign_t *user_p,
        [in] uuid_t               *childID_p,
        [in] cds_Set_t            *replicaset_p,
        [out] uuid_t              *parentID_p,
        [out] cds_status_t        *cds_status_p
        );

cds_CreateChild () creates a child pointer entry in the parent directory.

This operation is performed only in server-to-server communication as a result of a cds_CreateDirectory () operation which may affect a parent directory located in a different clearinghouse on a remote server.

The operation requires insert access permission to the parent directory.

Input Parameters

The input parameters for cds_CreateChild () are:

h

RPC binding handle referring to the target server and clearinghouse.

user_p

Identity of the principal that is invoking this operation.

This client's EPAC is used at the target server to verify the initiator's identity and access permissions (requesting server impersonates the initiator), for operations that set up an Access Control List on the child pointer entry. The appropriate security service operations are assumed (refer to the DCE Security Services specification).

childID_p

The UUID of the child.

replicaset_p

Replica set. Each member of the set contains one replica pointer (the sm_value fields are of type VT_ReplicaPointer).

Input/Output Parameters

The input/output parameters for cds_CreateChild () are:

Progress_p: Progress record, used at the server's clerk for handling referrals to another server. The pr_unresolved field of the progress record contains the portion of the original fully-qualified global name of the child entry created.

Output Parameters

The output parameters for cds_CreateChild () are:

parentID_p

The UUID of the parent directory.

cds_status_p

Error status return. On [CDS_UNKNOWNENTRY], the er_name field may be filled in with the last name the server successfully accessed.

Possible status codes are (non-exclusive):

 

[CDS_SUCCESS]
[CDS_VERSIONSKEW]
[CDS_ACCESSDENIED]
[CDS_CANNOTAUTHENTICATE]
[CDS_UNTRUSTEDCH]
[CDS_CLEARINGHOUSEDOWN]
[CDS_POSSIBLECYCLE]
[CDS_ROOTLOST]
[CDS_UNDERSPECIFIEDNAME]
[CDS_UNKNOWNENTRY]
[CDS_ENTRYEXISTS]

cds_CreateDirectory()

error_status_t cds_CreateDirectory(
        [in] handle_t            h,
        [in,out] cds_Progress_t  *Progress_p,
        [out] cds_Timestamp_t    *actual_ts_p,
        [out] cds_status_t       *cds_status_p
        );

cds_CreateDirectory () creates a directory entry as a child of the directory entry implied by the fully-qualified global name of the new directory.

The operation requires insert access permission to the parent directory, and write access permission to the clearinghouse which is to store the master replica for the directory.

Note also that this operation performs a cds_CreateChild () operation and therefore the server requires respective access permissions to its peer server.

Input Parameters

The input parameters for cds_CreateDirectory () are:

h: RPC binding handle referring to the target server and clearinghouse.

Input/Output Parameters

The input/output parameters for cds_CreateDirectory () are:

Progress_p: Progress record, used at the clerk for handling referrals to another server. The pr_unresolved field of the progress record contains the portion of the original fully-qualified global name of the directory entry created.

Output Parameters

The output parameters for cds_CreateDirectory () are:

actual_ts_p

A timestamp indicating the date and time that the directory was created.

cds_status_p

Error status return. On [CDS_UNKNOWNENTRY], the er_name field may be filled in with the last name the server successfully accessed.

Possible status codes are (non-exclusive):

 

[CDS_SUCCESS]
[CDS_VERSIONSKEW]
[CDS_ACCESSDENIED]
[CDS_CANNOTAUTHENTICATE]
[CDS_UNTRUSTEDCH]
[CDS_CLEARINGHOUSEDOWN]
[CDS_POSSIBLECYCLE]
[CDS_ROOTLOST]
[CDS_UNDERSPECIFIEDNAME]
[CDS_UNKNOWNENTRY]
[CDS_CANTPUTHERE]
[CDS_ENTRYEXISTS]

cds_CreateObject()

error_status_t cds_CreateObject(
        [in] handle_t            h,
        [in,out] cds_Progress_t  *Progress_p,
        [in,ptr] cds_Name_t      *class_p,
        [in,ptr] cds_Version_t   *version_p,
        [in, ptr] uuid_t         *uuid_p,
        [out] cds_Timestamp_t    *actual_ts_p,
        [out] cds_status_t       *cds_status_p
        );

cds_CreateObject () creates an object entry in the cell name space. Creating an object entry requires meeting the following conditions:

The name given for the object entry must be new for the cell name space. If a directory, object entry, clearinghouse or soft link already exists with the specified name, the operation is unsuccessful.
All directories cited in the fully-qualified global name must exist.

The entry initially has the CDS_CTS and CDS_UTS attributes, and optionally, the CDS_Class, CDS_ClassVersion and CDS_ObjectUUID attributes. Other attributes may be added via the cds_ModifyAttribute () operation.

The operation requires insert access permission to the parent directory.

Input Parameters

The input parameters for cds_CreateObject () are:

h: RPC binding handle referring to the target server and clearinghouse.
class_p: A printable string name representing the object's class. The nm_name field is encoded as a SimpleName_t structure with its sn_flag set to either SN_cds or SN_cdswildcard. This parameter is optional. If it contains a non-NULL value, version_p is also used.
version_p: The major and minor class version numbers of the application. This parameter is used only if class_p is non-NULL.
uuid_p: The optional unique identifier for the object entry.

Input/Output Parameters

The input/output parameters for cds_CreateObject () are:

Progress_p: Progress record, used at the clerk for handling referrals to another server. The pr_unresolved field of the progress record contains the portion of the original fully-qualified global name of the object entry created.

Output Parameters

The output parameters for cds_CreateObject () are:

actual_ts_p

A timestamp indicating the date and time the object entry was created.

cds_status_p

Error status return. On [CDS_UNKNOWNENTRY], the er_name field may be filled in with the last name the server successfully accessed.

Possible status codes are (non-exclusive):

 

[CDS_SUCCESS]
[CDS_VERSIONSKEW]
[CDS_ACCESSDENIED]
[CDS_CANNOTAUTHENTICATE]
[CDS_UNTRUSTEDCH]
[CDS_CLEARINGHOUSEDOWN]
[CDS_POSSIBLECYCLE]
[CDS_ROOTLOST]
[CDS_UNDERSPECIFIEDNAME]
[CDS_UNKNOWNENTRY]
[CDS_ENTRYEXISTS]

cds_CreateSoftLink()

error_status_t cds_CreateSoftLink(
        [in] handle_t            h,
        [in,out] cds_Progress_t  *Progress_p,
        [in] cds_FullName_t      *target_p,
        [in,ptr] cds_Timeout_t   *linkTimeout_p,
        [out] cds_Timestamp_t    *actual_ts_p,
        [out] cds_status_t       *cds_status_p
        );

cds_CreateSoftLink () creates a soft link entry with the name as identified in the progress record that points to another entry whose name is identified by target_p.

The operation requires insert access permission to the directory in which the soft link is created.

Input Parameters

The input parameters for cds_CreateSoftLink () are:

h

RPC binding handle referring to the target server and clearinghouse.

target_p

The string representation of the fully-qualified global name of an existing entry in the cell name space to which the soft link (identified in Progress_p) points.

linkTimeout_p

A structure that specifies two values: the first value is an absolute time after the elapse of which the soft link is deleted if its target entry no longer exists; the second value is an extension factor for the timeout. When the time determined by the first value expires, the CDS server attempts to verify that the entry to which the link points still exists, and extends the life of the soft link by the second value only if it does still exist.

If this operation parameter is set to NULL, the soft link is neither checked nor deleted by the CDS server on the client's behalf.

Input/Output Parameters

The input/output parameters for cds_CreateSoftLink () are:

Progress_p: Progress record, used at the clerk for handling referrals to another server. The pr_unresolved field of the progress record contains the portion of the original fully-qualified global name of the soft link to be created.

Output Parameters

The output parameters for cds_CreateSoftLink () are:

actual_ts_p

A timestamp indicating the date and time the soft link was created.

cds_status_p

Error status return. On [CDS_UNKNOWNENTRY], the er_name field may be filled in with the last name the server successfully accessed.

Possible status codes are (non-exclusive):

 

[CDS_SUCCESS]
[CDS_VERSIONSKEW]
[CDS_ACCESSDENIED]
[CDS_CANNOTAUTHENTICATE]
[CDS_UNTRUSTEDCH]
[CDS_CLEARINGHOUSEDOWN]
[CDS_POSSIBLECYCLE]
[CDS_ROOTLOST]
[CDS_UNDERSPECIFIEDNAME]
[CDS_UNKNOWNENTRY]
[CDS_ENTRYEXISTS]

cds_DeleteChild()

error_status_t cds_DeleteChild(
        [in] handle_t            h,
        [in,out] cds_Progress_t  *Progress_p,
        [out] cds_status_t       *cds_status_p
        );

cds_DeleteChild () deletes the child pointer entry from the parent directory as part of deleting a directory from the cell name space.

This operation is only performed in server-to-server communication as a result of a cds_DeleteDirectory () operation if the parent directory is located in a different clearinghouse on a remote server.

The operation requires either delete access permission to the child pointer, or administer access permission to the parent directory entry.

Input Parameters

The input parameters for cds_DeleteChild () are:

h: RPC binding handle referring to the target server and clearinghouse.

Input/Output Parameters

The input/output parameters for cds_DeleteChild () are:

Progress_p: Progress record, used at the server's clerk for handling referrals to another server. The pr_unresolved field of the progress record contains the portion of the original fully-qualified global name of the child entry deleted.

Output Parameters

The output parameters for cds_DeleteChild () are:

cds_status_p

Error status return. On [CDS_UNKNOWNENTRY], the er_name field may be filled in with the last name the server successfully accessed.

Possible status codes are (non-exclusive):

 

[CDS_SUCCESS]
[CDS_VERSIONSKEW]
[CDS_ACCESSDENIED]
[CDS_CANNOTAUTHENTICATE]
[CDS_UNTRUSTEDCH]
[CDS_CLEARINGHOUSEDOWN]
[CDS_POSSIBLECYCLE]
[CDS_ROOTLOST]
[CDS_UNDERSPECIFIEDNAME]
[CDS_UNKNOWNENTRY]

cds_DeleteDirectory()

error_status_t cds_DeleteDirectory(
        [in] handle_t            h,
        [in,out] cds_Progress_t  *Progress_p,
        [out] cds_status_t       *cds_status_p
        );

cds_DeleteDirectory () removes the specified directory entry from the cell name space. The directory must be empty in order to be deleted.

The operation requires delete access permission to the directory entry, and write permission to the clearinghouse that stores the master replica.

Note also that this operation performs a cds_DeleteChild () operation, and therefore the server requires respective access permissions to its peer server.

Input Parameters

The input parameters for cds_DeleteDirectory () are:

h: RPC binding handle referring to the target server and clearinghouse.

Input/Output Parameters

The input/output parameters for cds_DeleteDirectory () are:

Progress_p: Progress record, used at the clerk for handling referrals to another server. The pr_unresolved field of the progress record contains the portion of the original fully-qualified global name of the directory entry to be deleted.

Output Parameters

The output parameters for cds_DeleteDirectory () are:

cds_status_p

Error status return. On [CDS_UNKNOWNENTRY], the er_name field may be filled in with the last name the server successfully accessed.

Possible status codes are (non-exclusive):

 

[CDS_SUCCESS]
[CDS_VERSIONSKEW]
[CDS_ACCESSDENIED]
[CDS_CANNOTAUTHENTICATE]
[CDS_UNTRUSTEDCH]
[CDS_CLEARINGHOUSEDOWN]
[CDS_POSSIBLECYCLE]
[CDS_ROOTLOST]
[CDS_UNDERSPECIFIEDNAME]
[CDS_UNKNOWNENTRY]
[CDS_NOTEMPTY]

cds_DeleteObject()

error_status_t cds_DeleteObject(
        [in] handle_t            h,
        [in,out] cds_Progress_t  *Progress_p,
        [out] cds_status_t       *cds_status_p
        );

cds_DeleteObject () removes the specified object entry from the cell name space.

The operation requires delete access permission to the object entry, or administer permission to its parent directory.

Input Parameters

The input parameters for cds_DeleteObject () are:

h: RPC binding handle referring to the target server and clearinghouse.

Input/Output Parameters

The input/output parameters for cds_DeleteObject () are:

Progress_p: Progress record, used at the clerk for handling referrals to another server. The pr_unresolved field of the progress record contains the portion of the original fully-qualified global name of the object entry to be deleted.

Output Parameters

The output parameters for cds_DeleteObject () are:

cds_status_p

Error status return. On [CDS_UNKNOWNENTRY], the er_name field may be filled in with the last name the server successfully accessed.

Possible status codes are (non-exclusive):

 

[CDS_SUCCESS]
[CDS_VERSIONSKEW]
[CDS_ACCESSDENIED]
[CDS_CANNOTAUTHENTICATE]
[CDS_UNTRUSTEDCH]
[CDS_CLEARINGHOUSEDOWN]
[CDS_POSSIBLECYCLE]
[CDS_ROOTLOST]
[CDS_UNDERSPECIFIEDNAME]
[CDS_UNKNOWNENTRY]

cds_DeleteSoftLink()

error_status_t cds_DeleteSoftLink(
        [in] handle_t            h,
        [in,out] cds_Progress_t  *Progress_p,
        [out] cds_status_t       *cds_status_p
        );

cds_DeleteSoftLink () deletes a soft link from the cell name space.

The operation requires delete access permission to the soft link, or administer permission to its parent directory.

Input Parameters

The input parameters for cds_DeleteSoftLink () are:

h: RPC binding handle referring to the target server and clearinghouse.

Input/Output Parameters

The input/output parameters for cds_DeleteSoftLink () are:

Progress_p: Progress record, used at the clerk for handling referrals to another server. The pr_unresolved field of the progress record contains the portion of the original fully-qualified global name of the soft link to be deleted.

Output Parameters

The output parameters for cds_DeleteSoftLink () are:

cds_status_p

Error status return. On [CDS_UNKNOWNENTRY], the er_name field may be filled in with the last name the server successfully accessed.

Possible status codes are (non-exclusive):

 

[CDS_SUCCESS]
[CDS_VERSIONSKEW]
[CDS_ACCESSDENIED]
[CDS_CANNOTAUTHENTICATE]
[CDS_UNTRUSTEDCH]
[CDS_CLEARINGHOUSEDOWN]
[CDS_POSSIBLECYCLE]
[CDS_ROOTLOST]
[CDS_UNDERSPECIFIEDNAME]
[CDS_UNKNOWNENTRY]

cds_EnumerateAttributes()

[idempotent] error_status_t cds_EnumerateAttributes(
        [in] handle_t             h,
        [in,out] cds_Progress_t   *Progress_p,
        [in] unsigned small       type,
        [in] cds_Name_t           *context_p,
        [in] unsigned32           max_size,
        [in,out,ptr] cds_SetP_t   *attr_set,
        [out] unsigned small      *wholeset_p,
        [out] cds_status_t        *cds_status_p
        );

cds_EnumerateAttributes () returns in attr_set a set whose members are the attribute identifiers of each currently present attribute of the entry whose type is specified in type.

Note:: The attribute identifiers are enumerated in lexical order of the string representation of object identifiers (CCITT OIDs). If the call returns FALSE (parameter wholeset_p), not all attributes have been enumerated and the client may make further calls, setting context_p to the last attribute in the set returned, until the operation returns TRUE.

The operation requires read access permission to the entry whose attributes are to be enumerated.

Input Parameters

The input parameters for cds_EnumerateAttributes () are:

h

RPC binding handle referring to the target server and clearinghouse.

type

The type of the entry for which attributes are enumerated. Valid entry types are:

 

ET_directory
ET_object
ET_childPointer
ET_softlink
ET_clearinghouse
ET_dirOrObj

context_p

The context of the last attribute in the previous call (the attribute identifier returned in attr_set). The nm_name field is encoded as a SimpleName_t structure with its sn_flag set to SN_objectid. This is used in a sequence of calls to enumerate the whole set of attributes of this entry. If set to NULL, the look-up operation starts at the beginning of the entry.

max_size

The maximum size of values to be returned by attr_set per call instance.

Input/Output Parameters

The input/output parameters for cds_EnumerateAttributes () are:

Progress_p

Progress record, used at the clerk for handling referrals to another server. The pr_unresolved field of the progress record contains the portion of the original fully-qualified global name of the entry for which attributes are enumerated.

attr_set

A pointer to the set of the requested attribute identifiers (the attribute name to identifier mapping is specified in CDS Attributes Table ). These attribute identifiers are CCITT object identifiers, encoded in ASN.1, BER. The attribute identifiers are contained in the sm_value fields (type VT_byte), encoded as SimpleName_t structures. Attribute values are absent.

The buffer that attr_set points to must not exceed max_size.

Output Parameters

The output parameters for cds_EnumerateAttributes () are:

wholeset_p

A boolean value that indicates whether this call instance returned the whole set of enumerated attributes.

cds_status_p

Error status return. On [CDS_UNKNOWNENTRY], the er_name field may be filled in with the last name the server successfully accessed.

Possible status codes are (non-exclusive):

 

[CDS_SUCCESS]
[CDS_VERSIONSKEW]
[CDS_ACCESSDENIED]
[CDS_CANNOTAUTHENTICATE]
[CDS_UNTRUSTEDCH]
[CDS_CLEARINGHOUSEDOWN]
[CDS_POSSIBLECYCLE]
[CDS_ROOTLOST]
[CDS_UNDERSPECIFIEDNAME]
[CDS_UNKNOWNENTRY]
[CDS_NOTLINKED]
[CDS_DANGLINGLINK]

cds_EnumerateChildren()

[idempotent] error_status_t cds_EnumerateChildren(
        [in] handle_t             h,
        [in,out] cds_Progress_t   *Progress_p,
        [in] cds_Name_t           *wild_p,
        [in] cds_Name_t           *context_p,
        [in] unsigned32           max_size,
        [in,out,ptr] cds_SetP_t   *name_set,
        [out] unsigned small      *wholeset_p,
        [out] cds_status_t        *cds_status_p
        );

cds_EnumerateChildren () takes as input the name of a directory and a wildcarded component name to match against child pointer entries in the directory. It returns a set whose members are the component names of child directories of the directory which matched the wildcarded name. If no children matched the wildcard or the directory has no children, a NULL set is returned.

The child pointers are enumerated in lexical order (based on the Portable Character Set (PCS)). If the call returns FALSE (parameter wholeset_p), not all children have been enumerated and the client may make further calls, setting context_p to the last child directory name in the set returned, until the operation returns TRUE.

This operation requires read access permission to the parent directory and to each child pointer.

Input Parameters

The input parameters for cds_EnumerateChildren () are:

h: RPC binding handle referring to the target server and clearinghouse.
wild_p: A wildcard filter for the child directory names. The nm_name field is encoded as a SimpleName_t structure with its sn_flag set to either SN_cds or SN_cdswildcard. This operation parameter is optional, and can be set to NULL. Specifying a NULL value is the same as specifying the string * (asterisk character).
context_p: The context of the last child directory in the previous call (the child directory name returned in name_set). The nm_name field is encoded as a SimpleName_t structure with its sn_flag set to SN_cds. This is used in a sequence of calls to enumerate the whole set of child directories of this entry. If set to NULL, the look-up operation starts at the beginning of the entry.
max_size: The maximum size of values to be returned by name_set per call instance.

Input/Output Parameters

The input/output parameters for cds_EnumerateChildren () are:

Progress_p: Progress record, used at the clerk for handling referrals to another server. The pr_unresolved field of the progress record contains the portion of the original fully-qualified global name of the directory for which the child directories are enumerated.
name_set: A pointer to the set of the requested child directories. The child directory names are contained in the sm_value fields (type VT_byte), encoded as a SimpleName_t structure. The buffer that name_set points to must not exceed max_size.

Output Parameters

The output parameters for cds_EnumerateChildren () are:

wholeset_p

A boolean value that indicates whether this call instance returned the whole set of enumerated child directory entries.

cds_status_p

Error status return. On [CDS_UNKNOWNENTRY], the er_name field may be filled in with the last name the server successfully accessed.

Possible status codes are (non-exclusive):

 

[CDS_SUCCESS]
[CDS_VERSIONSKEW]
[CDS_ACCESSDENIED]
[CDS_CANNOTAUTHENTICATE]
[CDS_UNTRUSTEDCH]
[CDS_CLEARINGHOUSEDOWN]
[CDS_POSSIBLECYCLE]
[CDS_ROOTLOST]
[CDS_UNDERSPECIFIEDNAME]
[CDS_UNKNOWNENTRY]

cds_EnumerateObjects()

[idempotent] error_status_t cds_EnumerateObjects(
        [in] handle_t             h,
        [in,out] cds_Progress_t   *Progress_p,
        [in] cds_Name_t           *wild_p,
        [in] cds_Name_t           *context_p,
        [in] cds_Name_t           *class_p,
        [in] unsigned32           max_size,
        [in,out,ptr] cds_SetP_t   *name_set,
        [out] unsigned small      *wholeset_p,
        [in,out] unsigned small   *returnClass_p,
        [out] cds_status_t        *cds_status_p
        );

cds_EnumerateObjects () takes as input the name of a directory, a wildcarded component name, and optionally a filter on object class to match against object entries in the directory. It returns a set whose members are either the component names of object entries in the directory which matched the wildcarded name, or the object names paired with the object class, depending on the value of the returnClass_p parameter. If no object entries matched the wildcard or the directory contains no object entries, a NULL set is returned.

The objects are enumerated in lexical order (based on the Portable Character Set (PCS)). If the call returns FALSE (parameter wholeset_p), not all matching objects have been enumerated, and the client may make further calls, setting context_p to the last object name in the set returned, until the operation returns TRUE.

If the filter class_p is specified, only those objects of the specified class are returned. The filter may be a wildcard class.

This operation requires read access permission to the directory and objects.

Input Parameters

The input parameters for cds_EnumerateObjects () are:

h: RPC binding handle referring to the target server and clearinghouse.
wild_p: A wildcard filter for object entry names in the specified directory. The nm_name field is encoded as a SimpleName_t structure with its sn_flag set to either SN_cds or SN_cdswildcard. This operation parameter is optional and can be set to NULL. Specifying a NULL value is the same as specifying the string * (asterisk character).
context_p: The context of the last object entry name in the previous call (the object entry name returned in name_set). The nm_name field is encoded as a SimpleName_t structure with its sn_flag set to SN_cds. This is used in a sequence of calls to enumerate the whole set of object entries of the directory. If set to NULL, the look-up operation starts at the beginning.
class_p: A filter for class names (may be wildcarded) of object entries that use the CDS_Class attribute. The nm_name field is encoded as a SimpleName_t structure with its sn_flag set to either SN_cds or SN_cdswildcard. This operation parameter is optional and can be set to NULL. Specifying a NULL value is the same as specifying the string * (asterisk character).
max_size: The maximum size of values to be returned by name_set per call instance.

Input/Output Parameters

The input/output parameters for cds_EnumerateObjects () are:

Progress_p: Progress record, used at the clerk for handling referrals to another server. The pr_unresolved field of the progress record contains the portion of the original fully-qualified global name of the directory for which the object entries are enumerated.
name_set: A pointer to the set of the requested object entry names. Object and class names are contained in the sm_value fields (type VT_byte), encoded as a SimpleName_t structure. If returnClass_p is TRUE, each member of the returned set contains in the sm_value field a sequence of object entry name immediately followed by class name (encoded as SimpleName_t). The buffer that name_set points to must not exceed max_size.
returnClass_p: Indicates whether the object's class is returned. If set to TRUE, the object's class is returned along with the object name. If set to FALSE, the object's class is not returned.

Output Parameters

The output parameters for cds_EnumerateObjects () are:

wholeset_p

A boolean value that indicates whether this call instance returned the whole set of enumerated object entries.

cds_status_p

Error status return. On [CDS_UNKNOWNENTRY], the er_name field may be filled in with the last name the server successfully accessed.

Possible status codes are (non-exclusive):

 

[CDS_SUCCESS]
[CDS_VERSIONSKEW]
[CDS_ACCESSDENIED]
[CDS_CANNOTAUTHENTICATE]
[CDS_UNTRUSTEDCH]
[CDS_CLEARINGHOUSEDOWN]
[CDS_POSSIBLECYCLE]
[CDS_ROOTLOST]
[CDS_UNDERSPECIFIEDNAME]
[CDS_UNKNOWNENTRY]

cds_EnumerateSoftLinks()

[idempotent] error_status_t cds_EnumerateSoftLinks(
        [in] handle_t             h,
        [in,out] cds_Progress_t   *Progress_p,
        [in] cds_Name_t           *wild_p,
        [in] cds_Name_t           *context_p,
        [in] unsigned32           max_size,
        [in,out,ptr] cds_SetP_t   *name_set,
        [out] unsigned small      *wholeset_p,
        [out] cds_status_t        *cds_status_p
        );

cds_EnumerateSoftLinks () takes as input the name of a directory and a wildcarded component name to match against soft link entries in the directory. It returns a set whose members are the component names of soft link entries in the directory which matched the wildcarded name. If no soft link entries matched the wildcard or the directory contains no soft link entries, a NULL set is returned.

The soft links are enumerated in lexical order (based on the Portable Character Set (PCS)). If the call returns FALSE (parameter wholeset_p), not all matching soft links have been enumerated and the client may make further calls, setting context_p to the last soft link in the set returned, until the operation returns TRUE.

This operation requires read access permission to the directory and soft links.

Input Parameters

The input parameters for cds_EnumerateSoftLinks () are:

h: RPC binding handle referring to the target server and clearinghouse.
wild_p: A wildcard filter for the soft links in the specified directory. The nm_name field is encoded as a SimpleName_t structure with its sn_flag set to either SN_cds or SN_cdswildcard. This operation parameter is optional and can be set to NULL. Specifying a NULL value is the same as specifying the string * (asterisk character).
context_p: The context of the last soft link in the previous call (the soft link name returned in name_set). The nm_name field is encoded as a SimpleName_t structure with its sn_flag set to SN_cds. This is used in a sequence of calls to enumerate the whole set of soft link entries of the directory. If set to NULL, the look-up operation starts at the beginning.
max_size: The maximum size of values to be returned by name_set per call instance.

Input/Output Parameters

The input/output parameters for cds_EnumerateSoftLinks () are:

Progress_p: Progress record, used at the clerk for handling referrals to another server. The pr_unresolved field of the progress record contains the portion of the original fully-qualified global name of the directory for which soft links are enumerated.
name_set: A pointer to the set of the requested soft link values. The soft link entry names are contained in the sm_value fields (type VT_byte), encoded as SimpleName_t structures. The buffer that name_set points to must not exceed max_size.

Output Parameters

The output parameters for cds_EnumerateSoftLinks () are:

wholeset_p

A boolean value that indicates whether this call instance returned the whole set of enumerated soft links.

cds_status_p

Error status return. On [CDS_UNKNOWNENTRY], the er_name field may be filled in with the last name the server successfully accessed.

Possible status codes are (non-exclusive):

 

[CDS_SUCCESS]
[CDS_VERSIONSKEW]
[CDS_ACCESSDENIED]
[CDS_CANNOTAUTHENTICATE]
[CDS_UNTRUSTEDCH]
[CDS_CLEARINGHOUSEDOWN]
[CDS_POSSIBLECYCLE]
[CDS_ROOTLOST]
[CDS_UNDERSPECIFIEDNAME]
[CDS_UNKNOWNENTRY]

cds_ModifyAttribute()

[idempotent] error_status_t cds_ModifyAttribute(
        [in] handle_t            h,
        [in,out] cds_Progress_t  *Progress_p,
        [in] unsigned small      type,
        [in] cds_Update_t        *update_p,
        [out] cds_status_t       *cds_status_p
        );

cds_ModifyAttribute () applies one update to the specified entry. An attribute may be removed or added, or a value may be removed or added to the values of a set-valued attribute, or the value of a single-valued attribute may be altered. This operation may also remove an entire object entry from the name space.

If the target entry is a directory, only certain attributes of the directory may be directly modified with cds_ModifyAttribute ().

This operation requires either write access permission to the entry whose attribute is being modified (if the operation makes the attribute present or absent), or write access permission to the parent directory.

Input Parameters

The input parameters for cds_ModifyAttribute () are:

h

RPC binding handle referring to the target server and clearinghouse.

type

The type of the entry for which attributes are modified. Valid entry types are:

 

ET_directory
ET_object
ET_childPointer
ET_softlink
ET_clearinghouse

update_p

The structure defining the update operation, type, identifier, value and timestamp of the attribute to be modified.

Valid values for the update operation flag are:

UD_present: Make attribute or value (or both) present; that is, either add attribute or alternative value.
UD_absent: Make object entry, attribute or attribute value absent; that is, remove it.

Valid values for the attribute type are:

 

AT_none
AT_single
AT_set

The result of this operation is determined by the combination of the three fields defining operation, type and value. The relationship is listed in Modify Operations .

Attribute
_ _
Operation Type Value Result
UD_present AT_none - Invalid: returns status [CDS_WRONGATTRIBUTETYPE].
AT_single value Creates new attribute or replaces value if attribute exists.
AT_single empty Invalid: returns status [CDS_INVALIDUPDATE].
AT_set value Creates new attribute or adds value to existing attribute.
AT_set empty Creates new attribute (empty set). Invalid if attribute exists (returns status [CDS_INVALIDUPDATE]).
UD_absent AT_none ignored Deletes object entry (invalid on other entry types).
AT_single ignored Removes attribute from entry.
AT_set any value (except VT_none) Removes value from attribute.
AT_set value type VT_none Removes attribute from entry.

	Attribute
	_	_
Operation	Type	Value	Result
UD_present	AT_none	-	Invalid: returns status [CDS_WRONGATTRIBUTETYPE].
	AT_single	value	Creates new attribute or replaces value if attribute exists.
	AT_single	empty	Invalid: returns status [CDS_INVALIDUPDATE].
	AT_set	value	Creates new attribute or adds value to existing attribute.
	AT_set	empty	Creates new attribute (empty set). Invalid if attribute exists (returns status [CDS_INVALIDUPDATE]).
UD_absent	AT_none	ignored	Deletes object entry (invalid on other entry types).
	AT_single	ignored	Removes attribute from entry.
	AT_set	any value (except VT_none)	Removes value from attribute.
	AT_set	value type VT_none	Removes attribute from entry.

Table: Modify Operations

The update_p data structure contains a field in which the client may supply a timestamp to be used for the update. If the client chooses not to supply its own timestamp, this field (ud_timestamp) must be set to all zeros (NullTimestamp).

If the client chooses to supply a timestamp and the CDS server considers the timestamp invalid, the [CDS_BADCLOCK] failure status is returned.

Input/Output Parameters

The input/output parameters for cds_ModifyAttribute () are:

Progress_p: Progress record, used at the clerk for handling referrals to another server. The pr_unresolved field of the progress record contains the portion of the original fully-qualified global name of the target entry of which the attribute is to be modified.

Output Parameters

The output parameters for cds_ModifyAttribute () are:

cds_status_p

Error status return. On [CDS_UNKNOWNENTRY], the er_name field may be filled in with the last name the server successfully accessed.

Possible status codes are (non-exclusive):

 

[CDS_SUCCESS]
[CDS_VERSIONSKEW]
[CDS_ACCESSDENIED]
[CDS_CANNOTAUTHENTICATE]
[CDS_UNTRUSTEDCH]
[CDS_CLEARINGHOUSEDOWN]
[CDS_POSSIBLECYCLE]
[CDS_ROOTLOST]
[CDS_UNDERSPECIFIEDNAME]
[CDS_UNKNOWNENTRY]
[CDS_UNKNOWNATTRIBUTE]
[CDS_WRONGATTRIBUTETYPE]
[CDS_NOTSUPPORTED]
[CDS_INVALIDUPDATE]
[CDS_BADCLOCK]

cds_ReadAttribute()

[idempotent] error_status_t cds_ReadAttribute(
        [in] handle_t            h,
        [in,out] cds_Progress_t  *Progress_p,
        [in] unsigned small      type,
        [in] cds_Name_t          *att_p,
        [in] cds_Timestamp_t     *context_p,
        [in] unsigned32          max_size,
        [in] unsigned32          maybemore,
        [out] cds_RA_value_t     *value_p,
        [out] unsigned small     *wholeset_p,
        [out] cds_status_t       *cds_status_p
        );

cds_ReadAttribute () returns the values of the specified attribute. If maybemore is set to TRUE, the whole set of attributes contained in the specified entry may be returned (this behaviour is implementation-dependent).

The attribute values are returned in timestamp order (oldest timestamp first). If all values have not been returned and the client makes further calls, context_p must be set to the timestamp of the last attribute in the set returned.

The operation requires read access permission to the entry whose attribute value is to be read.

Input Parameters

The input parameters for cds_ReadAttribute () are:

h

RPC binding handle referring to the target server and clearinghouse.

type

The type of the entry for which attributes are read. Valid entry types are:

 

ET_directory
ET_object
ET_childPointer
ET_softlink
ET_clearinghouse
ET_dirOrObj

att_p

The identifier of the attribute. The nm_name field is encoded as a SimpleName_t structure with its sn_flag set to SN_objectid.

This attribute identifier may have been previously obtained through the cds_EnumerateAttributes operation.

context_p

The context (timestamp) of the last attribute in the previous call (the timestamp sm_ts returned in value_p). This is used in a sequence of calls to read the whole set of set-valued attributes. If set to NULL, the look-up operation starts at the beginning of the specified attribute value set.

max_size

The maximum size of values to be returned by value_p per call instance.

maybemore

This is a boolean flag to indicate (if set to TRUE) that the client intends to read the attribute values of the whole entry, and requests optimised use of resources.

If the clerk sets the maybemore parameter to TRUE, the CDS server may do extra work to attempt to make subsequent cds_ReadAttribute () calls for the same entry more efficient. If the buffer determined by max_size is big enough, the server may return the attribute values of the whole entry in value_p. In this case, the parameters att_p and context_p are ignored.

The clerk may set this argument to TRUE on any call, but improved performance may result only if the clerk's cache is large enough to hold all the relevant information.

CDS server implementations may not support this behaviour and instead always return only the values of a maximum of one attribute.

Input/Output Parameters

The input/output parameters for cds_ReadAttribute () are:

Progress_p: Progress record, used at the clerk for handling referrals to another server. The pr_unresolved field of the progress record contains the portion of the original fully-qualified global name of the entry whose attribute is read.

Output Parameters

The output parameters for cds_ReadAttribute () are:

value_p

A pointer to the set of the requested attribute values.

If the attribute is not present in the entry, the sm_flag of value_p has the value SM_absent, and the set contents are NULL.

An empty set-valued attribute is indicated by the sm_flag having the value SM_present, and the set contents being NULL.

The buffer that value_p points to must not exceed max_size.

wholeset_p

Not supported (reserved for future use).

cds_status_p

Error status return. On [CDS_UNKNOWNENTRY], the er_name field may be filled in with the last name the server successfully accessed.

Possible status codes are (non-exclusive):

 

[CDS_SUCCESS]
[CDS_NONSRESOURCES]
[CDS_VERSIONSKEW]
[CDS_ACCESSDENIED]
[CDS_CANNOTAUTHENTICATE]
[CDS_UNTRUSTEDCH]
[CDS_CLEARINGHOUSEDOWN]
[CDS_POSSIBLECYCLE]
[CDS_ROOTLOST]
[CDS_UNDERSPECIFIEDNAME]
[CDS_UNKNOWNENTRY]
[CDS_UNKNOWNATTRIBUTE]
[CDS_WRONGATTRIBUTETYPE]
[CDS_NOTLINKED]
[CDS_DANGLINGLINK]
[CDS_NAMESERVERBUG]

cds_ResolveName()

[idempotent] error_status_t cds_ResolveName(
        [in] handle_t            h,
        [in,out] cds_Progress_t  *Progress_p,
        [out] cds_status_t       *cds_status_p
        );

cds_ResolveName () follows a chain of soft links until it reaches an entry that is not a soft link. It returns the fully-qualified global name of that entry so that future calls by the client may use the direct name without incurring the overhead of following the link.

If the target of any of the chain of soft links followed does not exist, the [CDS_DANGLINGLINK] failure status is returned.

This operation requires read access permission to each of the soft links in the chain.

Input Parameters

The input parameters for cds_ResolveName () are:

h: RPC binding handle referring to the target server and clearinghouse.

Input/Output Parameters

The input/output parameters for cds_ResolveName () are:

Progress_p: Progress record, used at the clerk for handling referrals to another server. The pr_unresolved field of the progress record contains the portion of the original fully-qualified global name of the soft link to be resolved.

Output Parameters

The output parameters for cds_ResolveName () are:

cds_status_p

Error status return. On [CDS_UNKNOWNENTRY], the er_name field may be filled in with the last name the server successfully accessed.

Possible status codes are (non-exclusive):

 

[CDS_SUCCESS]
[CDS_VERSIONSKEW]
[CDS_ACCESSDENIED]
[CDS_CANNOTAUTHENTICATE]
[CDS_UNTRUSTEDCH]
[CDS_CLEARINGHOUSEDOWN]
[CDS_POSSIBLECYCLE]
[CDS_ROOTLOST]
[CDS_UNDERSPECIFIEDNAME]
[CDS_UNKNOWNENTRY]
[CDS_NOTLINKED]
[CDS_DANGLINGLINK]

cds_Solicit()

[broadcast,maybe] void cds_Solicit(
        [in] handle_t  h
        );

cds_Solicit () is used to provoke advertisement and carries no information of its own. Therefore it has the very simple structure of just the operation header.

No permissions are required for the operation.

Input Parameters

The input parameters for cds_Solicit () are:

h: RPC binding handle referring to the target.

cds_SolicitServer()

[idempotent] error_status_t cds_SolicitServer(
        [in] handle_t           h,
        [out] cds_FullName_t    *cellname_p,
        [out] uuid_t            *cell_diruid_p,
        [in,out,ptr] cds_CHP_t  *nscle_p
        );

cds_SolicitServer () is a directed solicitation request to obtain availability information about clearinghouses of a particular CDS server. The data structures in the response message (output parameters) are similar to those transmitted in the cds_Advertise () operation.

No permissions are required for the operation.

Input Parameters

The input parameters for cds_SolicitServer () are:

h: RPC binding handle referring to the target server.

Input/Output Parameters

The input/output parameters for cds_SolicitServer () are:

nscle_p

If provided as an input parameter, the information contained is a list of requested clearinghouses.

The output parameter contains the list of available clearinghouses at the server, including its UUIDs, fully-qualified global name, and exported protocol towers. The rp_type flag of this data structure determines the replica type.

Output Parameters

The output parameters for cds_SolicitServer () are:

cellname_p: The fully-qualified global name of the local cell.
cell_diruid_p: The UUID of the cell name space.

cds_TestAttribute()

[idempotent] error_status_t cds_TestAttribute(
        [in] handle_t            h,
        [in,out] cds_Progress_t  *Progress_p,
        [in] unsigned small      type,
        [in] cds_Name_t          *att_p,
        [in] cds_AtomicValue_t   *value_p,
        [out] unsigned small     *result_p,
        [out] cds_status_t       *cds_status_p
        );

cds_TestAttribute () returns a boolean value in result_p which is TRUE if one of the following is true:

The specified attribute is single attribute and its value matches the client-specified value.
The specified attribute is a set-valued attribute and it contains the client-specified value as one of its members.

If the attribute is not present in the entry, the operation returns FALSE.

The operation requires read or test access permission to the entry whose attribute is to be tested.

Input Parameters

The input parameters for cds_TestAttribute () are:

h

RPC binding handle referring to the target server and clearinghouse.

type

The type of the entry for which attributes are tested. Valid entry types are:

 

ET_directory
ET_object
ET_childPointer
ET_softlink
ET_clearinghouse
ET_dirOrObj

att_p

The identifier of the attribute. The nm_name field is encoded as a SimpleName_t structure with its sn_flag set to SN_objectid.

value_p

The attribute value to be tested. The data in this operation parameter is a discriminated union, consisting of a syntax identifier and value.

Input/Output Parameters

The input/output parameters for cds_TestAttribute () are:

Progress_p: Progress record, used at the clerk for handling referrals to another server. The pr_unresolved field of the progress record contains the portion of the original fully-qualified global name of the entry for which an attribute value is tested.

Output Parameters

The output parameters for cds_TestAttribute () are:

result_p

The boolean value indicating the result of the test operation.

cds_status_p

Error status return. On [CDS_UNKNOWNENTRY], the er_name field may be filled in with the last name the server successfully accessed.

Possible status codes are (non-exclusive):

 

[CDS_SUCCESS]
[CDS_VERSIONSKEW]
[CDS_ACCESSDENIED]
[CDS_CANNOTAUTHENTICATE]
[CDS_UNTRUSTEDCH]
[CDS_CLEARINGHOUSEDOWN]
[CDS_POSSIBLECYCLE]
[CDS_ROOTLOST]
[CDS_UNDERSPECIFIEDNAME]
[CDS_UNKNOWNENTRY]
[CDS_NOTLINKED]
[CDS_DANGLINGLINK]

Please note that the html version of this specification may contain formatting aberrations. The definitive version is available as an electronic publication on CD-ROM from The Open Group.

Contents

Next section

Index