Common Data Formats

The types and concepts that appear repeatedly throughout the rad protocol are described in this section.

Operations

The various operations one can perform against the server are communicated with an operation code.

Table A-1 OP-CODE Description

0
    OC-INVOKE
1
    OC-GETATTR
2
    OC-SETATTR
3
    OC-LOOKUP
4
    OC-DEFINE
5
    OC-LIST
6
    OC-SUB
7
    OC-UNSUB

Errors

Errors in the rad protocol are communicated by an error code, and optionally structured error data.

Table A-2 ERROR-CODE Description

0
    EC-OK
1
    EC-OBJECT
2
    EC-NOMEM
3
    EC-NOTFOUND
4
    EC-PRIV
5
    EC-SYSTEM
6
    EC-EXISTS
7
    EC-MISMATCH
8
    EC-ILLEGAL

For object-specific errors, EC-OBJECT, the format of the structured data is defined by the object's interface definition. For the remainder, save for EC-OK (which indicates success), the format is defined during the initial connection handshake. See Connection Initialization.

Time

Times are represented in the rad protocol, as seconds and nanoseconds offset from the epoch (January 1, 1970 UTC).

Note that the accuracy of such time data is determined by its context. In nearly all cases, the full nanosecond precision is only relevant when compared to time data obtained from the same host.

Table A-3 TIME-DATA

Object Names

rad object names are structured, consisting of a domain and one or more key-value pairs. When an object name or pattern needs to be represented in the rad protocol, this structure is flattened to a canonical string format. This string format consists of the domain, followed by a colon (':'), followed by comma-separated key-value pairs. Each key-value pair consists of the name, followed by an equals sign ('='), followed by the value.

Because keys and values may contain the special characters '=' or ',', a quoting algorithm is applied when constructing the string. The substitutions listed in the following table are applied to keys and values.

Table A-4 Object Name Escaping

Backslashes are found only as part of quoted characters, and commas and equals signs, when present, always have their special meaning. Object names that use no special characters are passed through unchanged. These facts can be used to simplify parsing or preprocessing of string-formatted object names.

Table A-5 NAME-DATA

For example, an object name in the domain com.example with the following keys and values:

would be represented by the string com.example:directory=C:\S,first\Clast=Doe\CJohn.

ADR Data

Central to the rad protocol is the communication of data defined by ADR. Most ADR primitives map directly to XDR types:

Table A-6 Primitive ADR to Wire Type Mapping

Optional ADR data of any type is represented as XDR optional data.

Table A-7 OPTIONAL-DATA Description

Array data is communicated as an XDR array of the element data represented by an XDR unsigned int whose value is the number of array elements followed by that number of element data.

Table A-8 ARRAY-DATA Description

Structure data is communicated by communicating each structure field in the order they are defined. This may consist of a mixture of nullable and non-nullable data.

Table A-9 STRUCT-DATA

Enumeration data is communicated as an XDR unsigned int whose value is the 1-based index into the list of enumerated values, that is, 1 would be the first enumerated value, n would be the nth enumerated value. A value of 0 represents the fallback value. For enumerations without a fallback value, the 0 value is unused.

Table A-10 ENUM-DATA Description

Union data is communicated as an XDR unsigned int whose value is the 1-based index into the list of union arms. A value of 0 represents the default arm. When a non-default arm is selected, the arm is followed by that arm's data. When the default arm is selected, it is first followed by the discriminant data value and then is followed by the default arm's data.

Table A-11 UNION-DATA (Non-Default) Description

Table A-12 UNION-DATA (Default) Description

ADR types

As discussed in ADR Data, the ADR data communicated by the rad protocol has a structure determined by its type. Before that data can be communicated to the client, however, the types themselves must be communicated.

For efficiency, type data is communicated using a system of type spaces and type references. A type space is an array of type definitions that is referenced by a protocol-defined set of consumers. A consumer referring to a type will use a type reference, which points to either a primitive type or to an element of the type space.

Both type references and type spaces refer to the various types by using an integral type code.

Table A-13 TYPE-CODE

0
    TC-VOID
1
    TC-BOOLEAN
2
    TC-INTEGER
3
    TC-UINTEGER
4
    TC-LONG
5
    TC-ULONG
6
    TC-FLOAT
7
    TC-DOUBLE
8
    TC-TIME
9
    TC-STRING
10
    TC-OPAQUE
11
    TC-SECRET
12
    TC-NAME
13
    TC-ENUM
14
    TC-ARRAY
15
    TC-STRUCT
16
    TC-UNION

A type reference consists of an XDR int whose value is one of the type constants listed in the table. If the type is an enum, array, union, or struct, the type reference also includes an XDR int whose value is an index into the current type space as listed in the following tables.

Table A-14 TYPEREF (Basic Type)

Table A-15 TYPEREF (Derived Type)

A type space is a topologically sorted array of type definitions. A derived type may reference only derived types defined earlier in the type space. That is, a type reference used by the type at index X may reference only a primitive type or a derived type at index less than X. Recursively defined types are not supported.

Apart from a common distinguishing type code, each derived type is defined differently. Arrays are the simplest. An array definition consists of only a reference to the element type.

Table A-16 ARRAY-TYPE

A structure type definition consists of a name and an array of field definitions. The order in which the fields are specified in STRUCT-TYPE is the order used to serialize the fields in STRUCT-DATA.

Table A-17 FIELD-TYPE

Table A-18 STRUCT-TYPE

A union type definition consists of a name, a reference to the discriminant type, optionally a default arm specification, and an array of arm definitions. The arm index referenced by UNION-DATA is an index into the array of arms defined by the corresponding UNION-TYPE.

Table A-19 ARM-TYPE

Table A-20 UNION-TYPE (Without Default Arm)

Table A-21 UNION-TYPE (With Default Arm)

Lastly, an enum type definition consists of a name, an optional fallback value, and a list of enumeration values. The value index referenced by ENUM-DATA is an index into the array of values defined by the corresponding ENUM-TYPE.

Table A-22 VALUE-TYPE

Table A-23 ENUM-TYPE

The type space itself is an array. Each element is one of these four type definitions (ARRAY-TYPE, STRUCT-TYPE, UNION-TYPE, or ENUM-TYPE).

Table A-24 TYPESPACE

Interface Definitions

The ultimate description of the interactions permitted with a particular object is its interface definition. An interface definition contains many elements: an API name, a list of versioned interface names the interface supports, and definitions of the interface's attributes, methods, and events.

Each interface name has a set of stabilities and versions.

Table A-25 STABILITY-CODE

1
    SC-PRIVATE
2
    SC-UNCOMMITTED
3
    SC-COMMITTED

Table A-26 VERSION-DATA

Table A-27 INTERFACENAME-DATA

An attribute consists of a name, stability, various flags, a type, and separate, optional read and write error types.

Table A-28 ATTRIBUTE-TYPE

A method resembles an attribute. It has a name, stability, a result type, only a single optional error type, and an array of argument definitions.

Table A-29 ARGUMENT-TYPE

Table A-30 METHOD-TYPE

An event consists only of a name, stability, and type.

Table A-31 EVENT-TYPE

An interface definition combines all of the described elements.

Table A-32 INTERFACE-TYPE