WSLAY_EVENT_QUEUE_FRAGMENTED_MSG(3)

💅 WSLAY_EVENT_QUEUE_FRAGMENTED_MSG — the wslay manual, section 3, bestie edition ✨

okay so you opened the wslay manual (section 3, the library functions girlies) and landed on WSLAY_EVENT_QUEUE_FRAGMENTED_MSG(3). sit down, grab a boba, we're doing this 🧋💖

---

🌸 NAME 🌸

wslay_event_queue_fragmented_msg — queue a fragmented message for future transmission. it's giving "hold this for me, i'll deal with it later" energy 🎀

---

✨ SYNOPSIS ✨

#include <wslay/wslay.h>

int wslay_event_queue_fragmented_msg(wslay_event_context_ptr ctx, const
struct wslay_event_fragmented_msg *arg)

int wslay_event_queue_fragmented_msg_ex(wslay_event_context_ptr ctx,
const struct wslay_event_fragmented_msg *arg, uint8_t rsv)

two whole functions, two whole vibes. the _ex one is just the original but with extra sprinkle ✨

---

🦋 DESCRIPTION 🦋

so wslay_event_queue_fragmented_msg() and wslay_event_queue_fragmented_msg_ex() queue up a fragmented message that you describe in arg. literally just putting it in the queue, bestie, that's the whole job 💅

the struct wslay_event_fragmented_msg is defined like this, and no i did not make this up:

union wslay_event_msg_source {
    int   fd;
    void *data;
};

struct wslay_event_fragmented_msg {
    uint8_t                             opcode;
    union wslay_event_msg_source        source;
    wslay_event_fragmented_msg_callback read_callback;
};

and the callback type itself, iconic:

typedef ssize_t
(*wslay_event_fragmented_msg_callback)(wslay_event_context_ptr ctx,
uint8_t *buf, size_t len, const union wslay_event_msg_source *source,
int *eof, void *user_data)

let's break it down, bestie, one field at a time 👑

• the opcode member is the opcode of the message. that's it, that's the tea ☕
• the source member is a union and normally it contains a "source" to generate message data. it's where the goods come from fr fr
• the read_callback is a callback function that gets called by wslay_event_send() to read message data from source. you don't call it, wslay does. it's the main character, you're just the support 🫶

now the rules for your wslay_event_fragmented_msg_callback implementation, and these are NOT negotiable:

• it must store at most len bytes of data into buf and return the number of stored bytes. at most, bestie. do not overfill, that's a crime 💀
• if all the data is read (i.e., EOF), set *eof to 1. wrap it up, we're done here 🎬
• if no data can be generated at the moment, return 0. not zero bytes of drama, just 0. be patient, she'll come back 🙈
• if there is an error, return -1 and set the error code WSLAY_ERR_CALLBACK_FAILURE using wslay_event_set_error(). communicate, don't ghost 😭

important, and i mean it: this function supports non-control messages only. for control frames you gotta use wslay_event_queue_msg() or wslay_event_queue_close() instead. wrong function, wrong frame, whole situation breaks. no cap 🚫

also this function just queues a message and does not send it. it's the "add to cart" button, not the checkout. the actual sending happens when you call wslay_event_send(), which is the one that ships all these queued messages 📦✨

and then wslay_event_queue_fragmented_msg_ex() is the same deal but it additionally accepts the rsv parameter, which is the reserved bits to send. to set reserved bits, use the macros WSLAY_RSV1_BIT, WSLAY_RSV2_BIT, and WSLAY_RSV3_BIT 🎀 see wslay_event_config_set_allowed_rsv_bits() to find out which reserved bits you're actually allowed to set — don't just set whatever, that's rude 😤

---

🔥 RETURN VALUE 🔥

both wslay_event_queue_fragmented_msg() and wslay_event_queue_fragmented_msg_ex() return 0 if it succeeds. yay, slay, we love a zero 🥳

or it returns one of these negative error codes, and they are all lowkey a bummer:

• WSLAY_ERR_NO_MORE_MSG — could not queue the given message. one of the possible reasons is that a close control frame has already been queued/sent, and no further queueing of messages is allowed. the door is closed, bestie, literally 🚪😭
• WSLAY_ERR_INVALID_ARGUMENT — the given message is invalid; or a bit is set in rsv which is not allowed (go read wslay_event_config_set_allowed_rsv_bits() before you come for me).
• WSLAY_ERR_NOMEM — out of memory. she's full. no room at the inn 💀

---

👑 SEE ALSO 👑

go read these next, they're all in the family:

• wslay_event_queue_msg()
• wslay_event_queue_msg_ex()
• wslay_event_queue_close()

---

🎀 AUTHOR 🎀

Tatsuhiro Tsujikawa. legend behavior, honestly. thank you for your service 🫡💖

---

💜 COPYRIGHT 💜

2024, 2015, Tatsuhiro Tsujikawa.

---

okay that's the whole page, you're officially educated 🌈 this has been the wslay manual, version @PACKAGE_VERSION@, dated Apr 22, and yes the footer is a little cursed but we love her anyway 💅✨ mwah, go queue something fragmented 🦋