libwebsockets
Lightweight C library for HTML5 websockets
Miscellaneous APIs

Data Structures

struct  lws_flow
 
struct  lws_wifi_scan
 
struct  lws_humanize_unit
 

Macros

#define lws_ptr_diff(head, tail)    ((int)((char *)(head) - (char *)(tail)))
 
#define lws_ptr_diff_size_t(head, tail)    ((size_t)(ssize_t)((char *)(head) - (char *)(tail)))
 
#define lws_strnncpy(dest, src, size1, destsize)
 
#define lws_assert_fourcc(_a, _b)   do { } while (0);
 

Typedefs

typedef struct lws_flow lws_flow_t
 
typedef struct lws_humanize_unit lws_humanize_unit_t
 

Enumerations

enum  { LWSDLOFLOW_STATE_READ , LWSDLOFLOW_STATE_READ_COMPLETED , LWSDLOFLOW_STATE_READ_FAILED }
 
enum  {
  LWS_RXFLOW_REASON_USER_BOOL = (1 << 0) , LWS_RXFLOW_REASON_HTTP_RXBUFFER = (1 << 6) , LWS_RXFLOW_REASON_H2_PPS_PENDING = (1 << 7) , LWS_RXFLOW_REASON_APPLIES = (1 << 14) ,
  LWS_RXFLOW_REASON_APPLIES_ENABLE_BIT = (1 << 13) , LWS_RXFLOW_REASON_APPLIES_ENABLE , LWS_RXFLOW_REASON_APPLIES_DISABLE = LWS_RXFLOW_REASON_APPLIES , LWS_RXFLOW_REASON_FLAG_PROCESS_NOW = (1 << 12)
}
 

Functions

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_buflist_append_segment (struct lws_buflist **head, const uint8_t *buf, size_t len)
 
LWS_VISIBLE LWS_EXTERN size_t lws_buflist_next_segment_len (struct lws_buflist **head, uint8_t **buf)
 
LWS_VISIBLE LWS_EXTERN size_t lws_buflist_use_segment (struct lws_buflist **head, size_t len)
 
LWS_VISIBLE LWS_EXTERN size_t lws_buflist_total_len (struct lws_buflist **head)
 
LWS_VISIBLE LWS_EXTERN int lws_buflist_linear_copy (struct lws_buflist **head, size_t ofs, uint8_t *buf, size_t len)
 
LWS_VISIBLE LWS_EXTERN int lws_buflist_linear_use (struct lws_buflist **head, uint8_t *buf, size_t len)
 
LWS_VISIBLE LWS_EXTERN int lws_buflist_fragment_use (struct lws_buflist **head, uint8_t *buf, size_t len, char *frag_first, char *frag_fin)
 
LWS_VISIBLE LWS_EXTERN void lws_buflist_destroy_all_segments (struct lws_buflist **head)
 
LWS_VISIBLE LWS_EXTERN void lws_buflist_describe (struct lws_buflist **head, void *id, const char *reason)
 
LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t lws_flow_feed (lws_flow_t *flow)
 
LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t lws_flow_req (lws_flow_t *flow)
 
LWS_VISIBLE LWS_EXTERN int lws_snprintf (char *str, size_t size, const char *format,...) LWS_FORMAT(3)
 
LWS_VISIBLE LWS_EXTERN char * lws_strncpy (char *dest, const char *src, size_t size)
 
LWS_VISIBLE LWS_EXTERN const char * lws_nstrstr (const char *buf, size_t len, const char *name, size_t nl)
 
LWS_VISIBLE LWS_EXTERN const char * lws_json_simple_find (const char *buf, size_t len, const char *name, size_t *alen)
 
LWS_VISIBLE LWS_EXTERN int lws_json_simple_strcmp (const char *buf, size_t len, const char *name, const char *comp)
 
LWS_VISIBLE LWS_EXTERN int lws_hex_len_to_byte_array (const char *h, size_t hlen, uint8_t *dest, int max)
 
LWS_VISIBLE LWS_EXTERN int lws_hex_to_byte_array (const char *h, uint8_t *dest, int max)
 
LWS_VISIBLE LWS_EXTERN void lws_hex_from_byte_array (const uint8_t *src, size_t slen, char *dest, size_t len)
 
LWS_VISIBLE LWS_EXTERN int lws_hex_random (struct lws_context *context, char *dest, size_t len)
 
LWS_VISIBLE LWS_EXTERN int lws_timingsafe_bcmp (const void *a, const void *b, uint32_t len)
 
LWS_VISIBLE LWS_EXTERN size_t lws_get_random (struct lws_context *context, void *buf, size_t len)
 
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_daemonize (const char *_lock_path)
 
LWS_VISIBLE LWS_EXTERN const char *LWS_WARN_UNUSED_RESULT lws_get_library_version (void)
 
LWS_VISIBLE LWS_EXTERN void * lws_wsi_user (struct lws *wsi)
 
LWS_VISIBLE LWS_EXTERN int lws_wsi_tsi (struct lws *wsi)
 
LWS_VISIBLE LWS_EXTERN void lws_set_wsi_user (struct lws *wsi, void *user)
 
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_parse_uri (char *p, const char **prot, const char **ads, int *port, const char **path)
 
LWS_VISIBLE LWS_EXTERN const char * lws_cmdline_option (int argc, const char **argv, const char *val)
 
LWS_VISIBLE LWS_EXTERN void lws_cmdline_option_handle_builtin (int argc, const char **argv, struct lws_context_creation_info *info)
 
LWS_VISIBLE LWS_EXTERN unsigned long lws_now_secs (void)
 
LWS_VISIBLE LWS_EXTERN lws_usec_t lws_now_usecs (void)
 
LWS_VISIBLE LWS_EXTERN struct lws_context *LWS_WARN_UNUSED_RESULT lws_get_context (const struct lws *wsi)
 
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_get_vhost_listen_port (struct lws_vhost *vhost)
 
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_get_count_threads (struct lws_context *context)
 
LWS_VISIBLE LWS_EXTERN struct lws *LWS_WARN_UNUSED_RESULT lws_get_parent (const struct lws *wsi)
 
LWS_VISIBLE LWS_EXTERN struct lws *LWS_WARN_UNUSED_RESULT lws_get_child (const struct lws *wsi)
 
LWS_VISIBLE LWS_EXTERN void lws_get_effective_uid_gid (struct lws_context *context, uid_t *uid, gid_t *gid)
 
LWS_VISIBLE LWS_EXTERN const struct lws_udp *LWS_WARN_UNUSED_RESULT lws_get_udp (const struct lws *wsi)
 
LWS_VISIBLE LWS_EXTERN void * lws_get_opaque_parent_data (const struct lws *wsi)
 
LWS_VISIBLE LWS_EXTERN void lws_set_opaque_parent_data (struct lws *wsi, void *data)
 
LWS_VISIBLE LWS_EXTERN void * lws_get_opaque_user_data (const struct lws *wsi)
 
LWS_VISIBLE LWS_EXTERN void lws_set_opaque_user_data (struct lws *wsi, void *data)
 
LWS_VISIBLE LWS_EXTERN int lws_get_child_pending_on_writable (const struct lws *wsi)
 
LWS_VISIBLE LWS_EXTERN void lws_clear_child_pending_on_writable (struct lws *wsi)
 
LWS_VISIBLE LWS_EXTERN int lws_get_close_length (struct lws *wsi)
 
LWS_VISIBLE LWS_EXTERN unsigned char * lws_get_close_payload (struct lws *wsi)
 
LWS_VISIBLE LWS_EXTERN struct lws * lws_get_network_wsi (struct lws *wsi)
 
LWS_VISIBLE LWS_EXTERN void lws_set_allocator (void *(*realloc)(void *ptr, size_t size, const char *reason))
 
LWS_VISIBLE LWS_EXTERN int lws_rx_flow_control (struct lws *wsi, int enable)
 
LWS_VISIBLE LWS_EXTERN void lws_rx_flow_allow_all_protocol (const struct lws_context *context, const struct lws_protocols *protocol)
 
LWS_VISIBLE LWS_EXTERN size_t lws_remaining_packet_payload (struct lws *wsi)
 
size_t lws_get_allocated_heap (void)
 
LWS_VISIBLE LWS_EXTERN int lws_get_tsi (struct lws *wsi)
 
LWS_VISIBLE LWS_EXTERN int lws_is_ssl (struct lws *wsi)
 
LWS_VISIBLE LWS_EXTERN int lws_is_cgi (struct lws *wsi)
 
LWS_VISIBLE LWS_EXTERN int lws_tls_jit_trust_blob_queury_skid (const void *_blob, size_t blen, const uint8_t *skid, size_t skid_len, const uint8_t **prpder, size_t *prder_len)
 
LWS_VISIBLE LWS_EXTERN int lws_open (const char *__file, int __oflag,...)
 
LWS_VISIBLE LWS_EXTERN void lws_explicit_bzero (void *p, size_t len)
 
LWS_VISIBLE LWS_EXTERN int lws_humanize (char *buf, size_t len, uint64_t value, const lws_humanize_unit_t *schema)
 
LWS_VISIBLE LWS_EXTERN void lws_ser_wu16be (uint8_t *b, uint16_t u)
 
LWS_VISIBLE LWS_EXTERN void lws_ser_wu32be (uint8_t *b, uint32_t u32)
 
LWS_VISIBLE LWS_EXTERN void lws_ser_wu64be (uint8_t *b, uint64_t u64)
 
LWS_VISIBLE LWS_EXTERN uint16_t lws_ser_ru16be (const uint8_t *b)
 
LWS_VISIBLE LWS_EXTERN uint32_t lws_ser_ru32be (const uint8_t *b)
 
LWS_VISIBLE LWS_EXTERN uint64_t lws_ser_ru64be (const uint8_t *b)
 
LWS_VISIBLE LWS_EXTERN int lws_vbi_encode (uint64_t value, void *buf)
 
LWS_VISIBLE LWS_EXTERN int lws_vbi_decode (const void *buf, uint64_t *value, size_t len)
 

Variables

LWS_VISIBLE const lws_humanize_unit_t humanize_schema_si [7]
 
LWS_VISIBLE const lws_humanize_unit_t humanize_schema_si_bytes [7]
 
LWS_VISIBLE const lws_humanize_unit_t humanize_schema_us [8]
 

Detailed Description

Miscellaneous APIs

Various APIs outside of other categories


Data Structure Documentation

◆ lws_flow

struct lws_flow

Definition at line 206 of file lws-misc.h.

+ Collaboration diagram for lws_flow:
Data Fields
lws_dll2_t list
struct lws_ss_handle * h
struct lws_buflist * bl
const uint8_t * data
size_t len
uint32_t blseglen
int32_t window
uint8_t state

◆ lws_wifi_scan

struct lws_wifi_scan

Definition at line 933 of file lws-misc.h.

+ Collaboration diagram for lws_wifi_scan:
Data Fields
struct lws_wifi_scan * next
char ssid[32]
int32_t rssi
uint8_t bssid[6]
uint8_t count
uint8_t channel
uint8_t authmode

◆ lws_humanize_unit

struct lws_humanize_unit

Definition at line 957 of file lws-misc.h.

+ Collaboration diagram for lws_humanize_unit:
Data Fields
const char * name
uint64_t factor

Macro Definition Documentation

◆ lws_ptr_diff

#define lws_ptr_diff (   head,
  tail 
)     ((int)((char *)(head) - (char *)(tail)))

#include <include/libwebsockets/lws-misc.h>

lws_ptr_diff(): helper to report distance between pointers as an int

Parameters
headthe pointer with the larger address
tailthe pointer with the smaller address

This helper gives you an int representing the number of bytes further forward the first pointer is compared to the second pointer.

Definition at line 250 of file lws-misc.h.

◆ lws_ptr_diff_size_t

#define lws_ptr_diff_size_t (   head,
  tail 
)     ((size_t)(ssize_t)((char *)(head) - (char *)(tail)))

#include <include/libwebsockets/lws-misc.h>

Definition at line 253 of file lws-misc.h.

◆ lws_strnncpy

#define lws_strnncpy (   dest,
  src,
  size1,
  destsize 
)

#include <include/libwebsockets/lws-misc.h>

Value:
lws_strncpy(dest, src, (size_t)(size1 + 1) < (size_t)(destsize) ? \
(size_t)(size1 + 1) : (size_t)(destsize))
LWS_VISIBLE LWS_EXTERN char * lws_strncpy(char *dest, const char *src, size_t size)

Definition at line 287 of file lws-misc.h.

◆ lws_assert_fourcc

#define lws_assert_fourcc (   _a,
  _b 
)    do { } while (0);

#include <include/libwebsockets/lws-misc.h>

Definition at line 970 of file lws-misc.h.

Typedef Documentation

◆ lws_flow_t

◆ lws_humanize_unit_t

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

#include <include/libwebsockets/lws-misc.h>

Enumerator
LWSDLOFLOW_STATE_READ 
LWSDLOFLOW_STATE_READ_COMPLETED 
LWSDLOFLOW_STATE_READ_FAILED 

Definition at line 197 of file lws-misc.h.

197  {
198  LWSDLOFLOW_STATE_READ, /* default, we want input */
199  LWSDLOFLOW_STATE_READ_COMPLETED, /* we do not need further rx, every-
200  * thing is locally buffered or used */
201  LWSDLOFLOW_STATE_READ_FAILED, /* operation has fatal error */
202 };
@ LWSDLOFLOW_STATE_READ
Definition: lws-misc.h:198
@ LWSDLOFLOW_STATE_READ_COMPLETED
Definition: lws-misc.h:199
@ LWSDLOFLOW_STATE_READ_FAILED
Definition: lws-misc.h:201

◆ anonymous enum

anonymous enum

#include <include/libwebsockets/lws-misc.h>

Enumerator
LWS_RXFLOW_REASON_USER_BOOL 
LWS_RXFLOW_REASON_HTTP_RXBUFFER 
LWS_RXFLOW_REASON_H2_PPS_PENDING 
LWS_RXFLOW_REASON_APPLIES 
LWS_RXFLOW_REASON_APPLIES_ENABLE_BIT 
LWS_RXFLOW_REASON_APPLIES_ENABLE 
LWS_RXFLOW_REASON_APPLIES_DISABLE 
LWS_RXFLOW_REASON_FLAG_PROCESS_NOW 

Definition at line 697 of file lws-misc.h.

697  {
698  /*
699  * Flags for enable and disable rxflow with reason bitmap and with
700  * backwards-compatible single bool
701  */
702  LWS_RXFLOW_REASON_USER_BOOL = (1 << 0),
705 
706  LWS_RXFLOW_REASON_APPLIES = (1 << 14),
712 
713 };
@ LWS_RXFLOW_REASON_APPLIES_DISABLE
Definition: lws-misc.h:710
@ LWS_RXFLOW_REASON_APPLIES
Definition: lws-misc.h:706
@ LWS_RXFLOW_REASON_USER_BOOL
Definition: lws-misc.h:702
@ LWS_RXFLOW_REASON_APPLIES_ENABLE_BIT
Definition: lws-misc.h:707
@ LWS_RXFLOW_REASON_APPLIES_ENABLE
Definition: lws-misc.h:708
@ LWS_RXFLOW_REASON_FLAG_PROCESS_NOW
Definition: lws-misc.h:711
@ LWS_RXFLOW_REASON_HTTP_RXBUFFER
Definition: lws-misc.h:703
@ LWS_RXFLOW_REASON_H2_PPS_PENDING
Definition: lws-misc.h:704

Function Documentation

◆ lws_buflist_append_segment()

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_buflist_append_segment ( struct lws_buflist **  head,
const uint8_t buf,
size_t  len 
)

#include <include/libwebsockets/lws-misc.h>

lws_buflist_append_segment(): add buffer to buflist at head

Parameters
headlist head
bufbuffer to stash
lenlength of buffer to stash

Returns -1 on OOM, 1 if this was the first segment on the list, and 0 if it was a subsequent segment.

◆ lws_buflist_next_segment_len()

LWS_VISIBLE LWS_EXTERN size_t lws_buflist_next_segment_len ( struct lws_buflist **  head,
uint8_t **  buf 
)

#include <include/libwebsockets/lws-misc.h>

lws_buflist_next_segment_len(): number of bytes left in current segment

Parameters
headlist head
bufif non-NULL, *buf is written with the address of the start of the remaining data in the segment

Returns the number of bytes left in the current segment. 0 indicates that the buflist is empty (there are no segments on the buflist).

◆ lws_buflist_use_segment()

LWS_VISIBLE LWS_EXTERN size_t lws_buflist_use_segment ( struct lws_buflist **  head,
size_t  len 
)

#include <include/libwebsockets/lws-misc.h>

lws_buflist_use_segment(): remove len bytes from the current segment

Parameters
headlist head
lennumber of bytes to mark as used

If len is less than the remaining length of the current segment, the position in the current segment is simply advanced and it returns.

If len uses up the remaining length of the current segment, then the segment is deleted and the list head moves to the next segment if any.

Returns the number of bytes left in the current segment. 0 indicates that the buflist is empty (there are no segments on the buflist).

◆ lws_buflist_total_len()

LWS_VISIBLE LWS_EXTERN size_t lws_buflist_total_len ( struct lws_buflist **  head)

#include <include/libwebsockets/lws-misc.h>

lws_buflist_total_len(): Get the total size of the buflist

Parameters
headlist head

Returns the total number of bytes held on all segments of the buflist

◆ lws_buflist_linear_copy()

LWS_VISIBLE LWS_EXTERN int lws_buflist_linear_copy ( struct lws_buflist **  head,
size_t  ofs,
uint8_t buf,
size_t  len 
)

#include <include/libwebsockets/lws-misc.h>

lws_buflist_linear_copy(): copy everything out as one without consuming

Parameters
headlist head
ofsstart offset into buflist in bytes
bufbuffer to copy linearly into
lenlength of buffer available

Returns -1 if len is too small, or bytes copied. Happy to do partial copies, returns 0 when there are no more bytes to copy.

◆ lws_buflist_linear_use()

LWS_VISIBLE LWS_EXTERN int lws_buflist_linear_use ( struct lws_buflist **  head,
uint8_t buf,
size_t  len 
)

#include <include/libwebsockets/lws-misc.h>

lws_buflist_linear_use(): copy and consume from buflist head

Parameters
headlist head
bufbuffer to copy linearly into
lenlength of buffer available

Copies a possibly fragmented buflist from the head into the linear output buffer buf for up to length len, and consumes the buflist content that was copied out.

Since it was consumed, calling again will resume copying out and consuming from as far as it got the first time.

Returns the number of bytes written into buf.

◆ lws_buflist_fragment_use()

LWS_VISIBLE LWS_EXTERN int lws_buflist_fragment_use ( struct lws_buflist **  head,
uint8_t buf,
size_t  len,
char *  frag_first,
char *  frag_fin 
)

#include <include/libwebsockets/lws-misc.h>

lws_buflist_fragment_use(): copy and consume <= 1 frag from buflist head

Parameters
headlist head
bufbuffer to copy linearly into
lenlength of buffer available
frag_firstpointer to char written on exit to if this is start of frag
frag_finpointer to char written on exit to if this is end of frag

Copies all or part of the fragment at the start of a buflist from the head into the output buffer buf for up to length len, and consumes the buflist content that was copied out.

Since it was consumed, calling again will resume copying out and consuming from as far as it got the first time.

Returns the number of bytes written into buf.

◆ lws_buflist_destroy_all_segments()

LWS_VISIBLE LWS_EXTERN void lws_buflist_destroy_all_segments ( struct lws_buflist **  head)

#include <include/libwebsockets/lws-misc.h>

lws_buflist_destroy_all_segments(): free all segments on the list

Parameters
headlist head

This frees everything on the list unconditionally. *head is always NULL after this.

◆ lws_buflist_describe()

LWS_VISIBLE LWS_EXTERN void lws_buflist_describe ( struct lws_buflist **  head,
void *  id,
const char *  reason 
)

#include <include/libwebsockets/lws-misc.h>

lws_buflist_describe(): debug helper logging buflist status

Parameters
headlist head
idpointer shown in debug list
reasonreason string show in debug list

Iterates through the buflist segments showing position and size. This only exists when lws was built in debug mode

◆ lws_flow_feed()

#include <include/libwebsockets/lws-misc.h>

lws_flow_feed() - consume waiting data if ready for it

Parameters
flowpointer to the flow struct managing waiting data

This will bring out waiting data from the flow buflist when it is needed.

◆ lws_flow_req()

#include <include/libwebsockets/lws-misc.h>

lws_flow_req() - request remote data if we have run low

Parameters
flowpointer to the flow struct managing waiting data

When the estimated remote tx credit is below flow->window, accounting for what is in the buflist, add to the peer tx credit so it can send us more.

◆ lws_snprintf()

LWS_VISIBLE LWS_EXTERN int lws_snprintf ( char *  str,
size_t  size,
const char *  format,
  ... 
)

#include <include/libwebsockets/lws-misc.h>

lws_snprintf(): snprintf that truncates the returned length too

Parameters
strdestination buffer
sizebytes left in destination buffer
formatformat string
...args for format

This lets you correctly truncate buffers by concatenating lengths, if you reach the limit the reported length doesn't exceed the limit.

◆ lws_strncpy()

LWS_VISIBLE LWS_EXTERN char* lws_strncpy ( char *  dest,
const char *  src,
size_t  size 
)

#include <include/libwebsockets/lws-misc.h>

lws_strncpy(): strncpy that guarantees NUL on truncated copy

Parameters
destdestination buffer
srcsource buffer
sizebytes left in destination buffer

This lets you correctly truncate buffers by concatenating lengths, if you reach the limit the reported length doesn't exceed the limit.

◆ lws_nstrstr()

LWS_VISIBLE LWS_EXTERN const char* lws_nstrstr ( const char *  buf,
size_t  len,
const char *  name,
size_t  nl 
)

#include <include/libwebsockets/lws-misc.h>

lws_nstrstr(): like strstr for length-based strings without terminating NUL

Parameters
bufthe string to search
lenthe length of the string to search
namethe substring to search for
nlthe length of name

Returns NULL if name is not present in buf. Otherwise returns the address of the first instance of name in buf.

Neither buf nor name need to be NUL-terminated.

◆ lws_json_simple_find()

LWS_VISIBLE LWS_EXTERN const char* lws_json_simple_find ( const char *  buf,
size_t  len,
const char *  name,
size_t *  alen 
)

#include <include/libwebsockets/lws-misc.h>

lws_json_simple_find(): dumb JSON string parser

Parameters
bufthe JSON to search
lenthe length of the JSON to search
namethe name field to search the JSON for, eg, "\"myname":"
alenset to the length of the argument part if non-NULL return

Either returns NULL if name is not present in buf, or returns a pointer to the argument body of the first instance of name, and sets *alen to the length of the argument body.

This can cheaply handle fishing out, eg, myarg from {"myname": "myarg"} by searching for "\"myname":". It will return a pointer to myarg and set *alen to 5. It equally handles args like "myname": true, or "myname":false, and null or numbers are all returned as delimited strings.

Anything more complicated like the value is a subobject or array, you should parse it using a full parser like lejp. This is suitable is the JSON is and will remain short and simple, and contains well-known names amongst other extensible JSON members.

◆ lws_json_simple_strcmp()

LWS_VISIBLE LWS_EXTERN int lws_json_simple_strcmp ( const char *  buf,
size_t  len,
const char *  name,
const char *  comp 
)

#include <include/libwebsockets/lws-misc.h>

lws_json_simple_strcmp(): dumb JSON string comparison

Parameters
bufthe JSON to search
lenthe length of the JSON to search
namethe name field to search the JSON for, eg, "\"myname":"
compreturn a strcmp of this and the discovered argument

Helper that combines lws_json_simple_find() with strcmp() if it was found. If the name was not found, returns -1. Otherwise returns a strcmp() between what was found and comp, ie, return 0 if they match or something else if they don't.

If the JSON is relatively simple and you want to target constrained devices, this can be a good choice. If the JSON may be complex, you should use a full JSON parser.

◆ lws_hex_len_to_byte_array()

LWS_VISIBLE LWS_EXTERN int lws_hex_len_to_byte_array ( const char *  h,
size_t  hlen,
uint8_t dest,
int  max 
)

#include <include/libwebsockets/lws-misc.h>

lws_hex_len_to_byte_array(): convert hex string like 0123456789ab into byte data

Parameters
hincoming hex string
hlennumber of chars to process at h
destarray to fill with binary decodes of hex pairs from h
maxmaximum number of bytes dest can hold, must be at least half the size of strlen(h)

This converts hex strings into an array of 8-bit representations, ie the input "abcd" produces two bytes of value 0xab and 0xcd.

Returns number of bytes produced into dest, or -1 on error.

Errors include non-hex chars and an odd count of hex chars in the input string.

◆ lws_hex_to_byte_array()

LWS_VISIBLE LWS_EXTERN int lws_hex_to_byte_array ( const char *  h,
uint8_t dest,
int  max 
)

#include <include/libwebsockets/lws-misc.h>

lws_hex_to_byte_array(): convert hex string like 0123456789ab into byte data

Parameters
hincoming NUL-terminated hex string
destarray to fill with binary decodes of hex pairs from h
maxmaximum number of bytes dest can hold, must be at least half the size of strlen(h)

This converts hex strings into an array of 8-bit representations, ie the input "abcd" produces two bytes of value 0xab and 0xcd.

Returns number of bytes produced into dest, or -1 on error.

Errors include non-hex chars and an odd count of hex chars in the input string.

◆ lws_hex_from_byte_array()

LWS_VISIBLE LWS_EXTERN void lws_hex_from_byte_array ( const uint8_t src,
size_t  slen,
char *  dest,
size_t  len 
)

#include <include/libwebsockets/lws-misc.h>

lws_hex_from_byte_array(): render byte array as hex char string

Parameters
srcincoming binary source array
slenlength of src in bytes
destarray to fill with hex chars representing src
lenmax extent of dest

This converts binary data of length slen at src, into a hex string at dest of maximum length len. Even if truncated, the result will be NUL-terminated.

◆ lws_hex_random()

LWS_VISIBLE LWS_EXTERN int lws_hex_random ( struct lws_context *  context,
char *  dest,
size_t  len 
)

#include <include/libwebsockets/lws-misc.h>

lws_hex_random(): generate len - 1 or - 2 characters of random ascii hex

Parameters
contextthe lws_context used to get the random
destdestination for hex ascii chars
lenthe number of bytes the buffer dest points to can hold

This creates random ascii-hex strings up to a given length, with a terminating NUL.

There will not be any characters produced that are not 0-9, a-f, so it's safe to go straight into, eg, JSON.

◆ lws_timingsafe_bcmp()

LWS_VISIBLE LWS_EXTERN int lws_timingsafe_bcmp ( const void *  a,
const void *  b,
uint32_t  len 
)

◆ lws_get_random()

LWS_VISIBLE LWS_EXTERN size_t lws_get_random ( struct lws_context *  context,
void *  buf,
size_t  len 
)

#include <include/libwebsockets/lws-misc.h>

lws_get_random(): fill a buffer with platform random data

Parameters
contextthe lws context
bufbuffer to fill
lenhow much to fill

Fills buf with len bytes of random. Returns the number of bytes set, if not equal to len, then getting the random failed.

◆ lws_daemonize()

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_daemonize ( const char *  _lock_path)

#include <include/libwebsockets/lws-misc.h>

lws_daemonize(): make current process run in the background

Parameters
_lock_paththe filepath to write the lock file

Spawn lws as a background process, taking care of various things

◆ lws_get_library_version()

LWS_VISIBLE LWS_EXTERN const char* LWS_WARN_UNUSED_RESULT lws_get_library_version ( void  )

#include <include/libwebsockets/lws-misc.h>

lws_get_library_version(): return string describing the version of lws

On unix, also includes the git describe

◆ lws_wsi_user()

LWS_VISIBLE LWS_EXTERN void* lws_wsi_user ( struct lws *  wsi)

#include <include/libwebsockets/lws-misc.h>

lws_wsi_user() - get the user data associated with the connection

Parameters
wsilws connection

Not normally needed since it's passed into the callback

◆ lws_wsi_tsi()

LWS_VISIBLE LWS_EXTERN int lws_wsi_tsi ( struct lws *  wsi)

#include <include/libwebsockets/lws-misc.h>

lws_wsi_tsi() - get the service thread index the wsi is bound to

Parameters
wsilws connection

Only useful is LWS_MAX_SMP > 1

◆ lws_set_wsi_user()

LWS_VISIBLE LWS_EXTERN void lws_set_wsi_user ( struct lws *  wsi,
void *  user 
)

#include <include/libwebsockets/lws-misc.h>

lws_set_wsi_user() - set the user data associated with the client connection

Parameters
wsilws connection
useruser data

By default lws allocates this and it's not legal to externally set it yourself. However client connections may have it set externally when the connection is created... if so, this api can be used to modify it at runtime additionally.

◆ lws_parse_uri()

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_parse_uri ( char *  p,
const char **  prot,
const char **  ads,
int *  port,
const char **  path 
)

#include <include/libwebsockets/lws-misc.h>

lws_parse_uri: cut up prot:/ads:port/path into pieces Notice it does so by dropping '\0' into input string and the leading / on the path is consequently lost

Parameters
pincoming uri string.. will get written to
protresult pointer for protocol part (https://)
adsresult pointer for address part
portresult pointer for port part
pathresult pointer for path part

You may also refer to unix socket addresses, using a '+' at the start of the address. In this case, the address should end with ':', which is treated as the separator between the address and path (the normal separator '/' is a valid part of the socket path). Eg,

http://+/var/run/mysocket:/my/path

If the first character after the + is '@', it's interpreted by lws client processing as meaning to use linux abstract namespace sockets, the @ is replaced with a '\0' before use.

◆ lws_cmdline_option()

LWS_VISIBLE LWS_EXTERN const char* lws_cmdline_option ( int  argc,
const char **  argv,
const char *  val 
)

#include <include/libwebsockets/lws-misc.h>

lws_cmdline_option(): simple commandline parser

Parameters
argccount of argument strings
argvargument strings
valstring to find

Returns NULL if the string val is not found in the arguments.

If it is found, then it returns a pointer to the next character after val. So if val is "-d", then for the commandlines "myapp -d15" and "myapp -d 15", in both cases the return will point to the "15".

In the case there is no argument, like "myapp -d", the return will either point to the '\0' at the end of -d, or to the start of the next argument, ie, will be non-NULL.

◆ lws_cmdline_option_handle_builtin()

LWS_VISIBLE LWS_EXTERN void lws_cmdline_option_handle_builtin ( int  argc,
const char **  argv,
struct lws_context_creation_info info 
)

#include <include/libwebsockets/lws-misc.h>

lws_cmdline_option_handle_builtin(): apply standard cmdline options

Parameters
argccount of argument strings
argvargument strings
infocontext creation info

Applies standard options to the context creation info to save them having to be (unevenly) copied into the minimal examples.

Applies default log levels that can be overriden by -d

◆ lws_now_secs()

LWS_VISIBLE LWS_EXTERN unsigned long lws_now_secs ( void  )

#include <include/libwebsockets/lws-misc.h>

lws_now_secs(): return seconds since 1970-1-1

◆ lws_now_usecs()

LWS_VISIBLE LWS_EXTERN lws_usec_t lws_now_usecs ( void  )

#include <include/libwebsockets/lws-misc.h>

lws_now_usecs(): return useconds since 1970-1-1

◆ lws_get_context()

LWS_VISIBLE LWS_EXTERN struct lws_context* LWS_WARN_UNUSED_RESULT lws_get_context ( const struct lws *  wsi)

#include <include/libwebsockets/lws-misc.h>

lws_get_context - Allow getting lws_context from a Websocket connection instance

With this function, users can access context in the callback function. Otherwise users may have to declare context as a global variable.

Parameters
wsiWebsocket connection instance

◆ lws_get_vhost_listen_port()

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_get_vhost_listen_port ( struct lws_vhost *  vhost)

#include <include/libwebsockets/lws-misc.h>

lws_get_vhost_listen_port - Find out the port number a vhost is listening on

In the case you passed 0 for the port number at context creation time, you can discover the port number that was actually chosen for the vhost using this api.

Parameters
vhostVhost to get listen port from

◆ lws_get_count_threads()

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_get_count_threads ( struct lws_context *  context)

#include <include/libwebsockets/lws-misc.h>

lws_get_count_threads(): how many service threads the context uses

Parameters
contextthe lws context

By default this is always 1, if you asked for more than lws can handle it will clip the number of threads. So you can use this to find out how many threads are actually in use.

◆ lws_get_parent()

LWS_VISIBLE LWS_EXTERN struct lws* LWS_WARN_UNUSED_RESULT lws_get_parent ( const struct lws *  wsi)

#include <include/libwebsockets/lws-misc.h>

lws_get_parent() - get parent wsi or NULL

Parameters
wsilws connection

Specialized wsi like cgi stdin/out/err are associated to a parent wsi, this allows you to get their parent.

◆ lws_get_child()

LWS_VISIBLE LWS_EXTERN struct lws* LWS_WARN_UNUSED_RESULT lws_get_child ( const struct lws *  wsi)

#include <include/libwebsockets/lws-misc.h>

lws_get_child() - get child wsi or NULL

Parameters
wsilws connection

Allows you to find a related wsi from the parent wsi.

◆ lws_get_effective_uid_gid()

LWS_VISIBLE LWS_EXTERN void lws_get_effective_uid_gid ( struct lws_context *  context,
uid_t *  uid,
gid_t *  gid 
)

#include <include/libwebsockets/lws-misc.h>

lws_get_effective_uid_gid() - find out eventual uid and gid while still root

Parameters
contextlws context
uidpointer to uid result
gidpointer to gid result

This helper allows you to find out what the uid and gid for the process will be set to after the privileges are dropped, beforehand. So while still root, eg in LWS_CALLBACK_PROTOCOL_INIT, you can arrange things like cache dir and subdir creation / permissions down /var/cache dynamically.

◆ lws_get_udp()

LWS_VISIBLE LWS_EXTERN const struct lws_udp* LWS_WARN_UNUSED_RESULT lws_get_udp ( const struct lws *  wsi)

#include <include/libwebsockets/lws-misc.h>

lws_get_udp() - get wsi's udp struct

Parameters
wsilws connection

Returns NULL or pointer to the wsi's UDP-specific information

◆ lws_get_opaque_parent_data()

LWS_VISIBLE LWS_EXTERN void* lws_get_opaque_parent_data ( const struct lws *  wsi)

◆ lws_set_opaque_parent_data()

LWS_VISIBLE LWS_EXTERN void lws_set_opaque_parent_data ( struct lws *  wsi,
void *  data 
)

◆ lws_get_opaque_user_data()

LWS_VISIBLE LWS_EXTERN void* lws_get_opaque_user_data ( const struct lws *  wsi)

◆ lws_set_opaque_user_data()

LWS_VISIBLE LWS_EXTERN void lws_set_opaque_user_data ( struct lws *  wsi,
void *  data 
)

◆ lws_get_child_pending_on_writable()

LWS_VISIBLE LWS_EXTERN int lws_get_child_pending_on_writable ( const struct lws *  wsi)

◆ lws_clear_child_pending_on_writable()

LWS_VISIBLE LWS_EXTERN void lws_clear_child_pending_on_writable ( struct lws *  wsi)

◆ lws_get_close_length()

LWS_VISIBLE LWS_EXTERN int lws_get_close_length ( struct lws *  wsi)

◆ lws_get_close_payload()

LWS_VISIBLE LWS_EXTERN unsigned char* lws_get_close_payload ( struct lws *  wsi)

◆ lws_get_network_wsi()

LWS_VISIBLE LWS_EXTERN struct lws* lws_get_network_wsi ( struct lws *  wsi)

#include <include/libwebsockets/lws-misc.h>

lws_get_network_wsi() - Returns wsi that has the tcp connection for this wsi

Parameters
wsiwsi you have

Returns wsi that has the tcp connection (which may be the incoming wsi)

HTTP/1 connections will always return the incoming wsi HTTP/2 connections may return a different wsi that has the tcp connection

◆ lws_set_allocator()

LWS_VISIBLE LWS_EXTERN void lws_set_allocator ( void *(*)(void *ptr, size_t size, const char *reason)  realloc)

#include <include/libwebsockets/lws-misc.h>

lws_set_allocator() - custom allocator support

Parameters
reallocAllows you to replace the allocator (and deallocator) used by lws

◆ lws_rx_flow_control()

LWS_VISIBLE LWS_EXTERN int lws_rx_flow_control ( struct lws *  wsi,
int  enable 
)

#include <include/libwebsockets/lws-misc.h>

lws_rx_flow_control() - Enable and disable socket servicing for received packets.

If the output side of a server process becomes choked, this allows flow control for the input side.

Parameters
wsiWebsocket connection instance to get callback for
enable0 = disable read servicing for this connection, 1 = enable

If you need more than one additive reason for rxflow control, you can give iLWS_RXFLOW_REASON_APPLIES_ENABLE or _DISABLE together with one or more of b5..b0 set to idicate which bits to enable or disable. If any bits are enabled, rx on the connection is suppressed.

LWS_RXFLOW_REASON_FLAG_PROCESS_NOW flag may also be given to force any change in rxflowbstatus to benapplied immediately, this should be used when you are changing a wsi flow control state from outside a callback on that wsi.

◆ lws_rx_flow_allow_all_protocol()

LWS_VISIBLE LWS_EXTERN void lws_rx_flow_allow_all_protocol ( const struct lws_context *  context,
const struct lws_protocols protocol 
)

#include <include/libwebsockets/lws-misc.h>

lws_rx_flow_allow_all_protocol() - Allow all connections with this protocol to receive

When the user server code realizes it can accept more input, it can call this to have the RX flow restriction removed from all connections using the given protocol.

Parameters
contextlws_context
protocolall connections using this protocol will be allowed to receive

◆ lws_remaining_packet_payload()

LWS_VISIBLE LWS_EXTERN size_t lws_remaining_packet_payload ( struct lws *  wsi)

#include <include/libwebsockets/lws-misc.h>

lws_remaining_packet_payload() - Bytes to come before "overall" rx fragment is complete

Parameters
wsiWebsocket instance (available from user callback)

This tracks how many bytes are left in the current ws fragment, according to the ws length given in the fragment header.

If the message was in a single fragment, and there is no compression, this is the same as "how much data is left to read for this message".

However, if the message is being sent in multiple fragments, this will reflect the unread amount of the current fragment, not the message. With ws, it is legal to not know the length of the message before it completes.

Additionally if the message is sent via the negotiated permessage-deflate extension, zero is always reported. You should use lws_is_final_fragment() to find out if you have completed the message... in compressed case, it holds back reporting the final fragment until it's also the final decompressed block issued.

◆ lws_get_allocated_heap()

size_t lws_get_allocated_heap ( void  )

#include <include/libwebsockets/lws-misc.h>

lws_get_allocated_heap() - if the platform supports it, returns amount of heap allocated by lws itself

On glibc currently, this reports the total amount of current logical heap allocation, found by tracking the amount allocated by lws_malloc() and friends and accounting for freed allocations via lws_free().

This is useful for confirming where processwide heap allocations actually come from... this number represents all lws internal allocations, for fd tables, wsi allocations, ah, etc combined. It doesn't include allocations from user code, since lws_malloc() etc are not exported from the library.

On other platforms, it always returns 0.

◆ lws_get_tsi()

LWS_VISIBLE LWS_EXTERN int lws_get_tsi ( struct lws *  wsi)

#include <include/libwebsockets/lws-misc.h>

lws_get_tsi() - Get thread service index wsi belong to

Parameters
wsiwebsocket connection to check

Returns more than zero (or zero if only one service thread as is the default).

◆ lws_is_ssl()

LWS_VISIBLE LWS_EXTERN int lws_is_ssl ( struct lws *  wsi)

#include <include/libwebsockets/lws-misc.h>

lws_is_ssl() - Find out if connection is using SSL

Parameters
wsiwebsocket connection to check

Returns nonzero if the wsi is inside a tls tunnel, else zero.

◆ lws_is_cgi()

LWS_VISIBLE LWS_EXTERN int lws_is_cgi ( struct lws *  wsi)

#include <include/libwebsockets/lws-misc.h>

lws_is_cgi() - find out if this wsi is running a cgi process

Parameters
wsilws connection

◆ lws_tls_jit_trust_blob_queury_skid()

LWS_VISIBLE LWS_EXTERN int lws_tls_jit_trust_blob_queury_skid ( const void *  _blob,
size_t  blen,
const uint8_t skid,
size_t  skid_len,
const uint8_t **  prpder,
size_t *  prder_len 
)

#include <include/libwebsockets/lws-misc.h>

lws_tls_jit_trust_blob_queury_skid() - walk jit trust blob for skid

Parameters
_blobthe start of the blob in memory
blenthe length of the blob in memory
skidthe SKID we are looking for
skid_lenthe length of the SKID we are looking for
prpderresult pointer to receive a pointer to the matching DER
prder_lenresult pointer to receive matching DER length

Helper to scan a JIT Trust blob in memory for a trusted CA cert matching a given SKID. Returns 0 if found and *prpder and *prder_len are set, else nonzero.

◆ lws_open()

LWS_VISIBLE LWS_EXTERN int lws_open ( const char *  __file,
int  __oflag,
  ... 
)

#include <include/libwebsockets/lws-misc.h>

lws_open() - platform-specific wrapper for open that prepares the fd

Parameters
__filethe filepath to open
__oflagoption flags

This is a wrapper around platform open() that sets options on the fd according to lws policy. Currently that is FD_CLOEXEC to stop the opened fd being available to any child process forked by user code.

◆ lws_explicit_bzero()

LWS_VISIBLE LWS_EXTERN void lws_explicit_bzero ( void *  p,
size_t  len 
)

◆ lws_humanize()

LWS_VISIBLE LWS_EXTERN int lws_humanize ( char *  buf,
size_t  len,
uint64_t  value,
const lws_humanize_unit_t schema 
)

#include <include/libwebsockets/lws-misc.h>

lws_humanize() - Convert possibly large number to human-readable uints

Parameters
bufresult string buffer
lenremaining length in buf
valuethe uint64_t value to represent
schemaand array of scaling factors and units

This produces a concise string representation of value, referencing the schema schema of scaling factors and units to find the smallest way to render it.

Three schema are exported from lws for general use, humanize_schema_si, which represents as, eg, " 22.130Gi" or " 128 "; humanize_schema_si_bytes which is the same but shows, eg, " 22.130GiB", and humanize_schema_us, which represents a count of us as a human-readable time like " 14.350min", or " 1.500d".

You can produce your own schema.

◆ lws_ser_wu16be()

LWS_VISIBLE LWS_EXTERN void lws_ser_wu16be ( uint8_t b,
uint16_t  u 
)

◆ lws_ser_wu32be()

LWS_VISIBLE LWS_EXTERN void lws_ser_wu32be ( uint8_t b,
uint32_t  u32 
)

◆ lws_ser_wu64be()

LWS_VISIBLE LWS_EXTERN void lws_ser_wu64be ( uint8_t b,
uint64_t  u64 
)

◆ lws_ser_ru16be()

LWS_VISIBLE LWS_EXTERN uint16_t lws_ser_ru16be ( const uint8_t b)

◆ lws_ser_ru32be()

LWS_VISIBLE LWS_EXTERN uint32_t lws_ser_ru32be ( const uint8_t b)

◆ lws_ser_ru64be()

LWS_VISIBLE LWS_EXTERN uint64_t lws_ser_ru64be ( const uint8_t b)

◆ lws_vbi_encode()

LWS_VISIBLE LWS_EXTERN int lws_vbi_encode ( uint64_t  value,
void *  buf 
)

◆ lws_vbi_decode()

LWS_VISIBLE LWS_EXTERN int lws_vbi_decode ( const void *  buf,
uint64_t *  value,
size_t  len 
)

Variable Documentation

◆ humanize_schema_si

LWS_VISIBLE const lws_humanize_unit_t humanize_schema_si[7]
extern

◆ humanize_schema_si_bytes

LWS_VISIBLE const lws_humanize_unit_t humanize_schema_si_bytes[7]
extern

◆ humanize_schema_us

LWS_VISIBLE const lws_humanize_unit_t humanize_schema_us[8]
extern