Websocket status APIs

Data Structures
struct	lws_wifi_scan
union	lws_tls_cert_info_results

Enumerations
enum	lws_tls_cert_info {   LWS_TLS_CERT_INFO_VALIDITY_FROM, LWS_TLS_CERT_INFO_VALIDITY_TO, LWS_TLS_CERT_INFO_COMMON_NAME, LWS_TLS_CERT_INFO_ISSUER_NAME,   LWS_TLS_CERT_INFO_USAGE, LWS_TLS_CERT_INFO_VERIFIED, LWS_TLS_CERT_INFO_OPAQUE_PUBLIC_KEY }

Functions
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT	lws_send_pipe_choked (struct lws *wsi)
LWS_VISIBLE LWS_EXTERN int	lws_is_final_fragment (struct lws *wsi)
LWS_VISIBLE LWS_EXTERN int	lws_is_first_fragment (struct lws *wsi)
LWS_VISIBLE LWS_EXTERN unsigned char	lws_get_reserved_bits (struct lws *wsi)
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT	lws_partial_buffered (struct lws *wsi)
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT	lws_frame_is_binary (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 SSL *	lws_get_ssl (struct lws *wsi)
LWS_VISIBLE LWS_EXTERN int	lws_tls_peer_cert_info (struct lws *wsi, enum lws_tls_cert_info type, union lws_tls_cert_info_results *buf, size_t len)
LWS_VISIBLE LWS_EXTERN int	lws_tls_vhost_cert_info (struct lws_vhost *vhost, enum lws_tls_cert_info type, union lws_tls_cert_info_results *buf, size_t len)
LWS_VISIBLE LWS_EXTERN int	lws_tls_acme_sni_cert_create (struct lws_vhost *vhost, const char *san_a, const char *san_b)
LWS_VISIBLE LWS_EXTERN int	lws_tls_acme_sni_csr_create (struct lws_context *context, const char *elements[], uint8_t *csr, size_t csr_len, char **privkey_pem, size_t *privkey_len)
LWS_VISIBLE LWS_EXTERN int	lws_tls_cert_updated (struct lws_context *context, const char *certpath, const char *keypath, const char *mem_cert, size_t len_mem_cert, const char *mem_privkey, size_t len_mem_privkey)

Detailed Description

Websocket connection status APIs

These provide information about ws connection or message status

Enumeration Type Documentation

lws_tls_cert_info

enum lws_tls_cert_info

#include <lib/libwebsockets.h>

Enumerator
LWS_TLS_CERT_INFO_VALIDITY_FROM	fills .time with the time_t the cert validity started from
LWS_TLS_CERT_INFO_VALIDITY_TO	fills .time with the time_t the cert validity ends at
LWS_TLS_CERT_INFO_COMMON_NAME	fills up to len bytes of .ns.name with the cert common name
LWS_TLS_CERT_INFO_ISSUER_NAME	fills up to len bytes of .ns.name with the cert issuer name
LWS_TLS_CERT_INFO_USAGE	fills verified with a bitfield asserting the valid uses
LWS_TLS_CERT_INFO_VERIFIED	fills .verified with a bool representing peer cert validity, call returns -1 if no cert
LWS_TLS_CERT_INFO_OPAQUE_PUBLIC_KEY	the certificate's public key, as an opaque bytestream. These opaque bytestreams can only be compared with each other using the same tls backend, ie, OpenSSL or mbedTLS. The different backends produce different, incompatible representations for the same cert.

                       {
        LWS_TLS_CERT_INFO_VALIDITY_FROM,
        LWS_TLS_CERT_INFO_VALIDITY_TO,
        LWS_TLS_CERT_INFO_COMMON_NAME,
        LWS_TLS_CERT_INFO_ISSUER_NAME,
        LWS_TLS_CERT_INFO_USAGE,
        LWS_TLS_CERT_INFO_VERIFIED,
        LWS_TLS_CERT_INFO_OPAQUE_PUBLIC_KEY,
};

Function Documentation

lws_frame_is_binary()

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_frame_is_binary

(

struct lws *

wsi

)

#include <lib/libwebsockets.h>

lws_frame_is_binary(): true if the current frame was sent in binary mode

Parameters

wsi	the connection we are inquiring about

This is intended to be called from the LWS_CALLBACK_RECEIVE callback if it's interested to see if the frame it's dealing with was sent in binary mode.

lws_get_reserved_bits()

LWS_VISIBLE LWS_EXTERN unsigned char lws_get_reserved_bits

(

struct lws *

wsi

)

#include <lib/libwebsockets.h>

lws_get_reserved_bits() - access reserved bits of ws frame

Parameters

wsi	lws connection

lws_get_ssl()

LWS_VISIBLE LWS_EXTERN SSL* lws_get_ssl

(

struct lws *

wsi

)

#include <lib/libwebsockets.h>

lws_get_ssl() - Return wsi's SSL context structure

Parameters

wsi	websocket connection

Returns pointer to the SSL library's context structure

lws_is_cgi()

LWS_VISIBLE LWS_EXTERN int lws_is_cgi

(

struct lws *

wsi

)

#include <lib/libwebsockets.h>

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

Parameters

wsi	lws connection

lws_is_final_fragment()

LWS_VISIBLE LWS_EXTERN int lws_is_final_fragment

(

struct lws *

wsi

)

#include <lib/libwebsockets.h>

lws_is_final_fragment() - tests if last part of ws message

Parameters

wsi	lws connection

lws_is_first_fragment()

LWS_VISIBLE LWS_EXTERN int lws_is_first_fragment

(

struct lws *

wsi

)

#include <lib/libwebsockets.h>

lws_is_first_fragment() - tests if first part of ws message

Parameters

wsi	lws connection

lws_is_ssl()

LWS_VISIBLE LWS_EXTERN int lws_is_ssl

(

struct lws *

wsi

)

#include <lib/libwebsockets.h>

lws_is_ssl() - Find out if connection is using SSL

Parameters

wsi	websocket connection to check Returns 0 if the connection is not using SSL, 1 if using SSL and using verified cert, and 2 if using SSL but the cert was not checked (appears for client wsi told to skip check on connection)

lws_partial_buffered()

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_partial_buffered

(

struct lws *

wsi

)

#include <lib/libwebsockets.h>

lws_partial_buffered() - find out if lws buffered the last write

Parameters

wsi	websocket connection to check

Returns 1 if you cannot use lws_write because the last write on this connection is still buffered, and can't be cleared without returning to the service loop and waiting for the connection to be writeable again.

If you will try to do >1 lws_write call inside a single WRITEABLE callback, you must check this after every write and bail if set, ask for a new writeable callback and continue writing from there.

This is never set at the start of a writeable callback, but any write may set it.

lws_send_pipe_choked()

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_send_pipe_choked

(

struct lws *

wsi

)

#include <lib/libwebsockets.h>

lws_send_pipe_choked() - tests if socket is writable or not

Parameters

wsi	lws connection

Allows you to check if you can write more on the socket

lws_tls_acme_sni_cert_create()

LWS_VISIBLE LWS_EXTERN int lws_tls_acme_sni_cert_create	(	struct lws_vhost *	vhost,
		const char *	san_a,
		const char *	san_b
	)

#include <lib/libwebsockets.h>

lws_tls_acme_sni_cert_create() - creates a temp selfsigned cert and attaches to a vhost

Parameters

vhost	the vhost to acquire the selfsigned cert
san_a	SAN written into the certificate
san_b	second SAN written into the certificate

Returns 0 if created and attached to the vhost. Returns -1 if problems and frees all allocations before returning.

On success, any allocations are destroyed at vhost destruction automatically.

lws_tls_acme_sni_csr_create()

LWS_VISIBLE LWS_EXTERN int lws_tls_acme_sni_csr_create	(	struct lws_context *	context,
		const char *	elements[],
		uint8_t *	csr,
		size_t	csr_len,
		char **	privkey_pem,
		size_t *	privkey_len
	)

#include <lib/libwebsockets.h>

lws_tls_acme_sni_csr_create() - creates a CSR and related private key PEM

Parameters

context	lws_context used for random
elements	array of LWS_TLS_REQ_ELEMENT_COUNT const char *
csr	buffer that will get the b64URL(ASN-1 CSR)
csr_len	max length of the csr buffer
privkey_pem	pointer to pointer allocated to hold the privkey_pem
privkey_len	pointer to size_t set to the length of the privkey_pem

Creates a CSR according to the information in elements, and a private RSA key used to sign the CSR.

The outputs are the b64URL(ASN-1 CSR) into csr, and the PEM private key into privkey_pem.

Notice that elements points to an array of const char *s pointing to the information listed in the enum above. If an entry is NULL or an empty string, the element is set to "none" in the CSR.

Returns 0 on success or nonzero for failure.

lws_tls_cert_updated()

LWS_VISIBLE LWS_EXTERN int lws_tls_cert_updated	(	struct lws_context *	context,
		const char *	certpath,
		const char *	keypath,
		const char *	mem_cert,
		size_t	len_mem_cert,
		const char *	mem_privkey,
		size_t	len_mem_privkey
	)

#include <lib/libwebsockets.h>

lws_tls_cert_updated() - update every vhost using the given cert path

Parameters

context	our lws_context
certpath	the filepath to the certificate
keypath	the filepath to the private key of the certificate
mem_cert	copy of the cert in memory
len_mem_cert	length of the copy of the cert in memory
mem_privkey	copy of the private key in memory
len_mem_privkey	length of the copy of the private key in memory

Checks every vhost to see if it is the using certificate described by the the given filepaths. If so, it attempts to update the vhost ssl_ctx to use the new certificate.

Returns 0 on success or nonzero for failure.

lws_tls_peer_cert_info()

LWS_VISIBLE LWS_EXTERN int lws_tls_peer_cert_info	(	struct lws *	wsi,
		enum lws_tls_cert_info	type,
		union lws_tls_cert_info_results *	buf,
		size_t	len
	)

#include <lib/libwebsockets.h>

lws_tls_peer_cert_info() - get information from the peer's TLS cert

Parameters

wsi	the connection to query
type	one of LWS_TLS_CERT_INFO_
buf	pointer to union to take result
len	when result is a string, the true length of buf->ns.name[]

lws_tls_peer_cert_info() lets you get hold of information from the peer certificate.

Return 0 if there is a result in buf, or -1 indicating there was no cert or another problem.

This function works the same no matter if the TLS backend is OpenSSL or mbedTLS.

lws_tls_vhost_cert_info()

LWS_VISIBLE LWS_EXTERN int lws_tls_vhost_cert_info	(	struct lws_vhost *	vhost,
		enum lws_tls_cert_info	type,
		union lws_tls_cert_info_results *	buf,
		size_t	len
	)

#include <lib/libwebsockets.h>

lws_tls_vhost_cert_info() - get information from the vhost's own TLS cert

Parameters

vhost	the vhost to query
type	one of LWS_TLS_CERT_INFO_
buf	pointer to union to take result
len	when result is a string, the true length of buf->ns.name[]

lws_tls_vhost_cert_info() lets you get hold of information from the vhost certificate.

Return 0 if there is a result in buf, or -1 indicating there was no cert or another problem.

This function works the same no matter if the TLS backend is OpenSSL or mbedTLS.