doc: Fix documentation of struct data types
[gpgme.git] / src / gpgme.h.in
index dad8d94..5c4de6b 100644 (file)
@@ -1,7 +1,7 @@
 /* gpgme.h - Public interface to GnuPG Made Easy.                   -*- c -*-
    Copyright (C) 2000 Werner Koch (dd9jn)
    Copyright (C) 2001, 2002, 2003, 2004, 2005, 2007, 2009
-                 2010 g10 Code GmbH
+                 2010, 2011, 2012, 2013 g10 Code GmbH
 
    This file is part of GPGME.
 
@@ -18,7 +18,7 @@
    You should have received a copy of the GNU Lesser General Public
    License along with this program; if not, see <http://www.gnu.org/licenses/>.
 
-   File: @configure_input@  */
+   Generated from gpgme.h.in for @GPGME_CONFIG_HOST@.  */
 
 #ifndef GPGME_H
 #define GPGME_H
 
 /* Include stdio.h for the FILE type definition.  */
 #include <stdio.h>
-
-@INSERT__TYPEDEFS_FOR_GPGME_H@
-
 #include <time.h>
-
 #include <gpg-error.h>
 
 #ifdef __cplusplus
@@ -47,6 +43,7 @@ extern "C" {
 #endif
 #endif /* __cplusplus */
 
+@INSERT__TYPEDEFS_FOR_GPGME_H@
 
 \f
 /* Check for compiler features.  */
@@ -80,6 +77,10 @@ extern "C" {
    library.  */
 #define GPGME_VERSION "@PACKAGE_VERSION@"
 
+/* The version number of this header.  It may be used to handle minor
+   API incompatibilities.  */
+#define GPGME_VERSION_NUMBER @VERSION_NUMBER@
+
 /* Check for a matching _FILE_OFFSET_BITS definition.  */
 #if @NEED__FILE_OFFSET_BITS@
 #ifndef _FILE_OFFSET_BITS
@@ -95,7 +96,7 @@ extern "C" {
 \f
 /* Some opaque data types used by GPGME.  */
 
-/* The context holds some global state and configration options, as
+/* The context holds some global state and configuration options, as
    well as the results of a crypto operation.  */
 struct gpgme_context;
 typedef struct gpgme_context *gpgme_ctx_t;
@@ -209,6 +210,22 @@ typedef enum
   }
 gpgme_data_encoding_t;
 
+/* Known data types.  */
+typedef enum
+  {
+    GPGME_DATA_TYPE_INVALID      = 0,   /* Not detected.  */
+    GPGME_DATA_TYPE_UNKNOWN      = 1,
+    GPGME_DATA_TYPE_PGP_SIGNED   = 0x10,
+    GPGME_DATA_TYPE_PGP_OTHER    = 0x12,
+    GPGME_DATA_TYPE_PGP_KEY      = 0x13,
+    GPGME_DATA_TYPE_CMS_SIGNED   = 0x20,
+    GPGME_DATA_TYPE_CMS_ENCRYPTED= 0x21,
+    GPGME_DATA_TYPE_CMS_OTHER    = 0x22,
+    GPGME_DATA_TYPE_X509_CERT    = 0x23,
+    GPGME_DATA_TYPE_PKCS12       = 0x24,
+  }
+gpgme_data_type_t;
+
 \f
 /* Public key algorithms from libgcrypt.  */
 typedef enum
@@ -341,6 +358,8 @@ typedef enum
     GPGME_PROTOCOL_UNKNOWN = 255
   }
 gpgme_protocol_t;
+/* Convenience macro for the surprisingly mixed spelling.  */
+#define GPGME_PROTOCOL_OPENPGP GPGME_PROTOCOL_OpenPGP
 
 \f
 /* The available keylist mode flags.  */
@@ -354,6 +373,18 @@ gpgme_protocol_t;
 typedef unsigned int gpgme_keylist_mode_t;
 
 \f
+/* The pinentry modes. */
+typedef enum
+  {
+    GPGME_PINENTRY_MODE_DEFAULT  = 0,
+    GPGME_PINENTRY_MODE_ASK      = 1,
+    GPGME_PINENTRY_MODE_CANCEL   = 2,
+    GPGME_PINENTRY_MODE_ERROR    = 3,
+    GPGME_PINENTRY_MODE_LOOPBACK = 4
+  }
+gpgme_pinentry_mode_t;
+
+\f
 /* The available export mode flags.  */
 #define GPGME_EXPORT_MODE_EXTERN                2
 #define GPGME_EXPORT_MODE_MINIMAL               4
@@ -859,6 +890,13 @@ gpgme_error_t gpgme_set_keylist_mode (gpgme_ctx_t ctx,
 /* Get keylist mode in CTX.  */
 gpgme_keylist_mode_t gpgme_get_keylist_mode (gpgme_ctx_t ctx);
 
+/* Set the pinentry mode for CTX to MODE. */
+gpgme_error_t gpgme_set_pinentry_mode (gpgme_ctx_t ctx,
+                                       gpgme_pinentry_mode_t mode);
+
+/* Get the pinentry mode of CTX.  */
+gpgme_pinentry_mode_t gpgme_get_pinentry_mode (gpgme_ctx_t ctx);
+
 /* Set the passphrase callback function in CTX to CB.  HOOK_VALUE is
    passed as first argument to the passphrase callback function.  */
 void gpgme_set_passphrase_cb (gpgme_ctx_t ctx,
@@ -912,6 +950,9 @@ void gpgme_signers_clear (gpgme_ctx_t ctx);
 /* Add KEY to list of signers in CTX.  */
 gpgme_error_t gpgme_signers_add (gpgme_ctx_t ctx, const gpgme_key_t key);
 
+/* Return the number of signers in CTX.  */
+unsigned int gpgme_signers_count (const gpgme_ctx_t ctx);
+
 /* Return the SEQth signer's key in CTX.  */
 gpgme_key_t gpgme_signers_enum (const gpgme_ctx_t ctx, int seq);
 
@@ -1020,8 +1061,9 @@ void gpgme_get_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
 
 /* Wrappers around the internal I/O functions for use with
    gpgme_passphrase_cb_t and gpgme_edit_cb_t.  */
-ssize_t gpgme_io_read (int fd, void *buffer, size_t count);
-ssize_t gpgme_io_write (int fd, const void *buffer, size_t count);
+@API__SSIZE_T@ gpgme_io_read (int fd, void *buffer, size_t count);
+@API__SSIZE_T@ gpgme_io_write (int fd, const void *buffer, size_t count);
+int     gpgme_io_writen (int fd, const void *buffer, size_t count);
 
 /* Process the pending operation and, if HANG is non-zero, wait for
    the pending operation to finish.  */
@@ -1036,19 +1078,20 @@ gpgme_ctx_t gpgme_wait_ext (gpgme_ctx_t ctx, gpgme_error_t *status,
 /* Read up to SIZE bytes into buffer BUFFER from the data object with
    the handle HANDLE.  Return the number of characters read, 0 on EOF
    and -1 on error.  If an error occurs, errno is set.  */
-typedef ssize_t (*gpgme_data_read_cb_t) (void *handle, void *buffer,
+typedef @API__SSIZE_T@ (*gpgme_data_read_cb_t) (void *handle, void *buffer,
                                         size_t size);
 
 /* Write up to SIZE bytes from buffer BUFFER to the data object with
    the handle HANDLE.  Return the number of characters written, or -1
    on error.  If an error occurs, errno is set.  */
-typedef ssize_t (*gpgme_data_write_cb_t) (void *handle, const void *buffer,
+typedef @API__SSIZE_T@ (*gpgme_data_write_cb_t) (void *handle, const void *buffer,
                                          size_t size);
 
 /* Set the current position from where the next read or write starts
    in the data object with the handle HANDLE to OFFSET, relativ to
    WHENCE.  */
-typedef off_t (*gpgme_data_seek_cb_t) (void *handle, off_t offset, int whence);
+typedef @API__OFF_T@ (*gpgme_data_seek_cb_t) (void *handle,
+                                       @API__OFF_T@ offset, int whence);
 
 /* Close the data object with the handle DL.  */
 typedef void (*gpgme_data_release_cb_t) (void *handle);
@@ -1065,17 +1108,17 @@ typedef struct gpgme_data_cbs *gpgme_data_cbs_t;
 /* Read up to SIZE bytes into buffer BUFFER from the data object with
    the handle DH.  Return the number of characters read, 0 on EOF and
    -1 on error.  If an error occurs, errno is set.  */
-ssize_t gpgme_data_read (gpgme_data_t dh, void *buffer, size_t size);
+@API__SSIZE_T@ gpgme_data_read (gpgme_data_t dh, void *buffer, size_t size);
 
 /* Write up to SIZE bytes from buffer BUFFER to the data object with
    the handle DH.  Return the number of characters written, or -1 on
    error.  If an error occurs, errno is set.  */
-ssize_t gpgme_data_write (gpgme_data_t dh, const void *buffer, size_t size);
+@API__SSIZE_T@ gpgme_data_write (gpgme_data_t dh, const void *buffer, size_t size);
 
 /* Set the current position from where the next read or write starts
    in the data object with the handle DH to OFFSET, relativ to
    WHENCE.  */
-off_t gpgme_data_seek (gpgme_data_t dh, off_t offset, int whence);
+@API__OFF_T@ gpgme_data_seek (gpgme_data_t dh, @API__OFF_T@ offset, int whence);
 
 /* Create a new data buffer and return it in R_DH.  */
 gpgme_error_t gpgme_data_new (gpgme_data_t *r_dh);
@@ -1122,6 +1165,9 @@ char *gpgme_data_get_file_name (gpgme_data_t dh);
 gpgme_error_t gpgme_data_set_file_name (gpgme_data_t dh,
                                        const char *file_name);
 
+/* Try to identify the type of the data in DH.  */
+gpgme_data_type_t gpgme_data_identify (gpgme_data_t dh, int reserved);
+
 
 /* Create a new data buffer which retrieves the data from the callback
    function READ_CB.  Deprecated, please use gpgme_data_new_from_cbs
@@ -1144,7 +1190,7 @@ gpgme_error_t gpgme_data_new_from_file (gpgme_data_t *r_dh,
    non-zero).  */
 gpgme_error_t gpgme_data_new_from_filepart (gpgme_data_t *r_dh,
                                            const char *fname, FILE *fp,
-                                           off_t offset, size_t length);
+                                           @API__OFF_T@ offset, size_t length);
 
 /* Reset the read pointer in DH.  Deprecated, please use
    gpgme_data_seek instead.  */
@@ -2026,6 +2072,9 @@ gpgme_error_t gpgme_key_from_uid (gpgme_key_t *key, const char *name);
 \f
 /* Various functions.  */
 
+/* Set special global flags; consult the manual before use.  */
+int gpgme_set_global_flag (const char *name, const char *value);
+
 /* Check that the library fulfills the version requirement.  Note:
    This is here only for the case where a user takes a pointer from
    the old version of this function.  The new version and macro for