connection.h File Reference

Connection API. More...

#include <time.h>
#include "account.h"
#include "plugin.h"
#include "status.h"
#include "sslconn.h"
Include dependency graph for connection.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  PurpleConnectionErrorInfo
 Holds the type of an error along with its description. More...
struct  PurpleConnectionUiOps
 Connection UI operations. More...
struct  _PurpleConnection

Typedefs

typedef struct _PurpleConnection PurpleConnection
 

Enumerations

enum  PurpleConnectionFlags {
  PURPLE_CONNECTION_HTML = 0x0001, PURPLE_CONNECTION_NO_BGCOLOR = 0x0002, PURPLE_CONNECTION_AUTO_RESP = 0x0004, PURPLE_CONNECTION_FORMATTING_WBFO = 0x0008,
  PURPLE_CONNECTION_NO_NEWLINES = 0x0010, PURPLE_CONNECTION_NO_FONTSIZE = 0x0020, PURPLE_CONNECTION_NO_URLDESC = 0x0040, PURPLE_CONNECTION_NO_IMAGES = 0x0080,
  PURPLE_CONNECTION_ALLOW_CUSTOM_SMILEY = 0x0100, PURPLE_CONNECTION_SUPPORT_MOODS = 0x0200, PURPLE_CONNECTION_SUPPORT_MOOD_MESSAGES = 0x0400
}
 Flags to change behavior of the client for a given connection. More...
enum  PurpleConnectionState { PURPLE_DISCONNECTED = 0, PURPLE_CONNECTED, PURPLE_CONNECTING }
enum  PurpleConnectionError {
  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, 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_OTHER_ERROR = 16
}
 Possible errors that can cause a connection to be closed. More...

Functions

UI Registration Functions
void purple_connections_set_ui_ops (PurpleConnectionUiOps *ops)
 Sets the UI operations structure to be used for connections.
PurpleConnectionUiOpspurple_connections_get_ui_ops (void)
 Returns the UI operations structure used for connections.
Connections Subsystem
void purple_connections_init (void)
 Initializes the connections subsystem.
void purple_connections_uninit (void)
 Uninitializes the connections subsystem.
void * purple_connections_get_handle (void)
 Returns the handle to the connections subsystem.

Connection API

#define PURPLE_CONNECTION_IS_CONNECTED(gc)   (purple_connection_get_state(gc) == PURPLE_CONNECTED)
 Returns TRUE if the account is connected, otherwise returns FALSE.
void purple_connection_new (PurpleAccount *account, gboolean regist, const char *password)
 This function should only be called by purple_account_connect() in account.c.
void purple_connection_new_unregister (PurpleAccount *account, const char *password, PurpleAccountUnregistrationCb cb, void *user_data)
 This function should only be called by purple_account_unregister() in account.c.
void purple_connection_destroy (PurpleConnection *gc)
 Disconnects and destroys a PurpleConnection.
void purple_connection_set_state (PurpleConnection *gc, PurpleConnectionState state)
 Sets the connection state.
void purple_connection_set_account (PurpleConnection *gc, PurpleAccount *account)
 Sets the connection's account.
void purple_connection_set_display_name (PurpleConnection *gc, const char *name)
 Sets the connection's displayed name.
void purple_connection_set_protocol_data (PurpleConnection *connection, void *proto_data)
 Sets the protocol data for a connection.
PurpleConnectionState purple_connection_get_state (const PurpleConnection *gc)
 Returns the connection state.
PurpleAccountpurple_connection_get_account (const PurpleConnection *gc)
 Returns the connection's account.
PurplePluginpurple_connection_get_prpl (const PurpleConnection *gc)
 Returns the protocol plugin managing a connection.
const char * purple_connection_get_password (const PurpleConnection *gc)
 Returns the connection's password.
const char * purple_connection_get_display_name (const PurpleConnection *gc)
 Returns the connection's displayed name.
void * purple_connection_get_protocol_data (const PurpleConnection *connection)
 Gets the protocol data from a connection.
void purple_connection_update_progress (PurpleConnection *gc, const char *text, size_t step, size_t count)
 Updates the connection progress.
void purple_connection_notice (PurpleConnection *gc, const char *text)
 Displays a connection-specific notice.
void purple_connection_error (PurpleConnection *gc, const char *reason)
 Closes a connection with an error.
void purple_connection_error_reason (PurpleConnection *gc, PurpleConnectionError reason, const char *description)
 Closes a connection with an error and a human-readable description of the error.
void purple_connection_ssl_error (PurpleConnection *gc, PurpleSslErrorType 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_reason().
gboolean purple_connection_error_is_fatal (PurpleConnectionError reason)
 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).

Connections API

#define PURPLE_CONNECTION_IS_VALID(gc)   (g_list_find(purple_connections_get_all(), (gc)) != NULL)
 Checks if gc is still a valid pointer to a gc.
void purple_connections_disconnect_all (void)
 Disconnects from all connections.
GList * purple_connections_get_all (void)
 Returns a list of all active connections.
GList * purple_connections_get_connecting (void)
 Returns a list of all connections in the process of connecting.

Detailed Description

Connection API.

See Also
Connection Signals

Definition in file connection.h.

Macro Definition Documentation

#define PURPLE_CONNECTION_IS_CONNECTED (   gc)    (purple_connection_get_state(gc) == PURPLE_CONNECTED)

Returns TRUE if the account is connected, otherwise returns FALSE.

Returns
TRUE if the account is connected, otherwise returns FALSE.

Definition at line 396 of file connection.h.

#define PURPLE_CONNECTION_IS_VALID (   gc)    (g_list_find(purple_connections_get_all(), (gc)) != NULL)

Checks if gc is still a valid pointer to a gc.

Returns
TRUE if gc is valid.
Deprecated:
Do not use this. Instead, cancel your asynchronous request when the PurpleConnection is destroyed.

Definition at line 572 of file connection.h.

Typedef Documentation

Definition at line 31 of file connection.h.

Enumeration Type Documentation

Possible errors that can cause a connection to be closed.

Since
2.3.0
Enumerator:
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 valid.

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.

Todo:
This reason really shouldn't be necessary. Usernames and other account preferences should be validated when the account is created.
PURPLE_CONNECTION_ERROR_CERT_NOT_PROVIDED 

The server did not provide a SSL certificate.

PURPLE_CONNECTION_ERROR_CERT_UNTRUSTED 

The server's SSL certificate could not be trusted.

PURPLE_CONNECTION_ERROR_CERT_EXPIRED 

The server's SSL certificate has expired.

PURPLE_CONNECTION_ERROR_CERT_NOT_ACTIVATED 

The server's SSL certificate is not yet valid.

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 self-signed.

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.

Definition at line 65 of file connection.h.

Flags to change behavior of the client for a given connection.

Enumerator:
PURPLE_CONNECTION_HTML 

Connection sends/receives in 'HTML'.

PURPLE_CONNECTION_NO_BGCOLOR 

Connection does not send/receive background colors.

PURPLE_CONNECTION_AUTO_RESP 

Send auto responses when away.

PURPLE_CONNECTION_FORMATTING_WBFO 

The text buffer must be formatted as a whole.

PURPLE_CONNECTION_NO_NEWLINES 

No new lines are allowed in outgoing messages.

PURPLE_CONNECTION_NO_FONTSIZE 

Connection does not send/receive font sizes.

PURPLE_CONNECTION_NO_URLDESC 

Connection does not support descriptions with links.

PURPLE_CONNECTION_NO_IMAGES 

Connection does not support sending of images.

PURPLE_CONNECTION_ALLOW_CUSTOM_SMILEY 

Connection supports sending and receiving custom smileys.

PURPLE_CONNECTION_SUPPORT_MOODS 

Connection supports setting moods.

PURPLE_CONNECTION_SUPPORT_MOOD_MESSAGES 

Connection supports setting a message on moods.

Definition at line 36 of file connection.h.

Enumerator:
PURPLE_DISCONNECTED 

Disconnected.

PURPLE_CONNECTED 

Connected.

PURPLE_CONNECTING 

Connecting.

Definition at line 52 of file connection.h.

Function Documentation

void purple_connection_destroy ( PurpleConnection gc)

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.

Parameters
gcThe purple connection to destroy.
Deprecated:
As this is internal, we should make it private in 3.0.0.
void purple_connection_error ( PurpleConnection gc,
const char *  reason 
)

Closes a connection with an error.

Parameters
gcThe connection.
reasonThe error text, which may not be NULL.
Deprecated:
in favour of purple_connection_error_reason. Calling purple_connection_error(gc, text) is equivalent to calling purple_connection_error_reason(gc, reason, text) where reason is PURPLE_CONNECTION_ERROR_OTHER_ERROR if gc->wants_to_die is 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.)
gboolean purple_connection_error_is_fatal ( PurpleConnectionError  reason)

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 purple_connection_error_is_fatal (PURPLE_CONNECTION_ERROR_NETWORK_ERROR) 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 purple_connection_error_is_fatal (PURPLE_CONNECTION_ERROR_AUTHENTICATION_FAILED) is TRUE.

(This function is meant to replace checking PurpleConnection.wants_to_die.)

Returns
TRUE if the account should not be automatically reconnected, and FALSE otherwise.
Since
2.3.0
void purple_connection_error_reason ( PurpleConnection gc,
PurpleConnectionError  reason,
const char *  description 
)

Closes a connection with an error and a human-readable description of the error.

It also sets gc->wants_to_die to the value of purple_connection_error_is_fatal(reason), mainly for backwards-compatibility.

Parameters
gcthe connection which is closing.
reasonwhy the connection is closing.
descriptiona non-NULL localized description of the error.
Since
2.3.0
PurpleAccount* purple_connection_get_account ( const PurpleConnection gc)

Returns the connection's account.

Parameters
gcThe connection.
Returns
The connection's account.
const char* purple_connection_get_display_name ( const PurpleConnection gc)

Returns the connection's displayed name.

Parameters
gcThe connection.
Returns
The connection's displayed name.
const char* purple_connection_get_password ( const PurpleConnection gc)

Returns the connection's password.

Parameters
gcThe connection.
Returns
The connection's password.
void* purple_connection_get_protocol_data ( const PurpleConnection connection)

Gets the protocol data from a connection.

Parameters
connectionThe PurpleConnection.
Returns
The protocol data for the connection.
Since
2.6.0
PurplePlugin* purple_connection_get_prpl ( const PurpleConnection gc)

Returns the protocol plugin managing a connection.

Parameters
gcThe connection.
Returns
The protocol plugin.
Since
2.4.0
PurpleConnectionState purple_connection_get_state ( const PurpleConnection gc)

Returns the connection state.

Parameters
gcThe connection.
Returns
The connection state.
void purple_connection_new ( PurpleAccount account,
gboolean  regist,
const char *  password 
)

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.

Creates a connection to the specified account and either connects or attempts to register a new account. If you are logging in, the connection uses the current active status for this account. So if you want to sign on as "away," for example, you need to have called purple_account_set_status(account, "away"). (And this will call purple_account_connect() automatically).

Parameters
accountThe account the connection should be connecting to.
registWhether we are registering a new account or just trying to do a normal signon.
passwordThe password to use.
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 
)

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.

Parameters
accountThe account to unregister
passwordThe password to use.
cbOptional callback to be called when unregistration is complete
user_datauser data to pass to the callback
Deprecated:
As this is internal, we should make it private in 3.0.0.
void purple_connection_notice ( PurpleConnection gc,
const char *  text 
)

Displays a connection-specific notice.

Parameters
gcThe connection.
textThe notice text.
void purple_connection_set_account ( PurpleConnection gc,
PurpleAccount account 
)

Sets the connection's account.

Parameters
gcThe connection.
accountThe account.
void purple_connection_set_display_name ( PurpleConnection gc,
const char *  name 
)

Sets the connection's displayed name.

Parameters
gcThe connection.
nameThe displayed name.
void purple_connection_set_protocol_data ( PurpleConnection connection,
void *  proto_data 
)

Sets the protocol data for a connection.

Parameters
connectionThe PurpleConnection.
proto_dataThe protocol data to set for the connection.
Since
2.6.0
void purple_connection_set_state ( PurpleConnection gc,
PurpleConnectionState  state 
)

Sets the connection state.

PRPLs should call this and pass in 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.

Parameters
gcThe connection.
stateThe connection state.
void purple_connection_ssl_error ( PurpleConnection gc,
PurpleSslErrorType  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_reason().

Since
2.3.0
void purple_connection_update_progress ( PurpleConnection gc,
const char *  text,
size_t  step,
size_t  count 
)

Updates the connection progress.

Parameters
gcThe connection.
textInformation on the current step.
stepThe current step.
countThe total number of steps.
GList* purple_connections_get_all ( void  )

Returns a list of all active connections.

This does not include connections that are in the process of connecting.

Note
The return value of this function must not be modified or freed.
Returns
A list of all active connections.
GList* purple_connections_get_connecting ( void  )

Returns a list of all connections in the process of connecting.

Note
The return value of this function must not be modified or freed.
Returns
A list of connecting connections.
void* purple_connections_get_handle ( void  )

Returns the handle to the connections subsystem.

Returns
The connections subsystem handle.
PurpleConnectionUiOps* purple_connections_get_ui_ops ( void  )

Returns the UI operations structure used for connections.

Returns
The UI operations structure in use.
void purple_connections_set_ui_ops ( PurpleConnectionUiOps ops)

Sets the UI operations structure to be used for connections.

Parameters
opsThe UI operations structure.
All information, including names and email addresses, entered onto this website or sent to mailing lists affiliated with this website will be public. Do not post confidential information, especially passwords!