Mercurial > pidgin
comparison libpurple/connection.h @ 15373:5fe8042783c1
Rename gtk/ and libgaim/ to pidgin/ and libpurple/
author | Sean Egan <seanegan@gmail.com> |
---|---|
date | Sat, 20 Jan 2007 02:32:10 +0000 |
parents | |
children | 32c366eeeb99 |
comparison
equal
deleted
inserted
replaced
15372:f79e0f4df793 | 15373:5fe8042783c1 |
---|---|
1 /** | |
2 * @file connection.h Connection API | |
3 * @ingroup core | |
4 * | |
5 * gaim | |
6 * | |
7 * Gaim is the legal property of its developers, whose names are too numerous | |
8 * to list here. Please refer to the COPYRIGHT file distributed with this | |
9 * source distribution. | |
10 * | |
11 * This program is free software; you can redistribute it and/or modify | |
12 * it under the terms of the GNU General Public License as published by | |
13 * the Free Software Foundation; either version 2 of the License, or | |
14 * (at your option) any later version. | |
15 * | |
16 * This program is distributed in the hope that it will be useful, | |
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
19 * GNU General Public License for more details. | |
20 * | |
21 * You should have received a copy of the GNU General Public License | |
22 * along with this program; if not, write to the Free Software | |
23 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
24 * | |
25 * @see @ref connection-signals | |
26 */ | |
27 #ifndef _GAIM_CONNECTION_H_ | |
28 #define _GAIM_CONNECTION_H_ | |
29 | |
30 typedef struct _GaimConnection GaimConnection; | |
31 | |
32 /** | |
33 * Flags to change behavior of the client for a given connection. | |
34 */ | |
35 typedef enum | |
36 { | |
37 GAIM_CONNECTION_HTML = 0x0001, /**< Connection sends/receives in 'HTML'. */ | |
38 GAIM_CONNECTION_NO_BGCOLOR = 0x0002, /**< Connection does not send/receive | |
39 background colors. */ | |
40 GAIM_CONNECTION_AUTO_RESP = 0x0004, /**< Send auto responses when away. */ | |
41 GAIM_CONNECTION_FORMATTING_WBFO = 0x0008, /**< The text buffer must be formatted as a whole */ | |
42 GAIM_CONNECTION_NO_NEWLINES = 0x0010, /**< No new lines are allowed in outgoing messages */ | |
43 GAIM_CONNECTION_NO_FONTSIZE = 0x0020, /**< Connection does not send/receive font sizes */ | |
44 GAIM_CONNECTION_NO_URLDESC = 0x0040, /**< Connection does not support descriptions with links */ | |
45 GAIM_CONNECTION_NO_IMAGES = 0x0080, /**< Connection does not support sending of images */ | |
46 | |
47 } GaimConnectionFlags; | |
48 | |
49 typedef enum | |
50 { | |
51 GAIM_DISCONNECTED = 0, /**< Disconnected. */ | |
52 GAIM_CONNECTED, /**< Connected. */ | |
53 GAIM_CONNECTING /**< Connecting. */ | |
54 | |
55 } GaimConnectionState; | |
56 | |
57 #include <time.h> | |
58 | |
59 #include "account.h" | |
60 #include "plugin.h" | |
61 #include "status.h" | |
62 | |
63 typedef struct | |
64 { | |
65 void (*connect_progress)(GaimConnection *gc, const char *text, | |
66 size_t step, size_t step_count); | |
67 void (*connected)(GaimConnection *gc); | |
68 void (*disconnected)(GaimConnection *gc); | |
69 void (*notice)(GaimConnection *gc, const char *text); | |
70 void (*report_disconnect)(GaimConnection *gc, const char *text); | |
71 void (*network_connected)(); | |
72 void (*network_disconnected)(); | |
73 | |
74 } GaimConnectionUiOps; | |
75 | |
76 struct _GaimConnection | |
77 { | |
78 GaimPlugin *prpl; /**< The protocol plugin. */ | |
79 GaimConnectionFlags flags; /**< Connection flags. */ | |
80 | |
81 GaimConnectionState state; /**< The connection state. */ | |
82 | |
83 GaimAccount *account; /**< The account being connected to. */ | |
84 char *password; /**< The password used. */ | |
85 int inpa; /**< The input watcher. */ | |
86 | |
87 GSList *buddy_chats; /**< A list of active chats. */ | |
88 void *proto_data; /**< Protocol-specific data. */ | |
89 | |
90 char *display_name; /**< How you appear to other people. */ | |
91 guint keepalive; /**< Keep-alive. */ | |
92 | |
93 | |
94 gboolean wants_to_die; /**< Wants to Die state. This is set | |
95 when the user chooses to log out, | |
96 or when the protocol is | |
97 disconnected and should not be | |
98 automatically reconnected | |
99 (incorrect password, etc.) */ | |
100 guint disconnect_timeout; /**< Timer used for nasty stack tricks */ | |
101 }; | |
102 | |
103 #ifdef __cplusplus | |
104 extern "C" { | |
105 #endif | |
106 | |
107 /**************************************************************************/ | |
108 /** @name Connection API */ | |
109 /**************************************************************************/ | |
110 /*@{*/ | |
111 | |
112 /** | |
113 * This function should only be called by gaim_account_connect() | |
114 * in account.c. If you're trying to sign on an account, use that | |
115 * function instead. | |
116 * | |
117 * Creates a connection to the specified account and either connects | |
118 * or attempts to register a new account. If you are logging in, | |
119 * the connection uses the current active status for this account. | |
120 * So if you want to sign on as "away," for example, you need to | |
121 * have called gaim_account_set_status(account, "away"). | |
122 * (And this will call gaim_account_connect() automatically). | |
123 * | |
124 * @param account The account the connection should be connecting to. | |
125 * @param regist Whether we are registering a new account or just | |
126 * trying to do a normal signon. | |
127 * @param password The password to use. | |
128 */ | |
129 void gaim_connection_new(GaimAccount *account, gboolean regist, | |
130 const char *password); | |
131 | |
132 /** | |
133 * Disconnects and destroys a GaimConnection. | |
134 * | |
135 * This function should only be called by gaim_account_disconnect() | |
136 * in account.c. If you're trying to sign off an account, use that | |
137 * function instead. | |
138 * | |
139 * @param gc The gaim connection to destroy. | |
140 */ | |
141 void gaim_connection_destroy(GaimConnection *gc); | |
142 | |
143 /** | |
144 * Sets the connection state. PRPLs should call this and pass in | |
145 * the state "GAIM_CONNECTED" when the account is completely | |
146 * signed on. What does it mean to be completely signed on? If | |
147 * the core can call prpl->set_status, and it successfully changes | |
148 * your status, then the account is online. | |
149 * | |
150 * @param gc The connection. | |
151 * @param state The connection state. | |
152 */ | |
153 void gaim_connection_set_state(GaimConnection *gc, GaimConnectionState state); | |
154 | |
155 /** | |
156 * Sets the connection's account. | |
157 * | |
158 * @param gc The connection. | |
159 * @param account The account. | |
160 */ | |
161 void gaim_connection_set_account(GaimConnection *gc, GaimAccount *account); | |
162 | |
163 /** | |
164 * Sets the connection's displayed name. | |
165 * | |
166 * @param gc The connection. | |
167 * @param name The displayed name. | |
168 */ | |
169 void gaim_connection_set_display_name(GaimConnection *gc, const char *name); | |
170 | |
171 /** | |
172 * Returns the connection state. | |
173 * | |
174 * @param gc The connection. | |
175 * | |
176 * @return The connection state. | |
177 */ | |
178 GaimConnectionState gaim_connection_get_state(const GaimConnection *gc); | |
179 | |
180 /** | |
181 * Returns TRUE if the account is connected, otherwise returns FALSE. | |
182 * | |
183 * @return TRUE if the account is connected, otherwise returns FALSE. | |
184 */ | |
185 #define GAIM_CONNECTION_IS_CONNECTED(gc) \ | |
186 (gc->state == GAIM_CONNECTED) | |
187 | |
188 /** | |
189 * Returns the connection's account. | |
190 * | |
191 * @param gc The connection. | |
192 * | |
193 * @return The connection's account. | |
194 */ | |
195 GaimAccount *gaim_connection_get_account(const GaimConnection *gc); | |
196 | |
197 /** | |
198 * Returns the connection's password. | |
199 * | |
200 * @param gc The connection. | |
201 * | |
202 * @return The connection's password. | |
203 */ | |
204 const char *gaim_connection_get_password(const GaimConnection *gc); | |
205 | |
206 /** | |
207 * Returns the connection's displayed name. | |
208 * | |
209 * @param gc The connection. | |
210 * | |
211 * @return The connection's displayed name. | |
212 */ | |
213 const char *gaim_connection_get_display_name(const GaimConnection *gc); | |
214 | |
215 /** | |
216 * Updates the connection progress. | |
217 * | |
218 * @param gc The connection. | |
219 * @param text Information on the current step. | |
220 * @param step The current step. | |
221 * @param count The total number of steps. | |
222 */ | |
223 void gaim_connection_update_progress(GaimConnection *gc, const char *text, | |
224 size_t step, size_t count); | |
225 | |
226 /** | |
227 * Displays a connection-specific notice. | |
228 * | |
229 * @param gc The connection. | |
230 * @param text The notice text. | |
231 */ | |
232 void gaim_connection_notice(GaimConnection *gc, const char *text); | |
233 | |
234 /** | |
235 * Closes a connection with an error. | |
236 * | |
237 * @param gc The connection. | |
238 * @param reason The error text. | |
239 */ | |
240 void gaim_connection_error(GaimConnection *gc, const char *reason); | |
241 | |
242 /*@}*/ | |
243 | |
244 /**************************************************************************/ | |
245 /** @name Connections API */ | |
246 /**************************************************************************/ | |
247 /*@{*/ | |
248 | |
249 /** | |
250 * Disconnects from all connections. | |
251 */ | |
252 void gaim_connections_disconnect_all(void); | |
253 | |
254 /** | |
255 * Returns a list of all active connections. This does not | |
256 * include connections that are in the process of connecting. | |
257 * | |
258 * @return A list of all active connections. | |
259 */ | |
260 GList *gaim_connections_get_all(void); | |
261 | |
262 /** | |
263 * Returns a list of all connections in the process of connecting. | |
264 * | |
265 * @return A list of connecting connections. | |
266 */ | |
267 GList *gaim_connections_get_connecting(void); | |
268 | |
269 /** | |
270 * Checks if gc is still a valid pointer to a gc. | |
271 * | |
272 * @return @c TRUE if gc is valid. | |
273 */ | |
274 /* | |
275 * TODO: Eventually this bad boy will be removed, because it is | |
276 * a gross fix for a crashy problem. | |
277 */ | |
278 #define GAIM_CONNECTION_IS_VALID(gc) (g_list_find(gaim_connections_get_all(), (gc))) | |
279 | |
280 /*@}*/ | |
281 | |
282 /**************************************************************************/ | |
283 /** @name UI Registration Functions */ | |
284 /**************************************************************************/ | |
285 /*@{*/ | |
286 | |
287 /** | |
288 * Sets the UI operations structure to be used for connections. | |
289 * | |
290 * @param ops The UI operations structure. | |
291 */ | |
292 void gaim_connections_set_ui_ops(GaimConnectionUiOps *ops); | |
293 | |
294 /** | |
295 * Returns the UI operations structure used for connections. | |
296 * | |
297 * @return The UI operations structure in use. | |
298 */ | |
299 GaimConnectionUiOps *gaim_connections_get_ui_ops(void); | |
300 | |
301 /*@}*/ | |
302 | |
303 /**************************************************************************/ | |
304 /** @name Connections Subsystem */ | |
305 /**************************************************************************/ | |
306 /*@{*/ | |
307 | |
308 /** | |
309 * Initializes the connections subsystem. | |
310 */ | |
311 void gaim_connections_init(void); | |
312 | |
313 /** | |
314 * Uninitializes the connections subsystem. | |
315 */ | |
316 void gaim_connections_uninit(void); | |
317 | |
318 /** | |
319 * Returns the handle to the connections subsystem. | |
320 * | |
321 * @return The connections subsystem handle. | |
322 */ | |
323 void *gaim_connections_get_handle(void); | |
324 | |
325 /*@}*/ | |
326 | |
327 | |
328 #ifdef __cplusplus | |
329 } | |
330 #endif | |
331 | |
332 #endif /* _GAIM_CONNECTION_H_ */ |