connection.h File Reference
libpurple

Connection API. More...

`#include <time.h>`
`#include "account.h"`
`#include "plugin.h"`
`#include "status.h"`
`#include "sslconn.h"`

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 <br>
void | purple_connections_set_ui_ops (PurpleConnectionUiOps *ops)
| Sets the UI operations structure to be used for connections. More...
PurpleConnectionUiOps * | purple_connections_get_ui_ops (void)
| Returns the UI operations structure used for connections. More...
Connections Subsystem <br>
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. More...

## Connection API <br>

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

## Connections API <br>

#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. More...
void | purple_connections_disconnect_all (void)
| Disconnects from all connections.
GList * | purple_connections_get_all (void)
| Returns a list of all active connections. More...
GList * | purple_connections_get_connecting (void)
| Returns a list of all connections in the process of connecting. More...

## Detailed Description

Connection API.

See also
  Connection Signals

Definition in file connection.h.

## Macro Definition Documentation

## PURPLE_CONNECTION_IS_CONNECTED

#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.

## PURPLE_CONNECTION_IS_VALID

#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

## PurpleConnection

typedef struct _PurpleConnection PurpleConnection

Definition at line 1 of file connection.h.

## Enumeration Type Documentation

## PurpleConnectionError

enum PurpleConnectionError

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.

## PurpleConnectionFlags

enum PurpleConnectionFlags

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.

## PurpleConnectionState

enum PurpleConnectionState

Enumerator
PURPLE_DISCONNECTED | Disconnected.
PURPLE_CONNECTED | Connected.
PURPLE_CONNECTING | Connecting.

Definition at line 52 of file connection.h.

## Function Documentation

## purple_connection_destroy()

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

  gc | The purple connection to destroy.

Deprecated:
  As this is internal, we should make it private in 3.0.0.

## purple_connection_error()

void purple_connection_error | ( | PurpleConnection * | gc,
|  | const char * | reason
| ) |  |

Closes a connection with an error.

Parameters

  gc | The connection.
  reason | The 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.)

## purple_connection_error_is_fatal()

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

## purple_connection_error_reason()

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

  gc | the connection which is closing.
  reason | why the connection is closing.
  description | a non-`NULL` localized description of the error.

Since
  2.3.0

## purple_connection_get_account()

PurpleAccount* purple_connection_get_account | ( | const PurpleConnection * | gc | ) |

Returns the connection's account.

Parameters

  gc | The connection.

Returns
  The connection's account.

## purple_connection_get_display_name()

const char* purple_connection_get_display_name | ( | const PurpleConnection * | gc | ) |

Returns the connection's displayed name.

Parameters

  gc | The connection.

Returns
  The connection's displayed name.

## purple_connection_get_password()

const char* purple_connection_get_password | ( | const PurpleConnection * | gc | ) |

Returns the connection's password.

Parameters

  gc | The connection.

Returns
  The connection's password.

## purple_connection_get_protocol_data()

void* purple_connection_get_protocol_data | ( | const PurpleConnection * | connection | ) |

Gets the protocol data from a connection.

Parameters

  connection | The PurpleConnection.

Returns
  The protocol data for the connection.

Since
  2.6.0

## purple_connection_get_prpl()

PurplePlugin* purple_connection_get_prpl | ( | const PurpleConnection * | gc | ) |

Returns the protocol plugin managing a connection.

Parameters

  gc | The connection.

Returns
  The protocol plugin.

Since
  2.4.0

## purple_connection_get_state()

PurpleConnectionState purple_connection_get_state | ( | const PurpleConnection * | gc | ) |

Returns the connection state.

Parameters

  gc | The connection.

Returns
  The connection state.

## purple_connection_new()

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

  account | The account the connection should be connecting to.
  regist | Whether we are registering a new account or just trying to do a normal signon.
  password | The password to use.

Deprecated:
  As this is internal, we should make it private in 3.0.0.

## purple_connection_new_unregister()

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

  account | The account to unregister
  password | The password to use.
  cb | Optional callback to be called when unregistration is complete
  user_data | user data to pass to the callback

Deprecated:
  As this is internal, we should make it private in 3.0.0.

## purple_connection_notice()

void purple_connection_notice | ( | PurpleConnection * | gc,
|  | const char * | text
| ) |  |

Displays a connection-specific notice.

Parameters

  gc | The connection.
  text | The notice text.

## purple_connection_set_account()

void purple_connection_set_account | ( | PurpleConnection * | gc,
|  | PurpleAccount * | account
| ) |  |

Sets the connection's account.

Parameters

  gc | The connection.
  account | The account.

## purple_connection_set_display_name()

void purple_connection_set_display_name | ( | PurpleConnection * | gc,
|  | const char * | name
| ) |  |

Sets the connection's displayed name.

Parameters

  gc | The connection.
  name | The displayed name.

## purple_connection_set_protocol_data()

void purple_connection_set_protocol_data | ( | PurpleConnection * | connection,
|  | void * | proto_data
| ) |  |

Sets the protocol data for a connection.

Parameters

  connection | The PurpleConnection.
  proto_data | The protocol data to set for the connection.

Since
  2.6.0

## purple_connection_set_state()

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

  gc | The connection.
  state | The connection state.

## purple_connection_ssl_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().

Since
  2.3.0

## purple_connection_update_progress()

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

Updates the connection progress.

Parameters

  gc | The connection.
  text | Information on the current step.
  step | The current step.
  count | The total number of steps.

## purple_connections_get_all()

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.

## purple_connections_get_connecting()

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.

## purple_connections_get_handle()

void* purple_connections_get_handle | ( | void |  | ) |

Returns the handle to the connections subsystem.

Returns
  The connections subsystem handle.

## purple_connections_get_ui_ops()

PurpleConnectionUiOps* purple_connections_get_ui_ops | ( | void |  | ) |

Returns the UI operations structure used for connections.

Returns
  The UI operations structure in use.

## purple_connections_set_ui_ops()

void purple_connections_set_ui_ops | ( | PurpleConnectionUiOps * | ops | ) |

Sets the UI operations structure to be used for connections.

Parameters

  ops | The UI operations structure.