Imported Upstream version 1.4.2upstream/1.4.2

6 files changed, 230 insertions, 159 deletions

diff --git a/doc/gpgme.info b/doc/gpgme.info
index 2ec045e..5ac6f47 100644
--- a/doc/gpgme.info
+++ b/doc/gpgme.info
@@ -22,8 +22,8 @@ General Public License for more details.
 
    This file documents the GPGME library.
 
-   This is Edition 1.4.1, last updated 30 April 2013, of `The `GnuPG
-Made Easy' Reference Manual', for Version 1.4.1.
+   This is Edition 1.4.2, last updated 28 May 2013, of `The `GnuPG Made
+Easy' Reference Manual', for Version 1.4.2.
 
    Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2010, 2012,
 2013 g10 Code GmbH.
@@ -41,117 +41,117 @@ General Public License for more details.
 
 
 Indirect:
-gpgme.info-1: 1758
-gpgme.info-2: 279278
+gpgme.info-1: 1756
+gpgme.info-2: 281093
 
 Tag Table:
 (Indirect)
-Node: Top1758
-Node: Introduction8599
-Node: Getting Started9386
-Node: Features10511
-Node: Overview11661
-Node: Preparation12770
-Node: Header13767
-Node: Building the Source14466
-Node: Largefile Support (LFS)16575
-Node: Using Automake20579
-Node: Using Libtool22215
-Node: Library Version Check22565
-Node: Signal Handling26520
-Node: Multi Threading27736
-Ref: Multi Threading-Footnote-129918
-Node: Protocols and Engines30332
-Node: Engine Version Check32681
-Node: Engine Information33258
-Node: Engine Configuration36958
-Node: OpenPGP38220
-Node: Cryptographic Message Syntax38556
-Node: Algorithms38850
-Ref: Algorithms-Footnote-139329
-Node: Public Key Algorithms39457
-Node: Hash Algorithms41388
-Node: Error Handling42486
-Node: Error Values44348
-Node: Error Sources49426
-Node: Error Codes51753
-Node: Error Strings56392
-Node: Exchanging Data58171
-Node: Creating Data Buffers59485
-Node: Memory Based Data Buffers60001
-Node: File Based Data Buffers63355
-Node: Callback Based Data Buffers65526
-Node: Destroying Data Buffers71082
-Node: Manipulating Data Buffers72441
-Node: Data Buffer I/O Operations72860
-Node: Data Buffer Meta-Data75563
-Node: Contexts78913
-Node: Creating Contexts80036
-Node: Destroying Contexts80847
-Node: Result Management81182
-Node: Context Attributes82588
-Node: Protocol Selection83366
-Node: Crypto Engine84378
-Node: ASCII Armor86199
-Node: Text Mode86811
-Node: Included Certificates87742
-Node: Key Listing Mode89117
-Node: Passphrase Callback92474
-Node: Progress Meter Callback95612
-Node: Locale97536
-Node: Key Management99075
-Node: Listing Keys109003
-Node: Information About Keys116265
-Node: Key Signatures124263
-Node: Manipulating Keys128275
-Node: Generating Keys129117
-Node: Exporting Keys133724
-Node: Importing Keys139623
-Ref: Importing Keys-Footnote-1146786
-Node: Deleting Keys146914
-Node: Changing Passphrases148311
-Node: Advanced Key Editing149572
-Node: Trust Item Management152676
-Node: Listing Trust Items153746
-Node: Information About Trust Items156044
-Node: Manipulating Trust Items157926
-Node: Crypto Operations158887
-Node: Decrypt160131
-Node: Verify163989
-Node: Decrypt and Verify181845
-Node: Sign183849
-Node: Selecting Signers184413
-Node: Creating a Signature185394
-Node: Signature Notation Data189983
-Node: Encrypt192167
-Node: Encrypting a Plaintext192523
-Node: Run Control198368
-Node: Waiting For Completion199115
-Node: Using External Event Loops201161
-Node: I/O Callback Interface203128
-Node: Registering I/O Callbacks208222
-Node: I/O Callback Example210213
-Node: I/O Callback Example GTK+216432
-Node: I/O Callback Example GDK218221
-Node: I/O Callback Example Qt219863
-Node: Cancellation222151
-Node: UI Server Protocol224404
-Ref: UI Server Protocol-Footnote-1225835
-Node: UI Server Encrypt225954
-Node: UI Server Sign231135
-Node: UI Server Decrypt233364
-Node: UI Server Verify234802
-Node: UI Server Set Input Files238304
-Node: UI Server Sign/Encrypt Files239104
-Node: UI Server Verify/Decrypt Files240873
-Node: UI Server Import/Export Keys242719
-Node: UI Server Checksum Files243752
-Node: Miscellaneous UI Server Commands245918
-Ref: command SENDER247830
-Node: Debugging249506
-Node: Library Copying251161
-Node: Copying279278
-Node: Function and Data Index316909
-Node: Concept Index342025
+Node: Top1756
+Node: Introduction8595
+Node: Getting Started9382
+Node: Features10507
+Node: Overview11657
+Node: Preparation12766
+Node: Header13763
+Node: Building the Source14462
+Node: Largefile Support (LFS)16571
+Node: Using Automake21882
+Node: Using Libtool23518
+Node: Library Version Check23868
+Node: Signal Handling27823
+Node: Multi Threading29039
+Ref: Multi Threading-Footnote-131221
+Node: Protocols and Engines31635
+Node: Engine Version Check33984
+Node: Engine Information34561
+Node: Engine Configuration38261
+Node: OpenPGP39523
+Node: Cryptographic Message Syntax39859
+Node: Algorithms40153
+Ref: Algorithms-Footnote-140632
+Node: Public Key Algorithms40760
+Node: Hash Algorithms42691
+Node: Error Handling43789
+Node: Error Values45651
+Node: Error Sources50729
+Node: Error Codes53056
+Node: Error Strings57695
+Node: Exchanging Data59474
+Node: Creating Data Buffers61303
+Node: Memory Based Data Buffers61819
+Node: File Based Data Buffers65173
+Node: Callback Based Data Buffers67344
+Node: Destroying Data Buffers72900
+Node: Manipulating Data Buffers74259
+Node: Data Buffer I/O Operations74678
+Node: Data Buffer Meta-Data77381
+Node: Contexts80731
+Node: Creating Contexts81854
+Node: Destroying Contexts82665
+Node: Result Management83000
+Node: Context Attributes84406
+Node: Protocol Selection85184
+Node: Crypto Engine86196
+Node: ASCII Armor88017
+Node: Text Mode88629
+Node: Included Certificates89560
+Node: Key Listing Mode90935
+Node: Passphrase Callback94292
+Node: Progress Meter Callback97430
+Node: Locale99354
+Node: Key Management100893
+Node: Listing Keys110818
+Node: Information About Keys118080
+Node: Key Signatures126078
+Node: Manipulating Keys130090
+Node: Generating Keys130932
+Node: Exporting Keys135539
+Node: Importing Keys141438
+Ref: Importing Keys-Footnote-1148601
+Node: Deleting Keys148729
+Node: Changing Passphrases150126
+Node: Advanced Key Editing151387
+Node: Trust Item Management154491
+Node: Listing Trust Items155561
+Node: Information About Trust Items157859
+Node: Manipulating Trust Items159741
+Node: Crypto Operations160702
+Node: Decrypt161946
+Node: Verify165804
+Node: Decrypt and Verify183660
+Node: Sign185664
+Node: Selecting Signers186228
+Node: Creating a Signature187209
+Node: Signature Notation Data191798
+Node: Encrypt193982
+Node: Encrypting a Plaintext194338
+Node: Run Control200183
+Node: Waiting For Completion200930
+Node: Using External Event Loops202976
+Node: I/O Callback Interface204943
+Node: Registering I/O Callbacks210037
+Node: I/O Callback Example212028
+Node: I/O Callback Example GTK+218247
+Node: I/O Callback Example GDK220036
+Node: I/O Callback Example Qt221678
+Node: Cancellation223966
+Node: UI Server Protocol226219
+Ref: UI Server Protocol-Footnote-1227650
+Node: UI Server Encrypt227769
+Node: UI Server Sign232950
+Node: UI Server Decrypt235179
+Node: UI Server Verify236617
+Node: UI Server Set Input Files240119
+Node: UI Server Sign/Encrypt Files240919
+Node: UI Server Verify/Decrypt Files242688
+Node: UI Server Import/Export Keys244534
+Node: UI Server Checksum Files245567
+Node: Miscellaneous UI Server Commands247733
+Ref: command SENDER249645
+Node: Debugging251321
+Node: Library Copying252976
+Node: Copying281093
+Node: Function and Data Index318724
+Node: Concept Index343986
 
 End Tag Table
diff --git a/doc/gpgme.info-1 b/doc/gpgme.info-1
index beb3286..2066b90 100644
--- a/doc/gpgme.info-1
+++ b/doc/gpgme.info-1
@@ -22,8 +22,8 @@ General Public License for more details.
 
    This file documents the GPGME library.
 
-   This is Edition 1.4.1, last updated 30 April 2013, of `The `GnuPG
-Made Easy' Reference Manual', for Version 1.4.1.
+   This is Edition 1.4.2, last updated 28 May 2013, of `The `GnuPG Made
+Easy' Reference Manual', for Version 1.4.2.
 
    Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2010, 2012,
 2013 g10 Code GmbH.
@@ -45,8 +45,8 @@ File: gpgme.info,  Node: Top,  Next: Introduction,  Up: (dir)
 Main Menu
 *********
 
-This is Edition 1.4.1, last updated 30 April 2013, of `The `GnuPG Made
-Easy' Reference Manual', for Version 1.4.1 of the GPGME library.
+This is Edition 1.4.2, last updated 28 May 2013, of `The `GnuPG Made
+Easy' Reference Manual', for Version 1.4.2 of the GPGME library.
 
 * Menu:
 
@@ -444,18 +444,38 @@ support by default and just use that.  The compatibility modes (small
 file sizes or dual mode) can be considered an historic artefact, only
 useful to allow for a transitional period.
 
-   GPGME is compiled using largefile support by default.  This means
-that your application must do the same, at least as far as it is
-relevant for using the `gpgme.h' header file.  All types in this header
-files refer to their largefile counterparts, if they are different from
-any default types on the system.
-
-   You can enable largefile support, if it is different from the default
-on the system the application is compiled on, by using the Autoconf
-macro `AC_SYS_LARGEFILE'.  If you do this, then you don't need to worry
-about anything else: It will just work.  In this case you might also
-want to use `AC_FUNC_FSEEKO' to take advantage of some new interfaces,
-and `AC_TYPE_OFF_T' (just in case).
+   On POSIX platforms GPGME is compiled using largefile support by
+default.  This means that your application must do the same, at least
+as far as it is relevant for using the `gpgme.h' header file.  All
+types in this header files refer to their largefile counterparts, if
+they are different from any default types on the system.
+
+   On 32 and 64 bit Windows platforms `off_t' is declared as 32 bit
+signed integer.  There is no specific support for LFS in the C library.
+The recommendation from Microsoft is to use the native interface
+(`CreateFile' et al.) for large files.  Released binary versions of
+GPGME (libgpgme-11.dll) have always been build with a 32 bit `off_t'.
+To avoid an ABI break we stick to this convention for 32 bit Windows by
+using `long' there.  GPGME versions for 64 bit Windows have never been
+released and thus we are able to use `int64_t' instead of `off_t'
+there.  For easier migration the typedef `gpgme_off_t' has been
+defined.  The reason we cannot use `off_t' directly is that some
+toolchains (e.g. mingw64) introduce a POSIX compatible hack for
+`off_t'.  Some widely used toolkits make use of this hack and in turn
+GPGME would need to use it also.  However, this would introduce an ABI
+break and existing software making use of libgpgme might suffer from a
+severe break.  Thus with version 1.4.2 we redefined all functions using
+`off_t' to use `gpgme_off_t' which is defined as explained above.  This
+way we keep the ABI well defined and independent of any toolchain
+hacks.  The bottom line is that LFS support in GPGME is only available
+on 64 bit versions of Windows.
+
+   On POSIX platforms you can enable largefile support, if it is
+different from the default on the system the application is compiled
+on, by using the Autoconf macro `AC_SYS_LARGEFILE'.  If you do this,
+then you don't need to worry about anything else: It will just work.
+In this case you might also want to use `AC_FUNC_FSEEKO' to take
+advantage of some new interfaces, and `AC_TYPE_OFF_T' (just in case).
 
    If you do not use Autoconf, you can define the preprocessor symbol
 `_FILE_OFFSET_BITS' to 64 _before_ including any header files, for
@@ -1449,6 +1469,17 @@ all GPGME data operations always have data available, for example by
 using memory buffers or files rather than pipes or sockets.  This might
 be relevant, for example, if the external event loop mechanism is used.
 
+ -- Data type: gpgme_off_t
+     On POSIX platforms the `gpgme_off_t' type is an alias for `off_t';
+     it may be used interchangeable.  On Windows platforms
+     `gpgme_off_t' is defined as a long (i.e. 32 bit) for 32 bit
+     Windows and as a 64 bit signed integer for 64 bit Windows.
+
+ -- Data type: gpgme_ssize_t
+     The `gpgme_ssize_t' type is an alias for `ssize_t'.  It has only
+     been introduced to overcome portability problems pertaining to the
+     declaration of `ssize_t' by different toolchains.
+
 * Menu:
 
 * Creating Data Buffers::         Creating new data buffers.
@@ -2383,9 +2414,9 @@ are specified.  This is always done by specifying the respective keys
 that should be used for the operation.  The following section describes
 how such keys can be selected and manipulated.
 
- -- Data type: gpgme_sub_key_t
-     The `gpgme_sub_key_t' type is a pointer to a subkey structure.
-     Sub keys are one component of a `gpgme_key_t' object.  In fact,
+ -- Data type: gpgme_subkey_t
+     The `gpgme_subkey_t' type is a pointer to a subkey structure.  Sub
+     keys are one component of a `gpgme_key_t' object.  In fact,
      subkeys are those parts that contains the real information about
      the individual cryptographic keys that belong to the same key
      object.  One `gpgme_key_t' can contain several subkeys.  The first
@@ -2393,7 +2424,7 @@ how such keys can be selected and manipulated.
 
      The subkey structure has the following members:
 
-    `gpgme_sub_key_t next'
+    `gpgme_subkey_t next'
           This is a pointer to the next subkey structure in the linked
           list, or `NULL' if this is the last element.
 
@@ -2627,7 +2658,7 @@ how such keys can be selected and manipulated.
           If `protocol' is `GPGME_PROTOCOL_OpenPGP', then this is the
           owner trust.
 
-    `gpgme_sub_key_t subkeys'
+    `gpgme_subkey_t subkeys'
           This is a linked list with the subkeys of the key.  The first
           subkey in the list is the primary key and usually available.
 
diff --git a/doc/gpgme.info-2 b/doc/gpgme.info-2
index 8d7a6ab..287304f 100644
--- a/doc/gpgme.info-2
+++ b/doc/gpgme.info-2
@@ -22,8 +22,8 @@ General Public License for more details.
 
    This file documents the GPGME library.
 
-   This is Edition 1.4.1, last updated 30 April 2013, of `The `GnuPG
-Made Easy' Reference Manual', for Version 1.4.1.
+   This is Edition 1.4.2, last updated 28 May 2013, of `The `GnuPG Made
+Easy' Reference Manual', for Version 1.4.2.
 
    Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2010, 2012,
 2013 g10 Code GmbH.
@@ -931,6 +931,7 @@ Function and Data Index
 * gpgme_new:                             Creating Contexts.   (line   7)
 * gpgme_new_signature_t:                 Creating a Signature.
                                                               (line  58)
+* gpgme_off_t:                           Exchanging Data.     (line  25)
 * gpgme_op_card_edit:                    Advanced Key Editing.
                                                               (line  50)
 * gpgme_op_card_edit_start:              Advanced Key Editing.
@@ -1039,10 +1040,11 @@ Function and Data Index
 * gpgme_signers_add:                     Selecting Signers.   (line  15)
 * gpgme_signers_clear:                   Selecting Signers.   (line   7)
 * gpgme_signers_enum:                    Selecting Signers.   (line  22)
+* gpgme_ssize_t:                         Exchanging Data.     (line  31)
 * gpgme_strerror:                        Error Strings.       (line   7)
 * gpgme_strerror_r:                      Error Strings.       (line  17)
 * gpgme_strsource:                       Error Strings.       (line  27)
-* gpgme_sub_key_t:                       Key Management.      (line  12)
+* gpgme_subkey_t:                        Key Management.      (line  12)
 * gpgme_trust_item_get_int_attr:         Information About Trust Items.
                                                               (line  31)
 * gpgme_trust_item_get_string_attr:      Information About Trust Items.
diff --git a/doc/gpgme.texi b/doc/gpgme.texi
index b47d438..217dc13 100644
--- a/doc/gpgme.texi
+++ b/doc/gpgme.texi
@@ -493,18 +493,42 @@ support by default and just use that.  The compatibility modes (small
 file sizes or dual mode) can be considered an historic artefact, only
 useful to allow for a transitional period.
 
-@acronym{GPGME} is compiled using largefile support by default.  This
-means that your application must do the same, at least as far as it is
-relevant for using the @file{gpgme.h} header file.  All types in this
-header files refer to their largefile counterparts, if they are
-different from any default types on the system.
-
-You can enable largefile support, if it is different from the default
-on the system the application is compiled on, by using the Autoconf
-macro @code{AC_SYS_LARGEFILE}.  If you do this, then you don't need to
-worry about anything else: It will just work.  In this case you might
-also want to use @code{AC_FUNC_FSEEKO} to take advantage of some new
-interfaces, and @code{AC_TYPE_OFF_T} (just in case).
+On POSIX platforms @acronym{GPGME} is compiled using largefile support
+by default.  This means that your application must do the same, at
+least as far as it is relevant for using the @file{gpgme.h} header
+file.  All types in this header files refer to their largefile
+counterparts, if they are different from any default types on the
+system.
+
+On 32 and 64 bit Windows platforms @code{off_t} is declared as 32 bit
+signed integer.  There is no specific support for LFS in the C
+library.  The recommendation from Microsoft is to use the native
+interface (@code{CreateFile} et al.) for large files.  Released binary
+versions of @acronym{GPGME} (libgpgme-11.dll) have always been build
+with a 32 bit @code{off_t}.  To avoid an ABI break we stick to this
+convention for 32 bit Windows by using @code{long} there.
+@acronym{GPGME} versions for 64 bit Windows have never been released
+and thus we are able to use @code{int64_t} instead of @code{off_t}
+there.  For easier migration the typedef @code{gpgme_off_t} has been
+defined.  The reason we cannot use @code{off_t} directly is that some
+toolchains (e.g. mingw64) introduce a POSIX compatible hack for
+@code{off_t}.  Some widely used toolkits make use of this hack and in
+turn @acronym{GPGME} would need to use it also.  However, this would
+introduce an ABI break and existing software making use of libgpgme
+might suffer from a severe break.  Thus with version 1.4.2 we
+redefined all functions using @code{off_t} to use @code{gpgme_off_t}
+which is defined as explained above.  This way we keep the ABI well
+defined and independent of any toolchain hacks.  The bottom line is
+that LFS support in @acronym{GPGME} is only available on 64 bit
+versions of Windows.
+
+On POSIX platforms you can enable largefile support, if it is
+different from the default on the system the application is compiled
+on, by using the Autoconf macro @code{AC_SYS_LARGEFILE}.  If you do
+this, then you don't need to worry about anything else: It will just
+work.  In this case you might also want to use @code{AC_FUNC_FSEEKO}
+to take advantage of some new interfaces, and @code{AC_TYPE_OFF_T}
+(just in case).
 
 If you do not use Autoconf, you can define the preprocessor symbol
 @code{_FILE_OFFSET_BITS} to 64 @emph{before} including any header
@@ -1538,6 +1562,20 @@ by using memory buffers or files rather than pipes or sockets.  This
 might be relevant, for example, if the external event loop mechanism
 is used.
 
+@deftp {Data type} {gpgme_off_t}
+On POSIX platforms the @code{gpgme_off_t} type is an alias for
+@code{off_t}; it may be used interchangeable.  On Windows platforms
+@code{gpgme_off_t} is defined as a long (i.e. 32 bit) for 32 bit
+Windows and as a 64 bit signed integer for 64 bit Windows.
+@end deftp
+
+@deftp {Data type} {gpgme_ssize_t}
+The @code{gpgme_ssize_t} type is an alias for @code{ssize_t}.  It has
+only been introduced to overcome portability problems pertaining to
+the declaration of @code{ssize_t} by different toolchains.
+@end deftp
+
+
 @menu
 * Creating Data Buffers::         Creating new data buffers.
 * Destroying Data Buffers::       Releasing data buffers.
@@ -2507,8 +2545,8 @@ signers are specified.  This is always done by specifying the
 respective keys that should be used for the operation.  The following
 section describes how such keys can be selected and manipulated.
 
-@deftp {Data type} gpgme_sub_key_t
-The @code{gpgme_sub_key_t} type is a pointer to a subkey structure.
+@deftp {Data type} gpgme_subkey_t
+The @code{gpgme_subkey_t} type is a pointer to a subkey structure.
 Sub keys are one component of a @code{gpgme_key_t} object.  In fact,
 subkeys are those parts that contains the real information about the
 individual cryptographic keys that belong to the same key object.  One
@@ -2518,7 +2556,7 @@ the linked list is also called the primary key.
 The subkey structure has the following members:
 
 @table @code
-@item gpgme_sub_key_t next
+@item gpgme_subkey_t next
 This is a pointer to the next subkey structure in the linked list, or
 @code{NULL} if this is the last element.
 
@@ -2757,7 +2795,7 @@ chain ID, which can be used to built the certificate chain.
 If @code{protocol} is @code{GPGME_PROTOCOL_OpenPGP}, then this is the
 owner trust.
 
-@item gpgme_sub_key_t subkeys
+@item gpgme_subkey_t subkeys
 This is a linked list with the subkeys of the key.  The first subkey
 in the list is the primary key and usually available.
 
diff --git a/doc/stamp-vti b/doc/stamp-vti
index 1131294..42d8cc5 100644
--- a/doc/stamp-vti
+++ b/doc/stamp-vti
@@ -1,4 +1,4 @@
-@set UPDATED 30 April 2013
-@set UPDATED-MONTH April 2013
-@set EDITION 1.4.1
-@set VERSION 1.4.1
+@set UPDATED 28 May 2013
+@set UPDATED-MONTH May 2013
+@set EDITION 1.4.2
+@set VERSION 1.4.2
diff --git a/doc/version.texi b/doc/version.texi
index 1131294..42d8cc5 100644
--- a/doc/version.texi
+++ b/doc/version.texi
@@ -1,4 +1,4 @@
-@set UPDATED 30 April 2013
-@set UPDATED-MONTH April 2013
-@set EDITION 1.4.1
-@set VERSION 1.4.1
+@set UPDATED 28 May 2013
+@set UPDATED-MONTH May 2013
+@set EDITION 1.4.2
+@set VERSION 1.4.2