D.2 Endpoints

Synopsis

endpoint : endpoint

Description

An endpoint list comprises one or more endpoints separated by a colon (:). An endpoint has the following format:

protocol option

The supported protocols are tcp, udp, ssl, and default. If default is used, it is replaced by the value of the Ice.Default.Protocol property. If an endpoint is malformed, or an unknown protocol is specified, the application receives Ice::EndpointParseException.

The ssl protocol is only available if the IceSSL plug‑in is installed.

The protocols and their supported options are described in the sections that follow.

TCP Endpoint

Synopsis

tcp ‑h host ‑p port ‑t timeout ‑z

Description

A tcp endpoint supports the following options:

Option	Description	Client Semantics	Server Semantics
‑h host	Specifies the host name or IP address of the endpoint. If not specified, the value of Ice.Default.Host is used instead.	Determines the host name or IP address to which a connection attempt is made. If not specified, the looback interface is used.	Determines the network interface on which the object adapter listens for connections. If not specified, (or specified as ‑h * or ‑h 0.0.0.0), the adapter listens on all network interfaces (including the loopback interface). The endpoints specified by ‑h are published in proxies. If not specified, all endpoints except loopback are published (except if loopback is the only available interface, in which case only loopback is published).
‑p port	Specifies the port number of the endpoint.	Determines the port to which a connection attempt is made (required).	The port will be selected by the operating system if this option is not specified or port is zero.
‑t timeout	Specifies the endpoint timeout in milliseconds.	If timeout is greater than zero, it sets a maximum delay for binding and proxy invocations. If a timeout occurs, the application receives Ice::TimeoutException.	Determines the default timeout that is advertised in proxies created by the object adapter.
‑z	Specifies bzip2 compression.	Determines whether compressed requests are sent.	Determines whether compression is advertised in proxies created by the adapter.

UDP Endpoint

Synopsis

udp ‑v major.minor ‑e major.minor ‑h host ‑p port ‑z

Description

A udp endpoint supports the following options:

Option	Description	Client Semantics	Server Semantics
‑v major.minor	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.	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.	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.
‑e major.minor	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.	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.	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.
‑h host	Specifies the host name or IP address of the endpoint. If not specified, the value of Ice.Default.Host is used instead.	Determines the host name or IP address to which a connection attempt is made. If not specified, the looback interface is used.	Determines the network interface on which the object adapter listens for datagrams. If not specified, (or specified as ‑h * or ‑h 0.0.0.0), the adapter listens on all network interfaces (including the loopback interface). The endpoints specified by ‑h are published in proxies. If not specified, all endpoints except loopback are published (except if loopback is the only available interface, in which case only loopback is published).
‑p port	Specifies the port number of the endpoint.	Determines the port to which datagrams are sent (required).	The port will be selected by the operating system if this option is not specified or port is zero.
‑z	Specifies bzip2 compression.	Determines whether compressed requests are sent.	Determines whether compression is advertised in proxies created by the adapter.

SSL Endpoint

Synopsis

ssl ‑h host ‑p port ‑t timeout ‑z

Description

An ssl endpoint supports the following options:

Option	Description	Client Semantics	Server Semantics
‑h host	Specifies the host name or IP address of the endpoint. If not specified, the value of Ice.Default.Host is used instead.	Determines the host name or IP address to which a connection attempt is made. If not specified, the looback interface is used.	Determines the network interface on which the object adapter listens for connections. If not specified, (or specified as ‑h * or ‑h 0.0.0.0), the adapter listens on all network interfaces (including the loopback interface). The endpoints specified by ‑h are published in proxies. If not specified, all endpoints except loopback are published (except if loopback is the only available interface, in which case only loopback is published).
‑p port	Specifies the port number of the endpoint.	Determines the port to which a connection attempt is made (required).	The port will be selected by the operating system if this option is not specified or port is zero.
‑t timeout	Specifies the endpoint timeout in milliseconds.	If timeout is greater than zero, it sets a maximum delay for binding and proxy invocations. If a timeout occurs, the application receives Ice::TimeoutException.	Determines the default timeout that is advertised in proxies created by the object adapter.
‑z	Specifies bzip2 compression.	Determines whether compressed requests are sent.	Determines whether compression is advertised in proxies created by the adapter.

Opaque Endpoint

Synopsis

opaque ‑t type ‑v value

Description

Proxies can contain endpoints that are not universally understood by Ice processes. For example, a proxy can contain an SSL endpoint; if that proxy is marshaled to a receiver without the IceSSL plug-in, the SSL endpoint does not make sense to the receiver.

Ice preserves such unknown endpoints when they are received over the wire. For the preceding example, if the receiver remarshals the proxy and sends it back to an Ice process that does have the IceSSL plug-in, that process can invoke on the proxy using its SSL transport. This mechanism allows proxies containing endpoints for arbitrary transports to pass through processes that do not understand these endpoints without losing information.

If an Ice process stringfies a proxy containing an unknown endpoint, it writes the endpoint as an opaque endpoint. For example:

opaque -t 2 -v CTEyNy4wLjAuMREnAAD/////AA==

This is how a process without the IceSSL plug-in stringifies an SSL endpoint. When a process with the IceSSL plug-in unstringifies this endpoint and converts it back into a string, it produces:

ssl -h 127.0.0.1 -p 10001

An opaque endpoint supports the following options:

Option	Description
‑t type	Specifies the transport for the endpoint. Transports are indicated by positive integers (1 for TCP, 2 for SSL, and 3 for UDP).
‑v value	Specifies the marshaled encoding of the endpoint (including its enclosing encapsulation) in base‑64 encoding..

Exactly one each of the ‑t and ‑v options must be present in an opaque endpoint.