CDS IDL Definitions

cds_clerkserver.idl

The remote interface for the transaction protocol.

cds_solicit.idl

The remote interface for the solicitation protocol.

cds_types.idl

Header file for basic CDS types.

id_base.idl

Base type definitions for identities.

Notes:

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.

cds_clerkserver.idl

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

}

cds_solicit.idl

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

}

cds_types.idl

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;

}

id_base.idl

/* 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.