API Reference

STOMP (Simple Text Oriented Messaging Protocol) client library.

A lightweight C library for connecting to and communicating with STOMP message brokers. This library provides asynchronous I/O operations using libuv and supports STOMP protocol version 1.1 features including connect and send.

Author

Logan Kloft

Version

1.0

Date

2025

Enums

enum cstomp_error_t

Error codes returned by CSTOMP functions.

All CSTOMP functions return one of these error codes to indicate success or the type of failure that occurred.

Values:

enumerator CSTOMP_OK

Operation completed successfully

enumerator CSTOMP_ERROR_NULL_POINTER

Null pointer passed as argument

enumerator CSTOMP_ERROR_BUFFER_OVERFLOW

Buffer would overflow

enumerator CSTOMP_ERROR_MEMORY_ALLOCATION

Memory allocation failed

enumerator CSTOMP_ERROR_NETWORK

Network operation failed

enumerator CSTOMP_ERROR_INVALID_FRAME

Invalid STOMP frame format

Functions

static inline int cstomp_set_connect_callback(cstomp_connection_t *connection, void *ctx, void (*on_connect)(void *ctx))

Set connection established callback.

Registers a callback function to be called when the STOMP connection is successfully established and the server sends a CONNECTED frame.

Note

If ctx is provided, on_connect must also be provided

Parameters:

  • connection – Pointer to connection structure

  • ctx – User context to pass to callback (can be NULL)

  • on_connect – Callback function to call on connection (required if ctx is not NULL)

Returns:

CSTOMP_OK on success, error code on failure

static inline int cstomp_set_read_callback(cstomp_connection_t *connection, void *ctx, void (*on_read)(void *ctx, char *buffer, size_t nread))

Set data received callback.

Registers a callback function to be called whenever data is received from the STOMP server on this connection.

Note

If ctx is provided, on_read must also be provided

Parameters:

  • connection – Pointer to connection structure

  • ctx – User context to pass to callback (can be NULL)

  • on_read – Callback function to call when data is received (required if ctx is not NULL)

Returns:

CSTOMP_OK on success, error code on failure

static inline int cstomp_set_write_callback(cstomp_connection_t *connection, void *ctx, void (*on_write)(void *ctx, char *buffer, size_t nwrote))

Set data sent callback.

Registers a callback function to be called when data has been successfully sent to the STOMP server.

Note

If ctx is provided, on_write must also be provided

Parameters:

  • connection – Pointer to connection structure

  • ctx – User context to pass to callback (can be NULL)

  • on_write – Callback function to call when data is sent (required if ctx is not NULL)

Returns:

CSTOMP_OK on success, error code on failure

void cstomp_alloc_callback(uv_handle_t *handle, size_t suggested_size, uv_buf_t *buf)

Memory allocation callback for libuv.

This function is called by libuv when it needs to allocate a buffer for incoming data. It allocates the requested amount of memory and initializes it to zero.

Note

This function prints an error message to stderr if allocation fails

Parameters:

  • handle – The handle that needs the buffer

  • suggested_size – Suggested buffer size from libuv

  • buf – Output buffer structure to fill

static inline int cstomp_get_body(cstomp_frame_t *frame, char **body, size_t *body_size)

Extract body from STOMP frame.

Parses a STOMP frame to locate and extract the message body portion. The body is the content that appears after the header block terminator and before the frame terminator.

Note

The returned body pointer points directly into the frame buffer

Parameters:

  • frame – Pointer to frame structure to parse

  • body – Output pointer to body data (will point into frame buffer)

  • body_size – Output size of body data in bytes

Returns:

CSTOMP_OK on success, error code on failure

void cstomp_on_read(uv_stream_t *client, ssize_t nread, const uv_buf_t *buf)

Callback for data received from server.

This function is called by libuv when data is received from the STOMP server. It handles connection acknowledgment detection and forwards data to user callbacks.

Note

This function automatically detects CONNECTED frames and triggers connection callbacks

Note

Buffer memory is automatically freed after processing

Parameters:

  • client – The stream that received data

  • nread – Number of bytes read (negative on error)

  • buf – Buffer containing received data

void cstomp_on_write(uv_write_t *req, int status)

Callback for data sent to server.

This function is called by libuv when a write operation completes. It extracts the message body and forwards it to user write callbacks, then cleans up allocated resources.

Note

This function automatically frees frame and request memory

Note

Error messages are printed to stderr on write failures

Parameters:

  • req – The write request that completed

  • status – Write operation status (0 on success, negative on error)

static inline cstomp_connection_t *cstomp_connection()

Create a new STOMP connection.

Allocates and initializes a new STOMP connection structure with default values. Sets up the libuv event loop and TCP socket for network operations.

Note

The returned connection must be freed with cstomp_connection_free()

Note

The connection is not yet connected to a server

Returns:

Pointer to new connection structure, or NULL on allocation failure

static inline int cstomp_add_command(cstomp_frame_t *frame, const char *command)

Add command to STOMP frame.

Adds a STOMP protocol command to the beginning of a frame buffer. This must be the first operation when building a new frame.

Parameters:

  • frame – Pointer to frame structure to modify

  • command – STOMP command string (e.g., “CONNECT”, “SEND”)

Returns:

CSTOMP_OK on success, error code on failure

Pre:

Frame buffer must be empty or this will overwrite existing content

Post:

Frame will contain command followed by line terminator and frame terminator

static inline int cstomp_add_header(cstomp_frame_t *frame, const char *key, const char *value)

Add header to STOMP frame.

Adds a key-value header pair to a STOMP frame. Headers must be added after the command and before the body.

Parameters:

  • frame – Pointer to frame structure to modify

  • key – Header key name (must not be empty)

  • value – Header value (must not be empty)

Returns:

CSTOMP_OK on success, error code on failure

Pre:

A command must already be present in the frame

Pre:

Frame must have an empty body (will be preserved)

Post:

New header will be added while preserving existing headers and command

Post:

Empty body will remain at the end of the frame

static inline int cstomp_add_body(cstomp_frame_t *frame, const char *body, size_t body_size)

Add body to STOMP frame.

Adds message body content to a STOMP frame. This should be the final step when building a frame, after command and headers are added.

Note

Body data can contain binary content. If body data contains null bytes, then a content-length header should be added before the body.

Note

The frame terminator will be added after the body content

Parameters:

  • frame – Pointer to frame structure to modify

  • body – Pointer to body data

  • body_size – Size of body data in bytes

Returns:

CSTOMP_OK on success, error code on failure

static inline int cstomp_send_frame(cstomp_connection_t *connection, cstomp_frame_t *frame)

Send STOMP frame to server.

Transmits a complete STOMP frame to the connected server. The frame must be properly formatted with command, headers, and body.

Note

The frame pointer will be freed automatically after sending

Note

Connection must be established before calling this function

Note

This function is asynchronous; use write callbacks to detect completion

Parameters:

  • connection – Pointer to active connection

  • frame – Pointer to frame to send (will be freed after sending)

Returns:

CSTOMP_OK on success, error code on failure

void cstomp_on_connect(uv_connect_t *req, int status)

Callback for connection establishment.

This function is called by libuv when the TCP connection to the STOMP server is established. It starts reading from the socket and sends the initial CONNECT frame with authentication credentials.

Note

This function automatically sends a CONNECT frame with stored credentials

Note

Error messages are printed to stderr on connection failures

Parameters:

  • req – The connection request that completed

  • status – Connection status (0 on success, negative on error)

static inline int cstomp_connection_free(cstomp_connection_t *connection)

Free STOMP connection resources.

Properly cleans up and frees all resources associated with a STOMP connection, including the event loop, socket handles, and connection structure itself.

Note

This function is safe to call with NULL pointer

Note

Connection should be disconnected before calling this function

Parameters:

connection – Pointer to connection to free (can be NULL)

Returns:

CSTOMP_OK always

static inline int cstomp_connect(cstomp_connection_t *connection, const char *destination_ip, const uint16_t destination_port, const char *username, const char *password)

Connect to STOMP server.

Establishes a TCP connection to the specified STOMP server and begins the STOMP protocol handshake. This function starts the event loop and will block until the connection is closed.

Note

Both username and password must be provided together or both must be NULL

Note

This function blocks until the connection is closed

Note

Connection callbacks will be triggered during execution

Parameters:

  • connection – Pointer to initialized connection structure

  • destination_ip – Server IP address or hostname

  • destination_port – Server port number

  • username – Authentication username (can be NULL for anonymous)

  • password – Authentication password (can be NULL for anonymous)

Returns:

CSTOMP_OK on success, error code on failure

static inline int cstomp_send(cstomp_connection_t *connection, const char *destination, const char *message, size_t message_size)

Send message to destination.

Sends a message to the specified destination on the STOMP server. The message will be delivered to any subscribers of that destination.

Note

Connection must be established before sending messages

Note

Message content can include binary data and null bytes

Note

Content-length header will be automatically added

Parameters:

  • connection – Pointer to active connection

  • destination – Destination name (e.g., “/queue/test”, “/topic/news”)

  • message – Pointer to message content

  • message_size – Size of message content in bytes

Returns:

CSTOMP_OK on success, error code on failure

struct cstomp_frame_t
#include <cstomp.h>

STOMP protocol frame structure.

Represents a complete STOMP frame including command, headers, and body. The frame is stored as a contiguous buffer with proper STOMP formatting.

Public Members

char buffer[CSTOMP_FRAME_BUFFER_MAX_SIZE]

Frame data buffer

size_t frame_size

Current size of frame data

struct cstomp_connection_t
#include <cstomp.h>

STOMP connection context.

Contains all state and configuration needed for a STOMP connection, including network socket, authentication credentials, and callback handlers.

Public Members

uv_tcp_t socket

TCP socket handle

char host[CSTOMP_HOST_MAX_LENGTH]

Server hostname or IP

char version[CSTOMP_CONNECTION_VERSION_MAX_LENGTH]

STOMP protocol version

char username[CSTOMP_USERNAME_MAX_LENGTH]

Authentication username

char password[CSTOMP_PASSWORD_MAX_LENGTH]

Authentication password

uint16_t port

Server port number

struct sockaddr_in destination

Server socket address

uv_loop_t *loop

Event loop handle

uv_connect_t *connect

Connection request handle

void (*on_connect)(void *ctx)

Connection established callback

void *on_connect_ctx

Context for connection callback

void (*on_read)(void *ctx, char *buffer, size_t nread)

Data received callback

void *on_read_ctx

Context for read callback

void (*on_write)(void *ctx, char *buffer, size_t nwrote)

Data sent callback

void *on_write_ctx

Context for write callback

struct cstomp_write_t
#include <cstomp.h>

Context passed to write completion callback.

Contains references to the frame that was sent and the connection it was sent on, used by the write completion handler.

Public Members

cstomp_frame_t *frame

Frame that was sent

cstomp_connection_t *connection

Connection frame was sent on