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