3.2.4 Channels and requests

The ssh2 protocol allows channels to be in various states. Major channel states in assh are: opening, open, half-closed in either direction, closing and released.

The connection protocol also provides the request primitive. Requests may be either global or attached to a channel.

A channel open can be initiated by either side. Once the open message has been acknowledged by the remote host, the channel is a symmetrical data pipe. This means that either side is allowed to send data and close the channel. Replies to channel open messages can be sent out of order.

The assh channel and request API relies on events and functions provided by the connection protocol module for use by the application. These API functions can be called when the related service is running.

Instances of the struct assh_channel_s and struct assh_request_s types are always created and released by the library. All related types and functions are declared in assh/assh_connection.h.

The application may try to open a channel by calling the assh_channel_open function. An struct assh_channel_s object is then allocated but the channel is not open until the open message has been acknowledged by the remote host.

Either an ASSH_EVENT_CHANNEL_CONFIRMATION event or an ASSH_EVENT_CHANNEL_FAILURE event is reported to the application at some point. When opening is denied, the struct assh_channel_s object is released by the library. One of those events is always reported, even when the reply from the remote host has not been received due to a disconnecting session.

When the remote host wants to open a channel, the ASSH_EVENT_CHANNEL_OPEN event is reported. The application has to accept or deny the channel open so that the library can send the appropriate reply.

The channel becomes open if the application acknowledges the event with the ASSH_CONNECTION_REPLY_SUCCESS status. The struct assh_channel_s object is released if the ASSH_CONNECTION_REPLY_FAILED value is used instead.

When the application is not able to decide immediately if the channel has to be opened, it must acknowledges the event with the ASSH_CONNECTION_REPLY_POSTPONED value. This allows replying to channel open messages out of order.

In this case, the application has to call either the assh_channel_open_success_reply function or the assh_channel_open_failed_reply function at some point in order to actually open or release the channel. In the mean time, the ASSH_EVENT_CHANNEL_ABORT event may be reported to indicate that the struct assh_channel_s object will be released before channel open due to a closing session.

Data may be transmitted over an open channel by using the assh_channel_data_alloc and assh_channel_data_send functions.

Any data transmitted by the remote host will be reported by the ASSH_EVENT_CHANNEL_DATA event.

When channel flow control is not delegated to the library, the application must take care of calling the assh_channel_window_adjust function and has to handle the ASSH_EVENT_CHANNEL_WINDOW event.

The application may send requests to the remote host by calling the assh_request function. It may optionally require that the remote host replies to the request. Doing so makes the library reports either an ASSH_EVENT_REQUEST_SUCCESS event or an ASSH_EVENT_REQUEST_FAILURE event. This always occurs, even if the associated channel is closing or the session disconnects.

Incoming requests are reported by the library using the ASSH_EVENT_REQUEST event. As for channel open, assh allows postponing request replies even if this is not actually handled by the protocol. This means that the library has to reorder the replies and a postponed request prevent subsequent request replies from being transmitted. The ASSH_EVENT_REQUEST_ABORT event is reported when the struct assh_request_s object associated to a postponed reply will be released due to a disconnecting session.

The ssh2 protocol allows channels to be closed in a single direction. Once the assh_channel_eof function has been called, it is not possible to send more data over the channel.

When the remote host send an end of file message, the ASSH_EVENT_CHANNEL_EOF event is reported to indicate that no more data will be received but it still possible to send data over the channel.

Half closing the channel in both directions results in the ASSH_EVENT_CHANNEL_CLOSE event being reported.

Once the channel is open, the ASSH_EVENT_CHANNEL_CLOSE event may be reported at any time. The channel is released by the library when this event is acknowledged.

This event is always reported at some point for open channels. This may occurs for multiple reasons, including the application calling the assh_channel_close function or due to a disconnecting session.

Likewise, the ASSH_EVENT_CHANNEL_FAILURE, ASSH_EVENT_CHANNEL_ABORT, ASSH_EVENT_REQUEST_FAILURE and ASSH_EVENT_REQUEST_ABORT events will be properly reported when the session is closing, even if the link with the remote host is broken and no related replies is actually received. This allows the application to implement fewer code paths in order to properly release the private resources it has associated to channels and requests.