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 updating some core state like

     9

 * current nickname.

    10

 */

    11

    12

struct irc_conn;

    13

    14

#include "error.h"

    15

#include "sock.h"

    16

#include "line_proto.h"

    17

#include "irc_line.h"

    18

#include "irc_cmd.h"

    19

#include <stdbool.h>

    20

    21

/**

    22

 * The configuration info for an IRC connection.

    23

 *

    24

 * XXX: this should probably be reworked, maybe as a separate irc_conn_register function?

    25

 */

    26

struct irc_conn_register_info {

    27

    /* Nickname to use on that server */

    28

    const char *nickname;

    29

    30

    /* Username to supply */

    31

    const char *username;

    32

    33

    /* Realname to supply */

    34

    const char *realname;

    35

};

    36

    37

/**

    38

 * Connection state callbacks

    39

 */

    40

struct irc_conn_callbacks {

    41

    /**

    42

     * irc_conn_register has completed.

    43

     */

    44

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

    45

};

    46

    47

/*

    48

 * Connection state

    49

 */

    50

struct irc_conn {

    51

    /* We are a line-based protocol */

    52

    struct line_proto *lp;

    53

    54

    /** Callbacks */

    55

    struct irc_conn_callbacks callbacks;

    56

    57

    /** Opaque argument for callbacks */

    58

    void *cb_arg;

    59

    60

    /** Registration request sent */

    61

    bool registering;

    62

    63

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

    64

    bool registered;

    65

    66

    /* Command handlers */

    67

    STAILQ_HEAD(irc_conn_handlers, irc_cmd_chain) handlers;

    68

};

    69

    70

/**

    71

 * Create a new irc_conn using the given sock_stream, which should be connected to an IRC server.

    72

 *

    73

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

    74

 * with the server.

    75

 *

    76

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

    77

 * via *err.

    78

 *

    79

 * @param conn the new irc_conn structure is returned via this pointer

    80

 * @param sock the socket connected to the IRC server

    81

 * @param err errors are returned via this pointer

    82

 * @return error code

    83

 */

    84

err_t irc_conn_create (struct irc_conn **conn, struct sock_stream *sock, const struct irc_conn_callbacks *callbacks, 

    85

        void *cb_arg, struct error_info *err);

    86

    87

/**

    95

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

    96

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

    97

 *

    98

 * XXX: rename to not conflict with irc_conn_register()

    99

 *

   100

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

   101

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

   102

 */

   103

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

   104

   105

/**

   106

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

   107

 *

   108

 * This sends the NICK/USER command sequence.

   109

 */

   110

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

   111

   112

/**

   113

 * @group Simple request functions

   114

 *

   115

 * The error handling of these functions is such that the error return code is can be used or ignored as convenient,

   116

 * as connection-fatal errors will be handled internally.

   117

 *

   118

 * @{

   119

 */

   120

   121

/**

   122

 * Send a generic IRC message

   123

 *

   124

 * @param conn the IRC protocol connection

   125

 * @param line the irc_line protocol line to send

   126

 * @return error code

   127

 */

   128

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

   129

   130

/**

   131

 * Send a NICK message

   132

 *

   133

 * @param nickname the new nickname to use

   134

 */

   135

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

   136

   137

/*

   138

 * Send a USER message

   139

 *

   140

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

   141

 * @param realname the full-name to register with

   142

 */

   143

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

   144

   145

/*

   146

 * Send a PONG message to the given target

   147

 *

   148

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

   149

 */

   150

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

   151

   152

/*

   153

 * Send a JOIN message for the given channel

   154

 *

   155

 * XXX: this doesn't implement the full command options

   156

 *

   157

 * @param channel the full channel name to join

   158

 */

   159

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

   160

   161

// @}

   162

   163

#endif /* IRC_CONN_H */