Added more doc entries and prepared for 0.2.3
[gpgme.git] / gpgme / recipient.c
1 /* recipient.c - mainatin recipient sets
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 "rungpg.h"
30
31 /**
32  * gpgme_recipients_new:
33  * @r_rset: Returns the new object.
34  * 
35  * Create a new uninitialized Reciepient set Object.
36  * 
37  * Return value: 0 on success or an error code.
38  **/
39 GpgmeError
40 gpgme_recipients_new (GpgmeRecipients *r_rset)
41 {
42     GpgmeRecipients rset;
43
44     rset = xtrycalloc ( 1, sizeof *rset  );
45     if (!rset)
46         return mk_error (Out_Of_Core);
47     *r_rset = rset;
48     return 0;
49 }
50
51 /**
52  * gpgme_recipients_release:
53  * @rset: Recipient Set object
54  * 
55  * Free the given object.
56  **/
57 void
58 gpgme_recipients_release ( GpgmeRecipients rset )
59 {
60     if (rset) {
61         struct user_id_s *u, *u2;
62
63         for (u = rset->list; u; u = u2) {
64             u2 = u->next;
65             xfree(u);
66         }
67     }
68     xfree ( rset );
69 }
70
71
72 /**
73  * gpgme_recipients_add_name:
74  * @rset: Recipient Set object 
75  * @name: user name or keyID
76  * 
77  * Add a name to the recipient Set.
78  * 
79  * Return value: 0 on success or an error code
80  **/
81 GpgmeError
82 gpgme_recipients_add_name (GpgmeRecipients rset, const char *name )
83 {
84     return gpgme_recipients_add_name_with_validity (
85         rset, name, GPGME_VALIDITY_UNKNOWN
86         );
87 }
88
89 /**
90  * gpgme_recipients_add_name_with_validity:
91  * @rset: Recipient Set object
92  * @name: user name or keyID
93  * @val: Validity value 
94  * 
95  * Same as gpgme_recipients_add_name() but with explictly given key
96  * validity.  Use one of the constants 
97  * %GPGME_VALIDITY_UNKNOWN, %GPGME_VALIDITY_UNDEFINED,
98  * %GPGME_VALIDITY_NEVER, %GPGME_VALIDITY_MARGINAL,
99  * %GPGME_VALIDITY_FULL, %GPGME_VALIDITY_ULTIMATE5
100  * for the validity.  %GPGME_VALIDITY_UNKNOWN is implicitly used by
101  * gpgme_recipients_add_name().
102  *
103  * Return value: o on success or an error value.
104  **/
105 GpgmeError
106 gpgme_recipients_add_name_with_validity (GpgmeRecipients rset,
107                                          const char *name,
108                                          GpgmeValidity val )
109 {
110     struct user_id_s *r;
111
112     if (!name || !rset )
113         return mk_error (Invalid_Value);
114     r = xtrymalloc ( sizeof *r + strlen (name) );
115     if (!r)
116         return mk_error (Out_Of_Core);
117     r->validity = val;
118     r->name_part = "";
119     r->email_part = "";
120     r->comment_part = "";
121     strcpy (r->name, name );
122     r->next = rset->list;
123     rset->list = r;
124     return 0;
125 }
126
127
128
129 /**
130  * gpgme_recipients_count:
131  * @rset: Recipient Set object
132  * 
133  * Return value: The number of recipients in the set.
134  **/
135 unsigned int 
136 gpgme_recipients_count ( const GpgmeRecipients rset )
137 {
138     struct user_id_s *r;
139     unsigned int count = 0;
140     
141     if ( rset ) {
142         for (r=rset->list ; r; r = r->next )
143             count++;
144     }
145     return count;
146 }
147
148
149
150 /**
151  * gpgme_recipients_enum_open:
152  * @rset: Recipient Set object
153  * @ctx: Enumerator
154  * 
155  * Start an enumeration on the Recipient Set object.  The caller must pass 
156  * the address of a void pointer which is used as the enumerator object.
157  * 
158  * Return value: 0 on success or an error code.
159  *
160  * See also: gpgme_recipients_enum_read(), gpgme_recipients_enum_close().
161  **/
162 GpgmeError
163 gpgme_recipients_enum_open ( const GpgmeRecipients rset, void **ctx )
164 {
165     if (!rset || !ctx)
166         return mk_error (Invalid_Value);
167
168     *ctx = rset->list;
169     return 0;
170 }
171
172 /**
173  * gpgme_recipients_enum_read:
174  * @rset: Recipient Set object
175  * @ctx: Enumerator 
176  * 
177  * Return the name of the next user name from the given recipient
178  * set. This name is valid as along as the @rset is valid and until
179  * the next call to this function.
180  * 
181  * Return value: name or NULL for no more names.
182  *
183  * See also: gpgme_recipients_enum_read(), gpgme_recipients_enum_close().
184  **/
185 const char *
186 gpgme_recipients_enum_read ( const GpgmeRecipients rset, void **ctx )
187 {
188     struct user_id_s *r;
189
190     if (!rset || !ctx)
191         return NULL; /* oops */
192     
193     r = *ctx;
194     if ( r ) {
195         const char *s = r->name;
196         r = r->next;
197         *ctx = r;
198         return s;
199     }
200
201     return NULL;
202 }
203
204 /**
205  * gpgme_recipients_enum_close:
206  * @rset: Recipient Set object
207  * @ctx: Enumerator
208  * 
209  * Release the enumerator @rset for this object.
210  * 
211  * Return value: 0 on success or %GPGME_Invalid_Value;
212  *
213  * See also: gpgme_recipients_enum_read(), gpgme_recipients_enum_close().
214  **/
215 GpgmeError
216 gpgme_recipients_enum_close ( const GpgmeRecipients rset, void **ctx )
217 {
218     if (!rset || !ctx)
219         return mk_error (Invalid_Value);
220     *ctx = NULL;
221     return 0;
222 }
223
224
225 void
226 _gpgme_append_gpg_args_from_recipients (
227     const GpgmeRecipients rset,
228     GpgObject gpg )
229 {
230     struct user_id_s *r;
231
232     assert (rset);
233     for (r=rset->list ; r; r = r->next ) {
234         _gpgme_gpg_add_arg ( gpg, "-r" );
235         _gpgme_gpg_add_arg ( gpg, r->name );
236     }    
237 }
238
239 int
240 _gpgme_recipients_all_valid ( const GpgmeRecipients rset )
241 {
242     struct user_id_s *r;
243
244     assert (rset);
245     for (r=rset->list ; r; r = r->next ) {
246         if (r->validity != GPGME_VALIDITY_FULL
247             && r->validity != GPGME_VALIDITY_ULTIMATE )
248             return 0; /*no*/
249     }
250     return 1; /*yes*/
251 }
252
253
254