connection.h
Go to the documentation of this file.
1
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
31 typedef struct _PurpleConnection PurpleConnection;
32
36 typedef enum
37 {
38 PURPLE_CONNECTION_HTML = 0x0001,
39 PURPLE_CONNECTION_NO_BGCOLOR = 0x0002,
41 PURPLE_CONNECTION_AUTO_RESP = 0x0004,
42 PURPLE_CONNECTION_FORMATTING_WBFO = 0x0008,
43 PURPLE_CONNECTION_NO_NEWLINES = 0x0010,
44 PURPLE_CONNECTION_NO_FONTSIZE = 0x0020,
45 PURPLE_CONNECTION_NO_URLDESC = 0x0040,
46 PURPLE_CONNECTION_NO_IMAGES = 0x0080,
47 PURPLE_CONNECTION_ALLOW_CUSTOM_SMILEY = 0x0100,
48 PURPLE_CONNECTION_SUPPORT_MOODS = 0x0200,
49 PURPLE_CONNECTION_SUPPORT_MOOD_MESSAGES = 0x0400
50 } PurpleConnectionFlags;
51
52 typedef enum
53 {
54 PURPLE_DISCONNECTED = 0,
55 PURPLE_CONNECTED,
56 PURPLE_CONNECTING
58 } PurpleConnectionState;
59
65 typedef enum
66 {
71 PURPLE_CONNECTION_ERROR_NETWORK_ERROR = 0,
73 PURPLE_CONNECTION_ERROR_INVALID_USERNAME = 1,
78 PURPLE_CONNECTION_ERROR_AUTHENTICATION_FAILED = 2,
82 PURPLE_CONNECTION_ERROR_AUTHENTICATION_IMPOSSIBLE = 3,
86 PURPLE_CONNECTION_ERROR_NO_SSL_SUPPORT = 4,
91 PURPLE_CONNECTION_ERROR_ENCRYPTION_ERROR = 5,
95 PURPLE_CONNECTION_ERROR_NAME_IN_USE = 6,
96
106 PURPLE_CONNECTION_ERROR_INVALID_SETTINGS = 7,
107
109 PURPLE_CONNECTION_ERROR_CERT_NOT_PROVIDED = 8,
111 PURPLE_CONNECTION_ERROR_CERT_UNTRUSTED = 9,
113 PURPLE_CONNECTION_ERROR_CERT_EXPIRED = 10,
115 PURPLE_CONNECTION_ERROR_CERT_NOT_ACTIVATED = 11,
117 PURPLE_CONNECTION_ERROR_CERT_HOSTNAME_MISMATCH = 12,
121 PURPLE_CONNECTION_ERROR_CERT_FINGERPRINT_MISMATCH = 13,
123 PURPLE_CONNECTION_ERROR_CERT_SELF_SIGNED = 14,
126 PURPLE_CONNECTION_ERROR_CERT_OTHER_ERROR = 15,
127
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
139 typedef struct
140 {
142 PurpleConnectionError type;
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
162 typedef struct
163 {
171 void (*connect_progress)(PurpleConnection *gc,
172 const char *text,
173 size_t step,
174 size_t step_count);
175
180 void (*connected)(PurpleConnection *gc);
181
186 void (*disconnected)(PurpleConnection *gc);
187
194 void (*notice)(PurpleConnection *gc, const char *text);
195
204 void (*report_disconnect)(PurpleConnection *gc, const char *text);
205
212 void (*network_connected)(void);
213
218 void (*network_disconnected)(void);
219
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;
248 PurpleConnectionFlags flags;
250 PurpleConnectionState state;
252 PurpleAccount *account;
253 char *password;
254 int inpa;
256 GSList *buddy_chats;
259 void *proto_data;
261 char *display_name;
262 guint keepalive;
271 gboolean wants_to_die;
272
273 guint disconnect_timeout;
274 time_t last_received;
276 };
277
278 #ifdef __cplusplus
279 extern "C" {
280 #endif
281
282 /**************************************************************************/
284 /**************************************************************************/
287 #if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_CONNECTION_C_)
288
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
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
341 void purple_connection_destroy(PurpleConnection *gc);
342 #endif
343
354 void purple_connection_set_state(PurpleConnection *gc, PurpleConnectionState state);
355
362 void purple_connection_set_account(PurpleConnection *gc, PurpleAccount *account);
363
370 void purple_connection_set_display_name(PurpleConnection *gc, const char *name);
371
380 void purple_connection_set_protocol_data(PurpleConnection *connection, void *proto_data);
381
389 PurpleConnectionState purple_connection_get_state(const PurpleConnection *gc);
390
396 #define PURPLE_CONNECTION_IS_CONNECTED(gc) \
397 (purple_connection_get_state(gc) == PURPLE_CONNECTED)
398
406 PurpleAccount *purple_connection_get_account(const PurpleConnection *gc);
407
417 PurplePlugin * purple_connection_get_prpl(const PurpleConnection *gc);
418
426 const char *purple_connection_get_password(const PurpleConnection *gc);
427
435 const char *purple_connection_get_display_name(const PurpleConnection *gc);
436
446 void *purple_connection_get_protocol_data(const PurpleConnection *connection);
447
456 void purple_connection_update_progress(PurpleConnection *gc, const char *text,
457 size_t step, size_t count);
458
465 void purple_connection_notice(PurpleConnection *gc, const char *text);
466
480 void purple_connection_error(PurpleConnection *gc, const char *reason);
481
494 void
495 purple_connection_error_reason (PurpleConnection *gc,
496 PurpleConnectionError reason,
497 const char *description);
498
506 void
507 purple_connection_ssl_error (PurpleConnection *gc,
508 PurpleSslErrorType ssl_error);
509
530 gboolean
531 purple_connection_error_is_fatal (PurpleConnectionError reason);
532
535 /**************************************************************************/
537 /**************************************************************************/
543 void purple_connections_disconnect_all(void);
544
551 GList *purple_connections_get_all(void);
552
558 GList *purple_connections_get_connecting(void);
559
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
576 /**************************************************************************/
578 /**************************************************************************/
586 void purple_connections_set_ui_ops(PurpleConnectionUiOps *ops);
587
593 PurpleConnectionUiOps *purple_connections_get_ui_ops(void);
594
597 /**************************************************************************/
599 /**************************************************************************/
605 void purple_connections_init(void);
606
610 void purple_connections_uninit(void);
611
617 void *purple_connections_get_handle(void);
618
622 #ifdef __cplusplus
623 }
624 #endif
625
626 #endif /* _PURPLE_CONNECTION_H_ */
purple_connection_get_state
PurpleConnectionState purple_connection_get_state(const PurpleConnection *gc)
Returns the connection state.
PURPLE_CONNECTION_HTML
Connection sends/receives in &#39;HTML&#39;.
Definition: connection.h:38
_PurpleConnection::last_received
time_t last_received
When we last received a packet.
Definition: connection.h:274
PURPLE_CONNECTION_ERROR_NETWORK_ERROR
There was an error sending or receiving on the network socket, or there was some protocol error (such...
Definition: connection.h:71
sslconn.h
SSL API.
PurpleConnectionState
PurpleConnectionState
Definition: connection.h:52
PURPLE_CONNECTED
Connected.
Definition: connection.h:55
PURPLE_CONNECTION_ERROR_AUTHENTICATION_IMPOSSIBLE
libpurple doesn&#39;t speak any of the authentication methods the server offered.
Definition: connection.h:82
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.
PURPLE_CONNECTION_NO_FONTSIZE
Connection does not send/receive font sizes.
Definition: connection.h:44
PURPLE_CONNECTION_ERROR_CERT_FINGERPRINT_MISMATCH
The server&#39;s SSL certificate does not have the expected fingerprint.
Definition: connection.h:121
PurpleConnectionUiOps
Connection UI operations.
Definition: connection.h:162
purple_connections_uninit
void purple_connections_uninit(void)
Uninitializes the connections subsystem.
PURPLE_DISCONNECTED
Disconnected.
Definition: connection.h:54
_PurpleConnection::state
PurpleConnectionState state
The connection state.
Definition: connection.h:250
purple_connection_set_display_name
void purple_connection_set_display_name(PurpleConnection *gc, const char *name)
Sets the connection&#39;s displayed name.
PurpleConnectionErrorInfo
Holds the type of an error along with its description.
Definition: connection.h:139
PURPLE_CONNECTION_AUTO_RESP
Send auto responses when away.
Definition: connection.h:41
PURPLE_CONNECTION_ERROR_INVALID_SETTINGS
The username/server/other preference for the account isn&#39;t valid.
Definition: connection.h:106
plugin.h
Plugin API.
_PurpleConnection::inpa
int inpa
The input watcher.
Definition: connection.h:254
purple_connections_disconnect_all
void purple_connections_disconnect_all(void)
Disconnects from all connections.
PURPLE_CONNECTING
Connecting.
Definition: connection.h:56
purple_connection_notice
void purple_connection_notice(PurpleConnection *gc, const char *text)
Displays a connection-specific notice.
PURPLE_CONNECTION_ERROR_NO_SSL_SUPPORT
libpurple was built without SSL support, and the connection needs SSL.
Definition: connection.h:86
purple_connection_set_state
void purple_connection_set_state(PurpleConnection *gc, PurpleConnectionState state)
Sets the connection state.
_PurpleAccount
Structure representing an account.
Definition: account.h:169
_PurpleConnection::keepalive
guint keepalive
Keep-alive.
Definition: connection.h:262
PURPLE_CONNECTION_ERROR_CERT_SELF_SIGNED
The server&#39;s SSL certificate is self-signed.
Definition: connection.h:123
_PurplePlugin
A plugin handle.
Definition: plugin.h:151
_PurpleConnection::proto_data
void * proto_data
Protocol-specific data.
Definition: connection.h:259
purple_connections_set_ui_ops
void purple_connections_set_ui_ops(PurpleConnectionUiOps *ops)
Sets the UI operations structure to be used for connections.
PURPLE_CONNECTION_FORMATTING_WBFO
The text buffer must be formatted as a whole.
Definition: connection.h:42
PURPLE_CONNECTION_NO_NEWLINES
No new lines are allowed in outgoing messages.
Definition: connection.h:43
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 aut...
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 PurpleSslErrorTy...
purple_connection_update_progress
void purple_connection_update_progress(PurpleConnection *gc, const char *text, size_t step, size_t count)
Updates the connection progress.
_PurpleConnection::flags
PurpleConnectionFlags flags
Connection flags.
Definition: connection.h:248
_PurpleConnection::prpl
PurplePlugin * prpl
The protocol plugin.
Definition: connection.h:247
purple_connections_init
void purple_connections_init(void)
Initializes the connections subsystem.
PURPLE_CONNECTION_ERROR_AUTHENTICATION_FAILED
The username, password or some other credential was incorrect.
Definition: connection.h:78
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.
_PurpleConnection::disconnect_timeout
guint disconnect_timeout
Timer used for nasty stack tricks.
Definition: connection.h:273
purple_connections_get_connecting
GList * purple_connections_get_connecting(void)
Returns a list of all connections in the process of connecting.
purple_connections_get_handle
void * purple_connections_get_handle(void)
Returns the handle to the connections subsystem.
purple_connection_destroy
void purple_connection_destroy(PurpleConnection *gc)
Disconnects and destroys a PurpleConnection.
PURPLE_CONNECTION_ERROR_CERT_NOT_PROVIDED
The server did not provide a SSL certificate.
Definition: connection.h:109
purple_connections_get_ui_ops
PurpleConnectionUiOps * purple_connections_get_ui_ops(void)
Returns the UI operations structure used for connections.
_PurpleConnection::buddy_chats
GSList * buddy_chats
A list of active chats (PurpleConversation structs of type PURPLE_CONV_TYPE_CHAT).
Definition: connection.h:256
purple_connections_get_all
GList * purple_connections_get_all(void)
Returns a list of all active connections.
_PurpleConnection::display_name
char * display_name
How you appear to other people.
Definition: connection.h:261
PURPLE_CONNECTION_ERROR_CERT_NOT_ACTIVATED
The server&#39;s SSL certificate is not yet valid.
Definition: connection.h:115
_PurpleConnection::wants_to_die
gboolean wants_to_die
Wants to Die state.
Definition: connection.h:271
purple_connection_error
void purple_connection_error(PurpleConnection *gc, const char *reason)
Closes a connection with an error.
_PurpleConnection::account
PurpleAccount * account
The account being connected to.
Definition: connection.h:252
PURPLE_CONNECTION_ERROR_INVALID_USERNAME
The username supplied was not valid.
Definition: connection.h:73
PURPLE_CONNECTION_ERROR_ENCRYPTION_ERROR
There was an error negotiating SSL on this connection, or the server does not support encryption but ...
Definition: connection.h:91
purple_connection_get_protocol_data
void * purple_connection_get_protocol_data(const PurpleConnection *connection)
Gets the protocol data from a connection.
PURPLE_CONNECTION_ERROR_CERT_HOSTNAME_MISMATCH
The server&#39;s SSL certificate did not match its hostname.
Definition: connection.h:117
PURPLE_CONNECTION_SUPPORT_MOOD_MESSAGES
Connection supports setting a message on moods.
Definition: connection.h:49
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.
account.h
Account API.
PurpleSslErrorType
PurpleSslErrorType
Possible SSL errors.
Definition: sslconn.h:30
purple_connection_get_account
PurpleAccount * purple_connection_get_account(const PurpleConnection *gc)
Returns the connection&#39;s account.
status.h
Status APIA brief explanation of the status API:
PurpleConnectionFlags
PurpleConnectionFlags
Flags to change behavior of the client for a given connection.
Definition: connection.h:36
PurpleConnectionError
PurpleConnectionError
Possible errors that can cause a connection to be closed.
Definition: connection.h:65
purple_connection_get_prpl
PurplePlugin * purple_connection_get_prpl(const PurpleConnection *gc)
Returns the protocol plugin managing a connection.
PURPLE_CONNECTION_ALLOW_CUSTOM_SMILEY
Connection supports sending and receiving custom smileys.
Definition: connection.h:47
PURPLE_CONNECTION_ERROR_CERT_OTHER_ERROR
There was some other error validating the server&#39;s SSL certificate.
Definition: connection.h:126
PURPLE_CONNECTION_ERROR_CERT_UNTRUSTED
The server&#39;s SSL certificate could not be trusted.
Definition: connection.h:111
PURPLE_CONNECTION_ERROR_CERT_EXPIRED
The server&#39;s SSL certificate has expired.
Definition: connection.h:113
_PurpleConnection
Definition: connection.h:245
purple_connection_get_display_name
const char * purple_connection_get_display_name(const PurpleConnection *gc)
Returns the connection&#39;s displayed name.
purple_connection_get_password
const char * purple_connection_get_password(const PurpleConnection *gc)
Returns the connection&#39;s password.
purple_connection_set_account
void purple_connection_set_account(PurpleConnection *gc, PurpleAccount *account)
Sets the connection&#39;s account.
PurpleConnectionErrorInfo::type
PurpleConnectionError type
The type of error.
Definition: connection.h:142
PURPLE_CONNECTION_NO_URLDESC
Connection does not support descriptions with links.
Definition: connection.h:45
purple_connection_set_protocol_data
void purple_connection_set_protocol_data(PurpleConnection *connection, void *proto_data)
Sets the protocol data for a connection.
PURPLE_CONNECTION_ERROR_NAME_IN_USE
Someone is already connected to the server using the name you are trying to connect with...
Definition: connection.h:95
PURPLE_CONNECTION_NO_IMAGES
Connection does not support sending of images.
Definition: connection.h:46
PURPLE_CONNECTION_NO_BGCOLOR
Connection does not send/receive background colors.
Definition: connection.h:39
PURPLE_CONNECTION_SUPPORT_MOODS
Connection supports setting moods.
Definition: connection.h:48
_PurpleConnection::password
char * password
The password used.
Definition: connection.h:253
PURPLE_CONNECTION_ERROR_OTHER_ERROR
Some other error occurred which fits into none of the other categories.
Definition: connection.h:135
PurpleConnectionErrorInfo::description
char * description
A localised, human-readable description of the error.
Definition: connection.h:144