gensio_accepter_event(3)

💖 gensio_accepter_event — the manual page, but make it make sense 💖

ok so real talk, bestie: this is from the Library Functions Manual, and it's all about gensio_accepter_event, the callback that fires when stuff happens on a gensio accepter. it's giving "your accepter has gossip and it needs to tell you." let's get into it 🫶

✨ NAME ✨

gensio_accepter_event — event handler for events from a gensio 🌸

✨ SYNOPSIS ✨

#include <gensio/gensio.h>

typedef int (*gensio_accepter_event)(struct gensio_accepter *acc,
                    void *user_data,
                    int event, void *data);

✨ DESCRIPTION ✨

okay so when an event happens on a gensio accepter and it gets reported to you, the gensio library calls the gensio_accepter_event type handler that you registered with the gensio accepter. that's it, that's the whole job. you signed up for the tea, now you're getting the tea 💅

the way the various parameters work depends on which event it is, but some of them are always the same, no cap:

• acc — the gensio_accepter the event is being reported for. the main character in question 👑
• user_data — the user_data you supplied back when the event handler got registered. your little snack you left for future you 🍓
• event — the particular event being reported. the plot twist.
• data — data specific to the event (may not be used). sometimes it's a whole struct, sometimes it's just vibes and nothing.

now. the events. buckle up ✨

🌈 GENSIO_ACC_EVENT_NEW_CONNECTION

got a new connection on the accepter!! 🎉 data points to the new gensio.

🌈 GENSIO_ACC_EVENT_LOG

struct gensio_loginfo {
    enum gensio_log_levels level;
    char *str;
    va_list args;
};

the gensio accepter had an issue that wouldn't otherwise be reported as an error return. lowkey it's just logging the drama instead of throwing it at you. data points to a struct gensio_loginfo.

🌈 GENSIO_ACC_EVENT_PRECERT_VERIFY

called right before certificate verification on a new incoming connection. see GENSIO_EVENT_PRECERT_VERIFY in gensio_event(3) for details. data points to the new gensio object. ⚠️ note that this gensio has not yet been reported in a new connection — it's the sneak peek before the official announcement, iykyk.

🌈 GENSIO_ACC_EVENT_AUTH_BEGIN

called at the start of an authorization process for a new connection. see GENSIO_EVENT_AUTH_BEGIN in gensio_event(3) for details. data points to the new gensio object. same warning as above, bestie: this gensio has not yet been reported in a new connection.

🌈 GENSIO_ACC_EVENT_PASSWORD_VERIFY

struct gensio_acc_password_verify_data {
    struct gensio *io;
    char *password;
    gensiods password_len;
};

a server gensio has received a password that requires verification. plot twist: the gensio handlers do not actually verify the passwords — they just transfer them and hand them over so you can verify them. it's giving "not my job, that's yours 💅". data points to a struct gensio_acc_password_verify_data that holds the new gensio and the password information. see GENSIO_EVENT_PASSWORD_VERIFY in gensio_event(3) for details.

🌈 GENSIO_ACC_EVENT_REQUEST_PASSWORD

a remote server gensio has requested that a password be sent for verification. data points to a struct gensio_acc_password_verify_data that holds the new gensio and the password information. see GENSIO_EVENT_REQUEST_PASSWORD in gensio_event(3) for details.

🌈 GENSIO_ACC_EVENT_POSTCERT_VERIFY

struct gensio_acc_postcert_verify_data {
    struct gensio *io;
    int err;
    const char *errstr;
};

a server gensio has finished certificate verification (and has not done any password verification). the cert arc concluded, no password subplot. data points to a struct gensio_acc_postcert_verify_data that holds the new gensio and error information. see GENSIO_EVENT_POSTCERT_VERIFY in gensio_event(3) for details.

✨ OTHER EVENTS ✨

other gensio accepters that aren't part of the gensio library proper may have their own events too. so like, if you're working with a custom accepter, don't be surprised if it shows up with events you've never met. it's got lore 🦋

✨ RETURN VALUES ✨

see the individual events for the values you should return. and here's the important part, no skipping:

if an event is not handled by the event handler, the handler must return GE_NOTSUP — except in the case of GENSIO_ACC_EVENT_NEW_CONNECTION, which must be handled. that one is non-negotiable. it's the main character of events and you cannot ghost it 😭

✨ SEE ALSO ✨

• gensio_err(3)
• gensio(5)
• gensio_event(3)
• gensio_acc_set_callback(3)
• str_to_gensio_accepter(3)

ok that's the whole page bestie, you ate it up 💅✨ this was gensio_accepter_event(3) from the Library Functions Manual, dated 27 Feb 2019 — and yeah, that date is giving vintage, but the callback energy is timeless. go register that handler, slay, periodt 🎀🦋💖