WSLAY_EVENT_RECV(3)

💖 WSLAY_EVENT_RECV 💖

okay so bestie, welcome to the wslay manual, section 3 (that's the library-functions section, iykyk). today's main character is wslay_event_recv(3) and she is literally the one who pulls messages off the wire for you. let's get into it 🫶

---

✨ NAME ✨

wslay_event_recv — Receive messages 💌

---

🌸 SYNOPSIS 🌸

#include <wslay/wslay.h>

int wslay_event_recv(wslay_event_context_ptr ctx)

---

🦋 DESCRIPTION 🦋

wslay_event_recv() receives messages from the peer. the way it does that is it leans on the wslay_event_recv_callback function. and here's the thing — one single call of this function doesn't just grab one message, no ma'am, it keeps receiving multiple messages until wslay_event_recv_callback sets the error code WSLAY_ERR_WOULDBLOCK. that's the lil stop sign. 🛑

so wslay_event_recv() calls the following callback functions, each one for its own event (peep wslay_event_context_server_init() or wslay_event_context_client_init() if you want the full deets on each of these callbacks).

• wslay_event_on_frame_recv_start_callback — called when a new frame starts to be received. 🎬
• wslay_event_on_frame_recv_start_callback — called when a new frame starts to be received. (and yes bestie, she's listed twice in the original — iconic behavior, we keep it exactly as-is 💅)
• wslay_event_on_frame_recv_chunk_callback — called when a chunk of frame payload is received. 🧩
• wslay_event_on_frame_recv_end_callback — called when a frame is completely received. ✅
• wslay_event_on_msg_recv_callback — called when a message is completely received. 📬

now the automatic stuff, and this is lowkey the slay part:

• when a close control frame is received, this function automatically queues a close control frame. also, it calls wslay_event_set_read_enabled() with the second argument 0, which disables any further read from the peer. 🚪
• when a ping control frame is received, this function automatically queues a pong control frame. 🏓

and in case of a fatal error — the kind that leads to a negative return code — this function calls wslay_event_set_read_enabled() with the second argument 0 to disable further read from the peer. same energy, sadder context. 😭

---

💜 RETURN VALUE 💜

wslay_event_recv() returns 0 if it succeeds 🎉 — or one of these negative error codes, and no, we are not happy about them:

• WSLAY_ERR_CALLBACK_FAILURE — user defined callback function is failed. 💀
• WSLAY_ERR_NOMEM — out of memory. 🙈

🚨 major warning, bestie, listen up: when a negative error code is returned, the application must not make any further call of wslay_event_recv() and must close the WebSocket connection. that's not a suggestion, that's the rules. periodt. 💅

---

🎀 SEE ALSO 🎀

• wslay_event_set_read_enabled()

---

👑 AUTHOR 👑

Tatsuhiro Tsujikawa 🌟

---

🌈 COPYRIGHT 🌈

2024, 2015, Tatsuhiro Tsujikawa

---

okay that's the whole page, bestie — this one shipped in @PACKAGE_VERSION@ and the date on it is Apr 22, 2024, so go forth, call your callbacks, respect the WSLAY_ERR_WOULDBLOCK, and close those connections when you're told to. mwah 💖✨🎀