Module Netxdr

module Netxdr: sig .. end

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.

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

type xdr_value = 

val xv_true : xdr_value

val xv_false : xdr_value

val xv_none : xdr_value

val xv_some : xdr_value -> 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 Netxdr_mstring.mstring.

The term X_direct(t,read,write,size,expand) 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.

type xdr_type_term = 

type xdr_type 

type xdr_type_term_system = (string * xdr_type_term) list 

type xdr_type_system 

val x_bool : xdr_type_term

val x_optional : xdr_type_term -> xdr_type_term

val x_opaque_max : xdr_type_term

val x_string_max : xdr_type_term

val x_mstring_max : string -> xdr_type_term

val x_array_max : xdr_type_term -> xdr_type_term

exception Dest_failure

val dest_xv_int : xdr_value -> Netnumber.int4

val dest_xv_uint : xdr_value -> Netnumber.uint4

val dest_xv_hyper : xdr_value -> Netnumber.int8

val dest_xv_uhyper : xdr_value -> Netnumber.uint8

val dest_xv_enum : xdr_value -> string

val dest_xv_enum_fast : xdr_value -> int

val dest_xv_float : xdr_value -> Netnumber.fp4

val dest_xv_double : xdr_value -> Netnumber.fp8

val dest_xv_opaque : xdr_value -> string

val dest_xv_string : xdr_value -> string

val dest_xv_mstring : xdr_value -> Netxdr_mstring.mstring

val dest_xv_array : xdr_value -> xdr_value array

val dest_xv_array_of_string_fast : xdr_value -> string array

val dest_xv_struct : xdr_value -> (string * xdr_value) list

val dest_xv_struct_fast : xdr_value -> xdr_value array

val dest_xv_union_over_int : xdr_value -> Netnumber.int4 * xdr_value

val dest_xv_union_over_uint : xdr_value -> Netnumber.uint4 * xdr_value

val dest_xv_union_over_enum : xdr_value -> string * xdr_value

val dest_xv_union_over_enum_fast : xdr_value -> int * xdr_value

val dest_xv_void : xdr_value -> unit

val map_xv_enum_fast : xdr_type -> xdr_value -> int32

val map_xv_struct_fast : xdr_type -> xdr_value -> xdr_value array

val map_xv_union_over_enum_fast : xdr_type -> xdr_value -> int * int32 * xdr_value

exception Xdr_format of string

exception Xdr_format_message_too_long of xdr_value

exception Xdr_failure of string

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.

val validate_xdr_type : xdr_type_term -> xdr_type

val validate_xdr_type_system : xdr_type_term_system -> xdr_type_system

val params : xdr_type -> string list

Get the unvalidated version back:

• Note that X_type constructions are always resolved

val xdr_type_term : xdr_type -> xdr_type_term

val xdr_type_term_system : xdr_type_system -> xdr_type_term_system

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.

val expanded_xdr_type : xdr_type_system -> xdr_type_term -> xdr_type

val expanded_xdr_type_term : xdr_type_term_system -> xdr_type_term -> xdr_type_term

val are_compatible : xdr_type -> xdr_type -> bool

val value_matches_type : xdr_value ->
       xdr_type -> (string * xdr_type) list -> bool

Packing and unpacking

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.

type encoder = Netxdr_mstring.mstring list -> Netxdr_mstring.mstring list 

type decoder = Stdlib.Bytes.t -> int -> int -> Stdlib.Bytes.t * int 

val pack_xdr_value : ?encode:(string * encoder) list ->
       xdr_value ->
       xdr_type ->
       (string * xdr_type) list -> (Stdlib.Bytes.t -> unit) -> unit

val pack_xdr_value_as_bytes : ?rm:bool ->
       ?encode:(string * encoder) list ->
       xdr_value ->
       xdr_type -> (string * xdr_type) list -> Stdlib.Bytes.t

val pack_xdr_value_as_string : ?rm:bool ->
       ?encode:(string * encoder) list ->
       xdr_value ->
       xdr_type -> (string * xdr_type) list -> string

val pack_xdr_value_as_mstrings : ?rm:bool ->
       ?encode:(string * encoder) list ->
       xdr_value ->
       xdr_type ->
       (string * xdr_type) list -> Netxdr_mstring.mstring list

type xdr_value_version = [ `Ocamlrpcgen | `V1 | `V2 | `V3 | `V4 ] 

val unpack_xdr_value : ?pos:int ->
       ?len:int ->
       ?fast:bool ->
       ?prefix:bool ->
       ?mstring_factories:Netxdr_mstring.named_mstring_factories ->
       ?xv_version:xdr_value_version ->
       ?decode:(string * decoder) list ->
       Stdlib.Bytes.t ->
       xdr_type -> (string * xdr_type) list -> xdr_value

val unpack_xdr_value_l : ?pos:int ->
       ?len:int ->
       ?fast:bool ->
       ?prefix:bool ->
       ?mstring_factories:Netxdr_mstring.named_mstring_factories ->
       ?xv_version:xdr_value_version ->
       ?decode:(string * decoder) list ->
       Stdlib.Bytes.t ->
       xdr_type -> (string * xdr_type) list -> xdr_value * int

val unpack_xdr_value_str : ?pos:int ->
       ?len:int ->
       ?fast:bool ->
       ?prefix:bool ->
       ?mstring_factories:Netxdr_mstring.named_mstring_factories ->
       ?xv_version:xdr_value_version ->
       ?decode:(string * decoder) list ->
       string ->
       xdr_type -> (string * xdr_type) list -> xdr_value * int