libwebsockets
Lightweight C library for HTML5 websockets
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.

40  {
41  LWSSMDCL_INTERACTION = (1 << 0),
46  LWSSMDCL_SYSTEM_STATE = (1 << 1),
50  LWSSMDCL_NETWORK = (1 << 2),
55  LWSSMDCL_METRICS = (1 << 3),
62 };
@ LWSSMDCL_NETWORK
Definition: lws-smd.h:50
@ LWSSMDCL_SYSTEM_STATE
Definition: lws-smd.h:46
@ LWSSMDCL_METRICS
Definition: lws-smd.h:55
@ LWSSMDCL_INTERACTION
Definition: lws-smd.h:41
@ LWSSMDCL_USER_BASE_BITNUM
Definition: lws-smd.h:61

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
ctxthe lws_context
_classthe smd message class, recipients filter on this
lenthe 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
payloadpointer 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
ctxthe lws_context
msgthe 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
ctxthe lws_context
_classthe message class
formatthe 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_userss user pointer, as delivered to rx callback
bufthe ss rx buffer
lenthe 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)