configure has fixed the version number, better checkin so that we are
[gpgme.git] / gpgme / gpgme.h
1 /* gpgme.h -  GnuPG Made Easy
2  *      Copyright (C) 2000 Werner Koch (dd9jn)
3  *      Copyright (C) 2001 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 /*
41  * The version of this header should match the one of the library
42  * It should not be used by a program because gpgme_check_version(NULL)
43  * does return the same version.  The purpose of this macro is to
44  * let autoconf (using the AM_PATH_GPGME macro) check that this
45  * header matches the installed library.
46  * Warning: Do not edit the next line.  configure will do that for you! */
47 #define GPGME_VERSION "0.3.0a-cvs"
48
49
50
51 struct gpgme_context_s;
52 typedef struct gpgme_context_s *GpgmeCtx;
53
54 struct gpgme_data_s;
55 typedef struct gpgme_data_s *GpgmeData;
56
57 struct gpgme_recipients_s;
58 typedef struct gpgme_recipients_s *GpgmeRecipients;
59
60 struct gpgme_key_s;
61 typedef struct gpgme_key_s *GpgmeKey;
62
63 struct gpgme_trust_item_s;
64 typedef struct gpgme_trust_item_s *GpgmeTrustItem;
65
66
67 typedef enum {
68     GPGME_EOF = -1,
69     GPGME_No_Error = 0,
70     GPGME_General_Error = 1,
71     GPGME_Out_Of_Core = 2,
72     GPGME_Invalid_Value = 3,
73     GPGME_Busy = 4,
74     GPGME_No_Request = 5,
75     GPGME_Exec_Error = 6,
76     GPGME_Too_Many_Procs = 7,
77     GPGME_Pipe_Error = 8,
78     GPGME_No_Recipients = 9,
79     GPGME_No_Data = 10,
80     GPGME_Conflict = 11,
81     GPGME_Not_Implemented = 12,
82     GPGME_Read_Error = 13,
83     GPGME_Write_Error = 14,
84     GPGME_Invalid_Type = 15,
85     GPGME_Invalid_Mode = 16,
86     GPGME_File_Error = 17,  /* errno is set in this case */
87     GPGME_Decryption_Failed = 18,
88     GPGME_No_Passphrase = 19,
89     GPGME_Canceled = 20,
90     GPGME_Invalid_Key = 21,
91     GPGME_Invalid_Engine = 22
92 } GpgmeError;
93
94 typedef enum {
95     GPGME_DATA_TYPE_NONE = 0,
96     GPGME_DATA_TYPE_MEM  = 1,
97     GPGME_DATA_TYPE_FD   = 2,
98     GPGME_DATA_TYPE_FILE = 3,
99     GPGME_DATA_TYPE_CB   = 4
100 } GpgmeDataType;
101
102 typedef enum {
103     GPGME_SIG_STAT_NONE = 0,
104     GPGME_SIG_STAT_GOOD = 1,
105     GPGME_SIG_STAT_BAD  = 2,
106     GPGME_SIG_STAT_NOKEY = 3,
107     GPGME_SIG_STAT_NOSIG = 4,
108     GPGME_SIG_STAT_ERROR = 5,
109     GPGME_SIG_STAT_DIFF  = 6
110 } GpgmeSigStat;
111
112 typedef enum {
113     GPGME_SIG_MODE_NORMAL = 0,
114     GPGME_SIG_MODE_DETACH = 1,
115     GPGME_SIG_MODE_CLEAR = 2
116 } GpgmeSigMode;
117
118 typedef enum {
119     GPGME_ATTR_KEYID   = 1,
120     GPGME_ATTR_FPR     = 2,
121     GPGME_ATTR_ALGO    = 3,
122     GPGME_ATTR_LEN     = 4,
123     GPGME_ATTR_CREATED = 5,
124     GPGME_ATTR_EXPIRE  = 6,
125     GPGME_ATTR_OTRUST  = 7,
126     GPGME_ATTR_USERID  = 8,
127     GPGME_ATTR_NAME    = 9,
128     GPGME_ATTR_EMAIL   = 10,
129     GPGME_ATTR_COMMENT = 11,
130     GPGME_ATTR_VALIDITY= 12,
131     GPGME_ATTR_LEVEL   = 13,
132     GPGME_ATTR_TYPE    = 14,
133     GPGME_ATTR_IS_SECRET= 15,
134     GPGME_ATTR_KEY_REVOKED = 16,
135     GPGME_ATTR_KEY_INVALID = 17,
136     GPGME_ATTR_UID_REVOKED = 18,
137     GPGME_ATTR_UID_INVALID = 19,
138     GPGME_ATTR_KEY_CAPS    = 20,
139     GPGME_ATTR_CAN_ENCRYPT = 21,
140     GPGME_ATTR_CAN_SIGN    = 22,
141     GPGME_ATTR_CAN_CERTIFY = 23,
142     GPGME_ATTR_KEY_EXPIRED = 24,
143     GPGME_ATTR_KEY_DISABLED= 25
144 } GpgmeAttr;
145
146 typedef enum {
147     GPGME_VALIDITY_UNKNOWN = 0,
148     GPGME_VALIDITY_UNDEFINED = 1,
149     GPGME_VALIDITY_NEVER = 2,
150     GPGME_VALIDITY_MARGINAL = 3,
151     GPGME_VALIDITY_FULL = 4,
152     GPGME_VALIDITY_ULTIMATE = 5
153 } GpgmeValidity;
154
155
156 typedef enum {
157   GPGME_PROTOCOL_OpenPGP = 0, /* default */
158   GPGME_PROTOCOL_CMS = 1,
159   GPGME_PROTOCOL_AUTO = 2
160 } GpgmeProtocol;
161
162 typedef const char *(*GpgmePassphraseCb)(void*,
163                                          const char *desc, void *r_hd);
164 typedef void (*GpgmeProgressCb)(void *opaque,
165                                 const char *what, 
166                                 int type, int current, int total );
167
168 /* Context management */
169 GpgmeError gpgme_new (GpgmeCtx *r_ctx);
170 void       gpgme_release (GpgmeCtx c);
171 void       gpgme_cancel (GpgmeCtx c);
172 GpgmeCtx   gpgme_wait (GpgmeCtx c, int hang);
173
174 char *gpgme_get_notation (GpgmeCtx c);
175 GpgmeError gpgme_set_protocol (GpgmeCtx c, GpgmeProtocol prot);
176 void gpgme_set_armor (GpgmeCtx c, int yes);
177 int  gpgme_get_armor (GpgmeCtx c);
178 void gpgme_set_textmode (GpgmeCtx c, int yes);
179 int  gpgme_get_textmode (GpgmeCtx c);
180 void gpgme_set_keylist_mode ( GpgmeCtx c, int mode );
181 void gpgme_set_passphrase_cb (GpgmeCtx c,
182                               GpgmePassphraseCb cb, void *cb_value);
183 void gpgme_set_progress_cb (GpgmeCtx c, GpgmeProgressCb cb, void *cb_value);
184
185 void       gpgme_signers_clear (GpgmeCtx c);
186 GpgmeError gpgme_signers_add (GpgmeCtx c, const GpgmeKey key);
187 GpgmeKey   gpgme_signers_enum (const GpgmeCtx c, int seq);
188
189 const char *gpgme_get_sig_status (GpgmeCtx c, int idx,
190                                   GpgmeSigStat *r_stat, time_t *r_created );
191 GpgmeError gpgme_get_sig_key (GpgmeCtx c, int idx, GpgmeKey *r_key);
192 char *gpgme_get_op_info (GpgmeCtx c, int reserved);
193
194
195 /* Functions to handle recipients */
196 GpgmeError   gpgme_recipients_new (GpgmeRecipients *r_rset);
197 void         gpgme_recipients_release ( GpgmeRecipients rset);
198 GpgmeError   gpgme_recipients_add_name (GpgmeRecipients rset,
199                                         const char *name);
200 GpgmeError   gpgme_recipients_add_name_with_validity (GpgmeRecipients rset,
201                                                       const char *name,
202                                                       GpgmeValidity val );
203 unsigned int gpgme_recipients_count ( const GpgmeRecipients rset );
204 GpgmeError gpgme_recipients_enum_open (const GpgmeRecipients rset,void **ctx);
205 const char *gpgme_recipients_enum_read (const GpgmeRecipients rset,void **ctx);
206 GpgmeError gpgme_recipients_enum_close (const GpgmeRecipients rset,void **ctx);
207
208
209 /* Functions to handle data sources */
210 GpgmeError    gpgme_data_new ( GpgmeData *r_dh );
211 GpgmeError    gpgme_data_new_from_mem ( GpgmeData *r_dh,
212                                         const char *buffer, size_t size,
213                                         int copy );
214 GpgmeError    gpgme_data_new_with_read_cb ( GpgmeData *r_dh,
215                               int (*read_cb)(void*,char *,size_t,size_t*),
216                               void *read_cb_value );
217
218 GpgmeError    gpgme_data_new_from_file ( GpgmeData *r_dh,
219                                          const char *fname,
220                                          int copy );
221 GpgmeError    gpgme_data_new_from_filepart ( GpgmeData *r_dh,
222                                              const char *fname, FILE *fp,
223                                              off_t offset, off_t length );
224 void          gpgme_data_release ( GpgmeData dh );
225 char *        gpgme_data_release_and_get_mem ( GpgmeData dh, size_t *r_len );
226 GpgmeDataType gpgme_data_get_type ( GpgmeData dh );
227 GpgmeError    gpgme_data_rewind ( GpgmeData dh );
228 GpgmeError    gpgme_data_read ( GpgmeData dh,
229                                 char *buffer, size_t length, size_t *nread );
230 GpgmeError    gpgme_data_write ( GpgmeData dh,
231                                  const char *buffer, size_t length );
232
233
234 /* Key and trust functions */
235 void gpgme_key_ref (GpgmeKey key);
236 void gpgme_key_unref (GpgmeKey key);
237 void gpgme_key_release ( GpgmeKey key );
238 char *gpgme_key_get_as_xml ( GpgmeKey key );
239 const char  *gpgme_key_get_string_attr ( GpgmeKey key, GpgmeAttr what,
240                                          const void *reserved, int idx );
241 unsigned long gpgme_key_get_ulong_attr ( GpgmeKey key, GpgmeAttr what,
242                                          const void *reserved, int idx );
243
244 void gpgme_trust_item_release ( GpgmeTrustItem item );
245 const char *gpgme_trust_item_get_string_attr ( GpgmeTrustItem item,
246                                                GpgmeAttr what,
247                                                const void *reserved, int idx );
248 int gpgme_trust_item_get_int_attr ( GpgmeTrustItem item, GpgmeAttr what,
249                                     const void *reserved, int idx );
250
251
252
253
254 /* Basic GnuPG functions */
255 GpgmeError gpgme_op_encrypt_start ( GpgmeCtx c,
256                                     GpgmeRecipients recp,
257                                     GpgmeData in, GpgmeData out );
258 GpgmeError gpgme_op_decrypt_start ( GpgmeCtx c, 
259                                     GpgmeData ciph, GpgmeData plain );
260 GpgmeError gpgme_op_decrypt_verify_start (GpgmeCtx c, 
261                                           GpgmeData ciph, GpgmeData plain);
262 GpgmeError gpgme_op_sign_start ( GpgmeCtx c,
263                                  GpgmeData in, GpgmeData out,
264                                  GpgmeSigMode mode );
265 GpgmeError gpgme_op_verify_start ( GpgmeCtx c,
266                                    GpgmeData sig, GpgmeData text );
267 GpgmeError gpgme_op_import_start ( GpgmeCtx c, GpgmeData keydata );
268 GpgmeError gpgme_op_export_start ( GpgmeCtx c, GpgmeRecipients recp,
269                                    GpgmeData keydata );
270 GpgmeError gpgme_op_genkey_start ( GpgmeCtx c, const char *parms,
271                                    GpgmeData pubkey, GpgmeData seckey );
272 GpgmeError gpgme_op_delete_start ( GpgmeCtx c, const GpgmeKey key,
273                                    int allow_secret );
274
275
276
277
278 /* Key management functions */
279 GpgmeError gpgme_op_keylist_start (GpgmeCtx ctx,
280                                    const char *pattern, int secret_only);
281 GpgmeError gpgme_op_keylist_next (GpgmeCtx ctx, GpgmeKey *r_key);
282 GpgmeError gpgme_op_keylist_end (GpgmeCtx ctx);
283 GpgmeError gpgme_op_trustlist_start (GpgmeCtx ctx,
284                                      const char *pattern, int max_level);
285 GpgmeError gpgme_op_trustlist_next (GpgmeCtx ctx, GpgmeTrustItem *r_item);
286
287
288
289 /* Convenience functions for normal usage */
290 GpgmeError gpgme_op_encrypt ( GpgmeCtx c, GpgmeRecipients recp,
291                               GpgmeData in, GpgmeData out );
292 GpgmeError gpgme_op_decrypt ( GpgmeCtx c, 
293                               GpgmeData in, GpgmeData out );
294 GpgmeError gpgme_op_decrypt_verify (GpgmeCtx c, 
295                                     GpgmeData in, GpgmeData out,
296                                     GpgmeSigStat *r_status);
297 GpgmeError gpgme_op_sign ( GpgmeCtx c, GpgmeData in, GpgmeData out,
298                            GpgmeSigMode mode);
299 GpgmeError gpgme_op_verify ( GpgmeCtx c, GpgmeData sig, GpgmeData text,
300                              GpgmeSigStat *r_status );
301 GpgmeError gpgme_op_import ( GpgmeCtx c, GpgmeData keydata );
302 GpgmeError gpgme_op_export ( GpgmeCtx c, GpgmeRecipients recp,
303                              GpgmeData keydata );
304 GpgmeError gpgme_op_genkey ( GpgmeCtx c, const char *parms,
305                              GpgmeData pubkey, GpgmeData seckey );
306 GpgmeError gpgme_op_delete ( GpgmeCtx c, const GpgmeKey key, int allow_secret);
307
308
309 /* miscellaneous functions */
310 const char *gpgme_check_version (const char *req_version);
311 GpgmeError  gpgme_check_engine (void);
312 const char *gpgme_get_engine_info (void);
313 const char *gpgme_strerror (GpgmeError err);
314 void        gpgme_register_idle (void (*fnc)(void));
315
316 /* Engine support functions.  */
317 GpgmeError gpgme_engine_check_version (GpgmeProtocol proto);
318
319 #ifdef __cplusplus
320 }
321 #endif
322 #endif /* GPGME_H */
323
324
325
326
327
328
329