--- name: "wslay_event_context_server_init" section: "3" platform: "linux" package: "libwslay" version: "1.1.1-7" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/wslay_event_context_server_init" --- # wslay\_event\_context\_server\_init(3) Initialize an event-based API context ## NAME wslay\_event\_context\_server\_init - Initialize an event-based API context ## SYNOPSIS \#include \ - **int wslay\_event\_context\_server\_init(wslay\_event\_context\_ptr *\*ctx*, const struct wslay\_event\_callbacks *\*callbacks*, void *\*user\_data*)** - **int wslay\_event\_context\_client\_init(wslay\_event\_context\_ptr *\*ctx*, const struct wslay\_event\_callbacks *\*callbacks*, void *\*user\_data*)** - **void wslay\_event\_context\_free(wslay\_event\_context\_ptr *ctx*)** ## DESCRIPTION *wslay\_event\_context\_server\_init()* function initializes an :c:event-based API context for WebSocket server use. *wslay\_event\_context\_client\_init()* function initializes an :c:event-based API context for WebSocket client use. If they return :c:successfully, *ctx* will point to a structure which holds any :c:necessary resources needed to process WebSocket protocol transfers. *callbacks* is a pointer to **struct wslay\_event\_callbacks**, which is defined as follows: ``` struct wslay_event_callbacks { wslay_event_recv_callback recv_callback; wslay_event_send_callback send_callback; wslay_event_genmask_callback genmask_callback; wslay_event_on_frame_recv_start_callback on_frame_recv_start_callback; wslay_event_on_frame_recv_chunk_callback on_frame_recv_chunk_callback; wslay_event_on_frame_recv_end_callback on_frame_recv_end_callback; wslay_event_on_msg_recv_callback on_msg_recv_callback; }; ``` **recv\_callback** - **typedef ssize\_t (\*wslay\_event\_recv\_callback)(wslay\_event\_context\_ptr *ctx*, uint8\_t *\*buf*, size\_t *len*, int *flags*, void *\*user\_data*)** *recv\_callback* is invoked by **wslay\_event\_recv()** when it wants to receive more data from peer. The implementation of this callback function must read data at most *len* bytes from peer and store them in *buf* and return the number of bytes read. *flags* is always 0 in this version. If there is an error, return -1 and set error code **WSLAY\_ERR\_CALLBACK\_FAILURE** using **wslay\_event\_set\_error()**. Wslay event-based API on the whole assumes non-blocking I/O. If the cause of error is **EAGAIN** or **EWOULDBLOCK**, set **WSLAY\_ERR\_WOULDBLOCK** instead. This is important because it tells **wslay\_event\_recv()** to stop receiving further data and return. **send\_callback** - **typedef ssize\_t (\*wslay\_event\_send\_callback)(wslay\_event\_context\_ptr *ctx*, const uint8\_t *\*data*, size\_t *len*, int *flags*, void *\*user\_data*)** *send\_callback* is invoked by **wslay\_event\_send()** when it wants to send more data to peer. The implementation of this callback function must send data at most *len* bytes to peer and return the number of bytes sent. *flags* is the bitwise OR of zero or more of the following flag: - **WSLAY\_MSG\_MORE** There is more data to send It provides some hints to tune performance and behaviour. If there is an error, return -1 and set error code **WSLAY\_ERR\_CALLBACK\_FAILURE** using **wslay\_event\_set\_error()**. Wslay event-based API on the whole assumes non-blocking I/O. If the cause of error is **EAGAIN** or **EWOULDBLOCK**, set **WSLAY\_ERR\_WOULDBLOCK** instead. This is important because it tells **wslay\_event\_send()** to stop sending data and return. **genmask\_callback** - **typedef int (\*wslay\_event\_genmask\_callback)(wslay\_event\_context\_ptr *ctx*, uint8\_t *\*buf*, size\_t *len*, void *\*user\_data*)** *genmask\_callback* is invoked by **wslay\_event\_send()** when it wants new mask key. As described in RFC6455, only the traffic from WebSocket client is masked, so this callback function is only needed if an event-based API is initialized for WebSocket client use. The implementation of this callback function must fill exactly *len* bytes of data in *buf* and return 0 on success. If there is an error, return -1 and set error code **WSLAY\_ERR\_CALLBACK\_FAILURE** using **wslay\_event\_set\_error()**. **on\_frame\_recv\_start\_callback** - **typedef void (\*wslay\_event\_on\_frame\_recv\_start\_callback)(wslay\_event\_context\_ptr *ctx*, const struct wslay\_event\_on\_frame\_recv\_start\_arg *\*arg*, void *\*user\_data*)** *on\_frame\_recv\_start\_callback* is invoked by **wslay\_event\_recv()** when a new frame starts to be received. This callback function is only invoked once for each frame. **struct wslay\_event\_on\_frame\_recv\_start\_arg** is defined as follows: ``` struct wslay_event_on_frame_recv_start_arg { uint8_t fin; uint8_t rsv; uint8_t opcode; uint64_t payload_length; }; ``` *fin*, *rsv* and *opcode* is fin bit and reserved bits and opcode of a frame. *payload\_length* is a payload length of a frame. **on\_frame\_recv\_chunk\_callback** - **typedef void (\*wslay\_event\_on\_frame\_recv\_chunk\_callback)(wslay\_event\_context\_ptr *ctx*, const struct wslay\_event\_on\_frame\_recv\_chunk\_arg *\*arg*, void *\*user\_data*)** *on\_frame\_recv\_chunk\_callback* is invoked by **wslay\_event\_recv()** when a chunk of frame payload is received. **struct wslay\_event\_on\_frame\_recv\_chunk\_arg** is defined as follows: ``` struct wslay_event_on_frame_recv_chunk_arg { const uint8_t *data; size_t data_length; }; ``` *data* points to a chunk of payload data. *data\_length* is the length of a chunk. **on\_frame\_recv\_end\_callback** - **typedef void (\*wslay\_event\_on\_frame\_recv\_end\_callback)(wslay\_event\_context\_ptr *ctx*, void *\*user\_data*)** *on\_frame\_recv\_end\_callback* is invoked by **wslay\_event\_recv()** when a frame is completely received. **on\_msg\_recv\_callback** - **typedef void (\*wslay\_event\_on\_msg\_recv\_callback)(wslay\_event\_context\_ptr *ctx*, const struct wslay\_event\_on\_msg\_recv\_arg *\*arg*, void *\*user\_data*)** *on\_msg\_recv\_callback* is invoked by **wslay\_event\_recv()** when a message is completely received. **struct wslay\_event\_on\_msg\_recv\_arg** is defined as follows: ``` struct wslay_event_on_msg_recv_arg { uint8_t rsv; uint8_t opcode; const uint8_t *msg; size_t msg_length; uint16_t status_code; }; ``` The *rsv* member and the *opcode* member are reserved bits and opcode of received message respectively. The *rsv* member is constructed as follows: ``` rsv = (RSV1 << 2) | (RSV2 << 1) | RSV3 ``` The *msg* member points to the message of the received message. The *msg\_length* member is the length of message. If a message is close control frame, in other words, **opcode == WSLAY\_CONNECTION\_CLOSE**, *status\_code* is set to the status code in the close control frame. If no status code is included in the close control frame, *status\_code* set to 0. *user\_data* is an arbitrary pointer, which is directly passed to each callback functions as *user\_data* argument. When initialized event-based API context *ctx* is no longer used, use *wslay\_event\_context\_free()* to free any resources allocated for *ctx*. ## RETURN VALUE *wslay\_event\_context\_server\_init()* and *wslay\_event\_context\_client\_init()* returns 0 if it succeeds, or one of the following negative error codes: - **WSLAY\_ERR\_NOMEM** Out of memory. ## SEE ALSO **wslay\_event\_send()**, **wslay\_event\_recv()**, **wslay\_event\_set\_error()** ## AUTHOR Tatsuhiro Tsujikawa ## COPYRIGHT 2012, 2015, Tatsuhiro Tsujikawa