libocamlnet-ocaml-dev 3.7.3-4 / usr / lib / ocaml / netstring / xdr.mli

(* $Id: xdr.mli 1709 2012-02-16 01:17:04Z gerd $ *)

(** External Data Representation *)

(** 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.
 *)

open Rtypes;;

(** 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))]
 *
 * {b 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.
 *)

type xdr_type_term =
  | X_int
  | X_uint
  | X_hyper
  | X_uhyper
  | X_enum of (string * int4) list
  | X_float
  | X_double
  | X_opaque_fixed of uint4
  | X_opaque of uint4
  | X_string of uint4
  | X_mstring of string * uint4
  | X_array_fixed of xdr_type_term * uint4
  | X_array of xdr_type_term * uint4
  | X_struct of (string * xdr_type_term) list
  | X_union_over_int of (int4 * xdr_type_term) list *
                          xdr_type_term option
  | X_union_over_uint of (uint4 * xdr_type_term) list *
                           xdr_type_term option
  | X_union_over_enum of xdr_type_term * (string * xdr_type_term) list *
                           xdr_type_term option
  | X_void
  | X_type of string
  | X_param of string
  | X_rec of (string * xdr_type_term)      (* define a recursive type *)
  | X_refer of string                      (* refer to a recursive type *)
  | X_direct of xdr_type_term * 
                (string -> int ref -> int -> exn) *
                (exn -> string -> int ref -> unit) *
                (exn -> int)
;;

type xdr_type;;
(** This is the validated version of [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].
 *)

type xdr_type_term_system = (string * xdr_type_term) list;;
(** Bind names to types. In a correct system you can only refer to
 * previously defined types, i.e. the type called [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;;
(** A validated type system. *)

val x_bool : xdr_type_term;;
(** Common abbreviation for boolean types. Has values [xv_true] and [xv_false]. *)

val x_optional : xdr_type_term -> xdr_type_term
(** Common abbreviation for optional types. Has values [xv_none] and
 * [xv_some v].
 *)

val x_opaque_max : xdr_type_term
(** Common abbreviation for opaque data of arbitrary length *)

val x_string_max : xdr_type_term
(** Common abbreviation for strings of arbitrary length *)

val x_mstring_max : string -> xdr_type_term
(** Common abbreviation for mstrings of arbitrary length *)

val x_array_max : xdr_type_term -> xdr_type_term
(** Common abbreviation for arrays of arbitrary length *)

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

type xdr_value =
  | XV_int of int4
  | XV_uint of uint4
  | XV_hyper of int8
  | XV_uhyper of uint8
  | XV_enum of string
  | XV_float of fp4
  | XV_double of fp8
  | XV_opaque of string
  | XV_string of string
  | XV_array of xdr_value array
  | XV_struct of (string * xdr_value) list
  | XV_union_over_int of (int4 * xdr_value)
  | XV_union_over_uint of (uint4 * xdr_value)
  | XV_union_over_enum of (string * xdr_value)
  | XV_void
  (* New in 0.4: *)
  | XV_enum_fast of int
      (** 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 xdr_value array
      (** The array elements are in the same order as declared in [X_struct] *)
  | XV_union_over_enum_fast of (int * xdr_value)
      (** The integer is the _position_ in the [X_enum] list. "position"
       * means the same as for [XV_enum_fast]
       *)
  (* New in 3.0: *)
  | XV_array_of_string_fast of string array
      (** To be used with an [X_array] or [X_array_fixed] with an inner
          type of [X_string]
       *)
  | XV_mstring of Xdr_mstring.mstring
  (* New in 3.5: *)
  | XV_direct of exn * int
      (* The variant [XV_direct(exn,size)] should only be used by
	 code generated with ocamlrpcgen. It is only allowed at positions
	 in the term with type [X_direct]. It is assumed that the value
	 is available as exception [exn] (in any form). [size] is the number
	 of bytes in XDR format. 
       *) 

  (* TODO: arrays of int, uint, hyper, uhyper, opaque, float, double *)

val xv_true : xdr_value
val xv_false : xdr_value
  (** See [x_bool] *)

val xv_none : xdr_value
val xv_some : xdr_value -> xdr_value
  (** See [x_optional] *)

(* Destructors. *)

exception Dest_failure
  (** raised if the dest_* function are applied to non-matching xdr_value
   *)

val dest_xv_int : xdr_value -> int4
val dest_xv_uint : xdr_value -> uint4
val dest_xv_hyper : xdr_value -> int8
val dest_xv_uhyper : xdr_value -> uint8
val dest_xv_enum : xdr_value -> string
val dest_xv_enum_fast : xdr_value -> int
val dest_xv_float : xdr_value -> fp4
val dest_xv_double : xdr_value -> fp8
val dest_xv_opaque : xdr_value -> string
val dest_xv_string : xdr_value -> string
val dest_xv_mstring : xdr_value -> Xdr_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 -> int4 * xdr_value
val dest_xv_union_over_uint : xdr_value -> 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
  (** Works for both [XV_enum] and [XV_enum_fast] *)

val map_xv_struct_fast : xdr_type -> xdr_value -> xdr_value array
  (** Works for both [XV_struct] and [XV_struct_fast] *)

val map_xv_union_over_enum_fast : xdr_type -> xdr_value ->
                                                      int * int32 * xdr_value
  (** Works for both [XV_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] array
   * - [i]: value of the enum
   * - [x]: selected arm of the union
   *)


(* This exception is used in unpack_xdr_value. *)

exception Xdr_format of string
  (** Format error found during unpacking a string *)

exception Xdr_format_message_too_long of xdr_value
  (** The message is too long and cannot be packed into a string *)

exception Xdr_failure of string
  (** Usually a problem during packing *)

(** 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
  (** return the [X_param] parameters contained in the type *)

(** 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
(** [are_compatible]: currently not implemented *)

val value_matches_type : xdr_value -> xdr_type -> (string*xdr_type) list -> bool
(** Is the value properly formed with respect to this type? The third
 * argument of this function is a list of parameter instances. Note that
 * all parameters must be instantiated to compare a value with a type
 * and that the parameters instances are not allowed to have parameters
 * themselves.
 *
 * Encrypted parameters are not supported here.
 *)

(** {2 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).
 *)

(** {b 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 = Xdr_mstring.mstring list -> Xdr_mstring.mstring list
  (** see text above *)
type decoder = string -> int -> int -> (string * int)
  (** see text above *)

val pack_xdr_value : ?encode:(string * encoder) list ->
                     xdr_value -> xdr_type -> (string*xdr_type) list ->
                     (string -> unit) -> unit
val pack_xdr_value_as_string :
                     ?rm:bool ->
                     ?encode:(string * encoder) list ->
                     xdr_value -> xdr_type -> (string*xdr_type) list ->
                       string
  (** rm: If true, four null bytes are prepended to the string for the
        record mark

      Changed in Ocamlnet-3.3: these functions raise [Xdr_failure] in
      case of errors.
   *)

val pack_xdr_value_as_mstrings :
       ?encode:(string * encoder) list ->
       xdr_value -> xdr_type -> (string*xdr_type) list -> 
         Xdr_mstring.mstring list
  (** The concatanated mstrings are the packed representation

      Changed in Ocamlnet-3.3: this function raises [Xdr_failure] in
      case of errors.
 *)


type xdr_value_version =
    [ `V1 | `V2 | `V3 | `V4 | `Ocamlrpcgen ]
  (** Selects which version of [xdr_value] is returned by [unpack_xdr_value].
      During the development of Ocamlnet several incompatible changes were
      made, but by selecting a certain version these changes can be hidden
      from the caller.

      - [`V1]: This version refers to the original [xdr_value] definition,
        which only included [XV_int], [XV_uint], [XV_hyper], [XV_uhyper],
        [XV_enum], [XV_float], [XV_double], [XV_opaque], [XV_string],
        [XV_array], [XV_struct], [XV_union_over_int], [XV_union_over_uint],
        [XV_union_over_enum], and [XV_void].
      - [`V2]: This version is available since the [rpc-0.4] distribution,
        and added the tags [XV_enum_fast], [XV_struct_fast], and
        [XV_union_over_enum_fast].
      - [`V3]: In Ocamlnet-3.0 the tag [XV_array_of_string_fast] was added.
      - [`V4]: In Ocamlnet-3.5 the tag [XV_direct] was added.
      - [`Ocamlrpcgen]: This refers to the version that must be used if the
        returned [xdr_value] is processed by code generated with [ocamlrpcgen].

      The default is still [`V1], for ultimate backward compatibility.
      The switch [fast=true] selects [`Ocamlrpcgen] (it was always used
      for this purpose, despite its name).
   *)

val unpack_xdr_value : ?pos:int -> ?len:int -> ?fast:bool -> ?prefix:bool ->
                       ?mstring_factories:Xdr_mstring.named_mstring_factories->
                       ?xv_version:xdr_value_version ->
                       ?decode:(string * decoder) list ->
                       string -> xdr_type -> (string * xdr_type) list ->
                       xdr_value
val unpack_xdr_value_l : ?pos:int -> ?len:int -> ?fast:bool -> ?prefix:bool ->
                       ?mstring_factories:Xdr_mstring.named_mstring_factories-> 
                         ?xv_version:xdr_value_version ->
                         ?decode:(string * decoder) list ->
                         string -> xdr_type -> (string * xdr_type) list ->
                         (xdr_value * int)
  (** [prefix]: whether it is ok that the string is longer than the message
   *   (default: false)
   *
   * [mstring_factories]: when a [T_mstring(name,_)] type is found, the
   * factory is looked up in this hash table under [name], and if this
   * fails under the name ["*"]. If there is no such
   * factory, unpacking fails! (Default: empty table.)
   *
   * [xv_version]: Selects a certain version of the returned [xdr_value]
   * terms. See {!Xdr.xdr_value_version} for details. Set this to
   * [`Ocamlrpcgen] if you decode the [xdr_value] with ocamlrpcgen-generated
   * decoders.
   *
   * [fast]: Setting this to true is a deprecated way to set
   * [xv_version=`Ocamlrpcgen].
   *
   * The variant [unpack_xdr_value_l] returns not only the decoded value,
   * but also the actual length in bytes.
   *
   * The exceptions [Xdr_format] and [Xdr_format_message_too_long] may
   * be raised.
   *)

(**/**)

(* Low-level *)
val get_string_decoration_size : int -> Rtypes.uint4 -> int
  (* Returns the size of the "string decoration", i.e. the size of the
     header (always 4 bytes) plus the size of the padding.
   *)

val sizefn_string : Rtypes.uint4 -> string -> int
  (* Return the packed size of a string *)

val sizefn_mstring : Rtypes.uint4 -> Xdr_mstring.mstring -> int
  (* Return the packed size of an mstring *)

val write_string_fixed : int -> string -> string -> int ref -> unit
val write_string : string -> string -> int ref -> unit
  (* [write_* s1 s2 p]: write the string s1 as XDR to s2 at position p *)

val read_string_fixed : int -> string -> int ref -> int -> string
val read_string : Rtypes.uint4 -> string -> int ref -> int -> string

val raise_xdr_format_too_short : unit -> 'a
val raise_xdr_format_value_not_included : unit -> 'a
val raise_xdr_format_maximum_length : unit -> 'a
val raise_xdr_format_undefined_descriminator : unit -> 'a

val safe_add : int -> int -> int
val safe_mul : int -> int -> int