doc: Fix documentation of struct data types
[gpgme.git] / src / gpgme.c
1 /* gpgme.c - GnuPG Made Easy.
2    Copyright (C) 2000 Werner Koch (dd9jn)
3    Copyright (C) 2001, 2002, 2003, 2004, 2005, 2007, 2012 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 Lesser General Public License as
9    published by the Free Software Foundation; either version 2.1 of
10    the License, or (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    Lesser General Public License for more details.
16
17    You should have received a copy of the GNU Lesser General Public
18    License along with this program; if not, write to the Free Software
19    Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
20    02111-1307, USA.  */
21
22 #if HAVE_CONFIG_H
23 #include <config.h>
24 #endif
25 #include <stdio.h>
26 #include <stdlib.h>
27 #include <string.h>
28 #include <assert.h>
29 #include <errno.h>
30 #ifdef HAVE_LOCALE_H
31 #include <locale.h>
32 #endif
33
34 #include "util.h"
35 #include "context.h"
36 #include "ops.h"
37 #include "wait.h"
38 #include "debug.h"
39 #include "priv-io.h"
40 #include "sys-util.h"
41
42 \f
43 /* The default locale.  */
44 DEFINE_STATIC_LOCK (def_lc_lock);
45 static char *def_lc_ctype;
46 static char *def_lc_messages;
47
48 \f
49 gpgme_error_t _gpgme_selftest = GPG_ERR_NOT_OPERATIONAL;
50
51 /* Protects all reference counters in result structures.  All other
52    accesses to a result structure are read only.  */
53 DEFINE_STATIC_LOCK (result_ref_lock);
54
55 \f
56 /* Set the global flag NAME to VALUE.  Return 0 on success.  Note that
57    this function does not use gpgme_error and thus a non-zero return
58    value merely means "error".  Certain flags may be set before
59    gpgme_check_version is called.  See the manual for a description of
60    supported flags.  The caller must assure that this function is
61    called only by one thread at a time.  */
62 int
63 gpgme_set_global_flag (const char *name, const char *value)
64 {
65   if (!name || !value)
66     return -1;
67   else if (!strcmp (name, "debug"))
68     return _gpgme_debug_set_debug_envvar (value);
69   else if (!strcmp (name, "disable-gpgconf"))
70     {
71       _gpgme_dirinfo_disable_gpgconf ();
72       return 0;
73     }
74   else if (!strcmp (name, "gpgconf-name"))
75     return _gpgme_set_default_gpgconf_name (value);
76   else if (!strcmp (name, "gpg-name"))
77     return _gpgme_set_default_gpg_name (value);
78   else
79     return -1;
80 }
81
82
83 \f
84 /* Create a new context as an environment for GPGME crypto
85    operations.  */
86 gpgme_error_t
87 gpgme_new (gpgme_ctx_t *r_ctx)
88 {
89   gpgme_error_t err;
90   gpgme_ctx_t ctx;
91   TRACE_BEG (DEBUG_CTX, "gpgme_new", r_ctx);
92
93   if (_gpgme_selftest)
94     return TRACE_ERR (gpgme_error (_gpgme_selftest));
95
96   if (!r_ctx)
97     return TRACE_ERR (gpg_error (GPG_ERR_INV_VALUE));
98
99   ctx = calloc (1, sizeof *ctx);
100   if (!ctx)
101     return TRACE_ERR (gpg_error_from_syserror ());
102
103   INIT_LOCK (ctx->lock);
104
105   err = _gpgme_engine_info_copy (&ctx->engine_info);
106   if (!err && !ctx->engine_info)
107     err = gpg_error (GPG_ERR_NO_ENGINE);
108   if (err)
109     {
110       free (ctx);
111       return TRACE_ERR (err);
112     }
113
114   ctx->keylist_mode = GPGME_KEYLIST_MODE_LOCAL;
115   ctx->include_certs = GPGME_INCLUDE_CERTS_DEFAULT;
116   ctx->protocol = GPGME_PROTOCOL_OpenPGP;
117   ctx->sub_protocol = GPGME_PROTOCOL_DEFAULT;
118   _gpgme_fd_table_init (&ctx->fdt);
119
120   LOCK (def_lc_lock);
121   if (def_lc_ctype)
122     {
123       ctx->lc_ctype = strdup (def_lc_ctype);
124       if (!ctx->lc_ctype)
125         {
126           int saved_err = gpg_error_from_syserror ();
127           UNLOCK (def_lc_lock);
128           _gpgme_engine_info_release (ctx->engine_info);
129           free (ctx);
130           return TRACE_ERR (saved_err);
131         }
132     }
133   else
134     def_lc_ctype = NULL;
135
136   if (def_lc_messages)
137     {
138       ctx->lc_messages = strdup (def_lc_messages);
139       if (!ctx->lc_messages)
140         {
141           int saved_err = gpg_error_from_syserror ();
142           UNLOCK (def_lc_lock);
143           if (ctx->lc_ctype)
144             free (ctx->lc_ctype);
145           _gpgme_engine_info_release (ctx->engine_info);
146           free (ctx);
147           return TRACE_ERR (saved_err);
148         }
149     }
150   else
151     def_lc_messages = NULL;
152   UNLOCK (def_lc_lock);
153
154   *r_ctx = ctx;
155
156   return TRACE_SUC1 ("ctx=%p", ctx);
157 }
158
159
160 gpgme_error_t
161 _gpgme_cancel_with_err (gpgme_ctx_t ctx, gpg_error_t ctx_err,
162                         gpg_error_t op_err)
163 {
164   gpgme_error_t err;
165   struct gpgme_io_event_done_data data;
166
167   TRACE_BEG2 (DEBUG_CTX, "_gpgme_cancel_with_err", ctx, "ctx_err=%i, op_err=%i",
168               ctx_err, op_err);
169
170   if (ctx_err)
171     {
172       err = _gpgme_engine_cancel (ctx->engine);
173       if (err)
174         return TRACE_ERR (err);
175     }
176   else
177     {
178       err = _gpgme_engine_cancel_op (ctx->engine);
179       if (err)
180         return TRACE_ERR (err);
181     }
182
183   data.err = ctx_err;
184   data.op_err = op_err;
185
186   _gpgme_engine_io_event (ctx->engine, GPGME_EVENT_DONE, &data);
187
188   return TRACE_ERR (0);
189 }
190
191
192 /* Cancel a pending asynchronous operation.  */
193 gpgme_error_t
194 gpgme_cancel (gpgme_ctx_t ctx)
195 {
196   gpg_error_t err;
197
198   TRACE_BEG (DEBUG_CTX, "gpgme_cancel", ctx);
199
200   if (!ctx)
201     return TRACE_ERR (gpg_error (GPG_ERR_INV_VALUE));
202
203   err = _gpgme_cancel_with_err (ctx, gpg_error (GPG_ERR_CANCELED), 0);
204
205   return TRACE_ERR (err);
206 }
207
208
209 /* Cancel a pending operation asynchronously.  */
210 gpgme_error_t
211 gpgme_cancel_async (gpgme_ctx_t ctx)
212 {
213   TRACE_BEG (DEBUG_CTX, "gpgme_cancel_async", ctx);
214
215   if (!ctx)
216     return TRACE_ERR (gpg_error (GPG_ERR_INV_VALUE));
217
218   LOCK (ctx->lock);
219   ctx->canceled = 1;
220   UNLOCK (ctx->lock);
221
222   return TRACE_ERR (0);
223 }
224
225
226 /* Release all resources associated with the given context.  */
227 void
228 gpgme_release (gpgme_ctx_t ctx)
229 {
230   TRACE (DEBUG_CTX, "gpgme_release", ctx);
231
232   if (!ctx)
233     return;
234
235   _gpgme_engine_release (ctx->engine);
236   _gpgme_fd_table_deinit (&ctx->fdt);
237   _gpgme_release_result (ctx);
238   _gpgme_signers_clear (ctx);
239   _gpgme_sig_notation_clear (ctx);
240   if (ctx->signers)
241     free (ctx->signers);
242   if (ctx->lc_ctype)
243     free (ctx->lc_ctype);
244   if (ctx->lc_messages)
245     free (ctx->lc_messages);
246   _gpgme_engine_info_release (ctx->engine_info);
247   DESTROY_LOCK (ctx->lock);
248   free (ctx);
249 }
250
251
252 void
253 gpgme_result_ref (void *result)
254 {
255   struct ctx_op_data *data;
256
257   if (! result)
258     return;
259
260   data = (void*)((char*)result - sizeof (struct ctx_op_data));
261
262   assert (data->magic == CTX_OP_DATA_MAGIC);
263
264   LOCK (result_ref_lock);
265   data->references++;
266   UNLOCK (result_ref_lock);
267 }
268
269
270 void
271 gpgme_result_unref (void *result)
272 {
273   struct ctx_op_data *data;
274
275   if (! result)
276     return;
277
278   data = (void*)((char*)result - sizeof (struct ctx_op_data));
279
280   assert (data->magic == CTX_OP_DATA_MAGIC);
281
282   LOCK (result_ref_lock);
283   if (--data->references)
284     {
285       UNLOCK (result_ref_lock);
286       return;
287     }
288   UNLOCK (result_ref_lock);
289
290   if (data->cleanup)
291     (*data->cleanup) (data->hook);
292   free (data);
293 }
294
295
296 void
297 _gpgme_release_result (gpgme_ctx_t ctx)
298 {
299   struct ctx_op_data *data = ctx->op_data;
300
301   while (data)
302     {
303       struct ctx_op_data *next_data = data->next;
304       data->next = NULL;
305       gpgme_result_unref (data->hook);
306       data = next_data;
307     }
308   ctx->op_data = NULL;
309 }
310
311
312 gpgme_error_t
313 gpgme_set_protocol (gpgme_ctx_t ctx, gpgme_protocol_t protocol)
314 {
315   TRACE_BEG2 (DEBUG_CTX, "gpgme_set_protocol", ctx, "protocol=%i (%s)",
316               protocol, gpgme_get_protocol_name (protocol)
317               ? gpgme_get_protocol_name (protocol) : "invalid");
318
319   if (protocol != GPGME_PROTOCOL_OpenPGP
320       && protocol != GPGME_PROTOCOL_CMS
321       && protocol != GPGME_PROTOCOL_GPGCONF
322       && protocol != GPGME_PROTOCOL_ASSUAN
323       && protocol != GPGME_PROTOCOL_G13
324       && protocol != GPGME_PROTOCOL_UISERVER)
325     return TRACE_ERR (gpg_error (GPG_ERR_INV_VALUE));
326
327   if (!ctx)
328     return TRACE_ERR (gpg_error (GPG_ERR_INV_VALUE));
329
330   if (ctx->protocol != protocol)
331     {
332       /* Shut down the engine when switching protocols.  */
333       if (ctx->engine)
334         {
335           TRACE_LOG1 ("releasing ctx->engine=%p", ctx->engine);
336           _gpgme_engine_release (ctx->engine);
337           ctx->engine = NULL;
338         }
339
340       ctx->protocol = protocol;
341     }
342   return TRACE_ERR (0);
343 }
344
345
346 gpgme_protocol_t
347 gpgme_get_protocol (gpgme_ctx_t ctx)
348 {
349   TRACE2 (DEBUG_CTX, "gpgme_get_protocol", ctx,
350           "ctx->protocol=%i (%s)", ctx->protocol,
351           gpgme_get_protocol_name (ctx->protocol)
352           ? gpgme_get_protocol_name (ctx->protocol) : "invalid");
353
354   return ctx->protocol;
355 }
356
357
358 gpgme_error_t
359 gpgme_set_sub_protocol (gpgme_ctx_t ctx, gpgme_protocol_t protocol)
360 {
361   TRACE2 (DEBUG_CTX, "gpgme_set_sub_protocol", ctx, "protocol=%i (%s)",
362           protocol, gpgme_get_protocol_name (protocol)
363           ? gpgme_get_protocol_name (protocol) : "invalid");
364
365   if (!ctx)
366     return gpg_error (GPG_ERR_INV_VALUE);
367
368   ctx->sub_protocol = protocol;
369   return 0;
370 }
371
372
373 gpgme_error_t
374 gpgme_get_sub_protocol (gpgme_ctx_t ctx)
375 {
376   TRACE2 (DEBUG_CTX, "gpgme_get_sub_protocol", ctx,
377           "ctx->sub_protocol=%i (%s)", ctx->sub_protocol,
378           gpgme_get_protocol_name (ctx->sub_protocol)
379           ? gpgme_get_protocol_name (ctx->sub_protocol) : "invalid");
380
381   return ctx->sub_protocol;
382 }
383
384
385 const char *
386 gpgme_get_protocol_name (gpgme_protocol_t protocol)
387 {
388   switch (protocol)
389     {
390     case GPGME_PROTOCOL_OpenPGP:
391       return "OpenPGP";
392
393     case GPGME_PROTOCOL_CMS:
394       return "CMS";
395
396     case GPGME_PROTOCOL_GPGCONF:
397       return "GPGCONF";
398
399     case GPGME_PROTOCOL_ASSUAN:
400       return "Assuan";
401
402     case GPGME_PROTOCOL_G13:
403       return "G13";
404
405     case GPGME_PROTOCOL_UISERVER:
406       return "UIServer";
407
408     case GPGME_PROTOCOL_DEFAULT:
409       return "default";
410
411     case GPGME_PROTOCOL_UNKNOWN:
412       return "unknown";
413
414     default:
415       return NULL;
416     }
417 }
418
419 /* Enable or disable the use of an ascii armor for all output.  */
420 void
421 gpgme_set_armor (gpgme_ctx_t ctx, int use_armor)
422 {
423   TRACE2 (DEBUG_CTX, "gpgme_set_armor", ctx, "use_armor=%i (%s)",
424           use_armor, use_armor ? "yes" : "no");
425
426   if (!ctx)
427     return;
428
429   ctx->use_armor = use_armor;
430 }
431
432
433 /* Return the state of the armor flag.  */
434 int
435 gpgme_get_armor (gpgme_ctx_t ctx)
436 {
437   TRACE2 (DEBUG_CTX, "gpgme_get_armor", ctx, "ctx->use_armor=%i (%s)",
438           ctx->use_armor, ctx->use_armor ? "yes" : "no");
439   return ctx->use_armor;
440 }
441
442
443 /* Enable or disable the use of the special textmode.  Textmode is for
444   example used for the RFC2015 signatures; note that the updated RFC
445   3156 mandates that the MUA does some preparations so that textmode
446   is not needed anymore.  */
447 void
448 gpgme_set_textmode (gpgme_ctx_t ctx, int use_textmode)
449 {
450   TRACE2 (DEBUG_CTX, "gpgme_set_textmode", ctx, "use_textmode=%i (%s)",
451           use_textmode, use_textmode ? "yes" : "no");
452
453   if (!ctx)
454     return;
455
456   ctx->use_textmode = use_textmode;
457 }
458
459 /* Return the state of the textmode flag.  */
460 int
461 gpgme_get_textmode (gpgme_ctx_t ctx)
462 {
463   TRACE2 (DEBUG_CTX, "gpgme_get_textmode", ctx, "ctx->use_textmode=%i (%s)",
464           ctx->use_textmode, ctx->use_textmode ? "yes" : "no");
465   return ctx->use_textmode;
466 }
467
468
469 /* Set the number of certifications to include in an S/MIME message.
470    The default is GPGME_INCLUDE_CERTS_DEFAULT.  -1 means all certs,
471    and -2 means all certs except the root cert.  */
472 void
473 gpgme_set_include_certs (gpgme_ctx_t ctx, int nr_of_certs)
474 {
475   if (!ctx)
476     return;
477
478   if (nr_of_certs == GPGME_INCLUDE_CERTS_DEFAULT)
479     ctx->include_certs = GPGME_INCLUDE_CERTS_DEFAULT;
480   else if (nr_of_certs < -2)
481     ctx->include_certs = -2;
482   else
483     ctx->include_certs = nr_of_certs;
484
485   TRACE2 (DEBUG_CTX, "gpgme_set_include_certs", ctx, "nr_of_certs=%i%s",
486           nr_of_certs, nr_of_certs == ctx->include_certs ? "" : " (-2)");
487 }
488
489
490 /* Get the number of certifications to include in an S/MIME
491    message.  */
492 int
493 gpgme_get_include_certs (gpgme_ctx_t ctx)
494 {
495   TRACE1 (DEBUG_CTX, "gpgme_get_include_certs", ctx, "ctx->include_certs=%i",
496           ctx->include_certs);
497   return ctx->include_certs;
498 }
499
500
501 /* This function changes the default behaviour of the keylisting
502    functions.  MODE is a bitwise-OR of the GPGME_KEYLIST_* flags.  The
503    default mode is GPGME_KEYLIST_MODE_LOCAL.  */
504 gpgme_error_t
505 gpgme_set_keylist_mode (gpgme_ctx_t ctx, gpgme_keylist_mode_t mode)
506 {
507   TRACE1 (DEBUG_CTX, "gpgme_set_keylist_mode", ctx, "keylist_mode=0x%x",
508           mode);
509
510   if (!ctx)
511     return gpg_error (GPG_ERR_INV_VALUE);
512
513   ctx->keylist_mode = mode;
514   return 0;
515 }
516
517 /* This function returns the default behaviour of the keylisting
518    functions.  */
519 gpgme_keylist_mode_t
520 gpgme_get_keylist_mode (gpgme_ctx_t ctx)
521 {
522   TRACE1 (DEBUG_CTX, "gpgme_get_keylist_mode", ctx,
523           "ctx->keylist_mode=0x%x", ctx->keylist_mode);
524   return ctx->keylist_mode;
525 }
526
527
528 /* Set the pinentry mode for CTX to MODE. */
529 gpgme_error_t
530 gpgme_set_pinentry_mode (gpgme_ctx_t ctx, gpgme_pinentry_mode_t mode)
531 {
532   TRACE1 (DEBUG_CTX, "gpgme_set_pinentry_mode", ctx, "pinentry_mode=%u",
533           (unsigned int)mode);
534
535   if (!ctx)
536     return gpg_error (GPG_ERR_INV_VALUE);
537
538   switch (mode)
539     {
540     case GPGME_PINENTRY_MODE_DEFAULT:
541     case GPGME_PINENTRY_MODE_ASK:
542     case GPGME_PINENTRY_MODE_CANCEL:
543     case GPGME_PINENTRY_MODE_ERROR:
544     case GPGME_PINENTRY_MODE_LOOPBACK:
545       break;
546     default:
547       return gpg_error (GPG_ERR_INV_VALUE);
548     }
549
550   ctx->pinentry_mode = mode;
551   return 0;
552 }
553
554
555 /* Get the pinentry mode of CTX.  */
556 gpgme_pinentry_mode_t
557 gpgme_get_pinentry_mode (gpgme_ctx_t ctx)
558 {
559   TRACE1 (DEBUG_CTX, "gpgme_get_pinentry_mode", ctx,
560           "ctx->pinentry_mode=%u", (unsigned int)ctx->pinentry_mode);
561   return ctx->pinentry_mode;
562 }
563
564
565 /* This function sets a callback function to be used to pass a
566    passphrase to gpg.  */
567 void
568 gpgme_set_passphrase_cb (gpgme_ctx_t ctx, gpgme_passphrase_cb_t cb,
569                          void *cb_value)
570 {
571   TRACE2 (DEBUG_CTX, "gpgme_set_passphrase_cb", ctx,
572           "passphrase_cb=%p/%p", cb, cb_value);
573
574   if (!ctx)
575     return;
576
577   ctx->passphrase_cb = cb;
578   ctx->passphrase_cb_value = cb_value;
579 }
580
581
582 /* This function returns the callback function to be used to pass a
583    passphrase to the crypto engine.  */
584 void
585 gpgme_get_passphrase_cb (gpgme_ctx_t ctx, gpgme_passphrase_cb_t *r_cb,
586                          void **r_cb_value)
587 {
588   TRACE2 (DEBUG_CTX, "gpgme_get_passphrase_cb", ctx,
589           "ctx->passphrase_cb=%p/%p",
590           ctx->passphrase_cb, ctx->passphrase_cb_value);
591   if (r_cb)
592     *r_cb = ctx->passphrase_cb;
593   if (r_cb_value)
594     *r_cb_value = ctx->passphrase_cb_value;
595 }
596
597
598 /* This function sets a callback function to be used as a progress
599    indicator.  */
600 void
601 gpgme_set_progress_cb (gpgme_ctx_t ctx, gpgme_progress_cb_t cb, void *cb_value)
602 {
603   TRACE2 (DEBUG_CTX, "gpgme_set_progress_cb", ctx, "progress_cb=%p/%p",
604           cb, cb_value);
605
606   if (!ctx)
607     return;
608
609   ctx->progress_cb = cb;
610   ctx->progress_cb_value = cb_value;
611 }
612
613
614 /* This function returns the callback function to be used as a
615    progress indicator.  */
616 void
617 gpgme_get_progress_cb (gpgme_ctx_t ctx, gpgme_progress_cb_t *r_cb,
618                        void **r_cb_value)
619 {
620   TRACE2 (DEBUG_CTX, "gpgme_get_progress_cb", ctx, "ctx->progress_cb=%p/%p",
621           ctx->progress_cb, ctx->progress_cb_value);
622   if (r_cb)
623     *r_cb = ctx->progress_cb;
624   if (r_cb_value)
625     *r_cb_value = ctx->progress_cb_value;
626 }
627
628
629 /* Set the I/O callback functions for CTX to IO_CBS.  */
630 void
631 gpgme_set_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs)
632 {
633   if (!ctx)
634     return;
635
636   if (io_cbs)
637     {
638       TRACE6 (DEBUG_CTX, "gpgme_set_io_cbs", ctx,
639               "io_cbs=%p (add=%p/%p, remove=%p, event=%p/%p",
640               io_cbs, io_cbs->add, io_cbs->add_priv, io_cbs->remove,
641               io_cbs->event, io_cbs->event_priv);
642       ctx->io_cbs = *io_cbs;
643     }
644   else
645     {
646       TRACE1 (DEBUG_CTX, "gpgme_set_io_cbs", ctx,
647               "io_cbs=%p (default)", io_cbs);
648       ctx->io_cbs.add = NULL;
649       ctx->io_cbs.add_priv = NULL;
650       ctx->io_cbs.remove = NULL;
651       ctx->io_cbs.event = NULL;
652       ctx->io_cbs.event_priv = NULL;
653     }
654 }
655
656
657 /* This function provides access to the internal read function; it is
658    normally not used.  */
659 gpgme_ssize_t
660 gpgme_io_read (int fd, void *buffer, size_t count)
661 {
662   int ret;
663   TRACE_BEG2 (DEBUG_GLOBAL, "gpgme_io_read", fd,
664               "buffer=%p, count=%u", buffer, count);
665
666   ret = _gpgme_io_read (fd, buffer, count);
667
668   return TRACE_SYSRES (ret);
669 }
670
671
672 /* This function provides access to the internal write function.  It
673    is to be used by user callbacks to return data to gpgme.  See
674    gpgme_passphrase_cb_t and gpgme_edit_cb_t.  */
675 gpgme_ssize_t
676 gpgme_io_write (int fd, const void *buffer, size_t count)
677 {
678   int ret;
679   TRACE_BEG2 (DEBUG_GLOBAL, "gpgme_io_write", fd,
680               "buffer=%p, count=%u", buffer, count);
681
682   ret = _gpgme_io_write (fd, buffer, count);
683
684   return TRACE_SYSRES (ret);
685 }
686
687 /* This function provides access to the internal write function.  It
688    is to be used by user callbacks to return data to gpgme.  See
689    gpgme_passphrase_cb_t and gpgme_edit_cb_t.  Note that this is a
690    variant of gpgme_io_write which guarantees that all COUNT bytes are
691    written or an error is return.  Returns: 0 on success or -1 on
692    error and the sets errno. */
693 int
694 gpgme_io_writen (int fd, const void *buffer, size_t count)
695 {
696   int ret = 0;
697   TRACE_BEG2 (DEBUG_GLOBAL, "gpgme_io_writen", fd,
698               "buffer=%p, count=%u", buffer, count);
699   while (count)
700     {
701       ret = _gpgme_io_write (fd, buffer, count);
702       if (ret < 0)
703         break;
704       buffer += ret;
705       count -= ret;
706       ret = 0;
707     }
708   return TRACE_SYSRES (ret);
709 }
710
711
712 /* This function returns the callback function for I/O.  */
713 void
714 gpgme_get_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs)
715 {
716   TRACE6 (DEBUG_CTX, "gpgme_get_io_cbs", ctx,
717           "io_cbs=%p, ctx->io_cbs.add=%p/%p, .remove=%p, .event=%p/%p",
718           io_cbs, io_cbs->add, io_cbs->add_priv, io_cbs->remove,
719           io_cbs->event, io_cbs->event_priv);
720
721   *io_cbs = ctx->io_cbs;
722 }
723
724 \f
725 /* This function sets the locale for the context CTX, or the default
726    locale if CTX is a null pointer.  */
727 gpgme_error_t
728 gpgme_set_locale (gpgme_ctx_t ctx, int category, const char *value)
729 {
730   int failed = 0;
731   char *new_lc_ctype = NULL;
732   char *new_lc_messages = NULL;
733
734   TRACE_BEG2 (DEBUG_CTX, "gpgme_set_locale", ctx,
735                "category=%i, value=%s", category, value ? value : "(null)");
736
737 #define PREPARE_ONE_LOCALE(lcat, ucat)                          \
738   if (!failed && value                                          \
739       && (category == LC_ALL || category == LC_ ## ucat))       \
740     {                                                           \
741       new_lc_ ## lcat = strdup (value);                         \
742       if (!new_lc_ ## lcat)                                     \
743         failed = 1;                                             \
744     }
745
746 #ifdef LC_CTYPE
747   PREPARE_ONE_LOCALE (ctype, CTYPE);
748 #endif
749 #ifdef LC_MESSAGES
750   PREPARE_ONE_LOCALE (messages, MESSAGES);
751 #endif
752
753   if (failed)
754     {
755       int saved_err = gpg_error_from_syserror ();
756
757       if (new_lc_ctype)
758         free (new_lc_ctype);
759       if (new_lc_messages)
760         free (new_lc_messages);
761
762       return TRACE_ERR (saved_err);
763     }
764
765 #define SET_ONE_LOCALE(lcat, ucat)                      \
766   if (category == LC_ALL || category == LC_ ## ucat)    \
767     {                                                   \
768       if (ctx)                                          \
769         {                                               \
770           if (ctx->lc_ ## lcat)                         \
771             free (ctx->lc_ ## lcat);                    \
772           ctx->lc_ ## lcat = new_lc_ ## lcat;           \
773         }                                               \
774       else                                              \
775         {                                               \
776           if (def_lc_ ## lcat)                          \
777             free (def_lc_ ## lcat);                     \
778           def_lc_ ## lcat = new_lc_ ## lcat;            \
779         }                                               \
780     }
781
782   if (!ctx)
783     LOCK (def_lc_lock);
784 #ifdef LC_CTYPE
785   SET_ONE_LOCALE (ctype, CTYPE);
786 #endif
787 #ifdef LC_MESSAGES
788   SET_ONE_LOCALE (messages, MESSAGES);
789 #endif
790   if (!ctx)
791     UNLOCK (def_lc_lock);
792
793   return TRACE_ERR (0);
794 }
795
796 \f
797 /* Get the information about the configured engines.  A pointer to the
798    first engine in the statically allocated linked list is returned.
799    The returned data is valid until the next gpgme_ctx_set_engine_info.  */
800 gpgme_engine_info_t
801 gpgme_ctx_get_engine_info (gpgme_ctx_t ctx)
802 {
803   TRACE1 (DEBUG_CTX, "gpgme_ctx_get_engine_info", ctx,
804           "ctx->engine_info=%p", ctx->engine_info);
805   return ctx->engine_info;
806 }
807
808
809 /* Set the engine info for the context CTX, protocol PROTO, to the
810    file name FILE_NAME and the home directory HOME_DIR.  */
811 gpgme_error_t
812 gpgme_ctx_set_engine_info (gpgme_ctx_t ctx, gpgme_protocol_t proto,
813                            const char *file_name, const char *home_dir)
814 {
815   gpgme_error_t err;
816   TRACE_BEG4 (DEBUG_CTX, "gpgme_ctx_set_engine_info", ctx,
817               "protocol=%i (%s), file_name=%s, home_dir=%s",
818               proto, gpgme_get_protocol_name (proto)
819               ? gpgme_get_protocol_name (proto) : "unknown",
820               file_name ? file_name : "(default)",
821               home_dir ? home_dir : "(default)");
822
823   if (!ctx)
824     return TRACE_ERR (gpg_error (GPG_ERR_INV_VALUE));
825
826   /* Shut down the engine when changing engine info.  */
827   if (ctx->engine)
828     {
829       TRACE_LOG1 ("releasing ctx->engine=%p", ctx->engine);
830       _gpgme_engine_release (ctx->engine);
831       ctx->engine = NULL;
832     }
833   err = _gpgme_set_engine_info (ctx->engine_info, proto,
834                                 file_name, home_dir);
835   return TRACE_ERR (err);
836 }
837
838 \f
839 /* Clear all notation data from the context.  */
840 void
841 _gpgme_sig_notation_clear (gpgme_ctx_t ctx)
842 {
843   gpgme_sig_notation_t notation;
844
845   if (!ctx)
846     return;
847
848   notation = ctx->sig_notations;
849   while (notation)
850     {
851       gpgme_sig_notation_t next_notation = notation->next;
852       _gpgme_sig_notation_free (notation);
853       notation = next_notation;
854     }
855   ctx->sig_notations = NULL;
856 }
857
858 void
859 gpgme_sig_notation_clear (gpgme_ctx_t ctx)
860 {
861   TRACE (DEBUG_CTX, "gpgme_sig_notation_clear", ctx);
862
863   if (!ctx)
864     return;
865
866   _gpgme_sig_notation_clear (ctx);
867 }
868
869
870 /* Add the human-readable notation data with name NAME and value VALUE
871    to the context CTX, using the flags FLAGS.  If NAME is NULL, then
872    VALUE should be a policy URL.  The flag
873    GPGME_SIG_NOTATION_HUMAN_READABLE is forced to be true for notation
874    data, and false for policy URLs.  */
875 gpgme_error_t
876 gpgme_sig_notation_add (gpgme_ctx_t ctx, const char *name,
877                         const char *value, gpgme_sig_notation_flags_t flags)
878 {
879   gpgme_error_t err;
880   gpgme_sig_notation_t notation;
881   gpgme_sig_notation_t *lastp;
882
883   TRACE_BEG3 (DEBUG_CTX, "gpgme_sig_notation_add", ctx,
884               "name=%s, value=%s, flags=0x%x",
885               name ? name : "(null)", value ? value : "(null)",
886               flags);
887
888   if (!ctx)
889     return TRACE_ERR (gpg_error (GPG_ERR_INV_VALUE));
890
891   if (name)
892     flags |= GPGME_SIG_NOTATION_HUMAN_READABLE;
893   else
894     flags &= ~GPGME_SIG_NOTATION_HUMAN_READABLE;
895
896   err = _gpgme_sig_notation_create (&notation, name, name ? strlen (name) : 0,
897                                     value, value ? strlen (value) : 0, flags);
898   if (err)
899     return TRACE_ERR (err);
900
901   lastp = &ctx->sig_notations;
902   while (*lastp)
903     lastp = &(*lastp)->next;
904
905   *lastp = notation;
906   return TRACE_ERR (0);
907 }
908
909
910 /* Get the sig notations for this context.  */
911 gpgme_sig_notation_t
912 gpgme_sig_notation_get (gpgme_ctx_t ctx)
913 {
914   if (!ctx)
915     {
916       TRACE (DEBUG_CTX, "gpgme_sig_notation_get", ctx);
917       return NULL;
918     }
919   TRACE1 (DEBUG_CTX, "gpgme_sig_notation_get", ctx,
920           "ctx->sig_notations=%p", ctx->sig_notations);
921
922   return ctx->sig_notations;
923 }
924
925 \f
926 const char *
927 gpgme_pubkey_algo_name (gpgme_pubkey_algo_t algo)
928 {
929   switch (algo)
930     {
931     case GPGME_PK_RSA:
932       return "RSA";
933
934     case GPGME_PK_RSA_E:
935       return "RSA-E";
936
937     case GPGME_PK_RSA_S:
938       return "RSA-S";
939
940     case GPGME_PK_ELG_E:
941       return "ELG-E";
942
943     case GPGME_PK_DSA:
944       return "DSA";
945
946     case GPGME_PK_ELG:
947       return "ELG";
948
949     case GPGME_PK_ECDSA:
950       return "ECDSA";
951
952     case GPGME_PK_ECDH:
953       return "ECDH";
954
955     default:
956       return NULL;
957     }
958 }
959
960
961 const char *
962 gpgme_hash_algo_name (gpgme_hash_algo_t algo)
963 {
964   switch (algo)
965     {
966     case GPGME_MD_MD5:
967       return "MD5";
968
969     case GPGME_MD_SHA1:
970       return "SHA1";
971
972     case GPGME_MD_RMD160:
973       return "RIPEMD160";
974
975     case GPGME_MD_MD2:
976       return "MD2";
977
978     case GPGME_MD_TIGER:
979       return "TIGER192";
980
981     case GPGME_MD_HAVAL:
982       return "HAVAL";
983
984     case GPGME_MD_SHA256:
985       return "SHA256";
986
987     case GPGME_MD_SHA384:
988       return "SHA384";
989
990     case GPGME_MD_SHA512:
991       return "SHA512";
992
993     case GPGME_MD_MD4:
994       return "MD4";
995
996     case GPGME_MD_CRC32:
997       return "CRC32";
998
999     case GPGME_MD_CRC32_RFC1510:
1000       return "CRC32RFC1510";
1001
1002     case GPGME_MD_CRC24_RFC2440:
1003       return "CRC24RFC2440";
1004
1005     default:
1006       return NULL;
1007     }
1008 }