8d1e0fe6f5286511014d5e830d29e53007f9c5d2
[gpgme.git] / gpgme / gpgme.h
1 /* gpgme.h - Public interface to GnuPG Made Easy.
2    Copyright (C) 2000 Werner Koch (dd9jn)
3    Copyright (C) 2001, 2002, 2003 g10 Code GmbH
4
5    This file is part of GPGME.
6  
7    GPGME is free software; you can redistribute it and/or modify it
8    under the terms of the GNU General Public License as published by
9    the Free Software Foundation; either version 2 of the License, or
10    (at your option) any later version.
11  
12    GPGME is distributed in the hope that it will be useful, but
13    WITHOUT ANY WARRANTY; without even the implied warranty of
14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15    General Public License for more details.
16  
17    You should have received a copy of the GNU General Public License
18    along with GPGME; if not, write to the Free Software Foundation,
19    Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.  */
20
21 #ifndef GPGME_H
22 #define GPGME_H
23
24 /* Include stdio.h for the FILE type definition.  */
25 #include <stdio.h>
26
27 #ifdef _MSC_VER
28   typedef long off_t;
29   typedef long ssize_t;
30 #else
31 # include <sys/types.h>
32 #endif
33
34 #ifdef __cplusplus
35 extern "C" {
36 #if 0 /* just to make Emacs auto-indent happy */
37 }
38 #endif
39 #endif
40
41 \f
42 /* The version of this header should match the one of the library.  Do
43    not use this symbol in your application, use gpgme_check_version
44    instead.  The purpose of this macro is to let autoconf (using the
45    AM_PATH_GPGME macro) check that this header matches the installed
46    library.  Warning: Do not edit the next line.  configure will do
47    that for you!  */
48 #define GPGME_VERSION "0.4.1"
49
50 \f
51 /* The opaque data types used by GPGME.  */
52
53 /* The context holds some global state and configration options, as
54    well as the results of a crypto operation.  */
55 struct gpgme_context_s;
56 typedef struct gpgme_context_s *GpgmeCtx;
57
58 /* The data object is used by GPGME to exchange arbitrary data.  */
59 struct gpgme_data_s;
60 typedef struct gpgme_data_s *GpgmeData;
61
62 /* A list of recipients to be used in an encryption operation.  */
63 struct gpgme_recipients_s;
64 typedef struct gpgme_recipients_s *GpgmeRecipients;
65
66 \f
67 /* Public data types provided by GPGME.  */
68
69 /* The error numbers used by GPGME.  */
70 typedef enum
71   {
72     GPGME_EOF                     = -1,
73     GPGME_No_Error                = 0x0000,
74     GPGME_General_Error           = 0x0001,
75     GPGME_Out_Of_Core             = 0x0002,
76     GPGME_Invalid_Value           = 0x0003,
77     GPGME_Exec_Error              = 0x0004,
78     GPGME_Too_Many_Procs          = 0x0005,
79     GPGME_Pipe_Error              = 0x0006,
80     GPGME_No_Data                 = 0x0007,
81     GPGME_Conflict                = 0x0008,
82     GPGME_Not_Implemented         = 0x0009,
83     GPGME_Read_Error              = 0x000a,
84     GPGME_Write_Error             = 0x000b,
85     GPGME_File_Error              = 0x000c, /* errno is set in this case.  */
86     GPGME_Decryption_Failed       = 0x000d,
87     GPGME_Bad_Passphrase          = 0x000e,
88     GPGME_Canceled                = 0x000f,
89     GPGME_Invalid_Key             = 0x0010,
90     GPGME_Invalid_Engine          = 0x0011,
91     GPGME_No_UserID               = 0x0012,
92     GPGME_Invalid_UserID          = 0x0013,
93
94     /* Reasons for invalid user id.  */
95     GPGME_Unknown_Reason          = 0x0100,
96     GPGME_Not_Found               = 0x0101,
97     GPGME_Ambiguous_Specification = 0x0102,
98     GPGME_Wrong_Key_Usage         = 0x0103,
99     GPGME_Key_Revoked             = 0x0104,
100     GPGME_Key_Expired             = 0x0105,
101     GPGME_No_CRL_Known            = 0x0106,
102     GPGME_CRL_Too_Old             = 0x0107,
103     GPGME_Policy_Mismatch         = 0x0108,
104     GPGME_No_Secret_Key           = 0x0109,
105     GPGME_Key_Not_Trusted         = 0x010a,
106     
107     /* Import problems.  */
108     GPGME_Issuer_Missing          = 0x0200,
109     GPGME_Chain_Too_Long          = 0x0201,
110
111     /* Verification problems.  */
112     GPGME_Unsupported_Algorithm   = 0x0300,
113     GPGME_Sig_Expired             = 0x0301,
114     GPGME_Bad_Signature           = 0x0302,
115     GPGME_No_Public_Key           = 0x0303,
116
117     /* Deprecated.  */
118     GPGME_Busy                    = -2,
119     GPGME_No_Request              = -3,
120     GPGME_Invalid_Type            = -4,
121     GPGME_Invalid_Mode            = -5
122   }
123 GpgmeError;
124
125 #define GPGME_No_Recipients     GPGME_No_UserID
126 #define GPGME_Invalid_Recipient GPGME_Invalid_UserID
127 #define GPGME_No_Passphrase     GPGME_Bad_Passphrase
128
129
130 /* The possible encoding mode of GpgmeData objects.  */
131 typedef enum
132   {
133     GPGME_DATA_ENCODING_NONE   = 0,     /* Not specified.  */
134     GPGME_DATA_ENCODING_BINARY = 1,
135     GPGME_DATA_ENCODING_BASE64 = 2,
136     GPGME_DATA_ENCODING_ARMOR  = 3      /* Either PEM or OpenPGP Armor.  */
137   }
138 GpgmeDataEncoding;
139
140
141 /* Public key algorithms from libgcrypt.  */
142 typedef enum
143   {
144     GPGME_PK_RSA   = 1,
145     GPGME_PK_RSA_E = 2,
146     GPGME_PK_RSA_S = 3,
147     GPGME_PK_ELG_E = 16,
148     GPGME_PK_DSA   = 17,
149     GPGME_PK_ELG   = 20
150   }
151 GpgmePubKeyAlgo;
152
153
154 /* Hash algorithms from libgcrypt.  */
155 typedef enum
156   {
157     GPGME_MD_NONE          = 0,  
158     GPGME_MD_MD5           = 1,
159     GPGME_MD_SHA1          = 2,
160     GPGME_MD_RMD160        = 3,
161     GPGME_MD_MD2           = 5,
162     GPGME_MD_TIGER         = 6,   /* TIGER/192. */
163     GPGME_MD_HAVAL         = 7,   /* HAVAL, 5 pass, 160 bit. */
164     GPGME_MD_SHA256        = 8,
165     GPGME_MD_SHA384        = 9,
166     GPGME_MD_SHA512        = 10,
167     GPGME_MD_MD4           = 301,
168     GPGME_MD_CRC32         = 302,
169     GPGME_MD_CRC32_RFC1510 = 303,
170     GPGME_MD_CRC24_RFC2440 = 304
171   }
172 GpgmeHashAlgo;
173
174
175 /* The possible signature stati.  */
176 typedef enum
177   {
178     GPGME_SIG_STAT_NONE  = 0,
179     GPGME_SIG_STAT_GOOD  = 1,
180     GPGME_SIG_STAT_BAD   = 2,
181     GPGME_SIG_STAT_NOKEY = 3,
182     GPGME_SIG_STAT_NOSIG = 4,
183     GPGME_SIG_STAT_ERROR = 5,
184     GPGME_SIG_STAT_DIFF  = 6,
185     GPGME_SIG_STAT_GOOD_EXP = 7,
186     GPGME_SIG_STAT_GOOD_EXPKEY = 8
187   }
188 GpgmeSigStat;
189
190 /* The available signature modes.  */
191 typedef enum
192   {
193     GPGME_SIG_MODE_NORMAL = 0,
194     GPGME_SIG_MODE_DETACH = 1,
195     GPGME_SIG_MODE_CLEAR  = 2
196   }
197 GpgmeSigMode;
198
199
200 /* The available key and signature attributes.  */
201 typedef enum
202   {
203     GPGME_ATTR_KEYID        = 1,
204     GPGME_ATTR_FPR          = 2,
205     GPGME_ATTR_ALGO         = 3,
206     GPGME_ATTR_LEN          = 4,
207     GPGME_ATTR_CREATED      = 5,
208     GPGME_ATTR_EXPIRE       = 6,
209     GPGME_ATTR_OTRUST       = 7,
210     GPGME_ATTR_USERID       = 8,
211     GPGME_ATTR_NAME         = 9,
212     GPGME_ATTR_EMAIL        = 10,
213     GPGME_ATTR_COMMENT      = 11,
214     GPGME_ATTR_VALIDITY     = 12,
215     GPGME_ATTR_LEVEL        = 13,
216     GPGME_ATTR_TYPE         = 14,
217     GPGME_ATTR_IS_SECRET    = 15,
218     GPGME_ATTR_KEY_REVOKED  = 16,
219     GPGME_ATTR_KEY_INVALID  = 17,
220     GPGME_ATTR_UID_REVOKED  = 18,
221     GPGME_ATTR_UID_INVALID  = 19,
222     GPGME_ATTR_KEY_CAPS     = 20,
223     GPGME_ATTR_CAN_ENCRYPT  = 21,
224     GPGME_ATTR_CAN_SIGN     = 22,
225     GPGME_ATTR_CAN_CERTIFY  = 23,
226     GPGME_ATTR_KEY_EXPIRED  = 24,
227     GPGME_ATTR_KEY_DISABLED = 25,
228     GPGME_ATTR_SERIAL       = 26,
229     GPGME_ATTR_ISSUER       = 27,
230     GPGME_ATTR_CHAINID      = 28,
231     GPGME_ATTR_SIG_STATUS   = 29,
232     GPGME_ATTR_ERRTOK       = 30,
233     GPGME_ATTR_SIG_SUMMARY  = 31,
234     GPGME_ATTR_SIG_CLASS    = 32
235   }
236 GpgmeAttr;
237
238 /* The available validities for a trust item or key.  */
239 typedef enum
240   {
241     GPGME_VALIDITY_UNKNOWN   = 0,
242     GPGME_VALIDITY_UNDEFINED = 1,
243     GPGME_VALIDITY_NEVER     = 2,
244     GPGME_VALIDITY_MARGINAL  = 3,
245     GPGME_VALIDITY_FULL      = 4,
246     GPGME_VALIDITY_ULTIMATE  = 5
247   }
248 GpgmeValidity;
249
250
251 /* The available protocols.  */
252 typedef enum
253   {
254     GPGME_PROTOCOL_OpenPGP = 0,  /* The default mode.  */
255     GPGME_PROTOCOL_CMS     = 1,
256   }
257 GpgmeProtocol;
258
259 \f
260 /* The possible stati for the edit operation.  */
261 typedef enum
262   {
263     GPGME_STATUS_EOF,
264     /* mkstatus processing starts here */
265     GPGME_STATUS_ENTER,
266     GPGME_STATUS_LEAVE,
267     GPGME_STATUS_ABORT,
268
269     GPGME_STATUS_GOODSIG,
270     GPGME_STATUS_BADSIG,
271     GPGME_STATUS_ERRSIG,
272
273     GPGME_STATUS_BADARMOR,
274
275     GPGME_STATUS_RSA_OR_IDEA,
276     GPGME_STATUS_KEYEXPIRED,
277     GPGME_STATUS_KEYREVOKED,
278
279     GPGME_STATUS_TRUST_UNDEFINED,
280     GPGME_STATUS_TRUST_NEVER,
281     GPGME_STATUS_TRUST_MARGINAL,
282     GPGME_STATUS_TRUST_FULLY,
283     GPGME_STATUS_TRUST_ULTIMATE,
284
285     GPGME_STATUS_SHM_INFO,
286     GPGME_STATUS_SHM_GET,
287     GPGME_STATUS_SHM_GET_BOOL,
288     GPGME_STATUS_SHM_GET_HIDDEN,
289
290     GPGME_STATUS_NEED_PASSPHRASE,
291     GPGME_STATUS_VALIDSIG,
292     GPGME_STATUS_SIG_ID,
293     GPGME_STATUS_ENC_TO,
294     GPGME_STATUS_NODATA,
295     GPGME_STATUS_BAD_PASSPHRASE,
296     GPGME_STATUS_NO_PUBKEY,
297     GPGME_STATUS_NO_SECKEY,
298     GPGME_STATUS_NEED_PASSPHRASE_SYM,
299     GPGME_STATUS_DECRYPTION_FAILED,
300     GPGME_STATUS_DECRYPTION_OKAY,
301     GPGME_STATUS_MISSING_PASSPHRASE,
302     GPGME_STATUS_GOOD_PASSPHRASE,
303     GPGME_STATUS_GOODMDC,
304     GPGME_STATUS_BADMDC,
305     GPGME_STATUS_ERRMDC,
306     GPGME_STATUS_IMPORTED,
307     GPGME_STATUS_IMPORT_OK,
308     GPGME_STATUS_IMPORT_PROBLEM,
309     GPGME_STATUS_IMPORT_RES,
310     GPGME_STATUS_FILE_START,
311     GPGME_STATUS_FILE_DONE,
312     GPGME_STATUS_FILE_ERROR,
313
314     GPGME_STATUS_BEGIN_DECRYPTION,
315     GPGME_STATUS_END_DECRYPTION,
316     GPGME_STATUS_BEGIN_ENCRYPTION,
317     GPGME_STATUS_END_ENCRYPTION,
318
319     GPGME_STATUS_DELETE_PROBLEM,
320     GPGME_STATUS_GET_BOOL,
321     GPGME_STATUS_GET_LINE,
322     GPGME_STATUS_GET_HIDDEN,
323     GPGME_STATUS_GOT_IT,
324     GPGME_STATUS_PROGRESS,
325     GPGME_STATUS_SIG_CREATED,
326     GPGME_STATUS_SESSION_KEY,
327     GPGME_STATUS_NOTATION_NAME,
328     GPGME_STATUS_NOTATION_DATA,
329     GPGME_STATUS_POLICY_URL,
330     GPGME_STATUS_BEGIN_STREAM,
331     GPGME_STATUS_END_STREAM,
332     GPGME_STATUS_KEY_CREATED,
333     GPGME_STATUS_USERID_HINT,
334     GPGME_STATUS_UNEXPECTED,
335     GPGME_STATUS_INV_RECP,
336     GPGME_STATUS_NO_RECP,
337     GPGME_STATUS_ALREADY_SIGNED,
338     GPGME_STATUS_SIGEXPIRED,
339     GPGME_STATUS_EXPSIG,
340     GPGME_STATUS_EXPKEYSIG,
341     GPGME_STATUS_TRUNCATED,
342     GPGME_STATUS_ERROR
343   }
344 GpgmeStatusCode;
345
346 \f
347 /* The engine information structure.  */
348 struct _gpgme_engine_info
349 {
350   struct _gpgme_engine_info *next;
351
352   /* The protocol ID.  */
353   GpgmeProtocol protocol;
354
355   /* The file name of the engine binary.  */
356   const char *file_name;
357
358   /* The version string of the installed engine.  */
359   const char *version;
360
361   /* The minimum version required for GPGME.  */
362   const char *req_version;
363 };
364 typedef struct _gpgme_engine_info *GpgmeEngineInfo;
365
366 \f
367 /* A subkey from a key.  */
368 struct _gpgme_subkey
369 {
370   struct _gpgme_subkey *next;
371
372   /* True if subkey is revoked.  */
373   unsigned int revoked : 1;
374
375   /* True if subkey is expired.  */
376   unsigned int expired : 1;
377
378   /* True if subkey is disabled.  */
379   unsigned int disabled : 1;
380
381   /* True if subkey is invalid.  */
382   unsigned int invalid : 1;
383
384   /* True if subkey can be used for encryption.  */
385   unsigned int can_encrypt : 1;
386
387   /* True if subkey can be used for signing.  */
388   unsigned int can_sign : 1;
389
390   /* True if subkey can be used for certification.  */
391   unsigned int can_certify : 1;
392
393   /* True if subkey is secret.  */
394   unsigned int secret : 1;
395
396   /* Internal to GPGME, do not use.  */
397   unsigned int _unused : 24;
398   
399   /* Public key algorithm supported by this subkey.  */
400   GpgmePubKeyAlgo pubkey_algo;
401
402   /* Length of the subkey.  */
403   unsigned int length;
404
405   /* The key ID of the subkey.  */
406   char *keyid;
407
408   /* Internal to GPGME, do not use.  */
409   char _keyid[16 + 1];
410
411   /* The fingerprint of the subkey in hex digit form.  */
412   char *fpr;
413
414   /* The creation timestamp, -1 if invalid, 0 if not available.  */
415   long int timestamp;
416
417   /* The expiration timestamp, 0 if the subkey does not expire.  */
418   long int expires;
419 };
420 typedef struct _gpgme_subkey *GpgmeSubkey;
421
422 /* A signature on a user ID.  */
423 struct _gpgme_key_sig
424 {
425   struct _gpgme_key_sig *next;
426
427   /* True if the signature is revoked.  */
428   unsigned int revoked : 1;
429
430   /* True if the signature is expired.  */
431   unsigned int expired : 1;
432
433   /* True if the signature is invalid.  */
434   unsigned int invalid : 1;
435
436   /* True if the signature should be exported.  */
437   unsigned int exportable : 1;
438
439   /* Internal to GPGME, do not use.  */
440   unsigned int _unused : 28;
441
442   /* The public key algorithm used to create the signature.  */
443   GpgmePubKeyAlgo pubkey_algo;
444
445   /* The key ID of key used to create the signature.  */
446   char *keyid;
447
448   /* Internal to GPGME, do not use.  */
449   char _keyid[16 + 1];
450
451   /* The creation timestamp, -1 if invalid, 0 if not available.  */
452   long int timestamp;
453
454   /* The expiration timestamp, 0 if the subkey does not expire.  */
455   long int expires;
456
457   /* Same as in GpgmeSignature.  */
458   GpgmeError status;
459
460   /* Crypto backend specific signature class.  */
461   unsigned int class;
462
463   /* The user ID string.  */
464   char *uid;
465
466   /* The name part of the user ID.  */
467   char *name;
468
469   /* The email part of the user ID.  */
470   char *email;
471
472   /* The comment part of the user ID.  */
473   char *comment;
474 };
475 typedef struct _gpgme_key_sig *GpgmeKeySig;
476
477 /* An user ID from a key.  */
478 struct _gpgme_user_id
479 {
480   struct _gpgme_user_id *next;
481
482   /* True if the user ID is revoked.  */
483   unsigned int revoked : 1;
484
485   /* True if the user ID is invalid.  */
486   unsigned int invalid : 1;
487
488   /* Internal to GPGME, do not use.  */
489   unsigned int _unused : 30;
490
491   /* The validity of the user ID.  */
492   GpgmeValidity validity; 
493
494   /* The user ID string.  */
495   char *uid;
496
497   /* The name part of the user ID.  */
498   char *name;
499
500   /* The email part of the user ID.  */
501   char *email;
502
503   /* The comment part of the user ID.  */
504   char *comment;
505
506   /* The signatures of the user ID.  */
507   GpgmeKeySig signatures;
508
509   /* Internal to GPGME, do not use.  */
510   GpgmeKeySig _last_keysig;
511 };
512 typedef struct _gpgme_user_id *GpgmeUserID;
513
514 /* A key from the keyring.  */
515 struct _gpgme_key
516 {
517   /* Internal to GPGME, do not use.  */
518   unsigned int _refs;
519
520   /* True if key is revoked.  */
521   unsigned int revoked : 1;
522
523   /* True if key is expired.  */
524   unsigned int expired : 1;
525
526   /* True if key is disabled.  */
527   unsigned int disabled : 1;
528
529   /* True if key is invalid.  */
530   unsigned int invalid : 1;
531
532   /* True if key can be used for encryption.  */
533   unsigned int can_encrypt : 1;
534
535   /* True if key can be used for signing.  */
536   unsigned int can_sign : 1;
537
538   /* True if key can be used for certification.  */
539   unsigned int can_certify : 1;
540
541   /* True if key is secret.  */
542   unsigned int secret : 1;
543
544   /* Internal to GPGME, do not use.  */
545   unsigned int _unused : 24;
546
547   /* This is the protocol supported by this key.  */
548   GpgmeProtocol protocol;
549
550   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the
551      issuer serial.  */
552   char *issuer_serial;
553
554   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the
555      issuer name.  */
556   char *issuer_name;
557
558   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the chain
559      ID.  */
560   char *chain_id;
561
562   /* If protocol is GPGME_PROTOCOL_OpenPGP, this field contains the
563      owner trust.  */
564   GpgmeValidity owner_trust;
565
566   /* The subkeys of the key.  */
567   GpgmeSubkey subkeys;
568
569   /* The user IDs of the key.  */
570   GpgmeUserID uids;
571
572   /* Internal to GPGME, do not use.  */
573   GpgmeSubkey _last_subkey;
574
575   /* Internal to GPGME, do not use.  */
576   GpgmeUserID _last_uid;
577 };
578 typedef struct _gpgme_key *GpgmeKey;
579
580 \f
581 /* Types for callback functions.  */
582
583 /* Request a passphrase from the user.  */
584 typedef GpgmeError (*GpgmePassphraseCb) (void *hook, const char *desc,
585                                          void **r_hd, const char **result);
586
587 /* Inform the user about progress made.  */
588 typedef void (*GpgmeProgressCb) (void *opaque, const char *what,
589                                  int type, int current, int total);
590
591 /* Interact with the user about an edit operation.  */
592 typedef GpgmeError (*GpgmeEditCb) (void *opaque, GpgmeStatusCode status,
593                                    const char *args, const char **reply);
594
595 \f
596 /* Context management functions.  */
597
598 /* Create a new context and return it in CTX.  */
599 GpgmeError gpgme_new (GpgmeCtx *ctx);
600
601 /* Release the context CTX.  */
602 void gpgme_release (GpgmeCtx ctx);
603
604 /* Set the protocol to be used by CTX to PROTO.  */
605 GpgmeError gpgme_set_protocol (GpgmeCtx ctx, GpgmeProtocol proto);
606
607 /* Get the protocol used with CTX */
608 GpgmeProtocol gpgme_get_protocol (GpgmeCtx ctx);
609
610 /* Get the string describing protocol PROTO, or NULL if invalid.  */
611 const char *gpgme_get_protocol_name (GpgmeProtocol proto);
612
613 /* If YES is non-zero, enable armor mode in CTX, disable it otherwise.  */
614 void gpgme_set_armor (GpgmeCtx ctx, int yes);
615
616 /* Return non-zero if armor mode is set in CTX.  */
617 int gpgme_get_armor (GpgmeCtx ctx);
618
619 /* If YES is non-zero, enable text mode in CTX, disable it otherwise.  */
620 void gpgme_set_textmode (GpgmeCtx ctx, int yes);
621
622 /* Return non-zero if text mode is set in CTX.  */
623 int gpgme_get_textmode (GpgmeCtx ctx);
624
625 /* Include up to NR_OF_CERTS certificates in an S/MIME message.  */
626 void gpgme_set_include_certs (GpgmeCtx ctx, int nr_of_certs);
627
628 /* Return the number of certs to include in an S/MIME message.  */
629 int gpgme_get_include_certs (GpgmeCtx ctx);
630
631 /* The available keylist mode flags.  */
632 enum
633   {
634     GPGME_KEYLIST_MODE_LOCAL  = 1,
635     GPGME_KEYLIST_MODE_EXTERN = 2,
636     GPGME_KEYLIST_MODE_SIGS   = 4
637   };
638
639 /* Set keylist mode in CTX to MODE.  */
640 GpgmeError gpgme_set_keylist_mode (GpgmeCtx ctx, int mode);
641
642 /* Get keylist mode in CTX.  */
643 int gpgme_get_keylist_mode (GpgmeCtx ctx);
644
645 /* Set the passphrase callback function in CTX to CB.  HOOK_VALUE is
646    passed as first argument to the passphrase callback function.  */
647 void gpgme_set_passphrase_cb (GpgmeCtx ctx,
648                               GpgmePassphraseCb cb, void *hook_value);
649
650 /* Get the current passphrase callback function in *CB and the current
651    hook value in *HOOK_VALUE.  */
652 void gpgme_get_passphrase_cb (GpgmeCtx ctx, GpgmePassphraseCb *cb,
653                               void **hook_value);
654
655 /* Set the progress callback function in CTX to CB.  HOOK_VALUE is
656    passed as first argument to the progress callback function.  */
657 void gpgme_set_progress_cb (GpgmeCtx c, GpgmeProgressCb cb, void *hook_value);
658
659 /* Get the current progress callback function in *CB and the current
660    hook value in *HOOK_VALUE.  */
661 void gpgme_get_progress_cb (GpgmeCtx ctx, GpgmeProgressCb *cb,
662                             void **hook_value);
663
664 \f
665 /* Return a statically allocated string with the name of the public
666    key algorithm ALGO, or NULL if that name is not known.  */
667 const char *gpgme_pubkey_algo_name (GpgmePubKeyAlgo algo);
668
669 /* Return a statically allocated string with the name of the hash
670    algorithm ALGO, or NULL if that name is not known.  */
671 const char *gpgme_hash_algo_name (GpgmeHashAlgo algo);
672
673 \f
674 /* Delete all signers from CTX.  */
675 void gpgme_signers_clear (GpgmeCtx ctx);
676
677 /* Add KEY to list of signers in CTX.  */
678 GpgmeError gpgme_signers_add (GpgmeCtx ctx, const GpgmeKey key);
679
680 /* Return the SEQth signer's key in CTX.  */
681 GpgmeKey gpgme_signers_enum (const GpgmeCtx ctx, int seq);
682
683 /* Retrieve the signature status of signature IDX in CTX after a
684    successful verify operation in R_STAT (if non-null).  The creation
685    time stamp of the signature is returned in R_CREATED (if non-null).
686    The function returns a string containing the fingerprint.  */
687 const char *gpgme_get_sig_status (GpgmeCtx ctx, int idx,
688                                   GpgmeSigStat *r_stat, time_t *r_created);
689
690 /* Retrieve certain attributes of a signature.  IDX is the index
691    number of the signature after a successful verify operation.  WHAT
692    is an attribute where GPGME_ATTR_EXPIRE is probably the most useful
693    one.  WHATIDX is to be passed as 0 for most attributes . */
694 unsigned long gpgme_get_sig_ulong_attr (GpgmeCtx c, int idx,
695                                         GpgmeAttr what, int whatidx);
696 const char *gpgme_get_sig_string_attr (GpgmeCtx c, int idx,
697                                       GpgmeAttr what, int whatidx);
698
699
700 /* Get the key used to create signature IDX in CTX and return it in
701    R_KEY.  */
702 GpgmeError gpgme_get_sig_key (GpgmeCtx ctx, int idx, GpgmeKey *r_key);
703
704 \f
705 /* Run control.  */
706
707 /* The type of an I/O callback function.  */
708 typedef GpgmeError (*GpgmeIOCb) (void *data, int fd);
709
710 /* The type of a function that can register FNC as the I/O callback
711    function for the file descriptor FD with direction dir (0: for writing,
712    1: for reading).  FNC_DATA should be passed as DATA to FNC.  The
713    function should return a TAG suitable for the corresponding
714    GpgmeRemoveIOCb, and an error value.  */
715 typedef GpgmeError (*GpgmeRegisterIOCb) (void *data, int fd, int dir,
716                                          GpgmeIOCb fnc, void *fnc_data,
717                                          void **tag);
718
719 /* The type of a function that can remove a previously registered I/O
720    callback function given TAG as returned by the register
721    function.  */
722 typedef void (*GpgmeRemoveIOCb) (void *tag);
723
724 typedef enum { GPGME_EVENT_START,
725                GPGME_EVENT_DONE,
726                GPGME_EVENT_NEXT_KEY,
727                GPGME_EVENT_NEXT_TRUSTITEM } GpgmeEventIO;
728
729 /* The type of a function that is called when a context finished an
730    operation.  */
731 typedef void (*GpgmeEventIOCb) (void *data, GpgmeEventIO type,
732                                 void *type_data);
733
734 struct GpgmeIOCbs
735 {
736   GpgmeRegisterIOCb add;
737   void *add_priv;
738   GpgmeRemoveIOCb remove;
739   GpgmeEventIOCb event;
740   void *event_priv;
741 };
742
743 /* Set the I/O callback functions in CTX to IO_CBS.  */
744 void gpgme_set_io_cbs (GpgmeCtx ctx, struct GpgmeIOCbs *io_cbs);
745
746 /* Get the current I/O callback functions.  */
747 void gpgme_get_io_cbs (GpgmeCtx ctx, struct GpgmeIOCbs *io_cbs);
748
749 /* Process the pending operation and, if HANG is non-zero, wait for
750    the pending operation to finish.  */
751 GpgmeCtx gpgme_wait (GpgmeCtx ctx, GpgmeError *status, int hang);
752
753 \f
754 /* Functions to handle recipients.  */
755
756 /* Create a new recipients set and return it in R_RSET.  */
757 GpgmeError gpgme_recipients_new (GpgmeRecipients *r_rset);
758
759 /* Release the recipients set RSET.  */
760 void gpgme_recipients_release (GpgmeRecipients rset);
761
762 /* Add NAME to the recipients set RSET.  */
763 GpgmeError gpgme_recipients_add_name (GpgmeRecipients rset, const char *name);
764
765 /* Add NAME with validity AL to the recipients set RSET.  */
766 GpgmeError gpgme_recipients_add_name_with_validity (GpgmeRecipients rset,
767                                                     const char *name,
768                                                     GpgmeValidity val);
769
770 /* Return the number of recipients in RSET.  */
771 unsigned int gpgme_recipients_count (const GpgmeRecipients rset);
772
773 /* Create a new enumeration handle for the recipients set RSET and
774    return it in ITER.  */
775 GpgmeError gpgme_recipients_enum_open (const GpgmeRecipients rset,
776                                        void **iter);
777
778 /* Return the next recipient from the recipient set RSET in the
779    enumerator ITER.  */
780 const char *gpgme_recipients_enum_read (const GpgmeRecipients rset,
781                                         void **iter);
782
783 /* Destroy the enumerator ITER for the recipient set RSET.  */
784 GpgmeError gpgme_recipients_enum_close (const GpgmeRecipients rset,
785                                         void **iter);
786
787 \f
788 /* Functions to handle data objects.  */
789
790 /* Read up to SIZE bytes into buffer BUFFER from the data object with
791    the handle HANDLE.  Return the number of characters read, 0 on EOF
792    and -1 on error.  If an error occurs, errno is set.  */
793 typedef ssize_t (*GpgmeDataReadCb) (void *handle, void *buffer, size_t size);
794
795 /* Write up to SIZE bytes from buffer BUFFER to the data object with
796    the handle HANDLE.  Return the number of characters written, or -1
797    on error.  If an error occurs, errno is set.  */
798 typedef ssize_t (*GpgmeDataWriteCb) (void *handle, const void *buffer,
799                                      size_t size);
800
801 /* Set the current position from where the next read or write starts
802    in the data object with the handle HANDLE to OFFSET, relativ to
803    WHENCE.  */
804 typedef off_t (*GpgmeDataSeekCb) (void *handle, off_t offset, int whence);
805
806 /* Close the data object with the handle DL.  */
807 typedef void (*GpgmeDataReleaseCb) (void *handle);
808
809 struct GpgmeDataCbs
810 {
811   GpgmeDataReadCb read;
812   GpgmeDataWriteCb write;
813   GpgmeDataSeekCb seek;
814   GpgmeDataReleaseCb release;
815 };
816
817 /* Read up to SIZE bytes into buffer BUFFER from the data object with
818    the handle DH.  Return the number of characters read, 0 on EOF and
819    -1 on error.  If an error occurs, errno is set.  */
820 ssize_t gpgme_data_read (GpgmeData dh, void *buffer, size_t size);
821
822 /* Write up to SIZE bytes from buffer BUFFER to the data object with
823    the handle DH.  Return the number of characters written, or -1 on
824    error.  If an error occurs, errno is set.  */
825 ssize_t gpgme_data_write (GpgmeData dh, const void *buffer, size_t size);
826
827 /* Set the current position from where the next read or write starts
828    in the data object with the handle DH to OFFSET, relativ to
829    WHENCE.  */
830 off_t gpgme_data_seek (GpgmeData dh, off_t offset, int whence);
831
832 /* Create a new data buffer and return it in R_DH.  */
833 GpgmeError gpgme_data_new (GpgmeData *r_dh);
834
835 /* Destroy the data buffer DH.  */
836 void gpgme_data_release (GpgmeData dh);
837
838 /* Create a new data buffer filled with SIZE bytes starting from
839    BUFFER.  If COPY is zero, copying is delayed until necessary, and
840    the data is taken from the original location when needed.  */
841 GpgmeError gpgme_data_new_from_mem (GpgmeData *r_dh,
842                                     const char *buffer, size_t size,
843                                     int copy);
844
845 /* Destroy the data buffer DH and return a pointer to its content.
846    The memory has be to released with free by the user.  It's size is
847    returned in R_LEN.  */
848 char *gpgme_data_release_and_get_mem (GpgmeData dh, size_t *r_len);
849
850 GpgmeError gpgme_data_new_from_cbs (GpgmeData *dh,
851                                     struct GpgmeDataCbs *cbs,
852                                     void *handle);
853
854 GpgmeError gpgme_data_new_from_fd (GpgmeData *dh, int fd);
855
856 GpgmeError gpgme_data_new_from_stream (GpgmeData *dh, FILE *stream);
857
858 /* Return the encoding attribute of the data buffer DH */
859 GpgmeDataEncoding gpgme_data_get_encoding (GpgmeData dh);
860
861 /* Set the encoding attribute of data buffer DH to ENC */
862 GpgmeError gpgme_data_set_encoding (GpgmeData dh, GpgmeDataEncoding enc);
863
864
865
866 /* Create a new data buffer which retrieves the data from the callback
867    function READ_CB.  Deprecated, please use gpgme_data_new_from_cbs
868    instead.  */
869 GpgmeError gpgme_data_new_with_read_cb (GpgmeData *r_dh,
870                                         int (*read_cb) (void*,char *,size_t,size_t*),
871                                         void *read_cb_value);
872
873 /* Create a new data buffer filled with the content of file FNAME.
874    COPY must be non-zero.  For delayed read, please use
875    gpgme_data_new_from_fd or gpgme_data_new_from stream instead.  */
876 GpgmeError gpgme_data_new_from_file (GpgmeData *r_dh,
877                                      const char *fname,
878                                      int copy);
879
880 /* Create a new data buffer filled with LENGTH bytes starting from
881    OFFSET within the file FNAME or stream FP (exactly one must be
882    non-zero).  */
883 GpgmeError gpgme_data_new_from_filepart (GpgmeData *r_dh,
884                                          const char *fname, FILE *fp,
885                                          off_t offset, size_t length);
886
887 /* Reset the read pointer in DH.  Deprecated, please use
888    gpgme_data_seek instead.  */
889 GpgmeError gpgme_data_rewind (GpgmeData dh);
890
891 \f
892 /* Key and trust functions.  */
893
894 /* Get the key with the fingerprint FPR from the crypto backend.  If
895    SECRET is true, get the secret key.  */
896 GpgmeError gpgme_get_key (GpgmeCtx ctx, const char *fpr, GpgmeKey *r_key,
897                           int secret);
898
899 /* Acquire a reference to KEY.  */
900 void gpgme_key_ref (GpgmeKey key);
901
902 /* Release a reference to KEY.  If this was the last one the key is
903    destroyed.  */
904 void gpgme_key_unref (GpgmeKey key);
905 void gpgme_key_release (GpgmeKey key);
906
907 /* Return the value of the attribute WHAT of KEY, which has to be
908    representable by a string.  IDX specifies the sub key or
909    user ID for attributes related to sub keys or user IDs.  */
910 const char *gpgme_key_get_string_attr (GpgmeKey key, GpgmeAttr what,
911                                        const void *reserved, int idx);
912
913 /* Return the value of the attribute WHAT of KEY, which has to be
914    representable by an unsigned integer.  IDX specifies the sub key or
915    user ID for attributes related to sub keys or user IDs.  */
916 unsigned long gpgme_key_get_ulong_attr (GpgmeKey key, GpgmeAttr what,
917                                         const void *reserved, int idx);
918
919 /* Return the value of the attribute WHAT of a signature on user ID
920    UID_IDX in KEY, which has to be representable by a string.  IDX
921    specifies the signature.  */
922 const char *gpgme_key_sig_get_string_attr (GpgmeKey key, int uid_idx,
923                                            GpgmeAttr what,
924                                            const void *reserved, int idx);
925
926 /* Return the value of the attribute WHAT of a signature on user ID
927    UID_IDX in KEY, which has to be representable by an unsigned
928    integer string.  IDX specifies the signature.  */
929 unsigned long gpgme_key_sig_get_ulong_attr (GpgmeKey key, int uid_idx,
930                                             GpgmeAttr what,
931                                             const void *reserved, int idx);
932
933 \f
934 /* Crypto Operations.  */
935
936 struct _gpgme_invalid_user_id
937 {
938   struct _gpgme_invalid_user_id *next;
939   char *id;
940   GpgmeError reason;
941 };
942 typedef struct _gpgme_invalid_user_id *GpgmeInvalidUserID;
943
944 \f
945 /* Encryption.  */
946 struct _gpgme_op_encrypt_result
947 {
948   /* The list of invalid recipients.  */
949   GpgmeInvalidUserID invalid_recipients;
950 };
951 typedef struct _gpgme_op_encrypt_result *GpgmeEncryptResult;
952
953 /* Retrieve a pointer to the result of the encrypt operation.  */
954 GpgmeEncryptResult gpgme_op_encrypt_result (GpgmeCtx ctx);
955
956 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
957    store the resulting ciphertext in CIPHER.  */
958 GpgmeError gpgme_op_encrypt_start (GpgmeCtx ctx,
959                                    GpgmeRecipients recp,
960                                    GpgmeData plain, GpgmeData cipher);
961 GpgmeError gpgme_op_encrypt (GpgmeCtx ctx,
962                              GpgmeRecipients recp,
963                              GpgmeData plain, GpgmeData cipher);
964
965 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
966    store the resulting ciphertext in CIPHER.  Also sign the ciphertext
967    with the signers in CTX.  */
968 GpgmeError gpgme_op_encrypt_sign_start (GpgmeCtx ctx,
969                                         GpgmeRecipients recp,
970                                         GpgmeData plain, GpgmeData cipher);
971 GpgmeError gpgme_op_encrypt_sign (GpgmeCtx ctx,
972                                   GpgmeRecipients recp,
973                                   GpgmeData plain, GpgmeData cipher);
974
975 \f
976 /* Decryption.  */
977 struct _gpgme_op_decrypt_result
978 {
979   char *unsupported_algorithm;
980 };
981 typedef struct _gpgme_op_decrypt_result *GpgmeDecryptResult;
982
983 /* Retrieve a pointer to the result of the decrypt operation.  */
984 GpgmeDecryptResult gpgme_op_decrypt_result (GpgmeCtx ctx);
985
986 /* Decrypt ciphertext CIPHER within CTX and store the resulting
987    plaintext in PLAIN.  */
988 GpgmeError gpgme_op_decrypt_start (GpgmeCtx ctx,
989                                    GpgmeData cipher, GpgmeData plain);
990 GpgmeError gpgme_op_decrypt (GpgmeCtx ctx,
991                              GpgmeData cipher, GpgmeData plain);
992
993 /* Decrypt ciphertext CIPHER and make a signature verification within
994    CTX and store the resulting plaintext in PLAIN.  */
995 GpgmeError gpgme_op_decrypt_verify_start (GpgmeCtx ctx,
996                                           GpgmeData cipher, GpgmeData plain);
997 GpgmeError gpgme_op_decrypt_verify (GpgmeCtx ctx,
998                                     GpgmeData cipher, GpgmeData plain);
999
1000 \f
1001 /* Signing.  */
1002 struct _gpgme_new_signature
1003 {
1004   struct _gpgme_new_signature *next;
1005   GpgmeSigMode type;
1006   GpgmePubKeyAlgo pubkey_algo;
1007   GpgmeHashAlgo hash_algo;
1008   unsigned long class;
1009   long int timestamp;
1010   char *fpr;
1011 };
1012 typedef struct _gpgme_new_signature *GpgmeNewSignature;
1013
1014 struct _gpgme_op_sign_result
1015 {
1016   /* The list of invalid signers.  */
1017   GpgmeInvalidUserID invalid_signers;
1018   GpgmeNewSignature signatures;
1019 };
1020 typedef struct _gpgme_op_sign_result *GpgmeSignResult;
1021
1022 /* Retrieve a pointer to the result of the signing operation.  */
1023 GpgmeSignResult gpgme_op_sign_result (GpgmeCtx ctx);
1024
1025 /* Sign the plaintext PLAIN and store the signature in SIG.  */
1026 GpgmeError gpgme_op_sign_start (GpgmeCtx ctx,
1027                                 GpgmeData plain, GpgmeData sig,
1028                                 GpgmeSigMode mode);
1029 GpgmeError gpgme_op_sign (GpgmeCtx ctx,
1030                           GpgmeData plain, GpgmeData sig,
1031                           GpgmeSigMode mode);
1032
1033 \f
1034 /* Verify.  */
1035 struct _gpgme_sig_notation
1036 {
1037   struct _gpgme_sig_notation *next;
1038
1039   /* If NAME is a null pointer, then VALUE contains a policy URL
1040      rather than a notation.  */
1041   char *name;
1042   char *value;
1043 };
1044 typedef struct _gpgme_sig_notation *GpgmeSigNotation;
1045
1046 /* Flags used for the SUMMARY field in a GpgmeSignature.  */
1047 enum 
1048   {
1049     GPGME_SIGSUM_VALID       = 0x0001,  /* The signature is fully valid.  */
1050     GPGME_SIGSUM_GREEN       = 0x0002,  /* The signature is good.  */
1051     GPGME_SIGSUM_RED         = 0x0004,  /* The signature is bad.  */
1052     GPGME_SIGSUM_KEY_REVOKED = 0x0010,  /* One key has been revoked.  */
1053     GPGME_SIGSUM_KEY_EXPIRED = 0x0020,  /* One key has expired.  */
1054     GPGME_SIGSUM_SIG_EXPIRED = 0x0040,  /* The signature has expired.  */
1055     GPGME_SIGSUM_KEY_MISSING = 0x0080,  /* Can't verify: key missing.  */
1056     GPGME_SIGSUM_CRL_MISSING = 0x0100,  /* CRL not available.  */
1057     GPGME_SIGSUM_CRL_TOO_OLD = 0x0200,  /* Available CRL is too old.  */
1058     GPGME_SIGSUM_BAD_POLICY  = 0x0400,  /* A policy was not met.  */
1059     GPGME_SIGSUM_SYS_ERROR   = 0x0800   /* A system error occured.  */
1060   };
1061
1062 struct _gpgme_signature
1063 {
1064   struct _gpgme_signature *next;
1065
1066   /* A summary of the signature status.  */
1067   unsigned int summary;
1068
1069   /* The fingerprint or key ID of the signature.  */
1070   char *fpr;
1071
1072   /* The status of the signature.  */
1073   GpgmeError status;
1074
1075   /* Notation data and policy URLs.  */
1076   GpgmeSigNotation notations;
1077
1078   /* Signature creation time.  */
1079   unsigned long timestamp;
1080
1081   /* Signature exipration time or 0.  */
1082   unsigned long exp_timestamp;
1083
1084   int wrong_key_usage : 1;
1085
1086   /* Internal to GPGME, do not use.  */
1087   int _unused : 31;
1088
1089   GpgmeValidity validity;
1090   GpgmeError validity_reason;
1091 };
1092 typedef struct _gpgme_signature *GpgmeSignature;
1093
1094 struct _gpgme_op_verify_result
1095 {
1096   GpgmeSignature signatures;
1097 };
1098 typedef struct _gpgme_op_verify_result *GpgmeVerifyResult;
1099
1100 /* Retrieve a pointer to the result of the verify operation.  */
1101 GpgmeVerifyResult gpgme_op_verify_result (GpgmeCtx ctx);
1102
1103 /* Verify within CTX that SIG is a valid signature for TEXT.  */
1104 GpgmeError gpgme_op_verify_start (GpgmeCtx ctx, GpgmeData sig,
1105                                   GpgmeData signed_text, GpgmeData plaintext);
1106 GpgmeError gpgme_op_verify (GpgmeCtx ctx, GpgmeData sig,
1107                             GpgmeData signed_text, GpgmeData plaintext);
1108
1109 \f
1110 /* Import.  */
1111 enum
1112   {
1113     /* The key was new.  */
1114     GPGME_IMPORT_NEW = 1,
1115
1116     /* The key contained new user IDs.  */
1117     GPGME_IMPORT_UID = 2,
1118
1119     /* The key contained new signatures.  */
1120     GPGME_IMPORT_SIG = 4,
1121
1122     /* The key contained new sub keys.  */
1123     GPGME_IMPORT_SUBKEY = 8,
1124
1125     /* The key contained a secret key.  */
1126     GPGME_IMPORT_SECRET = 16
1127   };
1128
1129 struct _gpgme_import_status
1130 {
1131   struct _gpgme_import_status *next;
1132
1133   /* Fingerprint.  */
1134   char *fpr;
1135
1136   /* If a problem occured, the reason why the key could not be
1137      imported.  Otherwise GPGME_No_Error.  */
1138   GpgmeError result;
1139
1140   /* The result of the import, the GPGME_IMPORT_* values bit-wise
1141      ORed.  0 means the key was already known and no new components
1142      have been added.  */
1143   unsigned int status;
1144 };
1145 typedef struct _gpgme_import_status *GpgmeImportStatus;
1146
1147 /* Import.  */
1148 struct _gpgme_op_import_result
1149 {
1150   /* Number of considered keys.  */
1151   int considered;
1152
1153   /* Keys without user ID.  */
1154   int no_user_id;
1155
1156   /* Imported keys.  */
1157   int imported;
1158
1159   /* Imported RSA keys.  */
1160   int imported_rsa;
1161
1162   /* Unchanged keys.  */
1163   int unchanged;
1164
1165   /* Number of new user ids.  */
1166   int new_user_ids;
1167
1168   /* Number of new sub keys.  */
1169   int new_sub_keys;
1170
1171   /* Number of new signatures.  */
1172   int new_signatures;
1173
1174   /* Number of new revocations.  */
1175   int new_revocations;
1176
1177   /* Number of secret keys read.  */
1178   int secret_read;
1179
1180   /* Number of secret keys imported.  */
1181   int secret_imported;
1182
1183   /* Number of secret keys unchanged.  */
1184   int secret_unchanged;
1185
1186   /* Number of keys not imported.  */
1187   int not_imported;
1188
1189   /* List of keys for which an import was attempted.  */
1190   GpgmeImportStatus imports;
1191 };
1192 typedef struct _gpgme_op_import_result *GpgmeImportResult;
1193
1194 /* Retrieve a pointer to the result of the import operation.  */
1195 GpgmeImportResult gpgme_op_import_result (GpgmeCtx ctx);
1196
1197 /* Import the key in KEYDATA into the keyring.  */
1198 GpgmeError gpgme_op_import_start (GpgmeCtx ctx, GpgmeData keydata);
1199 GpgmeError gpgme_op_import (GpgmeCtx ctx, GpgmeData keydata);
1200 GpgmeError gpgme_op_import_ext (GpgmeCtx ctx, GpgmeData keydata, int *nr);
1201
1202 \f
1203 /* Export the keys listed in RECP into KEYDATA.  */
1204 GpgmeError gpgme_op_export_start (GpgmeCtx ctx, GpgmeRecipients recp,
1205                                   GpgmeData keydata);
1206 GpgmeError gpgme_op_export (GpgmeCtx ctx, GpgmeRecipients recp,
1207                             GpgmeData keydata);
1208
1209 \f
1210 /* Key generation.  */
1211 struct _gpgme_op_genkey_result
1212 {
1213   /* A primary key was generated.  */
1214   unsigned int primary : 1;
1215
1216   /* A sub key was generated.  */
1217   unsigned int sub : 1;
1218
1219   /* Internal to GPGME, do not use.  */
1220   unsigned int _unused : 30;
1221
1222   /* The fingerprint of the generated key.  */
1223   char *fpr;
1224 };
1225 typedef struct _gpgme_op_genkey_result *GpgmeGenKeyResult;
1226
1227 /* Generate a new keypair and add it to the keyring.  PUBKEY and
1228    SECKEY should be null for now.  PARMS specifies what keys should be
1229    generated.  */
1230 GpgmeError gpgme_op_genkey_start (GpgmeCtx ctx, const char *parms,
1231                                   GpgmeData pubkey, GpgmeData seckey);
1232 GpgmeError gpgme_op_genkey (GpgmeCtx ctx, const char *parms,
1233                             GpgmeData pubkey, GpgmeData seckey);
1234
1235 /* Retrieve a pointer to the result of the genkey operation.  */
1236 GpgmeGenKeyResult gpgme_op_genkey_result (GpgmeCtx ctx);
1237
1238 \f
1239 /* Delete KEY from the keyring.  If ALLOW_SECRET is non-zero, secret
1240    keys are also deleted.  */
1241 GpgmeError gpgme_op_delete_start (GpgmeCtx ctx, const GpgmeKey key,
1242                                   int allow_secret);
1243 GpgmeError gpgme_op_delete (GpgmeCtx ctx, const GpgmeKey key,
1244                             int allow_secret);
1245
1246 /* Edit the key KEY.  Send status and command requests to FNC and
1247    output of edit commands to OUT.  */
1248 GpgmeError gpgme_op_edit_start (GpgmeCtx ctx, GpgmeKey key,
1249                           GpgmeEditCb fnc, void *fnc_value,
1250                           GpgmeData out);
1251 GpgmeError gpgme_op_edit (GpgmeCtx ctx, GpgmeKey key,
1252                           GpgmeEditCb fnc, void *fnc_value,
1253                           GpgmeData out);
1254
1255 \f
1256 /* Key management functions */
1257 struct _gpgme_op_keylist_result
1258 {
1259   unsigned int truncated : 1;
1260
1261   /* Internal to GPGME, do not use.  */
1262   unsigned int _unused : 31;
1263 };
1264 typedef struct _gpgme_op_keylist_result *GpgmeKeyListResult;
1265
1266 /* Retrieve a pointer to the result of the key listing operation.  */
1267 GpgmeKeyListResult gpgme_op_keylist_result (GpgmeCtx ctx);
1268
1269 /* Start a keylist operation within CTX, searching for keys which
1270    match PATTERN.  If SECRET_ONLY is true, only secret keys are
1271    returned.  */
1272 GpgmeError gpgme_op_keylist_start (GpgmeCtx ctx,
1273                                    const char *pattern, int secret_only);
1274 GpgmeError gpgme_op_keylist_ext_start (GpgmeCtx ctx, const char *pattern[],
1275                                        int secret_only, int reserved);
1276
1277 /* Return the next key from the keylist in R_KEY.  */
1278 GpgmeError gpgme_op_keylist_next (GpgmeCtx ctx, GpgmeKey *r_key);
1279
1280 /* Terminate a pending keylist operation within CTX.  */
1281 GpgmeError gpgme_op_keylist_end (GpgmeCtx ctx);
1282
1283 \f
1284 /* Trust items and operations.  */
1285
1286 struct _gpgme_trust_item
1287 {
1288   /* Internal to GPGME, do not use.  */
1289   unsigned int _refs;
1290
1291   /* The key ID to which the trust item belongs.  */
1292   char *keyid;
1293
1294   /* Internal to GPGME, do not use.  */
1295   char _keyid[16 + 1];
1296
1297   /* The type of the trust item, 1 refers to a key, 2 to a user ID.  */
1298   int type;
1299
1300   /* The trust level.  */
1301   int level;
1302
1303   /* The owner trust if TYPE is 1.  */
1304   char *owner_trust;
1305
1306   /* Internal to GPGME, do not use.  */
1307   char _owner_trust[2];
1308
1309   /* The calculated validity.  */
1310   char *validity;
1311  
1312   /* Internal to GPGME, do not use.  */
1313   char _validity[2];
1314
1315   /* The user name if TYPE is 2.  */
1316   char *name;
1317 };
1318 typedef struct _gpgme_trust_item *GpgmeTrustItem;
1319
1320 /* Start a trustlist operation within CTX, searching for trust items
1321    which match PATTERN.  */
1322 GpgmeError gpgme_op_trustlist_start (GpgmeCtx ctx,
1323                                      const char *pattern, int max_level);
1324
1325 /* Return the next trust item from the trustlist in R_ITEM.  */
1326 GpgmeError gpgme_op_trustlist_next (GpgmeCtx ctx, GpgmeTrustItem *r_item);
1327
1328 /* Terminate a pending trustlist operation within CTX.  */
1329 GpgmeError gpgme_op_trustlist_end (GpgmeCtx ctx);
1330
1331 /* Acquire a reference to ITEM.  */
1332 void gpgme_trust_item_ref (GpgmeTrustItem item);
1333
1334 /* Release a reference to ITEM.  If this was the last one the trust
1335    item is destroyed.  */
1336 void gpgme_trust_item_unref (GpgmeTrustItem item);
1337
1338 /* Release the trust item ITEM.  */
1339 void gpgme_trust_item_release (GpgmeTrustItem item);
1340
1341 /* Return the value of the attribute WHAT of ITEM, which has to be
1342    representable by a string.  */
1343 const char *gpgme_trust_item_get_string_attr (GpgmeTrustItem item,
1344                                               GpgmeAttr what,
1345                                               const void *reserved, int idx);
1346
1347 /* Return the value of the attribute WHAT of KEY, which has to be
1348    representable by an integer.  IDX specifies a running index if the
1349    attribute appears more than once in the key.  */
1350 int gpgme_trust_item_get_int_attr (GpgmeTrustItem item, GpgmeAttr what,
1351                                    const void *reserved, int idx);
1352
1353 \f
1354 /* Various functions.  */
1355
1356 /* Check that the library fulfills the version requirement.  */
1357 const char *gpgme_check_version (const char *req_version);
1358
1359 /* Retrieve information about the backend engines.  */
1360 GpgmeError gpgme_get_engine_info (GpgmeEngineInfo *engine_info);
1361
1362 /* Return a string describing ERR.  */
1363 const char *gpgme_strerror (GpgmeError err);
1364
1365 \f
1366 /* Engine support functions.  */
1367
1368 /* Verify that the engine implementing PROTO is installed and
1369    available.  */
1370 GpgmeError gpgme_engine_check_version (GpgmeProtocol proto);
1371
1372
1373 #ifdef __cplusplus
1374 }
1375 #endif
1376 #endif /* GPGME_H */