Socket adoption helpers

Data Structures
union	lws_sock_file_fd_type
union	lws_sockaddr46
struct	lws_transport_ops
struct	lws_adopt_desc

Macros
#define	sa46_sockaddr(_sa46)
#define	sa46_socklen(_sa46)
#define	sa46_sockport(_sa46, _sp)
#define	sa46_address(_sa46)
#define	sa46_address_len(_sa46)
#define	LWS_CAUDP_BIND   (1 << 0)
#define	LWS_CAUDP_BROADCAST   (1 << 1)
#define	LWS_CAUDP_PF_PACKET   (1 << 2)

Typedefs
typedef union lws_sockaddr46	lws_sockaddr46
typedef struct lws_transport_ops	lws_transport_ops_t
typedef struct lws_adopt_desc	lws_adopt_desc_t

Enumerations
enum	lws_adoption_type {   LWS_ADOPT_RAW_FILE_DESC = 0 , LWS_ADOPT_HTTP = 1 , LWS_ADOPT_SOCKET = 2 , LWS_ADOPT_ALLOW_SSL = 4 ,   LWS_ADOPT_FLAG_UDP = 16 , LWS_ADOPT_FLAG_RAW_PROXY = 32 , LWS_ADOPT_FLAG_NO_NONBLOCK = 64 , LWS_ADOPT_RAW_SOCKET_UDP = LWS_ADOPT_SOCKET | LWS_ADOPT_FLAG_UDP }

Functions
LWS_VISIBLE LWS_EXTERN struct lws *	lws_adopt_socket (struct lws_context *context, lws_sockfd_type accept_fd)
LWS_VISIBLE LWS_EXTERN struct lws *	lws_adopt_socket_vhost (struct lws_vhost *vh, lws_sockfd_type accept_fd)
LWS_VISIBLE LWS_EXTERN struct lws *	lws_adopt_descriptor_vhost (struct lws_vhost *vh, lws_adoption_type type, lws_sock_file_fd_type fd, const char *vh_prot_name, struct lws *parent)
LWS_VISIBLE LWS_EXTERN lws_sockfd_type	lws_get_socket_fd (struct lws *wsi)
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_set_transport (struct lws *wsi, const lws_transport_ops_t *ops, void *opaque)
LWS_VISIBLE LWS_EXTERN struct lws *	lws_adopt_descriptor_vhost_via_info (const lws_adopt_desc_t *info)
LWS_VISIBLE LWS_EXTERN struct lws *	lws_adopt_socket_readbuf (struct lws_context *context, lws_sockfd_type accept_fd, const char *readbuf, size_t len)
LWS_VISIBLE LWS_EXTERN struct lws *	lws_adopt_socket_vhost_readbuf (struct lws_vhost *vhost, lws_sockfd_type accept_fd, const char *readbuf, size_t len)

Detailed Description

Socket adoption helpers

When integrating with an external app with its own event loop, these can be used to accept connections from someone else's listening socket.

When using lws own event loop, these are not needed.

---

Data Structure Documentation

lws_sock_file_fd_type

union lws_sock_file_fd_type

Definition at line 82 of file lws-adopt.h.

Collaboration diagram for lws_sock_file_fd_type:

Data Fields
lws_sockfd_type	sockfd
lws_filefd_type	filefd

lws_sockaddr46

union lws_sockaddr46

Definition at line 91 of file lws-adopt.h.

Collaboration diagram for lws_sockaddr46:

Data Fields
struct sockaddr_in	sa4

lws_adopt_desc

struct lws_adopt_desc

Definition at line 222 of file lws-adopt.h.

Collaboration diagram for lws_adopt_desc:

Data Fields
struct lws_vhost *	vh	vhost the wsi should belong to
lws_adoption_type	type	OR-ed combinations of lws_adoption_type flags
lws_sock_file_fd_type	fd	union with either .sockfd or .filefd set
const char *	vh_prot_name	NULL or vh protocol name to bind raw connection to
struct lws *	parent	NULL or struct lws to attach new_wsi to as a child
void *	opaque	opaque pointer to set on created wsi
const char *	fi_wsi_name	NULL, or Fault Injection inheritence filter for wsi=string/ context faults

Macro Definition Documentation

sa46_sockaddr

#define sa46_sockaddr

(

_sa46

)

#include <lws-adopt.h>

Value:

((struct sockaddr *)(_sa46))

Definition at line 102 of file lws-adopt.h.

sa46_socklen

#define sa46_socklen

(

_sa46

)

#include <lws-adopt.h>

Value:

(socklen_t)sizeof(struct sockaddr_in)

Definition at line 114 of file lws-adopt.h.

sa46_sockport

#define sa46_sockport	(		_sa46,
			_sp )

#include <lws-adopt.h>

Value:

(_sa46)->sa4.sin_port = (_sp)

Definition at line 115 of file lws-adopt.h.

sa46_address

#define sa46_address

(

_sa46

)

#include <lws-adopt.h>

Value:

(uint8_t *)&_sa46->sa4.sin_addr

Definition at line 116 of file lws-adopt.h.

sa46_address_len

#define sa46_address_len

(

_sa46

)

#include <lws-adopt.h>

Value:

((_sa46)->sa4.sin_family == AF_INET ? 4 : 16)

Definition at line 119 of file lws-adopt.h.

LWS_CAUDP_BIND

#define LWS_CAUDP_BIND   (1 << 0)

#include <lws-adopt.h>

Definition at line 317 of file lws-adopt.h.

LWS_CAUDP_BROADCAST

#define LWS_CAUDP_BROADCAST   (1 << 1)

#include <lws-adopt.h>

Definition at line 318 of file lws-adopt.h.

LWS_CAUDP_PF_PACKET

#define LWS_CAUDP_PF_PACKET   (1 << 2)

#include <lws-adopt.h>

Definition at line 319 of file lws-adopt.h.

Typedef Documentation

lws_sockaddr46

typedef union lws_sockaddr46 lws_sockaddr46

#include <lws-adopt.h>

lws_transport_ops_t

typedef struct lws_transport_ops lws_transport_ops_t

#include <lws-adopt.h>

lws_adopt_desc_t

typedef struct lws_adopt_desc lws_adopt_desc_t

#include <lws-adopt.h>

Enumeration Type Documentation

lws_adoption_type

enum lws_adoption_type

#include <lws-adopt.h>

Enumerator
LWS_ADOPT_RAW_FILE_DESC
LWS_ADOPT_HTTP
LWS_ADOPT_SOCKET
LWS_ADOPT_ALLOW_SSL
LWS_ADOPT_FLAG_UDP
LWS_ADOPT_FLAG_RAW_PROXY
LWS_ADOPT_FLAG_NO_NONBLOCK
LWS_ADOPT_RAW_SOCKET_UDP

Definition at line 67 of file lws-adopt.h.

             {
        LWS_ADOPT_RAW_FILE_DESC         =  0,   /* convenience constant */
        LWS_ADOPT_HTTP                  =  1,   /* flag: absent implies RAW */
        LWS_ADOPT_SOCKET                =  2,   /* flag: absent implies file */
        LWS_ADOPT_ALLOW_SSL             =  4,   /* flag: use tls */
        LWS_ADOPT_FLAG_UDP              = 16,   /* flag: socket is UDP */
        LWS_ADOPT_FLAG_RAW_PROXY        = 32,   /* flag: raw proxy */
        LWS_ADOPT_FLAG_NO_NONBLOCK      = 64,   /* flag: file fd can't be made
                                                 * nonblocking, and is never
                                                 * read in a way that can block,
                                                 * eg, a Darwin kqueue fd */
 
        LWS_ADOPT_RAW_SOCKET_UDP = LWS_ADOPT_SOCKET | LWS_ADOPT_FLAG_UDP,
} lws_adoption_type;

Function Documentation

lws_adopt_socket()

LWS_VISIBLE LWS_EXTERN struct lws * lws_adopt_socket	(	struct lws_context *	context,
		lws_sockfd_type	accept_fd )

#include <lws-adopt.h>

lws_adopt_socket() - adopt foreign socket as if listen socket accepted it for the default vhost of context.

Parameters

context	lws context
accept_fd	fd of already-accepted socket to adopt

Either returns new wsi bound to accept_fd, or closes accept_fd and returns NULL, having cleaned up any new wsi pieces.

LWS adopts the socket in http serving mode, it's ready to accept an upgrade to ws or just serve http.

References LWS_EXTERN, and LWS_VISIBLE.

lws_adopt_socket_vhost()

LWS_VISIBLE LWS_EXTERN struct lws * lws_adopt_socket_vhost	(	struct lws_vhost *	vh,
		lws_sockfd_type	accept_fd )

#include <lws-adopt.h>

lws_adopt_socket_vhost() - adopt foreign socket as if listen socket accepted it for vhost

Parameters

vh	lws vhost
accept_fd	fd of already-accepted socket to adopt

Either returns new wsi bound to accept_fd, or closes accept_fd and returns NULL, having cleaned up any new wsi pieces.

LWS adopts the socket in http serving mode, it's ready to accept an upgrade to ws or just serve http.

lws_adopt_descriptor_vhost()

LWS_VISIBLE LWS_EXTERN struct lws * lws_adopt_descriptor_vhost	(	struct lws_vhost *	vh,
		lws_adoption_type	type,
		lws_sock_file_fd_type	fd,
		const char *	vh_prot_name,
		struct lws *	parent )

#include <lws-adopt.h>

lws_adopt_descriptor_vhost() - adopt foreign socket or file descriptor if socket descriptor, should already have been accepted from listen socket

Parameters

vh	lws vhost
type	OR-ed combinations of lws_adoption_type flags
fd	union with either .sockfd or .filefd set
vh_prot_name	NULL or vh protocol name to bind raw connection to
parent	NULL or struct lws to attach new_wsi to as a child

Either returns new wsi bound to accept_fd, or closes accept_fd and returns NULL, having cleaned up any new wsi pieces.

If LWS_ADOPT_SOCKET is set, LWS adopts the socket in http serving mode, it's ready to accept an upgrade to ws or just serve http.

parent may be NULL, if given it should be an existing wsi that will become the parent of the new wsi created by this call.

References LWS_EXTERN, and LWS_VISIBLE.

lws_get_socket_fd()

LWS_VISIBLE LWS_EXTERN lws_sockfd_type lws_get_socket_fd

(

struct lws *

wsi

)

#include <lws-adopt.h>

lws_get_socket_fd() - returns the socket file descriptor

This is needed to use sendto() on UDP raw sockets

Parameters

wsi	Websocket connection instance

References LWS_EXTERN, LWS_VISIBLE, and LWS_WARN_UNUSED_RESULT.

lws_get_udp()

LWS_VISIBLE LWS_EXTERN const struct lws_udp *LWS_WARN_UNUSED_RESULT lws_get_udp

(

const struct lws *

wsi

)

#include <lws-adopt.h>

lws_get_udp() - get wsi's udp struct

Parameters

wsi	lws connection

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

References LWS_EXTERN, and LWS_VISIBLE.

lws_set_transport()

LWS_VISIBLE LWS_EXTERN void lws_set_transport	(	struct lws *	wsi,
		const lws_transport_ops_t *	ops,
		void *	opaque )

#include <lws-adopt.h>

lws_set_transport() - carry a wsi's bytes over a transport, not its socket

Parameters

wsi	the connection (the one with the transport, not a stream)
ops	the transport, or NULL to go back to the socket
opaque	handed to every op

lws_adopt_descriptor_vhost_via_info()

LWS_VISIBLE LWS_EXTERN struct lws * lws_adopt_descriptor_vhost_via_info

(

const lws_adopt_desc_t *

info

)

#include <lws-adopt.h>

lws_adopt_descriptor_vhost_via_info() - adopt foreign socket or file descriptor if socket descriptor, should already have been accepted from listen socket

Parameters

info	the struct containing the parameters

• vh: lws vhost
• type: OR-ed combinations of lws_adoption_type flags
• fd: union with either .sockfd or .filefd set
• vh_prot_name: NULL or vh protocol name to bind raw connection to
• parent: NULL or struct lws to attach new_wsi to as a child
• opaque: opaque pointer to set on created wsi

Either returns new wsi bound to accept_fd, or closes accept_fd and returns NULL, having cleaned up any new wsi pieces.

If LWS_ADOPT_SOCKET is set, LWS adopts the socket in http serving mode, it's ready to accept an upgrade to ws or just serve http.

parent may be NULL, if given it should be an existing wsi that will become the parent of the new wsi created by this call.

References LWS_EXTERN, and LWS_VISIBLE.

lws_adopt_socket_readbuf()

LWS_VISIBLE LWS_EXTERN struct lws * lws_adopt_socket_readbuf	(	struct lws_context *	context,
		lws_sockfd_type	accept_fd,
		const char *	readbuf,
		size_t	len )

#include <lws-adopt.h>

lws_adopt_socket_readbuf() - adopt foreign socket and first rx as if listen socket accepted it for the default vhost of context.

Parameters

context	lws context
accept_fd	fd of already-accepted socket to adopt
readbuf	NULL or pointer to data that must be drained before reading from accept_fd
len	The length of the data held at readbuf

Either returns new wsi bound to accept_fd, or closes accept_fd and returns NULL, having cleaned up any new wsi pieces.

LWS adopts the socket in http serving mode, it's ready to accept an upgrade to ws or just serve http.

If your external code did not already read from the socket, you can use lws_adopt_socket() instead.

This api is guaranteed to use the data at readbuf first, before reading from the socket.

readbuf is limited to the size of the ah rx buf, currently 2048 bytes.

References LWS_EXTERN, and LWS_VISIBLE.

lws_adopt_socket_vhost_readbuf()

LWS_VISIBLE LWS_EXTERN struct lws * lws_adopt_socket_vhost_readbuf	(	struct lws_vhost *	vhost,
		lws_sockfd_type	accept_fd,
		const char *	readbuf,
		size_t	len )

#include <lws-adopt.h>

lws_adopt_socket_vhost_readbuf() - adopt foreign socket and first rx as if listen socket accepted it for vhost.

Parameters

vhost	lws vhost
accept_fd	fd of already-accepted socket to adopt
readbuf	NULL or pointer to data that must be drained before reading from accept_fd
len	The length of the data held at readbuf

Either returns new wsi bound to accept_fd, or closes accept_fd and returns NULL, having cleaned up any new wsi pieces.

LWS adopts the socket in http serving mode, it's ready to accept an upgrade to ws or just serve http.

If your external code did not already read from the socket, you can use lws_adopt_socket() instead.

This api is guaranteed to use the data at readbuf first, before reading from the socket.

readbuf is limited to the size of the ah rx buf, currently 2048 bytes.