Frameworks/libpurple.framework/Versions/2.10.12r8d2874a79747/Headers/connection.h
branchadium-1.5.11-merge
changeset 6013 f8d0dc659e3f
parent 5941 307f53385811
parent 6012 200a01709ba4
child 6014 fcb71cb71a3d
child 6015 2b01cc935b7c
equal deleted inserted replaced
5941:307f53385811 6013:f8d0dc659e3f
     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_ */