[Pkg-gnupg-commit] [gpgme] 48/132: core: Explain in gpgme.h that most stucts are read-only.
Daniel Kahn Gillmor
dkg at fifthhorseman.net
Wed Apr 26 01:01:21 UTC 2017
This is an automated email from the git hooks/post-receive script.
dkg pushed a commit to branch experimental
in repository gpgme.
commit 0ceeb2948c7210f120e5ddda1ca20a4bbbf83378
Author: Werner Koch <wk at gnupg.org>
Date: Thu Feb 2 10:13:36 2017 +0100
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 <wk at gnupg.org>
---
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 769c2c8..67c139b 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
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-gnupg/gpgme.git
More information about the Pkg-gnupg-commit
mailing list