Example

Example code

For some actual example code that uses libtwirc, check out twircclient. Alternatively, here is the rough outline of what you'll have to do to get a connection up.

Include the header and link to the library

Once you've installed libtwirc, all you have to do to get going is to include the header file:

#include "libtwirc.h"

To compile your code, you will also have to link to libtwirc. To do that, add -ltwirc to your gcc command.

Initialize libtwirc

First, you need an instance of a twirc_state_t. That's a struct that holds all the important information regarding your IRC connection and will have to be handed to every relevant function from this point on. To get this struct, use twirc_init():

twirc_state_t *s = twirc_init();

Write event handlers

To be notified of incoming IRC messages, you have to write at least one event handler function. It has to have the following signature: void handler(twirc_state_t *s, twirc_event_t *evt);. Here is a very simple event handler that will simply print the raw message from the server:

void handle_all(twirc_state_t *s, twirc_event_t *evt)
{
    fprintf(stdout, "> %s\n", evt->raw);
}

Set up event handlers

To have your event handler being called upon certain incoming communication, we'll have to register it with the twirc_state_t like so:

twirc_callbacks_t *cbs = twirc_get_callbacks(s);
cbs->welcome = handle_all;
cbs->privmsg = handle_all;

This let's libtwirc know that it should call your handle_all() function for the welcome and privmsg events. We'll talk about the different events in just a bit.

Connect to Twitch

In order to connect to Twitch chat, you need* a valid Twitch account (this can be your primary account, but you can also create another account that you want to use for this) and an oauth token. To get the oauth token, you can use the Twitch Chat OAuth Password Generator. Once you have all that, you are ready to roll:

twirc_connect("irc.chat.twitch.tv", "6667", NICK, TOKEN);

This will return 0 if the connection was established successfully, -1 on error.

_{*) Actually, I lied - you don't need one. You can connect anonymously instead, but you will be very limited in what you can do.}

Wait for and process events

Now you are ready to run an endless loop that waits for IRC messages, then dispatches events to your event handlers once a message comes in. The simplest way to achieve this is to use the twirc_loop() function. This is all it takes:

twirc_loop(s);

This function will return once the connection to the server was interrupted or an error occurred.

Clean up

Once the loop finished running, you should clean up the resources. The easiest way to do this is to use twirc_kill(), which will make sure that the connection is indeed closed and then free the twirc_state_t struct for you:

twirc_kill(s);

Do something useful

In order to make this somewhat more interesting, let's add two additional event handlers. One will handle the welcome event, which signifies that your bot was successfully authenticated. This is the perfect place to join a channel. Then, we'll also handle the join event, which is fired when a user joins a channel we're in - and happens to also fire for when we join the channel. This allows us to dispatch a message once we've joined the channel:

void handle_welcome(twirc_state_t *s, twirc_event_t *evt)
{
    twirc_cmd_join(s, "#domsson");
}

void handle_join(twirc_state_t *s, twirc_event_t *evt)
{
    // Check if 'origin' (the name of the user who triggered the event) 
    // was us and the channel is the one we are interested in
    if (strcmp(evt->channel, "#domsson") == 0 && strcmp(evt->origin, NICK) == 0)
    {
        twirc_cmd_privmsg(s, "#domsson", "Hello world!");
    }
}

Next steps

• Check the event reference for a list of all events in libtwirc
• Check the command reference for all commands you can send via libtwirc
• Check out twircclient for two working examples using libtwirc