1

#ifndef IRC_CONN_H

     2

#define IRC_CONN_H

     3

     4

/**

     5

 * @file

     6

 *

     7

 * Support for connections to IRC servers, a rather fundamental thing. This holds the line_proto to handle the network

     8

 * communications, and then takes care of sending/receiving commands, as well as some core functionality like

     9

 * responding to PING requests, and tracking our current nickname.

    10

 */

    11

    12

struct irc_conn;

    13

    14

#include "error.h"

    15

#include "transport.h"

    16

#include "line_proto.h"

    17

#include "irc_queue.h"

    18

#include "irc_line.h"

    19

#include "irc_cmd.h"

    20

#include <stdbool.h>

    21

    22

/**

    23

 * The info required to register using irc_conn_register()

    24

 */

    25

struct irc_conn_register_info {

    26

    /** Nickname to use on that server */

    27

    const char *nickname;

    28

    29

    /** Username to supply */

    30

    const char *username;

    31

    32

    /** Realname to supply */

    33

    const char *realname;

    34

};

    35

    36

/**

    37

 * Connection state callbacks

    38

 */

    39

struct irc_conn_callbacks {

    40

    /**

    41

     * Recieved RPL_WELCOME, so irc_conn_register has completed, and we are now registered.

    42

     */

    43

    void (*on_registered) (struct irc_conn *conn, void *arg);

    44

    45

    /**

    46

     * The connection has failed in some way, and can not be considered useable anymore. Sending messages won't work,

    47

     * and no more messages will be received. The connection should be destroyed, probably directly from this callback.

    48

     *

    49

     * NOTE: Implementing this callback is mandatory

    50

     */

    51

    void (*on_error) (struct irc_conn *conn, struct error_info *err, void *arg);

    52

    53

    /**

    54

     * The connection was closed cleanly after irc_conn_QUIT.

    55

     *

    56

     * You probably want to destroy the irc_conn now to clean up.

    57

     */

    58

    void (*on_quit) (struct irc_conn *conn, void *arg);

    59

};

    60

    61

/**

    62

 * A single sock_stream connection to a single IRC server, providing a nice interface to the low-level IRC protocol.

    63

 *

    64

 * Create a irc_conn from a connected sock_stream using irc_conn_create(), providing the high-level callbacks. Then,

    65

 * register handlers for the IRC protocol messages recieved from the server using irc_conn_add_cmd_handlers() or

    66

 * irc_cmd_add and irc_conn::handlers/irc_conn::ctcp_handlers.

    67

 *

    68

 * You can then perform the registration step using irc_conn_register(), providing a irc_conn_register_info struct with

    69

 * the relevant info.

    70

 *

    71

 * Once you have succesfully registered (RPL_WELCOME recieved, irc_conn_callbacks::on_registered called,

    72

 * irc_conn::registered set), you can then send messages to the server in the form of irc_line's using the set of

    73

 * irc_conn_send functions.

    74

 */

    75

struct irc_conn {

    76

    /** We are a line-based protocol, this wraps the given sock_stream */

    77

    struct line_proto *lp;

    78

    79

    /** Outgoing line queue */

    80

    struct irc_queue *out_queue;

    81

    82

    /** High-level callbacks */

    83

    struct irc_conn_callbacks callbacks;

    84

    85

    /** Opaque argument for callbacks */

    86

    void *cb_arg;

    87

    88

    /** @defgroup irc_conn_status Status flags

    89

     * @{ 

    90

     */

    91

    /** Registration request sent */

    92

    bool registering;

    93

    94

    /** Registered (as in, we have a working nickname) */

    95

    bool registered;

    96

    97

    /** Quit message sent, waiting for server to close connection */

    98

    bool quitting;

    99

   100

    /** Quit message sent, connection closed, we're done */

   101

    bool quit;

   102

   103

    // @}

   104

   105

    /** 

   106

     * Our current, actual nickname. This is set to NULL while we are still registering, but is then initialized when we

   107

     * get the first RPL_WELCOME message, and then kept up-to-date by handling relevant NICK messages.

   108

     */

   109

    char *nickname;

   110

   111

    /**

   112

     * General IRC command handlers. These handlers are invoked directly for all irc_line's recieved from the IRC

   113

     * server, everything including core PING/NICK/RPL_WELCOME handling is implemented using these. You should add

   114

     * your own handlers using irc_conn_add_cmd_handlers() to implement whatever functionality it is that you want;

   115

     * see irc_cmd.h for more info about how these work. The "command" field is the literal IRC command as received

   116

     * from the server itself.

   117

     *

   118

     * So for example, the following line:

   119

     * \verbatim :nick!user@host PRIVMSG #foo :Hello everyone! \endverbatim

   120

     *

   121

     * results in the following irc_line:

   122

     * \code

   123

     *  { { "nick", "user", "host" }, "PRIVMSG", { "#foo", "Hello everyone!", NULL } }

   124

     * \endcode

   125

     *

   126

     * As with all rules, there are exceptions - CTCP messages are handled differently. PRIVMSG's which contain

   127

     * CTCP extended messages are trapped before these handlers are invoked, and are instead processed using

   128

     * irc_conn::ctcp_handlers. Some built-in CTCP message handlers are provided that then submit these messages back

   129

     * to this main irc_conn::handlers list, as pseudo-irc_line's with a command field like "CTCP ACTION". These

   130

     * include:

   131

     *

   132

     *  CTCP ACTION     - { { "nick", "user", "host" }, "CTCP ACTION", "#foo", "sends an action message" }

   133

     *

   134

     * @see irc_cmd.h

   135

     * @see irc_line

   136

     * @see irc_conn::ctcp_handlers

   137

     */

   138

    struct irc_cmd_handlers handlers;

   139

   140

    /** 

   141

     * CTCP command handlers. These handlers are invoked for all PRIVMSG's recieved from the IRC server which begin

   142

     * with the CTCP X-DELIM char (in other words, a simplified CTCP spec is implemented). These PRIVMSG's will not be

   143

     * seen using irc_conn::handlers. These CTCP messages are then parsed, and a pseudo-irc_line is created, with the

   144

     * same source as the real message, the command set to the CTCP extended message tag, args[0] as the PRIVMSG's

   145

     * destination, and args[1] as the rest of the CTCP extended message payload.

   146

     *

   147

     * So for example, the following line:

   148

     * \verbatim :nick!user@host PRIVMSG #foo :\001ACTION does  something lame\001 \endverbatim

   149

     *

   150

     * results in the following irc_line:

   151

     * \code

   152

     *  { { "nick", "user", "host" }, "ACTION", "#foo", "does  something lame" }

   153

     * \endcode

   154

     *

   155

     * Internally, some of these CTCP messages are then redirected back to handlers for convenience; currently only

   156

     * "ACTION".

   157

     *

   158

     * @see irc_cmd.h

   159

     * @see irc_line

   160

     * @see irc_conn::handlers

   161

     */

   162

    struct irc_cmd_handlers ctcp_handlers;

   163

};

   164

   165

/**

   166

 * Create a new irc_conn using the given sock_stream, which should be connected to an IRC server (i.e. ready for

   167

 * read/write).

   168

 *

   169

 * This does not yet send any requests to the server, it only sets up the core state. Use irc_conn_register() to 

   170

 * actually register with the server.

   171

 *

   172

 * On success, the resulting irc_conn is returned via *conn_ptr with SUCCESS. Otherwise, ERR_* with error info returned

   173

 * via *err.

   174

 *

   175

 * @param conn_ptr returned new irc_conn structure

   176

 * @param transport connected transport

   177

 * @param callbacks the high-level status callbacks, required

   178

 * @param cb_arg opqaue context argument for callbacks

   179

 * @param err returned error info

   180

 */

   181

err_t irc_conn_create (struct irc_conn **conn_ptr, transport_t *transport, const struct irc_conn_callbacks *callbacks, 

   182

        void *cb_arg, error_t *err);

   183

   184

/**

   185

 * Destroy the irc_conn state, terminating any connection and releasing all resources.

   186

 *

   187

 * This does not end the session cleanly, and is intended mainly to be used after clean exit, or to clean up after errors.

   188

 */

   189

void irc_conn_destroy (struct irc_conn *conn);

   190

   191

/**

   192

 * Add a new chain of command handler callbacks to be used to handle irc_lines from the server. The given arg will be

   193

 * passed to the callbacks as the context argument. The chain will be appended to the end of the current list of chains.

   194

 *

   195

 * @param conn the connection to use

   196

 * @param handlers the array of irc_cmd_handler structs, terminated with a NULL entry

   197

 * @param arg the context argument to use for the callbacks

   198

 */

   199

err_t irc_conn_add_cmd_handlers (struct irc_conn *conn, struct irc_cmd_handler *handlers, void *arg);

   200

   201

/**

   202

 * Register with the IRC server using the given registration info (initial nickname etc.)

   203

 *

   204

 * This sends the NICK/USER command sequence.

   205

 *

   206

 * @param conn the connection to use

   207

 * @param info the information required to register, including nickname/username/etc

   208

 */

   209

err_t irc_conn_register (struct irc_conn *conn, const struct irc_conn_register_info *info);

   210

   211

/**

   212

 * Compare the given nickname against our current nickname, returning true if it represents ourselves.

   213

 *

   214

 * As a convenience function, this is NULL-safe - it can safely be called with a NULL conn, NULL nickname, or a

   215

 * conn that doesn't yet have a nickname, and it will simply return false.

   216

 */

   217

bool irc_conn_self (struct irc_conn *conn, const char *nickname);

   218

   219

/**

   220

 * Send a generic IRC message by formatting the given irc_line and sending it as a line.

   221

 *

   222

 * Use the irc_conn_COMMAND functions defined below for a more convenient interface.

   223

 *

   224

 * An error is returned if the line contains invalid data or writing the line to the sock_stream fails. Possible socket

   225

 * failures will also be reported using irc_conn_callbacks::on_error, so ignoring return values from this is usually

   226

 * OK...

   227

 *

   228

 * @param conn the IRC protocol connection

   229

 * @param line the irc_line protocol line to send

   230

 */

   231

err_t irc_conn_send (struct irc_conn *conn, const struct irc_line *line);

   232

   233

/**

   234

 * @defgroup irc_conn_COMMAND Simple request functions

   235

 *

   236

 * These functions all simply build the corresponding irc_line struct, and then pass it on to irc_conn_send().

   237

 *

   238

 * @{

   239

 */

   240

   241

/**

   242

 * Send a NICK message. Usually either called indirectly via irc_conn_register, or used to change to a new nickname.

   243

 *

   244

 * If succesfull, this will result in a NICK message for our current nickname; irc_conn will handle this to update 

   245

 * irc_conn::nickname.

   246

 *

   247

 * @param conn the IRC protocol connection

   248

 * @param nickname the new nickname to use

   249

 *

   250

 * Possible errors (from RFC2812):

   251

 *  ERR_NONICKNAMEGIVEN

   252

 *  ERR_NICKNAMEINUSE

   253

 *  ERR_UNAVAILRESOURCE

   254

 *  ERR_ERRONEUSNICKNAME

   255

 *  ERR_NICKCOLLISION

   256

 *  ERR_RESTRICTED

   257

 */

   258

err_t irc_conn_NICK (struct irc_conn *conn, const char *nickname);

   259

   260

/**

   261

 * Send a USER message. Usually called indirectly via irc_conn_register.

   262

 *

   263

 * @param conn the IRC protocol connection

   264

 * @param username the username to register with, may be replaced with username from ident reply

   265

 * @param realname the full-name to register with

   266

 *

   267

 * Possible errors (from RFC2812):

   268

 *  ERR_NEEDMOREPARAMS

   269

 *  ERR_ALREADYREGISTRED

   270

 */

   271

err_t irc_conn_USER (struct irc_conn *conn, const char *username, const char *realname);

   272

   273

/**

   274

 * Send a PONG message to the given target.

   275

 *

   276

 * Note that you do not need to handle the normal PING/PONG cycle, irc_conn does this for you.

   277

 *

   278

 * @param conn the IRC protocol connection

   279

 * @param target the PING source, aka. the target to send the PONG reply to

   280

 *

   281

 * Possible errors (from RFC2812):

   282

 *  ERR_NOORIGIN

   283

 *  ERR_NOSUCHSERVER

   284

 */

   285

err_t irc_conn_PONG (struct irc_conn *conn, const char *target);

   286

   287

/**

   288

 * Send a simple JOIN message for the given channel. Note that this does not implement all possible arguments.

   289

 *

   290

 * If succesfull, this will result in a JOIN message for us on the given channel, plus a series of

   291

 * RPL_NAMREPLY/RPL_ENDOFNAMES/RPL_TOPIC/etc messages.

   292

 *

   293

 * @param conn the IRC protocol connection

   294

 * @param channel the full channel name to join

   295

 *

   296

 * Possible errors (from RFC2812):

   297

 *  ERR_NEEDMOREPARAMS              ERR_BANNEDFROMCHAN

   298

 *  ERR_INVITEONLYCHAN              ERR_BADCHANNELKEY

   299

 *  ERR_CHANNELISFULL               ERR_BADCHANMASK

   300

 *  ERR_NOSUCHCHANNEL               ERR_TOOMANYCHANNELS

   301

 *  ERR_TOOMANYTARGETS              ERR_UNAVAILRESOURCE

   302

 *

   303

 */

   304

err_t irc_conn_JOIN (struct irc_conn *conn, const char *channel);

   305

   306

/**

   307

 * Send a PRIVMSG message to some target, usually a channel or another user (nickname).

   308

 *

   309

 * Note that the protocol limits messages to 512 bytes in length (total, including other protocol stuff), and messages

   310

 * can't contain newlines or NULs - this will return an ERR_IRC_LINE_* in both cases.

   311

 *

   312

 * If succesfull, this won't result in any reply. If the target is a nickname, the server supports AWAY, and the target

   313

 * has marked themselves as away, this may result in an RPL_AWAY reply.

   314

 *

   315

 * @param conn the IRC protocol connection

   316

 * @param target the message target, usually either a channel name or a nickname

   317

 * @param message the message to send

   318

 *

   319

 * Possible errors (from RFC2812):

   320

 *  ERR_NORECIPIENT                 ERR_NOTEXTTOSEND

   321

 *  ERR_CANNOTSENDTOCHAN            ERR_NOTOPLEVEL

   322

 *  ERR_WILDTOPLEVEL                ERR_TOOMANYTARGETS

   323

 *  ERR_NOSUCHNICK

   324

 *

   325

 */

   326

err_t irc_conn_PRIVMSG (struct irc_conn *conn, const char *target, const char *message);

   327

   328

/**

   329

 * Send a NOTICE messaeg to some target, usually a channel or another user (nickname).

   330

 *

   331

 * The same limitations on message length and data apply as for irc_conn_PRIVMSG.

   332

 *

   333

 * The only difference between PRIVMSG and NOTICE is that NOTICE messages should never generate an automated reply,

   334

 * hence, they are used for e.g. CTCP replies, and ideally, for IRC bot output.

   335

 *

   336

 * @param conn the IRC protocol connection

   337

 * @param target the message target, usually either a channel name or a nickname

   338

 * @param message the message to send

   339

 *

   340

 * Possible errors (from RFC2812):

   341

 *  None. Servers do not ever reply to NOTICE messages.

   342

 */

   343

err_t irc_conn_NOTICE (struct irc_conn *conn, const char *target, const char *message);

   344

   345

/**

   346

 * Send a QUIT message to the server. The server will reply with an ERROR message and close the connection.

   347

 *

   348

 * This updates our state as disconnecting, and once EOF is recieved, the irc_conn_callbacks::on_quit callback is

   349

 * called.

   350

 *

   351

 * @param conn the IRC protocol connection

   352

 * @param message the quit message, which may be displayed to other clients

   353

 */

   354

err_t irc_conn_QUIT (struct irc_conn *conn, const char *message);

   355

   356

// @}

   357

   358

#endif /* IRC_CONN_H */