object

# `stomp`

Portable STOMP 1.2 (Simple Text Orientated Messaging Protocol) client. Uses the sockets library for TCP communication.

Availability:
`logtalk_load(stomp(loader))`
Author: Paulo Moura
Version: 1:1:0
Date: 2026-06-16
Compilation flags:
`static, context_switching_calls`
Imports:
`public` options
Uses:
list
socket
term_io
user
uuid(Representation)
Remarks:

> - Supported backends: ECLiPSe, GNU Prolog, SICStus Prolog, and SWI-Prolog (same as the sockets library).

> - Protocol version: Implements STOMP 1.2 specification.

> - Heartbeat: Supports heartbeat negotiation. Automatic heartbeat sending is not implemented; use send_heartbeat/1 manually if needed.

> - Subscriptions: Supports multiple concurrent subscriptions with unique IDs.

> - Transactions: Supports STOMP transactions with BEGIN, COMMIT, and ABORT.

> - Frame encoding: Properly encodes/decodes header values according to STOMP 1.2 escaping rules.

Inherited public predicates:
check_option/1 check_options/1 default_option/1 default_options/1 option/2 option/3 valid_option/1 valid_options/1

## Public predicates

### `connect/4`

Connects to a STOMP server and performs the STOMP handshake. Returns a connection handle for subsequent operations.

Compilation flags:
`static`
Template:
`connect(Host,Port,Connection,Options)`
Mode and number of proofs:
`connect(+atom,+integer,--compound,+list)` - `one_or_error`
Exceptions:
Connection refused or network error:
`stomp_error(connection_failed)`
Server rejected connection:
`stomp_error(protocol_error(Message))`
Remarks:

> - Option login(Login): Username for authentication.

> - Option passcode(Passcode): Password for authentication.

> - Option host(VirtualHost): Virtual host name. Defaults to the Host parameter.

> - Option heartbeat(ClientMs, ServerMs): Heartbeat timing in milliseconds. Default is 0,0 (no heartbeat).

### `disconnect/2`

Gracefully disconnects from the STOMP server. Sends DISCONNECT frame and waits for RECEIPT if requested.

Compilation flags:
`static`
Template:
`disconnect(Connection,Options)`
Mode and number of proofs:
`disconnect(+compound,+list)` - `one_or_error`
Exceptions:
`Connection` is not a valid STOMP connection handle:
`error`
Remarks:

> - Option receipt(ReceiptId): Request receipt confirmation. Automatically generated if not specified.

### `connection_alive/1`

Checks if the connection is still open and valid.

Compilation flags:
`static`
Template:
`connection_alive(Connection)`
Mode and number of proofs:
`connection_alive(+compound)` - `zero_or_one`

### `send/4`

Sends a message to the specified destination.

Compilation flags:
`static`
Template:
`send(Connection,Destination,Body,Options)`
Mode and number of proofs:
`send(+compound,+atom,+term,+list)` - `one_or_error`
Exceptions:
`Connection` is invalid, `Body` cannot be encoded, or the SEND frame cannot be transmitted:
`stomp_error(error)`
Remarks:

> - Option content_type(MimeType): MIME type of the body.

> - Option content_length(Length): Body length in bytes. Auto-calculated if omitted for atom/string bodies.

> - Option transaction(TransactionId): Include message in the named transaction.

> - Option receipt(ReceiptId): Request receipt confirmation.

> - Option header(Name, Value): Add custom header (can be repeated).

### `subscribe/4`

Subscribes to a destination to receive messages.

Compilation flags:
`static`
Template:
`subscribe(Connection,Destination,SubscriptionId,Options)`
Mode and number of proofs:
`subscribe(+compound,+atom,+atom,+list)` - `one_or_error`
Exceptions:
`Connection` is invalid, the acknowledgment mode is unsupported, or the SUBSCRIBE frame cannot be transmitted:
`stomp_error(error)`
Remarks:

> - Option ack(Mode): Acknowledgment mode: auto (default), client, or client_individual.

### `unsubscribe/3`

Unsubscribes from a destination.

Compilation flags:
`static`
Template:
`unsubscribe(Connection,SubscriptionId,Options)`
Mode and number of proofs:
`unsubscribe(+compound,+atom,+list)` - `one_or_error`
Exceptions:
`Connection` is invalid or the UNSUBSCRIBE frame cannot be transmitted:
`stomp_error(error)`

### `receive/3`

Receives a frame from the server. Returns MESSAGE, RECEIPT, or ERROR frames.

Compilation flags:
`static`
Template:
`receive(Connection,Frame,Options)`
Mode and number of proofs:
`receive(+compound,-compound,+list)` - `zero_or_one_or_error`
Exceptions:
`Connection` is invalid or the input stream does not contain a valid STOMP frame within the requested timeout:
`error`
Remarks:

> - Option timeout(Milliseconds): Timeout in milliseconds. 0 for non-blocking, -1 for infinite wait. Default is -1.

### `ack/3`

Acknowledges receipt of a message.

Compilation flags:
`static`
Template:
`ack(Connection,AckId,Options)`
Mode and number of proofs:
`ack(+compound,+atom,+list)` - `one_or_error`
Exceptions:
`Connection` is invalid or the ACK frame cannot be transmitted:
`stomp_error(error)`
Remarks:

> - Option transaction(TransactionId): Include acknowledgment in the named transaction.

### `nack/3`

Negatively acknowledges a message (tells server the message was not consumed).

Compilation flags:
`static`
Template:
`nack(Connection,AckId,Options)`
Mode and number of proofs:
`nack(+compound,+atom,+list)` - `one_or_error`
Exceptions:
`Connection` is invalid or the NACK frame cannot be transmitted:
`stomp_error(error)`
Remarks:

> - Option transaction(TransactionId): Include negative acknowledgment in the named transaction.

### `begin_transaction/3`

Begins a new transaction.

Compilation flags:
`static`
Template:
`begin_transaction(Connection,TransactionId,Options)`
Mode and number of proofs:
`begin_transaction(+compound,+atom,+list)` - `one_or_error`
Exceptions:
`Connection` is invalid or the BEGIN frame cannot be transmitted:
`stomp_error(error)`

### `commit_transaction/3`

Commits a transaction, making all its operations permanent.

Compilation flags:
`static`
Template:
`commit_transaction(Connection,TransactionId,Options)`
Mode and number of proofs:
`commit_transaction(+compound,+atom,+list)` - `one_or_error`
Exceptions:
`Connection` is invalid or the COMMIT frame cannot be transmitted:
`stomp_error(error)`

### `abort_transaction/3`

Aborts a transaction, rolling back all its operations.

Compilation flags:
`static`
Template:
`abort_transaction(Connection,TransactionId,Options)`
Mode and number of proofs:
`abort_transaction(+compound,+atom,+list)` - `one_or_error`
Exceptions:
`Connection` is invalid or the ABORT frame cannot be transmitted:
`stomp_error(error)`

### `send_heartbeat/1`

Sends a heartbeat (EOL) to the server to keep the connection alive.

Compilation flags:
`static`
Template:
`send_heartbeat(Connection)`
Mode and number of proofs:
`send_heartbeat(+compound)` - `one_or_error`
Exceptions:
`Connection` is invalid or the heartbeat cannot be written to the output stream:
`stomp_error(error)`

### `frame_command/2`

Extracts the command from a frame.

Compilation flags:
`static`
Template:
`frame_command(Frame,Command)`
Mode and number of proofs:
`frame_command(+compound,-atom)` - `one`

### `frame_header/3`

Extracts a header value from a frame. Fails if header is not present.

Compilation flags:
`static`
Template:
`frame_header(Frame,HeaderName,Value)`
Mode and number of proofs:
`frame_header(+compound,+atom,-atom)` - `zero_or_one`

### `frame_headers/2`

Extracts all headers from a frame as a list of Name-Value pairs.

Compilation flags:
`static`
Template:
`frame_headers(Frame,Headers)`
Mode and number of proofs:
`frame_headers(+compound,-list)` - `one`

### `frame_body/2`

Extracts the body from a frame. Returns empty atom if no body.

Compilation flags:
`static`
Template:
`frame_body(Frame,Body)`
Mode and number of proofs:
`frame_body(+compound,-term)` - `one`

## Protected predicates

(no local declarations; see entity ancestors if any)

## Private predicates

(no local declarations; see entity ancestors if any)

## Operators

(none)