comparison libpurple/connection.h @ 32819:2c6510167895 default tip

propagate from branch 'im.pidgin.pidgin.2.x.y' (head 3315c5dfbd0ad16511bdcf865e5b07c02d07df24) to branch 'im.pidgin.pidgin' (head cbd1eda6bcbf0565ae7766396bb8f6f419cb6a9a)

32818:01ff09d4a463

} PurpleConnectionState;

/**
 * Possible errors that can cause a connection to be closed.
 *
 *  @since 2.3.0
 */
typedef enum
{
	/** There was an error sending or receiving on the network socket, or
	 *  there was some protocol error (such as the server sending malformed

	PURPLE_CONNECTION_ERROR_CERT_OTHER_ERROR = 15,

	/** Some other error occurred which fits into none of the other
	 *  categories.
	 */
	/* purple_connection_error_reason() 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
} PurpleConnectionError;

	 * shipped with libpurple.)
	 */
	void (*notice)(PurpleConnection *gc, const char *text);

	/**
	 * Called when an error causes a connection to be disconnected.
	 * Called before #disconnected.
	 * @param text  a localized error message.
	 * @see #purple_connection_error
	 * @deprecated in favour of
	 *             #PurpleConnectionUiOps.report_disconnect_reason.
	 */
	void (*report_disconnect)(PurpleConnection *gc, const char *text);

	/**
	 * 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.
	 */

	 */
	void (*network_disconnected)(void);

	/**
	 * Called when an error causes a connection to be disconnected.
	 *  Called before #disconnected.  This op is intended to replace
	 *  #report_disconnect.  If both are implemented, this will be called
	 *  first; however, there's no real reason to implement both.
	 *
	 *  @param reason  why the connection ended, if known, or
	 *                 #PURPLE_CONNECTION_ERROR_OTHER_ERROR, if not.
	 *  @param text  a localized message describing the disconnection
	 *               in more detail to the user.
	 *  @see #purple_connection_error_reason
	 *
	 *  @since 2.3.0
	 */
	void (*report_disconnect_reason)(PurpleConnection *gc,
	                                 PurpleConnectionError reason,
	                                 const char *text);

	void (*_purple_reserved1)(void);
	void (*_purple_reserved2)(void);
	void (*_purple_reserved3)(void);
} PurpleConnectionUiOps;

	PurpleConnectionState state;   /**< The connection state.              */

	PurpleAccount *account;        /**< The account being connected to.    */
	char *password;              /**< The password used.                 */
	int inpa;                    /**< The input watcher.                 */

	GSList *buddy_chats;         /**< A list of active chats
	                                  (#PurpleConversation structs of type
	                                  #PURPLE_CONV_TYPE_CHAT).           */
	void *proto_data;            /**< Protocol-specific data.            */

	guint keepalive;             /**< Keep-alive.                        */

	/** Wants to Die state.  This is set when the user chooses to log out, or
	 * when the protocol is disconnected and should not be automatically
	 * reconnected (incorrect password, etc.).  prpls should rely on
	 * purple_connection_error_reason() to set this for them rather than
	 * setting it themselves.
	 * @see purple_connection_error_is_fatal
	 */
	gboolean wants_to_die;

	guint disconnect_timeout;    /**< Timer used for nasty stack tricks  */
	time_t last_received;        /**< When we last received a packet. Set by the
					  prpl to avoid sending unneeded keepalives */
};

#ifdef __cplusplus
extern "C" {
#endif

/**************************************************************************/
/** @name Connection API                                                  */
/**************************************************************************/
/*@{*/

#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_CONNECTION_C_)
/**
 * 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).
 *
 * @param account  The account the connection should be connecting to.
 * @param regist   Whether we are registering a new account or just
 *                 trying to do a normal signon.
 * @param password The password to use.
 *
 * @deprecated As this is internal, we should make it private in 3.0.0.
 */
void purple_connection_new(PurpleAccount *account, gboolean regist,
									const char *password);
#endif

#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_CONNECTION_C_)
/**
 * 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.
 *
 * @param account  The account to unregister
 * @param password The password to use.
 * @param cb Optional callback to be called when unregistration is complete
 * @param user_data user data to pass to the callback
 *
 * @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);
#endif

#if !(defined PURPLE_DISABLE_DEPRECATED) || (defined _PURPLE_CONNECTION_C_)
/**
 * 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.
 *
 * @param gc The purple connection to destroy.
 *
 * @deprecated As this is internal, we should make it private in 3.0.0.
 */
void purple_connection_destroy(PurpleConnection *gc);
#endif

/**
 * 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

 * @param state The connection state.
 */
void purple_connection_set_state(PurpleConnection *gc, PurpleConnectionState state);

/**
 * Sets the connection's account.
 *
 * @param gc      The connection.
 * @param account The account.
 */

/**
 * Sets the protocol data for a connection.
 *
 * @param connection The PurpleConnection.
 * @param proto_data The protocol data to set for the connection.
 *
 * @since 2.6.0
 */
void purple_connection_set_protocol_data(PurpleConnection *connection, void *proto_data);

/**
 * Returns the connection state.

 * @param gc The connection.
 *
 * @return The connection state.
 */
PurpleConnectionState purple_connection_get_state(const PurpleConnection *gc);

/**
 * Returns TRUE if the account is connected, otherwise returns FALSE.
 *
 * @return TRUE if the account is connected, otherwise returns FALSE.

 * Returns the protocol plugin managing a connection.
 *
 * @param gc The connection.
 *
 * @return The protocol plugin.
 *
 * @since 2.4.0
 */
PurplePlugin * purple_connection_get_prpl(const PurpleConnection *gc);

/**
 * Returns the connection's password.

 * Gets the protocol data from a connection.
 *
 * @param connection The PurpleConnection.
 *
 * @return The protocol data for the connection.
 *
 * @since 2.6.0
 */
void *purple_connection_get_protocol_data(const PurpleConnection *connection);

/**
 * Updates the connection progress.

 * @param text The notice text.
 */
void purple_connection_notice(PurpleConnection *gc, const char *text);

/**
 * Closes a connection with an error.
 *
 * @param gc     The connection.
 * @param reason The error text, which may not be @c NULL.
 * @deprecated in favour of #purple_connection_error_reason.  Calling
 *  @c purple_connection_error(gc, text) is equivalent to calling
 *  @c purple_connection_error_reason(gc, reason, text) where @c reason is
 *  #PURPLE_CONNECTION_ERROR_OTHER_ERROR if @c gc->wants_to_die is @c 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.)
 */
void purple_connection_error(PurpleConnection *gc, const char *reason);

/**
 * Closes a connection with an error and a human-readable description of the
 * error.  It also sets @c gc->wants_to_die to the value of
 * #purple_connection_error_is_fatal(@a reason), mainly for
 * backwards-compatibility.
 *
 * @param gc          the connection which is closing.
 * @param reason      why the connection is closing.
 * @param description a non-@c NULL localized description of the error.
 *
 * @since 2.3.0
 */
void
purple_connection_error_reason (PurpleConnection *gc,
                                PurpleConnectionError reason,
                                const char *description);

/**
 * 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_ssl_error (PurpleConnection *gc,
                             PurpleSslErrorType ssl_error);

 *
 * (This function is meant to replace checking PurpleConnection.wants_to_die.)
 *
 * @return @c TRUE if the account should not be automatically reconnected, and
 *         @c FALSE otherwise.
 *
 * @since 2.3.0
 */
gboolean
purple_connection_error_is_fatal (PurpleConnectionError reason);

/*@}*/

/**************************************************************************/
/** @name Connections API                                                 */

void *purple_connections_get_handle(void);

/*@}*/


#ifdef __cplusplus
}
#endif

#endif /* _PURPLE_CONNECTION_H_ */

32819:2c6510167895

} PurpleConnectionState;

/**
 * Possible errors that can cause a connection to be closed.
 */
typedef enum
{
	/** There was an error sending or receiving on the network socket, or
	 *  there was some protocol error (such as the server sending malformed

	PURPLE_CONNECTION_ERROR_CERT_OTHER_ERROR = 15,

	/** Some other error occurred which fits into none of the other
	 *  categories.
	 */
	/* 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
} PurpleConnectionError;

	 * shipped with libpurple.)
	 */
	void (*notice)(PurpleConnection *gc, const char *text);

	/**
	 * 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.
	 */

	 */
	void (*network_disconnected)(void);

	/**
	 * Called when an error causes a connection to be disconnected.
	 * Called before #disconnected.
	 *
	 * @param reason  why the connection ended, if known, or
	 *                #PURPLE_CONNECTION_ERROR_OTHER_ERROR, if not.
	 * @param text  a localized message describing the disconnection
	 *              in more detail to the user.
	 * @see #purple_connection_error
	 */
	void (*report_disconnect)(PurpleConnection *gc,
	                          PurpleConnectionError reason,
	                          const char *text);

	void (*_purple_reserved1)(void);
	void (*_purple_reserved2)(void);
	void (*_purple_reserved3)(void);
} PurpleConnectionUiOps;

	PurpleConnectionState state;   /**< The connection state.              */

	PurpleAccount *account;        /**< The account being connected to.    */
	char *password;              /**< The password used.                 */

	GSList *buddy_chats;         /**< A list of active chats
	                                  (#PurpleConversation structs of type
	                                  #PURPLE_CONV_TYPE_CHAT).           */
	void *proto_data;            /**< Protocol-specific data.            */

	guint keepalive;             /**< Keep-alive.                        */

	/** Wants to Die state.  This is set when the user chooses to log out, or
	 * when the protocol is disconnected and should not be automatically
	 * reconnected (incorrect password, etc.).  prpls should rely on
	 * purple_connection_error() to set this for them rather than
	 * setting it themselves.
	 * @see purple_connection_error_is_fatal
	 */
	gboolean wants_to_die;

	guint disconnect_timeout;    /**< Timer used for nasty stack tricks  */
	time_t last_received;        /**< When we last received a packet. Set by the
					  prpl to avoid sending unneeded keepalives */
};

G_BEGIN_DECLS

/**************************************************************************/
/** @name Connection API                                                  */
/**************************************************************************/
/*@{*/

/**
 * 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

 * @param state The connection state.
 */
void purple_connection_set_state(PurpleConnection *gc, PurpleConnectionState state);

/**
 * Sets the connection flags.
 *
 * @param gc    The connection.
 * @param flags The flags.
 */
void purple_connection_set_flags(PurpleConnection *gc, PurpleConnectionFlags flags);

/**
 * Sets the connection's account.
 *
 * @param gc      The connection.
 * @param account The account.
 */

/**
 * Sets the protocol data for a connection.
 *
 * @param connection The PurpleConnection.
 * @param proto_data The protocol data to set for the connection.
 */
void purple_connection_set_protocol_data(PurpleConnection *connection, void *proto_data);

/**
 * Returns the connection state.

 * @param gc The connection.
 *
 * @return The connection state.
 */
PurpleConnectionState purple_connection_get_state(const PurpleConnection *gc);

/**
 * Returns the connection flags.
 *
 * @param gc The connection.
 *
 * @return The connection flags.
 */
PurpleConnectionFlags purple_connection_get_flags(const PurpleConnection *gc);

/**
 * Returns TRUE if the account is connected, otherwise returns FALSE.
 *
 * @return TRUE if the account is connected, otherwise returns FALSE.

 * Returns the protocol plugin managing a connection.
 *
 * @param gc The connection.
 *
 * @return The protocol plugin.
 */
PurplePlugin * purple_connection_get_prpl(const PurpleConnection *gc);

/**
 * Returns the connection's password.

 * Gets the protocol data from a connection.
 *
 * @param connection The PurpleConnection.
 *
 * @return The protocol data for the connection.
 */
void *purple_connection_get_protocol_data(const PurpleConnection *connection);

/**
 * Updates the connection progress.

 * @param text The notice text.
 */
void purple_connection_notice(PurpleConnection *gc, const char *text);

/**
 * Closes a connection with an error and a human-readable description of the
 * error.  It also sets @c gc->wants_to_die to the value of
 * #purple_connection_error_is_fatal(@a reason), mainly for
 * backwards-compatibility.
 *
 * @param gc          the connection which is closing.
 * @param reason      why the connection is closing.
 * @param description a non-@c NULL localized description of the error.
 */
void
purple_connection_error(PurpleConnection *gc,
                        PurpleConnectionError reason,
                        const char *description);

/**
 * 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().
 */
void
purple_connection_ssl_error (PurpleConnection *gc,
                             PurpleSslErrorType ssl_error);

 *
 * (This function is meant to replace checking PurpleConnection.wants_to_die.)
 *
 * @return @c TRUE if the account should not be automatically reconnected, and
 *         @c FALSE otherwise.
 */
gboolean
purple_connection_error_is_fatal (PurpleConnectionError reason);

/**
 * Indicate that a packet was received on the connection.
 * Set by the prpl to avoid sending unneeded keepalives.
 *
 * @param gc   The connection.
 */
void purple_connection_update_last_received(PurpleConnection *gc);

/*@}*/

/**************************************************************************/
/** @name Connections API                                                 */

void *purple_connections_get_handle(void);

/*@}*/


G_END_DECLS

#endif /* _PURPLE_CONNECTION_H_ */