2002-06-10 Marcus Brinkmann <marcus@g10code.de>
[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.8-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 /* The type of an I/O callback function.  */
320 typedef void (*GpgmeIOCb) (void *data, int fd);
321
322 /* The type of a function that can register FNC as the I/O callback
323    function for the file descriptor FD with direction dir (0: inbound,
324    1: outbound).  FNC_DATA should be passed as DATA to FNC.  The
325    function should return a TAG suitable for the corresponding
326    GpgmeRemoveIOCb.  */
327 typedef void *(*GpgmeRegisterIOCb) (void *data, int fd, int dir,
328                                     GpgmeIOCb fnc, void *fnc_data);
329
330 /* The type of a function that can remove a previously registered I/O
331    callback function given TAG as returned by the register
332    function.  */
333 typedef void (*GpgmeRemoveIOCb) (void *tag);
334
335 typedef enum { GPGME_EVENT_DONE,
336                GPGME_EVENT_NEXT_KEY,
337                GPGME_EVENT_NEXT_TRUSTITEM } GpgmeEventIO;
338
339 /* The type of a function that is called when a context finished an
340    operation.  */
341 typedef void (*GpgmeEventIOCb) (void *data, GpgmeEventIO type,
342                                 void *type_data);
343
344 struct GpgmeIOCbs
345 {
346   GpgmeRegisterIOCb add;
347   void *add_priv;
348   GpgmeRemoveIOCb remove;
349   GpgmeEventIOCb event;
350   void *event_priv;
351 };
352
353 /* Set the I/O callback functions in CTX to IO_CBS.  */
354 void gpgme_set_op_io_cbs (GpgmeCtx ctx, struct GpgmeIOCbs *io_cbs);
355
356 /* Get the current I/O callback functions.  */
357 void gpgme_get_op_io_cbs (GpgmeCtx ctx, struct GpgmeIOCbs *io_cbs);
358
359 /* Cancel a pending operation in CTX.  */
360 void       gpgme_cancel (GpgmeCtx ctx);
361
362 /* Process the pending operation and, if HANG is non-zero, wait for
363    the pending operation to finish.  */
364 GpgmeCtx gpgme_wait (GpgmeCtx ctx, GpgmeError *status, int hang);
365
366
367 /* Functions to handle recipients.  */
368
369 /* Create a new recipients set and return it in R_RSET.  */
370 GpgmeError gpgme_recipients_new (GpgmeRecipients *r_rset);
371
372 /* Release the recipients set RSET.  */
373 void gpgme_recipients_release (GpgmeRecipients rset);
374
375 /* Add NAME to the recipients set RSET.  */
376 GpgmeError gpgme_recipients_add_name (GpgmeRecipients rset, const char *name);
377
378 /* Add NAME with validity AL to the recipients set RSET.  */
379 GpgmeError gpgme_recipients_add_name_with_validity (GpgmeRecipients rset,
380                                                     const char *name,
381                                                     GpgmeValidity val);
382
383 /* Return the number of recipients in RSET.  */
384 unsigned int gpgme_recipients_count (const GpgmeRecipients rset);
385
386 /* Create a new enumeration handle for the recipients set RSET and
387    return it in ITER.  */
388 GpgmeError gpgme_recipients_enum_open (const GpgmeRecipients rset,
389                                        void **iter);
390
391 /* Return the next recipient from the recipient set RSET in the
392    enumerator ITER.  */
393 const char *gpgme_recipients_enum_read (const GpgmeRecipients rset,
394                                         void **iter);
395
396 /* Destroy the enumerator ITER for the recipient set RSET.  */
397 GpgmeError gpgme_recipients_enum_close (const GpgmeRecipients rset,
398                                         void **iter);
399
400
401 /* Functions to handle data objects.  */
402
403 /* Create a new data buffer and return it in R_DH.  */
404 GpgmeError gpgme_data_new (GpgmeData *r_dh);
405
406 /* Create a new data buffer filled with SIZE bytes starting from
407    BUFFER.  If COPY is zero, copying is delayed until necessary, and
408    the data is taken from the original location when needed.  */
409 GpgmeError gpgme_data_new_from_mem (GpgmeData *r_dh,
410                                     const char *buffer, size_t size,
411                                     int copy);
412
413 /* Create a new data buffer which retrieves the data from the callback
414    function READ_CB.  */
415 GpgmeError gpgme_data_new_with_read_cb (GpgmeData *r_dh,
416                                         int (*read_cb) (void*,char *,size_t,size_t*),
417                                         void *read_cb_value);
418
419 /* Create a new data buffer filled with the content of file FNAME.
420    COPY must be non-zero (delayed reads are not supported yet).  */
421 GpgmeError gpgme_data_new_from_file (GpgmeData *r_dh,
422                                      const char *fname,
423                                      int copy);
424
425 /* Create a new data buffer filled with LENGTH bytes starting from
426    OFFSET within the file FNAME or stream FP (exactly one must be
427    non-zero).  */
428 GpgmeError gpgme_data_new_from_filepart (GpgmeData *r_dh,
429                                          const char *fname, FILE *fp,
430                                          off_t offset, size_t length);
431
432 /* Destroy the data buffer DH.  */
433 void gpgme_data_release (GpgmeData dh);
434
435 /* Destroy the data buffer DH and return a pointer to its content.
436    The memory has be to released with free by the user.  It's size is
437    returned in R_LEN.  */
438 char *gpgme_data_release_and_get_mem (GpgmeData dh, size_t *r_len);
439
440 /* Return the type of the data buffer DH.  */
441 GpgmeDataType gpgme_data_get_type (GpgmeData dh);
442
443 /* Return the encoding attribute of the data buffer DH */
444 GpgmeDataEncoding gpgme_data_get_encoding (GpgmeData dh);
445
446 /* Set the encoding attribute of data buffer DH to ENC */
447 GpgmeError gpgme_data_set_encoding (GpgmeData dh, GpgmeDataEncoding enc);
448
449 /* Reset the read pointer in DH.  */
450 GpgmeError gpgme_data_rewind (GpgmeData dh);
451
452 /* Read LENGTH bytes from the data object DH and store them in the
453    memory starting at BUFFER.  The number of bytes actually read is
454    returned in NREAD.  */
455 GpgmeError gpgme_data_read (GpgmeData dh, void *buffer,
456                             size_t length, size_t *nread);
457
458 /* Write LENGTH bytes starting from BUFFER into the data object DH.  */
459 GpgmeError gpgme_data_write (GpgmeData dh, const void *buffer, size_t length);
460
461
462 /* Key and trust functions.  */
463
464 /* Acquire a reference to KEY.  */
465 void gpgme_key_ref (GpgmeKey key);
466
467 /* Release a reference to KEY.  If this was the last one the key is
468    destroyed.  */
469 void gpgme_key_unref (GpgmeKey key);
470 void gpgme_key_release (GpgmeKey key);
471
472 /* Get the data from key KEY in a XML string, which has to be released
473    with free by the user.  */
474 char *gpgme_key_get_as_xml (GpgmeKey key);
475
476 /* Return the value of the attribute WHAT of KEY, which has to be
477    representable by a string.  IDX specifies a running index if the
478    attribute appears more than once in the key.  */
479 const char *gpgme_key_get_string_attr (GpgmeKey key, GpgmeAttr what,
480                                        const void *reserved, int idx);
481
482 /* Return the value of the attribute WHAT of KEY, which has to be
483    representable by an unsigned integer.  IDX specifies a running
484    index if the attribute appears more than once in the key.  */
485 unsigned long gpgme_key_get_ulong_attr (GpgmeKey key, GpgmeAttr what,
486                                         const void *reserved, int idx);
487
488 /* Release the trust item ITEM.  */
489 void gpgme_trust_item_release (GpgmeTrustItem item);
490
491 /* Return the value of the attribute WHAT of ITEM, which has to be
492    representable by a string.  IDX specifies a running index if the
493    attribute appears more than once in the key.  */
494 const char *gpgme_trust_item_get_string_attr (GpgmeTrustItem item,
495                                               GpgmeAttr what,
496                                               const void *reserved, int idx);
497
498 /* Return the value of the attribute WHAT of KEY, which has to be
499    representable by an integer.  IDX specifies a running index if the
500    attribute appears more than once in the key.  */
501 int gpgme_trust_item_get_int_attr (GpgmeTrustItem item, GpgmeAttr what,
502                                    const void *reserved, int idx);
503
504
505 /* Crypto operation function.  */
506
507 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
508    store the resulting ciphertext in CIPHER.  */
509 GpgmeError gpgme_op_encrypt_start (GpgmeCtx ctx,
510                                    GpgmeRecipients recp,
511                                    GpgmeData plain, GpgmeData cipher);
512 GpgmeError gpgme_op_encrypt (GpgmeCtx ctx,
513                              GpgmeRecipients recp,
514                              GpgmeData plain, GpgmeData cipher);
515
516 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
517    store the resulting ciphertext in CIPHER.  Also sign the ciphertext
518    with the signers in CTX.  */
519 GpgmeError gpgme_op_encrypt_sign_start (GpgmeCtx ctx,
520                                         GpgmeRecipients recp,
521                                         GpgmeData plain, GpgmeData cipher);
522 GpgmeError gpgme_op_encrypt_sign (GpgmeCtx ctx,
523                                   GpgmeRecipients recp,
524                                   GpgmeData plain, GpgmeData cipher);
525
526 /* Decrypt ciphertext CIPHER within CTX and store the resulting
527    plaintext in PLAIN.  */
528 GpgmeError gpgme_op_decrypt_start (GpgmeCtx ctx,
529                                    GpgmeData cipher, GpgmeData plain);
530 GpgmeError gpgme_op_decrypt (GpgmeCtx ctx,
531                              GpgmeData cipher, GpgmeData plain);
532
533 /* Decrypt ciphertext CIPHER and make a signature verification within
534    CTX and store the resulting plaintext in PLAIN.  */
535 GpgmeError gpgme_op_decrypt_verify_start (GpgmeCtx ctx,
536                                           GpgmeData cipher, GpgmeData plain);
537 GpgmeError gpgme_op_decrypt_verify (GpgmeCtx ctx,
538                                     GpgmeData cipher, GpgmeData plain,
539                                     GpgmeSigStat *r_status);
540
541 /* Sign the plaintext PLAIN and store the signature in SIG.  Only
542    detached signatures are supported for now.  */
543 GpgmeError gpgme_op_sign_start (GpgmeCtx ctx,
544                                 GpgmeData plain, GpgmeData sig,
545                                 GpgmeSigMode mode);
546 GpgmeError gpgme_op_sign (GpgmeCtx ctx,
547                           GpgmeData plain, GpgmeData sig,
548                           GpgmeSigMode mode);
549
550 /* Verify within CTX that SIG is a valid signature for TEXT.  */
551 GpgmeError gpgme_op_verify_start (GpgmeCtx ctx,
552                                   GpgmeData sig, GpgmeData text);
553 GpgmeError gpgme_op_verify (GpgmeCtx ctx,
554                             GpgmeData sig, GpgmeData text,
555                             GpgmeSigStat *r_status);
556
557 /* Import the key in KEYDATA into the keyring.  */
558 GpgmeError gpgme_op_import_start (GpgmeCtx ctx, GpgmeData keydata);
559 GpgmeError gpgme_op_import (GpgmeCtx ctx, GpgmeData keydata);
560
561 /* Export the keys listed in RECP into KEYDATA.  */
562 GpgmeError gpgme_op_export_start (GpgmeCtx ctx, GpgmeRecipients recp,
563                                   GpgmeData keydata);
564 GpgmeError gpgme_op_export (GpgmeCtx ctx, GpgmeRecipients recp,
565                             GpgmeData keydata);
566
567 /* Generate a new keypair and add it to the keyring.  PUBKEY and
568    SECKEY should be null for now.  PARMS specifies what keys should be
569    generated.  */
570 GpgmeError gpgme_op_genkey_start (GpgmeCtx ctx, const char *parms,
571                                   GpgmeData pubkey, GpgmeData seckey);
572 GpgmeError gpgme_op_genkey (GpgmeCtx ctx, const char *parms,
573                             GpgmeData pubkey, GpgmeData seckey);
574
575 /* Delete KEY from the keyring.  If ALLOW_SECRET is non-zero, secret
576    keys are also deleted.  */
577 GpgmeError gpgme_op_delete_start (GpgmeCtx ctx, const GpgmeKey key,
578                                   int allow_secret);
579 GpgmeError gpgme_op_delete (GpgmeCtx ctx, const GpgmeKey key,
580                             int allow_secret);
581
582
583 /* Key management functions */
584
585 /* Start a keylist operation within CTX, searching for keys which
586    match PATTERN.  If SECRET_ONLY is true, only secret keys are
587    returned.  */
588 GpgmeError gpgme_op_keylist_start (GpgmeCtx ctx,
589                                    const char *pattern, int secret_only);
590 GpgmeError gpgme_op_keylist_ext_start (GpgmeCtx ctx, const char *pattern[],
591                                        int secret_only, int reserved);
592
593 /* Return the next key from the keylist in R_KEY.  */
594 GpgmeError gpgme_op_keylist_next (GpgmeCtx ctx, GpgmeKey *r_key);
595
596 /* Terminate a pending keylist operation within CTX.  */
597 GpgmeError gpgme_op_keylist_end (GpgmeCtx ctx);
598
599
600 /* Start a trustlist operation within CTX, searching for trust items
601    which match PATTERN.  */
602 GpgmeError gpgme_op_trustlist_start (GpgmeCtx ctx,
603                                      const char *pattern, int max_level);
604
605 /* Return the next trust item from the trustlist in R_ITEM.  */
606 GpgmeError gpgme_op_trustlist_next (GpgmeCtx ctx, GpgmeTrustItem *r_item);
607
608 /* Terminate a pending trustlist operation within CTX.  */
609 GpgmeError gpgme_op_trustlist_end (GpgmeCtx ctx);
610
611
612 /* Various functions.  */
613
614 /* Check that the library fulfills the version requirement.  */
615 const char *gpgme_check_version (const char *req_version);
616
617 /* Check that the backend engine is available.  DEPRECATED.  */
618 GpgmeError  gpgme_check_engine (void);
619
620 /* Retrieve information about the backend engines.  */
621 const char *gpgme_get_engine_info (void);
622
623 /* Return a string describing ERR.  */
624 const char *gpgme_strerror (GpgmeError err);
625
626 /* Register an idle function.  */
627 typedef void (*GpgmeIdleFunc)(void);
628 GpgmeIdleFunc gpgme_register_idle (GpgmeIdleFunc idle);
629
630
631 /* Engine support functions.  */
632
633 /* Verify that the engine implementing PROTO is installed and
634    available.  */
635 GpgmeError gpgme_engine_check_version (GpgmeProtocol proto);
636
637
638 #ifdef __cplusplus
639 }
640 #endif
641 #endif /* GPGME_H */