pidgin/pidgin
Clone
Summary
Browse
Changes
Graph
Add description to PurpleProtocol
2021-07-13, Prateek Pardeshi
ddc26be7f597
Add description to PurpleProtocol
Testing Done:
Ran and tested on the Account Assistant, which I'm developing currently.
![](https://i.ibb.co/bsVHdJv/Screenshot-from-2021-07-12-11-13-55.png)
Bugs closed: PIDGIN-17460
Reviewed at https://reviews.imfreedom.org/r/803/
/*
* Purple - Internet Messaging Library
* Copyright (C) Pidgin Developers <devel@pidgin.im>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser 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
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser 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_CREDENTIAL_PROVIDER_H
#define PURPLE_CREDENTIAL_PROVIDER_H
#include
<glib.h>
#include
<glib-object.h>
#include
"account.h"
#include
"request.h"
/**
* SECTION:purplecredentialprovider
* @section_id: libpurple-purplecredentialprovider
* @title: Credential Provider Object
*/
G_BEGIN_DECLS
/**
* PURPLE_CREDENTIAL_PROVIDER_DOMAIN:
*
* A #GError domain for errors from #PurpleCredentialProviders.
*
* Since: 3.0.0
*/
#define PURPLE_CREDENTIAL_PROVIDER_DOMAIN (g_quark_from_static_string("purple-credential-provider"))
/**
* PurpleCredentialProvider:
*
* #PurpleCredentialProvider is a base class that should be sub classed by
* credential providers. It defines the behavior of all credential providers
* and implements some shared properties.
*
* Since: 3.0.0
*/
#define PURPLE_TYPE_CREDENTIAL_PROVIDER (purple_credential_provider_get_type())
G_DECLARE_DERIVABLE_TYPE
(
PurpleCredentialProvider
,
purple_credential_provider
,
PURPLE
,
CREDENTIAL_PROVIDER
,
GObject
)
/**
* PurpleCredentialProviderClass:
* @activate: Called when the provider is made active.
* @deactivate: Called when another provider has been made active.
* @read_password_async: Reads a password from the provider.
* @read_password_finish: Finishes reading a password.
* @write_password_async: Writes a password to the provider.
* @write_password_finish: Finishes writing a password.
* @clear_password_async: Clears a password from the provider.
* @clear_password_finish: Finishes clearing a password from the provider.
* @read_settings: Creates a #PurpleRequestFields for the available settings.
* @write_settings: Updates the settings for provider.
*
* #PurpleCredentialProviderClass defines the interface for interacting with
* credential providers like libsecret, kwallet, etc.
*
* Since: 3.0.0
*/
struct
_PurpleCredentialProviderClass
{
/*< private >*/
GObjectClass
parent
;
/*< public >*/
void
(
*
activate
)(
PurpleCredentialProvider
*
provider
);
void
(
*
deactivate
)(
PurpleCredentialProvider
*
provider
);
void
(
*
read_password_async
)(
PurpleCredentialProvider
*
provider
,
PurpleAccount
*
account
,
GCancellable
*
cancellable
,
GAsyncReadyCallback
callback
,
gpointer
data
);
gchar
*
(
*
read_password_finish
)(
PurpleCredentialProvider
*
provider
,
GAsyncResult
*
result
,
GError
**
error
);
void
(
*
write_password_async
)(
PurpleCredentialProvider
*
provider
,
PurpleAccount
*
account
,
const
gchar
*
password
,
GCancellable
*
cancellable
,
GAsyncReadyCallback
callback
,
gpointer
data
);
gboolean
(
*
write_password_finish
)(
PurpleCredentialProvider
*
provider
,
GAsyncResult
*
result
,
GError
**
error
);
void
(
*
clear_password_async
)(
PurpleCredentialProvider
*
provider
,
PurpleAccount
*
account
,
GCancellable
*
cancellable
,
GAsyncReadyCallback
callback
,
gpointer
data
);
gboolean
(
*
clear_password_finish
)(
PurpleCredentialProvider
*
provider
,
GAsyncResult
*
result
,
GError
**
error
);
PurpleRequestFields
*
(
*
read_settings
)(
PurpleCredentialProvider
*
provider
);
gboolean
(
*
write_settings
)(
PurpleCredentialProvider
*
provider
,
PurpleRequestFields
*
fields
);
/*< private >*/
/* Some extra padding to play it safe. */
gpointer
reserved
[
8
];
};
/**
* purple_credential_provider_get_id:
* @provider: The #PurpleCredentialProvider instance.
*
* Gets the identifier of @provider.
*
* Returns: The identifier of @provider.
*
* Since: 3.0.0
*/
const
gchar
*
purple_credential_provider_get_id
(
PurpleCredentialProvider
*
provider
);
/**
* purple_credential_provider_get_name:
* @provider: The #PurpleCredentialProvider instance.
*
* Gets the name of @provider which can be show in user interfaces.
*
* Returns: The name of @provider.
*
* Since: 3.0.0
*/
const
gchar
*
purple_credential_provider_get_name
(
PurpleCredentialProvider
*
provider
);
/**
* purple_credential_provider_get_description:
* @provider: The #PurpleCredentialProvider instance.
*
* Gets the description of @provider which can be displayed in user interfaces
* to help users figure out which provider to use.
*
* Returns: The description of @provider.
*
* Since: 3.0.0
*/
const
gchar
*
purple_credential_provider_get_description
(
PurpleCredentialProvider
*
provider
);
/**
* purple_credential_provider_is_valid:
* @provider: The #PurpleCredentialProvider instance.
* @error: (out) (optional) (nullable): Return address for a #GError.
*
* Checks whether or not @provider is setup correctly. This is primarily meant
* for #purple_credential_provider_register_provider to call to avoid
* programming errors, but can be used by anyone.
*
* Returns: %FALSE on error, otherwise %TRUE.
*
* Since: 3.0.0
*/
gboolean
purple_credential_provider_is_valid
(
PurpleCredentialProvider
*
provider
,
GError
**
error
);
/**
* purple_credential_provider_read_password_async:
* @provider: The #PurpleCredentialProvider instance.
* @account: The #PurpleAccount whose password to read.
* @cancellable: (nullable): optional GCancellable object, %NULL to ignore.
* @callback: (scope async): a #GAsyncReadyCallback to call when the request is
* satisfied.
* @data: User data to pass to @callback.
*
* Reads the password for @account from @provider.
*
* Since: 3.0.0
*/
void
purple_credential_provider_read_password_async
(
PurpleCredentialProvider
*
provider
,
PurpleAccount
*
account
,
GCancellable
*
cancellable
,
GAsyncReadyCallback
callback
,
gpointer
data
);
/**
* purple_credential_provider_read_password_finish:
* @provider: The #PurpleCredentialProvider instance.
* @result: The #GAsyncResult from the previous
* purple_credential_provider_read_password_async() call.
* @error: (out) (optional) (nullable): Return address for a #GError.
*
* Finishes a previous call to purple_credential_provider_read_password_async().
*
* Returns: (transfer full): The password or %NULL if successful, otherwise
* %NULL with @error set on failure.
*
* Since: 3.0.0
*/
gchar
*
purple_credential_provider_read_password_finish
(
PurpleCredentialProvider
*
provider
,
GAsyncResult
*
result
,
GError
**
error
);
/**
* purple_credential_provider_write_password_async:
* @provider: The #PurpleCredentialProvider instance.
* @account: The #PurpleAccount whose password to write.
* @password: The password to write.
* @cancellable: (nullable): optional GCancellable object, %NULL to ignore.
* @callback: (scope async): a #GAsyncReadyCallback to call when the request is
* satisfied.
* @data: User data to pass to @callback.
*
* Writes @password for @account to @provider.
*
* Since: 3.0.0
*/
void
purple_credential_provider_write_password_async
(
PurpleCredentialProvider
*
provider
,
PurpleAccount
*
account
,
const
gchar
*
password
,
GCancellable
*
cancellable
,
GAsyncReadyCallback
callback
,
gpointer
data
);
/**
* purple_credential_provider_write_password_finish:
* @provider: The #PurpleCredentialProvider instance.
* @result: The #GAsyncResult from the previous
* purple_credential_provider_write_password_async() call.
* @error: (out) (optional) (nullable): Return address for a #GError.
*
* Finishes a previous call to
* purple_credential_provider_write_password_async().
*
* Returns: %TRUE if the password was written successfully, otherwise %FALSE
* with @error set.
*
* Since: 3.0.0
*/
gboolean
purple_credential_provider_write_password_finish
(
PurpleCredentialProvider
*
provider
,
GAsyncResult
*
result
,
GError
**
error
);
/**
* purple_credential_provider_clear_password_async:
* @provider: The #PurpleCredentialProvider instance.
* @account: The #PurpleAccount whose password to clear.
* @cancellable: (nullable): optional #GCancellable object, or %NULL to ignore.
* @callback: (scope async): a #GAsyncReadyCallback to call when the request is
* satisfied.
* @data: User data to pass to @callback.
*
* Clears the password for @account from @provider.
*
* Since: 3.0.0
*/
void
purple_credential_provider_clear_password_async
(
PurpleCredentialProvider
*
provider
,
PurpleAccount
*
account
,
GCancellable
*
cancellable
,
GAsyncReadyCallback
callback
,
gpointer
data
);
/**
* purple_credential_provider_clear_password_finish:
* @provider: The #PurpleCredentialProvider instance.
* @result: The #GAsyncResult from the previous
* purple_credential_provider_clear_password_async() call.
* @error: (out) (optional) (nullable): Return address for a #GError.
*
* Finishes a previous call to
* purple_credential_provider_clear_password_async().
*
* Returns: %TRUE if the password was cleared successfully, otherwise %FALSE
* with @error set.
*
* Since: 3.0.0
*/
gboolean
purple_credential_provider_clear_password_finish
(
PurpleCredentialProvider
*
provider
,
GAsyncResult
*
result
,
GError
**
error
);
/**
* purple_credential_provider_read_settings:
* @provider: The #PurpleCredentialProvider instance.
*
* Reads settings from @provider.
*
* Returns: (transfer full): New copy of current settings which must be free'd
* with purple_request_fields_destroy().
*
* Since: 3.0.0
*/
PurpleRequestFields
*
purple_credential_provider_read_settings
(
PurpleCredentialProvider
*
provider
);
/**
* purple_credential_provider_write_settings:
* @provider: The #PurpleCredentialProvider instance.
* @fields: Modified settings from purple_credential_provider_read_settings().
*
* Write @fields to @provider.
*
* Returns: %TRUE if successful, %FALSE otherwise.
*
* Since: 3.0.0
*/
gboolean
purple_credential_provider_write_settings
(
PurpleCredentialProvider
*
provider
,
PurpleRequestFields
*
fields
);
G_END_DECLS
#endif
/* PURPLE_CREDENTIAL_PROVIDER */