GpgFrontend/gpgme
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

core: Explain in gpgme.h that most stucts are read-only.

Browse Source 
--

It is common that developers look up only the header file and do not
read the manual.  These comments should make it clear that most
structures in gpgme.h are read-only and may only be allocated by
gpgme.

Signed-off-by: Werner Koch <wk@gnupg.org>
This commit is contained in:
Werner Koch 2017-02-02 10:13:36 +01:00
parent d19bea52af
commit 0ceeb2948c
No known key found for this signature in database
GPG Key ID: E3FDFF218E45B72B
1 changed files with 70 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

80
src/gpgme.h.in
View File

@ -394,6 +394,9 @@ typedef unsigned int gpgme_export_mode_t;
typedef unsigned int gpgme_sig_notation_flags_t;
/* An object to hold information about notation data. This structure
* shall be considered read-only and an application must not allocate
* such a structure on its own. */
struct _gpgme_sig_notation
{
struct _gpgme_sig_notation *next;
@ -431,7 +434,9 @@ typedef struct _gpgme_sig_notation *gpgme_sig_notation_t;
* Public structures.
*/
/* The engine information structure. */
/* The engine information structure.
* This structure shall be considered read-only and an application
* must not allocate such a structure on its own. */
struct _gpgme_engine_info
{
struct _gpgme_engine_info *next;
@ -454,7 +459,9 @@ struct _gpgme_engine_info
typedef struct _gpgme_engine_info *gpgme_engine_info_t;
/* An object with TOFU information. */
/* An object with TOFU information.
* This structure shall be considered read-only and an application
* must not allocate such a structure on its own. */
struct _gpgme_tofu_info
{
struct _gpgme_tofu_info *next;
@ -491,7 +498,9 @@ struct _gpgme_tofu_info
typedef struct _gpgme_tofu_info *gpgme_tofu_info_t;
/* A subkey from a key. */
/* A subkey from a key.
* This structure shall be considered read-only and an application
* must not allocate such a structure on its own. */
struct _gpgme_subkey
{
struct _gpgme_subkey *next;
@ -565,7 +574,9 @@ struct _gpgme_subkey
typedef struct _gpgme_subkey *gpgme_subkey_t;
/* A signature on a user ID. */
/* A signature on a user ID.
* This structure shall be considered read-only and an application
* must not allocate such a structure on its own. */
struct _gpgme_key_sig
{
struct _gpgme_key_sig *next;
@ -634,7 +645,9 @@ struct _gpgme_key_sig
typedef struct _gpgme_key_sig *gpgme_key_sig_t;
/* An user ID from a key. */
/* An user ID from a key.
* This structure shall be considered read-only and an application
* must not allocate such a structure on its own. */
struct _gpgme_user_id
{
struct _gpgme_user_id *next;
@ -681,7 +694,9 @@ struct _gpgme_user_id
typedef struct _gpgme_user_id *gpgme_user_id_t;
/* A key from the keyring. */
/* A key from the keyring.
* This structure shall be considered read-only and an application
* must not allocate such a structure on its own. */
struct _gpgme_key
{
/* Internal to GPGME, do not use. */
@ -762,7 +777,9 @@ struct _gpgme_key
typedef struct _gpgme_key *gpgme_key_t;
/* An invalid key object. */
/* An invalid key object.
* This structure shall be considered read-only and an application
* must not allocate such a structure on its own. */
struct _gpgme_invalid_key
{
struct _gpgme_invalid_key *next;
@ -1196,6 +1213,9 @@ void gpgme_key_release (gpgme_key_t key);
* Encryption.
*/
/* An object to return results from an encryption operation.
* This structure shall be considered read-only and an application
* must not allocate such a structure on its own. */
struct _gpgme_op_encrypt_result
{
/* The list of invalid recipients. */
@ -1244,6 +1264,9 @@ gpgme_error_t gpgme_op_encrypt_sign (gpgme_ctx_t ctx, gpgme_key_t recp[],
* Decryption.
*/
/* An object to hold information about a recipient.
* This structure shall be considered read-only and an application
* must not allocate such a structure on its own. */
struct _gpgme_recipient
{
struct _gpgme_recipient *next;
@ -1262,6 +1285,9 @@ struct _gpgme_recipient
};
typedef struct _gpgme_recipient *gpgme_recipient_t;
/* An object to return results from a decryption operation.
* This structure shall be considered read-only and an application
* must not allocate such a structure on its own. */
struct _gpgme_op_decrypt_result
{
char *unsupported_algorithm;
@ -1307,6 +1333,9 @@ gpgme_error_t gpgme_op_decrypt_verify (gpgme_ctx_t ctx, gpgme_data_t cipher,
* Signing.
*/
/* An object with signatures data.
* This structure shall be considered read-only and an application
* must not allocate such a structure on its own. */
struct _gpgme_new_signature
{
struct _gpgme_new_signature *next;
@ -1342,6 +1371,10 @@ struct _gpgme_new_signature
};
typedef struct _gpgme_new_signature *gpgme_new_signature_t;
/* An object to return results from a signing operation.
* This structure shall be considered read-only and an application
* must not allocate such a structure on its own. */
struct _gpgme_op_sign_result
{
/* The list of invalid signers. */
@ -1385,6 +1418,9 @@ typedef enum
gpgme_sigsum_t;
/* An object to hold the verification status of a signature.
* This structure shall be considered read-only and an application
* must not allocate such a structure on its own. */
struct _gpgme_signature
{
struct _gpgme_signature *next;
@ -1437,6 +1473,9 @@ struct _gpgme_signature
};
typedef struct _gpgme_signature *gpgme_signature_t;
/* An object to return the results of a verify operation.
* This structure shall be considered read-only and an application
* must not allocate such a structure on its own. */
struct _gpgme_op_verify_result
{
gpgme_signature_t signatures;
@ -1470,6 +1509,9 @@ gpgme_error_t gpgme_op_verify (gpgme_ctx_t ctx, gpgme_data_t sig,
#define GPGME_IMPORT_SECRET 16 /* The key contained a secret key. */
/* An object to hold results for one imported key.
* This structure shall be considered read-only and an application
* must not allocate such a structure on its own. */
struct _gpgme_import_status
{
struct _gpgme_import_status *next;
@ -1488,7 +1530,9 @@ struct _gpgme_import_status
};
typedef struct _gpgme_import_status *gpgme_import_status_t;
/* Import result object. */
/* Import result object.
* This structure shall be considered read-only and an application
* must not allocate such a structure on its own. */
struct _gpgme_op_import_result
{
/* Number of considered keys. */
@ -1594,6 +1638,9 @@ gpgme_error_t gpgme_op_export_keys (gpgme_ctx_t ctx,
#define GPGME_CREATE_WANTSEC (1 << 11) /* Return the secret key. */
#define GPGME_CREATE_FORCE (1 << 12) /* Force creation. */
/* An object to return result from a key generation.
* This structure shall be considered read-only and an application
* must not allocate such a structure on its own. */
struct _gpgme_op_genkey_result
{
/* A primary key was generated. */
@ -1750,6 +1797,9 @@ gpgme_error_t gpgme_op_tofu_policy (gpgme_ctx_t ctx,
* Key listing
*/
/* An object to return results from a key listing operation.
* This structure shall be considered read-only and an application
* must not allocate such a structure on its own. */
struct _gpgme_op_keylist_result
{
unsigned int truncated : 1;
@ -1790,6 +1840,9 @@ gpgme_error_t gpgme_op_passwd (gpgme_ctx_t ctx, gpgme_key_t key,
* Trust items and operations.
*/
/* An object to hold data of a trust item.
* This structure shall be considered read-only and an application
* must not allocate such a structure on its own. */
struct _gpgme_trust_item
{
/* Internal to GPGME, do not use. */
@ -1924,6 +1977,9 @@ gpgme_error_t gpgme_op_assuan_transact_ext (gpgme_ctx_t ctx,
* Crypto container support.
*/
/* An object to return results from a VFS mount operation.
* This structure shall be considered read-only and an application
* must not allocate such a structure on its own. */
struct _gpgme_op_vfs_mount_result
{
char *mount_dir;
@ -2112,7 +2168,9 @@ gpgme_error_t gpgme_op_conf_load (gpgme_ctx_t ctx, gpgme_conf_comp_t *conf_p);
gpgme_error_t gpgme_op_conf_save (gpgme_ctx_t ctx, gpgme_conf_comp_t comp);
/* Information about software versions. */
/* Information about software versions.
* This structure shall be considered read-only and an application
* must not allocate such a structure on its own. */
typedef struct _gpgme_op_query_swdb_result
{
/* RFU */
@ -2528,7 +2586,9 @@ int gpgme_trust_item_get_int_attr (gpgme_trust_item_t item, _gpgme_attr_t what,
const void *reserved, int idx)
_GPGME_DEPRECATED(0,4);
/* Compat. */
/* Compat.
* This structure shall be considered read-only and an application
* must not allocate such a structure on its own. */
struct _gpgme_op_assuan_result
{
/* Deprecated. Use the second value in a DONE event or the