Did you know ... Search Documentation:
Pack logtalk -- logtalk-3.101.0/docs/apis/_sources/http_websocket_client_service_1.rst.txt

.. index:: single: http_websocket_client_service(HTTPTransport) .. _http_websocket_client_service/1:

.. rst-class:: right

object

http_websocket_client_service(HTTPTransport)

Client-side convenience for callback-driven WebSocket sessions with atom text representation, combining the opening handshake, optional initial outbound messages, and the higher-level session loop.

| Availability: | logtalk_load(http_websocket_service(loader))

| Author: Paulo Moura | Version: 1:0:0 | Date: 2026-07-13

| Compilation flags: | static, context_switching_calls

| Extends: | public :ref:`http_websocket_service(HTTPTransport,client,atom) <http_websocket_service/3>` | Uses: | :ref:`http_client <http_client/0>` | :ref:`list <list/0>` | :ref:`user <user/0>`

| Remarks: | (none)

| Inherited public predicates: |  :ref:http_websocket_session/2::initial_state/1  :ref:http_websocket_messages/1::is_message/1  :ref:http_websocket_session/2::is_state/1  :ref:http_websocket_messages/1::message/3  :ref:http_websocket_messages/1::payload/2  :ref:http_websocket_messages/1::read_message/2  :ref:http_websocket_session/2::read_message/4  :ref:http_websocket_session/2::read_message/5  :ref:http_websocket_session/2::read_message/6  :ref:http_websocket_service/3::run_session/3  :ref:http_websocket_service/3::run_session/4  :ref:http_websocket_messages/1::type/2  :ref:http_websocket_session/2::write_message/2  :ref:http_websocket_session/2::write_message/3  :ref:http_websocket_session/2::write_message/4  :ref:http_websocket_session/2::write_message/5  

.. contents:: :local: :backlinks: top

Public predicates

.. index:: open/4 .. _http_websocket_client_service/1::open/4:

open/4 ^^^^^^^^^^

Builds a WebSocket opening handshake from the given absolute WebSocket URL supported by the selected transport parameterization, opens the upgraded connection, optionally writes initial outbound messages, then runs one callback-driven client session loop until the close handshake completes or the peer closes the stream.

| Compilation flags: | static

| Template: | open(URL,Handler,Response,State) | Mode and number of proofs: | open(+atom,+object_identifier,-compound,-compound) - one_or_error

| Exceptions: | URL is a variable: | instantiation_error | URL is not a supported absolute WebSocket URL: | domain_error(http_client_websocket_url,URL) | URL uses an unsupported WebSocket scheme: | domain_error(http_client_websocket_scheme,Scheme) | The WebSocket server rejects the opening handshake version: | domain_error(http_client_websocket_version_rejection,Response) | The WebSocket server rejects authentication: | domain_error(http_client_websocket_authentication_rejection,Response) | The WebSocket server redirects the opening handshake: | domain_error(http_client_websocket_redirection_rejection,Response) | The WebSocket server rejects the opening handshake: | domain_error(http_client_websocket_rejection,Response) | The WebSocket server response is not a valid opening handshake response: | domain_error(http_client_websocket_response,Response) | Handler is a variable: | instantiation_error | Handler is not a valid WebSocket service handler: | domain_error(http_websocket_service_handler,Handler) | The upgraded connection handle is invalid: | domain_error(http_socket_transport_connection,Connection) | The delegated session loop raises a WebSocket session error: | domain_error(http_websocket_session_sequence,Frame) | Handler returns an invalid reply: | domain_error(http_websocket_service_handler_reply,Reply)

.. index:: open/5 .. _http_websocket_client_service/1::open/5:

open/5 ^^^^^^^^^^

Builds a WebSocket opening handshake from the given absolute WebSocket URL supported by the selected transport parameterization, opens the upgraded connection, optionally writes initial outbound messages, then runs one callback-driven client session loop using the given combined handshake and session options.

| Compilation flags: | static

| Template: | open(URL,Handler,Response,State,Options) | Mode and number of proofs: | open(+atom,+object_identifier,-compound,-compound,+list) - one_or_error

| Exceptions: | URL is a variable: | instantiation_error | URL is not a supported absolute WebSocket URL: | domain_error(http_client_websocket_url,URL) | URL uses an unsupported WebSocket scheme: | domain_error(http_client_websocket_scheme,Scheme) | Options is a variable or a partial list: | instantiation_error | Options is neither a variable nor a list: | type_error(list,Options) | Options contains an invalid initial message list: | type_error(list,Messages) | Options contains an invalid initial message: | domain_error(http_websocket_client_service_initial_message,Message) | Options contains an invalid automatic pong setting: | domain_error(http_websocket_client_service_option,auto_pong(Option)) | Options contains an invalid client service option: | domain_error(http_websocket_client_service_option,Option) | Options contains an invalid WebSocket client option: | domain_error(http_client_websocket_option,Option) | Options contains an invalid WebSocket HTTP version: | domain_error(http_client_websocket_version,Version) | Options contains reserved WebSocket headers: | domain_error(http_client_websocket_headers,Headers) | Options contains an invalid WebSocket service loop option: | domain_error(http_websocket_service_option,Option) | Timed session-loop options are not available on this backend: | existence_error(http_websocket_service,timing) | The WebSocket server rejects the opening handshake version: | domain_error(http_client_websocket_version_rejection,Response) | The WebSocket server rejects authentication: | domain_error(http_client_websocket_authentication_rejection,Response) | The WebSocket server redirects the opening handshake: | domain_error(http_client_websocket_redirection_rejection,Response) | The WebSocket server rejects the opening handshake: | domain_error(http_client_websocket_rejection,Response) | The WebSocket server response is not a valid opening handshake response: | domain_error(http_client_websocket_response,Response) | Handler is a variable: | instantiation_error | Handler is not a valid WebSocket service handler: | domain_error(http_websocket_service_handler,Handler) | The upgraded connection handle is invalid: | domain_error(http_socket_transport_connection,Connection) | The delegated session loop raises a WebSocket session error: | domain_error(http_websocket_session_sequence,Frame) | Handler returns an invalid reply: | domain_error(http_websocket_service_handler_reply,Reply)

| Remarks:

  • Repeated options: When the same handshake or session option is given multiple times, the first occurrence is used.
  • Handshake options: The headers/1, query/1, version/1, protocols/1, key/1, and connection_options/1 options are forwarded to open_websocket/4. The accepted URL schemes depend on the selected transport parameterization, e.g. `ws:// for http_socket_transport` and both `ws:// and wss:// for http_process_transport`.
  • Session option auto_pong(on|off): Controls automatic pong replies during the session loop.
  • Session option initial_messages(Messages): Writes the given list of normalized outbound messages before entering the session loop.
  • Session option keepalive_interval(Seconds): Schedules empty ping messages when the peer stays silent for the given positive number of seconds. This option requires backend thread support.
  • Session option idle_timeout(Seconds): Closes the session with status(1001, idle_timeout) after the given positive number of seconds without an inbound message. This option requires backend thread support.
  • Session option max_payload_length(Bytes): Rejects inbound frames whose declared payload length is greater than Bytes before allocating payload storage. Oversized frames are treated as 1009 close errors in the session loop. Use a non-negative integer.

Protected predicates

(no local declarations; see entity ancestors if any)

Private predicates

(no local declarations; see entity ancestors if any)

Operators

(none)