/usr/lib/ocaml/netclient/nettelnet

(* $Id$
 * ----------------------------------------------------------------------
 *
 *)

(** Telnet client
 * 
 * This is a Telnet client providing the basic Telnet services. It
 * supports sending and receiving data (asynchronously), and the
 * negotiation of Telnet options, but it does not implement any option.
 *)

exception Telnet_protocol of exn;;
(** Wrapper for exceptions that already passed the exception handler. *)


type telnet_command =
    Telnet_data of string  (** User data *)
  | Telnet_nop             (** No operation *)
  | Telnet_dm           (** data mark *)
  | Telnet_brk          (** break *)
  | Telnet_ip           (** interrupt process *)
  | Telnet_ao           (** abort output *)
  | Telnet_ayt          (** are you there? *)
  | Telnet_ec           (** erase character *)
  | Telnet_el           (** erase line *)
  | Telnet_ga           (** Go ahead *)
  | Telnet_sb of char   (** Begin of subnegotiation *)
  | Telnet_se           (** End of subnegotation *)
  | Telnet_will of char (** Acknowledges that option is in effect *)
  | Telnet_wont of char (** Acknowledges that option is rejected *)
  | Telnet_do of char   (** Requests to turn on an option *)
  | Telnet_dont of char (** Requests to turn off an option *)
  | Telnet_unknown of char (** Unknown command *)
  | Telnet_eof          (** End of file *)
  | Telnet_timeout      (** Timeout event *)
(** A [telnet_command] is the interpretation of the octets in a Telnet
 * session, i.e. it is one level above the octet stream. See RFC 854
 * for an explanation what the commands mean. [Telnet_data] represents
 * the data chunks between the commands. Note that you do not need
 * to double octets having value 255; this is done automatically.
 * [Telnet_unknown] represents any command not covered by RFC 854, for
 * example the End-of-record-mark (introduced in RFC 885) would be
 * [Telnet_unknown '\239']. [Telnet_eof] represents the end of the octet
 * stream, useable in both directions. [Telnet_timeout] is added to the
 * input queue if I/O has not been happened for the configured period
 * of time.
 *)

type telnet_options =
    { connection_timeout : float;
      verbose_input : bool;
      verbose_output : bool;
    }
(** [telnet_options]: modifies the behaviour of the client. Do not mix these
 * options up with the options negotiated with the remote side.
 *
 * - [connection_timeout]:   After this period of time (in seconds) a
 *                           [Telnet_timeout] pseudo-command is added to
 *                           the input queue, and the connection is
 *                           aborted.
 * - [verbose_input]:        Enables printing of input events to {!Netlog.Debug}.
 * - [verbose_output]:       Enables printing of output events to {!Netlog.Debug}
 *)


type telnet_negotiated_option =
    Telnet_binary       (** see RFC 856 *)
  | Telnet_echo         (** see RFC 857 *)
  | Telnet_suppress_GA  (** see RFC 858 *)
  | Telnet_status       (** see RFC 859 *)
  | Telnet_timing_mark  (** see RFC 860 *)
  | Telnet_ext_opt_list (** see RFC 861 *)
  | Telnet_end_of_rec   (** see RFC 885 *)
  | Telnet_window_size  (** see RFC 1073 *)
  | Telnet_term_speed   (** see RFC 1079 *)
  | Telnet_term_type    (** see RFC 1091 *)
  | Telnet_X_display    (** see RFC 1096 *)
  | Telnet_linemode     (** see RFC 1184 *)
  | Telnet_flow_ctrl    (** see RFC 1372 *)
  | Telnet_auth         (** see RFC 1416 *)
  | Telnet_new_environ  (** see RFC 1572 and 1571 *)
  | Telnet_option of int   (** all other options *)
(** [telnet_negotiated_option]: names for the most common options, and
 * the generic name [Telnet_option] for other options.
 *)

type telnet_option_state =
    Not_negotiated
  | Accepted
  | Rejected  (** *)
(** An option has one of three states:
 * - [Not_negotiated]: There was no negotiation about the option. This means
 *   that the option is turned off (but this client is allowed to reject
 *   it explicitly)
 * - [Accepted]: Both sides have accepted the option.
 * - [Rejected]: One side has rejected the option. This also means that the
 *   option is off, but the client refuses to send further acknoledgements
 *   that the option is off (to avoid endless negotiation loops).
 *)


val char_of_option : telnet_negotiated_option -> char
(** Converts the option name to the character representing it on the
 * octet-stream level.
 *)

val option_of_char : char -> telnet_negotiated_option
(** Converts a character representing an option to the internal option
 * name.
 *)


type telnet_connector =
    Telnet_connect of (string * int)
  | Telnet_socket of Unix.file_descr (** *)
(** Connectors:
 * - [Telnet_connect(host,port)]: The client connects to this port.
 * - [Telnet_socket s]: The client uses an already connected socket.
 *
 * Why [Telnet_socket]? Telnet is a symmetrical protocol; client and servers
 * implement the same protocol features (the only difference is the
 * environment: a client is typically connected with a real terminal; a server
 * is connected with a pseudo terminal). This simply means that this
 * implementation of a client can also be used as a server implementation.
 * You need only to add code which accepts new connections and which passes
 * these connections over to a [telnet_session] object via [Telnet_socket].
 *)


(** A telnet session *)
class telnet_session :
  object
    (** Overwiew
     *
     * The [telnet_session] object has two queues, one for arriving data,
     * one for data to send.
     * Once the session object is attached to an event system, it connects
     * to the remote peer, and processes the queues. Input is appended to
     * the input queue; output found on the output queue is sent to the
     * other side.
     * If input arrives, a callback function is invoked.
     * You may close the output side of the socket by putting [Telnet_eof]
     * onto the output queue.
     * Once the EOF marker has been received, a [Telnet_eof] is appended to
     * the input queue, and the connection is closed (completely). The
     * session object detaches from the event system automatically in this
     * case.
     * 
     * {b Hints}
     *
     * Set an input handler as callback function in the session object.
     * The input handler is called when new input data have been arrived.
     * It should inspect the input queue, process the queue as much as
     * possible, and it should remove the processed items from the queue.
     * While processing, it may add new items to the output queue. 
     *
     * If you are not within the callback function and add items to the
     * output queue, the session object will not detect that there are
     * new items to send - unless you invoke the [update] method.
     *
     * If you want option negotiation, it is the simplest way to use
     * the special option negotiation methods. Configure the options
     * as you want (invoking [enable], [disable] etc), but do not forget
     * to modify the way input is processed. Every [Telnet_will], [_wont],
     * [_do], and [_dont] command must be passed to [process_option_command].
     *)

    method set_connection : telnet_connector -> unit
	(** Sets the host name and the port of the remote server to contact. *)

    method set_event_system : Unixqueue.event_system -> unit
	(** Sets the event system to use. By default, a private event system
	 * is used.
	 *)

    method set_callback : (bool -> unit) -> unit
	(** Sets the callback function. This function is called after new
	 * commands have been put onto the input queue. 
	 * The argument passed to the callback function indicates whether
	 * a 'Synch' sequence was received from the remote side or not.
	 *
	 * {b Note Synch:} If the client sees a data mark command it will assume
	 * that it is actually a Synch sequence. The client automatically
	 * discards any [Telnet_data] commands from the input queue (but not
	 * [Telnet_data]s inside subnegotiations). The data mark command
	 * itself remains on the queue.
	 *)

    method set_exception_handler : (exn -> unit) -> unit
	(** Sets the exception handler. Every known error condition is
	 * caught and passed to the exception handler.
	 * The exception handler can do whatever it wants to do. If it
	 * raises again an exception, the new exception is always propagated
	 * up to the caller (whoever this is). Often the caller is the
	 * event system scheduler (i.e. [Unixqueue.run]); see the documention
	 * there.
         *
	 * If you do not set the exception handler, a default handler is
	 * active. It first resets the session (see method [reset]), and
	 * then wraps the exception into the [Telnet_protocol] exception,
	 * and raises this exception again.
	 *)

    method output_queue : telnet_command Queue.t
        (** The queue of commands to send to the remote side. If you add new
	 * commands to this queue, do not forget to invoke the [update]
	 * method which indicates to the event system that new data to
	 * send is available.
	 * After commands have been sent, they are removed from the queue.
	 *)

    method input_queue : telnet_command Queue.t
        (** The queue of commands received from the remote side. This class
	 * only adds commands to the queue (and invokes the callback 
	 * function). The user of this class is responsible for removing
	 * commands from the queue which have been processed.
	 *)

    method get_options : telnet_options
        (** Get the configuration options. *)

    method set_options : telnet_options -> unit
	(** Set the configuration options. *)

    method reset : unit -> unit 
        (** Closes the connection immediately and empties all queues.
	 * All negotiated options are reset, too.
	 *)

    (** Telnet options
     *
     * The following methods deal with Telnet protocol options. These
     * are negotiated between local and remote side by the Will, Won't,
     * Do and Don't commands. 
     *
     * The "local" options describe the modification of the behaviour
     * of the local side; the "remote" options describe the modifications
     * of the remote side. Both set of options are independent.
     * This object may track the set of accepted and rejected options
     * if the following methods are used; but this works only if
     * the [Telnet_will], [_wont], [_do], and [_dont] commands received from
     * the remote side are processed by [process_option_command]. So
     * you need to invoke this method for the mentioned commands in
     * your command interpretation loop.
     *
     * The idea is: If you {b enable} an option, it is possible to
     * switch it on. If the remote side requests the option to be enabled,
     * the request will be acknowledged. If the remote side does not
     * request the option, it remains off.
     *
     * You can also actively demand an option ([offer_local_option],
     * [request_remote_option]); this is of course only possible if
     * the option is already enabled. In this case the client tries
     * actively to switch it on.
     *
     * You can also {b disable} an option. If the option is on, the
     * client actively rejects the option; following the Telnet protocol
     * this is always possible (rejections cannot be rejected).
     *
     * The [reset] methods are somewhat dangerous. They simply reset
     * the internal state of the client, but do not negotiate. This
     * possibility was added to allow the Timing Mark option to send
     * again timing marks even if the previous timing marks have
     * already been accepted. After [reset], the client thinks the
     * option was never negotiated; but nothing is done to tell
     * the remote side about this.
     *
     * [option_negotiation_is_over]: true if no option negotiation is
     * pending (i.e. nothing has still to be acknowledged).
     *)

    method enable_local_option : telnet_negotiated_option -> unit
    method enable_remote_option : telnet_negotiated_option -> unit
    method disable_local_option : telnet_negotiated_option -> unit
    method disable_remote_option : telnet_negotiated_option -> unit
    method offer_local_option : telnet_negotiated_option -> unit
    method request_remote_option : telnet_negotiated_option -> unit
    method reset_local_option : telnet_negotiated_option -> unit
    method reset_remote_option : telnet_negotiated_option -> unit
    method get_local_option : telnet_negotiated_option -> telnet_option_state
    method get_remote_option : telnet_negotiated_option -> telnet_option_state
    method option_negotiation_is_over : bool
    method process_option_command : telnet_command -> unit

    method fetch_subnegotiation : string option
      (** This method should be called as follows:
       * If you find a [Telnet_sb] at the beginning of the input queue,
       * remove this command [Queue.take], and invoke [fetch_subnegotiation].
       * This method scans the queue and looks for the associated 
       * [Telnet_se] command. If it does not find it, [None] is returned.
       * If [Telnet_se] is found, the parameter enclosed by the two commands
       * is returned as [Some s] where [s] is the parameter string. Furthermore,
       * in the latter case the data items and the closing [Telnet_se] are
       * removed from the queue.
       *)


    (** Running the session *)

    method attach : unit -> unit
        (** Attach to the event system. After being attached, the client
	 * is ready to work.
	 *)

    method run : unit -> unit
	(** Run the event system *)

    method update : unit -> unit
        (** If there are commands in the output queue, the event system is
	 * signaled that this client wants to do network I/O.
	 *)

    method send_synch : telnet_command list -> unit
        (** At the next output oppurtunity, a Synch sequence is sent to
	 * the remote peer. This means that the passed commands, extended
	 * by an additional Data Mark command, are sent to the peer as
	 * urgent data.
         *
	 * Sending a Synch sequence has higher priority than the output
	 * queue; processing of the output queue is deferred until the
	 * Synch sequence has been completely sent.
	 *)

    method expect_input : bool -> unit
      (** Set whether the timeout value is to be applied to the input side
	  of the connection. This is [true] by default.
       *)

    method start_tls : (module Netsys_crypto_types.TLS_CONFIG) -> 
                       peer_name:string option -> unit
      (** Switch to TLS. Note that this is not covered by the TELNET protocol
          standard. However, some applications of TELNET use this nevertheless
          (e.g. FTP control connections). 

          Switching to TLS can be done at any time, but should be done at a
          moment when the other side of the connection expects it. If
          [start_tls] is invoked before [attach], TLS is enabled at the
          very beginning of the TELNET connection.

          The arguments are the TLS configuration, and the peer name for
          validation (pass the host name here).
       *)

    method tls_session_props : Nettls_support.tls_session_props option
      (** TLS session properties (if on) *)

    method tls_session_data : string option
      (** TLS session data (if on) *)
       
  end
;;

(** {1 Debugging} *)

module Debug : sig
  val enable : bool ref
    (** Enables {!Netlog}-style debugging of this module  By default,
        the exchanged Telnet commands are logged. This can be extended
        by setting the [verbose_input] and [verbose_output] options.
     *)
end
libocamlnet-ocaml-dev 4.1.2-3 / usr / lib / ocaml / netclient / nettelnet_client.mli
