Mercurial > pidgin
comparison libpurple/connection.h @ 21563:1b174854bb80
merge of '30fcf2f336afb635b62a5c3ed3adb3e1fa1dd2d1'
and 'bb60447c0a8c79afca320f4dc689096f4788e7fa'
author | Sadrul Habib Chowdhury <imadil@gmail.com> |
---|---|
date | Sat, 17 Nov 2007 01:55:21 +0000 |
parents | 8ffb65f3c0e9 |
children | a463f05b4566 |
comparison
equal
deleted
inserted
replaced
20755:774f4924e74e | 21563:1b174854bb80 |
---|---|
1 /** | 1 /** |
2 * @file connection.h Connection API | 2 * @file connection.h Connection API |
3 * @ingroup core | 3 * @ingroup core |
4 * @see @ref connection-signals | |
4 */ | 5 */ |
5 | 6 |
6 /* purple | 7 /* purple |
7 * | 8 * |
8 * Purple is the legal property of its developers, whose names are too numerous | 9 * Purple is the legal property of its developers, whose names are too numerous |
20 * GNU General Public License for more details. | 21 * GNU General Public License for more details. |
21 * | 22 * |
22 * You should have received a copy of the GNU General Public License | 23 * You should have received a copy of the GNU General Public License |
23 * along with this program; if not, write to the Free Software | 24 * along with this program; if not, write to the Free Software |
24 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA | 25 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA |
25 * | |
26 * @see @ref connection-signals | |
27 */ | 26 */ |
28 #ifndef _PURPLE_CONNECTION_H_ | 27 #ifndef _PURPLE_CONNECTION_H_ |
29 #define _PURPLE_CONNECTION_H_ | 28 #define _PURPLE_CONNECTION_H_ |
30 | 29 |
31 typedef struct _PurpleConnection PurpleConnection; | 30 typedef struct _PurpleConnection PurpleConnection; |
53 PURPLE_CONNECTED, /**< Connected. */ | 52 PURPLE_CONNECTED, /**< Connected. */ |
54 PURPLE_CONNECTING /**< Connecting. */ | 53 PURPLE_CONNECTING /**< Connecting. */ |
55 | 54 |
56 } PurpleConnectionState; | 55 } PurpleConnectionState; |
57 | 56 |
57 /** Possible errors that can cause a connection to be closed. | |
58 * @since 2.3.0 | |
59 */ | |
60 typedef enum | |
61 { | |
62 /** There was an error sending or receiving on the network socket, or | |
63 * there was some protocol error (such as the server sending malformed | |
64 * data). | |
65 */ | |
66 PURPLE_CONNECTION_ERROR_NETWORK_ERROR = 0, | |
67 /** The username supplied was not valid. */ | |
68 PURPLE_CONNECTION_ERROR_INVALID_USERNAME = 1, | |
69 /** The username, password or some other credential was incorrect. Use | |
70 * #PURPLE_CONNECTION_ERROR_INVALID_USERNAME instead if the username | |
71 * is known to be invalid. | |
72 */ | |
73 PURPLE_CONNECTION_ERROR_AUTHENTICATION_FAILED = 2, | |
74 /** libpurple doesn't speak any of the authentication methods the | |
75 * server offered. | |
76 */ | |
77 PURPLE_CONNECTION_ERROR_AUTHENTICATION_IMPOSSIBLE = 3, | |
78 /** libpurple was built without SSL support, and the connection needs | |
79 * SSL. | |
80 */ | |
81 PURPLE_CONNECTION_ERROR_NO_SSL_SUPPORT = 4, | |
82 /** There was an error negotiating SSL on this connection, or the | |
83 * server does not support encryption but an account option was set to | |
84 * require it. | |
85 */ | |
86 PURPLE_CONNECTION_ERROR_ENCRYPTION_ERROR = 5, | |
87 /** Someone is already connected to the server using the name you are | |
88 * trying to connect with. | |
89 */ | |
90 PURPLE_CONNECTION_ERROR_NAME_IN_USE = 6, | |
91 | |
92 /** The username/server/other preference for the account isn't valid. | |
93 * For instance, on IRC the screen name cannot contain white space. | |
94 * This reason should not be used for incorrect passwords etc: use | |
95 * #PURPLE_CONNECTION_ERROR_AUTHENTICATION_FAILED for that. | |
96 * | |
97 * @todo This reason really shouldn't be necessary. Usernames and | |
98 * other account preferences should be validated when the | |
99 * account is created. | |
100 */ | |
101 PURPLE_CONNECTION_ERROR_INVALID_SETTINGS = 7, | |
102 | |
103 /** The server did not provide a SSL certificate. */ | |
104 PURPLE_CONNECTION_ERROR_CERT_NOT_PROVIDED = 8, | |
105 /** The server's SSL certificate could not be trusted. */ | |
106 PURPLE_CONNECTION_ERROR_CERT_UNTRUSTED = 9, | |
107 /** The server's SSL certificate has expired. */ | |
108 PURPLE_CONNECTION_ERROR_CERT_EXPIRED = 10, | |
109 /** The server's SSL certificate is not yet valid. */ | |
110 PURPLE_CONNECTION_ERROR_CERT_NOT_ACTIVATED = 11, | |
111 /** The server's SSL certificate did not match its hostname. */ | |
112 PURPLE_CONNECTION_ERROR_CERT_HOSTNAME_MISMATCH = 12, | |
113 /** The server's SSL certificate does not have the expected | |
114 * fingerprint. | |
115 */ | |
116 PURPLE_CONNECTION_ERROR_CERT_FINGERPRINT_MISMATCH = 13, | |
117 /** The server's SSL certificate is self-signed. */ | |
118 PURPLE_CONNECTION_ERROR_CERT_SELF_SIGNED = 14, | |
119 /** There was some other error validating the server's SSL certificate. | |
120 */ | |
121 PURPLE_CONNECTION_ERROR_CERT_OTHER_ERROR = 15, | |
122 | |
123 /** Some other error occured which fits into none of the other | |
124 * categories. | |
125 */ | |
126 /* purple_connection_error_reason() in connection.c uses the fact that | |
127 * this is the last member of the enum when sanity-checking; if other | |
128 * reasons are added after it, the check must be updated. | |
129 */ | |
130 PURPLE_CONNECTION_ERROR_OTHER_ERROR = 16 | |
131 } PurpleConnectionError; | |
132 | |
133 /** Holds the type of an error along with its description. */ | |
134 typedef struct | |
135 { | |
136 /** The type of error. */ | |
137 PurpleConnectionError type; | |
138 /** A localised, human-readable description of the error. */ | |
139 char *description; | |
140 } PurpleConnectionErrorInfo; | |
141 | |
58 #include <time.h> | 142 #include <time.h> |
59 | 143 |
60 #include "account.h" | 144 #include "account.h" |
61 #include "plugin.h" | 145 #include "plugin.h" |
62 #include "status.h" | 146 #include "status.h" |
147 #include "sslconn.h" | |
63 | 148 |
64 /** Connection UI operations. Used to notify the user of changes to | 149 /** Connection UI operations. Used to notify the user of changes to |
65 * connections, such as being disconnected, and to respond to the | 150 * connections, such as being disconnected, and to respond to the |
66 * underlying network connection appearing and disappearing. UIs should | 151 * underlying network connection appearing and disappearing. UIs should |
67 * call #purple_connections_set_ui_ops() with an instance of this struct. | 152 * call #purple_connections_set_ui_ops() with an instance of this struct. |
72 { | 157 { |
73 /** When an account is connecting, this operation is called to notify | 158 /** When an account is connecting, this operation is called to notify |
74 * the UI of what is happening, as well as which @a step out of @a | 159 * the UI of what is happening, as well as which @a step out of @a |
75 * step_count has been reached (which might be displayed as a progress | 160 * step_count has been reached (which might be displayed as a progress |
76 * bar). | 161 * bar). |
162 * @see #purple_connection_update_progress | |
77 */ | 163 */ |
78 void (*connect_progress)(PurpleConnection *gc, | 164 void (*connect_progress)(PurpleConnection *gc, |
79 const char *text, | 165 const char *text, |
80 size_t step, | 166 size_t step, |
81 size_t step_count); | 167 size_t step_count); |
168 | |
82 /** Called when a connection is established (just before the | 169 /** Called when a connection is established (just before the |
83 * @ref signed-on signal). | 170 * @ref signed-on signal). |
84 */ | 171 */ |
85 void (*connected)(PurpleConnection *gc); | 172 void (*connected)(PurpleConnection *gc); |
86 /** Called when a connection is ended (between the @ref signing-off | 173 /** Called when a connection is ended (between the @ref signing-off |
87 * and @ref signed-off signals). | 174 * and @ref signed-off signals). |
88 */ | 175 */ |
89 void (*disconnected)(PurpleConnection *gc); | 176 void (*disconnected)(PurpleConnection *gc); |
177 | |
90 /** Used to display connection-specific notices. (Pidgin's Gtk user | 178 /** Used to display connection-specific notices. (Pidgin's Gtk user |
91 * interface implements this as a no-op; #purple_connection_notice(), | 179 * interface implements this as a no-op; #purple_connection_notice(), |
92 * which uses this operation, is not used by any of the protocols | 180 * which uses this operation, is not used by any of the protocols |
93 * shipped with libpurple.) | 181 * shipped with libpurple.) |
94 */ | 182 */ |
95 void (*notice)(PurpleConnection *gc, const char *text); | 183 void (*notice)(PurpleConnection *gc, const char *text); |
184 | |
96 /** Called when an error causes a connection to be disconnected. | 185 /** Called when an error causes a connection to be disconnected. |
97 * Called before #disconnected. | 186 * Called before #disconnected. |
98 * @param text a localized error message. | 187 * @param text a localized error message. |
188 * @see #purple_connection_error | |
189 * @deprecated in favour of | |
190 * #PurpleConnectionUiOps.report_disconnect_reason. | |
99 */ | 191 */ |
100 void (*report_disconnect)(PurpleConnection *gc, const char *text); | 192 void (*report_disconnect)(PurpleConnection *gc, const char *text); |
193 | |
101 /** Called when libpurple discovers that the computer's network | 194 /** Called when libpurple discovers that the computer's network |
102 * connection is active. On Linux, this uses Network Manager if | 195 * connection is active. On Linux, this uses Network Manager if |
103 * available; on Windows, it uses Win32's network change notification | 196 * available; on Windows, it uses Win32's network change notification |
104 * infrastructure. | 197 * infrastructure. |
105 */ | 198 */ |
107 /** Called when libpurple discovers that the computer's network | 200 /** Called when libpurple discovers that the computer's network |
108 * connection has gone away. | 201 * connection has gone away. |
109 */ | 202 */ |
110 void (*network_disconnected)(); | 203 void (*network_disconnected)(); |
111 | 204 |
205 /** Called when an error causes a connection to be disconnected. | |
206 * Called before #disconnected. This op is intended to replace | |
207 * #report_disconnect. If both are implemented, this will be called | |
208 * first; however, there's no real reason to implement both. | |
209 * @param reason why the connection ended, if known, or | |
210 * #PURPLE_CONNECTION_ERROR_OTHER_ERROR, if not. | |
211 * @param text a localized message describing the disconnection | |
212 * in more detail to the user. | |
213 * @see #purple_connection_error_reason | |
214 * @since 2.3.0 | |
215 */ | |
216 void (*report_disconnect_reason)(PurpleConnection *gc, | |
217 PurpleConnectionError reason, | |
218 const char *text); | |
219 | |
112 void (*_purple_reserved1)(void); | 220 void (*_purple_reserved1)(void); |
113 void (*_purple_reserved2)(void); | 221 void (*_purple_reserved2)(void); |
114 void (*_purple_reserved3)(void); | 222 void (*_purple_reserved3)(void); |
115 void (*_purple_reserved4)(void); | |
116 } PurpleConnectionUiOps; | 223 } PurpleConnectionUiOps; |
117 | 224 |
118 struct _PurpleConnection | 225 struct _PurpleConnection |
119 { | 226 { |
120 PurplePlugin *prpl; /**< The protocol plugin. */ | 227 PurplePlugin *prpl; /**< The protocol plugin. */ |
124 | 231 |
125 PurpleAccount *account; /**< The account being connected to. */ | 232 PurpleAccount *account; /**< The account being connected to. */ |
126 char *password; /**< The password used. */ | 233 char *password; /**< The password used. */ |
127 int inpa; /**< The input watcher. */ | 234 int inpa; /**< The input watcher. */ |
128 | 235 |
129 GSList *buddy_chats; /**< A list of active chats. */ | 236 GSList *buddy_chats; /**< A list of active chats |
237 (#PurpleConversation structs of type | |
238 #PURPLE_CONV_TYPE_CHAT). */ | |
130 void *proto_data; /**< Protocol-specific data. */ | 239 void *proto_data; /**< Protocol-specific data. */ |
131 | 240 |
132 char *display_name; /**< How you appear to other people. */ | 241 char *display_name; /**< How you appear to other people. */ |
133 guint keepalive; /**< Keep-alive. */ | 242 guint keepalive; /**< Keep-alive. */ |
134 | 243 |
135 | 244 /** Wants to Die state. This is set when the user chooses to log out, or |
136 gboolean wants_to_die; /**< Wants to Die state. This is set | 245 * when the protocol is disconnected and should not be automatically |
137 when the user chooses to log out, | 246 * reconnected (incorrect password, etc.). prpls should rely on |
138 or when the protocol is | 247 * purple_connection_error_reason() to set this for them rather than |
139 disconnected and should not be | 248 * setting it themselves. |
140 automatically reconnected | 249 * @see purple_connection_error_is_fatal |
141 (incorrect password, etc.) */ | 250 */ |
251 gboolean wants_to_die; | |
252 | |
142 guint disconnect_timeout; /**< Timer used for nasty stack tricks */ | 253 guint disconnect_timeout; /**< Timer used for nasty stack tricks */ |
143 }; | 254 }; |
144 | 255 |
145 #ifdef __cplusplus | 256 #ifdef __cplusplus |
146 extern "C" { | 257 extern "C" { |
149 /**************************************************************************/ | 260 /**************************************************************************/ |
150 /** @name Connection API */ | 261 /** @name Connection API */ |
151 /**************************************************************************/ | 262 /**************************************************************************/ |
152 /*@{*/ | 263 /*@{*/ |
153 | 264 |
265 #ifndef PURPLE_DISABLE_DEPRECATED | |
154 /** | 266 /** |
155 * This function should only be called by purple_account_connect() | 267 * This function should only be called by purple_account_connect() |
156 * in account.c. If you're trying to sign on an account, use that | 268 * in account.c. If you're trying to sign on an account, use that |
157 * function instead. | 269 * function instead. |
158 * | 270 * |
165 * | 277 * |
166 * @param account The account the connection should be connecting to. | 278 * @param account The account the connection should be connecting to. |
167 * @param regist Whether we are registering a new account or just | 279 * @param regist Whether we are registering a new account or just |
168 * trying to do a normal signon. | 280 * trying to do a normal signon. |
169 * @param password The password to use. | 281 * @param password The password to use. |
282 * | |
283 * @deprecated As this is internal, we should make it private in 3.0.0. | |
170 */ | 284 */ |
171 void purple_connection_new(PurpleAccount *account, gboolean regist, | 285 void purple_connection_new(PurpleAccount *account, gboolean regist, |
172 const char *password); | 286 const char *password); |
173 | 287 #endif |
288 | |
289 #ifndef PURPLE_DISABLE_DEPRECATED | |
174 /** | 290 /** |
175 * This function should only be called by purple_account_unregister() | 291 * This function should only be called by purple_account_unregister() |
176 * in account.c. | 292 * in account.c. |
177 * | 293 * |
178 * Tries to unregister the account on the server. If the account is not | 294 * Tries to unregister the account on the server. If the account is not |
179 * connected, also creates a new connection. | 295 * connected, also creates a new connection. |
180 * | 296 * |
181 * @param account The account to unregister | 297 * @param account The account to unregister |
182 * @param password The password to use. | 298 * @param password The password to use. |
299 * @param cb Optional callback to be called when unregistration is complete | |
300 * @param user_data user data to pass to the callback | |
301 * | |
302 * @deprecated As this is internal, we should make it private in 3.0.0. | |
183 */ | 303 */ |
184 void purple_connection_new_unregister(PurpleAccount *account, const char *password, PurpleAccountUnregistrationCb cb, void *user_data); | 304 void purple_connection_new_unregister(PurpleAccount *account, const char *password, PurpleAccountUnregistrationCb cb, void *user_data); |
185 | 305 #endif |
306 | |
307 #ifndef PURPLE_DISABLE_DEPRECATED | |
186 /** | 308 /** |
187 * Disconnects and destroys a PurpleConnection. | 309 * Disconnects and destroys a PurpleConnection. |
188 * | 310 * |
189 * This function should only be called by purple_account_disconnect() | 311 * This function should only be called by purple_account_disconnect() |
190 * in account.c. If you're trying to sign off an account, use that | 312 * in account.c. If you're trying to sign off an account, use that |
191 * function instead. | 313 * function instead. |
192 * | 314 * |
193 * @param gc The purple connection to destroy. | 315 * @param gc The purple connection to destroy. |
316 * | |
317 * @deprecated As this is internal, we should make it private in 3.0.0. | |
194 */ | 318 */ |
195 void purple_connection_destroy(PurpleConnection *gc); | 319 void purple_connection_destroy(PurpleConnection *gc); |
320 #endif | |
196 | 321 |
197 /** | 322 /** |
198 * Sets the connection state. PRPLs should call this and pass in | 323 * Sets the connection state. PRPLs should call this and pass in |
199 * the state "PURPLE_CONNECTED" when the account is completely | 324 * the state #PURPLE_CONNECTED when the account is completely |
200 * signed on. What does it mean to be completely signed on? If | 325 * signed on. What does it mean to be completely signed on? If |
201 * the core can call prpl->set_status, and it successfully changes | 326 * the core can call prpl->set_status, and it successfully changes |
202 * your status, then the account is online. | 327 * your status, then the account is online. |
203 * | 328 * |
204 * @param gc The connection. | 329 * @param gc The connection. |
287 | 412 |
288 /** | 413 /** |
289 * Closes a connection with an error. | 414 * Closes a connection with an error. |
290 * | 415 * |
291 * @param gc The connection. | 416 * @param gc The connection. |
292 * @param reason The error text. | 417 * @param reason The error text, which may not be @c NULL. |
418 * @deprecated in favour of #purple_connection_error_reason. Calling | |
419 * @c purple_connection_error(gc, text) is equivalent to calling | |
420 * @c purple_connection_error_reason(gc, reason, text) where @c reason is | |
421 * #PURPLE_CONNECTION_ERROR_OTHER_ERROR if @c gc->wants_to_die is @c TRUE, and | |
422 * #PURPLE_CONNECTION_ERROR_NETWORK_ERROR if not. (This is to keep | |
423 * auto-reconnection behaviour the same when using old prpls which don't use | |
424 * reasons yet.) | |
293 */ | 425 */ |
294 void purple_connection_error(PurpleConnection *gc, const char *reason); | 426 void purple_connection_error(PurpleConnection *gc, const char *reason); |
427 | |
428 /** | |
429 * Closes a connection with an error and a human-readable description of the | |
430 * error. It also sets @c gc->wants_to_die to the value of | |
431 * #purple_connection_error_is_fatal(@a reason), mainly for | |
432 * backwards-compatibility. | |
433 * | |
434 * @param gc the connection which is closing. | |
435 * @param reason why the connection is closing. | |
436 * @param description a non-@c NULL localized description of the error. | |
437 * @since 2.3.0 | |
438 */ | |
439 void | |
440 purple_connection_error_reason (PurpleConnection *gc, | |
441 PurpleConnectionError reason, | |
442 const char *description); | |
443 | |
444 /** | |
445 * Closes a connection due to an SSL error; this is basically a shortcut to | |
446 * turning the #PurpleSslErrorType into a #PurpleConnectionError and a | |
447 * human-readable string and then calling purple_connection_error_reason(). | |
448 * @since 2.3.0 | |
449 */ | |
450 void | |
451 purple_connection_ssl_error (PurpleConnection *gc, | |
452 PurpleSslErrorType ssl_error); | |
453 | |
454 /** | |
455 * Reports whether a disconnection reason is fatal (in which case the account | |
456 * should probably not be automatically reconnected) or transient (so | |
457 * auto-reconnection is a good idea). | |
458 * For instance, #PURPLE_CONNECTION_ERROR_NETWORK_ERROR is a temporary error, | |
459 * which might be caused by losing the network connection, so <tt> | |
460 * purple_connection_error_is_fatal (PURPLE_CONNECTION_ERROR_NETWORK_ERROR)</tt> | |
461 * is @c FALSE. On the other hand, | |
462 * #PURPLE_CONNECTION_ERROR_AUTHENTICATION_FAILED probably indicates a | |
463 * misconfiguration of the account which needs the user to go fix it up, so | |
464 * <tt> purple_connection_error_is_fatal | |
465 * (PURPLE_CONNECTION_ERROR_AUTHENTICATION_FAILED)</tt> is @c TRUE. | |
466 * | |
467 * (This function is meant to replace checking PurpleConnection.wants_to_die.) | |
468 * | |
469 * @return @c TRUE if the account should not be automatically reconnected, and | |
470 * @c FALSE otherwise. | |
471 * @since 2.3.0 | |
472 */ | |
473 gboolean | |
474 purple_connection_error_is_fatal (PurpleConnectionError reason); | |
295 | 475 |
296 /*@}*/ | 476 /*@}*/ |
297 | 477 |
298 /**************************************************************************/ | 478 /**************************************************************************/ |
299 /** @name Connections API */ | 479 /** @name Connections API */ |