roar_vs_role(3)

📦 version 1.0~beta12, in ubuntu jammy

💅 roar_vs_role(3) — the RoarAudio Programmer's Manual, but make it cute

okay bestie, so this is a page from the RoarAudio Programmer's Manual, and today's main character is roar_vs_role(3). yes the manual section is literally (3), that's the "library functions" section, iykyk 🎀

✨ NAME ✨

roar_vs_role — Update role for a stream

like… you're telling the stream what it is. its vibe. its role. 🦋

🌸 SYNOPSIS 🌸

#include <roaraudio.h>

int     roar_vs_role          (roar_vs_t * vss, int role, int * error);

that's the whole signature, no cap. copy it exactly, don't freestyle the types 💖

👑 DESCRIPTION 👑

This function updates the role of the stream. That's the whole job. That's the assignment and she ATE. 🔥

So when should you call it? The manual says you should do this before any read or write operation, okay? before. like, get your life together before you start touching the stream, bestie.

but also — and this is the slay part — it can be used at any time to update the meta data. so it's not a one-and-done thing, you can come back and change the role whenever. main character energy, she's flexible 💅

🎀 PARAMETERS 🎀

  • vss — the VS object to be updated. this is the thing getting the glow-up.
  • role — the new role of the stream. the new identity. the new era. ✨
  • error — this is a pointer to a integer used to store the error value in case of error. yes, "a integer", we're quoting the original grammar and moving on 🫶. This can be NULL if not used, but it is very recommended to use this error value to report good error messages to the user. like, pls. your users deserve nice error messages. don't leave them on read 😭

⭐ RETURN VALUE ⭐

  • On success these calls return 0. 🎉
  • On error, -1 is returned. 💀

that's it, that's the whole vibe check.

🌈 EXAMPLES 🌈

here's the example, verbatim, exactly as the manual gives it:

 struct roar_keyval kv[2] = {
  {.key = "TITLE",  .value = "Some title"},
  {.key = "ARTIST", .value = "Some artist"}
 };
 ret = roar_vs_meta(vss, &kv, 2, &err);
not me noticing the example calls roar_vs_meta and not roar_vs_role 🙈 — that's literally what the manual shows tho, so we're keeping it exactly as-is. no edits, no fixing, we don't do that here. 💖

💜 SEE ALSO 💜

go read these next, bestie, they're all part of the same friend group:

and that's the page!! source is RoarAudio, dated May 2011, and the page itself is roar_vs_role(3). mwah, go update some roles, you've got this 🧚✨

📦 where this page comes from