(* $Id: hydro_types.mli 16195 2008-01-21 22:15:59Z gerd $ *)

(** Basic type and exception definitions *)

(** {1 Exceptions} *)

(** These are the base exceptions of the runtime. Note that user code
    usually does not get them directly because they are wrapped into
    the [Client_condition] exception. E.g. user code could get
    [Client_condition(`Connect_error(Proxy_error(`NoEndpointIsReachable)))].

    For technical reasons, [Client_condition] is defined below.
 *)

open Hydro_prelim


type protocol_violation =
    [ `MessageFormatViolation of string
    | `CompressionNotSupported
    | `BadMessageType
    ]

exception Protocol_violation of protocol_violation
  (** A violation of the protocol has been detected:
      - [`MessageFormatViolation reason]: The data received over the wire
        cannot be even split into messages. [reason] explains why.
      - [`CompressionNotSupported]: A compressed message was received
        although Hydro announces that it does not support compression.
      - [`BadMessageType]: XXX
   *)

exception Marshal_error of string
  (** A value cannot be marshalled, i.e. converted into the string format
      that is sent over the wire. The argument explains the reason.
   *)

exception Unmarshal_error of string
  (** A received message cannot be decoded into a value.
      The argument explains the reason.
   *)

type limitation =
    [ `UnsupportedEncodingVersion
    | `UnsupportedProtocolVersion
    | `UnsupportedEndpointType of int
    ]

exception Limitation of limitation
  (** A Hydro limitation was hit:
      - [`UnsupportedEncodingVersion]: Hydro only understands version 1.0
      - [`UnsupportedProtocolVersion]: Hydro only understands version 1.0
   *)


type proxy_error =
    [ `NoCallableEndpointFound
    | `NoEndpointIsReachable
    | `NoLocatorIsReachable
    | `ProxyIsDown
    ]

exception Proxy_error of proxy_error
  (** The proxy is unable to fulfill the request:
      - [`NoCallableEndpointFound]: After the endpoint resolution procedure
        no endpoint turns out to be usable. Note that also DNS failures
        can lead to this error.
      - [`NoEndpointIsReachable]: None of the resolved endpoints is
        actually reachable.
      - [`NoLocatorIsReachable]: No locator (i.e. IceGrid node) is
        actually reachable, and the resolution procedure fails because of 
        this.
      - [`ProxyIsDown]: The proxy has been shut down
   *)

exception Domain_not_found of string
  (** A DNS name cannot be resolved. The argument is the name *)

exception Unbound_exception of exn
  (** An exception that has not to be caught by a exception handler
      built into Hydro. Such exceptions always fall through to the
      user code.
    *)

exception Unimplemented_operation of string
  (** This operation was called, but the actual definition is missing *)

(** See also the exception [Client_condition] below! *)


(** {1 Values} *)

(** This defines [value], the abstract (non-mapped) representation of
    values that can be sent over the wire. [value] is mostly internally
    used, because [hydrogen] generates a user-friendlier representation
    of values that uses directly OCaml types.
 *)


type noreturn
  (** A type without value. May be used to indicate that functions or methods
      never return normally to the caller.
   *)

type value =
    [ `Nothing
	(* The fictive value for `Void types *)
    | `Bool of bool
    | `Byte of int
    | `Short of int
    | `Int of int
    | `Int32 of int32
    | `Long of int64
    | `Float of float
    | `Double of float
    | `String of string   
	(* the UTF8-encoded string *)
    | `Sequence of value array
	(* the elements of the sequence in order *)
    | `Byteseq of string
	(* `Sequence `Byte, represented as ocaml string *)
    | `Dictionary of (value * value) array
	(* the dictionary pairs *)
    | `Enum of int   
	(* the number is the position in the declaration *)
    | `Struct of value array
	(* the elements of the structure in order *)
    | `Null
    | `Class of class_repr ref
	(* This is a reference so we can patch the value during unmarshalling
         *)
    | `Proxy of proxy_addr
    | `DirectWriter of (Netbuffer.t -> unit)
    ]
  (** This is mostly clear: e.g. [`Long n] represents a value that is declared
      as "long" in the Ice IDL file. Some remarks:
      - [`Nothing] is the fictive value for [`Void] types (think of [()] in
        OCaml)
      - There are two representations for "int": [`Int n] and [`Int32 n],
        so the user can select which representation to prefer
      - [`Float f] means that [f] is only single-precision, although the
        OCaml [float] type corresponds to double-precision floats.
      - [`Byteseq s] is used for values of  [sequence<byte>] Ice type.
      - [`Enum k]: The number [k] is the position in the declaration.
      - [`Class cls_ref]: We use a reference as argument to simply the
        unmarshalling algorithm. User code should never see [`Placeholder]
        inside this reference, but only [`Value].
   *)


and class_repr =
    [ `Placeholder of int32
    | `Value of object_value
    ]

and sliced_value =
    < hydro_slices : slice list;
      hydro_effective_id : string;
     >
  (** Sliced values are used to marshal exceptions and object instances.
      For these there is an inheritance hierarchy.
      - [hydro_slices]: These are the slices in base-to-derived order,
        i.e. the root slice for the root of the inheritance hierarchy
        comes first, and the most derived slice comes last.
      - [hydro_effective_id]:  The effective type ID of the class or 
        exception. This is the most derived ID the local type system 
        knows = the latest element in [hydro_slices] with a decoded slice.

      This type also exists as class type {!Hydro_lm.sliced_base}.
   *)


and object_value =
    < (* This is an enhanced sliced_value *)
      hydro_slices : slice list;
      hydro_effective_id : string;
      hydro_inflate : string -> noreturn;
      hydro_invoke_operation : string -> value array -> session -> unit
    >
  (** Object values are subtypes of [sliced_value]. Additional
      methods:
      - [hydro_inflate id]: Used in the language-mapping layer to restore
        the full object type for the [object_value]. This is done by
        calling [hydro_inflate] with the class [id] of the desired class.
        The method in turn raises a special exception [E obj]
        that has to be caught by the caller in order to get [obj].
        The argument [obj] is the object itself, but with a richer type
        that corresponds to [id].
      - [hydro_invoke_operation name args sess]: invoke the operation
        [name] (always passed in lowercase letters) with arguments [args]
        and session [sess].

      Basically this means that an [object_value] is a [sliced_value]
      that can be recovered as rich class type by the language mapping layer.

      For an [object_value] that has callable operations, use 
      the class type {!Hydro_lm.object_base}.
   *)


and slice =
    [ `Decoded of string * value array
    | `Opaque of string * string
    ]
  (** It is possible that the ID of a slice is known or not. In the first
      case Hydro represents it as [`Decoded(id,values)] where [id] is the
      type ID of the slice, and [values] are the decoded values in order.
      If Hydro does not know the type ID, the slice is represented as
      [`Opaque(id,values)], and the values remain unmarshalled. It is still
      possible to forward an opaque value to another Ice node.
   *)


and proxy_addr =
    (* Only non-Null proxies *)
    < id : identity;
      facet : string option;
      mode : proxy_mode;
      secure : bool;
      parameters : proxy_parameters
    >
  (** The address of a remote object (for creating a proxy):
      - [id] is the identity of the remote object
      - [facet] is the facet if any
      - [mode] is the mode of the proxy
      - [secure] may demand that only SSL endpoints are chose in order
        to access the remote object
      - [parameters] denotes the endpoint(s) where the object is reachable
        in a transport-dependent form
   *)

and proxy_mode = 
    [ `Twoway | `Oneway | `Batch_oneway | `Datagram | `Batch_datagram ]

and proxy_parameters =
    [ `Endpoints of endpoint array
    | `Indirect of string
    ]

and endpoint =
    [ `TCP of tcp_endpoint
    | `UDP of udp_endpoint
    | `SSL of ssl_endpoint
    | `Unknown of int * string
    ]

and endpoint_type =
    [ `TCP | `UDP | `SSL | `Unknown of int ]

and tcp_endpoint =
    < host : string; 
      port : int;
      timeout : int32;
      compress : bool;
    >

and udp_endpoint =
    < host : string;
      port : int;
      proto_major : int;
      proto_minor : int;
      enc_major : int;
      enc_minor : int;
      compress : bool;
    >

and ssl_endpoint = tcp_endpoint

and identity =
    < name : string;
      category : string
    >
  (** The identity of a remote object *)


(** {1 Type system} *)

and htype =
    [ `Void
    | `Bool
    | `Byte
    | `Short
    | `Int     (* Prefer int as O'Caml type *)
    | `Int32   (* Prefer int32 as O'Caml type *)
    | `Long
    | `Float
    | `Double
    | `String
    | `Byteseq
    | `Enum of string array
    | `Struct of (string * htype) array
    | `Sequence of htype
    | `Dictionary of htype * htype
    | `Proxy of string   (* name of the interface in [system] *)
    | `Class of string   (* name of the class in [system] *)
    ]

and hexn =
    < name : string;             (* Absolute name *)
      super : hexn option;       (* The next exception in the hierarchy *)
      elements : (string * htype) array;
    >

and hintf =
    < name : string;             (* Absolute name *)
      super : hintf list;
      elements : hfunction list;
    >

and hfunction =
    < name : string;             (* relative name *)
      m