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 info required to register with irc_conn_register

    23

 */

    24

struct irc_conn_register_info {

    25

    /* Nickname to use on that server */

    26

    const char *nickname;

    27

    28

    /* Username to supply */

    29

    const char *username;

    30

    31

    /* Realname to supply */

    32

    const char *realname;

    33

};

    34

    35

/**

    36

 * Connection state callbacks

    37

 */

    38

struct irc_conn_callbacks {

    39

    /**

    40

     * irc_conn_register has completed.

    41

     */

    42

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

    43

    44

    /**

    45

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

    46

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

    47

     *

    48

     * NOTE: Implementing this callback is mandatory

    49

     */

    50

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

    51

    52

    /**

    53

     * The connection was closed cleanly after irc_conn_QUIT.

    54

     *

    55

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

    56

     */

    57

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

    58

};

    59

    60

/*

    61

 * Connection state

    62

 */

    63

struct irc_conn {

    64

    /* We are a line-based protocol */

    65

    struct line_proto *lp;

    66

    67

    /** Callbacks */

    68

    struct irc_conn_callbacks callbacks;

    69

    70

    /** Opaque argument for callbacks */

    71

    void *cb_arg;

    72

    73

    /** @group flags @{ */

    74

    /** Registration request sent */

    75

    bool registering;

    76

    77

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

    78

    bool registered;

    79

    80

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

    81

    bool quitting;

    85

    86

    // @}

    87

    88

    /** Our current real nickname */

    89

    char *nickname;

    90

    91

    /** Command handlers */

    92

    irc_cmd_handlers_t handlers;

    93

};

    94

    95

/**

    96

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

    97

 *

    98

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

    99

 * with the server.

   100

 *

   101

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

   102

 * via *err.

   103

 *

   104

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

   105

 * @param sock the socket connected to the IRC server

   106

 * @param err errors are returned via this pointer

   107

 * @return error code

   108

 */

   109

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

   110

        void *cb_arg, struct error_info *err);

   111

   112

/**

   113

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

   114

 *

   115

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

   116

 */

   117

void irc_conn_destroy (struct irc_conn *conn);

   118

   119

/**

   120

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

   121

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

   122

 *

   123

 * XXX: rename to not conflict with irc_conn_register()

   124

 *

   125

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

   126

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

   127

 */

   128

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

   129

   130

/**

   131

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

   132

 *

   133

 * This sends the NICK/USER command sequence.

   134

 */

   135

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

   136

   137

/**

   138

 * @group Simple request functions

   139

 *

   140

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

   141

 * as connection-fatal errors will be handled internally.

   142

 *

   143

 * @{

   144

 */

   145

   146

/**

   147

 * Send a generic IRC message

   148

 *

   149

 * @param conn the IRC protocol connection

   150

 * @param line the irc_line protocol line to send

   151

 * @return error code

   152

 */

   153

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

   154

   155

/**

   156

 * Send a NICK message

   157

 *

   158

 * @param nickname the new nickname to use

   159

 */

   160

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

   161

   162

/**

   163

 * Send a USER message

   164

 *

   165

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

   166

 * @param realname the full-name to register with

   167

 */

   168

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

   169

   170

/**

   171

 * Send a PONG message to the given target

   172

 *

   173

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

   174

 */

   175

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

   176

   177

/**

   178

 * Send a JOIN message for the given channel

   179

 *

   180

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

   181

 *

   182

 * @param channel the full channel name to join

   183

 */

   184

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

   185

   186

/**

   187

 * Send a QUIT message to the server.

   188

 *

   189

 * This updates our state as disconnecting, and waits for the server to close the connection cleanly.

   190

 */

   191

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

   192

   193

// @}

   194

   195

#endif /* IRC_CONN_H */