pidgin: libpurple/connection.h comparison

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

-:774f4924e74e
+:1b174854bb80
 /**
 * @file connection.h Connection API
 * @ingroup core
+* @see @ref connection-signals
 */
 /* purple
 *
 * Purple is the legal property of its developers, whose names are too numerous
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
-*
-* @see @ref connection-signals
 */
 #ifndef _PURPLE_CONNECTION_H_
 #define _PURPLE_CONNECTION_H_
 typedef struct _PurpleConnection PurpleConnection;
 	PURPLE_CONNECTED,        /**< Connected.    */
 	PURPLE_CONNECTING        /**< Connecting.   */
 } PurpleConnectionState;
+/** Possible errors that can cause a connection to be closed.
+*  @since 2.3.0
+*/
+typedef enum
+{
+	/** There was an error sending or receiving on the network socket, or
+	 *  there was some protocol error (such as the server sending malformed
+	 *  data).
+	 */
+	PURPLE_CONNECTION_ERROR_NETWORK_ERROR = 0,
+	/** The username supplied was not valid. */
+	PURPLE_CONNECTION_ERROR_INVALID_USERNAME = 1,
+	/** The username, password or some other credential was incorrect.  Use
+	 *  #PURPLE_CONNECTION_ERROR_INVALID_USERNAME instead if the username
+*  is known to be invalid.
+	 */
+	PURPLE_CONNECTION_ERROR_AUTHENTICATION_FAILED = 2,
+	/** libpurple doesn't speak any of the authentication methods the
+	 *  server offered.
+	 */
+	PURPLE_CONNECTION_ERROR_AUTHENTICATION_IMPOSSIBLE = 3,
+	/** libpurple was built without SSL support, and the connection needs
+	 *  SSL.
+	 */
+	PURPLE_CONNECTION_ERROR_NO_SSL_SUPPORT = 4,
+	/** There was an error negotiating SSL on this connection, or the
+	 *  server does not support encryption but an account option was set to
+	 *  require it.
+	 */
+	PURPLE_CONNECTION_ERROR_ENCRYPTION_ERROR = 5,
+	/** Someone is already connected to the server using the name you are
+	 *  trying to connect with.
+	 */
+	PURPLE_CONNECTION_ERROR_NAME_IN_USE = 6,
+	/** The username/server/other preference for the account isn't valid.
+	 *  For instance, on IRC the screen name cannot contain white space.
+	 *  This reason should not be used for incorrect passwords etc: use
+	 *  #PURPLE_CONNECTION_ERROR_AUTHENTICATION_FAILED for that.
+	 *
+	 *  @todo This reason really shouldn't be necessary.  Usernames and
+	 *        other account preferences should be validated when the
+	 *        account is created.
+	 */
+	PURPLE_CONNECTION_ERROR_INVALID_SETTINGS = 7,
+	/** The server did not provide a SSL certificate. */
+	PURPLE_CONNECTION_ERROR_CERT_NOT_PROVIDED = 8,
+	/** The server's SSL certificate could not be trusted. */
+	PURPLE_CONNECTION_ERROR_CERT_UNTRUSTED = 9,
+	/** The server's SSL certificate has expired. */
+	PURPLE_CONNECTION_ERROR_CERT_EXPIRED = 10,
+	/** The server's SSL certificate is not yet valid. */
+	PURPLE_CONNECTION_ERROR_CERT_NOT_ACTIVATED = 11,
+	/** The server's SSL certificate did not match its hostname. */
+	PURPLE_CONNECTION_ERROR_CERT_HOSTNAME_MISMATCH = 12,
+	/** The server's SSL certificate does not have the expected
+	 *  fingerprint.
+	 */
+	PURPLE_CONNECTION_ERROR_CERT_FINGERPRINT_MISMATCH = 13,
+	/** The server's SSL certificate is self-signed.  */
+	PURPLE_CONNECTION_ERROR_CERT_SELF_SIGNED = 14,
+	/** There was some other error validating the server's SSL certificate.
+	 */
+	PURPLE_CONNECTION_ERROR_CERT_OTHER_ERROR = 15,
+	/** Some other error occured which fits into none of the other
+	 *  categories.
+	 */
+	/* purple_connection_error_reason() in connection.c uses the fact that
+	 * this is the last member of the enum when sanity-checking; if other
+	 * reasons are added after it, the check must be updated.
+	 */
+	PURPLE_CONNECTION_ERROR_OTHER_ERROR = 16
+} PurpleConnectionError;
+/** Holds the type of an error along with its description. */
+typedef struct
+{
+	/** The type of error. */
+	PurpleConnectionError type;
+	/** A localised, human-readable description of the error. */
+	char *description;
+} PurpleConnectionErrorInfo;
 #include <time.h>
 #include "account.h"
 #include "plugin.h"
 #include "status.h"
+#include "sslconn.h"
 /** Connection UI operations.  Used to notify the user of changes to
 *  connections, such as being disconnected, and to respond to the
 *  underlying network connection appearing and disappearing.  UIs should
 *  call #purple_connections_set_ui_ops() with an instance of this struct.
 {
 	/** When an account is connecting, this operation is called to notify
 	 *  the UI of what is happening, as well as which @a step out of @a
 	 *  step_count has been reached (which might be displayed as a progress
 	 *  bar).
+	 *  @see #purple_connection_update_progress
 	 */
 	void (*connect_progress)(PurpleConnection *gc,
 	                         const char *text,
 	                         size_t step,
 	                         size_t step_count);
 	/** Called when a connection is established (just before the
 	 *  @ref signed-on signal).
 	 */
 	void (*connected)(PurpleConnection *gc);
 	/** Called when a connection is ended (between the @ref signing-off
 	 *  and @ref signed-off signals).
 	 */
 	void (*disconnected)(PurpleConnection *gc);
 	/** Used to display connection-specific notices.  (Pidgin's Gtk user
 	 *  interface implements this as a no-op; #purple_connection_notice(),
 	 *  which uses this operation, is not used by any of the protocols
 	 *  shipped with libpurple.)
 	 */
 	void (*notice)(PurpleConnection *gc, const char *text);
 	/** Called when an error causes a connection to be disconnected.
 	 *  Called before #disconnected.
 	 *  @param text  a localized error message.
+	 *  @see #purple_connection_error
+	 *  @deprecated in favour of
+	 *              #PurpleConnectionUiOps.report_disconnect_reason.
 	 */
 	void (*report_disconnect)(PurpleConnection *gc, const char *text);
 	/** Called when libpurple discovers that the computer's network
 	 *  connection is active.  On Linux, this uses Network Manager if
 	 *  available; on Windows, it uses Win32's network change notification
 	 *  infrastructure.
 	 */
 	/** Called when libpurple discovers that the computer's network
 	 *  connection has gone away.
 	 */
 	void (*network_disconnected)();
+	/** Called when an error causes a connection to be disconnected.
+	 *  Called before #disconnected.  This op is intended to replace
+	 *  #report_disconnect.  If both are implemented, this will be called
+	 *  first; however, there's no real reason to implement both.
+	 *  @param reason  why the connection ended, if known, or
+	 *                 #PURPLE_CONNECTION_ERROR_OTHER_ERROR, if not.
+	 *  @param text  a localized message describing the disconnection
+	 *               in more detail to the user.
+	 *  @see #purple_connection_error_reason
+	 *  @since 2.3.0
+	 */
+	void (*report_disconnect_reason)(PurpleConnection *gc,
+	                                 PurpleConnectionError reason,
+	                                 const char *text);
 	void (*_purple_reserved1)(void);
 	void (*_purple_reserved2)(void);
 	void (*_purple_reserved3)(void);
-	void (*_purple_reserved4)(void);
 } PurpleConnectionUiOps;
 struct _PurpleConnection
 {
 	PurplePlugin *prpl;            /**< The protocol plugin.               */
 	PurpleAccount *account;        /**< The account being connected to.    */
 	char *password;              /**< The password used.                 */
 	int inpa;                    /**< The input watcher.                 */
-	GSList *buddy_chats;         /**< A list of active chats.            */
+	GSList *buddy_chats;         /**< A list of active chats
+	                                  (#PurpleConversation structs of type
+	                                  #PURPLE_CONV_TYPE_CHAT).           */
 	void *proto_data;            /**< Protocol-specific data.            */
 	char *display_name;          /**< How you appear to other people.    */
 	guint keepalive;             /**< Keep-alive.                        */
+	/** Wants to Die state.  This is set when the user chooses to log out, or
-	gboolean wants_to_die;	     /**< Wants to Die state.  This is set
+	 * when the protocol is disconnected and should not be automatically
-	                                  when the user chooses to log out,
+	 * reconnected (incorrect password, etc.).  prpls should rely on
-	                                  or when the protocol is
+	 * purple_connection_error_reason() to set this for them rather than
-	                                  disconnected and should not be
+	 * setting it themselves.
-	                                  automatically reconnected
+	 * @see purple_connection_error_is_fatal
-	                                  (incorrect password, etc.)         */
+	 */
+	gboolean wants_to_die;
 	guint disconnect_timeout;    /**< Timer used for nasty stack tricks  */
 };
 #ifdef __cplusplus
 extern "C" {
 /**************************************************************************/
 /** @name Connection API                                                  */
 /**************************************************************************/
 /*@{*/
+#ifndef PURPLE_DISABLE_DEPRECATED
 /**
 * This function should only be called by purple_account_connect()
 * in account.c.  If you're trying to sign on an account, use that
 * function instead.
 *
 *
 * @param account  The account the connection should be connecting to.
 * @param regist   Whether we are registering a new account or just
 *                 trying to do a normal signon.
 * @param password The password to use.
+*
+* @deprecated As this is internal, we should make it private in 3.0.0.
 */
 void purple_connection_new(PurpleAccount *account, gboolean regist,
 									const char *password);
+#endif
+#ifndef PURPLE_DISABLE_DEPRECATED
 /**
 * This function should only be called by purple_account_unregister()
 * in account.c.
 *
 * Tries to unregister the account on the server. If the account is not
 * connected, also creates a new connection.
 *
 * @param account  The account to unregister
 * @param password The password to use.
+* @param cb Optional callback to be called when unregistration is complete
+* @param user_data user data to pass to the callback
+*
+* @deprecated As this is internal, we should make it private in 3.0.0.
 */
 void purple_connection_new_unregister(PurpleAccount *account, const char *password, PurpleAccountUnregistrationCb cb, void *user_data);
+#endif
+#ifndef PURPLE_DISABLE_DEPRECATED
 /**
 * Disconnects and destroys a PurpleConnection.
 *
 * This function should only be called by purple_account_disconnect()
 * in account.c.  If you're trying to sign off an account, use that
 * function instead.
 *
 * @param gc The purple connection to destroy.
+*
+* @deprecated As this is internal, we should make it private in 3.0.0.
 */
 void purple_connection_destroy(PurpleConnection *gc);
+#endif
 /**
 * Sets the connection state.  PRPLs should call this and pass in
-* the state "PURPLE_CONNECTED" when the account is completely
+* the state #PURPLE_CONNECTED when the account is completely
 * signed on.  What does it mean to be completely signed on?  If
 * the core can call prpl->set_status, and it successfully changes
 * your status, then the account is online.
 *
 * @param gc    The connection.
 /**
 * Closes a connection with an error.
 *
 * @param gc     The connection.
-* @param reason The error text.
+* @param reason The error text, which may not be @c NULL.
+* @deprecated in favour of #purple_connection_error_reason.  Calling
+*  @c purple_connection_error(gc, text) is equivalent to calling
+*  @c purple_connection_error_reason(gc, reason, text) where @c reason is
+*  #PURPLE_CONNECTION_ERROR_OTHER_ERROR if @c gc->wants_to_die is @c TRUE, and
+*  #PURPLE_CONNECTION_ERROR_NETWORK_ERROR if not.  (This is to keep
+*  auto-reconnection behaviour the same when using old prpls which don't use
+*  reasons yet.)
 */
 void purple_connection_error(PurpleConnection *gc, const char *reason);
+/**
+* Closes a connection with an error and a human-readable description of the
+* error.  It also sets @c gc->wants_to_die to the value of
+* #purple_connection_error_is_fatal(@a reason), mainly for
+* backwards-compatibility.
+*
+* @param gc          the connection which is closing.
+* @param reason      why the connection is closing.
+* @param description a non-@c NULL localized description of the error.
+* @since 2.3.0
+*/
+void
+purple_connection_error_reason (PurpleConnection *gc,
+PurpleConnectionError reason,
+const char *description);
+/**
+* Closes a connection due to an SSL error; this is basically a shortcut to
+* turning the #PurpleSslErrorType into a #PurpleConnectionError and a
+* human-readable string and then calling purple_connection_error_reason().
+* @since 2.3.0
+*/
+void
+purple_connection_ssl_error (PurpleConnection *gc,
+PurpleSslErrorType ssl_error);
+/**
+* Reports whether a disconnection reason is fatal (in which case the account
+* should probably not be automatically reconnected) or transient (so
+* auto-reconnection is a good idea).
+* For instance, #PURPLE_CONNECTION_ERROR_NETWORK_ERROR is a temporary error,
+* which might be caused by losing the network connection, so <tt>
+* purple_connection_error_is_fatal (PURPLE_CONNECTION_ERROR_NETWORK_ERROR)</tt>
+* is @c FALSE.  On the other hand,
+* #PURPLE_CONNECTION_ERROR_AUTHENTICATION_FAILED probably indicates a
+* misconfiguration of the account which needs the user to go fix it up, so
+* <tt> purple_connection_error_is_fatal
+* (PURPLE_CONNECTION_ERROR_AUTHENTICATION_FAILED)</tt> is @c TRUE.
+*
+* (This function is meant to replace checking PurpleConnection.wants_to_die.)
+*
+* @return @c TRUE if the account should not be automatically reconnected, and
+*         @c FALSE otherwise.
+* @since 2.3.0
+*/
+gboolean
+purple_connection_error_is_fatal (PurpleConnectionError reason);
 /*@}*/
 /**************************************************************************/
 /** @name Connections API                                                 */

Mercurial > pidgin

comparison libpurple/connection.h @ 21563:1b174854bb80