A couple of minor changes and a short README for Gpgcom
[gpgme.git] / gpgme / gpgme.c
1 /* gpgme.c -  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 #include <config.h>
23 #include <stdio.h>
24 #include <stdlib.h>
25 #include <assert.h>
26
27 #include "util.h"
28 #include "context.h"
29 #include "ops.h"
30
31 #define my_isdigit(a)  ( (a) >='0' && (a) <= '9' )
32 #define my_isxdigit(a) ( my_isdigit((a))               \
33                          || ((a) >= 'A' && (a) <= 'F') \
34                          || ((a) >= 'f' && (a) <= 'f') )
35
36 /**
37  * gpgme_new:
38  * @r_ctx: Returns the new context
39  * 
40  * Create a new context to be used with most of the other GPGME
41  * functions.  Use gpgme_release_contect() to release all resources
42  *
43  * Return value: An error code 
44  **/
45 GpgmeError
46 gpgme_new (GpgmeCtx *r_ctx)
47 {
48     GpgmeCtx c;
49
50     c = xtrycalloc ( 1, sizeof *c );
51     if (!c)
52         return mk_error (Out_Of_Core);
53     c->verbosity = 1;
54     *r_ctx = c;
55
56     return 0;
57 }
58
59 /**
60  * gpgme_release:
61  * @c: Context to be released. 
62  * 
63  * Release all resources associated with the given context.
64  **/
65 void
66 gpgme_release ( GpgmeCtx c )
67 {
68     if (!c)
69         return;
70     _gpgme_gpg_release ( c->gpg ); 
71     _gpgme_release_result ( c );
72     gpgme_key_release ( c->tmp_key );
73     gpgme_data_release ( c->help_data_1 );
74     gpgme_data_release ( c->notation );
75     gpgme_signers_clear (c);
76     if (c->signers)
77         xfree (c->signers);
78     /* fixme: release the key_queue */
79     xfree (c);
80 }
81
82
83 void
84 _gpgme_release_result ( GpgmeCtx c )
85 {
86     switch (c->result_type) {
87       case RESULT_TYPE_NONE:
88         break;
89       case RESULT_TYPE_VERIFY:
90         _gpgme_release_verify_result ( c->result.verify );
91         break;
92       case RESULT_TYPE_DECRYPT:
93         _gpgme_release_decrypt_result ( c->result.decrypt );
94         break;
95       case RESULT_TYPE_SIGN:
96         _gpgme_release_sign_result ( c->result.sign );
97         break;
98     }
99
100     c->result.verify = NULL;
101     c->result_type = RESULT_TYPE_NONE;
102 }
103
104
105 /**
106  * gpgme_cancel:
107  * @c: the context
108  * 
109  * Cancel the current operation.  It is not guaranteed that it will work for
110  * all kinds of operations.  It is especially useful in a passphrase callback
111  * to stop the system from asking another time for the passphrase.
112  **/
113
114 void
115 gpgme_cancel (GpgmeCtx c)
116 {
117     return_if_fail (c);
118
119     c->cancel = 1;
120 }
121
122 /**
123  * gpgme_get_notation:
124  * @c: the context 
125  * 
126  * If there is notation data available from the last signature check, this
127  * function may be used to return this notation data as a string.  The string
128  * is an XML represantaton of that data embedded in a %<notation> container.
129  * 
130  * Return value: An XML string or NULL if no notation data is available.
131  **/
132 char *
133 gpgme_get_notation ( GpgmeCtx c )
134 {
135     if ( !c->notation )
136         return NULL;
137     return _gpgme_data_get_as_string ( c->notation );
138 }
139
140 /**
141  * gpgme_set_armor:
142  * @c: the contect 
143  * @yes: boolean value to set or clear that flag
144  * 
145  * Enable or disable the use of an ascii armor for all output.  
146  **/
147 void
148 gpgme_set_armor ( GpgmeCtx c, int yes )
149 {
150     if ( !c )
151         return; /* oops */
152     c->use_armor = yes;
153 }
154
155
156 /**
157  * gpgme_get_armor:
158  * @c: the context
159  * 
160  * Return the state of the armor flag which can be changed using
161  * gpgme_set_armor().
162  * 
163  * Return value: Boolean whether armor mode is to be used.
164  **/
165 int 
166 gpgme_get_armor (GpgmeCtx c)
167 {
168     return c && c->use_armor;
169 }
170
171
172 /**
173  * gpgme_set_textmode:
174  * @c: the context 
175  * @yes: boolean flag whether textmode should be enabled
176  * 
177  * Enable or disable the use of the special textmode.  Textmode is for example
178  * used for MIME (RFC2015) signatures
179  **/
180 void
181 gpgme_set_textmode ( GpgmeCtx c, int yes )
182 {
183     if ( !c )
184         return; /* oops */
185     c->use_textmode = yes;
186 }
187
188 /**
189  * gpgme_get_textmode:
190  * @c: the context
191  * 
192  * Return the state of the textmode flag which can be changed using
193  * gpgme_set_textmode().
194  * 
195  * Return value: Boolean whether textmode is to be used.
196  **/
197 int 
198 gpgme_get_textmode (GpgmeCtx c)
199 {
200     return c && c->use_textmode;
201 }
202
203
204
205 /**
206  * gpgme_set_keylist_mode:
207  * @c: the context
208  * @mode: listing mode
209  * 
210  * This function changes the default behaviour of the keylisting functions.
211  * Defines values for @mode are: %0 = normal, %1 = fast listing without
212  * information about key validity.
213  **/
214 void
215 gpgme_set_keylist_mode ( GpgmeCtx c, int mode )
216 {
217     if (!c)
218         return;
219     c->keylist_mode = mode;
220 }
221
222
223 /**
224  * gpgme_set_passphrase_cb:
225  * @c: the context 
226  * @cb: A callback function
227  * @cb_value: The value passed to the callback function
228  * 
229  * This function sets a callback function to be used to pass a passphrase
230  * to gpg. The preferred way to handle this is by using the gpg-agent, but
231  * because that beast is not ready for real use, you can use this passphrase
232  * thing.
233  *
234  * The callback function is defined as:
235  * <literal>
236  * typedef const char *(*GpgmePassphraseCb)(void*cb_value,
237  *                                          const char *desc,
238  *                                          void *r_hd);
239  * </literal>
240  * and called whenever gpgme needs a passphrase. DESC will have a nice
241  * text, to be used to prompt for the passphrase and R_HD is just a parameter
242  * to be used by the callback it self.  Becuase the callback returns a const
243  * string, the callback might want to know when it can release resources
244  * assocated with that returned string; gpgme helps here by calling this
245  * passphrase callback with an DESC of %NULL as soon as it does not need
246  * the returned string anymore.  The callback function might then choose
247  * to release resources depending on R_HD.
248  *
249  **/
250 void
251 gpgme_set_passphrase_cb ( GpgmeCtx c, GpgmePassphraseCb cb, void *cb_value )
252 {
253     c->passphrase_cb = cb;
254     c->passphrase_cb_value = cb_value;
255 }
256
257 /**
258  * gpgme_set_pprogress_cb:
259  * @c: the context 
260  * @cb: A callback function
261  * @cb_value: The value passed to the callback function
262  * 
263  * This function sets a callback function to be used as a progress indicator.
264  *
265  * The callback function is defined as:
266  * <literal>
267  * typedef void (*GpgmeProgressCb) (void*cb_value,
268  *                                  const char *what, int type,
269  *                                  int curretn, int total);
270  * </literal>
271  * For details on the progress events, see the entry for the PROGRESS
272  * status in the file doc/DETAILS of the GnuPG distribution.
273  **/
274 void
275 gpgme_set_progress_cb ( GpgmeCtx c, GpgmeProgressCb cb, void *cb_value )
276 {
277     c->progress_cb = cb;
278     c->progress_cb_value = cb_value;
279 }
280
281
282
283
284
285
286
287
288