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