path: root/cpp/doc/ProxiesEndpoints.sgml

<!--
 **********************************************************************

 Copyright (c) 2003 - 2004
 ZeroC, Inc.
 North Palm Beach, FL, USA

 All Rights Reserved.

 This copy of Ice is licensed to you under the terms described in the
 ICE_LICENSE file included in this distribution.

 **********************************************************************
-->

<!-- ********************************************************************** -->
<section><title>Proxies</title>
<!-- ********************************************************************** -->

<section><title>Synopsis</title>
<cmdsynopsis>
<arg choice=plain><replaceable>identity</replaceable></arg>
<group>
<arg>-f <replaceable>facet</replaceable></arg>
<arg>-t</arg>
<arg>-o</arg>
<arg>-O</arg>
<arg>-d</arg>
<arg>-D</arg>
<arg>-s</arg>
</group>
<group>
<arg choice=plain> @ <replaceable>adapter_id</replaceable></arg>
<arg choice=plain> : <replaceable>endpoints</replaceable></arg>
</group>
</cmdsynopsis>
</section>

<section><title>Description</title>
<para>
A stringified proxy consists of an identity, proxy options, and an
optional object adapter identifier or endpoint list. A proxy containing
an identity with no endpoints, or an identity with an object adapter
identifier, represents an indirect proxy that will be resolved using the
&Ice; locator (see the <literal>Ice.Default.Locator</literal> property).
</para>
<para>
Proxy options configure the invocation mode:
</para>
<informaltable>
<tgroup cols=2>
<tbody>
<row>
<entry>-f <replaceable>facet</replaceable></entry>
<entry>Select a facet of the Ice object.</entry>
</row>
<row>
<entry>-t</entry>
<entry>Configures the proxy for twoway invocations. (default)</entry>
</row>
<row>
<entry>-o</entry>
<entry>Configures the proxy for oneway invocations.</entry>
</row>
<row>
<entry>-O</entry>
<entry>Configures the proxy for batch oneway invocations.</entry>
</row>
<row>
<entry>-d</entry>
<entry>Configures the proxy for datagram invocations.</entry>
</row>
<row>
<entry>-D</entry>
<entry>Configures the proxy for batch datagram invocations.</entry>
</row>
<row>
<entry>-s</entry>
<entry>Configures the proxy for secure invocations.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
The proxy options <literal>-t</literal>, <literal>-o</literal>,
<literal>-O</literal>, <literal>-d</literal>, and <literal>-D</literal>
are mutually exclusive.
</para>
<para>
The object identity <replaceable>identity</replaceable> is structured
as <literal>[<replaceable>category</replaceable>/]<replaceable>name
</replaceable></literal>, where the <replaceable>category</replaceable>
component and slash separator are optional. If
<replaceable>identity</replaceable> contains white space or either of the
characters <literal>:</literal> or <literal>@</literal>, it must be enclosed
in single or double quotes. The <replaceable>category</replaceable> and
<replaceable>name</replaceable> components are UTF8 strings that use the
encoding described below. Any occurrence of a slash (<literal>/</literal>)
in <replaceable>category</replaceable> or <replaceable>name</replaceable>
must be escaped with a backslash (i.e., <literal>\/</literal>).
</para>
<para>
The <replaceable>facet</replaceable> argument of the <literal>-f</literal>
option represents a facet path comprising one or more facets separated by
a slash (<literal>/</literal>). If <replaceable>facet</replaceable>
contains white space, it must be enclosed in single or double quotes. Each
component of the facet path is a UTF8 string that uses the encoding described
below. Any occurrence of a slash (<literal>/</literal>) in a facet path
component must be escaped with a backslash (i.e., <literal>\/</literal>).
</para>
<para>
The object adapter identifier <replaceable>adapter_id</replaceable>
is a UTF8 string that uses the encoding described below. If
<replaceable>adapter_id</replaceable> contains white space, it must
be enclosed in single or double quotes.
</para>
<para>
UTF8 strings are encoded using ASCII characters for the ordinal
range 32-126 (inclusive). Characters outside this range must be encoded
using escape sequences (<literal>\b</literal>,
<literal>\f</literal>, <literal>\n</literal>, <literal>\r</literal>,
<literal>\t</literal>) or octal notation (e.g., <literal>\007</literal>).
Quotation marks used to enclose a string can be escaped using a backslash,
as can the backslash itself (<literal>\\</literal>).
</para>
<para>
If endpoints are specified, they must be separated with a colon
(<literal>:</literal>) and formatted as described in
<link linkend="endpoints" endterm="endpoints.title">Endpoints</link>. The order of
endpoints in the stringified proxy is not necessarily the order in
which connections are attempted during binding: when a stringified proxy is
converted into a proxy instance, the endpoint list is randomized as a form
of load balancing.
</para>
<para>
If the <literal>-s</literal> option is specified, only those endpoints that
support secure invocations are considered during binding. If no valid
endpoints are found, the application receives
<literal>Ice::NoEndpointException</literal>.
</para>
<para>
Otherwise, if the <literal>-s</literal> option is not specified, the endpoint
list is ordered so that non-secure endpoints have priority over secure
endpoints during binding. In other words, connections are attempted on all
non-secure endpoints before any secure endpoints are attempted.
</para>
<para>
If an unknown option is specified, or the stringified proxy is malformed,
the application receives <literal>Ice::ProxyParseException</literal>. If
an endpoint is malformed, the application receives
<literal>Ice::EndpointParseException</literal>.
</para>
</section>

</section>

<!-- ********************************************************************** -->
<section id="endpoints"><title id="endpoints.title">Endpoints</title>
<!-- ********************************************************************** -->

<section><title>Synopsis</title>
<cmdsynopsis>
<arg choice=plain><replaceable>endpoint</replaceable></arg>
<arg rep=repeat> : <replaceable>endpoint</replaceable></arg>
</cmdsynopsis>
</section>

<section><title>Description</title>
<para>
An endpoint list comprises one or more endpoints separated by a colon
(<literal>:</literal>). An endpoint has the following format:
<cmdsynopsis>
<arg choice=plain><replaceable>protocol</replaceable></arg>
<arg rep=repeat><replaceable>option</replaceable></arg>
</cmdsynopsis>
The supported protocols are <literal>tcp</literal>, <literal>udp</literal>,
<literal>ssl</literal>, and <literal>default</literal>. If
<literal>default</literal> is used, it is replaced by the value of the
<literal>Ice.Default.Protocol</literal> property. If an endpoint is
malformed, or an unknown protocol is specified, the application receives
<literal>Ice::EndpointParseException</literal>.
</para>
<note>
<para>
The <literal>ssl</literal> protocol is only available if the IceSSL plug-in
is installed.
</para>
</note>
<para>
The protocols and their supported options are described in the sections that
follow.
</para>
</section>

<!-- ********************************************************************** -->
<section><title>TCP Endpoint</title>
<!-- ********************************************************************** -->

<section><title>Synopsis</title>
<cmdsynopsis>
<command>tcp</command>
<arg>-h <replaceable>host</replaceable></arg>
<arg>-p <replaceable>port</replaceable></arg>
<arg>-t <replaceable>timeout</replaceable></arg>
<arg>-z</arg>
</cmdsynopsis>
</section>

<section><title>Description</title>
<para>
A <literal>tcp</literal> endpoint supports the following options:
<informaltable>
<tgroup cols=4>
<thead>
<row>
<entry>Option</entry>
<entry>Description</entry>
<entry>Client Semantics</entry>
<entry>Server Semantics</entry>
</row>
</thead>
<tbody>
<row>
<entry>-h <replaceable>host</replaceable></entry>
<entry>Specifies the hostname or IP address of the endpoint. If not
specified, the value of <literal>Ice.Default.Host</literal> is used
instead.</entry>
<entry>Determines the hostname or IP address to which a connection
attempt is made.</entry>
<entry>Determines the network interface on which the object adapter
listens for connections, as well as the hostname that is advertised
in proxies created by the adapter.</entry>
</row>
<row>
<entry>-p <replaceable>port</replaceable></entry>
<entry>Specifies the port number of the endpoint.</entry>
<entry>Determines the port to which a connection attempt is made.
(required)</entry>
<entry>The port will be selected by the operating system if this option
is not specified or <replaceable>port</replaceable> is zero.</entry>
</row>
<row>
<entry>-t <replaceable>timeout</replaceable></entry>
<entry>Specifies the endpoint timeout in milliseconds.</entry>
<entry>If <replaceable>timeout</replaceable> is greater than zero,
it sets a maximum delay for binding and proxy invocations. If a timeout
occurs, the application receives <literal>Ice::TimeoutException</literal>.
</entry>
<entry>Determines the default timeout that is advertised in proxies
created by the object adapter.</entry>
</row>
<row>
<entry>-z</entry>
<entry>Specifies bzip2 compression.</entry>
<entry>Determines whether compressed requests are sent.</entry>
<entry>Determines whether compressed responses are sent, as well as
whether compression is advertised in proxies created by the
adapter.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</section>

</section>

<!-- ********************************************************************** -->
<section><title>UDP Endpoint</title>
<!-- ********************************************************************** -->

<section><title>Synopsis</title>
<cmdsynopsis>
<command>udp</command>
<arg>-v <replaceable>major</replaceable>.<replaceable>minor</replaceable></arg>
<arg>-e <replaceable>major</replaceable>.<replaceable>minor</replaceable></arg>
<arg>-h <replaceable>host</replaceable></arg>
<arg>-p <replaceable>port</replaceable></arg>
<arg>-c</arg>
<arg>-z</arg>
</cmdsynopsis>
</section>

<section><title>Description</title>
<para>
A <literal>udp</literal> endpoint supports the following options:
<informaltable>
<tgroup cols=4>
<thead>
<row>
<entry>Option</entry>
<entry>Description</entry>
<entry>Client Semantics</entry>
<entry>Server Semantics</entry>
</row>
</thead>
<tbody>
<row>
<entry>-v <replaceable>major</replaceable>.<replaceable>minor</replaceable></entry>
<entry>Specifies the protocol major and highest minor version number to be used for this
endpoint. If not specified, the protocol major version and highest supported minor version
of the client-side &Ice; run time is used.</entry>
<entry>Determines the protocol major version and highest minor version used by the client side
when sending messages to this endpoint. The protocol major version number must match the protocol major
version number of the server; the protocol minor version number must not be higher than the highest minor
version number supported by the server.</entry>
<entry>Determines the protocol major version and highest minor version advertised by the server side for this endpoint.
The protocol major version number must match the protocol major
version number of the server; the protocol minor version number must not be higher than the highest minor
version number supported by the server.</entry>
</row>
<row>
<entry>-e <replaceable>major</replaceable>.<replaceable>minor</replaceable></entry>
<entry>Specifies the encoding major and highest minor version number to be used for this
endpoint. If not specified, the encoding major version and highest supported minor version
of the client-side &Ice; run time is used.</entry>
<entry>Determines the encoding major version and highest minor version used by the client side
when sending messages to this endpoint. The encoding major version number must match the encoding major
version number of the server; the encoding minor version number must not be higher than the highest minor
version number supported by the server.</entry>
<entry>Determines the encoding version and highest minor version advertised by the server side for this endpoint.
The protocol major version number must match the protocol major
version number of the server; the protocol minor version number must not be higher than the highest minor
version number supported by the server.</entry>
</row>
<row>
<entry>-h <replaceable>host</replaceable></entry>
<entry>Specifies the hostname or IP address of the endpoint. If not
specified, the value of <literal>Ice.Default.Host</literal> is used
instead.</entry>
<entry>Determines the hostname or IP address to which datagrams
are sent.</entry>
<entry>Determines the network interface on which the object adapter
listens for datagrams, as well as the hostname that is advertised
in proxies created by the adapter.</entry>
</row>
<row>
<entry>-p <replaceable>port</replaceable></entry>
<entry>Specifies the port number of the endpoint.</entry>
<entry>Determines the port to which datagrams are sent. (required)</entry>
<entry>The port will be selected by the operating system if this option
is not specified or <replaceable>port</replaceable> is zero.</entry>
</row>
<row>
<entry>-c</entry>
<entry>Specifies that a connected UDP socket should be used.</entry>
<entry>None.</entry>
<entry>Causes the server to connect to the socket of the first peer
that sends a datagram to this endpoint.</entry>
</row>
<row>
<entry>-z</entry>
<entry>Specifies bzip2 compression.</entry>
<entry>Determines whether compressed requests are sent.</entry>
<entry>Determines whether compression is advertised in proxies created
by the adapter.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</section>

</section>

<!-- ********************************************************************** -->
<section><title>SSL Endpoint</title>
<!-- ********************************************************************** -->

<section><title>Synopsis</title>
<cmdsynopsis>
<command>ssl</command>
<arg>-h <replaceable>host</replaceable></arg>
<arg>-p <replaceable>port</replaceable></arg>
<arg>-t <replaceable>timeout</replaceable></arg>
<arg>-z</arg>
</cmdsynopsis>
</section>

<section><title>Description</title>
<para>
An <literal>ssl</literal> endpoint supports the following options:
<informaltable>
<tgroup cols=4>
<thead>
<row>
<entry>Option</entry>
<entry>Description</entry>
<entry>Client Semantics</entry>
<entry>Server Semantics</entry>
</row>
</thead>
<tbody>
<row>
<entry>-h <replaceable>host</replaceable></entry>
<entry>Specifies the hostname or IP address of the endpoint. If not
specified, the value of <literal>Ice.Default.Host</literal> is used
instead.</entry>
<entry>Determines the hostname or IP address to which a connection
attempt is made.</entry>
<entry>Determines the network interface on which the object adapter
listens for connections, as well as the hostname that is advertised
in proxies created by the adapter.</entry>
</row>
<row>
<entry>-p <replaceable>port</replaceable></entry>
<entry>Specifies the port number of the endpoint.</entry>
<entry>Determines the port to which a connection attempt is made.
(required)</entry>
<entry>The port will be selected by the operating system if this option
is not specified or <replaceable>port</replaceable> is zero.</entry>
</row>
<row>
<entry>-t <replaceable>timeout</replaceable></entry>
<entry>Specifies the endpoint timeout in milliseconds.</entry>
<entry>If <replaceable>timeout</replaceable> is greater than zero,
it sets a maximum delay for binding and proxy invocations. If a timeout
occurs, the application receives <literal>Ice::TimeoutException</literal>.
</entry>
<entry>Determines the default timeout that is advertised in proxies
created by the object adapter.</entry>
</row>
<row>
<entry>-z</entry>
<entry>Specifies bzip2 compression.</entry>
<entry>Determines whether compressed requests are sent.</entry>
<entry>Determines whether compressed responses are sent, as well as
whether compression is advertised in proxies created by the
adapter.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</section>

</section>

</section>