From 0ceeb2948c7210f120e5ddda1ca20a4bbbf83378 Mon Sep 17 00:00:00 2001 From: Werner Koch Date: Thu, 2 Feb 2017 10:13:36 +0100 Subject: [PATCH] core: Explain in gpgme.h that most stucts are read-only. -- 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 --- src/gpgme.h.in | 80 +++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 70 insertions(+), 10 deletions(-) diff --git a/src/gpgme.h.in b/src/gpgme.h.in index 769c2c85..67c139be 100644 --- a/src/gpgme.h.in +++ b/src/gpgme.h.in @@ -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