62 lines
2.8 KiB
OCaml
62 lines
2.8 KiB
OCaml
(**************************************************************************)
|
||
(* *)
|
||
(* Copyright (c) 2014 - 2016. *)
|
||
(* Dynamic Ledger Solutions, Inc. <contact@tezos.com> *)
|
||
(* *)
|
||
(* All rights reserved. No warranty, explicit or implicit, provided. *)
|
||
(* *)
|
||
(**************************************************************************)
|
||
|
||
(** A simple, portable implementation of network frames. *)
|
||
|
||
(** The type of a single datum in a network frame. The encoding of a
|
||
datum is as follows: [[TYPE][CONTENTS]], where [[type]] is a
|
||
single byte whose value is [1] for [S], [2] for [I], [3] for [L],
|
||
[4] for B, [5] for [D], [6] for [F] and [7] for [C].
|
||
For [S]. [I], [L] and [D]¸ the raw values are stored using big
|
||
endianness. For [B], [F] and [C], the size is prefixed as a 16-bit,
|
||
big endian, unsigned integer
|
||
([[SIZE][BYTES]]). *)
|
||
type chunk =
|
||
| S of int (** A 16-bit integer *)
|
||
| I of int32 (** A 32-bit integer *)
|
||
| L of int64 (** A 64-bit integer *)
|
||
| B of MBytes.t (** A series of bytes *)
|
||
| D of float (** A 64-bits IEEE-754 floating point number *)
|
||
| F of frame (** An encapsulated subframe *)
|
||
| C of string (** A string *)
|
||
|
||
(** A network frame is a list of simple data. Its encoding on the
|
||
network is as follows: [[SIZE][DATA]] where [[SIZE]] is the raw
|
||
length of [[DATA]] in bytes as a big endian, 32-bit, unsigned
|
||
integer. *)
|
||
and frame =
|
||
chunk list
|
||
|
||
(** Writes a frame from to file descriptor Returns [true] if
|
||
successful, [false] if an error happened, which means that the
|
||
descriptor cannot accept any more data and should be closed. *)
|
||
val write : Lwt_unix.file_descr -> frame -> bool Lwt.t
|
||
|
||
(** Reads a frame from a file descriptor. Returns [Some frame] if
|
||
successful, [None] if an error happened, which means either that
|
||
that the descriptor cannot provide any more data or that corrupted
|
||
bytes have been received, and in any case says that the descriptor
|
||
should not be used anymore. The second parameter is the limit in
|
||
bytes of the underlying representation, including the size. [None]
|
||
is returned in case of overhead, and the bytes are not consumed
|
||
from the descriptor. *)
|
||
val read : Lwt_unix.file_descr -> int -> frame option Lwt.t
|
||
|
||
(** Pretty printing of frames for debugging *)
|
||
val print : Format.formatter -> frame -> unit
|
||
|
||
(** Pretty prints of frames *)
|
||
val to_string : frame -> string
|
||
|
||
(** Encode a frame as raw bytes to send over the network *)
|
||
val to_raw : frame -> MBytes.t
|
||
|
||
(** Decode a complete raw frame as read from the network *)
|
||
val of_raw : MBytes.t -> frame option
|