5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2001 - 2007 Pekka Riikonen
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.
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.
20 /****h* silccore/SILC Argument Interface
24 * Implementations of the Argument Payload and Argument List Payload, that
25 * is used to include arguments to other payload that needs arguments.
29 #ifndef SILCARGUMENT_H
30 #define SILCARGUMENT_H
32 /****s* silccore/SilcArgumentAPI/SilcArgumentPayload
36 * typedef struct SilcArgumentPayloadStruct *SilcArgumentPayload;
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.
46 typedef struct SilcArgumentPayloadStruct *SilcArgumentPayload;
48 /****f* silccore/SilcArgumentAPI/silc_argument_payload_parse
53 * silc_argument_payload_parse(const unsigned char *payload,
54 * SilcUInt32 payload_len,
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.
67 SilcArgumentPayload silc_argument_payload_parse(const unsigned char *payload,
68 SilcUInt32 payload_len,
71 /****f* silccore/SilcArgumentAPI/silc_argument_payload_encode
75 * SilcBuffer silc_argument_payload_encode(SilcUInt32 argc,
76 * unsigned char **argv,
77 * SilcUInt32 *argv_lens,
78 * SilcUInt32 *argv_types);
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.
89 SilcBuffer silc_argument_payload_encode(SilcUInt32 argc,
91 SilcUInt32 *argv_lens,
92 SilcUInt32 *argv_types);
94 /****f* silccore/SilcArgumentAPI/silc_argument_payload_encode_one
98 * SilcBuffer silc_argument_payload_encode_one(SilcBuffer args,
100 * SilcUInt32 arg_len,
101 * SilcUInt32 arg_type);
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.
111 SilcBuffer silc_argument_payload_encode_one(SilcBuffer args,
114 SilcUInt32 arg_type);
116 /****f* silccore/SilcArgumentAPI/silc_argument_payload_encode_payload
121 * silc_argument_payload_encode_payload(SilcArgumentPayload payload);
125 * Same as silc_argument_payload_encode but encodes the payload from
126 * already allocated SilcArgumentPayload structure instead of raw data.
129 SilcBuffer silc_argument_payload_encode_payload(SilcArgumentPayload payload);
131 /****f* silccore/SilcArgumentAPI/silc_argument_payload_free
135 * void silc_argument_payload_free(SilcArgumentPayload payload);
139 * Frees the Argument Payload and all data in it.
142 void silc_argument_payload_free(SilcArgumentPayload payload);
144 /****f* silccore/SilcArgumentAPI/silc_argument_get_arg_num
148 * SilcUInt32 silc_argument_get_arg_num(SilcArgumentPayload payload);
152 * Returns the number of arguments in the Argument Payload.
155 SilcUInt32 silc_argument_get_arg_num(SilcArgumentPayload payload);
157 /****f* silccore/SilcArgumentAPI/silc_argument_get_first_arg
161 * unsigned char *silc_argument_get_first_arg(SilcArgumentPayload payload,
163 * SilcUInt32 *ret_len);
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.
172 unsigned char *silc_argument_get_first_arg(SilcArgumentPayload payload,
174 SilcUInt32 *ret_len);
176 /****f* silccore/SilcArgumentAPI/silc_argument_get_next_arg
180 * unsigned char *silc_argument_get_next_arg(SilcArgumentPayload payload,
181 * SilcUInt32 *ret_len);
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.
191 unsigned char *silc_argument_get_next_arg(SilcArgumentPayload payload,
193 SilcUInt32 *ret_len);
195 /****f* silccore/SilcArgumentAPI/silc_argument_get_arg_type
199 * unsigned char *silc_argument_get_arg_type(SilcArgumentPayload payload,
201 * SilcUInt32 *ret_len);
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.
212 unsigned char *silc_argument_get_arg_type(SilcArgumentPayload payload,
214 SilcUInt32 *ret_len);
216 /****d* silccore/SilcArgumentAPI/SilcArgumentDecodeType
220 * typedef enum { ... } SilcArgumentDecodeType;
224 * Argument decode types used with silc_argument_get_decoded.
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;
237 /****f* silccore/SilcArgumentAPI/silc_argument_get_decoded
241 * SilcBool silc_argument_get_decoded(SilcArgumentPayload payload,
243 * SilcArgumentDecodeType dec_type,
245 * void *ret_arg_alloc);
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.
258 * Return TRUE if the argument was present and waa successfully decoded.
259 * FALSE if it is not present, or could not be decoded.
264 * SilcPublicKey public_key;
266 * if (!silc_argument_get_decoded(args, 2, SILC_ARGUMENT_ID, &id, NULL))
269 * if (!silc_argument_get_decoded(args, 4, SILC_ARGUMENT_PUBLIC_KEY,
270 * NULL, &public_key))
274 SilcBool silc_argument_get_decoded(SilcArgumentPayload payload,
276 SilcArgumentDecodeType dec_type,
278 void **ret_arg_alloc);
280 /****f* silccore/SilcArgumentAPI/silc_argument_list_parse
284 * SilcArgumentPayload
285 * silc_argument_list_parse(const unsigned char *payload,
286 * SilcUInt32 payload_len);
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.
296 silc_argument_list_parse(const unsigned char *payload, SilcUInt32 payload_len);
298 /****s* silccore/SilcArgumentAPI/SilcArgumentDecodedList
302 * typedef struct { ... } *SilcArgumentDecodedList;
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.
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;
316 /****f* silccore/SilcArgumentAPI/silc_argument_list_parse_decoded
321 * silc_argument_list_parse_decoded(const unsigned char *payload,
322 * SilcUInt32 payload_len,
323 * SilcArgumentDecodeType dec_type);
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.
335 silc_argument_list_parse_decoded(const unsigned char *payload,
336 SilcUInt32 payload_len,
337 SilcArgumentDecodeType dec_type);
339 /****f* silccore/SilcArgumentAPI/silc_argument_list_free
344 * silc_argument_list_free(SilcDList list, SilcArgumentDecodeType dec_type);
348 * Free's the decoded argument list and its contents.
351 void silc_argument_list_free(SilcDList list, SilcArgumentDecodeType dec_type);
353 #endif /* SILCARGUMENT_H */