WSLAY_EVENT_CONTEXT_CLIENT_INIT(3)

💅 NAME 💅

wslay_event_context_client_init — the one that sets up your event-based API context. It's giving "let's go, client side" energy. ✨

---

✨ SYNOPSIS ✨

#include <wslay/wslay.h>

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 🫶

okay so, two besties, two jobs. wslay_event_context_server_init() spins up an event-based API context for WebSocket server use, and wslay_event_context_client_init() spins up one for WebSocket client use. If either one comes back successful, ctx is gonna point at a struct holding literally every resource you need to process WebSocket protocol transfers. slay. 💖

callbacks is a pointer to wslay_event_callbacks, and it's defined like this, no cap:

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;
};

🦋 the callback girlies 🦋

wslay_event_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 gets called by wslay_event_recv() when it wants more data from the peer. Your implementation has to read at most len bytes from the peer, stash them in buf, and return the number of bytes read. flags is always 0 in this version. periodt.

If something goes wrong, return -1 and set the error code to WSLAY_ERR_CALLBACK_FAILURE using wslay_event_set_error(). Wslay's event-based API as a whole assumes non-blocking I/O. If the error cause is EAGAIN or EWOULDBLOCK, set WSLAY_ERR_WOULDBLOCK instead. This one is important because it tells wslay_event_recv() to stop receiving further data and return. 👑

wslay_event_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 gets called by wslay_event_send() when it wants to send more data to the peer. Your implementation has to send at most len bytes to the peer and return the number of bytes sent. flags is the bitwise OR of zero or more of these:

• WSLAY_MSG_MORE — there is more data to send. It's just dropping some hints to tune performance and behaviour. 💫

If something goes wrong, return -1 and set the error code to WSLAY_ERR_CALLBACK_FAILURE using wslay_event_set_error(). Again: the Wslay event-based API on the whole assumes non-blocking I/O. If the cause of the 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. 🛑

wslay_event_genmask_callback

typedef int (*wslay_event_genmask_callback)(wslay_event_context_ptr ctx,
uint8_t *buf, size_t len, void *user_data)

genmask_callback gets called by wslay_event_send() when it wants a fresh mask key. As described in RFC6455, only the traffic coming from the WebSocket client is masked, so this callback is only needed if you initialized the event-based API for WebSocket client use. Your implementation has to fill exactly len bytes of data into buf and return 0 on success. If there's an error, return -1 and set the error code to WSLAY_ERR_CALLBACK_FAILURE using wslay_event_set_error(). 🔐

wslay_event_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 gets called by wslay_event_recv() when a new frame starts being received. Heads up: this one fires only once per frame. The wslay_event_on_frame_recv_start_arg is defined like this:

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 are the fin bit, the reserved bits and the opcode of a frame. payload_length is the payload length of a frame. 🎀

wslay_event_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 gets called by wslay_event_recv() when a chunk of frame payload has been received. wslay_event_on_frame_recv_chunk_arg is defined like this:

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 that chunk. 🍓

wslay_event_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 gets called by wslay_event_recv() when a frame is completely received. the end, bestie. ✨

wslay_event_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 gets called by wslay_event_recv() when a message is completely received. And wslay_event_on_msg_recv_arg is defined like this:

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 the reserved bits and the opcode of the received message, respectively. The rsv member is constructed like this:

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 the message. If a message is a close control frame — in other words, opcode == WSLAY_CONNECTION_CLOSE — then status_code is set to the status code in the close control frame. And if no status code is included in the close control frame, status_code is set to 0. 🧚

---

user_data is an arbitrary pointer, and it gets passed directly to each callback function as the user_data argument. it's giving "your personal little luggage". 💜

When your initialized event-based API context ctx is no longer used, call wslay_event_context_free() to free any resources allocated for ctx. don't ghost your memory, bestie. 😭

---

🔥 RETURN VALUE 🔥

wslay_event_context_server_init() and wslay_event_context_client_init() return 0 if it succeeds, or one of these negative error codes:

• WSLAY_ERR_NOMEM — out of memory. that's it, that's the whole list. 💀

---

👀 SEE ALSO 👀

wslay_event_send(), wslay_event_recv(), wslay_event_set_error() — go read these next, iykyk. 📚

---

🌸 AUTHOR 🌸

Tatsuhiro Tsujikawa — the icon, the legend, the main character. 👑

---

🎀 COPYRIGHT 🎀

2024, 2015, Tatsuhiro Tsujikawa. periodt.

---

and that's the whole page, bestie!! 💖✨🦋 this one shipped in @PACKAGE_VERSION@, dated Apr 22, 2024 — go forth and init those contexts, you absolute legend 🫶💅🌈