comparison libpurple/connection.h @ 20893:c521b0f72a7b

Add "@since 2.3.0" annotations to the new API, as advocated by rlaager.

20892:bbcc9e206c43

	PURPLE_CONNECTED,        /**< Connected.    */
	PURPLE_CONNECTING        /**< Connecting.   */

} 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
	 *  data).

	 *  @param reason  why the connection ended, if known, or
	 *                 #PURPLE_REASON_OTHER_ERROR, if not.
	 *  @param text  a localized message describing the disconnection
	 *               in more detail to the user.
	 *  @see #purple_connection_error_reason
	 */
	void (*report_disconnect_reason)(PurpleConnection *gc,
	                                 PurpleDisconnectReason reason,
	                                 const char *text);

 * error.  It also sets @c gc->wants_to_die to the value of
 * #purple_connection_reason_is_fatal(@a reason).
 *
 * @param reason      why the connection is closing.
 * @param description a localized description of the error.
 */
void
purple_connection_error_reason (PurpleConnection *gc,
                                PurpleDisconnectReason reason,
                                const char *description);

/**
 * Closes a connection due to an SSL error; this is basically a shortcut to
 * turning the #PurpleSslErrorType into a #PurpleDisconnectReason and a
 * human-readable string and then calling purple_connection_error_reason().
 */
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_reason_is_fatal (PurpleDisconnectReason reason);

/*@}*/

20893:c521b0f72a7b

	PURPLE_CONNECTED,        /**< Connected.    */
	PURPLE_CONNECTING        /**< Connecting.   */

} 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
	 *  data).

	 *  @param reason  why the connection ended, if known, or
	 *                 #PURPLE_REASON_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,
	                                 PurpleDisconnectReason reason,
	                                 const char *text);

 * error.  It also sets @c gc->wants_to_die to the value of
 * #purple_connection_reason_is_fatal(@a reason).
 *
 * @param reason      why the connection is closing.
 * @param description a localized description of the error.
 * @since 2.3.0
 */
void
purple_connection_error_reason (PurpleConnection *gc,
                                PurpleDisconnectReason reason,
                                const char *description);

/**
 * Closes a connection due to an SSL error; this is basically a shortcut to
 * turning the #PurpleSslErrorType into a #PurpleDisconnectReason 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_reason_is_fatal (PurpleDisconnectReason reason);

/*@}*/