Events

twirc_events_t *evt

The event struct will be handed into your event handler functions for almost all events. Only for the connect and disconnect events will this be NULL. When given, it contains all the information about the received message. It provides the raw message, the individual parts of the message, as well as some convenience members that give direct access to often required pieces of information. The event struct contains the following members:

• char *raw
  Contains the raw IRC message as received from the server. Great for debugging.

• char *prefix
  The prefix part of the IRC message as defined in the IRC RFC. This is usually either tmi.twitch.tv or a string like [email protected], where domsson is the username of the user who caused the event. If the message did not contain a prefix, this will be NULL.

• char *command
  The command part of the IRC message as defined in the IRC RFC. This is mostly PRIVMSG or NOTICE, but can be a lot of other things, some of them specific to Twitch IRC.

• char **params
  Array of strings, where each string is a parameter of the IRC message as defined in the IRC RFC. The parameters usually contain the channel and actual chat message, but it always depends on the type of event. If the message did not contain any parameter, this will be NULL.

• size_t num_params
  Number of parameters in params.

• int trailing
  The index of the trailing (last) parameter in params.

• twirc_tag_t **tags
  An array of twirc_tag_t structs, where every struct contains the members key and value. The array contains one struct for each tag in the IRC message. tags Will be NULL if the message did not contain any tags.

• size_t num_tags
  Number of elements in tags.

• char *origin
  If the prefix represented a username, this is the cleaned version of it that can be used as argument for other functions. If the prefix did not contain a username, this will be NULL.

• char *channel
  If the parameters contained a channel, it will be provided in channel, otherwise this will be NULL.

• char *target
  If a message had a target user, for example the target of a ban, timeout, host or raid, it will be provided in target. Otherwise, this will be NULL.

• char *message
  If the IRC message contained an actual text message, which is always the case for regular chat messages in a channel, it can be accessed through this member. Otherwise this will be NULL.

• char *ctcp In case of a CTCP message, which is a special type of IRC message, this will contain the CTCP command. Otherwise NULL.

Callbacks

twirc_callback connect

Will be fired once the connection to the server has been established. For this event, the twirc_event_t *evt argument will actually be NULL. You most likely don't need to handle this, it makes more sense to handle the welcome and/or globaluserstate events.

twirc_callback welcome

We received the welcome message (command "001") from the server, which means we are now logged in.

twirc_callback globaluserstate

Similar to welcome, as it also indicates successful login, but this carries additional information: the tags from this event will contain details on your account, for example your display-name and user-id.

twirc_callback capack

Twitch confirmed capabilities that we have requested. The request is being done automatically by libtwirc and it is highly unlikely that Twitch would not grant them, so you can probably ignore this.

twirc_callback ping

The Twitch server will send you a PING every now and then. You have to react to this with an appropriate PONG, otherwise you will be disconnected. Fortunately for you, libtwirc does this automatically, so you don't need to handle this event unless you want to know about pings for some other reason.

twirc_callback join

A user has joined a channel we're in. Notice, however, that these events will be sent in batches and you will usually receive one for every user in a channel that you have just joined. This is not a reliable way to detect users actually coming into a stream. You should probably only use this to detect your own joining of channels. evt->origin will contain the name of the user who joined, evt->channel contains the channel in which the join occurred.

twirc_callback part

A user has left a channel we're in. Equally unreliable as join, I don't recommend doing anything with this. Again, evt->origin and evt->channel will contain the affected user and channel.

twirc_callback mode

User in a channel we're in gained/lost mod status. Also comes in batches. Sometimes isn't send at all. Not very reliable, hence not too helpful.

twirc_callback names

When you join a channel, you will receive a list of users in the channel - unless there are too many users in the channel, in which case you will only receive a list of the moderators. This is the event that catches this list. Note, however, that the list can - and usually does - come in multiple separate messages.

twirc_callback privmsg

A user in a channel we're in has sent a message to the channel. In other words, a chat message. You probably want to handle this. evt->origin is the name of the user who sent the message, evt->channel is the channel to which the message was sent, evt->message will contain the actual chat message.

twirc_callback whisper

We have received a whisper (private message). evt->origin will contain the username of the sender.

twirc_callback action

A user used the /me command in a channel we're in. Similar to privmsg, so evt->origin, evt->channel and evt->message will be filled with the relevant information.

twirc_callback notice

Notices from the server. There is a whole host of possible notices. I recommend handling these and logging/printing them to get a good idea of what comes through here.

twirc_callback roomstate

You should receive this when you join a channel (room), but also when something about the channel changes. A change could be a channel setting, for example when follower only mode is activated, but sometimes this is also being sent when a user joins a channel. According to my testing, it does not always trigger on joins though.

twirc_callback usernotice

This event is triggered when a user subs, resubs, gifts a sub, when a raid is incoming or when a "ritual" occurs. For this event, the evt->channel member should contain the affected channel, evt->message might contain an optional message. Do check both of these for NULL before using them, though.

twirc_callback userstate

According to the Twitch documentation, this event occurs when a user joins a channel or sends a message in a channel. Your mileage may vary. Let me know if you figure this one out properly. :-)

twirc_callback clearchat

This event can mean two things, either a user has been banned in a channel and all of their messages have hence been deleted, or someone used the /clear command to completely delete the chat history. evt->channel should contain the affected channel.

twirc_callback clearmsg

A single chat message has been removed in a channel. evt->channel should contain the affected channel, evt->message should hold the deleted message. Additionally, the target-msg-id tag should be present and contain the UUID of the deleted message.

twirc_callback hosttarget

You'll see this when a channel starts or stops host mode, in other words when a channel you are in starts hosting another channel or stops hosting and goes back to normal operation. evt->channel contains the channel that hosts, evt->target should contain the user who is being hosted or NULL for when a host has ended.

twirc_callback reconnect

This means the server is announcing that it will go for a restart soon. If you want to handle this, I recommend setting a flag in your program, so that when you disconnect shortly after, you know that you can reconnect a little while later, as the disconnect was expected.

twirc_callback disconnect

The connection to the server was interrupted. The evt will be NULL for this event!

twirc_callback invalidcmd

The server did not recognize a command you've sent it earlier. evt->params[1] should contain the invalid command, but check evt->num_params for whether there really are at least 2 parameters before trying to access it.

twirc_callback other

Should Twitch introduce some new kind of message/event that is unknown to libtwirc, it will come through here.

twirc_callback outbound

This is fired for every messages that we send to the server. For this event, only evt->raw will be set! This is mainly for debugging. If people find this generally useful, I might extend this so that the other event struct members are also set. Let me know what you think.