1 /** 2 * @file connection.h Connection API 3 * @ingroup core 4 * @see @ref connection-signals 5 */ 6 7 /* purple 8 * 9 * Purple is the legal property of its developers, whose names are too numerous 10 * to list here. Please refer to the COPYRIGHT file distributed with this 11 * source distribution. 12 * 13 * This program is free software; you can redistribute it and/or modify 14 * it under the terms of the GNU General Public License as published by 15 * the Free Software Foundation; either version 2 of the License, or 16 * (at your option) any later version. 17 * 18 * This program is distributed in the hope that it will be useful, 19 * but WITHOUT ANY WARRANTY; without even the implied warranty of 20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 21 * GNU General Public License for more details. 22 * 23 * You should have received a copy of the GNU General Public License 24 * along with this program; if not, write to the Free Software 25 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA 26 */ 27 #ifndef _PURPLE_CONNECTION_H_ 28 #define _PURPLE_CONNECTION_H_ 29 30 /** @copydoc _PurpleConnection */ 31 typedef struct _PurpleConnection PurpleConnection; 32 33 /** 34 * Flags to change behavior of the client for a given connection. 35 */ 36 typedef enum 37 { 38 PURPLE_CONNECTION_HTML = 0x0001, /**< Connection sends/receives in 'HTML'. */ 39 PURPLE_CONNECTION_NO_BGCOLOR = 0x0002, /**< Connection does not send/receive 40 background colors. */ 41 PURPLE_CONNECTION_AUTO_RESP = 0x0004, /**< Send auto responses when away. */ 42 PURPLE_CONNECTION_FORMATTING_WBFO = 0x0008, /**< The text buffer must be formatted as a whole */ 43 PURPLE_CONNECTION_NO_NEWLINES = 0x0010, /**< No new lines are allowed in outgoing messages */ 44 PURPLE_CONNECTION_NO_FONTSIZE = 0x0020, /**< Connection does not send/receive font sizes */ 45 PURPLE_CONNECTION_NO_URLDESC = 0x0040, /**< Connection does not support descriptions with links */ 46 PURPLE_CONNECTION_NO_IMAGES = 0x0080, /**< Connection does not support sending of images */ 47 PURPLE_CONNECTION_ALLOW_CUSTOM_SMILEY = 0x0100, /**< Connection supports sending and receiving custom smileys */ 48 PURPLE_CONNECTION_SUPPORT_MOODS = 0x0200, /**< Connection supports setting moods */ 49 PURPLE_CONNECTION_SUPPORT_MOOD_MESSAGES = 0x0400 /**< Connection supports setting a message on moods */ 50 } PurpleConnectionFlags; 51 52 typedef enum 53 { 54 PURPLE_DISCONNECTED = 0, /**< Disconnected. */ 55 PURPLE_CONNECTED, /**< Connected. */ 56 PURPLE_CONNECTING /**< Connecting. */ 57 58 } PurpleConnectionState; 59 60 /** 61 * Possible errors that can cause a connection to be closed. 62 * 63 * @since 2.3.0 64 */ 65 typedef enum 66 { 67 /** There was an error sending or receiving on the network socket, or 68 * there was some protocol error (such as the server sending malformed 69 * data). 70 */ 71 PURPLE_CONNECTION_ERROR_NETWORK_ERROR = 0, 72 /** The username supplied was not valid. */ 73 PURPLE_CONNECTION_ERROR_INVALID_USERNAME = 1, 74 /** The username, password or some other credential was incorrect. Use 75 * #PURPLE_CONNECTION_ERROR_INVALID_USERNAME instead if the username 76 * is known to be invalid. 77 */ 78 PURPLE_CONNECTION_ERROR_AUTHENTICATION_FAILED = 2, 79 /** libpurple doesn't speak any of the authentication methods the 80 * server offered. 81 */ 82 PURPLE_CONNECTION_ERROR_AUTHENTICATION_IMPOSSIBLE = 3, 83 /** libpurple was built without SSL support, and the connection needs 84 * SSL. 85 */ 86 PURPLE_CONNECTION_ERROR_NO_SSL_SUPPORT = 4, 87 /** There was an error negotiating SSL on this connection, or the 88 * server does not support encryption but an account option was set to 89 * require it. 90 */ 91 PURPLE_CONNECTION_ERROR_ENCRYPTION_ERROR = 5, 92 /** Someone is already connected to the server using the name you are 93 * trying to connect with. 94 */ 95 PURPLE_CONNECTION_ERROR_NAME_IN_USE = 6, 96 97 /** The username/server/other preference for the account isn't valid. 98 * For instance, on IRC the username cannot contain white space. 99 * This reason should not be used for incorrect passwords etc: use 100 * #PURPLE_CONNECTION_ERROR_AUTHENTICATION_FAILED for that. 101 * 102 * @todo This reason really shouldn't be necessary. Usernames and 103 * other account preferences should be validated when the 104 * account is created. 105 */ 106 PURPLE_CONNECTION_ERROR_INVALID_SETTINGS = 7, 107 108 /** The server did not provide a SSL certificate. */ 109 PURPLE_CONNECTION_ERROR_CERT_NOT_PROVIDED = 8, 110 /** The server's SSL certificate could not be trusted. */ 111 PURPLE_CONNECTION_ERROR_CERT_UNTRUSTED = 9, 112 /** The server's SSL certificate has expired. */ 113 PURPLE_CONNECTION_ERROR_CERT_EXPIRED = 10, 114 /** The server's SSL certificate is not yet valid. */ 115 PURPLE_CONNECTION_ERROR_CERT_NOT_ACTIVATED = 11, 116 /** The server's SSL certificate did not match its hostname. */ 117 PURPLE_CONNECTION_ERROR_CERT_HOSTNAME_MISMATCH = 12, 118 /** The server's SSL certificate does not have the expected 119 * fingerprint. 120 */ 121 PURPLE_CONNECTION_ERROR_CERT_FINGERPRINT_MISMATCH = 13, 122 /** The server's SSL certificate is self-signed. */ 123 PURPLE_CONNECTION_ERROR_CERT_SELF_SIGNED = 14, 124 /** There was some other error validating the server's SSL certificate. 125 */ 126 PURPLE_CONNECTION_ERROR_CERT_OTHER_ERROR = 15, 127 128 /** Some other error occurred which fits into none of the other 129 * categories. 130 */ 131 /* purple_connection_error_reason() in connection.c uses the fact that 132 * this is the last member of the enum when sanity-checking; if other 133 * reasons are added after it, the check must be updated. 134 */ 135 PURPLE_CONNECTION_ERROR_OTHER_ERROR = 16 136 } PurpleConnectionError; 137 138 /** Holds the type of an error along with its description. */ 139 typedef struct 140 { 141 /** The type of error. */ 142 PurpleConnectionError type; 143 /** A localised, human-readable description of the error. */ 144 char *description; 145 } PurpleConnectionErrorInfo; 146 147 #include <time.h> 148 149 #include "account.h" 150 #include "plugin.h" 151 #include "status.h" 152 #include "sslconn.h" 153 154 /** 155 * Connection UI operations. Used to notify the user of changes to 156 * connections, such as being disconnected, and to respond to the 157 * underlying network connection appearing and disappearing. UIs should 158 * call #purple_connections_set_ui_ops() with an instance of this struct. 159 * 160 * @see @ref ui-ops 161 */ 162 typedef struct 163 { 164 /** 165 * When an account is connecting, this operation is called to notify 166 * the UI of what is happening, as well as which @a step out of @a 167 * step_count has been reached (which might be displayed as a progress 168 * bar). 169 * @see #purple_connection_update_progress 170 */ 171 void (*connect_progress)(PurpleConnection *gc, 172 const char *text, 173 size_t step, 174 size_t step_count); 175 176 /** 177 * Called when a connection is established (just before the 178 * @ref signed-on signal). 179 */ 180 void (*connected)(PurpleConnection *gc); 181 182 /** 183 * Called when a connection is ended (between the @ref signing-off 184 * and @ref signed-off signals). 185 */ 186 void (*disconnected)(PurpleConnection *gc); 187 188 /** 189 * Used to display connection-specific notices. (Pidgin's Gtk user 190 * interface implements this as a no-op; #purple_connection_notice(), 191 * which uses this operation, is not used by any of the protocols 192 * shipped with libpurple.) 193 */ 194 void (*notice)(PurpleConnection *gc, const char *text); 195 196 /** 197 * Called when an error causes a connection to be disconnected. 198 * Called before #disconnected. 199 * @param text a localized error message. 200 * @see #purple_connection_error 201 * @deprecated in favour of 202 * #PurpleConnectionUiOps.report_disconnect_reason. 203 */ 204 void (*report_disconnect)(PurpleConnection *gc, const char *text); 205 206 /** 207 * Called when libpurple discovers that the computer's network 208 * connection is active. On Linux, this uses Network Manager if 209 * available; on Windows, it uses Win32's network change notification 210 * infrastructure. 211 */ 212 void (*network_connected)(void); 213 214 /** 215 * Called when libpurple discovers that the computer's network 216 * connection has gone away. 217 */ 218 void (*network_disconnected)(void); 219 220 /** 221 * Called when an error causes a connection to be disconnected. 222 * Called before #disconnected. This op is intended to replace 223 * #report_disconnect. If both are implemented, this will be called 224 * first; however, there's no real reason to implement both. 225 * 226 * @param reason why the connection ended, if known, or 227 * #PURPLE_CONNECTION_ERROR_OTHER_ERROR, if not. 228 * @param text a localized message describing the disconnection 229 * in more detail to the user. 230 * @see #purple_connection_error_reason 231 * 232 * @since 2.3.0 233 */ 234 void (*report_disconnect_reason)(PurpleConnection *gc, 235 PurpleConnectionError reason, 236 const char *text); 237 238 void (*_purple_reserved1)(void); 239 void (*_purple_reserved2)(void); 240 void (*_purple_reserved3)(void); 241 } PurpleConnectionUiOps; 242 243 244 /* Represents an active connection on an account. */ 245 struct _PurpleConnection 246 { 247 PurplePlugin *prpl; /**< The protocol plugin. */ 248 PurpleConnectionFlags flags; /**< Connection flags. */ 249 250 PurpleConnectionState state; /**< The connection state. */ 251 252 PurpleAccount *account; /**< The account being connected to. */ 253 char *password; /**< The password used. */ 254 int inpa; /**< The input watcher. */ 255 256 GSList *buddy_chats; /**< A list of active chats 257 (#PurpleConversation structs of type 258 #PURPLE_CONV_TYPE_CHAT). */ 259 void *proto_data; /**< Protocol-specific data. */ 260 261 char *display_name; /**< How you appear to other people. */ 262 guint keepalive; /**< Keep-alive. */ 263 264 /** Wants to Die state. This is set when the user chooses to log out, or 265 * when the protocol is disconnected and should not be automatically 266 * reconnected (incorrect password, etc.). prpls should rely on 267 * purple_connection_error_reason() to set this for them rather than 268 * setting it themselves. 269 * @see purple_connection_error_is_fatal 270 */ 271 gboolean wants_to_die; 272 273 guint disconnect_timeout; /**< Timer used for nasty stack tricks */ 274 time_t last_received; /**< When we last received a packet. Set by the 275 prpl to avoid sending unneeded keepalives */ 276 }; 277 278 #ifdef __cplusplus 279 extern "C" { 280 #endif 281 282 /**************************************************************************/ 283 /** @name Connection API */ 284 /**************************************************************************/ 285 /*@{*/ 286 287 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_CONNECTION_C_) 288 /** 289 * This function should only be called by purple_account_connect() 290 * in account.c. If you're trying to sign on an account, use that 291 * function instead. 292 * 293 * Creates a connection to the specified account and either connects 294 * or attempts to register a new account. If you are logging in, 295 * the connection uses the current active status for this account. 296 * So if you want to sign on as "away," for example, you need to 297 * have called purple_account_set_status(account, "away"). 298 * (And this will call purple_account_connect() automatically). 299 * 300 * @param account The account the connection should be connecting to. 301 * @param regist Whether we are registering a new account or just 302 * trying to do a normal signon. 303 * @param password The password to use. 304 * 305 * @deprecated As this is internal, we should make it private in 3.0.0. 306 */ 307 void purple_connection_new(PurpleAccount *account, gboolean regist, 308 const char *password); 309 #endif 310 311 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_CONNECTION_C_) 312 /** 313 * This function should only be called by purple_account_unregister() 314 * in account.c. 315 * 316 * Tries to unregister the account on the server. If the account is not 317 * connected, also creates a new connection. 318 * 319 * @param account The account to unregister 320 * @param password The password to use. 321 * @param cb Optional callback to be called when unregistration is complete 322 * @param user_data user data to pass to the callback 323 * 324 * @deprecated As this is internal, we should make it private in 3.0.0. 325 */ 326 void purple_connection_new_unregister(PurpleAccount *account, const char *password, PurpleAccountUnregistrationCb cb, void *user_data); 327 #endif 328 329 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_CONNECTION_C_) 330 /** 331 * Disconnects and destroys a PurpleConnection. 332 * 333 * This function should only be called by purple_account_disconnect() 334 * in account.c. If you're trying to sign off an account, use that 335 * function instead. 336 * 337 * @param gc The purple connection to destroy. 338 * 339 * @deprecated As this is internal, we should make it private in 3.0.0. 340 */ 341 void purple_connection_destroy(PurpleConnection *gc); 342 #endif 343 344 /** 345 * Sets the connection state. PRPLs should call this and pass in 346 * the state #PURPLE_CONNECTED when the account is completely 347 * signed on. What does it mean to be completely signed on? If 348 * the core can call prpl->set_status, and it successfully changes 349 * your status, then the account is online. 350 * 351 * @param gc The connection. 352 * @param state The connection state. 353 */ 354 void purple_connection_set_state(PurpleConnection *gc, PurpleConnectionState state); 355 356 /** 357 * Sets the connection's account. 358 * 359 * @param gc The connection. 360 * @param account The account. 361 */ 362 void purple_connection_set_account(PurpleConnection *gc, PurpleAccount *account); 363 364 /** 365 * Sets the connection's displayed name. 366 * 367 * @param gc The connection. 368 * @param name The displayed name. 369 */ 370 void purple_connection_set_display_name(PurpleConnection *gc, const char *name); 371 372 /** 373 * Sets the protocol data for a connection. 374 * 375 * @param connection The PurpleConnection. 376 * @param proto_data The protocol data to set for the connection. 377 * 378 * @since 2.6.0 379 */ 380 void purple_connection_set_protocol_data(PurpleConnection *connection, void *proto_data); 381 382 /** 383 * Returns the connection state. 384 * 385 * @param gc The connection. 386 * 387 * @return The connection state. 388 */ 389 PurpleConnectionState purple_connection_get_state(const PurpleConnection *gc); 390 391 /** 392 * Returns TRUE if the account is connected, otherwise returns FALSE. 393 * 394 * @return TRUE if the account is connected, otherwise returns FALSE. 395 */ 396 #define PURPLE_CONNECTION_IS_CONNECTED(gc) \ 397 (purple_connection_get_state(gc) == PURPLE_CONNECTED) 398 399 /** 400 * Returns the connection's account. 401 * 402 * @param gc The connection. 403 * 404 * @return The connection's account. 405 */ 406 PurpleAccount *purple_connection_get_account(const PurpleConnection *gc); 407 408 /** 409 * Returns the protocol plugin managing a connection. 410 * 411 * @param gc The connection. 412 * 413 * @return The protocol plugin. 414 * 415 * @since 2.4.0 416 */ 417 PurplePlugin * purple_connection_get_prpl(const PurpleConnection *gc); 418 419 /** 420 * Returns the connection's password. 421 * 422 * @param gc The connection. 423 * 424 * @return The connection's password. 425 */ 426 const char *purple_connection_get_password(const PurpleConnection *gc); 427 428 /** 429 * Returns the connection's displayed name. 430 * 431 * @param gc The connection. 432 * 433 * @return The connection's displayed name. 434 */ 435 const char *purple_connection_get_display_name(const PurpleConnection *gc); 436 437 /** 438 * Gets the protocol data from a connection. 439 * 440 * @param connection The PurpleConnection. 441 * 442 * @return The protocol data for the connection. 443 * 444 * @since 2.6.0 445 */ 446 void *purple_connection_get_protocol_data(const PurpleConnection *connection); 447 448 /** 449 * Updates the connection progress. 450 * 451 * @param gc The connection. 452 * @param text Information on the current step. 453 * @param step The current step. 454 * @param count The total number of steps. 455 */ 456 void purple_connection_update_progress(PurpleConnection *gc, const char *text, 457 size_t step, size_t count); 458 459 /** 460 * Displays a connection-specific notice. 461 * 462 * @param gc The connection. 463 * @param text The notice text. 464 */ 465 void purple_connection_notice(PurpleConnection *gc, const char *text); 466 467 /** 468 * Closes a connection with an error. 469 * 470 * @param gc The connection. 471 * @param reason The error text, which may not be @c NULL. 472 * @deprecated in favour of #purple_connection_error_reason. Calling 473 * @c purple_connection_error(gc, text) is equivalent to calling 474 * @c purple_connection_error_reason(gc, reason, text) where @c reason is 475 * #PURPLE_CONNECTION_ERROR_OTHER_ERROR if @c gc->wants_to_die is @c TRUE, and 476 * #PURPLE_CONNECTION_ERROR_NETWORK_ERROR if not. (This is to keep 477 * auto-reconnection behaviour the same when using old prpls which don't use 478 * reasons yet.) 479 */ 480 void purple_connection_error(PurpleConnection *gc, const char *reason); 481 482 /** 483 * Closes a connection with an error and a human-readable description of the 484 * error. It also sets @c gc->wants_to_die to the value of 485 * #purple_connection_error_is_fatal(@a reason), mainly for 486 * backwards-compatibility. 487 * 488 * @param gc the connection which is closing. 489 * @param reason why the connection is closing. 490 * @param description a non-@c NULL localized description of the error. 491 * 492 * @since 2.3.0 493 */ 494 void 495 purple_connection_error_reason (PurpleConnection *gc, 496 PurpleConnectionError reason, 497 const char *description); 498 499 /** 500 * Closes a connection due to an SSL error; this is basically a shortcut to 501 * turning the #PurpleSslErrorType into a #PurpleConnectionError and a 502 * human-readable string and then calling purple_connection_error_reason(). 503 * 504 * @since 2.3.0 505 */ 506 void 507 purple_connection_ssl_error (PurpleConnection *gc, 508 PurpleSslErrorType ssl_error); 509 510 /** 511 * Reports whether a disconnection reason is fatal (in which case the account 512 * should probably not be automatically reconnected) or transient (so 513 * auto-reconnection is a good idea). 514 * For instance, #PURPLE_CONNECTION_ERROR_NETWORK_ERROR is a temporary error, 515 * which might be caused by losing the network connection, so <tt> 516 * purple_connection_error_is_fatal (PURPLE_CONNECTION_ERROR_NETWORK_ERROR)</tt> 517 * is @c FALSE. On the other hand, 518 * #PURPLE_CONNECTION_ERROR_AUTHENTICATION_FAILED probably indicates a 519 * misconfiguration of the account which needs the user to go fix it up, so 520 * <tt> purple_connection_error_is_fatal 521 * (PURPLE_CONNECTION_ERROR_AUTHENTICATION_FAILED)</tt> is @c TRUE. 522 * 523 * (This function is meant to replace checking PurpleConnection.wants_to_die.) 524 * 525 * @return @c TRUE if the account should not be automatically reconnected, and 526 * @c FALSE otherwise. 527 * 528 * @since 2.3.0 529 */ 530 gboolean 531 purple_connection_error_is_fatal (PurpleConnectionError reason); 532 533 /*@}*/ 534 535 /**************************************************************************/ 536 /** @name Connections API */ 537 /**************************************************************************/ 538 /*@{*/ 539 540 /** 541 * Disconnects from all connections. 542 */ 543 void purple_connections_disconnect_all(void); 544 545 /** 546 * Returns a list of all active connections. This does not 547 * include connections that are in the process of connecting. 548 * 549 * @constreturn A list of all active connections. 550 */ 551 GList *purple_connections_get_all(void); 552 553 /** 554 * Returns a list of all connections in the process of connecting. 555 * 556 * @constreturn A list of connecting connections. 557 */ 558 GList *purple_connections_get_connecting(void); 559 560 /** 561 * Checks if gc is still a valid pointer to a gc. 562 * 563 * @return @c TRUE if gc is valid. 564 * 565 * @deprecated Do not use this. Instead, cancel your asynchronous request 566 * when the PurpleConnection is destroyed. 567 */ 568 /* 569 * TODO: Eventually this bad boy will be removed, because it is 570 * a gross fix for a crashy problem. 571 */ 572 #define PURPLE_CONNECTION_IS_VALID(gc) (g_list_find(purple_connections_get_all(), (gc)) != NULL) 573 574 /*@}*/ 575 576 /**************************************************************************/ 577 /** @name UI Registration Functions */ 578 /**************************************************************************/ 579 /*@{*/ 580 581 /** 582 * Sets the UI operations structure to be used for connections. 583 * 584 * @param ops The UI operations structure. 585 */ 586 void purple_connections_set_ui_ops(PurpleConnectionUiOps *ops); 587 588 /** 589 * Returns the UI operations structure used for connections. 590 * 591 * @return The UI operations structure in use. 592 */ 593 PurpleConnectionUiOps *purple_connections_get_ui_ops(void); 594 595 /*@}*/ 596 597 /**************************************************************************/ 598 /** @name Connections Subsystem */ 599 /**************************************************************************/ 600 /*@{*/ 601 602 /** 603 * Initializes the connections subsystem. 604 */ 605 void purple_connections_init(void); 606 607 /** 608 * Uninitializes the connections subsystem. 609 */ 610 void purple_connections_uninit(void); 611 612 /** 613 * Returns the handle to the connections subsystem. 614 * 615 * @return The connections subsystem handle. 616 */ 617 void *purple_connections_get_handle(void); 618 619 /*@}*/ 620 621 622 #ifdef __cplusplus 623 } 624 #endif 625 626 #endif /* _PURPLE_CONNECTION_H_ */ 627