TCP client

The ClientChannel class represents a communication channel for making requests to server devices. The channel presents the same interface regardless of underlying transport. Create a TCP client channel using the create_tcp method.

note

In Rust, you can use spawn_tcp_client_task to create a channel and spawn its task in the current runtime. Otherwise, create_tcp_client_task_with_options returns the Channel and a ClientTask; spawn task.run() when ready.

Rust

let channel = spawn_tcp_client_task(
    HostAddr::ip(endpoint.ip(), endpoint.port()),
    MAX_QUEUED_REQUESTS,
    default_retry_strategy(),
    DecodeLevel::new(
        AppDecodeLevel::DataHeaders,
        FrameDecodeLevel::Nothing,
        PhysDecodeLevel::Nothing,
    ),
    Some(Box::new(ClientStateListener)),
);

C

rodbus_client_channel_t *channel = NULL;
rodbus_decode_level_t decode_level = rodbus_decode_level_build(RODBUS_APP_DECODE_LEVEL_DATA_HEADERS, RODBUS_FRAME_DECODE_LEVEL_NOTHING, RODBUS_PHYS_DECODE_LEVEL_NOTHING);
rodbus_param_error_t err = rodbus_client_channel_create_tcp(runtime,
    host,                         // host
    port,                         // port
    MAX_QUEUED_REQUESTS,          // max queued requests
    rodbus_retry_strategy_init(), // retry delays
    decode_level,                 // decode level
    get_client_state_listener(),  // listener
    &channel
);
if (err) {
    printf("unable to create channel: %s\n", rodbus_param_error_to_string(err));
    return NULL;
}

C++

auto channel = rodbus::ClientChannel::create_tcp(
    runtime,
    endpoint.host,
    endpoint.port,
    MAX_QUEUED_REQUESTS,
    rodbus::RetryStrategy(),
    rodbus::DecodeLevel(rodbus::AppDecodeLevel::data_headers, rodbus::FrameDecodeLevel::nothing, rodbus::PhysDecodeLevel::nothing),
    create_client_state_listener()
);

Java

ClientChannel channel = ClientChannel.createTcp(
        runtime,
        host,
        port,
        ushort(MAX_QUEUED_REQUESTS),
        new RetryStrategy(),
        new DecodeLevel(AppDecodeLevel.DATA_HEADERS, FrameDecodeLevel.NOTHING, PhysDecodeLevel.NOTHING),
        new PrintingClientStateListener()
);

C#

var channel = ClientChannel.CreateTcp(
    runtime,
    host,
    port,
    MaxQueuedRequests,
    new RetryStrategy(),
    new DecodeLevel(AppDecodeLevel.DataHeaders, FrameDecodeLevel.Nothing, PhysDecodeLevel.Nothing),
    new ClientStateListener()
);

Enabling

The channel is created disabled: it doesn't connect until you call enable, and requests made while it has no connection fail with a NoConnection error. Once enabled, it keeps a connection open, reconnecting when it fails. Call disable to close the connection and stop communicating.

Endpoint

The remote endpoint is a host and a port, where the host is an IPv4 address, an IPv6 address, or a DNS name that the library resolves. In Rust, pass a HostAddr, created with HostAddr::ip or HostAddr::dns.

Retry strategy

The RetryStrategy controls how often the client retries. After each failed connection attempt it waits, doubling the wait from min_delay up to max_delay; after an established connection closes, it waits min_delay.

Maximum queued requests

The channel sends one request at a time and queues the rest, up to max_queued_requests. When the queue is full, a request made in the bindings fails with the TOO_MANY_REQUESTS error, while one made in Rust waits for room.

Decode level

See the logging page.

ClientStateListener

The ClientStateListener interface (Listener<ClientState> in Rust) has a single callback that informs your code about the state of the connection: disabled, connecting, connected, waiting to retry after a failed connection attempt or a disconnection, and shut down.