* verify.c (_gpgme_verify_status_handler): Handle TRUST_* status
[gpgme.git] / gpgme / gpgme.h
1 /* gpgme.h -  GnuPG Made Easy
2  *      Copyright (C) 2000 Werner Koch (dd9jn)
3  *      Copyright (C) 2001, 2002 g10 Code GmbH
4  *
5  * This file is part of GPGME.
6  *
7  * GPGME is free software; you can redistribute it and/or modify
8  * it 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,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15  * GNU General Public License for more details.
16  *
17  * You should have received a copy of the GNU General Public License
18  * along with this program; if not, write to the Free Software
19  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
20  */
21
22 #ifndef GPGME_H
23 #define GPGME_H
24
25 #include <stdio.h> /* For FILE *.  */
26 #ifdef _MSC_VER
27   typedef long off_t;
28 #else
29 # include <sys/types.h>
30 #endif
31
32 #ifdef __cplusplus
33 extern "C" {
34 #if 0 /* just to make Emacs auto-indent happy */
35 }
36 #endif
37 #endif
38
39
40 /* The version of this header should match the one of the library.  Do
41    not use this symbol in your application, use gpgme_check_version
42    instead.  The purpose of this macro is to let autoconf (using the
43    AM_PATH_GPGME macro) check that this header matches the installed
44    library.  Warning: Do not edit the next line.  configure will do
45    that for you!  */
46 #define GPGME_VERSION "0.3.6-cvs"
47
48
49 /* The opaque data types used by GPGME.  */
50
51 /* The context holds some global state and configration options as
52    well as the results of a crypto operation.  */
53 struct gpgme_context_s;
54 typedef struct gpgme_context_s *GpgmeCtx;
55
56 /* The data object used by GPGME to exchange arbitrary data.  */
57 struct gpgme_data_s;
58 typedef struct gpgme_data_s *GpgmeData;
59
60 /* A list of recipients to be used in an encryption operation.  */
61 struct gpgme_recipients_s;
62 typedef struct gpgme_recipients_s *GpgmeRecipients;
63
64 /* A key from the keyring.  */
65 struct gpgme_key_s;
66 typedef struct gpgme_key_s *GpgmeKey;
67
68 /* A trust item.  */
69 struct gpgme_trust_item_s;
70 typedef struct gpgme_trust_item_s *GpgmeTrustItem;
71
72
73 /* The error numbers used by GPGME.  */
74 typedef enum
75   {
76     GPGME_EOF                = -1,
77     GPGME_No_Error           = 0,
78     GPGME_General_Error      = 1,
79     GPGME_Out_Of_Core        = 2,
80     GPGME_Invalid_Value      = 3,
81     GPGME_Busy               = 4,
82     GPGME_No_Request         = 5,
83     GPGME_Exec_Error         = 6,
84     GPGME_Too_Many_Procs     = 7,
85     GPGME_Pipe_Error         = 8,
86     GPGME_No_Recipients      = 9,
87     GPGME_No_Data            = 10,
88     GPGME_Conflict           = 11,
89     GPGME_Not_Implemented    = 12,
90     GPGME_Read_Error         = 13,
91     GPGME_Write_Error        = 14,
92     GPGME_Invalid_Type       = 15,
93     GPGME_Invalid_Mode       = 16,
94     GPGME_File_Error         = 17,  /* errno is set in this case.  */
95     GPGME_Decryption_Failed  = 18,
96     GPGME_No_Passphrase      = 19,
97     GPGME_Canceled           = 20,
98     GPGME_Invalid_Key        = 21,
99     GPGME_Invalid_Engine     = 22,
100     GPGME_Invalid_Recipients = 23
101   }
102 GpgmeError;
103
104 /* The possible types of GpgmeData objects.  */
105 typedef enum
106   {
107     GPGME_DATA_TYPE_NONE = 0,
108     GPGME_DATA_TYPE_MEM  = 1,
109     GPGME_DATA_TYPE_FD   = 2,
110     GPGME_DATA_TYPE_FILE = 3,
111     GPGME_DATA_TYPE_CB   = 4
112   }
113 GpgmeDataType;
114
115 /* The possible encoding mode of GpgmeData objects.  */
116 typedef enum
117   {
118     GPGME_DATA_ENCODING_NONE   = 0, /* i.e. not specified */
119     GPGME_DATA_ENCODING_BINARY = 1,
120     GPGME_DATA_ENCODING_BASE64 = 2, 
121     GPGME_DATA_ENCODING_ARMOR  = 3 /* Either PEM or OpenPGP Armor */
122   }
123 GpgmeDataEncoding;
124
125 /* The possible signature stati.  */
126 typedef enum
127   {
128     GPGME_SIG_STAT_NONE  = 0,
129     GPGME_SIG_STAT_GOOD  = 1,
130     GPGME_SIG_STAT_BAD   = 2,
131     GPGME_SIG_STAT_NOKEY = 3,
132     GPGME_SIG_STAT_NOSIG = 4,
133     GPGME_SIG_STAT_ERROR = 5,
134     GPGME_SIG_STAT_DIFF  = 6,
135     GPGME_SIG_STAT_GOOD_EXP = 7,
136     GPGME_SIG_STAT_GOOD_EXPKEY = 8
137   }
138 GpgmeSigStat;
139
140 /* The available signature modes.  */
141 typedef enum
142   {
143     GPGME_SIG_MODE_NORMAL = 0,
144     GPGME_SIG_MODE_DETACH = 1,
145     GPGME_SIG_MODE_CLEAR  = 2
146   }
147 GpgmeSigMode;
148
149 /* The available key and signature attributes.  */
150 typedef enum
151   {
152     GPGME_ATTR_KEYID        = 1,
153     GPGME_ATTR_FPR          = 2,
154     GPGME_ATTR_ALGO         = 3,
155     GPGME_ATTR_LEN          = 4,
156     GPGME_ATTR_CREATED      = 5,
157     GPGME_ATTR_EXPIRE       = 6,
158     GPGME_ATTR_OTRUST       = 7,
159     GPGME_ATTR_USERID       = 8,
160     GPGME_ATTR_NAME         = 9,
161     GPGME_ATTR_EMAIL        = 10,
162     GPGME_ATTR_COMMENT      = 11,
163     GPGME_ATTR_VALIDITY     = 12,
164     GPGME_ATTR_LEVEL        = 13,
165     GPGME_ATTR_TYPE         = 14,
166     GPGME_ATTR_IS_SECRET    = 15,
167     GPGME_ATTR_KEY_REVOKED  = 16,
168     GPGME_ATTR_KEY_INVALID  = 17,
169     GPGME_ATTR_UID_REVOKED  = 18,
170     GPGME_ATTR_UID_INVALID  = 19,
171     GPGME_ATTR_KEY_CAPS     = 20,
172     GPGME_ATTR_CAN_ENCRYPT  = 21,
173     GPGME_ATTR_CAN_SIGN     = 22,
174     GPGME_ATTR_CAN_CERTIFY  = 23,
175     GPGME_ATTR_KEY_EXPIRED  = 24,
176     GPGME_ATTR_KEY_DISABLED = 25,
177     GPGME_ATTR_SERIAL       = 26,
178     GPGME_ATTR_ISSUER       = 27,
179     GPGME_ATTR_CHAINID      = 28,
180     GPGME_ATTR_SIG_STATUS   = 29
181   }
182 GpgmeAttr;
183
184 /* The available validities for a trust item or key.  */
185 typedef enum
186   {
187     GPGME_VALIDITY_UNKNOWN   = 0,
188     GPGME_VALIDITY_UNDEFINED = 1,
189     GPGME_VALIDITY_NEVER     = 2,
190     GPGME_VALIDITY_MARGINAL  = 3,
191     GPGME_VALIDITY_FULL      = 4,
192     GPGME_VALIDITY_ULTIMATE  = 5
193   }
194 GpgmeValidity;
195
196 /* The available protocols.  */
197 typedef enum
198   {
199     GPGME_PROTOCOL_OpenPGP = 0,  /* The default mode.  */
200     GPGME_PROTOCOL_CMS     = 1,
201     GPGME_PROTOCOL_AUTO    = 2
202   }
203 GpgmeProtocol;
204
205
206 /* The available keylist mode flags.  */
207 #define GPGME_KEYLIST_MODE_LOCAL 1
208 #define GPGME_KEYLIST_MODE_EXTERN 2
209
210
211 /* Types for callback functions.  */
212
213 /* Request a passphrase from the user.  */
214 typedef const char *(*GpgmePassphraseCb) (void *hook, const char *desc,
215                                           void **r_hd);
216
217 /* Inform the user about progress made.  */
218 typedef void (*GpgmeProgressCb) (void *opaque, const char *what,
219                                  int type, int current, int total);
220
221
222 /* Context management functions.  */
223
224 /* Create a new context and return it in CTX.  */
225 GpgmeError gpgme_new (GpgmeCtx *ctx);
226
227 /* Release the context CTX.  */
228 void gpgme_release (GpgmeCtx ctx);
229
230 /* Retrieve more info about performed signature check.  */
231 char *gpgme_get_notation (GpgmeCtx ctx);
232
233 /* Set the protocol to be used by CTX to PROTO.  */
234 GpgmeError gpgme_set_protocol (GpgmeCtx ctx, GpgmeProtocol proto);
235
236 /* If YES is non-zero, enable armor mode in CTX, disable it otherwise.  */
237 void gpgme_set_armor (GpgmeCtx ctx, int yes);
238
239 /* Return non-zero if armor mode is set in CTX.  */
240 int gpgme_get_armor (GpgmeCtx ctx);
241
242 /* If YES is non-zero, enable text mode in CTX, disable it otherwise.  */
243 void gpgme_set_textmode (GpgmeCtx ctx, int yes);
244
245 /* Return non-zero if text mode is set in CTX.  */
246 int gpgme_get_textmode (GpgmeCtx ctx);
247
248 /* Include up to NR_OF_CERTS certificates in an S/MIME message.  */
249 void gpgme_set_include_certs (GpgmeCtx ctx, int nr_of_certs);
250
251 /* Return the number of certs to include in an S/MIME message.  */
252 int gpgme_get_include_certs (GpgmeCtx ctx);
253
254 /* Set keylist mode in CTX to MODE.  */
255 GpgmeError gpgme_set_keylist_mode (GpgmeCtx ctx, int mode);
256
257 /* Get keylist mode in CTX.  */
258 int gpgme_get_keylist_mode (GpgmeCtx ctx);
259
260 /* Set the passphrase callback function in CTX to CB.  HOOK_VALUE is
261    passed as first argument to the passphrase callback function.  */
262 void gpgme_set_passphrase_cb (GpgmeCtx ctx,
263                               GpgmePassphraseCb cb, void *hook_value);
264
265 /* Get the current passphrase callback function in *CB and the current
266    hook value in *HOOK_VALUE.  */
267 void gpgme_get_passphrase_cb (GpgmeCtx ctx, GpgmePassphraseCb *cb,
268                               void **hook_value);
269
270 /* Set the progress callback function in CTX to CB.  HOOK_VALUE is
271    passed as first argument to the progress callback function.  */
272 void gpgme_set_progress_cb (GpgmeCtx c, GpgmeProgressCb cb, void *hook_value);
273
274 /* Get the current progress callback function in *CB and the current
275    hook value in *HOOK_VALUE.  */
276 void gpgme_get_progress_cb (GpgmeCtx ctx, GpgmeProgressCb *cb,
277                             void **hook_value);
278
279 /* Delete all signers from CTX.  */
280 void gpgme_signers_clear (GpgmeCtx ctx);
281
282 /* Add KEY to list of signers in CTX.  */
283 GpgmeError gpgme_signers_add (GpgmeCtx ctx, const GpgmeKey key);
284
285 /* Return the SEQth signer's key in CTX.  */
286 GpgmeKey gpgme_signers_enum (const GpgmeCtx ctx, int seq);
287
288 /* Retrieve the signature status of signature IDX in CTX after a
289    successful verify operation in R_STAT (if non-null).  The creation
290    time stamp of the signature is returned in R_CREATED (if non-null).
291    The function returns a string containing the fingerprint.  */
292 const char *gpgme_get_sig_status (GpgmeCtx ctx, int idx,
293                                   GpgmeSigStat *r_stat, time_t *r_created);
294
295 /* Retrieve certain attributes of a signature.  IDX is the index
296    number of the signature after a successful verify operation.  WHAT
297    is an attribute where GPGME_ATTR_EXPIRE is probably the most useful
298    one.  RESERVED must be passed as 0. */
299 unsigned long gpgme_get_sig_ulong_attr (GpgmeCtx c, int idx,
300                                         GpgmeAttr what, int reserved);
301 const char *gpgme_get_sig_string_attr (GpgmeCtx c, int idx,
302                                       GpgmeAttr what, int reserved);
303
304
305 /* Get the key used to create signature IDX in CTX and return it in
306    R_KEY.  */
307 GpgmeError gpgme_get_sig_key (GpgmeCtx ctx, int idx, GpgmeKey *r_key);
308
309 /* Return a string with more info about the last crypto operating in CTX.
310    RESERVED should be zero.  The user has to free the string.  */
311 char *gpgme_get_op_info (GpgmeCtx ctx, int reserved);
312
313
314 /* Run control.  */
315
316 /* Cancel a pending operation in CTX.  */
317 void       gpgme_cancel (GpgmeCtx ctx);
318
319 /* Process the pending operation and, if HANG is non-zero, wait for
320    the pending operation to finish.  */
321 GpgmeCtx gpgme_wait (GpgmeCtx ctx, GpgmeError *status, int hang);
322
323
324 /* Functions to handle recipients.  */
325
326 /* Create a new recipients set and return it in R_RSET.  */
327 GpgmeError gpgme_recipients_new (GpgmeRecipients *r_rset);
328
329 /* Release the recipients set RSET.  */
330 void gpgme_recipients_release (GpgmeRecipients rset);
331
332 /* Add NAME to the recipients set RSET.  */
333 GpgmeError gpgme_recipients_add_name (GpgmeRecipients rset, const char *name);
334
335 /* Add NAME with validity AL to the recipients set RSET.  */
336 GpgmeError gpgme_recipients_add_name_with_validity (GpgmeRecipients rset,
337                                                     const char *name,
338                                                     GpgmeValidity val);
339
340 /* Return the number of recipients in RSET.  */
341 unsigned int gpgme_recipients_count (const GpgmeRecipients rset);
342
343 /* Create a new enumeration handle for the recipients set RSET and
344    return it in ITER.  */
345 GpgmeError gpgme_recipients_enum_open (const GpgmeRecipients rset,
346                                        void **iter);
347
348 /* Return the next recipient from the recipient set RSET in the
349    enumerator ITER.  */
350 const char *gpgme_recipients_enum_read (const GpgmeRecipients rset,
351                                         void **iter);
352
353 /* Destroy the enumerator ITER for the recipient set RSET.  */
354 GpgmeError gpgme_recipients_enum_close (const GpgmeRecipients rset,
355                                         void **iter);
356
357
358 /* Functions to handle data objects.  */
359
360 /* Create a new data buffer and return it in R_DH.  */
361 GpgmeError gpgme_data_new (GpgmeData *r_dh);
362
363 /* Create a new data buffer filled with SIZE bytes starting from
364    BUFFER.  If COPY is zero, copying is delayed until necessary, and
365    the data is taken from the original location when needed.  */
366 GpgmeError gpgme_data_new_from_mem (GpgmeData *r_dh,
367                                     const char *buffer, size_t size,
368                                     int copy);
369
370 /* Create a new data buffer which retrieves the data from the callback
371    function READ_CB.  */
372 GpgmeError gpgme_data_new_with_read_cb (GpgmeData *r_dh,
373                                         int (*read_cb) (void*,char *,size_t,size_t*),
374                                         void *read_cb_value);
375
376 /* Create a new data buffer filled with the content of file FNAME.
377    COPY must be non-zero (delayed reads are not supported yet).  */
378 GpgmeError gpgme_data_new_from_file (GpgmeData *r_dh,
379                                      const char *fname,
380                                      int copy);
381
382 /* Create a new data buffer filled with LENGTH bytes starting from
383    OFFSET within the file FNAME or stream FP (exactly one must be
384    non-zero).  */
385 GpgmeError gpgme_data_new_from_filepart (GpgmeData *r_dh,
386                                          const char *fname, FILE *fp,
387                                          off_t offset, size_t length);
388
389 /* Destroy the data buffer DH.  */
390 void gpgme_data_release (GpgmeData dh);
391
392 /* Destroy the data buffer DH and return a pointer to its content.
393    The memory has be to released with free by the user.  It's size is
394    returned in R_LEN.  */
395 char *gpgme_data_release_and_get_mem (GpgmeData dh, size_t *r_len);
396
397 /* Return the type of the data buffer DH.  */
398 GpgmeDataType gpgme_data_get_type (GpgmeData dh);
399
400 /* Return the encoding attribute of the data buffer DH */
401 GpgmeDataEncoding gpgme_data_get_encoding (GpgmeData dh);
402
403 /* Set the encoding attribute of data buffer DH to ENC */
404 GpgmeError gpgme_data_set_encoding (GpgmeData dh, GpgmeDataEncoding enc);
405
406 /* Reset the read pointer in DH.  */
407 GpgmeError gpgme_data_rewind (GpgmeData dh);
408
409 /* Read LENGTH bytes from the data object DH and store them in the
410    memory starting at BUFFER.  The number of bytes actually read is
411    returned in NREAD.  */
412 GpgmeError gpgme_data_read (GpgmeData dh, char *buffer,
413                             size_t length, size_t *nread);
414
415 /* Write LENGTH bytes starting from BUFFER into the data object DH.  */
416 GpgmeError gpgme_data_write (GpgmeData dh, const char *buffer, size_t length);
417
418
419 /* Key and trust functions.  */
420
421 /* Acquire a reference to KEY.  */
422 void gpgme_key_ref (GpgmeKey key);
423
424 /* Release a reference to KEY.  If this was the last one the key is
425    destroyed.  */
426 void gpgme_key_unref (GpgmeKey key);
427 void gpgme_key_release (GpgmeKey key);
428
429 /* Get the data from key KEY in a XML string, which has to be released
430    with free by the user.  */
431 char *gpgme_key_get_as_xml (GpgmeKey key);
432
433 /* Return the value of the attribute WHAT of KEY, which has to be
434    representable by a string.  IDX specifies a running index if the
435    attribute appears more than once in the key.  */
436 const char *gpgme_key_get_string_attr (GpgmeKey key, GpgmeAttr what,
437                                        const void *reserved, int idx);
438
439 /* Return the value of the attribute WHAT of KEY, which has to be
440    representable by an unsigned integer.  IDX specifies a running
441    index if the attribute appears more than once in the key.  */
442 unsigned long gpgme_key_get_ulong_attr (GpgmeKey key, GpgmeAttr what,
443                                         const void *reserved, int idx);
444
445 /* Release the trust item ITEM.  */
446 void gpgme_trust_item_release (GpgmeTrustItem item);
447
448 /* Return the value of the attribute WHAT of ITEM, which has to be
449    representable by a string.  IDX specifies a running index if the
450    attribute appears more than once in the key.  */
451 const char *gpgme_trust_item_get_string_attr (GpgmeTrustItem item,
452                                               GpgmeAttr what,
453                                               const void *reserved, int idx);
454
455 /* Return the value of the attribute WHAT of KEY, which has to be
456    representable by an integer.  IDX specifies a running index if the
457    attribute appears more than once in the key.  */
458 int gpgme_trust_item_get_int_attr (GpgmeTrustItem item, GpgmeAttr what,
459                                    const void *reserved, int idx);
460
461
462 /* Crypto operation function.  */
463
464 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
465    store the resulting ciphertext in CIPHER.  */
466 GpgmeError gpgme_op_encrypt_start (GpgmeCtx ctx,
467                                    GpgmeRecipients recp,
468                                    GpgmeData plain, GpgmeData cipher);
469 GpgmeError gpgme_op_encrypt (GpgmeCtx ctx,
470                              GpgmeRecipients recp,
471                              GpgmeData plain, GpgmeData cipher);
472
473 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
474    store the resulting ciphertext in CIPHER.  Also sign the ciphertext
475    with the signers in CTX.  */
476 GpgmeError gpgme_op_encrypt_sign_start (GpgmeCtx ctx,
477                                         GpgmeRecipients recp,
478                                         GpgmeData plain, GpgmeData cipher);
479 GpgmeError gpgme_op_encrypt_sign (GpgmeCtx ctx,
480                                   GpgmeRecipients recp,
481                                   GpgmeData plain, GpgmeData cipher);
482
483 /* Decrypt ciphertext CIPHER within CTX and store the resulting
484    plaintext in PLAIN.  */
485 GpgmeError gpgme_op_decrypt_start (GpgmeCtx ctx,
486                                    GpgmeData cipher, GpgmeData plain);
487 GpgmeError gpgme_op_decrypt (GpgmeCtx ctx,
488                              GpgmeData cipher, GpgmeData plain);
489
490 /* Decrypt ciphertext CIPHER and make a signature verification within
491    CTX and store the resulting plaintext in PLAIN.  */
492 GpgmeError gpgme_op_decrypt_verify_start (GpgmeCtx ctx,
493                                           GpgmeData cipher, GpgmeData plain);
494 GpgmeError gpgme_op_decrypt_verify (GpgmeCtx ctx,
495                                     GpgmeData cipher, GpgmeData plain,
496                                     GpgmeSigStat *r_status);
497
498 /* Sign the plaintext PLAIN and store the signature in SIG.  Only
499    detached signatures are supported for now.  */
500 GpgmeError gpgme_op_sign_start (GpgmeCtx ctx,
501                                 GpgmeData plain, GpgmeData sig,
502                                 GpgmeSigMode mode);
503 GpgmeError gpgme_op_sign (GpgmeCtx ctx,
504                           GpgmeData plain, GpgmeData sig,
505                           GpgmeSigMode mode);
506
507 /* Verify within CTX that SIG is a valid signature for TEXT.  */
508 GpgmeError gpgme_op_verify_start (GpgmeCtx ctx,
509                                   GpgmeData sig, GpgmeData text);
510 GpgmeError gpgme_op_verify (GpgmeCtx ctx,
511                             GpgmeData sig, GpgmeData text,
512                             GpgmeSigStat *r_status);
513
514 /* Import the key in KEYDATA into the keyring.  */
515 GpgmeError gpgme_op_import_start (GpgmeCtx ctx, GpgmeData keydata);
516 GpgmeError gpgme_op_import (GpgmeCtx ctx, GpgmeData keydata);
517
518 /* Export the keys listed in RECP into KEYDATA.  */
519 GpgmeError gpgme_op_export_start (GpgmeCtx ctx, GpgmeRecipients recp,
520                                   GpgmeData keydata);
521 GpgmeError gpgme_op_export (GpgmeCtx ctx, GpgmeRecipients recp,
522                             GpgmeData keydata);
523
524 /* Generate a new keypair and add it to the keyring.  PUBKEY and
525    SECKEY should be null for now.  PARMS specifies what keys should be
526    generated.  */
527 GpgmeError gpgme_op_genkey_start (GpgmeCtx ctx, const char *parms,
528                                   GpgmeData pubkey, GpgmeData seckey);
529 GpgmeError gpgme_op_genkey (GpgmeCtx ctx, const char *parms,
530                             GpgmeData pubkey, GpgmeData seckey);
531
532 /* Delete KEY from the keyring.  If ALLOW_SECRET is non-zero, secret
533    keys are also deleted.  */
534 GpgmeError gpgme_op_delete_start (GpgmeCtx ctx, const GpgmeKey key,
535                                   int allow_secret);
536 GpgmeError gpgme_op_delete (GpgmeCtx ctx, const GpgmeKey key,
537                             int allow_secret);
538
539
540 /* Key management functions */
541
542 /* Start a keylist operation within CTX, searching for keys which
543    match PATTERN.  If SECRET_ONLY is true, only secret keys are
544    returned.  */
545 GpgmeError gpgme_op_keylist_start (GpgmeCtx ctx,
546                                    const char *pattern, int secret_only);
547 GpgmeError gpgme_op_keylist_ext_start (GpgmeCtx ctx, const char *pattern[],
548                                        int secret_only, int reserved);
549
550 /* Return the next key from the keylist in R_KEY.  */
551 GpgmeError gpgme_op_keylist_next (GpgmeCtx ctx, GpgmeKey *r_key);
552
553 /* Terminate a pending keylist operation within CTX.  */
554 GpgmeError gpgme_op_keylist_end (GpgmeCtx ctx);
555
556
557 /* Start a trustlist operation within CTX, searching for trust items
558    which match PATTERN.  */
559 GpgmeError gpgme_op_trustlist_start (GpgmeCtx ctx,
560                                      const char *pattern, int max_level);
561
562 /* Return the next trust item from the trustlist in R_ITEM.  */
563 GpgmeError gpgme_op_trustlist_next (GpgmeCtx ctx, GpgmeTrustItem *r_item);
564
565 /* Terminate a pending trustlist operation within CTX.  */
566 GpgmeError gpgme_op_trustlist_end (GpgmeCtx ctx);
567
568
569 /* Various functions.  */
570
571 /* Check that the library fulfills the version requirement.  */
572 const char *gpgme_check_version (const char *req_version);
573
574 /* Check that the backend engine is available.  DEPRECATED.  */
575 GpgmeError  gpgme_check_engine (void);
576
577 /* Retrieve information about the backend engines.  */
578 const char *gpgme_get_engine_info (void);
579
580 /* Return a string describing ERR.  */
581 const char *gpgme_strerror (GpgmeError err);
582
583 /* Register an idle function.  */
584 typedef void (*GpgmeIdleFunc)(void);
585 GpgmeIdleFunc gpgme_register_idle (GpgmeIdleFunc idle);
586
587
588 /* Engine support functions.  */
589
590 /* Verify that the engine implementing PROTO is installed and
591    available.  */
592 GpgmeError gpgme_engine_check_version (GpgmeProtocol proto);
593
594
595 #ifdef __cplusplus
596 }
597 #endif
598 #endif /* GPGME_H */