.. index:: single: http_websocket_messages(TextRepresentation) .. _http_websocket_messages/1:

.. rst-class:: right

object

`http_websocket_messages(TextRepresentation)`

TextRepresentation - Text representation to be used for text messages and close reasons. Possible values are atom (default), chars, and codes. Transport-neutral WebSocket message predicates built on top of the http_websocket frame layer.
| Availability: | logtalk_load(http_websocket_messages(loader))

| Author: Paulo Moura | Version: 1:0:0 | Date: 2026-06-26

| Compilation flags: | static, context_switching_calls

| Uses: | :ref:`http_websocket_frames <http_websocket_frames/0>` | :ref:`list <list/0>` | :ref:`utf_8 <utf_8/0>`

| Remarks:
- Fragmentation model: This layer reassembles fragmented text and binary messages only when all continuation frames arrive contiguously. Interleaved control frames during fragmented messages raise http_websocket_message_sequence. Use http_websocket_session for RFC 6455 live-stream processing that must surface interleaved control frames while reassembling data messages.
| Inherited public predicates: | (none)

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

Public predicates

.. index:: message/3 .. _http_websocket_messages/1::message/3:

message/3 ^^^^^^^^^^^^^

Constructs a validated normalized WebSocket message term from the message type atom and payload term.

| Compilation flags: | static

| Template: | message(Type,Payload,Message) | Mode and number of proofs: | message(+atom,+term,-compound) - one_or_error

| Exceptions: | Type is not a supported WebSocket message type: | domain_error(http_websocket_message_type,Type) | Payload is not valid for the requested WebSocket message type: | domain_error(http_websocket_message,Message) | Payload is not a valid WebSocket close payload: | domain_error(http_websocket_close_payload,Payload) | Payload contains an invalid WebSocket close code: | domain_error(http_websocket_close_code,Code) | Payload is not valid text for the selected text representation: | domain_error(http_websocket_message_text,Text)

| Remarks:

Type text: Payload is text in the selected text representation.
Type binary: Payload is a list of bytes.
Type ping or pong: Payload is a list of bytes.
Type close: Payload is one of empty, status(Code), or status(Code, Reason).

.. index:: is_message/1 .. _http_websocket_messages/1::is_message/1:

is_message/1 ^^^^^^^^^^^^^^^^

True when the argument is a valid normalized WebSocket message term.

| Compilation flags: | static

| Template: | is_message(Message) | Mode and number of proofs: | is_message(@term) - zero_or_one

.. index:: read_message/2 .. _http_websocket_messages/1::read_message/2:

read_message/2 ^^^^^^^^^^^^^^^^^^

Reads one WebSocket message from a binary stream. Continuation frames are reassembled for text and binary messages when they arrive contiguously. Returns end_of_file when the stream is already exhausted.

| Compilation flags: | static

| Template: | read_message(Stream,Message) | Mode and number of proofs: | read_message(+stream_or_alias,-term) - one_or_error

| Exceptions: | Stream is a variable: | instantiation_error | The inbound frames do not form a valid normalized WebSocket message sequence: | domain_error(http_websocket_message_sequence,Frame) | The inbound frame is invalid: | domain_error(http_websocket_frame,Frame) | The inbound message payload is invalid: | domain_error(http_websocket_message,Message) | The inbound message text is invalid for the selected text representation: | domain_error(http_websocket_message_text,Text)

| Remarks:

Interleaved control frames: Control frames interleaved in the middle of a fragmented data message are not surfaced by this simplified layer and instead raise http_websocket_message_sequence. Use http_websocket_session when interleaved control frames must be handled while a fragmented message is in progress.

.. index:: write_message/2 .. _http_websocket_messages/1::write_message/2:

write_message/2 ^^^^^^^^^^^^^^^^^^^

Writes one validated WebSocket message as a single final frame to a binary stream and flushes the stream.

| Compilation flags: | static

| Template: | write_message(Stream,Message) | Mode and number of proofs: | write_message(+stream_or_alias,+compound) - one_or_error

| Exceptions: | Stream is a variable: | instantiation_error | Message is not a valid normalized WebSocket message term: | domain_error(http_websocket_message,Message) | Message has an unsupported message type: | domain_error(http_websocket_message_type,Type) | Message has an invalid close payload: | domain_error(http_websocket_close_payload,Payload) | Message has invalid text for the selected text representation: | domain_error(http_websocket_message_text,Text)

.. index:: type/2 .. _http_websocket_messages/1::type/2:

type/2 ^^^^^^^^^^

Returns the type atom of a validated WebSocket message term.

| Compilation flags: | static

| Template: | type(Message,Type) | Mode and number of proofs: | type(+compound,-atom) - one_or_error

.. index:: payload/2 .. _http_websocket_messages/1::payload/2:

payload/2 ^^^^^^^^^^^^^

Returns the payload term of a validated WebSocket message term.

| Compilation flags: | static

| Template: | payload(Message,Payload) | Mode and number of proofs: | payload(+compound,-term) - one_or_error

Protected predicates

.. index:: encode_message/4 .. _http_websocket_messages/1::encode_message/4:

encode_message/4 ^^^^^^^^^^^^^^^^^^^^

Protected helper that normalizes a WebSocket message term and returns the normalized term together with the corresponding frame opcode and payload bytes.

| Compilation flags: | static

| Template: | encode_message(Message,NormalizedMessage,Opcode,PayloadBytes) | Mode and number of proofs: | encode_message(+compound,-compound,-atom,-list(byte)) - one_or_error

| Exceptions: | Message is not a valid normalized WebSocket message term: | domain_error(http_websocket_message,Message) | Message has an unsupported message type: | domain_error(http_websocket_message_type,Type) | Message has an invalid close payload: | domain_error(http_websocket_close_payload,Payload) | Message has invalid text for the selected text representation: | domain_error(http_websocket_message_text,Text)

.. index:: decode_message/3 .. _http_websocket_messages/1::decode_message/3:

decode_message/3 ^^^^^^^^^^^^^^^^^^^^

Protected helper that decodes payload bytes for the given message type atom into a normalized WebSocket message term.

| Compilation flags: | static

| Template: | decode_message(Type,PayloadBytes,Message) | Mode and number of proofs: | decode_message(+atom,+list(byte),-compound) - one_or_error

| Exceptions: | Type is not a supported WebSocket message type: | domain_error(http_websocket_message_type,Type) | PayloadBytes is not a valid close payload: | domain_error(http_websocket_close_payload,PayloadBytes) | PayloadBytes contains an invalid close code: | domain_error(http_websocket_close_code,Code) | PayloadBytes does not decode to valid text for the selected text representation: | domain_error(http_websocket_message_text,PayloadBytes)

Private predicates

(no local declarations; see entity ancestors if any)

Operators

(none)