lws-smd.h File Reference

Go to the source code of this file.

Macros
#define	LWS_SMD_MAX_PAYLOAD   384
#define	LWS_SMD_CLASS_BITFIELD_BYTES   4
#define	LWS_SMD_STREAMTYPENAME   "_lws_smd"
#define	LWS_SMD_SS_RX_HEADER_LEN   16
#define	LWSSMDREG_FLAG_PROXIED_SS   (1 << 0)

Typedefs
typedef uint32_t	lws_smd_class_t
typedef int(*	lws_smd_notification_cb_t) (void *opaque, lws_smd_class_t _class, lws_usec_t timestamp, void *buf, size_t len)

Enumerations
enum	{   LWSSMDCL_INTERACTION = (1 << 0) , LWSSMDCL_SYSTEM_STATE = (1 << 1) , LWSSMDCL_NETWORK = (1 << 2) , LWSSMDCL_METRICS = (1 << 3) ,   LWSSMDCL_USER_BASE_BITNUM = 24 }

Functions
LWS_VISIBLE LWS_EXTERN void *	lws_smd_msg_alloc (struct lws_context *ctx, lws_smd_class_t _class, size_t len)
LWS_VISIBLE LWS_EXTERN void	lws_smd_msg_free (void **payload)
LWS_VISIBLE LWS_EXTERN int	lws_smd_msg_send (struct lws_context *ctx, void *payload)
LWS_VISIBLE LWS_EXTERN int	lws_smd_msg_printf (struct lws_context *ctx, lws_smd_class_t _class, const char *format,...) LWS_FORMAT(3)
LWS_VISIBLE LWS_EXTERN int	lws_smd_ss_msg_printf (const char *tag, uint8_t *buf, size_t *len, lws_smd_class_t _class, const char *format,...) LWS_FORMAT(5)
LWS_VISIBLE LWS_EXTERN int	lws_smd_ss_rx_forward (void *ss_user, const uint8_t *buf, size_t len)
LWS_VISIBLE LWS_EXTERN int	lws_smd_sspc_rx_forward (void *ss_user, const uint8_t *buf, size_t len)
LWS_VISIBLE LWS_EXTERN struct lws_smd_peer *	lws_smd_register (struct lws_context *ctx, void *opaque, int flags, lws_smd_class_t _class_filter, lws_smd_notification_cb_t cb)
LWS_VISIBLE LWS_EXTERN void	lws_smd_unregister (struct lws_smd_peer *pr)

Macro Definition Documentation

LWS_SMD_MAX_PAYLOAD

#define LWS_SMD_MAX_PAYLOAD   384

Definition at line 25 of file lws-smd.h.

LWS_SMD_CLASS_BITFIELD_BYTES

#define LWS_SMD_CLASS_BITFIELD_BYTES   4

Definition at line 26 of file lws-smd.h.

LWS_SMD_STREAMTYPENAME

#define LWS_SMD_STREAMTYPENAME   "_lws_smd"

Definition at line 28 of file lws-smd.h.

LWS_SMD_SS_RX_HEADER_LEN

#define LWS_SMD_SS_RX_HEADER_LEN   16

Definition at line 29 of file lws-smd.h.

LWSSMDREG_FLAG_PROXIED_SS

#define LWSSMDREG_FLAG_PROXIED_SS   (1 << 0)

It's actually a proxied SS connection registering, opaque is the ss h

Definition at line 190 of file lws-smd.h.

Typedef Documentation

lws_smd_class_t

typedef uint32_t lws_smd_class_t

Definition at line 31 of file lws-smd.h.

lws_smd_notification_cb_t

typedef int(* lws_smd_notification_cb_t) (void *opaque, lws_smd_class_t _class, lws_usec_t timestamp, void *buf, size_t len)

Definition at line 185 of file lws-smd.h.

Enumeration Type Documentation

anonymous enum

anonymous enum

Enumerator
LWSSMDCL_INTERACTION	Any kind of event indicating a user was interacting with the device, eg, press a button, touched the screen, lifted the device etc
LWSSMDCL_SYSTEM_STATE	The lws_system state changed, eg, to OPERATIONAL
LWSSMDCL_NETWORK	Something happened on the network, eg, link-up or DHCP, or captive portal state update
LWSSMDCL_METRICS	An SS client process is reporting a metric to the proxy (this class is special in that it is not rebroadcast by the proxy)
LWSSMDCL_USER_BASE_BITNUM

Definition at line 40 of file lws-smd.h.

     {
        LWSSMDCL_INTERACTION                                    = (1 << 0),
        LWSSMDCL_SYSTEM_STATE                                   = (1 << 1),
        LWSSMDCL_NETWORK                                        = (1 << 2),
        LWSSMDCL_METRICS                                        = (1 << 3),
        LWSSMDCL_USER_BASE_BITNUM                               = 24
};

Function Documentation

lws_smd_msg_alloc()

LWS_VISIBLE LWS_EXTERN void* lws_smd_msg_alloc	(	struct lws_context *	ctx,
		lws_smd_class_t	_class,
		size_t	len
	)

lws_smd_msg_alloc() - allocate a message of length len

Parameters

ctx	the lws_context
_class	the smd message class, recipients filter on this
len	the required payload length

This helper returns an opaque lws_smd_msg pointer and sets *buf to a buffer associated with it of length len.

In this way the lws_msg_smd type remains completely opaque and the allocated area can be prepared by the caller directly, without copying.

On failure, it returns NULL... it may fail for OOM but it may also fail if you request to allocate for a message class that the system has no participant who is listening for that class of event currently... the event generation action at the caller should be bypassed without error then.

This is useful if you have a message you know the length of. For text-based messages like JSON, lws_smd_msg_printf() is more convenient.

lws_smd_msg_free()

LWS_VISIBLE LWS_EXTERN void lws_smd_msg_free

(

void **

payload

)

lws_smd_msg_free() - abandon a previously allocated message before sending

Parameters

payload

pointer the previously-allocated message payload

Destroys a previously-allocated opaque message object and the requested buffer space, in the case that between allocating it and sending it, some condition was met that means it can no longer be sent, eg, an error generating the content. Otherwise there is no need to destroy allocated message objects with this, lws will take care of it.

lws_smd_msg_send()

LWS_VISIBLE LWS_EXTERN int lws_smd_msg_send	(	struct lws_context *	ctx,
		void *	payload
	)

lws_smd_msg_send() - queue a previously allocated message

Parameters

ctx	the lws_context
msg	the prepared message

Queues an allocated, prepared message for delivery to smd clients

This is threadsafe to call from a non-service thread.

lws_smd_msg_printf()

LWS_VISIBLE LWS_EXTERN int lws_smd_msg_printf	(	struct lws_context *	ctx,
		lws_smd_class_t	_class,
		const char *	format,
			...
	)

lws_smd_msg_printf() - queue a previously allocated message

Parameters

ctx	the lws_context
_class	the message class
format	the format string to prepare the payload with
...	arguments for the format string, if any

For string-based messages, eg, JSON, allows formatted creating of the payload size discovery, allocation and message send all in one step.

Unlike lws_smd_msg_alloc() you do not need to know the length beforehand as this computes it and calls lws_smd_msg_alloc() with the correct length.

To be clear this also calls through to lws_smd_msg_send(), it really does everything in one step. If there are no registered participants that want messages of _class, this function returns immediately without doing any allocation or anything else.

This is threadsafe to call from a non-service thread.

lws_smd_ss_msg_printf()

LWS_VISIBLE LWS_EXTERN int lws_smd_ss_msg_printf	(	const char *	tag,
		uint8_t *	buf,
		size_t *	len,
		lws_smd_class_t	_class,
		const char *	format,
			...
	)

lws_smd_ss_rx_forward()

LWS_VISIBLE LWS_EXTERN int lws_smd_ss_rx_forward	(	void *	ss_user,
		const uint8_t *	buf,
		size_t	len
	)

lws_smd_ss_rx_forward() - helper to forward smd messages that came in by SS

Parameters

ss_user	ss user pointer, as delivered to rx callback
buf	the ss rx buffer
len	the length of the ss rx buffer

Proxied Secure Streams with the streamtype LWS_SMD_STREAMTYPENAME receive serialized SMD messages from the proxy, this helper allows them to be translated into deserialized SMD messages and forwarded to registered SMD participants in the local context in one step.

Just pass through what arrived in the LWS_SMD_STREAMTYPENAME rx() callback to this api.

Returns 0 if OK else nonzero if unable to queue the SMD message.

lws_smd_sspc_rx_forward()

LWS_VISIBLE LWS_EXTERN int lws_smd_sspc_rx_forward	(	void *	ss_user,
		const uint8_t *	buf,
		size_t	len
	)

lws_smd_register()

LWS_VISIBLE LWS_EXTERN struct lws_smd_peer* lws_smd_register	(	struct lws_context *	ctx,
		void *	opaque,
		int	flags,
		lws_smd_class_t	_class_filter,
		lws_smd_notification_cb_t	cb
	)

lws_smd_unregister()

LWS_VISIBLE LWS_EXTERN void lws_smd_unregister

(

struct lws_smd_peer *

pr

)