Imported Upstream version 1.4.1upstream/1.4.1

6 files changed, 207 insertions, 126 deletions

diff --git a/doc/gpgme.info b/doc/gpgme.info
index 77cb4d5..2ec045e 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.0, last updated 26 February 2013, of `The `GnuPG
-Made Easy' Reference Manual', for Version 1.4.0.
+   This is Edition 1.4.1, last updated 30 April 2013, of `The `GnuPG
+Made Easy' Reference Manual', for Version 1.4.1.
 
    Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2010, 2012,
 2013 g10 Code GmbH.
@@ -41,116 +41,117 @@ General Public License for more details.
 
 
 Indirect:
-gpgme.info-1: 1761
-gpgme.info-2: 277587
+gpgme.info-1: 1758
+gpgme.info-2: 279278
 
 Tag Table:
 (Indirect)
-Node: Top1761
-Node: Introduction8548
-Node: Getting Started9335
-Node: Features10460
-Node: Overview11610
-Node: Preparation12719
-Node: Header13716
-Node: Building the Source14415
-Node: Largefile Support (LFS)16524
-Node: Using Automake20528
-Node: Using Libtool22164
-Node: Library Version Check22514
-Node: Signal Handling26469
-Node: Multi Threading27685
-Ref: Multi Threading-Footnote-129867
-Node: Protocols and Engines30281
-Node: Engine Version Check32630
-Node: Engine Information33207
-Node: Engine Configuration36907
-Node: OpenPGP38169
-Node: Cryptographic Message Syntax38505
-Node: Algorithms38799
-Ref: Algorithms-Footnote-139278
-Node: Public Key Algorithms39406
-Node: Hash Algorithms41337
-Node: Error Handling42435
-Node: Error Values44297
-Node: Error Sources49375
-Node: Error Codes51702
-Node: Error Strings56341
-Node: Exchanging Data58120
-Node: Creating Data Buffers59434
-Node: Memory Based Data Buffers59950
-Node: File Based Data Buffers63304
-Node: Callback Based Data Buffers65475
-Node: Destroying Data Buffers71031
-Node: Manipulating Data Buffers72390
-Node: Data Buffer I/O Operations72809
-Node: Data Buffer Meta-Data75512
-Node: Contexts78862
-Node: Creating Contexts79985
-Node: Destroying Contexts80796
-Node: Result Management81131
-Node: Context Attributes82537
-Node: Protocol Selection83315
-Node: Crypto Engine84327
-Node: ASCII Armor86148
-Node: Text Mode86760
-Node: Included Certificates87691
-Node: Key Listing Mode89066
-Node: Passphrase Callback92423
-Node: Progress Meter Callback95561
-Node: Locale97485
-Node: Key Management99024
-Node: Listing Keys108952
-Node: Information About Keys116214
-Node: Key Signatures124212
-Node: Manipulating Keys128224
-Node: Generating Keys129066
-Node: Exporting Keys133673
-Node: Importing Keys139572
-Ref: Importing Keys-Footnote-1146735
-Node: Deleting Keys146863
-Node: Changing Passphrases148260
-Node: Advanced Key Editing149521
-Node: Trust Item Management152625
-Node: Listing Trust Items153695
-Node: Information About Trust Items155993
-Node: Manipulating Trust Items157875
-Node: Crypto Operations158836
-Node: Decrypt160080
-Node: Verify163938
-Node: Decrypt and Verify181794
-Node: Sign183798
-Node: Selecting Signers184362
-Node: Creating a Signature185343
-Node: Signature Notation Data189932
-Node: Encrypt192116
-Node: Encrypting a Plaintext192472
-Node: Run Control198317
-Node: Waiting For Completion199064
-Node: Using External Event Loops201110
-Node: I/O Callback Interface203077
-Node: Registering I/O Callbacks208171
-Node: I/O Callback Example210162
-Node: I/O Callback Example GTK+216381
-Node: I/O Callback Example GDK218170
-Node: I/O Callback Example Qt219812
-Node: Cancellation222100
-Node: UI Server Protocol224353
-Ref: UI Server Protocol-Footnote-1225790
-Node: UI Server Encrypt225909
-Node: UI Server Sign231090
-Node: UI Server Decrypt233319
-Node: UI Server Verify234757
-Node: UI Server Set Input Files238259
-Node: UI Server Sign/Encrypt Files239059
-Node: UI Server Verify/Decrypt Files240828
-Node: UI Server Import/Export Keys242674
-Node: UI Server Checksum Files243707
-Node: Miscellaneous UI Server Commands245873
-Ref: command SENDER247785
-Node: Library Copying249461
-Node: Copying277587
-Node: Function and Data Index315218
-Node: Concept Index340334
+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
 
 End Tag Table
diff --git a/doc/gpgme.info-1 b/doc/gpgme.info-1
index 1275165..beb3286 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.0, last updated 26 February 2013, of `The `GnuPG
-Made Easy' Reference Manual', for Version 1.4.0.
+   This is Edition 1.4.1, last updated 30 April 2013, of `The `GnuPG
+Made Easy' Reference Manual', for Version 1.4.1.
 
    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.0, last updated 26 February 2013, of `The `GnuPG
-Made Easy' Reference Manual', for Version 1.4.0 of 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 of the GPGME library.
 
 * Menu:
 
@@ -61,6 +61,7 @@ Made Easy' Reference Manual', for Version 1.4.0 of the GPGME library.
 Appendices
 
 * UI Server Protocol::            The GnuPG UI Server Protocol.
+* Debugging::                     How to solve problems.
 
 * Library Copying::               The GNU Lesser General Public License says
                                   how you can copy and share `GnuPG Made Easy'.
@@ -5543,7 +5544,7 @@ I/O occurs in the target context).
      this case the state of CTX is not modified).
 
 
-File: gpgme.info,  Node: UI Server Protocol,  Next: Library Copying,  Prev: Contexts,  Up: Top
+File: gpgme.info,  Node: UI Server Protocol,  Next: Debugging,  Prev: Contexts,  Up: Top
 
 Appendix A The GnuPG UI Server Protocol
 ***************************************
@@ -6111,7 +6112,42 @@ associate operations the server MAY support the command:
 
 
 
-File: gpgme.info,  Node: Library Copying,  Next: Copying,  Prev: UI Server Protocol,  Up: Top
+File: gpgme.info,  Node: Debugging,  Next: Library Copying,  Prev: UI Server Protocol,  Up: Top
+
+Appendix B How to solve problems
+********************************
+
+Everyone knows that software often does not do what it should do and
+thus there is a need to track down problems.  This is in particular true
+for applications using a complex library like GPGME and of course also
+for the library itself.  Here we give a few hints on how to solve such
+problems.
+
+   First of all you should make sure that the keys you want to use are
+installed in the GnuPG engine and are usable.  Thus the first test is
+to run the desired operation using `gpg' or `gpgsm' on the command
+line.  If you can't figure out why things don't work, you may use
+GPGME's built in trace feature.  This feature is either enabled using
+the environment variable `GPGME_DEBUG' or, if this is not possible, by
+calling the function `gpgme_set_global_flag'.  The value is the trace
+level and an optional file name.
+
+For example
+     GPGME_DEBUG=9:/home/user/mygpgme.log
+   (Note that under Windows you use a semicolon in place of the colon to
+separate the fields.)
+
+   A trace level of 9 is pretty verbose and thus you may want to start
+off with a lower level.  The exact definition of the trace levels and
+the output format may change with any release; you need to check the
+source code for details.  In any case the trace log should be helpful
+to understand what is going going on.  Warning: The trace log may
+reveal sensitive details like passphrases or other data you use in your
+application.  If you are asked to send a log file, make sure that you
+run your tests only with play data.
+
+
+File: gpgme.info,  Node: Library Copying,  Next: Copying,  Prev: Debugging,  Up: Top
 
 GNU Lesser General Public License
 *********************************
diff --git a/doc/gpgme.info-2 b/doc/gpgme.info-2
index 35239ba..8d7a6ab 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.0, last updated 26 February 2013, of `The `GnuPG
-Made Easy' Reference Manual', for Version 1.4.0.
+   This is Edition 1.4.1, last updated 30 April 2013, of `The `GnuPG
+Made Easy' Reference Manual', for Version 1.4.1.
 
    Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2010, 2012,
 2013 g10 Code GmbH.
@@ -1189,6 +1189,7 @@ Concept Index
 * data buffer, write:                    Data Buffer I/O Operations.
                                                                 (line 6)
 * data, exchanging:                      Exchanging Data.       (line 6)
+* debug:                                 Debugging.             (line 6)
 * decryption:                            Decrypt.               (line 6)
 * decryption and verification:           Decrypt and Verify.    (line 6)
 * encryption:                            Encrypt.               (line 6)
@@ -1214,6 +1215,7 @@ Concept Index
 * GDK, using GPGME with:                 I/O Callback Example GDK.
                                                                 (line 6)
 * GnuPG:                                 OpenPGP.               (line 6)
+* GPGME_DEBUG:                           Debugging.             (line 6)
 * GpgSM:                                 Cryptographic Message Syntax.
                                                                 (line 6)
 * GTK+, using GPGME with:                I/O Callback Example GTK+.
diff --git a/doc/gpgme.texi b/doc/gpgme.texi
index af2e163..b47d438 100644
--- a/doc/gpgme.texi
+++ b/doc/gpgme.texi
@@ -101,6 +101,7 @@ This is Edition @value{EDITION}, last updated @value{UPDATED}, of
 Appendices
 
 * UI Server Protocol::            The GnuPG UI Server Protocol.
+* Debugging::                     How to solve problems.
 
 * Library Copying::               The GNU Lesser General Public License says
                                   how you can copy and share `GnuPG Made Easy'.
@@ -5794,6 +5795,47 @@ case the state of @var{ctx} is not modified).
 
 @include uiserver.texi
 
+@node Debugging
+@appendix How to solve problems
+@cindex debug
+@cindex GPGME_DEBUG
+
+Everyone knows that software often does not do what it should do and thus
+there is a need to track down problems.  This is in particular true
+for applications using a complex library like @acronym{GPGME} and of
+course also for the library itself.  Here we give a few hints on how
+to solve such problems.
+
+First of all you should make sure that the keys you want to use are
+installed in the GnuPG engine and are usable.  Thus the first test is
+to run the desired operation using @command{gpg} or @command{gpgsm} on
+the command line.  If you can't figure out why things don't work, you
+may use @acronym{GPGME}'s built in trace feature.  This feature is
+either enabled using the environment variable @code{GPGME_DEBUG} or,
+if this is not possible, by calling the function
+@code{gpgme_set_global_flag}.  The value is the trace level and
+an optional file name.
+
+@noindent
+For example
+@smallexample
+GPGME_DEBUG=9:/home/user/mygpgme.log
+@end smallexample
+@noindent
+(Note that under Windows you use a semicolon in place of the colon to
+separate the fields.)
+
+A trace level of 9 is pretty verbose and thus you may want to start
+off with a lower level.  The exact definition of the trace levels and
+the output format may change with any release; you need to check the
+source code for details.  In any case the trace log should be helpful
+to understand what is going going on.  Warning: The trace log may
+reveal sensitive details like passphrases or other data you use in
+your application.  If you are asked to send a log file, make sure that
+you run your tests only with play data.
+
+
+
 @include lesser.texi
 
 @include gpl.texi
diff --git a/doc/stamp-vti b/doc/stamp-vti
index 1040955..1131294 100644
--- a/doc/stamp-vti
+++ b/doc/stamp-vti
@@ -1,4 +1,4 @@
-@set UPDATED 26 February 2013
-@set UPDATED-MONTH February 2013
-@set EDITION 1.4.0
-@set VERSION 1.4.0
+@set UPDATED 30 April 2013
+@set UPDATED-MONTH April 2013
+@set EDITION 1.4.1
+@set VERSION 1.4.1
diff --git a/doc/version.texi b/doc/version.texi
index 1040955..1131294 100644
--- a/doc/version.texi
+++ b/doc/version.texi
@@ -1,4 +1,4 @@
-@set UPDATED 26 February 2013
-@set UPDATED-MONTH February 2013
-@set EDITION 1.4.0
-@set VERSION 1.4.0
+@set UPDATED 30 April 2013
+@set UPDATED-MONTH April 2013
+@set EDITION 1.4.1
+@set VERSION 1.4.1