---
title: "Endpoint Syntax"
url: https://docs.zeroc.com/ice/3.8/runtime/endpoint-syntax
language: cpp
docs_index: https://docs.zeroc.com/llms.txt
---

> For an index of every page, see [llms.txt](https://docs.zeroc.com/llms.txt).

# Endpoint Syntax

Programming language: C++. Other languages: [C#](https://docs.zeroc.com/ice/3.8/runtime/endpoint-syntax/csharp.md), [Java](https://docs.zeroc.com/ice/3.8/runtime/endpoint-syntax/java.md), [JavaScript](https://docs.zeroc.com/ice/3.8/runtime/endpoint-syntax/js.md), [MATLAB](https://docs.zeroc.com/ice/3.8/runtime/endpoint-syntax/matlab.md), [PHP](https://docs.zeroc.com/ice/3.8/runtime/endpoint-syntax/php.md), [Python](https://docs.zeroc.com/ice/3.8/runtime/endpoint-syntax/python.md), [Ruby](https://docs.zeroc.com/ice/3.8/runtime/endpoint-syntax/ruby.md), [Swift](https://docs.zeroc.com/ice/3.8/runtime/endpoint-syntax/swift.md).

Ice uses endpoints for two similar but distinct purposes:

1. In a client context (that is, in a proxy), endpoints determine how Ice establishes a connection to a server.
2. In a server context (that is, in an object adapter's configuration), endpoints define the addresses and transport protocols over which new incoming connections are accepted.

> **Tip**
>
> Endpoint is an overloaded term - many things are “endpoints”. Think of an Ice endpoint as a “server address”. Not so coincidentally, that’s the term we’ve adopted for IceRPC.

This page presents the addressing component of endpoints, as well as the transport protocols and their options.

## Endpoint List Syntax

### Synopsis {#endpoint-list-synopsis}

`endpoint : endpoint`

### Description {#endpoint-list-description}

An endpoint list comprises one or more endpoints separated by a colon (`:`).

An endpoint has the following format:

`transport option`

`transport` can be any of the Ice transport protocols described on this page (`tcp`, `ssl`, `udp` etc.), or `default`. When `default` is used, it is replaced by the value of the [Ice.Default.Protocol](https://docs.zeroc.com/ice/3.8/property-reference/ice-default-properties/cpp.md#ice.default.protocol) property (default protocol means default *transport* protocol). If an endpoint is malformed, the application receives a `ParseException`. If the transport of an endpoint is not registered with the communicator, an object adapter throws `ParseException` when it parses its endpoints, whereas Ice drops the endpoint from a [stringified proxy](https://docs.zeroc.com/ice/3.8/runtime/invocation/syntax-for-stringified-proxies.md).

> **Note**
>
> See [Object Adapter Endpoints](https://docs.zeroc.com/ice/3.8/runtime/dispatch/object-adapter-endpoints/cpp.md) for examples.

### IP Address Syntax

#### Synopsis {#ip-address-synopsis}

`host : hostname | x.x.x.x | ":x:x:x:x:x:x:x"`

#### Description {#ip-address-description}

Ice supports Internet Protocol (IP) versions 4 and 6. Both are enabled by default; you can disable one of them with the [Ice.IPv4](https://docs.zeroc.com/ice/3.8/property-reference/ice-properties/cpp.md#ice.ipv4) or [Ice.IPv6](https://docs.zeroc.com/ice/3.8/property-reference/ice-properties/cpp.md#ice.ipv6) property. When it resolves a host name, Ice tries the IPv4 addresses before the IPv6 addresses, unless [Ice.PreferIPv6Address](https://docs.zeroc.com/ice/3.8/property-reference/ice-properties/cpp.md#ice.preferipv6address) is set to `1`. These properties are not available in JavaScript.

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 runtime. 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, outgoing connections are attempted over loopback addresses. | 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 proxy resolves the host name via DNS and tries each returned address in turn until a connection succeeds. | The object adapter resolves the host name via DNS and listens on the network interface corresponding to each address returned by the DNS query. You should avoid using DNS names in object adapter endpoints. |
| IPv4 address | An outgoing connection is attempted to the given address. | The object adapter listens on the network interface corresponding to the address. |
| IPv6 address | An outgoing connection is attempted to the given address. | The object adapter listens on the network interface corresponding to the address. |
| `0.0.0.0` (IPv4) | A "wildcard" IPv4 address that causes Ice to try all local interfaces when establishing an outgoing connection. | The adapter listens on all IPv4 network interfaces (including the loopback interface), that is, binds to INADDR\_ANY for IPv4. |
| `"::"` (IPv6) | A "wildcard" IPv6 address that causes Ice to try all local interfaces when establishing an outgoing connection. | Equivalent to \* (see below). |
| `*` (IPv4, IPv6) | Not supported in proxies. | The adapter listens on all network interfaces (including the loopback interface), that is, binds to INADDR\_ANY for the enabled transport protocols (IPv4 and/or IPv6). |

When IPv4 and IPv6 are enabled, an object adapter endpoint that uses an IPv6 (or \* wildcard) address can accept both IPv4 and IPv6 connections.

### TCP Endpoint Syntax

#### Synopsis {#tcp-synopsis}

`tcp -h host -p port -z --sourceAddress addr`

#### Availability {#tcp-availability}

The TCP transport protocol is a built-in transport protocol: it's always available.

#### Description {#tcp-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 [IP Address Syntax](#ip-address-syntax). | See [IP Address Syntax](#ip-address-syntax). |
| `-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 `0`. |
| `-z` | Specifies bzip2 compression. | Determines whether requests are compressed during sending. | Determines whether compression is advertised in proxies created by the adapter. |
| `--sourceAddress ADDR` | Specifies the source address of the connection. | The value for `ADDR` must be a numeric IPv4 or IPv6 address. If this option is not specified, it defaults to the value of [Ice.Default.SourceAddress](https://docs.zeroc.com/ice/3.8/property-reference/ice-default-properties/cpp.md#ice.default.sourceaddress). Ice binds the socket to `ADDR` before connecting. | Not supported |

### UDP Endpoint Syntax

#### Synopsis {#udp-synopsis}

`udp -h host -p port -z --ttl TTL --interface INTF --sourceAddress addr`

#### Availability {#udp-availability}

The UDP transport protocol is a built-in transport protocol that is always available.

If you’re using C++ with a static build, you need to load this transport explicitly as follows:

```cpp
Ice::InitializationData initData;
initData.properties = Ice::createProperties(argc, argv);
initData.pluginFactories = {Ice::udpPluginFactory()};

Ice::CommunicatorPtr communicator = Ice::initialize(initData);
```

#### Description {#udp-description}

A `udp` endpoint supports either unicast or multicast delivery; the address resolved by `host` argument determines the delivery mode. To use multicast in IPv4, select an IP address in the range `224.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 |
| --- | --- | --- | --- |
| `-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 [IP Address Syntax](#ip-address-syntax). | See [IP Address Syntax](#ip-address-syntax). |
| `-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 `0`. |
| `-z` | Specifies bzip2 compression. | Determines whether requests are compressed during sending. | 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 network. If not specified, or the value of `TTL` is `-1`, multicast messages are not forwarded. The maximum value is `255`. | N/A |
| `--interface` `INTF` | Specifies the network interface or group for multicast messages (see below). | Selects the network interface for outgoing multicast messages. If not specified, multicast messages are sent using the default interface. | Selects the network interface to use when joining the multicast group. If set to \* or not specified, the group is joined on all the local network interfaces. |
| `--sourceAddress ADDR` | Specifies the source address of the connection. | The value for `ADDR` must be a numeric IPv4 or IPv6 address. If this option is not specified, it defaults to the value of [Ice.Default.SourceAddress](https://docs.zeroc.com/ice/3.8/property-reference/ice-default-properties/cpp.md#ice.default.sourceaddress). Ice binds the socket to `ADDR` before connecting. | Not supported |

#### 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 `INTF` can be an interface name, such as `eth0`, or an IP address. If using IPv6, it can also be an interface index. Interface names on Windows may contain spaces, such as `Local Area Connection`, therefore they must be enclosed in double quotes.
- 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 Syntax

#### Synopsis {#ssl-synopsis}

`ssl -h host -p port -z --sourceAddress addr`

#### Description {#ssl-description}

An `ssl` endpoint supports the same options as for [tcp endpoints](#tcp-endpoint-syntax).

### WS Endpoint Syntax

#### Synopsis {#ws-synopsis}

`ws -r resource -h host -p port -z --sourceAddress addr`

#### Description {#ws-description}

A `ws` (WebSocket) endpoint supports all [tcp endpoint](#tcp-endpoint-syntax) options in addition to the following:

| Option | Description | Client Semantics | Server Semantics |
| --- | --- | --- | --- |
| `-r` `resource` | A URI specifying the resource associated with this endpoint. If not specified, the default value is `/`. | The value for `resource` is passed as the target for `GET` in the WebSocket upgrade request. | The web server configuration must direct the given `resource` to this endpoint. |

An object adapter with `ws` or `wss` endpoints can check the `Origin` header of WebSocket upgrade requests against the [adapter.AllowedOrigins](https://docs.zeroc.com/ice/3.8/property-reference/object-adapter-properties/cpp.md#adapter.allowedorigins) property.

If you’re using C++ with a static build, you need to load the WebSocket transports (`ws` and `wss`) explicitly as follows:

```cpp
Ice::InitializationData initData;
initData.properties = Ice::createProperties(argc, argv);
initData.pluginFactories = {Ice::wsPluginFactory()};

Ice::CommunicatorPtr communicator = Ice::initialize(initData);
```

### WSS Endpoint Syntax

#### Synopsis {#wss-synopsis}

`wss -r resource -h host -p port -z --sourceAddress addr`

#### Description {#wss-description}

A `wss` (Secure WebSocket) endpoint supports all [ssl endpoint](#ssl-endpoint-syntax) options in addition to the following:

| Option | Description | Client Semantics | Server Semantics |
| --- | --- | --- | --- |
| `-r` `resource` | A URI specifying the resource associated with this endpoint. If not specified, the default value is `/`. | The value for `resource` is passed as the target for `GET` in the WebSocket upgrade request. | The web server configuration must direct the given `resource` to this endpoint. |

If you’re using C++ with a static build, the WebSocket plug-in loaded above for `ws` endpoints provides `wss` as well.

### Bluetooth Endpoint Syntax

#### Synopsis {#bluetooth-synopsis}

`bt -a addr -u uuid -c channel -z --name name` `bts -a addr -u uuid -c channel -z --name name`

#### Availability {#bluetooth-availability}

The Bluetooth transport protocol is provided by a separate [IceBT plug-in](https://docs.zeroc.com/ice/3.8/plugins/icebt/cpp.md).

#### Description {#bluetooth-description}

The [IceBT](https://docs.zeroc.com/ice/3.8/plugins/icebt/cpp.md) transport plug-in enables `bt` endpoints and TLS-protected `bts` endpoints. Configure TLS using the [SSL transport](https://docs.zeroc.com/ice/3.8/runtime/ssl-transport/cpp.md) settings for your language mapping. A Bluetooth endpoint supports the following options:

| Option | Description | Client Semantics | Server Semantics |
| --- | --- | --- | --- |
| `-a` `addr` | Specifies the Bluetooth device address in the form `xx:xx:xx:xx:xx:xx`. The address must be enclosed in double quotes because the colon (`:`) character is also a separator in the endpoint syntax. If not specified, the value of `Ice.Default.Host` is used instead. | Selects the device to connect to. `*` is not valid in a proxy endpoint: parsing `-a *` in a proxy endpoint throws `ParseException`. | On Linux, the plug-in uses the address to select the Bluetooth adapter on which to listen for new connections. If no address is specified via the `-a` option or `Ice.Default.Host`, the plug-in uses the system's default adapter. On Android, the plug-in ignores this setting and always uses the system's default adapter. In addition to a Bluetooth device address, `addr` can also be `*` (e.g., `bt -a * ...`) to force the endpoint to use the system's default adapter without having to specify its address directly. The plug-in ignores the setting for `Ice.Default.Host` in this case. |
| `-u uuid` | Specifies the UUID of a service. | A UUID is required for proxy endpoints: parsing a proxy endpoint without `-u` throws `ParseException`. The plug-in uses the UUID to search for a matching service at the specified device address. | A UUID is optional (but recommended) for object adapter endpoints. If this option is not specified, the plug-in generates a random UUID. The plug-in registers the service with its UUID in the local SDP registry so that clients can locate it. |
| `-c` `channel` | Specifies the RFCOMM channel number of the endpoint. | Not supported in proxy endpoints – the plug-in always uses the service UUID to connect to a server. | This setting is optional on Linux. The value for `channel` must be in the range `0` to `30`. An available channel will be selected automatically if this setting is not specified or `channel` is `0`. This setting is ignored on Android – the system always selects the channel. |
| `-z` | Specifies bzip2 compression. | Determines whether requests are compressed during sending. | Determines whether compression is advertised in proxies created by the adapter. |
| `--name name` | Specifies the service name. | Ignored in proxy endpoints. | Associates a human-friendly name with the service's entry in the SDP registry. If not specified, the default name is `Ice Service`. |

### iAP Endpoint Syntax

#### Synopsis {#iap-synopsis}

`iap -p protocol -n name -m manufacturer -o model number -z` `iaps -p protocol -n name -m manufacturer -o model number -z`

#### Availability {#iap-availability}

The iAP transport protocol is provided by the [IceIAP plug-in](https://docs.zeroc.com/ice/3.8/plugins/iceiap/cpp.md), which is part of the Ice library for iOS, and is available to C++ and Swift applications.

A C++ application installs the iAP transport by adding its plug-in factory to the communicator's initialization data:

```cpp
Ice::InitializationData initData;
initData.properties = Ice::createProperties(argc, argv);
initData.pluginFactories = {Ice::iapPluginFactory()};

Ice::CommunicatorPtr communicator = Ice::initialize(initData);
```

#### Description {#iap-description}

The iAP transport protocol allows applications running on iOS to communicate with accessories connected to the iOS device either through Bluetooth or the lightning connector. The iAP transport protocol is a client-side transport protocol: there's no server-side support. An iAP endpoint supports the following options to allow selecting the accessory to connect to:

| Option | Description | Client Semantics |
| --- | --- | --- |
| `-p` `protocol` | Specifies the protocol implemented by the accessory. | The iAP transport protocol will only connect to accessories that advertise the specified iAP protocol. The default value for protocol is `com.zeroc.ice`. |
| `-n name` | Specifies the name of the accessory. | When specified, the iAP transport protocol will only connect to accessories that match the specified accessory name. |
| `-m` `manufacturer` | Specifies the manufacturer of the accessory. | When specified, the iAP transport protocol will only connect to accessories that match the specified accessory manufacturer. |
| `-o` `model number` | Specifies the model number of the accessory. | When specified, the iAP transport protocol will only connect to accessories that match the specified accessory model number. |
| -z | Specifies bzip2 compression. | Determines whether requests are compressed during sending. |

### Opaque Endpoint Syntax

#### Synopsis {#opaque-synopsis}

`opaque -t type -e encoding -v value`

#### Description {#opaque-description}

Proxies can contain endpoints that are not universally understood by Ice processes. For example, a proxy can contain an endpoint for a transport that the receiver does not know.

Ice preserves such unknown endpoints when they are received over the wire. If an Ice process stringifies a proxy containing an unknown endpoint, it writes the endpoint as an opaque endpoint.

An `opaque` endpoint supports the following options:

| Option | Description |
| --- | --- |
| `-t` `type` | Specifies the endpoint type (also known as transport code) for the endpoint. TCP is `1`, SSL is `2`, UDP is `3`, etc. |
| `-e encoding` | Specifies the encoding version of the endpoint's marshaled data. |
| `-v` `value` | Specifies the marshaled encoding of the endpoint in base-64 encoding. |

Exactly one each of the `-t` and `-v` options must be present in an opaque endpoint. If `-e` is not specified, the encoding version is `1.0`.

## See Also

- [Syntax for Stringified Proxies](https://docs.zeroc.com/ice/3.8/runtime/invocation/syntax-for-stringified-proxies.md)
- [Object Adapter Endpoints](https://docs.zeroc.com/ice/3.8/runtime/dispatch/object-adapter-endpoints/cpp.md)
