connection.h File Reference

Connection API

purple. More...

#include <time.h>
#include "account.h"
#include "plugin.h"
#include "status.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  PurpleConnectionUiOps
 Connection UI operations. More...
struct  _PurpleConnection

Connection API

#define PURPLE_CONNECTION_IS_CONNECTED(gc)   (gc->state == 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_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.
PurpleConnectionState purple_connection_get_state (const PurpleConnection *gc)
 Returns the connection state.
PurpleAccount * purple_connection_get_account (const PurpleConnection *gc)
 Returns the connection's account.
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_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.

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.

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.

Typedefs

typedef _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
}
 Flags to change behavior of the client for a given connection. More...
enum  PurpleConnectionState { PURPLE_DISCONNECTED = 0, PURPLE_CONNECTED, PURPLE_CONNECTING }


Detailed Description

Connection API

purple.

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 source distribution.

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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

See also:
Connection Signals

Define Documentation

#define PURPLE_CONNECTION_IS_CONNECTED gc   )     (gc->state == PURPLE_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_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.


Enumeration Type Documentation

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.

enum PurpleConnectionState
 

Enumerator:
PURPLE_DISCONNECTED  Disconnected.
PURPLE_CONNECTED  Connected.
PURPLE_CONNECTING  Connecting.


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:
gc The purple connection to destroy.

void purple_connection_error PurpleConnection *  gc,
const char *  reason
 

Closes a connection with an error.

Parameters:
gc The connection.
reason The error text.

PurpleAccount* purple_connection_get_account const PurpleConnection *  gc  ) 
 

Returns the connection's account.

Parameters:
gc The connection.
Returns:
The connection's account.

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.

const char* purple_connection_get_password const PurpleConnection *  gc  ) 
 

Returns the connection's password.

Parameters:
gc The connection.
Returns:
The connection's password.

PurpleConnectionState purple_connection_get_state const PurpleConnection *  gc  ) 
 

Returns the connection state.

Parameters:
gc The 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:
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.

void purple_connection_notice PurpleConnection *  gc,
const char *  text
 

Displays a connection-specific notice.

Parameters:
gc The connection.
text The notice text.

void purple_connection_set_account PurpleConnection *  gc,
PurpleAccount *  account
 

Sets the connection's account.

Parameters:
gc The connection.
account The account.

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.

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.

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.

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.

A list of all active connections.

GList* purple_connections_get_connecting void   ) 
 

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

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:
ops The UI operations structure.