gpgme/
[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.12"
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 /* Flags used with the GPGME_ATTR_SIG_SUMMARY. */
141 enum 
142   {
143     GPGME_SIGSUM_VALID       = 0x0001,  /* The signature is fully valid */
144     GPGME_SIGSUM_GREEN       = 0x0002,  /* The signature is good. */
145     GPGME_SIGSUM_RED         = 0x0004,  /* The signature is bad. */
146     GPGME_SIGSUM_KEY_REVOKED = 0x0010,  /* One key has been revoked. */
147     GPGME_SIGSUM_KEY_EXPIRED = 0x0020,  /* One key has expired. */
148     GPGME_SIGSUM_SIG_EXPIRED = 0x0040,  /* The signature has expired. */
149     GPGME_SIGSUM_KEY_MISSING = 0x0080,  /* Can't verify: key missing. */
150     GPGME_SIGSUM_CRL_MISSING = 0x0100,  /* CRL not available. */
151     GPGME_SIGSUM_CRL_TOO_OLD = 0x0200,  /* Available CRL is too old. */
152     GPGME_SIGSUM_BAD_POLICY  = 0x0400,  /* A policy was not met. */
153     GPGME_SIGSUM_SYS_ERROR   = 0x0800   /* A system error occured. */
154   };
155
156
157 /* The available signature modes.  */
158 typedef enum
159   {
160     GPGME_SIG_MODE_NORMAL = 0,
161     GPGME_SIG_MODE_DETACH = 1,
162     GPGME_SIG_MODE_CLEAR  = 2
163   }
164 GpgmeSigMode;
165
166 /* The available key and signature attributes.  */
167 typedef enum
168   {
169     GPGME_ATTR_KEYID        = 1,
170     GPGME_ATTR_FPR          = 2,
171     GPGME_ATTR_ALGO         = 3,
172     GPGME_ATTR_LEN          = 4,
173     GPGME_ATTR_CREATED      = 5,
174     GPGME_ATTR_EXPIRE       = 6,
175     GPGME_ATTR_OTRUST       = 7,
176     GPGME_ATTR_USERID       = 8,
177     GPGME_ATTR_NAME         = 9,
178     GPGME_ATTR_EMAIL        = 10,
179     GPGME_ATTR_COMMENT      = 11,
180     GPGME_ATTR_VALIDITY     = 12,
181     GPGME_ATTR_LEVEL        = 13,
182     GPGME_ATTR_TYPE         = 14,
183     GPGME_ATTR_IS_SECRET    = 15,
184     GPGME_ATTR_KEY_REVOKED  = 16,
185     GPGME_ATTR_KEY_INVALID  = 17,
186     GPGME_ATTR_UID_REVOKED  = 18,
187     GPGME_ATTR_UID_INVALID  = 19,
188     GPGME_ATTR_KEY_CAPS     = 20,
189     GPGME_ATTR_CAN_ENCRYPT  = 21,
190     GPGME_ATTR_CAN_SIGN     = 22,
191     GPGME_ATTR_CAN_CERTIFY  = 23,
192     GPGME_ATTR_KEY_EXPIRED  = 24,
193     GPGME_ATTR_KEY_DISABLED = 25,
194     GPGME_ATTR_SERIAL       = 26,
195     GPGME_ATTR_ISSUER       = 27,
196     GPGME_ATTR_CHAINID      = 28,
197     GPGME_ATTR_SIG_STATUS   = 29,
198     GPGME_ATTR_ERRTOK       = 30,
199     GPGME_ATTR_SIG_SUMMARY  = 31
200   }
201 GpgmeAttr;
202
203 /* The available validities for a trust item or key.  */
204 typedef enum
205   {
206     GPGME_VALIDITY_UNKNOWN   = 0,
207     GPGME_VALIDITY_UNDEFINED = 1,
208     GPGME_VALIDITY_NEVER     = 2,
209     GPGME_VALIDITY_MARGINAL  = 3,
210     GPGME_VALIDITY_FULL      = 4,
211     GPGME_VALIDITY_ULTIMATE  = 5
212   }
213 GpgmeValidity;
214
215 /* The available protocols.  */
216 typedef enum
217   {
218     GPGME_PROTOCOL_OpenPGP = 0,  /* The default mode.  */
219     GPGME_PROTOCOL_CMS     = 1,
220     GPGME_PROTOCOL_AUTO    = 2
221   }
222 GpgmeProtocol;
223
224
225 /* The possible stati for the edit operation.  */
226
227 typedef enum  {
228     GPGME_STATUS_EOF,
229     /* mkstatus starts here */
230     GPGME_STATUS_ENTER              , 
231     GPGME_STATUS_LEAVE              ,
232     GPGME_STATUS_ABORT              ,
233
234     GPGME_STATUS_GOODSIG            ,
235     GPGME_STATUS_BADSIG             ,
236     GPGME_STATUS_ERRSIG             ,
237
238     GPGME_STATUS_BADARMOR           ,
239
240     GPGME_STATUS_RSA_OR_IDEA        ,
241     GPGME_STATUS_KEYEXPIRED         ,
242     GPGME_STATUS_KEYREVOKED         ,
243
244     GPGME_STATUS_TRUST_UNDEFINED    ,
245     GPGME_STATUS_TRUST_NEVER        ,
246     GPGME_STATUS_TRUST_MARGINAL     ,
247     GPGME_STATUS_TRUST_FULLY        ,
248     GPGME_STATUS_TRUST_ULTIMATE     ,
249
250     GPGME_STATUS_SHM_INFO           ,
251     GPGME_STATUS_SHM_GET            ,
252     GPGME_STATUS_SHM_GET_BOOL       ,
253     GPGME_STATUS_SHM_GET_HIDDEN     ,
254
255     GPGME_STATUS_NEED_PASSPHRASE    ,
256     GPGME_STATUS_VALIDSIG           ,
257     GPGME_STATUS_SIG_ID             ,
258     GPGME_STATUS_ENC_TO             ,
259     GPGME_STATUS_NODATA             ,
260     GPGME_STATUS_BAD_PASSPHRASE     ,
261     GPGME_STATUS_NO_PUBKEY          ,
262     GPGME_STATUS_NO_SECKEY          ,
263     GPGME_STATUS_NEED_PASSPHRASE_SYM,
264     GPGME_STATUS_DECRYPTION_FAILED  ,
265     GPGME_STATUS_DECRYPTION_OKAY    ,
266     GPGME_STATUS_MISSING_PASSPHRASE ,
267     GPGME_STATUS_GOOD_PASSPHRASE    ,
268     GPGME_STATUS_GOODMDC            ,
269     GPGME_STATUS_BADMDC             ,
270     GPGME_STATUS_ERRMDC             ,
271     GPGME_STATUS_IMPORTED           ,
272     GPGME_STATUS_IMPORT_RES         ,
273     GPGME_STATUS_FILE_START         ,
274     GPGME_STATUS_FILE_DONE          ,
275     GPGME_STATUS_FILE_ERROR         ,
276
277     GPGME_STATUS_BEGIN_DECRYPTION   ,
278     GPGME_STATUS_END_DECRYPTION     ,
279     GPGME_STATUS_BEGIN_ENCRYPTION   ,
280     GPGME_STATUS_END_ENCRYPTION     ,
281
282     GPGME_STATUS_DELETE_PROBLEM     ,
283     GPGME_STATUS_GET_BOOL           ,
284     GPGME_STATUS_GET_LINE           ,
285     GPGME_STATUS_GET_HIDDEN         ,
286     GPGME_STATUS_GOT_IT             ,
287     GPGME_STATUS_PROGRESS           ,
288     GPGME_STATUS_SIG_CREATED        ,
289     GPGME_STATUS_SESSION_KEY        ,
290     GPGME_STATUS_NOTATION_NAME      ,
291     GPGME_STATUS_NOTATION_DATA      ,
292     GPGME_STATUS_POLICY_URL         ,
293     GPGME_STATUS_BEGIN_STREAM       ,
294     GPGME_STATUS_END_STREAM         ,
295     GPGME_STATUS_KEY_CREATED        ,
296     GPGME_STATUS_USERID_HINT        ,
297     GPGME_STATUS_UNEXPECTED         ,
298     GPGME_STATUS_INV_RECP           ,
299     GPGME_STATUS_NO_RECP            ,
300     GPGME_STATUS_ALREADY_SIGNED     ,
301     GPGME_STATUS_SIGEXPIRED         ,
302     GPGME_STATUS_EXPSIG             ,
303     GPGME_STATUS_EXPKEYSIG          ,
304     GPGME_STATUS_TRUNCATED          ,
305     GPGME_STATUS_ERROR              
306 } GpgmeStatusCode;
307
308
309 /* The available keylist mode flags.  */
310 #define GPGME_KEYLIST_MODE_LOCAL  1
311 #define GPGME_KEYLIST_MODE_EXTERN 2
312 #define GPGME_KEYLIST_MODE_SIGS   4
313
314 /* Types for callback functions.  */
315
316 /* Request a passphrase from the user.  */
317 typedef const char *(*GpgmePassphraseCb) (void *hook, const char *desc,
318                                           void **r_hd);
319
320 /* Inform the user about progress made.  */
321 typedef void (*GpgmeProgressCb) (void *opaque, const char *what,
322                                  int type, int current, int total);
323
324 /* Interact with the user about an edit operation.  */
325 typedef GpgmeError (*GpgmeEditCb) (void *opaque, GpgmeStatusCode status,
326                                    const char *args, const char **reply);
327
328 /* Context management functions.  */
329
330 /* Create a new context and return it in CTX.  */
331 GpgmeError gpgme_new (GpgmeCtx *ctx);
332
333 /* Release the context CTX.  */
334 void gpgme_release (GpgmeCtx ctx);
335
336 /* Retrieve more info about performed signature check.  */
337 char *gpgme_get_notation (GpgmeCtx ctx);
338
339 /* Set the protocol to be used by CTX to PROTO.  */
340 GpgmeError gpgme_set_protocol (GpgmeCtx ctx, GpgmeProtocol proto);
341
342 /* Get the protocol used with CTX */
343 GpgmeProtocol gpgme_get_protocol (GpgmeCtx ctx);
344
345 /* If YES is non-zero, enable armor mode in CTX, disable it otherwise.  */
346 void gpgme_set_armor (GpgmeCtx ctx, int yes);
347
348 /* Return non-zero if armor mode is set in CTX.  */
349 int gpgme_get_armor (GpgmeCtx ctx);
350
351 /* If YES is non-zero, enable text mode in CTX, disable it otherwise.  */
352 void gpgme_set_textmode (GpgmeCtx ctx, int yes);
353
354 /* Return non-zero if text mode is set in CTX.  */
355 int gpgme_get_textmode (GpgmeCtx ctx);
356
357 /* Include up to NR_OF_CERTS certificates in an S/MIME message.  */
358 void gpgme_set_include_certs (GpgmeCtx ctx, int nr_of_certs);
359
360 /* Return the number of certs to include in an S/MIME message.  */
361 int gpgme_get_include_certs (GpgmeCtx ctx);
362
363 /* Set keylist mode in CTX to MODE.  */
364 GpgmeError gpgme_set_keylist_mode (GpgmeCtx ctx, int mode);
365
366 /* Get keylist mode in CTX.  */
367 int gpgme_get_keylist_mode (GpgmeCtx ctx);
368
369 /* Set the passphrase callback function in CTX to CB.  HOOK_VALUE is
370    passed as first argument to the passphrase callback function.  */
371 void gpgme_set_passphrase_cb (GpgmeCtx ctx,
372                               GpgmePassphraseCb cb, void *hook_value);
373
374 /* Get the current passphrase callback function in *CB and the current
375    hook value in *HOOK_VALUE.  */
376 void gpgme_get_passphrase_cb (GpgmeCtx ctx, GpgmePassphraseCb *cb,
377                               void **hook_value);
378
379 /* Set the progress callback function in CTX to CB.  HOOK_VALUE is
380    passed as first argument to the progress callback function.  */
381 void gpgme_set_progress_cb (GpgmeCtx c, GpgmeProgressCb cb, void *hook_value);
382
383 /* Get the current progress callback function in *CB and the current
384    hook value in *HOOK_VALUE.  */
385 void gpgme_get_progress_cb (GpgmeCtx ctx, GpgmeProgressCb *cb,
386                             void **hook_value);
387
388 /* Delete all signers from CTX.  */
389 void gpgme_signers_clear (GpgmeCtx ctx);
390
391 /* Add KEY to list of signers in CTX.  */
392 GpgmeError gpgme_signers_add (GpgmeCtx ctx, const GpgmeKey key);
393
394 /* Return the SEQth signer's key in CTX.  */
395 GpgmeKey gpgme_signers_enum (const GpgmeCtx ctx, int seq);
396
397 /* Retrieve the signature status of signature IDX in CTX after a
398    successful verify operation in R_STAT (if non-null).  The creation
399    time stamp of the signature is returned in R_CREATED (if non-null).
400    The function returns a string containing the fingerprint.  */
401 const char *gpgme_get_sig_status (GpgmeCtx ctx, int idx,
402                                   GpgmeSigStat *r_stat, time_t *r_created);
403
404 /* Retrieve certain attributes of a signature.  IDX is the index
405    number of the signature after a successful verify operation.  WHAT
406    is an attribute where GPGME_ATTR_EXPIRE is probably the most useful
407    one.  WHATIDX is to be passed as 0 for most attributes . */
408 unsigned long gpgme_get_sig_ulong_attr (GpgmeCtx c, int idx,
409                                         GpgmeAttr what, int whatidx);
410 const char *gpgme_get_sig_string_attr (GpgmeCtx c, int idx,
411                                       GpgmeAttr what, int whatidx);
412
413
414 /* Get the key used to create signature IDX in CTX and return it in
415    R_KEY.  */
416 GpgmeError gpgme_get_sig_key (GpgmeCtx ctx, int idx, GpgmeKey *r_key);
417
418 /* Return a string with more info about the last crypto operating in CTX.
419    RESERVED should be zero.  The user has to free the string.  */
420 char *gpgme_get_op_info (GpgmeCtx ctx, int reserved);
421
422
423 /* Run control.  */
424
425 /* The type of an I/O callback function.  */
426 typedef void (*GpgmeIOCb) (void *data, int fd);
427
428 /* The type of a function that can register FNC as the I/O callback
429    function for the file descriptor FD with direction dir (0: for writing,
430    1: for reading).  FNC_DATA should be passed as DATA to FNC.  The
431    function should return a TAG suitable for the corresponding
432    GpgmeRemoveIOCb, and an error value.  */
433 typedef GpgmeError (*GpgmeRegisterIOCb) (void *data, int fd, int dir,
434                                          GpgmeIOCb fnc, void *fnc_data,
435                                          void **tag);
436
437 /* The type of a function that can remove a previously registered I/O
438    callback function given TAG as returned by the register
439    function.  */
440 typedef void (*GpgmeRemoveIOCb) (void *tag);
441
442 typedef enum { GPGME_EVENT_DONE,
443                GPGME_EVENT_NEXT_KEY,
444                GPGME_EVENT_NEXT_TRUSTITEM } GpgmeEventIO;
445
446 /* The type of a function that is called when a context finished an
447    operation.  */
448 typedef void (*GpgmeEventIOCb) (void *data, GpgmeEventIO type,
449                                 void *type_data);
450
451 struct GpgmeIOCbs
452 {
453   GpgmeRegisterIOCb add;
454   void *add_priv;
455   GpgmeRemoveIOCb remove;
456   GpgmeEventIOCb event;
457   void *event_priv;
458 };
459
460 /* Set the I/O callback functions in CTX to IO_CBS.  */
461 void gpgme_set_io_cbs (GpgmeCtx ctx, struct GpgmeIOCbs *io_cbs);
462
463 /* Get the current I/O callback functions.  */
464 void gpgme_get_io_cbs (GpgmeCtx ctx, struct GpgmeIOCbs *io_cbs);
465
466 /* Cancel a pending operation in CTX.  */
467 void gpgme_cancel (GpgmeCtx ctx);
468
469 /* Process the pending operation and, if HANG is non-zero, wait for
470    the pending operation to finish.  */
471 GpgmeCtx gpgme_wait (GpgmeCtx ctx, GpgmeError *status, int hang);
472
473
474 /* Functions to handle recipients.  */
475
476 /* Create a new recipients set and return it in R_RSET.  */
477 GpgmeError gpgme_recipients_new (GpgmeRecipients *r_rset);
478
479 /* Release the recipients set RSET.  */
480 void gpgme_recipients_release (GpgmeRecipients rset);
481
482 /* Add NAME to the recipients set RSET.  */
483 GpgmeError gpgme_recipients_add_name (GpgmeRecipients rset, const char *name);
484
485 /* Add NAME with validity AL to the recipients set RSET.  */
486 GpgmeError gpgme_recipients_add_name_with_validity (GpgmeRecipients rset,
487                                                     const char *name,
488                                                     GpgmeValidity val);
489
490 /* Return the number of recipients in RSET.  */
491 unsigned int gpgme_recipients_count (const GpgmeRecipients rset);
492
493 /* Create a new enumeration handle for the recipients set RSET and
494    return it in ITER.  */
495 GpgmeError gpgme_recipients_enum_open (const GpgmeRecipients rset,
496                                        void **iter);
497
498 /* Return the next recipient from the recipient set RSET in the
499    enumerator ITER.  */
500 const char *gpgme_recipients_enum_read (const GpgmeRecipients rset,
501                                         void **iter);
502
503 /* Destroy the enumerator ITER for the recipient set RSET.  */
504 GpgmeError gpgme_recipients_enum_close (const GpgmeRecipients rset,
505                                         void **iter);
506
507
508 /* Functions to handle data objects.  */
509
510 /* Read up to SIZE bytes into buffer BUFFER from the data object with
511    the handle HANDLE.  Return the number of characters read, 0 on EOF
512    and -1 on error.  If an error occurs, errno is set.  */
513 typedef int (*GpgmeDataReadCb) (void *handle, void *buffer, size_t size);
514
515 /* Write up to SIZE bytes from buffer BUFFER to the data object with
516    the handle HANDLE.  Return the number of characters written, or -1
517    on error.  If an error occurs, errno is set.  */
518 typedef ssize_t (*GpgmeDataWriteCb) (void *handle, const void *buffer,
519                                      size_t size);
520
521 /* Set the current position from where the next read or write starts
522    in the data object with the handle HANDLE to OFFSET, relativ to
523    WHENCE.  */
524 typedef int (*GpgmeDataSeekCb) (void *handle, off_t offset, int whence);
525
526 /* Close the data object with the handle DL.  */
527 typedef void (*GpgmeDataReleaseCb) (void *handle);
528
529 struct GpgmeDataCbs
530 {
531   GpgmeDataReadCb read;
532   GpgmeDataWriteCb write;
533   GpgmeDataSeekCb seek;
534   GpgmeDataReleaseCb release;
535 };
536
537 /* Read up to SIZE bytes into buffer BUFFER from the data object with
538    the handle DH.  Return the number of characters read, 0 on EOF and
539    -1 on error.  If an error occurs, errno is set.  */
540 int gpgme_data_read (GpgmeData dh, void *buffer, size_t size);
541
542 /* Write up to SIZE bytes from buffer BUFFER to the data object with
543    the handle DH.  Return the number of characters written, or -1 on
544    error.  If an error occurs, errno is set.  */
545 ssize_t gpgme_data_write (GpgmeData dh, const void *buffer, size_t size);
546
547 /* Set the current position from where the next read or write starts
548    in the data object with the handle DH to OFFSET, relativ to
549    WHENCE.  */
550 off_t gpgme_data_seek (GpgmeData dh, off_t offset, int whence);
551
552 /* Create a new data buffer and return it in R_DH.  */
553 GpgmeError gpgme_data_new (GpgmeData *r_dh);
554
555 /* Destroy the data buffer DH.  */
556 void gpgme_data_release (GpgmeData dh);
557
558 /* Create a new data buffer filled with SIZE bytes starting from
559    BUFFER.  If COPY is zero, copying is delayed until necessary, and
560    the data is taken from the original location when needed.  */
561 GpgmeError gpgme_data_new_from_mem (GpgmeData *r_dh,
562                                     const char *buffer, size_t size,
563                                     int copy);
564
565 /* Destroy the data buffer DH and return a pointer to its content.
566    The memory has be to released with free by the user.  It's size is
567    returned in R_LEN.  */
568 char *gpgme_data_release_and_get_mem (GpgmeData dh, size_t *r_len);
569
570 GpgmeError gpgme_data_new_from_cbs (GpgmeData *dh,
571                                     struct GpgmeDataCbs *cbs,
572                                     void *handle);
573
574 GpgmeError gpgme_data_new_from_fd (GpgmeData *dh, int fd);
575
576 GpgmeError gpgme_data_new_from_stream (GpgmeData *dh, FILE *stream);
577
578 /* Return the encoding attribute of the data buffer DH */
579 GpgmeDataEncoding gpgme_data_get_encoding (GpgmeData dh);
580
581 /* Set the encoding attribute of data buffer DH to ENC */
582 GpgmeError gpgme_data_set_encoding (GpgmeData dh, GpgmeDataEncoding enc);
583
584
585
586 /* Create a new data buffer which retrieves the data from the callback
587    function READ_CB.  Deprecated, please use gpgme_data_new_from_cbs
588    instead.  */
589 GpgmeError gpgme_data_new_with_read_cb (GpgmeData *r_dh,
590                                         int (*read_cb) (void*,char *,size_t,size_t*),
591                                         void *read_cb_value);
592
593 /* Create a new data buffer filled with the content of file FNAME.
594    COPY must be non-zero.  For delayed read, please use
595    gpgme_data_new_from_fd or gpgme_data_new_from stream instead.  */
596 GpgmeError gpgme_data_new_from_file (GpgmeData *r_dh,
597                                      const char *fname,
598                                      int copy);
599
600 /* Create a new data buffer filled with LENGTH bytes starting from
601    OFFSET within the file FNAME or stream FP (exactly one must be
602    non-zero).  */
603 GpgmeError gpgme_data_new_from_filepart (GpgmeData *r_dh,
604                                          const char *fname, FILE *fp,
605                                          off_t offset, size_t length);
606
607 /* Reset the read pointer in DH.  Deprecated, please use
608    gpgme_data_seek instead.  */
609 GpgmeError gpgme_data_rewind (GpgmeData dh);
610
611
612 /* Key and trust functions.  */
613
614 /* Acquire a reference to KEY.  */
615 void gpgme_key_ref (GpgmeKey key);
616
617 /* Release a reference to KEY.  If this was the last one the key is
618    destroyed.  */
619 void gpgme_key_unref (GpgmeKey key);
620 void gpgme_key_release (GpgmeKey key);
621
622 /* Get the data from key KEY in a XML string, which has to be released
623    with free by the user.  */
624 char *gpgme_key_get_as_xml (GpgmeKey key);
625
626 /* Return the value of the attribute WHAT of KEY, which has to be
627    representable by a string.  IDX specifies the sub key or
628    user ID for attributes related to sub keys or user IDs.  */
629 const char *gpgme_key_get_string_attr (GpgmeKey key, GpgmeAttr what,
630                                        const void *reserved, int idx);
631
632 /* Return the value of the attribute WHAT of KEY, which has to be
633    representable by an unsigned integer.  IDX specifies the sub key or
634    user ID for attributes related to sub keys or user IDs.  */
635 unsigned long gpgme_key_get_ulong_attr (GpgmeKey key, GpgmeAttr what,
636                                         const void *reserved, int idx);
637
638 /* Release the trust item ITEM.  */
639 void gpgme_trust_item_release (GpgmeTrustItem item);
640
641 /* Return the value of the attribute WHAT of ITEM, which has to be
642    representable by a string.  */
643 const char *gpgme_trust_item_get_string_attr (GpgmeTrustItem item,
644                                               GpgmeAttr what,
645                                               const void *reserved, int idx);
646
647 /* Return the value of the attribute WHAT of KEY, which has to be
648    representable by an integer.  IDX specifies a running index if the
649    attribute appears more than once in the key.  */
650 int gpgme_trust_item_get_int_attr (GpgmeTrustItem item, GpgmeAttr what,
651                                    const void *reserved, int idx);
652
653
654 /* Crypto operation function.  */
655
656 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
657    store the resulting ciphertext in CIPHER.  */
658 GpgmeError gpgme_op_encrypt_start (GpgmeCtx ctx,
659                                    GpgmeRecipients recp,
660                                    GpgmeData plain, GpgmeData cipher);
661 GpgmeError gpgme_op_encrypt (GpgmeCtx ctx,
662                              GpgmeRecipients recp,
663                              GpgmeData plain, GpgmeData cipher);
664
665 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
666    store the resulting ciphertext in CIPHER.  Also sign the ciphertext
667    with the signers in CTX.  */
668 GpgmeError gpgme_op_encrypt_sign_start (GpgmeCtx ctx,
669                                         GpgmeRecipients recp,
670                                         GpgmeData plain, GpgmeData cipher);
671 GpgmeError gpgme_op_encrypt_sign (GpgmeCtx ctx,
672                                   GpgmeRecipients recp,
673                                   GpgmeData plain, GpgmeData cipher);
674
675 /* Decrypt ciphertext CIPHER within CTX and store the resulting
676    plaintext in PLAIN.  */
677 GpgmeError gpgme_op_decrypt_start (GpgmeCtx ctx,
678                                    GpgmeData cipher, GpgmeData plain);
679 GpgmeError gpgme_op_decrypt (GpgmeCtx ctx,
680                              GpgmeData cipher, GpgmeData plain);
681
682 /* Decrypt ciphertext CIPHER and make a signature verification within
683    CTX and store the resulting plaintext in PLAIN.  */
684 GpgmeError gpgme_op_decrypt_verify_start (GpgmeCtx ctx,
685                                           GpgmeData cipher, GpgmeData plain);
686 GpgmeError gpgme_op_decrypt_verify (GpgmeCtx ctx,
687                                     GpgmeData cipher, GpgmeData plain,
688                                     GpgmeSigStat *r_status);
689
690 /* Sign the plaintext PLAIN and store the signature in SIG.  Only
691    detached signatures are supported for now.  */
692 GpgmeError gpgme_op_sign_start (GpgmeCtx ctx,
693                                 GpgmeData plain, GpgmeData sig,
694                                 GpgmeSigMode mode);
695 GpgmeError gpgme_op_sign (GpgmeCtx ctx,
696                           GpgmeData plain, GpgmeData sig,
697                           GpgmeSigMode mode);
698
699 /* Verify within CTX that SIG is a valid signature for TEXT.  */
700 GpgmeError gpgme_op_verify_start (GpgmeCtx ctx, GpgmeData sig,
701                                   GpgmeData signed_text, GpgmeData plaintext);
702 GpgmeError gpgme_op_verify (GpgmeCtx ctx, GpgmeData sig,
703                             GpgmeData signed_text, GpgmeData plaintext,
704                             GpgmeSigStat *r_status);
705
706 /* Import the key in KEYDATA into the keyring.  */
707 GpgmeError gpgme_op_import_start (GpgmeCtx ctx, GpgmeData keydata);
708 GpgmeError gpgme_op_import (GpgmeCtx ctx, GpgmeData keydata);
709 GpgmeError gpgme_op_import_ext (GpgmeCtx ctx, GpgmeData keydata, int *nr);
710
711 /* Export the keys listed in RECP into KEYDATA.  */
712 GpgmeError gpgme_op_export_start (GpgmeCtx ctx, GpgmeRecipients recp,
713                                   GpgmeData keydata);
714 GpgmeError gpgme_op_export (GpgmeCtx ctx, GpgmeRecipients recp,
715                             GpgmeData keydata);
716
717 /* Generate a new keypair and add it to the keyring.  PUBKEY and
718    SECKEY should be null for now.  PARMS specifies what keys should be
719    generated.  */
720 GpgmeError gpgme_op_genkey_start (GpgmeCtx ctx, const char *parms,
721                                   GpgmeData pubkey, GpgmeData seckey);
722 GpgmeError gpgme_op_genkey (GpgmeCtx ctx, const char *parms,
723                             GpgmeData pubkey, GpgmeData seckey);
724
725 /* Delete KEY from the keyring.  If ALLOW_SECRET is non-zero, secret
726    keys are also deleted.  */
727 GpgmeError gpgme_op_delete_start (GpgmeCtx ctx, const GpgmeKey key,
728                                   int allow_secret);
729 GpgmeError gpgme_op_delete (GpgmeCtx ctx, const GpgmeKey key,
730                             int allow_secret);
731
732 /* Edit the key KEY.  Send status and command requests to FNC and
733    output of edit commands to OUT.  */
734 GpgmeError gpgme_op_edit_start (GpgmeCtx ctx, GpgmeKey key,
735                           GpgmeEditCb fnc, void *fnc_value,
736                           GpgmeData out);
737 GpgmeError gpgme_op_edit (GpgmeCtx ctx, GpgmeKey key,
738                           GpgmeEditCb fnc, void *fnc_value,
739                           GpgmeData out);
740
741 /* Key management functions */
742
743 /* Start a keylist operation within CTX, searching for keys which
744    match PATTERN.  If SECRET_ONLY is true, only secret keys are
745    returned.  */
746 GpgmeError gpgme_op_keylist_start (GpgmeCtx ctx,
747                                    const char *pattern, int secret_only);
748 GpgmeError gpgme_op_keylist_ext_start (GpgmeCtx ctx, const char *pattern[],
749                                        int secret_only, int reserved);
750
751 /* Return the next key from the keylist in R_KEY.  */
752 GpgmeError gpgme_op_keylist_next (GpgmeCtx ctx, GpgmeKey *r_key);
753
754 /* Terminate a pending keylist operation within CTX.  */
755 GpgmeError gpgme_op_keylist_end (GpgmeCtx ctx);
756
757
758 /* Start a trustlist operation within CTX, searching for trust items
759    which match PATTERN.  */
760 GpgmeError gpgme_op_trustlist_start (GpgmeCtx ctx,
761                                      const char *pattern, int max_level);
762
763 /* Return the next trust item from the trustlist in R_ITEM.  */
764 GpgmeError gpgme_op_trustlist_next (GpgmeCtx ctx, GpgmeTrustItem *r_item);
765
766 /* Terminate a pending trustlist operation within CTX.  */
767 GpgmeError gpgme_op_trustlist_end (GpgmeCtx ctx);
768
769
770 /* Various functions.  */
771
772 /* Check that the library fulfills the version requirement.  */
773 const char *gpgme_check_version (const char *req_version);
774
775 /* Retrieve information about the backend engines.  */
776 const char *gpgme_get_engine_info (void);
777
778 /* Return a string describing ERR.  */
779 const char *gpgme_strerror (GpgmeError err);
780
781 /* Register an idle function.  */
782 typedef void (*GpgmeIdleFunc)(void);
783 GpgmeIdleFunc gpgme_register_idle (GpgmeIdleFunc idle);
784
785
786 /* Engine support functions.  */
787
788 /* Verify that the engine implementing PROTO is installed and
789    available.  */
790 GpgmeError gpgme_engine_check_version (GpgmeProtocol proto);
791
792
793 #ifdef __cplusplus
794 }
795 #endif
796 #endif /* GPGME_H */