doc/
[gpgme.git] / gpgme / gpgme.c
1 /* gpgme.c -  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 #include <config.h>
23 #include <stdio.h>
24 #include <stdlib.h>
25 #include <string.h>
26 #include <assert.h>
27
28 #include "util.h"
29 #include "context.h"
30 #include "ops.h"
31
32 /**
33  * gpgme_new:
34  * @r_ctx: Returns the new context
35  * 
36  * Create a new context to be used with most of the other GPGME
37  * functions.  Use gpgme_release_context() to release all resources
38  *
39  * Return value: An error code 
40  **/
41 GpgmeError
42 gpgme_new (GpgmeCtx *r_ctx)
43 {
44   GpgmeCtx ctx;
45
46   if (!r_ctx)
47     return mk_error (Invalid_Value);
48   *r_ctx = 0;
49   ctx = xtrycalloc (1, sizeof *ctx);
50   if (!ctx)
51     return mk_error (Out_Of_Core);
52   ctx->verbosity = 1;
53   *r_ctx = ctx;
54
55   return 0;
56 }
57
58 /**
59  * gpgme_release:
60  * @c: Context to be released. 
61  * 
62  * Release all resources associated with the given context.
63  **/
64 void
65 gpgme_release (GpgmeCtx ctx)
66 {
67   if (!ctx)
68     return;
69   _gpgme_engine_release (ctx->engine); 
70   _gpgme_release_result (ctx);
71   gpgme_key_release (ctx->tmp_key);
72   gpgme_data_release (ctx->help_data_1);
73   gpgme_data_release (ctx->notation);
74   gpgme_signers_clear (ctx);
75   if (ctx->signers)
76     xfree (ctx->signers);
77   /* FIXME: Release the key_queue.  */
78   xfree (ctx);
79 }
80
81 void
82 _gpgme_release_result (GpgmeCtx ctx)
83 {
84   _gpgme_release_verify_result (ctx->result.verify);
85   _gpgme_release_decrypt_result (ctx->result.decrypt);
86   _gpgme_release_sign_result (ctx->result.sign);
87   _gpgme_release_encrypt_result (ctx->result.encrypt);
88   _gpgme_release_passphrase_result (ctx->result.passphrase);
89   _gpgme_release_import_result (ctx->result.import);
90   _gpgme_release_delete_result (ctx->result.delete);
91   _gpgme_release_genkey_result (ctx->result.genkey);
92   memset (&ctx->result, 0, sizeof (ctx->result));
93   _gpgme_set_op_info (ctx, NULL);
94 }
95
96
97 /**
98  * gpgme_cancel:
99  * @c: the context
100  * 
101  * Cancel the current operation.  It is not guaranteed that it will work for
102  * all kinds of operations.  It is especially useful in a passphrase callback
103  * to stop the system from asking another time for the passphrase.
104  **/
105 void
106 gpgme_cancel (GpgmeCtx ctx)
107 {
108   return_if_fail (ctx);
109
110   ctx->cancel = 1;
111 }
112
113 /**
114  * gpgme_get_notation:
115  * @c: the context 
116  * 
117  * If there is notation data available from the last signature check,
118  * this function may be used to return this notation data as a string.
119  * The string is an XML represantaton of that data embedded in a
120  * %&lt;notation&gt; container.
121  * 
122  * Return value: An XML string or NULL if no notation data is available.
123  **/
124 char *
125 gpgme_get_notation (GpgmeCtx ctx)
126 {
127   if (!ctx->notation)
128     return NULL;
129   return _gpgme_data_get_as_string (ctx->notation);
130 }
131
132
133 /**
134  * gpgme_get_op_info:
135  * @c: the context 
136  * @reserved: 
137  * 
138  * Return information about the last information.  The caller has to
139  * free the string.  NULL is returned if there is not previous
140  * operation available or the operation has not yet finished.
141  *
142  * Here is a sample information we return:
143  * <literal>
144  * <![CDATA[
145  * <GnupgOperationInfo>
146  *   <signature>
147  *     <detached/> <!-- or cleartext or standard -->
148  *     <algo>17</algo>
149  *     <hashalgo>2</hashalgo>
150  *     <micalg>pgp-sha1</micalg>
151  *     <sigclass>01</sigclass>
152  *     <created>9222222</created>
153  *     <fpr>121212121212121212</fpr>
154  *   </signature>
155  * </GnupgOperationInfo>
156  * ]]>
157  * </literal>
158  * Return value: NULL for no info available or an XML string 
159  **/
160 char *
161 gpgme_get_op_info (GpgmeCtx ctx, int reserved)
162 {
163   if (!ctx || reserved)
164     return NULL;  /* Invalid value.  */
165  
166   return _gpgme_data_get_as_string (ctx->op_info);
167 }
168
169
170 /*
171  * Store the data object with the operation info in the
172  * context. Caller should not use that object anymore.  
173  */
174 void
175 _gpgme_set_op_info (GpgmeCtx ctx, GpgmeData info)
176 {
177   assert (ctx);
178
179   gpgme_data_release (ctx->op_info); 
180   ctx->op_info = NULL;
181
182   if (info)
183     ctx->op_info = info;
184 }
185
186
187 GpgmeError
188 gpgme_set_protocol (GpgmeCtx ctx, GpgmeProtocol protocol)
189 {
190   if (!ctx)
191     return mk_error (Invalid_Value);
192   
193   switch (protocol)
194     {
195     case GPGME_PROTOCOL_OpenPGP:
196       ctx->use_cms = 0;
197       break;
198     case GPGME_PROTOCOL_CMS:
199       ctx->use_cms = 1;
200       break;
201     case GPGME_PROTOCOL_AUTO:
202       return mk_error (Not_Implemented);
203     default:
204       return mk_error (Invalid_Value);
205     }
206   
207   return 0;
208 }
209
210
211 /**
212  * gpgme_set_armor:
213  * @ctx: the context 
214  * @yes: boolean value to set or clear that flag
215  * 
216  * Enable or disable the use of an ascii armor for all output.  
217  **/
218 void
219 gpgme_set_armor (GpgmeCtx ctx, int yes)
220 {
221   if (!ctx)
222     return;
223   ctx->use_armor = yes;
224 }
225
226
227 /**
228  * gpgme_get_armor:
229  * @ctx: the context
230  * 
231  * Return the state of the armor flag which can be changed using
232  * gpgme_set_armor().
233  * 
234  * Return value: Boolean whether armor mode is to be used.
235  **/
236 int 
237 gpgme_get_armor (GpgmeCtx ctx)
238 {
239   return ctx && ctx->use_armor;
240 }
241
242
243 /**
244  * gpgme_set_textmode:
245  * @ctx: the context
246  * @yes: boolean flag whether textmode should be enabled
247  * 
248  * Enable or disable the use of the special textmode.  Textmode is for example
249  * used for the RFC2015 signatures; note that the updated RFC 3156 mandates 
250  * that the MUA does some preparations so that textmode is not needed anymore.
251  **/
252 void
253 gpgme_set_textmode (GpgmeCtx ctx, int yes)
254 {
255   if (!ctx)
256     return;
257   ctx->use_textmode = yes;
258 }
259
260 /**
261  * gpgme_get_textmode:
262  * @ctx: the context
263  * 
264  * Return the state of the textmode flag which can be changed using
265  * gpgme_set_textmode().
266  * 
267  * Return value: Boolean whether textmode is to be used.
268  **/
269 int 
270 gpgme_get_textmode (GpgmeCtx ctx)
271 {
272   return ctx && ctx->use_textmode;
273 }
274
275
276 /**
277  * gpgme_set_keylist_mode:
278  * @ctx: the context
279  * @mode: listing mode
280  * 
281  * This function changes the default behaviour of the keylisting functions.
282  * Defines values for @mode are: %0 = normal, %1 = fast listing without
283  * information about key validity.
284  **/
285 void
286 gpgme_set_keylist_mode (GpgmeCtx ctx, int mode)
287 {
288   if (!ctx)
289     return;
290   ctx->keylist_mode = mode;
291 }
292
293
294 /**
295  * gpgme_set_passphrase_cb:
296  * @ctx: the context 
297  * @cb: A callback function
298  * @cb_value: The value passed to the callback function
299  * 
300  * This function sets a callback function to be used to pass a passphrase
301  * to gpg. The preferred way to handle this is by using the gpg-agent, but
302  * because that beast is not ready for real use, you can use this passphrase
303  * thing.
304  *
305  * The callback function is defined as:
306  * <literal>
307  * typedef const char *(*GpgmePassphraseCb)(void*cb_value,
308  *                                          const char *desc,
309  *                                          void **r_hd);
310  * </literal>
311  * and called whenever gpgme needs a passphrase. DESC will have a nice
312  * text, to be used to prompt for the passphrase and R_HD is just a parameter
313  * to be used by the callback it self.  Because the callback returns a const
314  * string, the callback might want to know when it can release resources
315  * assocated with that returned string; gpgme helps here by calling this
316  * passphrase callback with an DESC of %NULL as soon as it does not need
317  * the returned string anymore.  The callback function might then choose
318  * to release resources depending on R_HD.
319  *
320  **/
321 void
322 gpgme_set_passphrase_cb (GpgmeCtx ctx, GpgmePassphraseCb cb, void *cb_value)
323 {
324   if (ctx)
325     {
326       ctx->passphrase_cb = cb;
327       ctx->passphrase_cb_value = cb_value;
328     }
329 }
330
331 /**
332  * gpgme_set_progress_cb:
333  * @ctx: the context 
334  * @cb: A callback function
335  * @cb_value: The value passed to the callback function
336  * 
337  * This function sets a callback function to be used as a progress indicator.
338  *
339  * The callback function is defined as:
340  * <literal>
341  * typedef void (*GpgmeProgressCb) (void *cb_value,
342  *                                  const char *what, int type,
343  *                                  int curretn, int total);
344  * </literal>
345  * For details on the progress events, see the entry for the PROGRESS
346  * status in the file doc/DETAILS of the GnuPG distribution.
347  **/
348 void
349 gpgme_set_progress_cb (GpgmeCtx ctx, GpgmeProgressCb cb, void *cb_value)
350 {
351   if (ctx)
352     {
353       ctx->progress_cb = cb;
354       ctx->progress_cb_value = cb_value;
355     }
356 }