module Xdr

This module supports the "external data representation", or XDR for short. XDR is a means to pack structured values as strings and it serves to transport such values across character streams even between computers with different architectures.

XDR values must be formed according to an XDR type. Such types are usually written in a notation that is close to the C notation of structured types. There are some important details where XDR is better than C:

• direct support for strings
• arrays may have fixed or variable length
• unions must have a discriminator
• no pointers. The notation *t is allowed, but means something different, namely "t option" in O'Caml notation.
• recursive types are possible and behave like recursive types in O'Caml. For example,

         struct *list {
           int value;
           next list;
         }

  is a list of integer values and equivalent to

         type intlist = intlist_el option
          and intlist_el = { value : int; next : intlist }

See RFC 1014 for details about XDR.

This module defines:

• XDR types
• XDR type terms
• XDR type systems
• XDR type term systems

In "type terms" you can see the components from which the type has been formed, while a "type" is an opaque representation that has been checked and for that some preprocessing has been done.

A "type system" is a collection of several types that have names and that can refer to previously defined types (i.e. a sequence of "typedef"s). As with simple types, there is an extensive and an opaque representation.

A typical way of using this module is to define an "XDR type term system" by simply writing an O'Caml expression. After that, this system is validated and you get the "type system". From now on, you can refer to the types defined in the system by name and get the corresponding "XDR types". Once you have an XDR type you can use it to pack or unpack an XDR value.

Terms that describe possible XDR types:

• X_int: integer (32 bit)
• X_uint: unsigned integer
• X_hyper: hyper (64 bit signed integer)
• X_uhyper: unsigned hyper
• X_enum [x1,i1; ...]: enum { x1 = i1, ... }
• X_float: float (32 bit fp number)
• X_double: double (64 bit fp number)
• X_opaque_fixed n: opaque[n]
• X_opaque n: opaque<n>
• X_string n: string<n>
• X_mstring(name,n): _managed string<n> (see below)
• X_array_fixed (t,n): t[n]
• X_array (t,n): t<n>
• X_struct [x1,t1;...]: struct { t1 x1; ...}
• X_union_over_int ([n1,t1;...], None): union switch(int) {case n1: t1; ...}
• X_union_over_int ([n1,t1;...], Some t): union switch(int) {case n1: t1; ...; default t}
• X_union_over_uint ([n1,t1;...], None): union switch(unsigned int) {case n1: t1; ...}
• X_union_over_uint ([n1,t1;...], Some t): union switch(unsigned int) {case n1: t1; ...; default t}
• X_union_over_enum (e, [n1,t1;...], None): union switch(e) {case n1:t1; ...} where e is an enumeration type
• X_union_over_enum (e, [n1,t1;...], Some t): union switch(e) {case n1:t1; ...; default t} where e is an enumeration type
• X_void: void

The X_type constructor is only useful for types interpreted relative to a type system. Then it refers to a named type in this system.

The X_param constructor includes a reference to an arbitrary type which must first be given when packing or unpacking values. (A "lazy" type reference.) Additionally, the values for parameters may be encrypted or decrypted.

Example how to define a recursive type:

X_rec ("a", X_array ( X_struct ["value", X_int; "next", X_refer "a"], 1))

Managed strings are represented as X_mstring(name,n). The name refers to the preferred factory for managed strings (needs to be passed to the XDR unpacker). Values for managed strings are objects of type Xdr_mstring.mstring.

The term X_direct(t,read,write,size) is generated by ocamlrpcgen at positions suitable for direct mapping. In this case, the XDR byte representation is directly mapped to the final Ocaml value bypassing the intermediate representation defined in this module. t is the mapped type. The function read is called as read s cursor len in order to map the XDR bytes at !cursor in s. The cursor must be advanced to the end position. len is the number of valid bytes in s (i.e. s.(len-1) is the last one). The result of read is an arbitrary exception which needs to be postprocessed by ocamlrpcgen-generated code. The function write is called as write x s cursor: The value encapsulated in exception x is written to string s at position cursor. Like for read the cursor is advanced by the number of written bytes. There must be enough space in s. The function size can be used to determine the number of written bytes beforehand.

Values possible for XDR types. This is straight-forward, except the "_fast" variants:

You must use these two functions to obtain validated types and type systems. They fail with "validate_xdr_type" resp. "validate_xdr_type_system" if the parameters are incorrect.

Get the unvalidated version back:

• Note that X_type constructions are always resolved

You can expand any type term relative to a (validated) type system. For example: expanded_xdr_type sys1 (X_type "xy") extracts the type called "xy" defined in sys1. Expansion removes all X_type constructions in a type term.

pack_xdr_value v t p print: Serialize v into a string conforming to the XDR standard where v matches t. In p the parameter instances are given. All parameters must be given, and the parameters must not contain parameters themselves. The fourth argument, print, is a function which is evaluated for the pieces of the resultant string. You can use pack_xdr_value_as_string to get the whole string at once.

unpack_xdr_value s t p: Unserialize a string to a value matching t. If this operation fails you get an Xdr_format exception explaining what the reason for the failure is. Mostly the cause for failures is that t isn't the type of the value. Note that there are some implementation restrictions limiting the number of elements in array, strings and opaque fields. If you get such an error this normally still means that the value is not of the expected type, because these limits have no practical meaning (they are still higher than the usable address space).

Encryption: The encode and decode functions can be used to encrypt/decrypt parameters (placeholders in the type marked with X_param pname for a parameter name pname). The encode argument may list for each parameter an encoding function:

encode = [ pname1, encoder1; pname2, encoder2; ... ]

The functions encoder are called with the XDR-packed parameter value, and return the encrypted value.

Likewise, the decode argument may list for each parameter a decoding function:

decode = [ pname1, decoder1; pname2, decoder2; ... ]

The call style of the decoder functions is a bit more complicated, though. They are called as

let (xdr_s, n) = decoder s pos len

meaning that the decoder starts decoding at position pos of string s, and that at most len bytes can be decoded. It returns the decoded string xdr_s (which is then unpacked), and in n the number of consumed input bytes is returned.

Exceptions raised in encoders or decoders fall through unmodified.