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.

    12

 */

    13

    14

struct irc_conn;

    15

    16

#include "error.h"

    17

#include "transport.h"

    18

#include "line_proto.h"

    19

#include "irc_queue.h"

    20

#include "irc_line.h"

    21

#include "irc_cmd.h"

    22

#include <stdbool.h>

    23

    24

/**

    25

 * The info required to register using irc_conn_register()

    26

 */

    27

struct irc_conn_register_info {

    28

    /** Nickname to use on that server */

    29

    const char *nickname;

    30

    31

    /** Username to supply */

    32

    const char *username;

    33

    34

    /** Realname to supply */

    35

    const char *realname;

    36

};

    37

    38

/**

    39

 * Connection state callbacks

    40

 */

    41

struct irc_conn_callbacks {

    42

    /**

    43

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

    44

     */

    45

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

    46

    47

    /**

    48

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

    49

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

    50

     *

    51

     * NOTE: Implementing this callback is mandatory

    52

     */

    54

    55

    /**

    56

     * The connection was closed cleanly after irc_conn_QUIT.

    57

     *

    58

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

    59

     */

    60

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

    61

};

    62

    63

/**

    64

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

    65

 *

    66

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

    67

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

    68

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

    69

 *

    70

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

    71

 * the relevant info.

    72

 *

    73

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

    74

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

    75

 * irc_conn_send functions.

    76

 */

    77

struct irc_conn {

    78

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

    79

    struct line_proto *lp;

    80

    81

    /** Outgoing line queue */

    82

    struct irc_queue *out_queue;

    83

    84

    /** High-level callbacks */

    85

    struct irc_conn_callbacks callbacks;

    86

    87

    /** Opaque argument for callbacks */

    88

    void *cb_arg;

    89

    90

    /** @defgroup irc_conn_status Status flags

    91

     * @{ 

    92

     */

    93

    /** Registration request sent */

    94

    bool registering;

    95

    96

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

    97

    bool registered;

    98

    99

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

   100

    bool quitting;

   101

   102

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

   103

    bool quit;

   104

   105

    // @}

   106

   107

    /** 

   108

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

   109

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

   110

     */

   111

    char *nickname;

   112

   113

    /**

   114

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

   115

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

   116

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

   117

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

   118

     * from the server itself.

   119

     *

   120

     * So for example, the following line:

   121

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

   122

     *

   123

     * results in the following irc_line:

   124

     * \code

   125

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

   126

     * \endcode

   127

     *

   128

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

   129

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

   130

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

   131

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

   132

     * include:

   133

     *

   134

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

   135

     *

   136

     * @see irc_cmd.h

   137

     * @see irc_line

   138

     * @see irc_conn::ctcp_handlers

   139

     */

   140

    struct irc_cmd_handlers handlers;

   141

   142

    /** 

   143

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

   144

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

   145

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

   146

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

   147

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

   148

     *

   149

     * So for example, the following line:

   150

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

   151

     *

   152

     * results in the following irc_line:

   153

     * \code

   154

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

   155

     * \endcode

   156

     *

   157

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

   158

     * "ACTION".

   159

     *

   160

     * @see irc_cmd.h

   161

     * @see irc_line

   162

     * @see irc_conn::handlers

   163

     */

   164

    struct irc_cmd_handlers ctcp_handlers;

   165

};

   166

   167

/**

   168

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

   169

 * read/write).

   170

 *

   171

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

   172

 * actually register with the server.

   173

 *

   174

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

   175

 * via *err.

   176

 *

   177

 * @param conn_ptr returned new irc_conn structure

   178

 * @param transport connected transport

   179

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

   180

 * @param cb_arg opqaue context argument for callbacks

   181

 * @param err returned error info

   182

 */

   183

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

   184

        void *cb_arg, error_t *err);

   185

   186

/**

   187

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

   188

 *

   189

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

   190

 */

   191

void irc_conn_destroy (struct irc_conn *conn);

   192

   193

/**

   194

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

   195

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

   196

 *

   197

 * @param conn the connection to use

   198

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

   199

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

   200

 */

   201

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

   202

   203

/**

   204

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

   205

 *

   206

 * This sends the NICK/USER command sequence.

   207

 *

   208

 * @param conn the connection to use

   209

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

   210

 */

   211

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

   212

   213

/**

   214

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

   215

 *

   216

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

   217

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

   218

 */

   219

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

   220

   221

/**

   222

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

   223

 *

   224

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

   225

 *

   226

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

   227

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

   228

 * OK...

   229

 *

   230

 * @param conn the IRC protocol connection

   231

 * @param line the irc_line protocol line to send

   232

 */

   233

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

   234

   235

/**

   236

 * @defgroup irc_conn_COMMAND Simple request functions

   237

 *

   238

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

   239

 *

   240

 * @{

   241

 */

   242

   243

/**

   244

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

   245

 *

   246

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

   247

 * irc_conn::nickname.

   248

 *

   249

 * @param conn the IRC protocol connection

   250

 * @param nickname the new nickname to use

   251

 *

   252

 * Possible errors (from RFC2812):

   253

 *  ERR_NONICKNAMEGIVEN

   254

 *  ERR_NICKNAMEINUSE

   255

 *  ERR_UNAVAILRESOURCE

   256

 *  ERR_ERRONEUSNICKNAME

   257

 *  ERR_NICKCOLLISION

   258

 *  ERR_RESTRICTED

   259

 */

   260

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

   261

   262

/**

   263

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

   264

 *

   265

 * @param conn the IRC protocol connection

   266

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

   267

 * @param realname the full-name to register with

   268

 *

   269

 * Possible errors (from RFC2812):

   270

 *  ERR_NEEDMOREPARAMS

   271

 *  ERR_ALREADYREGISTRED

   272

 */

   273

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

   274

   275

/**

   276

 * Send a PONG message to the given target.

   277

 *

   278

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

   279

 *

   280

 * @param conn the IRC protocol connection

   281

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

   282

 *

   283

 * Possible errors (from RFC2812):

   284

 *  ERR_NOORIGIN

   285

 *  ERR_NOSUCHSERVER

   286

 */

   287

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

   288

   289

/**

   290

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

   291

 *

   292

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

   293

 * RPL_NAMREPLY/RPL_ENDOFNAMES/RPL_TOPIC/etc messages.

   294

 *

   295

 * @param conn the IRC protocol connection

   296

 * @param channel the full channel name to join

   297

 *

   298

 * Possible errors (from RFC2812):

   299

 *  ERR_NEEDMOREPARAMS              ERR_BANNEDFROMCHAN

   300

 *  ERR_INVITEONLYCHAN              ERR_BADCHANNELKEY

   301

 *  ERR_CHANNELISFULL               ERR_BADCHANMASK

   302

 *  ERR_NOSUCHCHANNEL               ERR_TOOMANYCHANNELS

   303

 *  ERR_TOOMANYTARGETS              ERR_UNAVAILRESOURCE

   304

 *

   305

 */

   306

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

   307

   308

/**

   309

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

   310

 *

   311

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

   312

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

   313

 *

   314

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

   315

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

   316

 *

   317

 * @param conn the IRC protocol connection

   318

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

   319

 * @param message the message to send

   320

 *

   321

 * Possible errors (from RFC2812):

   322

 *  ERR_NORECIPIENT                 ERR_NOTEXTTOSEND

   323

 *  ERR_CANNOTSENDTOCHAN            ERR_NOTOPLEVEL

   324

 *  ERR_WILDTOPLEVEL                ERR_TOOMANYTARGETS

   325

 *  ERR_NOSUCHNICK

   326

 *

   327

 */

   328

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

   329

   330

/**

   331

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

   332

 *

   333

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

   334

 *

   335

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

   336

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

   337

 *

   338

 * @param conn the IRC protocol connection

   339

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

   340

 * @param message the message to send

   341

 *

   342

 * Possible errors (from RFC2812):

   343

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

   344

 */

   345

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

   346

   347

/**

   348

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

   349

 *

   350

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

   351

 * called.

   352

 *

   353

 * @param conn the IRC protocol connection

   354

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

   355

 */

   356

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

   357

   358

// @}

   359

   360

#endif /* IRC_CONN_H */