module Rpc_portmapper

: sig

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.

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 -> Rtypes.uint4 -> Rtypes.uint4 -> Rpc.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 -> Rtypes.uint4 -> Rtypes.uint4 -> Rpc.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 -> Rtypes.uint4 -> Rtypes.uint4 -> Rpc.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 -> (Rtypes.uint4 * Rtypes.uint4 * Rpc.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.xdr_value -> int * Xdr.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. This implementation of a callit client cannot be used for broadcasts, however.

val port_of_program : Rpc_program.t -> string -> Rpc.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.

end