module Xdr:External Data Representationsig..end
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:
*t is allowed, but means something
different, namely "t option" in O'Caml notation. 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 }
This module defines:
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 integerX_hyper: hyper (64 bit signed integer)X_uhyper: unsigned hyperX_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_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 typeX_union_over_enum
(e, [n1,t1;...], Some t): union switch(e) {case n1:t1; ...; default t}
where e is an enumeration typeX_void: voidX_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 only be given while packing or unpacking values.
(A "lazy" type reference.)
Example how to define a recursive type:
X_rec ("a", X_array ( X_struct ["value", X_int; "next", X_refer "a"], 1))
type xdr_type_term =
| |
X_int |
| |
X_uint |
| |
X_hyper |
| |
X_uhyper |
| |
X_enum of |
| |
X_float |
| |
X_double |
| |
X_opaque_fixed of |
| |
X_opaque of |
| |
X_string of |
| |
X_array_fixed of |
| |
X_array of |
| |
X_struct of |
| |
X_union_over_int of |
| |
X_union_over_uint of |
| |
X_union_over_enum of |
| |
X_void |
| |
X_type of |
| |
X_param of |
| |
X_rec of |
| |
X_refer of |
type xdr_type
xdr_type_term. Note that it does not
contain X_type constructors, i.e. is completely expanded.
It is allowed that an xdr_type contains X_param constructors (parameters).
The set of occurring parameters can be determined very quickly for an
xdr_type.typexdr_type_term_system =(string * xdr_type_term) list
n must be defined
in the list before it can be used via X_type n.
It is possible to use this module without the means of type
systems, but often code is more readable if types are defined
in an environment allowing bindings to names.type xdr_type_system
val x_bool : xdr_type_termxv_true and xv_false.val x_optional : xdr_type_term -> xdr_type_termxv_none and
xv_some v.val x_opaque_max : xdr_type_termval x_string_max : xdr_type_termval x_array_max : xdr_type_term -> xdr_type_termtype xdr_value =
| |
XV_int of |
|||
| |
XV_uint of |
|||
| |
XV_hyper of |
|||
| |
XV_uhyper of |
|||
| |
XV_enum of |
|||
| |
XV_float of |
|||
| |
XV_double of |
|||
| |
XV_opaque of |
|||
| |
XV_string of |
|||
| |
XV_array of |
|||
| |
XV_struct of |
|||
| |
XV_union_over_int of |
|||
| |
XV_union_over_uint of |
|||
| |
XV_union_over_enum of |
|||
| |
XV_void |
|||
| |
XV_enum_fast of |
(* | The integer is the _position_ in the X_enum list, sorted by
enum values (ascending). For example, if we have
X_enum [ "A", 4; "B", 2; "C", 6 ]
the element "B" has the position 0, because 2 is the lowest
number | *) |
| |
XV_struct_fast of |
(* | The array elements are in the same order as declared in X_struct | *) |
| |
XV_union_over_enum_fast of |
(* | The integer is the _position_ in the X_enum list. "position"
means the same as for XV_enum_fast | *) |
val xv_true : xdr_valueval xv_false : xdr_valuex_boolval xv_none : xdr_valueval xv_some : xdr_value -> xdr_valuex_optionalexception Dest_failure
val dest_xv_int : xdr_value -> Rtypes.int4val dest_xv_uint : xdr_value -> Rtypes.uint4val dest_xv_hyper : xdr_value -> Rtypes.int8val dest_xv_uhyper : xdr_value -> Rtypes.uint8val dest_xv_enum : xdr_value -> stringval dest_xv_enum_fast : xdr_value -> intval dest_xv_float : xdr_value -> Rtypes.fp4val dest_xv_double : xdr_value -> Rtypes.fp8val dest_xv_opaque : xdr_value -> stringval dest_xv_string : xdr_value -> stringval dest_xv_array : xdr_value -> xdr_value arrayval dest_xv_struct : xdr_value -> (string * xdr_value) listval dest_xv_struct_fast : xdr_value -> xdr_value arrayval dest_xv_union_over_int : xdr_value -> Rtypes.int4 * xdr_valueval dest_xv_union_over_uint : xdr_value -> Rtypes.uint4 * xdr_valueval dest_xv_union_over_enum : xdr_value -> string * xdr_valueval dest_xv_union_over_enum_fast : xdr_value -> int * xdr_valueval dest_xv_void : xdr_value -> unitval map_xv_enum_fast : xdr_type -> xdr_value -> int32XV_enum and XV_enum_fastval map_xv_struct_fast : xdr_type -> xdr_value -> xdr_value arrayXV_struct and XV_struct_fastval map_xv_union_over_enum_fast : xdr_type -> xdr_value -> int * int32 * xdr_valueXV_union_over_enum and XV_union_over_enum_fast.
Returns the triple (k,i,x):k: Position of the selected value in the T_enum arrayi: value of the enumx: selected arm of the unionexception Xdr_format of string
exception Xdr_format_message_too_long of xdr_value
val validate_xdr_type : xdr_type_term -> xdr_typeval validate_xdr_type_system : xdr_type_term_system -> xdr_type_system
X_type constructions are always resolvedval xdr_type_term : xdr_type -> xdr_type_termval xdr_type_term_system : xdr_type_system -> xdr_type_term_systemexpanded_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_typeval expanded_xdr_type_term : xdr_type_term_system -> xdr_type_term -> xdr_type_termval are_compatible : xdr_type -> xdr_type -> boolval value_matches_type : xdr_value -> xdr_type -> (string * xdr_type) list -> boolpack_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, 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).
val pack_xdr_value : xdr_value ->
xdr_type -> (string * xdr_type) list -> (string -> unit) -> unitval pack_xdr_value_as_string : ?rm:bool ->
xdr_value -> xdr_type -> (string * xdr_type) list -> stringval unpack_xdr_value : ?pos:int ->
?len:int ->
?fast:bool ->
?prefix:bool ->
string -> xdr_type -> (string * xdr_type) list -> xdr_valueval unpack_xdr_value_l : ?pos:int ->
?len:int ->
?fast:bool ->
?prefix:bool ->
string -> xdr_type -> (string * xdr_type) list -> xdr_value * intfast: whether to prefer the new "fast" values (default: false)
prefix: whether it is ok that the string is longer than the message
(default: false)
The variant unpack_xdr_value_l returns not only the decoded value,
but also the actual length in bytes.