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@gnupg.org>

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