NATS client interface. More...

#include <cwist/sys/err/cwist_err.h>
#include <stddef.h>

Include dependency graph for cwist_nats.h:

This graph shows which files directly or indirectly include this file:

Typedefs
typedef struct cwist_nats	cwist_nats_t

typedef struct __natsConnection	natsConnection

typedef void(*	cwist_nats_msg_cb) (const char subject, const char data, size_t len, void *ctx)

Functions
cwist_error_t	cwist_nats_connect (cwist_nats_t *nats, const char url)
	Connect to a NATS server.

cwist_error_t	cwist_nats_subscribe (cwist_nats_t nats, const char subject, cwist_nats_msg_cb cb, void *ctx)
	Subscribe to a subject.

cwist_error_t	cwist_nats_publish_string (cwist_nats_t nats, const char subject, const char *data)
	Publish a string message.

void	cwist_nats_dispatch (cwist_nats_t *nats)
	Dispatch incoming messages.

void	cwist_nats_destroy (cwist_nats_t *nats)
	Disconnect and destroy the NATS handle.

natsConnection *	cwist_nats_native (cwist_nats_t *nats)
	Borrow the underlying cnats connection.

Detailed Description

NATS client interface.

Definition in file cwist_nats.h.

Typedef Documentation

◆ cwist_nats_msg_cb

typedef void(* cwist_nats_msg_cb) (const char *subject, const char *data, size_t len, void *ctx)

Definition at line 20 of file cwist_nats.h.

◆ cwist_nats_t

typedef struct cwist_nats cwist_nats_t

Definition at line 16 of file cwist_nats.h.

◆ natsConnection

typedef struct __natsConnection natsConnection

Definition at line 18 of file cwist_nats.h.

Function Documentation

◆ cwist_nats_connect()

cwist_error_t cwist_nats_connect	(	cwist_nats_t **	nats,
		const char *	url
	)

Connect to a NATS server.

Allocates a cwist_nats_t and connects to the given URL, or to the NATS default URL when url is NULL.

Parameters

[out]	nats	Receives the new handle on success; must not be NULL.
	url	Server URL, or NULL for the default server.

Returns: cwist_error_t with err_i16 set to 0 on success, CWIST_ERROR_INVALID_PARAM if nats is NULL, CWIST_ERROR_NOMEM on allocation failure, or the natsStatus code on connection failure.

Definition at line 56 of file cwist_nats.c.

References cap, cwist_alloc(), CWIST_ERR_INT16, CWIST_ERROR_INVALID_PARAM, CWIST_ERROR_NOMEM, cwist_free(), and make_error().

◆ cwist_nats_destroy()

void cwist_nats_destroy ( cwist_nats_t * nats )

Disconnect and destroy the NATS handle.

Unsubscribes and disconnects if still active, then frees the handle. Safe to call with NULL; the handle must not be used afterwards.

Parameters

nats	Handle to destroy, or NULL.

Definition at line 161 of file cwist_nats.c.

References cap, and cwist_free().

◆ cwist_nats_dispatch()

void cwist_nats_dispatch ( cwist_nats_t * nats )

Dispatch incoming messages.

Flushes the connection, pushing buffered outgoing messages and processing incoming traffic so delivered callbacks can run. Safe to call with a NULL or disconnected handle; such calls are no-ops.

Parameters

nats	Handle to flush, or NULL.

Definition at line 148 of file cwist_nats.c.

References cap.

◆ cwist_nats_native()

natsConnection * cwist_nats_native ( cwist_nats_t * nats )

Borrow the underlying cnats connection.

Supported since v3.8. Used by opt-in extensions built on top of the bundled cnats client (e.g. the durable job queue's JetStream backend). Ownership stays with the cwist_nats_t handle; do not destroy the returned connection.

Borrow the underlying cnats connection.

The returned pointer is owned by the handle and remains valid until cwist_nats_destroy is called.

Parameters

nats	Handle to query, or NULL.

Returns: The native natsConnection, or NULL if nats is NULL.

Definition at line 180 of file cwist_nats.c.

References cap.

◆ cwist_nats_publish_string()

cwist_error_t cwist_nats_publish_string	(	cwist_nats_t *	nats,
		const char *	subject,
		const char *	data
	)

Publish a string message.

A NULL data is published as an empty string. Flushes the connection after publishing so the message is written out before returning.

Parameters

nats	Handle with an active connection; must not be NULL.
subject	Subject to publish to; must not be NULL.
data	Payload string, or NULL to send an empty payload.

Returns: cwist_error_t with err_i16 set to 0 on success, CWIST_ERROR_INVALID_PARAM on NULL arguments, or the natsStatus code on publish/flush failure.

Definition at line 126 of file cwist_nats.c.

References cap, CWIST_ERR_INT16, CWIST_ERROR_INVALID_PARAM, and make_error().

◆ cwist_nats_subscribe()

cwist_error_t cwist_nats_subscribe	(	cwist_nats_t *	nats,
		const char *	subject,
		cwist_nats_msg_cb	cb,
		void *	ctx
	)

Subscribe to a subject.

Replaces any existing subscription on the handle: the previous subscription is destroyed before the new one is created. The callback is invoked from the NATS delivery thread via cwist_nats_adapter.

Parameters

nats	Handle with an active connection; must not be NULL.
subject	Subject to subscribe to; must not be NULL.
cb	Callback invoked for each incoming message; may be NULL.
ctx	Opaque pointer passed back to `cb`.

Returns: cwist_error_t with err_i16 set to 0 on success, CWIST_ERROR_INVALID_PARAM on NULL arguments, or the natsStatus code on failure.

Definition at line 92 of file cwist_nats.c.

References cap, CWIST_ERR_INT16, CWIST_ERROR_INVALID_PARAM, and make_error().

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ cwist_nats_msg_cb

◆ cwist_nats_t

◆ natsConnection

Function Documentation

◆ cwist_nats_connect()

◆ cwist_nats_destroy()

◆ cwist_nats_dispatch()

◆ cwist_nats_native()

◆ cwist_nats_publish_string()

◆ cwist_nats_subscribe()