doc/
[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.7-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 /* Get the protocol used with CTX */
237 GpgmeProtocol gpgme_get_protocol (GpgmeCtx ctx);
238
239 /* If YES is non-zero, enable armor mode in CTX, disable it otherwise.  */
240 void gpgme_set_armor (GpgmeCtx ctx, int yes);
241
242 /* Return non-zero if armor mode is set in CTX.  */
243 int gpgme_get_armor (GpgmeCtx ctx);
244
245 /* If YES is non-zero, enable text mode in CTX, disable it otherwise.  */
246 void gpgme_set_textmode (GpgmeCtx ctx, int yes);
247
248 /* Return non-zero if text mode is set in CTX.  */
249 int gpgme_get_textmode (GpgmeCtx ctx);
250
251 /* Include up to NR_OF_CERTS certificates in an S/MIME message.  */
252 void gpgme_set_include_certs (GpgmeCtx ctx, int nr_of_certs);
253
254 /* Return the number of certs to include in an S/MIME message.  */
255 int gpgme_get_include_certs (GpgmeCtx ctx);
256
257 /* Set keylist mode in CTX to MODE.  */
258 GpgmeError gpgme_set_keylist_mode (GpgmeCtx ctx, int mode);
259
260 /* Get keylist mode in CTX.  */
261 int gpgme_get_keylist_mode (GpgmeCtx ctx);
262
263 /* Set the passphrase callback function in CTX to CB.  HOOK_VALUE is
264    passed as first argument to the passphrase callback function.  */
265 void gpgme_set_passphrase_cb (GpgmeCtx ctx,
266                               GpgmePassphraseCb cb, void *hook_value);
267
268 /* Get the current passphrase callback function in *CB and the current
269    hook value in *HOOK_VALUE.  */
270 void gpgme_get_passphrase_cb (GpgmeCtx ctx, GpgmePassphraseCb *cb,
271                               void **hook_value);
272
273 /* Set the progress callback function in CTX to CB.  HOOK_VALUE is
274    passed as first argument to the progress callback function.  */
275 void gpgme_set_progress_cb (GpgmeCtx c, GpgmeProgressCb cb, void *hook_value);
276
277 /* Get the current progress callback function in *CB and the current
278    hook value in *HOOK_VALUE.  */
279 void gpgme_get_progress_cb (GpgmeCtx ctx, GpgmeProgressCb *cb,
280                             void **hook_value);
281
282 /* Delete all signers from CTX.  */
283 void gpgme_signers_clear (GpgmeCtx ctx);
284
285 /* Add KEY to list of signers in CTX.  */
286 GpgmeError gpgme_signers_add (GpgmeCtx ctx, const GpgmeKey key);
287
288 /* Return the SEQth signer's key in CTX.  */
289 GpgmeKey gpgme_signers_enum (const GpgmeCtx ctx, int seq);
290
291 /* Retrieve the signature status of signature IDX in CTX after a
292    successful verify operation in R_STAT (if non-null).  The creation
293    time stamp of the signature is returned in R_CREATED (if non-null).
294    The function returns a string containing the fingerprint.  */
295 const char *gpgme_get_sig_status (GpgmeCtx ctx, int idx,
296                                   GpgmeSigStat *r_stat, time_t *r_created);
297
298 /* Retrieve certain attributes of a signature.  IDX is the index
299    number of the signature after a successful verify operation.  WHAT
300    is an attribute where GPGME_ATTR_EXPIRE is probably the most useful
301    one.  RESERVED must be passed as 0. */
302 unsigned long gpgme_get_sig_ulong_attr (GpgmeCtx c, int idx,
303                                         GpgmeAttr what, int reserved);
304 const char *gpgme_get_sig_string_attr (GpgmeCtx c, int idx,
305                                       GpgmeAttr what, int reserved);
306
307
308 /* Get the key used to create signature IDX in CTX and return it in
309    R_KEY.  */
310 GpgmeError gpgme_get_sig_key (GpgmeCtx ctx, int idx, GpgmeKey *r_key);
311
312 /* Return a string with more info about the last crypto operating in CTX.
313    RESERVED should be zero.  The user has to free the string.  */
314 char *gpgme_get_op_info (GpgmeCtx ctx, int reserved);
315
316
317 /* Run control.  */
318
319 /* Cancel a pending operation in CTX.  */
320 void       gpgme_cancel (GpgmeCtx ctx);
321
322 /* Process the pending operation and, if HANG is non-zero, wait for
323    the pending operation to finish.  */
324 GpgmeCtx gpgme_wait (GpgmeCtx ctx, GpgmeError *status, int hang);
325
326
327 /* Functions to handle recipients.  */
328
329 /* Create a new recipients set and return it in R_RSET.  */
330 GpgmeError gpgme_recipients_new (GpgmeRecipients *r_rset);
331
332 /* Release the recipients set RSET.  */
333 void gpgme_recipients_release (GpgmeRecipients rset);
334
335 /* Add NAME to the recipients set RSET.  */
336 GpgmeError gpgme_recipients_add_name (GpgmeRecipients rset, const char *name);
337
338 /* Add NAME with validity AL to the recipients set RSET.  */
339 GpgmeError gpgme_recipients_add_name_with_validity (GpgmeRecipients rset,
340                                                     const char *name,
341                                                     GpgmeValidity val);
342
343 /* Return the number of recipients in RSET.  */
344 unsigned int gpgme_recipients_count (const GpgmeRecipients rset);
345
346 /* Create a new enumeration handle for the recipients set RSET and
347    return it in ITER.  */
348 GpgmeError gpgme_recipients_enum_open (const GpgmeRecipients rset,
349                                        void **iter);
350
351 /* Return the next recipient from the recipient set RSET in the
352    enumerator ITER.  */
353 const char *gpgme_recipients_enum_read (const GpgmeRecipients rset,
354                                         void **iter);
355
356 /* Destroy the enumerator ITER for the recipient set RSET.  */
357 GpgmeError gpgme_recipients_enum_close (const GpgmeRecipients rset,
358                                         void **iter);
359
360
361 /* Functions to handle data objects.  */
362
363 /* Create a new data buffer and return it in R_DH.  */
364 GpgmeError gpgme_data_new (GpgmeData *r_dh);
365
366 /* Create a new data buffer filled with SIZE bytes starting from
367    BUFFER.  If COPY is zero, copying is delayed until necessary, and
368    the data is taken from the original location when needed.  */
369 GpgmeError gpgme_data_new_from_mem (GpgmeData *r_dh,
370                                     const char *buffer, size_t size,
371                                     int copy);
372
373 /* Create a new data buffer which retrieves the data from the callback
374    function READ_CB.  */
375 GpgmeError gpgme_data_new_with_read_cb (GpgmeData *r_dh,
376                                         int (*read_cb) (void*,char *,size_t,size_t*),
377                                         void *read_cb_value);
378
379 /* Create a new data buffer filled with the content of file FNAME.
380    COPY must be non-zero (delayed reads are not supported yet).  */
381 GpgmeError gpgme_data_new_from_file (GpgmeData *r_dh,
382                                      const char *fname,
383                                      int copy);
384
385 /* Create a new data buffer filled with LENGTH bytes starting from
386    OFFSET within the file FNAME or stream FP (exactly one must be
387    non-zero).  */
388 GpgmeError gpgme_data_new_from_filepart (GpgmeData *r_dh,
389                                          const char *fname, FILE *fp,
390                                          off_t offset, size_t length);
391
392 /* Destroy the data buffer DH.  */
393 void gpgme_data_release (GpgmeData dh);
394
395 /* Destroy the data buffer DH and return a pointer to its content.
396    The memory has be to released with free by the user.  It's size is
397    returned in R_LEN.  */
398 char *gpgme_data_release_and_get_mem (GpgmeData dh, size_t *r_len);
399
400 /* Return the type of the data buffer DH.  */
401 GpgmeDataType gpgme_data_get_type (GpgmeData dh);
402
403 /* Return the encoding attribute of the data buffer DH */
404 GpgmeDataEncoding gpgme_data_get_encoding (GpgmeData dh);
405
406 /* Set the encoding attribute of data buffer DH to ENC */
407 GpgmeError gpgme_data_set_encoding (GpgmeData dh, GpgmeDataEncoding enc);
408
409 /* Reset the read pointer in DH.  */
410 GpgmeError gpgme_data_rewind (GpgmeData dh);
411
412 /* Read LENGTH bytes from the data object DH and store them in the
413    memory starting at BUFFER.  The number of bytes actually read is
414    returned in NREAD.  */
415 GpgmeError gpgme_data_read (GpgmeData dh, void *buffer,
416                             size_t length, size_t *nread);
417
418 /* Write LENGTH bytes starting from BUFFER into the data object DH.  */
419 GpgmeError gpgme_data_write (GpgmeData dh, const void *buffer, size_t length);
420
421
422 /* Key and trust functions.  */
423
424 /* Acquire a reference to KEY.  */
425 void gpgme_key_ref (GpgmeKey key);
426
427 /* Release a reference to KEY.  If this was the last one the key is
428    destroyed.  */
429 void gpgme_key_unref (GpgmeKey key);
430 void gpgme_key_release (GpgmeKey key);
431
432 /* Get the data from key KEY in a XML string, which has to be released
433    with free by the user.  */
434 char *gpgme_key_get_as_xml (GpgmeKey key);
435
436 /* Return the value of the attribute WHAT of KEY, which has to be
437    representable by a string.  IDX specifies a running index if the
438    attribute appears more than once in the key.  */
439 const char *gpgme_key_get_string_attr (GpgmeKey key, GpgmeAttr what,
440                                        const void *reserved, int idx);
441
442 /* Return the value of the attribute WHAT of KEY, which has to be
443    representable by an unsigned integer.  IDX specifies a running
444    index if the attribute appears more than once in the key.  */
445 unsigned long gpgme_key_get_ulong_attr (GpgmeKey key, GpgmeAttr what,
446                                         const void *reserved, int idx);
447
448 /* Release the trust item ITEM.  */
449 void gpgme_trust_item_release (GpgmeTrustItem item);
450
451 /* Return the value of the attribute WHAT of ITEM, which has to be
452    representable by a string.  IDX specifies a running index if the
453    attribute appears more than once in the key.  */
454 const char *gpgme_trust_item_get_string_attr (GpgmeTrustItem item,
455                                               GpgmeAttr what,
456                                               const void *reserved, int idx);
457
458 /* Return the value of the attribute WHAT of KEY, which has to be
459    representable by an integer.  IDX specifies a running index if the
460    attribute appears more than once in the key.  */
461 int gpgme_trust_item_get_int_attr (GpgmeTrustItem item, GpgmeAttr what,
462                                    const void *reserved, int idx);
463
464
465 /* Crypto operation function.  */
466
467 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
468    store the resulting ciphertext in CIPHER.  */
469 GpgmeError gpgme_op_encrypt_start (GpgmeCtx ctx,
470                                    GpgmeRecipients recp,
471                                    GpgmeData plain, GpgmeData cipher);
472 GpgmeError gpgme_op_encrypt (GpgmeCtx ctx,
473                              GpgmeRecipients recp,
474                              GpgmeData plain, GpgmeData cipher);
475
476 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
477    store the resulting ciphertext in CIPHER.  Also sign the ciphertext
478    with the signers in CTX.  */
479 GpgmeError gpgme_op_encrypt_sign_start (GpgmeCtx ctx,
480                                         GpgmeRecipients recp,
481                                         GpgmeData plain, GpgmeData cipher);
482 GpgmeError gpgme_op_encrypt_sign (GpgmeCtx ctx,
483                                   GpgmeRecipients recp,
484                                   GpgmeData plain, GpgmeData cipher);
485
486 /* Decrypt ciphertext CIPHER within CTX and store the resulting
487    plaintext in PLAIN.  */
488 GpgmeError gpgme_op_decrypt_start (GpgmeCtx ctx,
489                                    GpgmeData cipher, GpgmeData plain);
490 GpgmeError gpgme_op_decrypt (GpgmeCtx ctx,
491                              GpgmeData cipher, GpgmeData plain);
492
493 /* Decrypt ciphertext CIPHER and make a signature verification within
494    CTX and store the resulting plaintext in PLAIN.  */
495 GpgmeError gpgme_op_decrypt_verify_start (GpgmeCtx ctx,
496                                           GpgmeData cipher, GpgmeData plain);
497 GpgmeError gpgme_op_decrypt_verify (GpgmeCtx ctx,
498                                     GpgmeData cipher, GpgmeData plain,
499                                     GpgmeSigStat *r_status);
500
501 /* Sign the plaintext PLAIN and store the signature in SIG.  Only
502    detached signatures are supported for now.  */
503 GpgmeError gpgme_op_sign_start (GpgmeCtx ctx,
504                                 GpgmeData plain, GpgmeData sig,
505                                 GpgmeSigMode mode);
506 GpgmeError gpgme_op_sign (GpgmeCtx ctx,
507                           GpgmeData plain, GpgmeData sig,
508                           GpgmeSigMode mode);
509
510 /* Verify within CTX that SIG is a valid signature for TEXT.  */
511 GpgmeError gpgme_op_verify_start (GpgmeCtx ctx,
512                                   GpgmeData sig, GpgmeData text);
513 GpgmeError gpgme_op_verify (GpgmeCtx ctx,
514                             GpgmeData sig, GpgmeData text,
515                             GpgmeSigStat *r_status);
516
517 /* Import the key in KEYDATA into the keyring.  */
518 GpgmeError gpgme_op_import_start (GpgmeCtx ctx, GpgmeData keydata);
519 GpgmeError gpgme_op_import (GpgmeCtx ctx, GpgmeData keydata);
520
521 /* Export the keys listed in RECP into KEYDATA.  */
522 GpgmeError gpgme_op_export_start (GpgmeCtx ctx, GpgmeRecipients recp,
523                                   GpgmeData keydata);
524 GpgmeError gpgme_op_export (GpgmeCtx ctx, GpgmeRecipients recp,
525                             GpgmeData keydata);
526
527 /* Generate a new keypair and add it to the keyring.  PUBKEY and
528    SECKEY should be null for now.  PARMS specifies what keys should be
529    generated.  */
530 GpgmeError gpgme_op_genkey_start (GpgmeCtx ctx, const char *parms,
531                                   GpgmeData pubkey, GpgmeData seckey);
532 GpgmeError gpgme_op_genkey (GpgmeCtx ctx, const char *parms,
533                             GpgmeData pubkey, GpgmeData seckey);
534
535 /* Delete KEY from the keyring.  If ALLOW_SECRET is non-zero, secret
536    keys are also deleted.  */
537 GpgmeError gpgme_op_delete_start (GpgmeCtx ctx, const GpgmeKey key,
538                                   int allow_secret);
539 GpgmeError gpgme_op_delete (GpgmeCtx ctx, const GpgmeKey key,
540                             int allow_secret);
541
542
543 /* Key management functions */
544
545 /* Start a keylist operation within CTX, searching for keys which
546    match PATTERN.  If SECRET_ONLY is true, only secret keys are
547    returned.  */
548 GpgmeError gpgme_op_keylist_start (GpgmeCtx ctx,
549                                    const char *pattern, int secret_only);
550 GpgmeError gpgme_op_keylist_ext_start (GpgmeCtx ctx, const char *pattern[],
551                                        int secret_only, int reserved);
552
553 /* Return the next key from the keylist in R_KEY.  */
554 GpgmeError gpgme_op_keylist_next (GpgmeCtx ctx, GpgmeKey *r_key);
555
556 /* Terminate a pending keylist operation within CTX.  */
557 GpgmeError gpgme_op_keylist_end (GpgmeCtx ctx);
558
559
560 /* Start a trustlist operation within CTX, searching for trust items
561    which match PATTERN.  */
562 GpgmeError gpgme_op_trustlist_start (GpgmeCtx ctx,
563                                      const char *pattern, int max_level);
564
565 /* Return the next trust item from the trustlist in R_ITEM.  */
566 GpgmeError gpgme_op_trustlist_next (GpgmeCtx ctx, GpgmeTrustItem *r_item);
567
568 /* Terminate a pending trustlist operation within CTX.  */
569 GpgmeError gpgme_op_trustlist_end (GpgmeCtx ctx);
570
571
572 /* Various functions.  */
573
574 /* Check that the library fulfills the version requirement.  */
575 const char *gpgme_check_version (const char *req_version);
576
577 /* Check that the backend engine is available.  DEPRECATED.  */
578 GpgmeError  gpgme_check_engine (void);
579
580 /* Retrieve information about the backend engines.  */
581 const char *gpgme_get_engine_info (void);
582
583 /* Return a string describing ERR.  */
584 const char *gpgme_strerror (GpgmeError err);
585
586 /* Register an idle function.  */
587 typedef void (*GpgmeIdleFunc)(void);
588 GpgmeIdleFunc gpgme_register_idle (GpgmeIdleFunc idle);
589
590
591 /* Engine support functions.  */
592
593 /* Verify that the engine implementing PROTO is installed and
594    available.  */
595 GpgmeError gpgme_engine_check_version (GpgmeProtocol proto);
596
597
598 #ifdef __cplusplus
599 }
600 #endif
601 #endif /* GPGME_H */