(* $Id: netencoding.mli 1003 2006-09-24 15:17:15Z gerd $
* ----------------------------------------------------------------------
*
*)
(** Base64, Quoted Printable, URL encoding, HTML escaping *)
(* *********************************************************************)
(* Several encodings important for the net *)
(* *********************************************************************)
(* *********************************************************************)
(* Base 64 encoding *)
(* *********************************************************************)
(* See RFC 2045 for a description of Base 64 encoding. *)
(* THREAD-SAFETY:
* All Base64 functions are reentrant and thus thread-safe.
*)
module Base64 : sig
(** Base64 encoding as described in RFC 2045 *)
val encode : ?pos:int -> ?len:int -> ?linelength:int -> ?crlf:bool ->
string -> string
(** Compute the "base 64" encoding of the given string argument.
* Note that the result is a string that only contains the characters
* a-z, A-Z, 0-9, +, /, =, and optionally spaces, CR and LF characters.
*
* If [pos] and/or [len] are passed, only the substring starting at
* [pos] (default: 0) with length [len] (default: rest of the string)
* is encoded.
*
* The result is divided up into lines not longer than [linelength]
* (without counting the line separator); default: do not divide lines.
* If [linelength] is smaller than 4, no line division is performed.
* If [linelength] is not divisible by 4, the produced lines are a
* bit shorter than [linelength].
*
* If [crlf] (default: false) the lines are ended by CRLF; otherwise
* they are only ended by LF.
* (You need the crlf option to produce correct MIME messages.)
*
*)
val url_encode : ?pos:int -> ?len:int -> ?linelength:int -> ?crlf:bool ->
string -> string
(** Same as [encode] but use slightly different characters that can be
* part of URLs without additional encodings.
* The encoded string consists only of the characters a-z, A-Z, 0-9,
* -, /, .
* [url_encode] does {b not} implement the Base 64 encoding as described
* in the standard!
*
* @deprecated Since Ocamlnet 0.98, this function is deprecated,
* as it is non-standard, and it has a confusing name.
*)
val decode : ?pos:int -> ?len:int -> ?url_variant:bool ->
?accept_spaces:bool -> string -> string
(** Decodes the given string argument.
*
* If [pos] and/or [len] are passed, only the substring starting at
* [pos] (default: 0) with length [len] (default: rest of the string)
* is decoded.
*
* If [url_variant] (default: [true]) is set, the functions also
* accepts the characters '-' and '.' as produced by [url_encode].
*
* If [accept_spaces] (default: [false]) is set, the function ignores
* white space contained in the string to decode (otherwise the
* function fails if it finds white space). Furthermore, the character
* '>' is considered as "space", too (so you don't have trouble with
* mbox mailboxes that accidentally quote "From").
*)
class encoding_pipe : ?linelength:int -> ?crlf:bool -> unit ->
Netchannels.pipe
(** This pipe encodes the data written into the pipe.
* [linelength] and [crlf] work as in [encode].
*)
class decoding_pipe : ?url_variant:bool -> ?accept_spaces:bool -> unit ->
Netchannels.pipe
(** This pipe decodes the data written into the pipe.
* [url_variant] and [accept_spaces] work as in [decode].
*)
end
(* *********************************************************************)
(* Quoted printable encoding *)
(* *********************************************************************)
(* THREAD-SAFETY:
* All QuotedPrintable functions are reentrant and thus thread-safe.
*)
module QuotedPrintable :
sig
(** This module implements the "Quoted Printable" encoding as
* described in RFC 2045.
*
* This implementation assumes that the encoded string has a text MIME
* type. On input both CR/LF and LF are accepted as end-of-line (eol) terminators,
* but the output normalizes the eol delimiter as the [crlf] argument
* specifies. Note that this implies that
* - If [crlf], the output uses CR/LF as line separator as MIME prescribes
* - the encoding is not invertible for binary data
*)
val encode : ?crlf:bool -> ?pos:int -> ?len:int -> string -> string
(** Encodes the string and returns it.
*
* Since OcamlNet 0.98, soft line breaks are added to the output
* to ensure that all output lines have a length <= 76 bytes.
*
* Note unsafe characters:
* As recommended by RFC 2045, the characters [!#$\@[]^`{|}~]
* and the double quotes
* are additionally represented as hex tokens.
* Furthermore, the letter 'F' is considered as unsafe if it
* occurs at the beginning of the line, so the encoded text
* never contains the word "From" at the beginning of a line.
*
* If [pos] and/or [len] are passed, only the substring starting at
* [pos] (default: 0) with length [len] (default: rest of the string)
* is encoded.
*
* If [crlf] is set (the default), the output text uses CR/LF as
* line separator. Otherwise only LF is used.
*)
val decode : ?pos:int -> ?len:int -> string -> string
(** Decodes the string and returns it.
*
* Most format errors cause an [Invalid_argument] exception.
*
* If [pos] and/or [len] are passed, only the substring starting at
* [pos] (default: 0) with length [len] (default: rest of the string)
* is decoded.
*)
class encoding_pipe : ?crlf:bool -> unit -> Netchannels.pipe
(** This pipe encodes the data written into the pipe. *)
class decoding_pipe : unit -> Netchannels.pipe
(** This pipe decodes the data written into the pipe. *)
end
(* *********************************************************************)
(* Q encoding *)
(* *********************************************************************)
(* See RFC 2047.
* The functions behave similar to those of QuotedPrintable.
*)
(* THREAD-SAFETY:
* All Q functions are reentrant and thus thread-safe.
*)
module Q :
sig
(** The "Q" encoding as described by RFC 2047. *)
val encode : ?pos:int -> ?len:int -> string -> string
(** Note:
* All characters except alphanumeric characters are protected by
* hex tokens.
* In particular, spaces are represented as "=20", not as "_".
*)
val decode : ?pos:int -> ?len:int -> string -> string
end
(* ******************************* 
