1 /*
2
3 silcargument.h
4
5 Author: Pekka Riikonen <priikone@silcnet.org>
6
7 Copyright (C) 2001 - 2007 Pekka Riikonen
8
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; version 2 of the License.
12
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
17
18 */
19
20 /****h* silccore/SILC Argument Interface
21 *
22 * DESCRIPTION
23 *
24 * Implementations of the Argument Payload and Argument List Payload, that
25 * is used to include arguments to other payload that needs arguments.
26 *
27 ***/
28
29 #ifndef SILCARGUMENT_H
30 #define SILCARGUMENT_H
31
32 /****s* silccore/SilcArgumentAPI/SilcArgumentPayload
33 *
34 * NAME
35 *
36 * typedef struct SilcArgumentPayloadStruct *SilcArgumentPayload;
37 *
38 * DESCRIPTION
39 *
40 * This context is the actual Argument Payload and is allocated
41 * by silc_argument_payload_parse and given as argument usually to
42 * all silc_argument_payload_* functions. It is freed by the
43 * silc_argument_payload_free function.
44 *
45 ***/
46 typedef struct SilcArgumentPayloadStruct *SilcArgumentPayload;
47
48 /****f* silccore/SilcArgumentAPI/silc_argument_payload_parse
49 *
50 * SYNOPSIS
51 *
52 * SilcArgumentPayload
53 * silc_argument_payload_parse(const unsigned char *payload,
54 * SilcUInt32 payload_len,
55 * SilcUInt32 argc);
56 *
57 * DESCRIPTION
58 *
59 * Parses arguments and returns them into Argument Payload structure.
60 * the `buffer' is raw Argument Payload data buffer. The `argc' is
61 * the number of arguments in the Argument Payload. The caller must
62 * know the number of the arguments. This is always known as the
63 * Argument payload is associated with other payloads which defines
64 * the number of the arguments.
65 *
66 ***/
67 SilcArgumentPayload silc_argument_payload_parse(const unsigned char *payload,
68 SilcUInt32 payload_len,
69 SilcUInt32 argc);
70
71 /****f* silccore/SilcArgumentAPI/silc_argument_payload_encode
72 *
73 * SYNOPSIS
74 *
75 * SilcBuffer silc_argument_payload_encode(SilcUInt32 argc,
76 * unsigned char **argv,
77 * SilcUInt32 *argv_lens,
78 * SilcUInt32 *argv_types);
79 *
80 * DESCRIPTION
81 *
82 * Encodes arguments in to Argument Paylods returning them to SilcBuffer.
83 * The `argv' is the array of the arguments, the `argv_lens' array of
84 * the length of the `argv' arguments and the `argv_types' array of
85 * the argument types of the `argv' arguments. The `argc' is the
86 * number of arguments.
87 *
88 ***/
89 SilcBuffer silc_argument_payload_encode(SilcUInt32 argc,
90 unsigned char **argv,
91 SilcUInt32 *argv_lens,
92 SilcUInt32 *argv_types);
93
94 /****f* silccore/SilcArgumentAPI/silc_argument_payload_encode_one
95 *
96 * SYNOPSIS
97 *
98 * SilcBuffer silc_argument_payload_encode_one(SilcBuffer args,
99 * unsigned char *arg,
100 * SilcUInt32 arg_len,
101 * SilcUInt32 arg_type);
102 *
103 * DESCRIPTION
104 *
105 * Same as silc_argument_payload_encode but encodes one argument to
106 * the buffer `args' and returns the buffer. The returned buffer
107 * may be different than the `args'. If `args' is NULL for the first
108 * argument this allocates the buffer and returns it.
109 *
110 ***/
111 SilcBuffer silc_argument_payload_encode_one(SilcBuffer args,
112 unsigned char *arg,
113 SilcUInt32 arg_len,
114 SilcUInt32 arg_type);
115
116 /****f* silccore/SilcArgumentAPI/silc_argument_payload_encode_payload
117 *
118 * SYNOPSIS
119 *
120 * SilcBuffer
121 * silc_argument_payload_encode_payload(SilcArgumentPayload payload);
122 *
123 * DESCRIPTION
124 *
125 * Same as silc_argument_payload_encode but encodes the payload from
126 * already allocated SilcArgumentPayload structure instead of raw data.
127 *
128 ***/
129 SilcBuffer silc_argument_payload_encode_payload(SilcArgumentPayload payload);
130
131 /****f* silccore/SilcArgumentAPI/silc_argument_payload_free
132 *
133 * SYNOPSIS
134 *
135 * void silc_argument_payload_free(SilcArgumentPayload payload);
136 *
137 * DESCRIPTION
138 *
139 * Frees the Argument Payload and all data in it.
140 *
141 ***/
142 void silc_argument_payload_free(SilcArgumentPayload payload);
143
144 /****f* silccore/SilcArgumentAPI/silc_argument_get_arg_num
145 *
146 * SYNOPSIS
147 *
148 * SilcUInt32 silc_argument_get_arg_num(SilcArgumentPayload payload);
149 *
150 * DESCRIPTION
151 *
152 * Returns the number of arguments in the Argument Payload.
153 *
154 ***/
155 SilcUInt32 silc_argument_get_arg_num(SilcArgumentPayload payload);
156
157 /****f* silccore/SilcArgumentAPI/silc_argument_get_first_arg
158 *
159 * SYNOPSIS
160 *
161 * unsigned char *silc_argument_get_first_arg(SilcArgumentPayload payload,
162 * SilcUInt32 *type,
163 * SilcUInt32 *ret_len);
164 *
165 * DESCRIPTION
166 *
167 * Returns the first argument in the Argument Payload. The lenght
168 * of the argument is returned to `ret_len'. The caller must not
169 * free the returned argument. Returns NULL on error.
170 *
171 ***/
172 unsigned char *silc_argument_get_first_arg(SilcArgumentPayload payload,
173 SilcUInt32 *type,
174 SilcUInt32 *ret_len);
175
176 /****f* silccore/SilcArgumentAPI/silc_argument_get_next_arg
177 *
178 * SYNOPSIS
179 *
180 * unsigned char *silc_argument_get_next_arg(SilcArgumentPayload payload,
181 * SilcUInt32 *ret_len);
182 *
183 * DESCRIPTION
184 *
185 * Returns next argument from the Argument Payload. The length of
186 * the argument is returned to `ret_len'. The caller must not free
187 * the returned argument. This returns NULL when there are no more
188 * arguments in the payload.
189 *
190 ***/
191 unsigned char *silc_argument_get_next_arg(SilcArgumentPayload payload,
192 SilcUInt32 *type,
193 SilcUInt32 *ret_len);
194
195 /****f* silccore/SilcArgumentAPI/silc_argument_get_arg_type
196 *
197 * SYNOPSIS
198 *
199 * unsigned char *silc_argument_get_arg_type(SilcArgumentPayload payload,
200 * SilcUInt32 type,
201 * SilcUInt32 *ret_len);
202 *
203 * DESCRIPTION
204 *
205 * Returns argument by type. The returned argument has type `type'
206 * in the Argument Payload. Each argument has their own type (or zero
207 * if no specific type is set). The length of the argument is returned
208 * to the `ret_len'. The caller must not free the returned argument.
209 * Returns NULL on error.
210 *
211 ***/
212 unsigned char *silc_argument_get_arg_type(SilcArgumentPayload payload,
213 SilcUInt32 type,
214 SilcUInt32 *ret_len);
215
216 /****d* silccore/SilcArgumentAPI/SilcArgumentDecodeType
217 *
218 * NAME
219 *
220 * typedef enum { ... } SilcArgumentDecodeType;
221 *
222 * DESCRIPTION
223 *
224 * Argument decode types used with silc_argument_get_decoded.
225 *
226 * SOURCE
227 */
228 typedef enum {
229 SILC_ARGUMENT_ID, /* SilcID */
230 SILC_ARGUMENT_PUBLIC_KEY, /* SilcPublicKey (always alloc) */
231 SILC_ARGUMENT_ATTRIBUTES, /* SilcDList (always alloc) */
232 SILC_ARGUMENT_UINT32, /* SilcUInt32 */
233 SILC_ARGUMENT_BOOL, /* SilcBool */
234 } SilcArgumentDecodeType;
235 /***/
236
237 /****f* silccore/SilcArgumentAPI/silc_argument_get_decoded
238 *
239 * SYNOPSIS
240 *
241 * SilcBool silc_argument_get_decoded(SilcArgumentPayload payload,
242 * SilcUInt32 type,
243 * SilcArgumentDecodeType dec_type,
244 * void *ret_arg,
245 * void *ret_arg_alloc);
246 *
247 * DESCRIPTION
248 *
249 * Returns decoded argument by type. This is a helper function to
250 * decode common argument types directly. The `type' is the argument
251 * type number in the payload, and the `dec_type' is the type the
252 * argument is decoded to. If the `ret_arg' is non-NULL then the
253 * decodec data is returned into that pointer. If the `ret_arg_alloc'
254 * is non-NULL then this function will allocate the decoded data and
255 * will return the pointer into `ret_arg_alloc'. Some types must always
256 * be allocated; see SilcArgumentDecodeType.
257 *
258 * Return TRUE if the argument was present and waa successfully decoded.
259 * FALSE if it is not present, or could not be decoded.
260 *
261 * EXAMPLE
262 *
263 * SilcID id;
264 * SilcPublicKey public_key;
265 *
266 * if (!silc_argument_get_decoded(args, 2, SILC_ARGUMENT_ID, &id, NULL))
267 * error;
268 *
269 * if (!silc_argument_get_decoded(args, 4, SILC_ARGUMENT_PUBLIC_KEY,
270 * NULL, &public_key))
271 * error;
272 *
273 ***/
274 SilcBool silc_argument_get_decoded(SilcArgumentPayload payload,
275 SilcUInt32 type,
276 SilcArgumentDecodeType dec_type,
277 void *ret_arg,
278 void **ret_arg_alloc);
279
280 /****f* silccore/SilcArgumentAPI/silc_argument_list_parse
281 *
282 * SYNOPSIS
283 *
284 * SilcArgumentPayload
285 * silc_argument_list_parse(const unsigned char *payload,
286 * SilcUInt32 payload_len);
287 *
288 * DESCRIPTION
289 *
290 * Parses argument list payload. Returns parsed SilcArgumentPayload which
291 * contains all the arguments from the list. The caller must free the
292 * returned context with silc_argument_payload_free.
293 *
294 ***/
295 SilcArgumentPayload
296 silc_argument_list_parse(const unsigned char *payload, SilcUInt32 payload_len);
297
298 /****s* silccore/SilcArgumentAPI/SilcArgumentDecodedList
299 *
300 * NAME
301 *
302 * typedef struct { ... } *SilcArgumentDecodedList;
303 *
304 * DESCRIPTION
305 *
306 * This structure is in the list returned by the function
307 * silc_argument_list_payload_parse_decoded. The caller is responsible
308 * of freeing the contents of the structure and the structure itself.
309 *
310 ***/
311 typedef struct SilcArgumentDecodedListStruct {
312 void *argument; /* Decoded argument, caller must know its type */
313 SilcUInt32 arg_type; /* Argument type number from the payload */
314 } *SilcArgumentDecodedList;
315
316 /****f* silccore/SilcArgumentAPI/silc_argument_list_parse_decoded
317 *
318 * SYNOPSIS
319 *
320 * SilcDList
321 * silc_argument_list_parse_decoded(const unsigned char *payload,
322 * SilcUInt32 payload_len,
323 * SilcArgumentDecodeType dec_type);
324 *
325 * DESCRIPTION
326 *
327 * Parses argument list payload of arguments of the type `dec_type'.
328 * The returned list includes the already decoded arguments. The caller
329 * is responsible of freeing the the contents of the list and the list
330 * itself. Each entry in the list is SilcArgumentDecodedList. The
331 * caller must free the returned list with silc_argument_list_free.
332 *
333 ***/
334 SilcDList
335 silc_argument_list_parse_decoded(const unsigned char *payload,
336 SilcUInt32 payload_len,
337 SilcArgumentDecodeType dec_type);
338
339 /****f* silccore/SilcArgumentAPI/silc_argument_list_free
340 *
341 * SYNOPSIS
342 *
343 * void
344 * silc_argument_list_free(SilcDList list, SilcArgumentDecodeType dec_type);
345 *
346 * DESCRIPTION
347 *
348 * Free's the decoded argument list and its contents.
349 *
350 ***/
351 void silc_argument_list_free(SilcDList list, SilcArgumentDecodeType dec_type);
352
353 #endif /* SILCARGUMENT_H */
354
This page was automatically generated by the LXR engine.
Free-text search provided by Glimpse