libwebsockets
Lightweight C library for HTML5 websockets
Socket adoption helpers

Data Structures

union  lws_sock_file_fd_type
 
union  lws_sockaddr46
 
struct  lws_adopt_desc
 

Macros

#define sa46_sockaddr(_sa46)   ((struct sockaddr *)(_sa46))
 
#define sa46_socklen(_sa46)   (socklen_t)sizeof(struct sockaddr_in)
 
#define sa46_sockport(_sa46, _sp)   (_sa46)->sa4.sin_port = (_sp)
 
#define sa46_address(_sa46)   (uint8_t *)&_sa46->sa4.sin_addr
 
#define sa46_address_len(_sa46)   ((_sa46)->sa4.sin_family == AF_INET ? 4 : 16)
 
#define LWS_CAUDP_BIND   (1 << 0)
 
#define LWS_CAUDP_BROADCAST   (1 << 1)
 
#define LWS_CAUDP_PF_PACKET   (1 << 2)
 

Typedefs

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_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 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 78 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 87 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 149 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)    ((struct sockaddr *)(_sa46))

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

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

◆ sa46_socklen

#define sa46_socklen (   _sa46)    (socklen_t)sizeof(struct sockaddr_in)

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

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

◆ sa46_sockport

#define sa46_sockport (   _sa46,
  _sp 
)    (_sa46)->sa4.sin_port = (_sp)

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

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

◆ sa46_address

#define sa46_address (   _sa46)    (uint8_t *)&_sa46->sa4.sin_addr

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

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

◆ sa46_address_len

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

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

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

◆ LWS_CAUDP_BIND

#define LWS_CAUDP_BIND   (1 << 0)

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

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

◆ LWS_CAUDP_BROADCAST

#define LWS_CAUDP_BROADCAST   (1 << 1)

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

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

◆ LWS_CAUDP_PF_PACKET

#define LWS_CAUDP_PF_PACKET   (1 << 2)

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

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

Typedef Documentation

◆ lws_adopt_desc_t

Enumeration Type Documentation

◆ lws_adoption_type

#include <include/libwebsockets/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_RAW_SOCKET_UDP 

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

67  {
68  LWS_ADOPT_RAW_FILE_DESC = 0, /* convenience constant */
69  LWS_ADOPT_HTTP = 1, /* flag: absent implies RAW */
70  LWS_ADOPT_SOCKET = 2, /* flag: absent implies file */
71  LWS_ADOPT_ALLOW_SSL = 4, /* flag: use tls */
72  LWS_ADOPT_FLAG_UDP = 16, /* flag: socket is UDP */
73  LWS_ADOPT_FLAG_RAW_PROXY = 32, /* flag: raw proxy */
74 
lws_adoption_type
Definition: lws-adopt.h:67
@ LWS_ADOPT_HTTP
Definition: lws-adopt.h:69
@ LWS_ADOPT_SOCKET
Definition: lws-adopt.h:70
@ LWS_ADOPT_FLAG_RAW_PROXY
Definition: lws-adopt.h:73
@ LWS_ADOPT_RAW_FILE_DESC
Definition: lws-adopt.h:68
@ LWS_ADOPT_ALLOW_SSL
Definition: lws-adopt.h:71
@ LWS_ADOPT_FLAG_UDP
Definition: lws-adopt.h:72
@ LWS_ADOPT_RAW_SOCKET_UDP
Definition: lws-adopt.h:75

Function Documentation

◆ lws_adopt_socket()

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

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

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

Parameters
contextlws context
accept_fdfd 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_socket_vhost()

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

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

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

Parameters
vhlws vhost
accept_fdfd 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 <include/libwebsockets/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
vhlws vhost
typeOR-ed combinations of lws_adoption_type flags
fdunion with either .sockfd or .filefd set
vh_prot_nameNULL or vh protocol name to bind raw connection to
parentNULL 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.

◆ 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 <include/libwebsockets/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
infothe 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.

◆ 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 <include/libwebsockets/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
contextlws context
accept_fdfd of already-accepted socket to adopt
readbufNULL or pointer to data that must be drained before reading from accept_fd
lenThe 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.

◆ 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 <include/libwebsockets/lws-adopt.h>

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

Parameters
vhostlws vhost
accept_fdfd of already-accepted socket to adopt
readbufNULL or pointer to data that must be drained before reading from accept_fd
lenThe 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.