Previous section.

DCE 1.1: Directory Services
Copyright © 1997 The Open Group

CDS IDL Definitions

This appendix gives the IDL specification of the CDS remote interface, including:

The remote interface for the transaction protocol.

The remote interface for the solicitation protocol.

Header file for basic CDS types.

Base type definitions for identities.


  1. The listings of *.idl definitions in this appendix provide supplementary information. In particular, the ordering of operations is significant for conforming implementations. For further information about the semantics of operations and encodings refer to CDS Protocol Encodings and IDL Notation of CDS Operations .

  2. The cds_clerkserver.idl definition contains the following operations that are not further specified in this document:
    cds_AddReplica cds_AllowClearinghouses cds_Combine cds_DisallowClearinghouses cds_DoUpdate cds_LinkReplica cds_ModifyReplica cds_NewEpoch cds_RemoveReplica cds_Skulk cds_TestGroup

    These operations are used by the CDS replication service that is not specified in this document. However, in order to preserve the ordering of IDL operations, it is necessary to maintain these operations in the *.idl definition.


[uuid(257df1c9-c6d3-11ca-8554-08002b1c8f1f), version(1.0)]

interface cds_clerkserver

{ import "dce/cds_types.idl"; import "dce/id_base.idl";

error_status_t cds_AddReplica( [in] handle_t h, [in] cds_FullName_t *directory_p, [in] unsigned small type, [out] cds_status_t *cds_status_p );

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

error_status_t cds_Combine( [in] handle_t h, [in] uuid_t *dir_p, [in] cds_Timestamp_t *skulk_p, [in] cds_Timestamp_t *allupto_p, [in] uuid_t *epoch_p, [in] cds_FullName_t *to_p, [out] uuid_t *next_p, [out] cds_status_t *cds_status_p );

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 );

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 );

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 );

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 *acutal_ts_p, [out] cds_status_t *cds_status_p );

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

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

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

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

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

[idempotent] error_status_t cds_DoUpdate( [in] handle_t h, [in] uuid_t *epoch_p, [in] cds_UpdatePkt_t *update_p, [out] cds_status_t *cds_status_p );

[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 );

[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 );

[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 );

[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 );

[idempotent] error_status_t cds_LinkReplica( [in] handle_t h, [in,out] cds_Progress_t *Progress_p, [in] uuid_t *directory_p, [in] cds_Update_t *update_p, [out] uuid_t *epoch_p, [out] uuid_t *ring_p, [out] cds_Version_t *rpversion_p, [out] cds_status_t *cds_status_p );

[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 );

[idempotent] error_status_t cds_ModifyReplica( [in] handle_t h, [in] uuid_t *dir_p, [in] cds_Update_t *update_p, [out] cds_status_t *cds_status_p );

error_status_t cds_NewEpoch( [in] handle_t h, [in] cds_FullName_t *dirname_p, [in] cds_Set_t *readonlies_p, [in] cds_Set_t *secondaries_p, [out] cds_status_t *cds_status_p );

const unsigned small RA_none = 1; const unsigned small RA_single = 2; const unsigned small RA_set = 3; const unsigned small RA_wholeSet = 4;

typedef struct { cds_Name_t name; union switch (unsigned small type) { case RA_none: ; case RA_single: [ptr] cds_SetMember_t *single_p; case RA_set: [ptr] cds_Set_t *set_p; } value; } cds_WE_entry_t;

typedef struct { unsigned small numberOfAttributes; [size_is(numberOfAttributes)] cds_WE_entry_t entry[]; } cds_WholeEntry_t;

typedef union switch (unsigned small returningToClerk) { case RA_none: ; case RA_single: [ptr] cds_SetMember_t *value_single_p; case RA_set: [ptr] cds_Set_t *value_set_p; case RA_wholeSet: [ptr] cds_WholeEntry_t *wholeEntry_p; } cds_RA_value_t;

[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 );

error_status_t cds_RemoveReplica( [in] handle_t h, [in] cds_FullName_t *directory_p, [out] cds_status_t *cds_status_p );

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

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

[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 );

[idempotent] error_status_t cds_TestGroup( [in] handle_t h, [in,out]cds_Progress_t *Progress_p, [in] cds_FullName_t *member_p, [in,out] uuid_t *loop_p, [in,out] unsigned small *direct_p, [out] unsigned small *result_p, [in,out,ptr] cds_TimeoutP_t *outTimeout_p, [out] cds_status_t *cds_status_p );



[uuid(d5579459-8bca-11ca-b771-08002b1c8f1f), version(1.0)]
interface cds_solicit
import "cds_types.idl";

typedef [ref]cds_ReplicaPointer_t *cds_ReplicaPointerP_t;

typedef struct { unsigned short ch_length; [size_is(ch_length)] cds_ReplicaPointerP_t ch_members[]; } cds_CH_t;

typedef [ptr]cds_CH_t *cds_CHP_t;

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

[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);

[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);



interface cds_types

#ifdef DCE_SEC import "dce/aclbase.idl"; #endif

const small VT_none = 0; const small VT_long = 1; const small VT_short = 2; const small VT_small = 3; const small VT_uuid = 4; const small VT_Timestamp = 5; const small VT_Timeout = 6; const small VT_Version = 7; const small VT_char = 8; const small VT_byte = 9; const small VT_ReplicaPointer = 10; const small VT_GroupMember = 11; const small VT_ParentPointer = 12; const small VT_FullName = 13; const small VT_CHDirectory = 14; const small VT_ASN1 = 15; const small VT_DACL = 16; const small VT_gdaPointer = 18;

typedef small ValueType_t;

/* * CDS timestamp - 6 byte node id followed by time based on smithsonian * zero */ typedef struct { byte ts_node[6]; unsigned hyper int ts_time; } cds_Timestamp_t;

/* * 2 utc values. First is absolute time, second is relative */ typedef struct { byte to_expire[16]; byte to_extend[16]; } cds_Timeout_t;

typedef [ptr]cds_Timeout_t *cds_TimeoutP_t;

/* * Can be used for software version numbers */ typedef struct { unsigned small int ver_major; unsigned small int ver_minor; } cds_Version_t;

/* * Represents Simplenames, attributenames and class values as input to * RPC routines. These names are passed in their internal opq format. * within the nm_name array. */ typedef struct { unsigned short int nm_length; [length_is(nm_length)] byte nm_name[257]; } cds_Name_t;

/* * The global root and the string representation of the pathname. * CDS server-server operations may use a directory uuid in the fn_root * and the fn_name is the entry name relative to fn_root (ie, not global) * fn_name does not include terminating null */ typedef struct { uuid_t fn_root; long int fn_length; [length_is(fn_length)] char fn_name[1023]; } cds_FullName_t;

/* * Error status return. On Unknownentry, the er_name may be filled in * with the last name the server successfully accessed. */ typedef struct { unsigned long int er_status; [ptr]cds_FullName_t *er_name; } cds_status_t;

/* * Internal CDS structure that describes the replicas of directory * * const small RT_master = 1; * const small RT_readOnly = 3; * const small RT_gda = 4; */ typedef struct { unsigned small int rp_type; uuid_t rp_chid; cds_FullName_t rp_chname; unsigned long int rp_length; [size_is(rp_length)] byte rp_towers[]; } cds_ReplicaPointer_t;

/* * Internal CDS structure to describe the members of a CDS group * Members may by other group names in which isaGroup would be true */ typedef struct { boolean gm_isaGroup; cds_FullName_t gm_member; } cds_GroupMember_t;

/* * Internal CDS structure that describes the parent of a directory * The timeout value is used to update replica pointers in the * child ptr. */ typedef struct { uuid_t pp_parentID; cds_Timeout_t pp_timeout; cds_FullName_t pp_myName; } cds_ParentPointer_t;

/* * Uppointers to the GDA */ typedef struct { cds_Timeout_t gp_timeout; cds_ReplicaPointer_t gp_replica; } cds_gdaPointer_t;

/* * Internal CDS attribute that defines the directories within a * clearinghouse */ typedef struct { uuid_t cp_dirID; cds_FullName_t cp_directory; } cds_CHDirectory_t;

/* * Structure for transporting opaque variable length user data */ typedef struct { unsigned short int op_length; [size_is(op_length)] byte op_array[]; } cds_OpenByte_t;

/* * Structure for transporting char variable length user data */ typedef struct { unsigned short int op_length; [size_is(op_length)] char op_array[]; } cds_OpenChar_t;

/* All the data types CDS recognizes */ typedef union switch (ValueType_t av_valuetype) av_val { case VT_none: ; case VT_long: long int av_long; case VT_short: short int av_short; case VT_small: small int av_small; case VT_uuid: uuid_t av_uuid; case VT_Timestamp: cds_Timestamp_t av_timestamp; case VT_Timeout: cds_Timeout_t av_timeout; case VT_Version: cds_Version_t av_version; case VT_char: [ptr]cds_OpenChar_t *av_char_p; case VT_ASN1: case VT_byte: [ptr]cds_OpenByte_t *av_byte_p; /* The remaining types are for internal CDS use only */ case VT_ReplicaPointer: [ptr]cds_ReplicaPointer_t *av_rp_p; case VT_GroupMember: [ptr]cds_GroupMember_t *av_gm_p; case VT_ParentPointer: [ptr]cds_ParentPointer_t *av_pp_p; case VT_FullName: [ptr]cds_FullName_t *av_fullname_p; case VT_CHDirectory: [ptr]cds_CHDirectory_t *av_cp_p; #ifdef DCE_SEC case VT_DACL: [ptr]sec_acl_t *av_acl_p; #endif case VT_gdaPointer: [ptr]cds_gdaPointer_t *av_gda_p; } cds_AtomicValue_t;

/* * Set member contains a present/absent flag, timestamp member * was created and the value * The flag is actually a bitmask with only bit 0 currently in use. * const small SM_present=1; * const small SM_absent=0; */ typedef struct { unsigned small int sm_flag; cds_Timestamp_t sm_ts; cds_AtomicValue_t sm_value; } cds_SetMember_t;

/* * Sets describe single or set valued attributes. They contain a * a list of members * const small AT_none=1; * const small AT_single=2; * const small AT_set=3; */ typedef struct { unsigned small int set_type; unsigned short int set_length; [size_is(set_length)] cds_SetMember_t set_members[]; } cds_Set_t; typedef [ptr]cds_Set_t *cds_SetP_t;

/* * Progress record is used to direct the clerk from one server * to another. * Flags is a bitmask. * const small PR_done=1; Got results * const small PR_up =2; returning ptr up the tree * const small PR_linked=4; Link was found in name * const small PR_hitLink=8; Link just found, new name returned * const small PR_ignoreState=16; ignore directory state * const small PR_directory =32; */ typedef struct { unsigned small int pr_flags; [ptr]cds_Timeout_t *pr_timeout; cds_FullName_t pr_unresolved; cds_FullName_t pr_resolved; [ptr]cds_Set_t *pr_replicas_p; } cds_Progress_t;

/* * Update an attribute * const small UD_present=1; * const small UD_absent=2; */ typedef struct { small int ud_operation; cds_Timestamp_t ud_timestamp; unsigned small int ud_type; /* attribute type */ byte ud_attribute[33]; cds_AtomicValue_t ud_value; } cds_Update_t;

/* * Structure used to bundle multiple updates to one entry. Used in * DoUpdate function. Name is relative to a directory. * const small int ET_directory=1; * const small int ET_object=2; * const small int ET_childPointer=3; * const small int ET_softlink=4; * const small int ET_clearinghouse=5; * const small int ET_anyDirectName=6; * const small int ET_firstLink=7; * const small int ET_dirOrObj=8; */ typedef struct { cds_FullName_t pkt_name; cds_Timestamp_t pkt_cts; small int pkt_type; /* EntryType */ unsigned small int pkt_cnt; [size_is(pkt_cnt)] cds_Update_t pkt_data[]; } cds_UpdatePkt_t;



/* Identity base type definitions

[ uuid(47EAABA3-3000-0000-0D00-01DC6C000000) ]

interface sec_id_base {

import "dce/nbase.idl";

/* s e c _ i d _ t * * A sec_id_t is the basic unit for identifying principals or groups etc. * It contains the uuid (object handle for the identity) and an optional * printstring name. * * This datatype requires a destructor function since the printstring * name is dynamically allocated. Generally this datatype is embedded * in other datatypes (like acl's) which have their own destructor which * will release the printstring storage as well. */ typedef struct { uuid_t uuid; [ string,ptr ] char *name; } sec_id_t;

/* s e c _ i d _ f o r e i g n _ t * * A foreign id (sec_id_foreign_t) is an identity from a foreign realm. * It contains a sec_id_t for the foreign user or group and a sec_id_t * for the foreign realm. */ typedef struct { sec_id_t id; sec_id_t realm; } sec_id_foreign_t;

/* Set of groups all associated with the same foreign cell */ typedef struct { sec_id_t realm; unsigned16 num_groups; [size_is(num_groups), ptr] sec_id_t *groups; } sec_id_foreign_groupset_t;

/* s e c _ i d _ p a c _ f o r m a t _ t * * A format label to indicate which EPAC format is being used. */ typedef enum { sec_id_pac_format_v1 } sec_id_pac_format_t;

/* s e c _ i d _ p a c _ t (sec_id_pac_format_v1) * * A privilege attribute certificate contains the principal's identity * along with the current group and concurrent group set. The pac is * generally not directly visible to applications. It is normally included * in an authentication ticket where it appears as a sealed certificate. * Anticipating future systems that wish to extend the EPAC structure, we * include a format label (which takes the value sec_id_pac_format_t) * and we also add version specific encodings of the type. Applications * that wish to provide persistent storage of a EPAC should * use the version specific type name, applications that wish the latest * version should use the simple sec_id_pac_t generic type name. * * The pac contains an "authenticated" field which when set indicates that * the certificate was obtained from an authenticated source. When unset * the certificate should not be trusted. (The field is unset - false - * when it is obtained from the rpc_auth layer and the "assert_id" mode * was selected. This indicates that no authentication protocol was * actually used in the rpc, the identity was simply transmitted from the * caller to the callee. If an authentication protocol was used, then * the flag is set to true) */ typedef struct { sec_id_pac_format_t pac_type; boolean32 authenticated; sec_id_t realm; sec_id_t principal; sec_id_t group; unsigned16 num_groups; unsigned16 num_foreign_groups; [size_is(num_groups), ptr] sec_id_t *groups; [size_is(num_foreign_groups), ptr] sec_id_foreign_t *foreign_groups; } sec_id_pac_t, sec_id_pac_format_v1_t;

/* s e c _ i d _ p i c k l e d _ p a c _ t * * An pickled privilege attribute certificate is a labeled pac. It * contains an ndr_format_t label which describes the pickle format. * Generally a pickled pac occurs in an authentication ticket where * the data is also encrypted. */ typedef struct { ndr_format_t format_label; unsigned32 num_bytes; [size_is(num_bytes)] byte pickled_data[]; } sec_id_pickled_pac_t;


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