<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<link rel="stylesheet" href="style.css" type="text/css">
<meta content="text/html; charset=iso-8859-1" http-equiv="Content-Type">
<link rel="Start" href="index.html">
<link rel="previous" href="Rpc_transport.html">
<link rel="next" href="Rpc_simple_client.html">
<link rel="Up" href="index.html">
<link title="Index of types" rel=Appendix href="index_types.html">
<link title="Index of exceptions" rel=Appendix href="index_exceptions.html">
<link title="Index of values" rel=Appendix href="index_values.html">
<link title="Index of class attributes" rel=Appendix href="index_attributes.html">
<link title="Index of class methods" rel=Appendix href="index_methods.html">
<link title="Index of classes" rel=Appendix href="index_classes.html">
<link title="Index of class types" rel=Appendix href="index_class_types.html">
<link title="Index of modules" rel=Appendix href="index_modules.html">
<link title="Index of module types" rel=Appendix href="index_module_types.html">
<link title="Uq_gtk" rel="Chapter" href="Uq_gtk.html">
<link title="Equeue" rel="Chapter" href="Equeue.html">
<link title="Unixqueue" rel="Chapter" href="Unixqueue.html">
<link title="Uq_engines" rel="Chapter" href="Uq_engines.html">
<link title="Uq_socks5" rel="Chapter" href="Uq_socks5.html">
<link title="Unixqueue_mt" rel="Chapter" href="Unixqueue_mt.html">
<link title="Equeue_intro" rel="Chapter" href="Equeue_intro.html">
<link title="Uq_ssl" rel="Chapter" href="Uq_ssl.html">
<link title="Uq_tcl" rel="Chapter" href="Uq_tcl.html">
<link title="Netcgi_common" rel="Chapter" href="Netcgi_common.html">
<link title="Netcgi" rel="Chapter" href="Netcgi.html">
<link title="Netcgi_ajp" rel="Chapter" href="Netcgi_ajp.html">
<link title="Netcgi_scgi" rel="Chapter" href="Netcgi_scgi.html">
<link title="Netcgi_cgi" rel="Chapter" href="Netcgi_cgi.html">
<link title="Netcgi_fcgi" rel="Chapter" href="Netcgi_fcgi.html">
<link title="Netcgi_dbi" rel="Chapter" href="Netcgi_dbi.html">
<link title="Netcgi1_compat" rel="Chapter" href="Netcgi1_compat.html">
<link title="Netcgi_test" rel="Chapter" href="Netcgi_test.html">
<link title="Netcgi_porting" rel="Chapter" href="Netcgi_porting.html">
<link title="Netcgi_plex" rel="Chapter" href="Netcgi_plex.html">
<link title="Http_client" rel="Chapter" href="Http_client.html">
<link title="Telnet_client" rel="Chapter" href="Telnet_client.html">
<link title="Ftp_data_endpoint" rel="Chapter" href="Ftp_data_endpoint.html">
<link title="Ftp_client" rel="Chapter" href="Ftp_client.html">
<link title="Nethttpd_types" rel="Chapter" href="Nethttpd_types.html">
<link title="Nethttpd_kernel" rel="Chapter" href="Nethttpd_kernel.html">
<link title="Nethttpd_reactor" rel="Chapter" href="Nethttpd_reactor.html">
<link title="Nethttpd_engine" rel="Chapter" href="Nethttpd_engine.html">
<link title="Nethttpd_services" rel="Chapter" href="Nethttpd_services.html">
<link title="Nethttpd_plex" rel="Chapter" href="Nethttpd_plex.html">
<link title="Nethttpd_intro" rel="Chapter" href="Nethttpd_intro.html">
<link title="Netplex_types" rel="Chapter" href="Netplex_types.html">
<link title="Netplex_mp" rel="Chapter" href="Netplex_mp.html">
<link title="Netplex_mt" rel="Chapter" href="Netplex_mt.html">
<link title="Netplex_log" rel="Chapter" href="Netplex_log.html">
<link title="Netplex_controller" rel="Chapter" href="Netplex_controller.html">
<link title="Netplex_container" rel="Chapter" href="Netplex_container.html">
<link title="Netplex_sockserv" rel="Chapter" href="Netplex_sockserv.html">
<link title="Netplex_workload" rel="Chapter" href="Netplex_workload.html">
<link title="Netplex_main" rel="Chapter" href="Netplex_main.html">
<link title="Netplex_config" rel="Chapter" href="Netplex_config.html">
<link title="Netplex_kit" rel="Chapter" href="Netplex_kit.html">
<link title="Rpc_netplex" rel="Chapter" href="Rpc_netplex.html">
<link title="Netplex_cenv" rel="Chapter" href="Netplex_cenv.html">
<link title="Netplex_intro" rel="Chapter" href="Netplex_intro.html">
<link title="Netshm" rel="Chapter" href="Netshm.html">
<link title="Netshm_data" rel="Chapter" href="Netshm_data.html">
<link title="Netshm_hashtbl" rel="Chapter" href="Netshm_hashtbl.html">
<link title="Netshm_array" rel="Chapter" href="Netshm_array.html">
<link title="Netshm_intro" rel="Chapter" href="Netshm_intro.html">
<link title="Netconversion" rel="Chapter" href="Netconversion.html">
<link title="Netchannels" rel="Chapter" href="Netchannels.html">
<link title="Netstream" rel="Chapter" href="Netstream.html">
<link title="Mimestring" rel="Chapter" href="Mimestring.html">
<link title="Netmime" rel="Chapter" href="Netmime.html">
<link title="Netsendmail" rel="Chapter" href="Netsendmail.html">
<link title="Neturl" rel="Chapter" href="Neturl.html">
<link title="Netaddress" rel="Chapter" href="Netaddress.html">
<link title="Netbuffer" rel="Chapter" href="Netbuffer.html">
<link title="Netdate" rel="Chapter" href="Netdate.html">
<link title="Netencoding" rel="Chapter" href="Netencoding.html">
<link title="Netulex" rel="Chapter" href="Netulex.html">
<link title="Netaccel" rel="Chapter" href="Netaccel.html">
<link title="Netaccel_link" rel="Chapter" href="Netaccel_link.html">
<link title="Nethtml" rel="Chapter" href="Nethtml.html">
<link title="Netstring_str" rel="Chapter" href="Netstring_str.html">
<link title="Netstring_pcre" rel="Chapter" href="Netstring_pcre.html">
<link title="Netstring_mt" rel="Chapter" href="Netstring_mt.html">
<link title="Netmappings" rel="Chapter" href="Netmappings.html">
<link title="Netaux" rel="Chapter" href="Netaux.html">
<link title="Nethttp" rel="Chapter" href="Nethttp.html">
<link title="Netchannels_tut" rel="Chapter" href="Netchannels_tut.html">
<link title="Netmime_tut" rel="Chapter" href="Netmime_tut.html">
<link title="Netsendmail_tut" rel="Chapter" href="Netsendmail_tut.html">
<link title="Netulex_tut" rel="Chapter" href="Netulex_tut.html">
<link title="Neturl_tut" rel="Chapter" href="Neturl_tut.html">
<link title="Netsys" rel="Chapter" href="Netsys.html">
<link title="Netpop" rel="Chapter" href="Netpop.html">
<link title="Rpc_auth_dh" rel="Chapter" href="Rpc_auth_dh.html">
<link title="Rpc_key_service" rel="Chapter" href="Rpc_key_service.html">
<link title="Rpc_time" rel="Chapter" href="Rpc_time.html">
<link title="Rpc_auth_local" rel="Chapter" href="Rpc_auth_local.html">
<link title="Rtypes" rel="Chapter" href="Rtypes.html">
<link title="Xdr" rel="Chapter" href="Xdr.html">
<link title="Rpc" rel="Chapter" href="Rpc.html">
<link title="Rpc_program" rel="Chapter" href="Rpc_program.html">
<link title="Rpc_portmapper_aux" rel="Chapter" href="Rpc_portmapper_aux.html">
<link title="Rpc_packer" rel="Chapter" href="Rpc_packer.html">
<link title="Rpc_transport" rel="Chapter" href="Rpc_transport.html">
<link title="Rpc_client" rel="Chapter" href="Rpc_client.html">
<link title="Rpc_simple_client" rel="Chapter" href="Rpc_simple_client.html">
<link title="Rpc_portmapper_clnt" rel="Chapter" href="Rpc_portmapper_clnt.html">
<link title="Rpc_portmapper" rel="Chapter" href="Rpc_portmapper.html">
<link title="Rpc_server" rel="Chapter" href="Rpc_server.html">
<link title="Rpc_auth_sys" rel="Chapter" href="Rpc_auth_sys.html">
<link title="Rpc_intro" rel="Chapter" href="Rpc_intro.html">
<link title="Rpc_mapping_ref" rel="Chapter" href="Rpc_mapping_ref.html">
<link title="Rpc_ssl" rel="Chapter" href="Rpc_ssl.html">
<link title="Rpc_xti_client" rel="Chapter" href="Rpc_xti_client.html">
<link title="Shell_sys" rel="Chapter" href="Shell_sys.html">
<link title="Shell" rel="Chapter" href="Shell.html">
<link title="Shell_uq" rel="Chapter" href="Shell_uq.html">
<link title="Shell_mt" rel="Chapter" href="Shell_mt.html">
<link title="Shell_intro" rel="Chapter" href="Shell_intro.html">
<link title="Netsmtp" rel="Chapter" href="Netsmtp.html"><title>Ocamlnet 2 Reference Manual : Rpc_client</title>
</head>
<body>
<div class="navbar"><a href="Rpc_transport.html">Previous</a>
<a href="index.html">Up</a>
<a href="Rpc_simple_client.html">Next</a>
</div>
<center><h1>Module <a href="type_Rpc_client.html">Rpc_client</a></h1></center>
<br>
<pre><span class="keyword">module</span> Rpc_client: <code class="code">sig</code> <a href="Rpc_client.html">..</a> <code class="code">end</code></pre>RPC clients<br>
<hr width="100%">
<br>
This module implements an RPC client, i.e. provides means to connect
to an RPC service and call remote procedures.
In general, this module works in an asynchronous way and is implemented
event-driven. All events are handled by an event queue of type
Unixqueue.t that must already exist and to which this module adds its
own event handlers and event resources. This means that this module
can co-exist with other services and share the same event queue with
them.
<p>
You can push several procedure calls on the event queue at once.
The queue serves then as a pipeline; the calls are sent to the
server as long as the server accepts new calls. Replies are received
in any order, and the return values of the remote procedures are
delivered using a callback function.
<p>
You can set timeouts and force automatic retransmission if you want
this; these features are enabled by default if the underlying transport
mechanism is UDP. Timeouts and other exceptions are delivered to the
callback functions, too.
<p>
The whole mechanism is designed to allow maximum parallelism without
needing to use the multi-threading features of O'Caml. Especially,
the following parallelisms can be done:<ul>
<li>Call several procedures of the same server in parallel. Note that
this does not necessarily mean that the procedures are run in
parallel since the server is free to decide whether to work
in a synchronous or asynchronous way.</li>
<li>Call several procedures of different servers in parallel. To do so,
simply add several RPC clients to the same event queue.</li>
<li>Call a procedure and do something completely different in the
background; this works well as long as the other task can be
programmed using file descriptor events, too.</li>
</ul>
However, there are still some restrictions concerning asynchronous
calls. Some of them will be removed in the future, but others are
difficult to tackle:<ul>
<li>Authentication methods requiring RPC calls or other network services are
performed in an synchronous way, too.</li>
<li>Name service lookups are synchronous, too.</li>
</ul>
<br>
<pre><span class="keyword">exception</span> <a name="EXCEPTIONMessage_lost"></a>Message_lost</pre>
<div class="info">
got EOF when some pending procedure calls were not replied or even sent<br>
</div>
<pre><span class="keyword">exception</span> <a name="EXCEPTIONMessage_timeout"></a>Message_timeout</pre>
<div class="info">
After all retransmissions, there was still no reply<br>
</div>
<pre><span class="keyword">exception</span> <a name="EXCEPTIONCommunication_error"></a>Communication_error <span class="keyword">of</span> <code class="type">exn</code></pre>
<div class="info">
an I/O error happened<br>
</div>
<pre><span class="keyword">exception</span> <a name="EXCEPTIONClient_is_down"></a>Client_is_down</pre>
<div class="info">
The RPC call cannot be performed because the client has been shut down
in the meantime. You can get this exception if you begin a new call,
but the connection is closed now.<br>
</div>
<pre><span class="keyword">exception</span> <a name="EXCEPTIONKeep_call"></a>Keep_call</pre>
<div class="info">
This exception can be raised by the callback function that is invoked
when the server response arrives. It causes that the RPC call record
is kept in the housekeeping structure of the client. If the server
sends another response, the callback function will be invoked again.
I.e. one call can be replied several times (batching).<br>
</div>
<pre><span class="keyword">exception</span> <a name="EXCEPTIONUnbound_exception"></a>Unbound_exception <span class="keyword">of</span> <code class="type">exn</code></pre>
<div class="info">
This exception can be raised by the callback function that is invoked
when the server response arrives. It simply causes that the inner
exception bypasses the exception handler, and falls through to the
caller of <code class="code">Unixqueue.run</code>. This is useful to jump out of the running RPC
routines.<br>
</div>
<pre><span class="keyword">type</span> <a name="TYPEt"></a><code class="type"></code>t </pre>
<div class="info">
The type of RPC clients<br>
</div>
<br><code><span class="keyword">type</span> <a name="TYPEconnector"></a><code class="type"></code>connector = </code><table class="typetable">
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">Inet</span> <span class="keyword">of</span> <code class="type">(string * int)</code></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" >Hostname or IP address, port</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">Internet</span> <span class="keyword">of</span> <code class="type">(Unix.inet_addr * int)</code></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" >The address plus port</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">Unix</span> <span class="keyword">of</span> <code class="type">string</code></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" >Path to unix dom sock</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">Descriptor</span> <span class="keyword">of</span> <code class="type">Unix.file_descr</code></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" >Pass an already open socket descriptor. The descriptor will not
be closed when the client is done!</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">Dynamic_descriptor</span> <span class="keyword">of</span> <code class="type">(unit -> Unix.file_descr)</code></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" >The function is called to get the socket descriptor.
Unlike <code class="code">Descriptor</code>, the descriptor will be closed when the
client is done</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span class="constructor">Portmapped</span> <span class="keyword">of</span> <code class="type">string</code></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" >The portmapper on this host is queried to get address information</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr></table>
<pre><span class="keyword">val</span> <a name="VALshutdown_connector"></a>shutdown_connector : <code class="type"><a href="Rpc_client.html#TYPEt">t</a> -> <a href="Rpc_transport.rpc_multiplex_controller.html">Rpc_transport.rpc_multiplex_controller</a> -> unit</code></pre><div class="info">
The default implementation to shut down the connector.
For <code class="code">Descriptor</code> this is a no-op,
for the other connector types the socket is closed.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALcreate"></a>create : <code class="type">?program_number:<a href="Rtypes.html#TYPEuint4">Rtypes.uint4</a> -><br> ?version_number:<a href="Rtypes.html#TYPEuint4">Rtypes.uint4</a> -><br> ?initial_xid:int -><br> ?shutdown:(<a href="Rpc_client.html#TYPEt">t</a> -> <a href="Rpc_transport.rpc_multiplex_controller.html">Rpc_transport.rpc_multiplex_controller</a> -> unit) -><br> <a href="Unixqueue.event_system.html">Unixqueue.event_system</a> -><br> <a href="Rpc_client.html#TYPEconnector">connector</a> -> <a href="Rpc.html#TYPEprotocol">Rpc.protocol</a> -> <a href="Rpc_program.html#TYPEt">Rpc_program.t</a> -> <a href="Rpc_client.html#TYPEt">t</a></code></pre><div class="info">
Opens a connection to the server specified by the <code class="code">connector</code>.
The server is assumed to implement an RPC program as specified by
the <code class="code">Rpc_program.t</code> argument. (You can override the program and version
numbers stored in this argument by the optional parameters
<code class="code">program_number</code> and <code class="code">version_number</code>.)
<p>
All communication to the server is handled using the given queue
<code class="code">Unixqueue.event_system</code>.
<p>
If the protocol is Tcp, the communication will be handled stream-
oriented. In this case, no timeout is detected and no retransmissions
are done.
<p>
If the protocol is Udp, a datagram-oriented communication style is
used. This works only for Internet UDP sockets because these are
bidirectional (Unix domain sockets are unidirectional and do not
work). For Udp, there is a timeout of 15 seconds and a maximum
of 3 retransmissions (i.e. a total of 4 transmission trials).
<p>
Unlike <code class="code">create2</code>, servers made with <code class="code">create</code> always use blocking
<code class="code">connect</code> for backwards compatibility.
<p>
<br>
</div>
<div class="param_info"><code class="code">program_number</code> : Overrides the program number in <code class="code">Rpc_program.t</code></div>
<div class="param_info"><code class="code">version_number</code> : Overrides the version number in <code class="code">Rpc_program.t</code></div>
<div class="param_info"><code class="code">initial_xid</code> : The initial value for the session identifier.</div>
<div class="param_info"><code class="code">shutdown</code> : This function is called when the client is shut down
to close the client socket. By default, <code class="code">shutdown_connector</code> is
called.</div>
<pre><span class="keyword">class type</span> <a name="TYPEsocket_config"></a><a href="Rpc_client.socket_config.html">socket_config</a> = <code class="code">object</code> <a href="Rpc_client.socket_config.html">..</a> <code class="code">end</code></pre><div class="info">
Configuration for <code class="code">`Socket</code> (see below).
</div>
<pre><span class="keyword">val</span> <a name="VALdefault_socket_config"></a>default_socket_config : <code class="type"><a href="Rpc_client.socket_config.html">socket_config</a></code></pre><div class="info">
Default configuration with <code class="code">non_blocking_connect</code> = true<br>
</div>
<pre><span class="keyword">class</span> <a name="TYPEdefault_socket_config"></a><a href="Rpc_client.default_socket_config.html">default_socket_config</a> : <code class="type"></code><code class="type"><a href="Rpc_client.socket_config.html">socket_config</a></code></pre><div class="info">
Default configuration as class
</div>
<pre><span class="keyword">val</span> <a name="VALblocking_socket_config"></a>blocking_socket_config : <code class="type"><a href="Rpc_client.socket_config.html">socket_config</a></code></pre><div class="info">
Configuration with <code class="code">non_blocking_connect</code> = false<br>
</div>
<pre><span class="keyword">class</span> <a name="TYPEblocking_socket_config"></a><a href="Rpc_client.blocking_socket_config.html">blocking_socket_config</a> : <code class="type"></code><code class="type"><a href="Rpc_client.socket_config.html">socket_config</a></code></pre><div class="info">
blocking <code class="code">connect</code> configuration as class
</div>
<pre><span class="keyword">type</span> <a name="TYPEmode2"></a><code class="type"></code>mode2 = <code class="type">[ `Multiplexer_endpoint of <a href="Rpc_transport.rpc_multiplex_controller.html">Rpc_transport.rpc_multiplex_controller</a><br> | `Socket of <a href="Rpc.html#TYPEprotocol">Rpc.protocol</a> * <a href="Rpc_client.html#TYPEconnector">connector</a> * <a href="Rpc_client.socket_config.html">socket_config</a><br> | `Socket_endpoint of <a href="Rpc.html#TYPEprotocol">Rpc.protocol</a> * Unix.file_descr ]</code> </pre>
<div class="info">
Determines the type of the client for <code class="code">create2</code>:
<p>
<ul>
<li><code class="code">`Socket_endpoint(proto,fd)</code>: Socket <code class="code">fd</code> is a connected socket
descriptor used for communication. <code class="code">proto</code> determines the
encapsulation; should be <code class="code">Tcp</code> for stream sockets and <code class="code">Udp</code> for
datagram sockets. The descriptor will be closed when the client
terminates.</li>
</ul>
<ul>
<li><code class="code">`Multiplexer_endpoint m</code>: <code class="code">m</code> is an RPC multiplex controller.</li>
</ul>
<ul>
<li><code class="code">`Socket(proto, conn, config)</code>: Creates and connect a client
socket according to <code class="code">conn</code>. <code class="code">proto</code> determines the
encapsulation; should be <code class="code">Tcp</code> for stream sockets and <code class="code">Udp</code> for
datagram sockets. <code class="code">config</code> specifies configuration details.</li>
</ul>
<br>
</div>
<pre><span class="keyword">val</span> <a name="VALcreate2"></a>create2 : <code class="type">?program_number:<a href="Rtypes.html#TYPEuint4">Rtypes.uint4</a> -><br> ?version_number:<a href="Rtypes.html#TYPEuint4">Rtypes.uint4</a> -><br> ?initial_xid:int -><br> ?shutdown:(<a href="Rpc_client.html#TYPEt">t</a> -> <a href="Rpc_transport.rpc_multiplex_controller.html">Rpc_transport.rpc_multiplex_controller</a> -> unit) -><br> <a href="Rpc_client.html#TYPEmode2">mode2</a> -> <a href="Rpc_program.html#TYPEt">Rpc_program.t</a> -> <a href="Unixqueue.event_system.html">Unixqueue.event_system</a> -> <a href="Rpc_client.html#TYPEt">t</a></code></pre><div class="info">
Creates a new style client. See <code class="code">create</code> and <code class="code">mode2</code> for explanations.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALconfigure"></a>configure : <code class="type"><a href="Rpc_client.html#TYPEt">t</a> -> int -> float -> unit</code></pre><div class="info">
<code class="code">configure client retransmissions timeout</code>:
sets the number of retransmissions and the timeout for the next calls.
(These values are defaults; the actual values are stored with each
call.)
<p>
Values of <code class="code">retransmissions > 0</code> are semantically only valid if the
called procedures are idempotent, i.e. invoking them several times
with the same values has the same effect as only one invocation.
Positive values for <code class="code">retransmissions</code> should only be used for Udp-style
communication.
<p>
The timeout value determines how long the client waits until the
next retransmission is done, or, if no more retransmissions are
permitted, a <code class="code">Message_timeout</code> exception is delivered to the receiving
callback function. A <code class="code">timeout</code> value of 0.0 means immediate timeout
(see next paragraph). A negative <code class="code">timeout</code> value means 'no timeout'.
Positive <code class="code">timeout</code> values are possible for both Udp and Tcp connections.
Timeout values are measured in seconds.
<p>
There is a special application for the timeout value 0.0: If you
don't expect an answer from the server at all ("batch mode"), this
timeout value will cause that the message handler will get
a <code class="code">Message_timeout</code> exception immediately. You should ignore this
exception for batch mode. The positive effect from the timeout is that
the internal management routines will remove the remote call from
the list of pending calls such that this list will not become too long.
<p>
Note that the meaning of timeouts for TCP connections is unclear.
The TCP stream may be in an undefined state. Because of this, the
client does not make any attempt to clean the state up for TCP.
The user is advised to shut down the client, and reconnect.
<p>
There is another subtle difference between UDP and TCP. For UDP,
the timer is started when the packet is sent. For TCP, however,
the timer is already started when the RPC call is added to the
queue, i.e. much earlier. This means that the time for connecting
to the remote service is also bound by the timeout. The rationale
is that TCP timeouts are usually set to catch total service failures
rather than packet losses, and this behaviour is best for this purpose.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALset_dgram_destination"></a>set_dgram_destination : <code class="type"><a href="Rpc_client.html#TYPEt">t</a> -> Unix.sockaddr option -> unit</code></pre><div class="info">
<code class="code">set_dgram_destination client addr_opt</code>: This function is required
for using the client in conjunction with unconnected UDP sockets.
For connected sockets, the destination of datagrams is implicitly
given. For unconnected sockets, one has to set the destination
explicitly. Do so by calling <code class="code">set_dgram_destination</code> with
<code class="code">Some addr</code> as <code class="code">addr_opt</code> argument before doing the next call.
Passing <code class="code">None</code> as <code class="code">addr_opt</code> removes the explicit destination again.
Note that unconnected sockets differ from connected sockets also in
the relaxation that they can receive messages from any IP address,
and not only the one they are connected to.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALset_exception_handler"></a>set_exception_handler : <code class="type"><a href="Rpc_client.html#TYPEt">t</a> -> (exn -> unit) -> unit</code></pre><div class="info">
sets an exception handler (the default prints the exception to stderr).
Only exceptions resulting from invocations of a
callback function are forwarded to this handler (unless wrapped
by <code class="code">Unbound_exception</code>).
<p>
Exceptions occuring in the handler itself are not caught, and will
fall through.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALadd_call"></a>add_call : <code class="type">?when_sent:(unit -> bool) -><br> <a href="Rpc_client.html#TYPEt">t</a> -><br> string -> <a href="Xdr.html#TYPExdr_value">Xdr.xdr_value</a> -> ((unit -> <a href="Xdr.html#TYPExdr_value">Xdr.xdr_value</a>) -> unit) -> unit</code></pre><div class="info">
<code class="code">add_call client proc_name arg f</code>: add the call to the procedure <code class="code">name</code>
with argument <code class="code">arg</code> to the queue of unprocessed calls.
<p>
When the reply has arrived or an error situation is detected, the
function <code class="code">f</code> is called back. The argument of <code class="code">f</code> is another function
that will return the result or raise an exception:
<p>
<pre><code class="code"> let my_f get_result =
try
let result = get_result() in
...
with
exn -> ...
in
add_call client name arg my_f
</code></pre>
<p>
If <code class="code">f</code> does not catch the exception, the pluggable exception handler
of the client is called (see <code class="code">set_exception_handler</code>). Exceptions are
either <code class="code">Message_lost</code>, <code class="code">Message_timeout</code>, or <code class="code">Communication_error</code>.
<p>
The function <code class="code">f</code> can raise the exception <code class="code">Keep_call</code> to indicate
the special handling that a further reply of the call is expected
(batching).
<p>
<code class="code">when_sent</code>: This function is called when the call has been fully sent
to the server, but before the reply arrives. The function returns whether
to continue the call. By returning <code class="code">false</code> the call is removed from the
internal bookkeeping. The function <code class="code">f</code> is not called in this case.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALevent_system"></a>event_system : <code class="type"><a href="Rpc_client.html#TYPEt">t</a> -> <a href="Unixqueue.event_system.html">Unixqueue.event_system</a></code></pre><div class="info">
Returns the unixqueue to which the client is attached<br>
</div>
<pre><span class="keyword">val</span> <a name="VALprogram"></a>program : <code class="type"><a href="Rpc_client.html#TYPEt">t</a> -> <a href="Rpc_program.html#TYPEt">Rpc_program.t</a></code></pre><div class="info">
Returns the program the client represents<br>
</div>
<pre><span class="keyword">val</span> <a name="VALget_socket_name"></a>get_socket_name : <code class="type"><a href="Rpc_client.html#TYPEt">t</a> -> Unix.sockaddr</code></pre><pre><span class="keyword">val</span> <a name="VALget_peer_name"></a>get_peer_name : <code class="type"><a href="Rpc_client.html#TYPEt">t</a> -> Unix.sockaddr</code></pre><div class="info">
Return the addresses of the client socket and the server socket, resp.
Note that these are only available when the client is already connected.
The function calls fail in this case. It is also possible that the
underlying transport mechanism does not know these data.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALget_sender_of_last_response"></a>get_sender_of_last_response : <code class="type"><a href="Rpc_client.html#TYPEt">t</a> -> Unix.sockaddr</code></pre><div class="info">
Return the address of the sender of the last received response.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALget_protocol"></a>get_protocol : <code class="type"><a href="Rpc_client.html#TYPEt">t</a> -> <a href="Rpc.html#TYPEprotocol">Rpc.protocol</a></code></pre><div class="info">
Get the protocol flavour<br>
</div>
<pre><span class="keyword">val</span> <a name="VALsync_call"></a>sync_call : <code class="type"><a href="Rpc_client.html#TYPEt">t</a> -> string -> <a href="Xdr.html#TYPExdr_value">Xdr.xdr_value</a> -> <a href="Xdr.html#TYPExdr_value">Xdr.xdr_value</a></code></pre><br>
Calls the procedure synchronously.
Note that this implies that the underlying unixqueue is started and that
all events are processed regardless of whether they have something to do
with this call or not.<br>
<pre><span class="keyword">val</span> <a name="VALshut_down"></a>shut_down : <code class="type"><a href="Rpc_client.html#TYPEt">t</a> -> unit</code></pre><div class="info">
Shuts down the connection. Any unprocessed calls get the exception
<code class="code">Message_lost</code>.<br>
</div>
<pre><span class="keyword">class type</span> <a name="TYPEauth_session"></a><a href="Rpc_client.auth_session.html">auth_session</a> = <code class="code">object</code> <a href="Rpc_client.auth_session.html">..</a> <code class="code">end</code></pre><div class="info">
An <code class="code">auth_session</code> object is normally created for every client instance.
</div>
<pre><span class="keyword">class type</span> <a name="TYPEauth_method"></a><a href="Rpc_client.auth_method.html">auth_method</a> = <code class="code">object</code> <a href="Rpc_client.auth_method.html">..</a> <code class="code">end</code></pre><div class="info">
An <code class="code">auth_method</code> object represents a method of authentication.
</div>
<pre><span class="keyword">val</span> <a name="VALauth_none"></a>auth_none : <code class="type"><a href="Rpc_client.auth_method.html">auth_method</a></code></pre><div class="info">
The authentication method that does not perform authentication.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALset_auth_methods"></a>set_auth_methods : <code class="type"><a href="Rpc_client.html#TYPEt">t</a> -> <a href="Rpc_client.auth_method.html">auth_method</a> list -> unit</code></pre><div class="info">
Set the authentication methods for this client. The passed methods
are tried in turn until a method is accepted by the server.
The default is <code class="code"> auth_none </code><br>
</div>
<pre><span class="keyword">val</span> <a name="VALverbose"></a>verbose : <code class="type">bool -> unit</code></pre><div class="info">
set whether you want debug messages or not<br>
</div>
</body></html>
