* Purple is the legal property of its developers, whose names are too numerous * to list here. Please refer to the COPYRIGHT file distributed with this * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * 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 #ifndef PURPLE_CONNECTION_H #define PURPLE_CONNECTION_H * @section_id: libpurple-connection * @short_description: <filename>connection.h</filename> * @see_also: <link linkend="chapter-signals-connection">Connection signals</link> #define PURPLE_TYPE_CONNECTION purple_connection_get_type() typedef struct _PurpleConnection PurpleConnection; #define PURPLE_TYPE_CONNECTION_UI_OPS (purple_connection_ui_ops_get_type()) typedef struct _PurpleConnectionUiOps PurpleConnectionUiOps; #define PURPLE_TYPE_CONNECTION_ERROR_INFO (purple_connection_error_info_get_type()) typedef struct _PurpleConnectionErrorInfo PurpleConnectionErrorInfo; * @PURPLE_CONNECTION_FLAG_HTML: Connection sends/receives in 'HTML' * @PURPLE_CONNECTION_FLAG_NO_BGCOLOR: Connection does not send/receive * @PURPLE_CONNECTION_FLAG_AUTO_RESP: Send auto responses when away * @PURPLE_CONNECTION_FLAG_FORMATTING_WBFO: The text buffer must be formatted * @PURPLE_CONNECTION_FLAG_NO_NEWLINES: No new lines are allowed in outgoing * @PURPLE_CONNECTION_FLAG_NO_FONTSIZE: Connection does not send/receive font * @PURPLE_CONNECTION_FLAG_NO_URLDESC: Connection does not support descriptions * @PURPLE_CONNECTION_FLAG_NO_IMAGES: Connection does not support sending of * @PURPLE_CONNECTION_FLAG_ALLOW_CUSTOM_SMILEY: Connection supports sending * and receiving custom smileys * @PURPLE_CONNECTION_FLAG_SUPPORT_MOODS: Connection supports setting moods * @PURPLE_CONNECTION_FLAG_SUPPORT_MOOD_MESSAGES: Connection supports setting * Flags to change behavior of the client for a given connection. typedef enum /*< flags >*/ PURPLE_CONNECTION_FLAG_HTML = 0x0001, PURPLE_CONNECTION_FLAG_NO_BGCOLOR = 0x0002, PURPLE_CONNECTION_FLAG_AUTO_RESP = 0x0004, PURPLE_CONNECTION_FLAG_FORMATTING_WBFO = 0x0008, PURPLE_CONNECTION_FLAG_NO_NEWLINES = 0x0010, PURPLE_CONNECTION_FLAG_NO_FONTSIZE = 0x0020, PURPLE_CONNECTION_FLAG_NO_URLDESC = 0x0040, PURPLE_CONNECTION_FLAG_NO_IMAGES = 0x0080, PURPLE_CONNECTION_FLAG_ALLOW_CUSTOM_SMILEY = 0x0100, PURPLE_CONNECTION_FLAG_SUPPORT_MOODS = 0x0200, PURPLE_CONNECTION_FLAG_SUPPORT_MOOD_MESSAGES = 0x0400 * @PURPLE_CONNECTION_DISCONNECTED: Disconnected. * @PURPLE_CONNECTION_CONNECTED: Connected. * @PURPLE_CONNECTION_CONNECTING: Connecting. PURPLE_CONNECTION_DISCONNECTED = 0, PURPLE_CONNECTION_CONNECTED, PURPLE_CONNECTION_CONNECTING #define PURPLE_CONNECTION_ERROR purple_connection_error_quark() * purple_connection_error_quark: * Error domain for Purple connection errors. Errors in this domain will be * from the #PurpleConnectionError enum. GQuark purple_connection_error_quark(void); * @PURPLE_CONNECTION_ERROR_NETWORK_ERROR: 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_INVALID_USERNAME: The username supplied was not * @PURPLE_CONNECTION_ERROR_AUTHENTICATION_FAILED: 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_IMPOSSIBLE: libpurple doesn't speak * any of the authentication methods the server offered. * @PURPLE_CONNECTION_ERROR_NO_SSL_SUPPORT: libpurple was built without SSL * support, and the connection needs SSL. * @PURPLE_CONNECTION_ERROR_ENCRYPTION_ERROR: 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_NAME_IN_USE: Someone is already connected to the * server using the name you are trying to connect with. * @PURPLE_CONNECTION_ERROR_INVALID_SETTINGS: The username/server/other * preference for the account isn't valid. For instance, on IRC the * username cannot contain white space. This reason should not be used * for incorrect passwords etc: use * #PURPLE_CONNECTION_ERROR_AUTHENTICATION_FAILED for that. * @PURPLE_CONNECTION_ERROR_CERT_NOT_PROVIDED: The server did not provide a * @PURPLE_CONNECTION_ERROR_CERT_UNTRUSTED: The server's SSL certificate could * @PURPLE_CONNECTION_ERROR_CERT_EXPIRED: The server's SSL certificate has * @PURPLE_CONNECTION_ERROR_CERT_NOT_ACTIVATED: The server's SSL certificate is * @PURPLE_CONNECTION_ERROR_CERT_HOSTNAME_MISMATCH: The server's SSL * certificate did not match its hostname. * @PURPLE_CONNECTION_ERROR_CERT_FINGERPRINT_MISMATCH: The server's SSL * certificate does not have the expected fingerprint. * @PURPLE_CONNECTION_ERROR_CERT_SELF_SIGNED: The server's SSL certificate is * @PURPLE_CONNECTION_ERROR_CERT_OTHER_ERROR: There was some other error * validating the server's SSL certificate. * @PURPLE_CONNECTION_ERROR_OTHER_ERROR: Some other error occurred which fits * into none of the other categories. * Possible errors that can cause a connection to be closed. PURPLE_CONNECTION_ERROR_NETWORK_ERROR = 0, PURPLE_CONNECTION_ERROR_INVALID_USERNAME = 1, PURPLE_CONNECTION_ERROR_AUTHENTICATION_FAILED = 2, PURPLE_CONNECTION_ERROR_AUTHENTICATION_IMPOSSIBLE = 3, PURPLE_CONNECTION_ERROR_NO_SSL_SUPPORT = 4, PURPLE_CONNECTION_ERROR_ENCRYPTION_ERROR = 5, PURPLE_CONNECTION_ERROR_NAME_IN_USE = 6, /* TODO This reason really shouldn't be necessary. Usernames and * other account preferences should be validated when the PURPLE_CONNECTION_ERROR_INVALID_SETTINGS = 7, PURPLE_CONNECTION_ERROR_CERT_NOT_PROVIDED = 8, PURPLE_CONNECTION_ERROR_CERT_UNTRUSTED = 9, PURPLE_CONNECTION_ERROR_CERT_EXPIRED = 10, PURPLE_CONNECTION_ERROR_CERT_NOT_ACTIVATED = 11, PURPLE_CONNECTION_ERROR_CERT_HOSTNAME_MISMATCH = 12, PURPLE_CONNECTION_ERROR_CERT_FINGERPRINT_MISMATCH = 13, PURPLE_CONNECTION_ERROR_CERT_SELF_SIGNED = 14, PURPLE_CONNECTION_ERROR_CERT_OTHER_ERROR = 15, /* purple_connection_error() 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 * PurpleConnectionErrorInfo: * @type: The type of error. * @description: A localised, human-readable description of the error. * Holds the type of an error along with its description. struct _PurpleConnectionErrorInfo PurpleConnectionError type; * @connect_progress: When an account is connecting, this operation is called to * notify the UI of what is happening, as well as which @step * out of @step_count has been reached (which might be * displayed as a progress bar). * <sbr/>See purple_connection_update_progress(). * @connected: Called when a connection is established (just before the * <link linkend="connections-signed-on"><literal>"signed-on"</literal></link> * @disconnected: Called when a connection is ended (between the * <link linkend="connections-signing-off"><literal>"signing-off"</literal></link> * and <link linkend="connections-signed-off"><literal>"signed-off"</literal></link> * @notice: 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.) * @network_connected: 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. * @network_disconnected: Called when libpurple discovers that the computer's * network connection has gone away. * @report_disconnect: Called when an error causes a connection to be * disconnected. Called before @disconnected. * <sbr/>See purple_connection_error(). * <sbr/>@reason: why the connection ended, if known, or * #PURPLE_CONNECTION_ERROR_OTHER_ERROR, if not. * <sbr/>@text: a localized message describing the * disconnection in more detail to the user. * 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. * See <link linkend="chapter-ui-ops">List of <literal>UiOps</literal> Structures</link> struct _PurpleConnectionUiOps void (*connect_progress)(PurpleConnection *gc, void (*connected)(PurpleConnection *gc); void (*disconnected)(PurpleConnection *gc); void (*notice)(PurpleConnection *gc, const char *text); void (*network_connected)(void); void (*network_disconnected)(void); void (*report_disconnect)(PurpleConnection *gc, PurpleConnectionError reason, void (*_purple_reserved1)(void); void (*_purple_reserved2)(void); void (*_purple_reserved3)(void); void (*_purple_reserved4)(void); /**************************************************************************/ /**************************************************************************/ * purple_connection_get_type: * Returns: The #GType for the Connection object. G_DECLARE_FINAL_TYPE(PurpleConnection, purple_connection, PURPLE, CONNECTION, GObject) * purple_connection_error_info_get_type: * Returns: The #GType for the #PurpleConnectionErrorInfo boxed structure. GType purple_connection_error_info_get_type(void); * purple_connection_set_state: * @state: The connection state. * Sets the connection state. Protocols should call this and pass in * the state #PURPLE_CONNECTION_CONNECTED when the account is completely * signed on. What does it mean to be completely signed on? If * the core can call protocol's set_status, and it successfully changes * your status, then the account is online. void purple_connection_set_state(PurpleConnection *gc, PurpleConnectionState state); * purple_connection_set_flags: * Sets the connection flags. void purple_connection_set_flags(PurpleConnection *gc, PurpleConnectionFlags flags); * purple_connection_set_display_name: * @name: The displayed name. * Sets the connection's displayed name. void purple_connection_set_display_name(PurpleConnection *gc, const char *name); * purple_connection_set_protocol_data: * @connection: The PurpleConnection. * @proto_data: The protocol data to set for the connection. * Sets the protocol data for a connection. void purple_connection_set_protocol_data(PurpleConnection *connection, void *proto_data); * purple_connection_get_state: * Returns the connection state. * Returns: The connection state. PurpleConnectionState purple_connection_get_state(PurpleConnection *gc); * purple_connection_get_flags: * Returns the connection flags. * Returns: The connection flags. PurpleConnectionFlags purple_connection_get_flags(PurpleConnection *gc); * PURPLE_CONNECTION_IS_CONNECTED: * Returns TRUE if the account is connected, otherwise returns FALSE. * Returns: TRUE if the account is connected, otherwise returns FALSE. #define PURPLE_CONNECTION_IS_CONNECTED(gc) \ (purple_connection_get_state(gc) == PURPLE_CONNECTION_CONNECTED) * purple_connection_is_disconnecting: * @param gc The connection. * Checks, if connection is in disconnecting state. * Returns: %TRUE, if the account is disconnecting. purple_connection_is_disconnecting(PurpleConnection *gc); * purple_connection_get_account: * Returns the connection's account. * Returns: (transfer none): The connection's account. PurpleAccount *purple_connection_get_account(PurpleConnection *gc); * purple_connection_get_protocol: * Returns the protocol managing a connection. * Returns: (transfer none): The protocol. PurpleProtocol *purple_connection_get_protocol(PurpleConnection *gc); * purple_connection_get_password: * Returns the connection's password. * Returns: The connection's password. const char *purple_connection_get_password(PurpleConnection *gc); * purple_connection_get_active_chats: * Returns a list of active chat conversations on a connection. * Returns: (element-type PurpleChatConversation) (transfer none): The active * chats on the connection. GSList *purple_connection_get_active_chats(PurpleConnection *gc); * purple_connection_get_display_name: * Returns the connection's displayed name. * Returns: The connection's displayed name. const char *purple_connection_get_display_name(PurpleConnection *gc); * purple_connection_get_protocol_data: * @gc: The PurpleConnection. * Gets the protocol data from a connection. * Returns: The protocol data for the connection. void *purple_connection_get_protocol_data(PurpleConnection *gc); * purple_connection_update_progress: * @text: Information on the current step. * @step: The current step. * @count: The total number of steps. * Updates the connection progress. void purple_connection_update_progress(PurpleConnection *gc, const char *text, size_t step, size_t count); * purple_connection_notice: * @text: The notice text. * Displays a connection-specific notice. void purple_connection_notice(PurpleConnection *gc, const char *text); * purple_connection_error: * @gc: the connection which is closing. * @reason: why the connection is closing. * @description: a localized description of the error (not %NULL ). * Closes a connection with an error and a human-readable description of the purple_connection_error(PurpleConnection *gc, PurpleConnectionError reason, const char *description); * purple_connection_get_error_info: * Returns the #PurpleConnectionErrorInfo instance of a connection if an * Returns: The #PurpleConnectionErrorInfo instance of the connection if an * error exists, %NULL otherwise. PurpleConnectionErrorInfo * purple_connection_get_error_info(PurpleConnection *gc); * purple_connection_ssl_error: * 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(). purple_connection_ssl_error (PurpleConnection *gc, PurpleSslErrorType ssl_error); * purple_connection_g_error * @gc: Connection the error is associated with * @error: Error information * Closes a connection similar to purple_connection_error(), but * takes a GError which is then converted to purple error codes. * This function ignores G_IO_ERROR_CANCELLED, returning without * closing the connection. This can be used as a shortcut when * cancelling connections, as this is commonly done when shutting * down a connection. If G_IO_ERROR_CANCELLED needs to be caught, * do so with g_error_matches() prior to calling this function. purple_connection_g_error(PurpleConnection *pc, * purple_connection_take_error * @gc: Connection the error is associated with * @error: (transfer full): Error information * Closes a connection similar to purple_connection_error(), but * takes a GError which is then converted to purple error codes. * This function is equivalent to purple_connection_g_error(), * except that it takes ownership of the GError. purple_connection_take_error(PurpleConnection *pc, * purple_connection_error_is_fatal: * 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 <literal> * purple_connection_error_is_fatal (PURPLE_CONNECTION_ERROR_NETWORK_ERROR)</literal> * is %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 * <literal> purple_connection_error_is_fatal * (PURPLE_CONNECTION_ERROR_AUTHENTICATION_FAILED)</literal> is %TRUE. * Returns: %TRUE if the account should not be automatically reconnected, and purple_connection_error_is_fatal (PurpleConnectionError reason); * purple_connection_update_last_received: * Indicate that a packet was received on the connection. * Set by the protocol to avoid sending unneeded keepalives. void purple_connection_update_last_received(PurpleConnection *gc); /**************************************************************************/ /**************************************************************************/ * purple_connections_disconnect_all: * Disconnects from all connections. void purple_connections_disconnect_all(void); * purple_connections_get_all: * Returns a list of all active connections. This does not * include connections that are in the process of connecting. * Returns: (element-type PurpleConnection) (transfer none): A list of all GList *purple_connections_get_all(void); * purple_connections_get_connecting: * Returns a list of all connections in the process of connecting. * Returns: (element-type PurpleConnection) (transfer none): A list of * connecting connections. GList *purple_connections_get_connecting(void); /**************************************************************************/ /* UI Registration Functions */ /**************************************************************************/ * purple_connection_ui_ops_get_type: * Returns: The #GType for the #PurpleConnectionUiOps boxed structure. GType purple_connection_ui_ops_get_type(void); * purple_connections_set_ui_ops: * @ops: The UI operations structure. * Sets the UI operations structure to be used for connections. void purple_connections_set_ui_ops(PurpleConnectionUiOps *ops); * purple_connections_get_ui_ops: * Returns the UI operations structure used for connections. * Returns: The UI operations structure in use. PurpleConnectionUiOps *purple_connections_get_ui_ops(void); /**************************************************************************/ /* Connections Subsystem */ /**************************************************************************/ * purple_connections_init: * Initializes the connections subsystem. void purple_connections_init(void); * purple_connections_uninit: * Uninitializes the connections subsystem. void purple_connections_uninit(void); * purple_connections_get_handle: * Returns the handle to the connections subsystem. * Returns: The connections subsystem handle. void *purple_connections_get_handle(void); #endif /* PURPLE_CONNECTION_H */