(* $Id: rpc_portmapper.mli 279 2006-04-24 14:45:15Z gerd $
 * ----------------------------------------------------------------------
 *
 *)

(** Portmapper version 2 *)

(** Call the portmapper version 2. Note that version 2 is an older version
 * (version 3 and 4 are called 'rpcbind'), but it is normally available.
 *
 * The task of the portmapper is to map program numbers to port numbers.
 * A RPC service that should be available in the whole network should:
 * - on startup: call the [set] procedure to establish a mapping of the
 *   own program number to the port that has been allocated previously
 * - on shutdown: call the [unset] procedure to remove the mapping
 *   (this is NEVER done automatically!)
 *
 * To call an RPC service which is only known by its program number one should
 * contact the portmapper using [getport] to find out the port where the
 * service is actually listening.
 *)

open Rtypes
open Rpc
open Xdr

type t
  (** represents a client for the portmapper *)

val create : Rpc_client.connector -> t
  (** Connects to the portmapper service listening on the given connector. *)

val create_inet : string -> t
  (** Connects to a portmapper listening on an Internet port. The argument
   * is the hostname where the portmapper is running or its internet
   * address. This function connects always to the port 111 on the given
   * host; this is the standard for portmapper daemons.
   *)

val shut_down : t -> unit
  (** Shuts down the connection to the portmapper. *)

val null : t -> unit
  (** Calls the 'NULL' procedure of the portmapper. This procedure has no
   * effect. You can use 'null' to determine whether a procedure call is
   * possible or not.
   *)

val set : t -> uint4 -> uint4 -> protocol -> int -> bool
  (** [set pm_client program_nr version_nr protocol port_nr]:
   * Extends the mapping managed by the portmapper: The triple
   * [(program_nr, version_nr, protocol)] is mapped to the given
   * [port_nr].
   * It is not allowed to overwrite an existing mapping.
   * The procedure returns [true] if the mapping has been extended
   * and [false] otherwise.
   * Note that it usually only possible to [set] a mapping on the local
   * host.
   *)

val unset : t -> uint4 -> uint4 -> protocol -> int -> bool
  (** [unset pm_client program_nr version_nr protocol port_nr]:
   * removes the mapping.
   * The procedure returns [true] if the mapping has been removed
   * and [false] otherwise.
   * Note that it usually only possible to [unset] a mapping on the local
   * host.
   *)

val getport : t -> uint4 -> uint4 -> protocol -> int
  (** [getport pm_client program_nr version_nr protocol]:
   * finds out the port where the given service runs. Returns 0 if the
   * service is not registered.
   *)

val dump : t -> (uint4 * uint4 * protocol * int) list
  (** returns the list of known mappings. The quadrupels have the meaning
   * [(program_nr, version_nr, protocol, port)]
   *)

val callit : t -> Rpc_program.t -> string -> xdr_value -> (int * xdr_value)
  (** [callit pm_client program_spec proc_name argument]:
   * This is an alternate way of calling a remote procedure. Instead
   * of directly invoking the procedure, the portmapper does it for you.
   *
   * You must pass a program specification, the procedure name and the
   * argument to [callit]. On return, you get the port of the service
   * and the result of the procedure invocation.
   *
   * Note that there are several disadvantages:
   * - Error conditions cannot be transmitted back from the portmapper.
   *   [callit] gets a timeout in this case.
   * - The portmapper uses always UDP. This means that the length of
   *   the messages that are exchanged is limited to a total of 8000 bytes.
   *
   * It is NOT recommended to use [callit] for indirecting calls.
   * The [callit] interface was designed for broadcasts and should only
   * be used for this purpose.
   * {b This} implementation of a [callit] client cannot be used for
   * broadcasts, however.
   *)

val port_of_program : Rpc_program.t -> string -> protocol -> int
  (** [port_of_program program host protocol]:
   * queries the portmapper running on [host] for the [program] registered
   * for [protocol].
   * Returns the port number or fails if the number is not known.
   *)