E.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.

Ice uses endpoints for two similar but distinct purposes:

1. In a client context (that is, in a proxy), endpoints determine how Ice estab­lishes a connection to a server.

2. In a server context (that is, in an object adapter’s configuration), endpoints define the addresses and transports over which new incoming connections are accepted. These endpoints are also embedded in the proxies created by the object adapter, unless a separate set of “published” endpoints are explicitly configured.

The sections that follow discuss the addressing component of endpoints, as well as the protocols and their supported options.

Addressing

Synopsis

host : hostname | x.x.x.x (IPv4)
host : hostname | ":x:x:x:x:x:x:x" (IPv6)

Description

Ice supports Internet Protocol (IP) versions 4 and 6 in all language mappings2. Support for these protocols is configured using the properties Ice.IPv4 (enabled by default) and Ice.IPv6 (disabled by default).

In the endpoint descriptions below, the host parameter represents either a host name that is resolved via the Domain Name System (DNS), an IPv4 address in dotted quad notation, or an IPv6 address in 128-bit hexadecimal format and enclosed in double quotes. Due to limitation of the DNS infrastructure, host and domain names are restricted to the ASCII character set.

The presence (or absence) of the host parameter has a significant influence on the behavior of the Ice run time. The table below describes these semantics:

Value	Client Semantics	Server Semantics
None	If host is not specified in a proxy, Ice uses the value of the Ice.Default.Host property. If that property is not defined, out­going connections are only attempted over loopback inter­faces.	If host is not specified in an object adapter endpoint, Ice uses the value of the Ice.Default.Host property. If that property is not defined, the adapter behaves as if the wildcard symbol * was specified (see below).
Host name	The host name is resolved via DNS. Outgoing connections are attempted to each address returned by the DNS query.	The host name is resolved via DNS, and the object adapter lis­tens on the network interfaces corresponding to each address returned by the DNS query. The specified host name is embedded in proxies created by the adapter.
IPv4 address	An outgoing connection is attempted to the given address.	The object adapter listens on the network interface corresponding to the address. The specified address is embedded in proxies created by the adapter.
IPv6 address	An outgoing connection is attempted to the given address.	The object adapter listens on the network interface corresponding to the address. The specified address is embedded in proxies created by the adapter.
0.0.0.0 (IPv4)	A “wildcard” IPv4 address that causes Ice to try all local inter­faces when establishing an out­going connection.	Equivalent to * (see below).
"::" (IPv6)	A “wildcard” IPv6 address that causes Ice to try all local inter­faces when establishing an out­going connection.	Equivalent to * (see below).
* (IPv4, IPv6)	Not supported in proxies.	The adapter listens on all net­work interfaces (including the loopback interface), that is, binds to INADDR_ANY for the enabled protocols (IPv4 and/or IPv6). Endpoints for all addresses except loopback and IPv6 link-local are published in proxies (unless loopback is the only available interface, in which case only loopback is published).   Using Mono, proxies created by an object adapter listening on the IPv6 wildcard address contain only the IPv6 loopback address unless published endpoints are configured.

There is one additional benefit in specifying a wildcard address for host (or not specifying it at all) in an object adapter’s endpoint: if the list of network interfaces on a host may change while the application is running, using a wildcard address for host ensures that the object adapter automatically includes the updated inter­faces. Note however that the list of published endpoints is not changed automati­cally; see page 936 for more information. For diagnostic purposes, you can set the configuration property Ice.Trace.Network=3 to cause Ice to log the current list of local addresses that it is substituting for the wildcard address.

When IPv4 and IPv6 are enabled, an object adapter endpoint that uses an IPv6 (or wildcard) address can accept both IPv4 and IPv6 connections. This is true for all supported platforms except Windows XP and Windows Server 2003, where you must define separate IPv4 and IPv6 endpoints if you want the object adapter to accept both types of connections.

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.	See page 1960.	See page 1960.
‑p port	Specifies the port number of the end­point.	Determines the port to which a connec­tion 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 end­point timeout in milliseconds.	If timeout is greater than zero, it specifies the time­out used by the cli­ent to open or close connections and to read or write data. It also specifies how long the run time waits for an invoca­tion to complete. If a timeout occurs, the application receives Ice::TimeoutException.	If timeout is greater than zero, it specifies the time­out used by the server to accept or close connections and to read or write data (see page 936 and Section 32.13). timeout also con­trols the timeout that is published in proxies created by the object adapter.
‑z	Specifies bzip2 compression.	Determines whether com­pressed requests are sent.	Determines whether compres­sion is advertised in proxies created by the adapter.

UDP Endpoint

Synopsis

udp ‑v major.minor ‑e major.minor ‑h host ‑p port ‑z --ttl TTL
    --interface INTF

Description

A udp endpoint supports either unicast or multicast delivery; the address resolved by the host argument determines the delivery mode. To use multicast in IPv4, select an IP address in the range 233.0.0.0 to 239.255.255.255. In IPv6, use an address that begins with ff, such as ff01::1:1.

A udp endpoint supports the following options:

Option	Description	Client Semantics	Server Semantics
‑v major.minor	Specifies the protocol major and highest minor version num­ber to be used for this endpoint. If not spec­ified, the protocol major version and highest supported minor version of the client-side Ice run time is used.	Determines the pro­tocol major version and highest minor version used by the client side when sending messages to this endpoint. The protocol major ver­sion number must match the protocol major version num­ber of the server; the protocol minor ver­sion number must not be higher than the highest minor version number supported by the server.	Determines the pro­tocol major version and highest minor version advertised by the server side for this endpoint. The protocol major ver­sion number must match the protocol major version num­ber of the server; the protocol minor ver­sion number must not be higher than the highest minor version number supported by the server.
‑e major.minor	Specifies the encod­ing major and highest minor version num­ber to be used for this endpoint. If not spec­ified, the encoding major version and highest supported minor version of the client-side Ice run time is used.	Determines the encoding major ver­sion and highest minor version used by the client side when sending mes­sages to this end­point. The encoding major version num­ber must match the encoding major ver­sion number of the server; the encoding minor version num­ber must not be higher than the high­est minor version number supported by the server.	Determines the encoding version and highest minor version advertised by the server side for this endpoint. The proto­col major version number must match the protocol major version number of the server; the proto­col minor version number must not be higher than the high­est 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.	See page 1960.	See page 1960.
‑p port	Specifies the port number of the end­point.	Determines the port to which datagrams are sent (required).	The port will be selected by the oper­ating system if this option is not speci­fied or port is zero.
‑z	Specifies bzip2 com­pression.	Determines whether compressed requests are sent.	Determines whether compression is advertised in proxies created by the adapter.
‑-ttl TTL	Specifies the time-to-live (also known as “hops”) of multicast messages.	Determines whether multicast messages are forwarded beyond the local net­work. If not speci­fied, or the value of TTL is -1, multicast messages are not for­warded. The maxi­mum value is 255.	N/A
‑-inte rface INTF	Specifies the network interface or group for multicast messages (see below).	Selects the network interface for outgo­ing multicast mes­sages. If not specified, multicast messages are sent using the default interface.	Selects the network interface to use when joining the multicast group. If not speci­fied, the group is joined on the default network interface.

Multicast Interfaces

When host denotes a multicast address, the --interface INTF option selects a particular network interface to be used for communication. The format of INTF depends on the language and IP version:

• C++ and .NET (IPv4)

INTF can be an interface name, such as eth0, or an IP address. Interface names on Windows may contain spaces, such as Local Area Connection, therefore they must be enclosed in double quotes.

• C++ and .NET (IPv6)

INTF can be an interface name, such as eth0, or an interface index.

• Java

INTF can be an interface name, such as eth0, or an IP address. On Windows, Java maps interface names to Unix-style nicknames.

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.	See page 1960.	See page 1960.
‑p port	Specifies the port number of the end­point.	Determines the port to which a connec­tion 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 end­point timeout in milliseconds.	If timeout is greater than zero, it specifies the time­out used by the cli­ent to open or close connections and to read or write data. It also specifies how long the run time waits for an invoca­tion to complete. If a timeout occurs, the application receives Ice::TimeoutException.	If timeout is greater than zero, it specifies the time­out used by the server to accept or close connections and to read or write data (see page 936 and Section 32.13). timeout also con­trols the timeout that is published in proxies created by the object adapter.
‑z	Specifies bzip2 compression.	Determines whether com­pressed requests are sent.	Determines whether compres­sion 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 stringifies 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.

---

1

See Section 32.4.6 for examples.

2

IPv6 is not supported when using Ice for Java on Windows due to a limitation in the JVM.