libpurple/connection.h

   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_ */