Fri, 07 Feb 2025 00:14:03 -0600
Replace the Purple.Sqlite3 API with Seagull
Seagull is our new SQLite3 utility library which will be expanded in the near
future.
Testing Done:
Ran in the devenv and built and ran the flatpak as well.
Reviewed at https://reviews.imfreedom.org/r/3821/
/* * Purple - Internet Messaging Library * Copyright (C) Pidgin Developers <devel@pidgin.im> * * 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 library 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 library 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 library; if not, see <https://www.gnu.org/licenses/>. */ #if !defined(PURPLE_GLOBAL_HEADER_INSIDE) && !defined(PURPLE_COMPILATION) # error "only <purple.h> may be included directly" #endif #ifndef PURPLE_CONNECTION_H #define PURPLE_CONNECTION_H #include <glib.h> #include <glib-object.h> #include "purpleversion.h" G_BEGIN_DECLS /** * PurpleConnection: * * Represents an active connection on an account. */ #define PURPLE_TYPE_CONNECTION (purple_connection_get_type()) PURPLE_AVAILABLE_IN_3_0 G_DECLARE_DERIVABLE_TYPE(PurpleConnection, purple_connection, PURPLE, CONNECTION, GObject) /** * PurpleConnectionState: * @PURPLE_CONNECTION_STATE_DISCONNECTED: Disconnected * @PURPLE_CONNECTION_STATE_DISCONNECTING: Disconnecting * @PURPLE_CONNECTION_STATE_CONNECTED: Connected * @PURPLE_CONNECTION_STATE_CONNECTING: Connecting * * A representation of the state of a [class@Purple.Connection]. * * Since: 2.0 */ typedef enum { PURPLE_CONNECTION_STATE_DISCONNECTED PURPLE_AVAILABLE_ENUMERATOR_IN_3_0 = 0, PURPLE_CONNECTION_STATE_DISCONNECTING PURPLE_AVAILABLE_ENUMERATOR_IN_3_0, PURPLE_CONNECTION_STATE_CONNECTED PURPLE_AVAILABLE_ENUMERATOR_IN_3_0, PURPLE_CONNECTION_STATE_CONNECTING PURPLE_AVAILABLE_ENUMERATOR_IN_3_0 } PurpleConnectionState; /** * PURPLE_CONNECTION_ERROR: * * Error domain for Purple connection errors. Errors in this domain will be * from the #PurpleConnectionError enum. * * Since: 3.0 */ #define PURPLE_CONNECTION_ERROR \ g_quark_from_static_string("purple-connection-error") \ PURPLE_AVAILABLE_MACRO_IN_3_0 /** * PurpleConnectionError: * @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. * @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_CUSTOM_TEMPORARY: A custom error that is temporary. * @PURPLE_CONNECTION_ERROR_CUSTOM_FATAL: A custom error that is fatal. * @PURPLE_CONNECTION_ERROR_OTHER_ERROR: Some other error occurred which fits * into none of the other categories. * * Possible errors that can cause a connection to be closed. */ typedef enum { 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, /* TODO This reason really shouldn't be necessary. Usernames and * other account preferences should be validated when the * account is created. */ 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_CUSTOM_TEMPORARY = 16, PURPLE_CONNECTION_ERROR_CUSTOM_FATAL = 17, /* 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 = 18 } PurpleConnectionError; #include "purpleaccount.h" #include "purpleprotocol.h" struct _PurpleConnectionClass { /*< private >*/ GObjectClass parent; gboolean (*connect)(PurpleConnection *connection, GError **error); gboolean (*disconnect)(PurpleConnection *connection, GError **error); /*< private >*/ gpointer reserved[8]; }; /** * purple_connection_connect: * @connection: The instance. * @error: Return address for a #GError, or %NULL. * * Tells the connection to connect. This is done by calling the * [vfunc@Purple.Connection.connect] function. State is managed by this * function. * * Due to the asynchronous nature of network connections, the return value and * @error are to be used to do some initial validation before a connection is * actually attempted. * * Returns: %TRUE if the initial connection for @account was successful, * otherwise %FALSE with @error possibly set. * * Since: 3.0 */ PURPLE_AVAILABLE_IN_3_0 gboolean purple_connection_connect(PurpleConnection *connection, GError **error); /** * purple_connection_disconnect: * @connection: The instance. * @error: Return address for a #GError, or %NULL. * * Tells the connection to disconnect. This is done by calling the * [vfunc@Purple.Connection.disconnect] function. State is managed by this * function. * * Returns: %TRUE if the account was disconnected gracefully, otherwise %FALSE * with @error possibly set. * * Since: 3.0 */ PURPLE_AVAILABLE_IN_3_0 gboolean purple_connection_disconnect(PurpleConnection *connection, GError **error); /** * purple_connection_set_state: * @connection: The connection. * @state: The connection state. * * Sets the connection state. Protocols should call this and pass in * the state #PURPLE_CONNECTION_CONNECTED when the account is completely * signed on. What does it mean to be completely signed on? If * the core can call protocol's set_status, and it successfully changes * your status, then the account is online. * * Since: 2.0 */ PURPLE_DEPRECATED_FOR(purple_account_connected) void purple_connection_set_state(PurpleConnection *connection, PurpleConnectionState state); /** * purple_connection_get_state: * @connection: The connection. * * Gets the connection state. * * Returns: The connection state. * * Since: 2.0 */ PURPLE_AVAILABLE_IN_ALL PurpleConnectionState purple_connection_get_state(PurpleConnection *connection); /** * PURPLE_CONNECTION_IS_CONNECTED: * * Returns TRUE if the account is connected, otherwise returns FALSE. * * Returns: TRUE if the account is connected, otherwise returns FALSE. * * Since: 2.0 */ #define PURPLE_CONNECTION_IS_CONNECTED(connection) \ (purple_connection_get_state(connection) == PURPLE_CONNECTION_STATE_CONNECTED) /** * purple_connection_get_id: * @connection: The connection. * * Gets the identifier of the connection. * * Returns: The identifier of the connection. * * Since: 3.0 */ PURPLE_AVAILABLE_IN_3_0 const gchar *purple_connection_get_id(PurpleConnection *connection); /** * purple_connection_get_account: * @connection: The connection. * * Returns the connection's account. * * Returns: (transfer none): The connection's account. * * Since: 2.0 */ PURPLE_AVAILABLE_IN_ALL PurpleAccount *purple_connection_get_account(PurpleConnection *connection); /** * purple_connection_get_protocol: * @connection: The connection. * * Returns the protocol managing a connection. * * Returns: (transfer none): The protocol. * * Since: 3.0 */ PURPLE_AVAILABLE_IN_3_0 PurpleProtocol *purple_connection_get_protocol(PurpleConnection *connection); /** * purple_connection_get_password: * @connection: The connection. * * Returns the connection's password. * * Returns: The connection's password. * * Since: 2.0 */ PURPLE_AVAILABLE_IN_ALL const char *purple_connection_get_password(PurpleConnection *connection); /** * purple_connection_set_password: * @connection: The instance. * @password: (nullable): The new password. * * Sets the password for @connection to @password. * * This will not change your password on the remote service. It just updates * the password that the protocol should use when connecting. * * This is generally used by protocol plugins that support multiple * authentication methods and need to prompt the user for a password. * * Since: 3.0 */ PURPLE_AVAILABLE_IN_3_0 void purple_connection_set_password(PurpleConnection *connection, const char *password); /** * purple_connection_get_cancellable: * @connection: The instance. * * Gets the cancellable that should be used with @connection. * * Returns: (transfer none): The cancellable. * * Since: 3.0 */ PURPLE_AVAILABLE_IN_3_0 GCancellable *purple_connection_get_cancellable(PurpleConnection *connection); /** * purple_connection_error_is_fatal: * @reason: The connection error to check. * * 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 <code> * purple_connection_error_is_fatal(PURPLE_CONNECTION_ERROR_NETWORK_ERROR) * </code> 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 <code> * purple_connection_error_is_fatal(PURPLE_CONNECTION_ERROR_AUTHENTICATION_FAILED) * </code> is %TRUE. * * Returns: %TRUE if the account should not be automatically reconnected, and * %FALSE otherwise. * * Since: 2.0 */ PURPLE_AVAILABLE_IN_ALL gboolean purple_connection_error_is_fatal(PurpleConnectionError reason); G_END_DECLS #endif /* PURPLE_CONNECTION_H */