Server-Sent Events stream API. More...

#include <cwist/net/http/http.h>

Include dependency graph for sse.h:

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

Classes
struct	cwist_sse_event

Macros
#define	CWIST_SSE_EVENT(payload) ((cwist_sse_event_t){.event = NULL, .id = NULL, .retry_ms = -1, .data = (payload)})

#define	CWIST_SSE_NAMED(event_name, payload) ((cwist_sse_event_t){.event = (event_name), .id = NULL, .retry_ms = -1, .data = (payload)})

#define	CWIST_SSE_JSON(payload) CWIST_SSE_NAMED("message", (payload))

#define	CWIST_SSE_RESPONSE_SEND(res, event) cwist_sse_response_write((res), &(event))

#define	CWIST_SSE_STREAM_SEND(stream, event) cwist_sse_stream_write((stream), &(event))

Typedefs
typedef struct cwist_sse_stream	cwist_sse_stream_t

typedef struct cwist_sse_event	cwist_sse_event_t

Functions
cwist_error_t	cwist_sse_response_init (cwist_http_response *res)
	Prepare a response buffer for a Server-Sent Events reply.

cwist_error_t	cwist_sse_response_event (cwist_http_response res, const char event, const char id, int retry_ms, const char data)
	Append a formatted SSE event to a response buffer.

cwist_error_t	cwist_sse_response_comment (cwist_http_response res, const char comment)
	Append an SSE comment line to a response buffer.

cwist_error_t	cwist_sse_response_write (cwist_http_response res, const cwist_sse_event_t event)
	Append an SSE event described by a cwist_sse_event_t to a response.

cwist_sse_stream_t *	cwist_sse_stream_open (cwist_http_request *req)
	Upgrade a request connection to a live SSE stream.

cwist_error_t	cwist_sse_stream_send (cwist_sse_stream_t stream, const char event, const char id, int retry_ms, const char data)
	Send a formatted SSE event on a live stream.

cwist_error_t	cwist_sse_stream_comment (cwist_sse_stream_t stream, const char comment)
	Send an SSE comment line on a live stream.

cwist_error_t	cwist_sse_stream_write (cwist_sse_stream_t stream, const cwist_sse_event_t event)
	Send an SSE event described by a cwist_sse_event_t on a stream.

void	cwist_sse_stream_close (cwist_sse_stream_t *stream)
	Close a live SSE stream and release its resources.

Detailed Description

Server-Sent Events stream API.

Definition in file sse.h.

Macro Definition Documentation

◆ CWIST_SSE_EVENT

#define CWIST_SSE_EVENT ( payload ) ((cwist_sse_event_t){.event = NULL, .id = NULL, .retry_ms = -1, .data = (payload)})

Convenience forms for the common SSE payload styles.

Definition at line 36 of file sse.h.

◆ CWIST_SSE_JSON

#define CWIST_SSE_JSON ( payload ) CWIST_SSE_NAMED("message", (payload))

Definition at line 40 of file sse.h.

◆ CWIST_SSE_NAMED

#define CWIST_SSE_NAMED	(	event_name,
		payload
	)	((cwist_sse_event_t){.event = (event_name), .id = NULL, .retry_ms = -1, .data = (payload)})

Definition at line 38 of file sse.h.

◆ CWIST_SSE_RESPONSE_SEND

#define CWIST_SSE_RESPONSE_SEND	(	res,
		event
	)	cwist_sse_response_write((res), &(event))

Definition at line 41 of file sse.h.

◆ CWIST_SSE_STREAM_SEND

#define CWIST_SSE_STREAM_SEND	(	stream,
		event
	)	cwist_sse_stream_write((stream), &(event))

Definition at line 42 of file sse.h.

Typedef Documentation

◆ cwist_sse_event_t

typedef struct cwist_sse_event cwist_sse_event_t

A structured SSE event. NULL fields are omitted; retry_ms < 0 omits retry.

◆ cwist_sse_stream_t

typedef struct cwist_sse_stream cwist_sse_stream_t

Definition at line 11 of file sse.h.

Function Documentation

◆ cwist_sse_response_comment()

cwist_error_t cwist_sse_response_comment	(	cwist_http_response *	res,
		const char *	comment
	)

Append an SSE comment line to a response buffer.

Parameters

res	Response whose body receives the comment; must not be NULL.
comment	Comment text.

Returns: 0 on success, -1 if res is NULL or the comment frame could not be built or appended.

Definition at line 154 of file sse.c.

References cwist_http_response::body, cap, cwist_sstring_append_len(), cwist_sstring_destroy(), and cwist_sstring::data.

◆ cwist_sse_response_event()

cwist_error_t cwist_sse_response_event	(	cwist_http_response *	res,
		const char *	event,
		const char *	id,
		int	retry_ms,
		const char *	data
	)

Append a formatted SSE event to a response buffer.

Parameters

res	Response whose body receives the frame; must not be NULL.
event	Event type field, optional.
id	Event id field, optional.
retry_ms	Reconnection delay in milliseconds; -1 to omit.
data	Event payload data.

Returns: 0 on success, -1 if res is NULL, retry_ms is less than -1, or the frame could not be built or appended.

Definition at line 138 of file sse.c.

References cwist_http_response::body, cap, cwist_sstring_append_len(), cwist_sstring_destroy(), and cwist_sstring::data.

Referenced by cwist_sse_response_write().

◆ cwist_sse_response_init()

cwist_error_t cwist_sse_response_init ( cwist_http_response * res )

Prepare a response buffer for a Server-Sent Events reply.

Adds the Content-Type, Cache-Control, and X-Accel-Buffering headers required for SSE and enables keep-alive.

Parameters

res	Response to initialize; must not be NULL.

Returns: 0 on success, -1 if res is NULL or a header could not be added.

Definition at line 117 of file sse.c.

References cwist_http_header_add(), cwist_http_response::headers, and cwist_http_response::keep_alive.

◆ cwist_sse_response_write()

cwist_error_t cwist_sse_response_write	(	cwist_http_response *	res,
		const cwist_sse_event_t *	event
	)

Append an SSE event described by a cwist_sse_event_t to a response.

Parameters

res	Response whose body receives the frame.
event	Event descriptor; must not be NULL.

Returns: 0 on success, -1 on failure (see cwist_sse_response_event()).

Definition at line 168 of file sse.c.

References cwist_sse_response_event(), cwist_sse_event::data, cwist_sse_event::event, cwist_sse_event::id, and cwist_sse_event::retry_ms.

◆ cwist_sse_stream_close()

void cwist_sse_stream_close ( cwist_sse_stream_t * stream )

Close a live SSE stream and release its resources.

Destroys the stream mutex and frees the stream; the underlying socket remains owned by the upgraded request.

Parameters

stream Stream to close; NULL is silently ignored.

Definition at line 285 of file sse.c.

References cap, and cwist_free().

◆ cwist_sse_stream_comment()

cwist_error_t cwist_sse_stream_comment	(	cwist_sse_stream_t *	stream,
		const char *	comment
	)

Send an SSE comment line on a live stream.

Serializes access to the stream with its mutex; a failed send marks the stream as closed.

Parameters

stream	Stream to write to; must not be NULL.
comment	Comment text.

Returns: 0 on success, -1 if the stream or frame is invalid, the stream is closed, or the send fails.

Definition at line 256 of file sse.c.

References cap, and cwist_sstring_destroy().

◆ cwist_sse_stream_open()

cwist_sse_stream_t * cwist_sse_stream_open ( cwist_http_request * req )

Upgrade a request connection to a live SSE stream.

Writes SSE response headers immediately and sets req->upgraded.

Sends the SSE HTTP response headers and marks the request as upgraded, transferring ownership of the connection to the returned stream (release with cwist_sse_stream_close()).

Parameters

req	Request to upgrade; must not be NULL and must not already be upgraded.

Returns: New stream on success, NULL if the request is invalid or the headers could not be sent or the stream could not be allocated.

Definition at line 205 of file sse.c.

References cap, cwist_http_request::client_fd, cwist_alloc(), and cwist_http_request::upgraded.

◆ cwist_sse_stream_send()

cwist_error_t cwist_sse_stream_send	(	cwist_sse_stream_t *	stream,
		const char *	event,
		const char *	id,
		int	retry_ms,
		const char *	data
	)

Send a formatted SSE event on a live stream.

Serializes access to the stream with its mutex; a failed send marks the stream as closed.

Parameters

stream	Stream to write to; must not be NULL.
event	Event type field, optional.
id	Event id field, optional.
retry_ms	Reconnection delay in milliseconds; -1 to omit.
data	Event payload data.

Returns: 0 on success, -1 if the stream or frame is invalid, the stream is closed, or the send fails.

Definition at line 233 of file sse.c.

References cap, and cwist_sstring_destroy().

Referenced by cwist_sse_stream_write().

◆ cwist_sse_stream_write()

cwist_error_t cwist_sse_stream_write	(	cwist_sse_stream_t *	stream,
		const cwist_sse_event_t *	event
	)

Send an SSE event described by a cwist_sse_event_t on a stream.

Parameters

stream	Stream to write to.
event	Event descriptor; must not be NULL.

Returns: 0 on success, -1 on failure (see cwist_sse_stream_send()).

Definition at line 273 of file sse.c.

References cwist_sse_stream_send(), cwist_sse_event::data, cwist_sse_event::event, cwist_sse_event::id, and cwist_sse_event::retry_ms.

Classes

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ CWIST_SSE_EVENT

◆ CWIST_SSE_JSON

◆ CWIST_SSE_NAMED

◆ CWIST_SSE_RESPONSE_SEND

◆ CWIST_SSE_STREAM_SEND

Typedef Documentation

◆ cwist_sse_event_t

◆ cwist_sse_stream_t

Function Documentation

◆ cwist_sse_response_comment()

◆ cwist_sse_response_event()

◆ cwist_sse_response_init()

◆ cwist_sse_response_write()

◆ cwist_sse_stream_close()

◆ cwist_sse_stream_comment()

◆ cwist_sse_stream_open()

◆ cwist_sse_stream_send()

◆ cwist_sse_stream_write()