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