1 #ifndef IRC_CONN_H |
1 #ifndef IRC_CONN_H |
2 #define IRC_CONN_H |
2 #define IRC_CONN_H |
3 |
3 |
4 /* |
4 /** |
5 * Per-connection IRC setup and state/protocol handling. |
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. |
6 */ |
10 */ |
7 |
11 |
|
12 struct irc_conn; |
|
13 |
|
14 #include "error.h" |
8 #include "sock.h" |
15 #include "sock.h" |
9 #include "line_proto.h" |
16 #include "line_proto.h" |
10 #include "irc_line.h" |
17 #include "irc_line.h" |
11 #include "error.h" |
18 #include "irc_cmd.h" |
12 #include <stdbool.h> |
19 #include <stdbool.h> |
13 |
20 |
14 /* |
21 /* |
15 * A connection to an IRC server. |
22 * Connection state |
16 */ |
23 */ |
17 struct irc_conn { |
24 struct irc_conn { |
18 /* We are a line-based protocol */ |
25 /* We are a line-based protocol */ |
19 struct line_proto *lp; |
26 struct line_proto *lp; |
20 |
27 |
21 /* Registered (as in, we have a working nickname)? */ |
28 /* Registered (as in, we have a working nickname)? */ |
22 bool registered; |
29 bool registered; |
|
30 |
|
31 /* Command handlers */ |
|
32 STAILQ_HEAD(irc_conn_handlers, irc_cmd_chain) handlers; |
23 }; |
33 }; |
24 |
34 |
25 // XXX: this should probably be slightly reworked |
35 // XXX: this should probably be slightly reworked |
26 struct irc_conn_config { |
36 struct irc_conn_config { |
27 /* Nickname to use on that server */ |
37 /* Nickname to use on that server */ |
32 |
42 |
33 /* Realname to supply */ |
43 /* Realname to supply */ |
34 const char *realname; |
44 const char *realname; |
35 }; |
45 }; |
36 |
46 |
37 /* |
47 /** |
38 * Create a new irc_conn using the given sock_stream, which should be connected to an IRC server. The parameters given |
48 * Create a new irc_conn using the given sock_stream, which should be connected to an IRC server. The parameters given |
39 * in \a config will be used to identify with the IRC server. |
49 * in \a config will be used to identify with the IRC server. |
40 * |
50 * |
41 * On success, the resulting irc_conn is returned via *conn with SUCCESS. Otherwise, -ERR_* and error info is returned |
51 * On success, the resulting irc_conn is returned via *conn with SUCCESS. Otherwise, -ERR_* and error info is returned |
42 * via *err. |
52 * via *err. |
|
53 * |
|
54 * @param conn the new irc_conn structure is returned via this pointer |
|
55 * @param sock the socket connected to the IRC server |
|
56 * @param config the basic information used to register |
|
57 * @param err errors are returned via this pointer |
|
58 * @return error code |
43 */ |
59 */ |
44 err_t irc_conn_create (struct irc_conn **conn, struct sock_stream *sock, const struct irc_conn_config *config, struct error_info *err); |
60 err_t irc_conn_create (struct irc_conn **conn, struct sock_stream *sock, const struct irc_conn_config *config, struct error_info *err); |
|
61 |
|
62 /** |
|
63 * Add a new chain of command handler callbacks to be used to handle irc_lines from the server. The given arg will be |
|
64 * passed to the callbacks as the context argument. The chain will be appended to the end of the current list of chains. |
|
65 * |
|
66 * @param chain the array of irc_cmd_handler structs, terminated with a NULL entry |
|
67 * @param arg the context argument to use for the callbacks |
|
68 */ |
|
69 err_t irc_conn_register_handler_chain (struct irc_conn *conn, struct irc_cmd_handler *handlers, void *arg); |
45 |
70 |
46 /** |
71 /** |
47 * @group Simple request functions |
72 * @group Simple request functions |
48 * |
73 * |
49 * The error handling of these functions is such that the error return code is can be used or ignored as convenient, |
74 * The error handling of these functions is such that the error return code is can be used or ignored as convenient, |
50 * as connection-fatal errors will be handled internally. |
75 * as connection-fatal errors will be handled internally. |
51 * |
76 * |
52 * @{ |
77 * @{ |
53 */ |
78 */ |
54 |
79 |
55 /* |
80 /** |
56 * Send a generic IRC message |
81 * Send a generic IRC message |
|
82 * |
|
83 * @param conn the IRC protocol connection |
|
84 * @param line the irc_line protocol line to send |
|
85 * @return error code |
57 */ |
86 */ |
58 err_t irc_conn_send (struct irc_conn *conn, const struct irc_line *line); |
87 err_t irc_conn_send (struct irc_conn *conn, const struct irc_line *line); |
59 |
88 |
60 /* |
89 /** |
61 * Send a NICK message |
90 * Send a NICK message |
|
91 * |
|
92 * @param nickname the new nickname to use |
62 */ |
93 */ |
63 err_t irc_conn_NICK (struct irc_conn *conn, const char *nickname); |
94 err_t irc_conn_NICK (struct irc_conn *conn, const char *nickname); |
64 |
95 |
65 /* |
96 /* |
66 * Send a USER message |
97 * Send a USER message |
|
98 * |
|
99 * @param username the username to register with, may be replaced with ident reply |
|
100 * @param realname the full-name to register with |
67 */ |
101 */ |
68 err_t irc_conn_USER (struct irc_conn *conn, const char *username, const char *realname); |
102 err_t irc_conn_USER (struct irc_conn *conn, const char *username, const char *realname); |
69 |
103 |
70 /* |
104 /* |
71 * Send a PONG message to the given target |
105 * Send a PONG message to the given target |
|
106 * |
|
107 * @param target the PING source, aka. the target to send the PONG reply to |
72 */ |
108 */ |
73 err_t irc_conn_PONG (struct irc_conn *conn, const char *target); |
109 err_t irc_conn_PONG (struct irc_conn *conn, const char *target); |
|
110 |
|
111 /* |
|
112 * Send a JOIN message for the given channel |
|
113 * |
|
114 * XXX: this doesn't implement the full command options |
|
115 * |
|
116 * @param channel the full channel name to join |
|
117 */ |
|
118 err_t irc_conn_JOIN (struct irc_conn *conn, const char *channel); |
74 |
119 |
75 // @} |
120 // @} |
76 |
121 |
77 #endif /* IRC_CONN_H */ |
122 #endif /* IRC_CONN_H */ |