5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2000 - 2001 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; either version 2 of the License, or
12 (at your option) any later version.
14 This program is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License for more details.
21 /****h* silccore/SilcGenericPayloadAPI
25 * Implementation of the generic payloads described in the protocol
26 * specification; ID Payload and Argument Payload. The ID Payload is
27 * used to represent an ID. The Argument Payload is used to include
28 * arguments to other payloads that needs arguments.
35 /****s* silccore/SilcGenericPayloadAPI/SilcIDPayload
39 * typedef struct SilcIDPayloadStruct *SilcIDPayload;
43 * This context is the actual ID Payload and is allocated by
44 * silc_id_payload_parse and given as argument usually to all
45 * silc_id_payload_* functions. It is freed by the function
46 * silc_id_payload_free.
49 typedef struct SilcIDPayloadStruct *SilcIDPayload;
51 /****s* silccore/SilcGenericPayloadAPI/SilcArgumentPayload
55 * typedef struct SilcArgumentPayloadStruct *SilcArgumentPayload;
59 * This context is the actual Argument Payload and is allocated
60 * by silc_argument_payload_parse and given as argument usually to
61 * all silc_argument_payload_* functions. It is freed by the
62 * silc_argument_payload_free function.
65 typedef struct SilcArgumentPayloadStruct *SilcArgumentPayload;
69 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_parse
73 * SilcIDPayload silc_id_payload_parse(const unsigned char *payload,
74 * uint32 payload_len);
78 * Parses buffer and return ID payload into payload structure. The
79 * `buffer' is raw payload buffer.
82 SilcIDPayload silc_id_payload_parse(const unsigned char *payload,
85 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_parse_id
89 * void *silc_id_payload_parse_id(const unsigned char *data, uint32 len);
93 * Return ID directly from the raw ID Payload data buffer. The
94 * caller must free the returned ID.
97 void *silc_id_payload_parse_id(const unsigned char *data, uint32 len);
99 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_encode
103 * SilcBuffer silc_id_payload_encode(const void *id, SilcIdType type);
107 * Encodes ID Payload. The `id' is the ID of the type `type' to put
108 * into the payload. Returns the encoded payload buffer.
111 SilcBuffer silc_id_payload_encode(const void *id, SilcIdType type);
113 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_encode_data
117 * SilcBuffer silc_id_payload_encode_data(const unsigned char *id,
118 * uin32 id_len, SilcIdType type);
122 * Encodes ID Payload. The `id' is raw ID data of the length of `id_len'
123 * of type of `type'. Returns the encoded payload buffer.
126 SilcBuffer silc_id_payload_encode_data(const unsigned char *id,
127 uint32 id_len, SilcIdType type);
129 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_free
133 * void silc_id_payload_free(SilcIDPayload payload);
137 * Frees the ID Payload and all data in it.
140 void silc_id_payload_free(SilcIDPayload payload);
142 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_get_type
146 * SilcIdType silc_id_payload_get_type(SilcIDPayload payload);
150 * Returns the ID type from the ID Payload. The type tells the
151 * type of the ID in the payload.
154 SilcIdType silc_id_payload_get_type(SilcIDPayload payload);
156 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_get_id
160 * void *silc_id_payload_get_id(SilcIDPayload payload);
164 * Returns the ID in the ID Payload. The caller must free the
168 void *silc_id_payload_get_id(SilcIDPayload payload);
170 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_get_data
174 * unsigned char *silc_id_payload_get_data(SilcIDPayload payload);
178 * Returns the raw ID data from the ID Payload. The data is duplicated
179 * and the caller must free it.
182 unsigned char *silc_id_payload_get_data(SilcIDPayload payload);
184 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_get_len
188 * uint32 silc_id_payload_get_len(SilcIDPayload payload);
192 * Returns the length of the ID in the ID Payload.
195 uint32 silc_id_payload_get_len(SilcIDPayload payload);
197 /****f* silccore/SilcGenericPayloadAPI/silc_argument_payload_parse
201 * SilcArgumentPayload
202 * silc_argument_payload_parse(const unsigned char *payload,
203 * uint32 payload_len,
208 * Parses arguments and returns them into Argument Payload structure.
209 * the `buffer' is raw Argument Payload data buffer. The `argc' is
210 * the number of arguments in the Argument Payload. The caller must
211 * know the number of the arguments. This is always known as the
212 * Argument payload is associated with other payloads which defines
213 * the number of the arguments.
216 SilcArgumentPayload silc_argument_payload_parse(const unsigned char *payload,
220 /****f* silccore/SilcGenericPayloadAPI/silc_argument_payload_encode
224 * SilcBuffer silc_argument_payload_encode(uint32 argc,
225 * unsigned char **argv,
227 * uint32 *argv_types);
231 * Encodes arguments in to Argument Paylods returning them to SilcBuffer.
232 * The `argv' is the array of the arguments, the `argv_lens' array of
233 * the length of the `argv' arguments and the `argv_types' array of
234 * the argument types of the `argv' arguments. The `argc' is the
235 * number of arguments.
238 SilcBuffer silc_argument_payload_encode(uint32 argc,
239 unsigned char **argv,
243 /****f* silccore/SilcGenericPayloadAPI/silc_argument_payload_encode_payload
248 * silc_argument_payload_encode_payload(SilcArgumentPayload payload);
252 * Same as silc_argument_payload_encode but encodes the payload from
253 * already allocated SilcArgumentPayload structure instead of raw data.
256 SilcBuffer silc_argument_payload_encode_payload(SilcArgumentPayload payload);
258 /****f* silccore/SilcGenericPayloadAPI/silc_argument_payload_free
262 * void silc_argument_payload_free(SilcArgumentPayload payload);
266 * Frees the Argument Payload and all data in it.
269 void silc_argument_payload_free(SilcArgumentPayload payload);
271 /****f* silccore/SilcGenericPayloadAPI/silc_argument_get_arg_num
275 * uint32 silc_argument_get_arg_num(SilcArgumentPayload payload);
279 * Returns the number of argument in the Argument Payload.
282 uint32 silc_argument_get_arg_num(SilcArgumentPayload payload);
284 /****f* silccore/SilcGenericPayloadAPI/silc_argument_get_first_arg
288 * unsigned char *silc_argument_get_first_arg(SilcArgumentPayload payload,
293 * Returns the first argument in the Argument Payload. The lenght
294 * of the argument is returned to `ret_len'. The caller must not
295 * free the returned argument. Returns NULL on error.
298 unsigned char *silc_argument_get_first_arg(SilcArgumentPayload payload,
301 /****f* silccore/SilcGenericPayloadAPI/silc_argument_get_next_arg
305 * unsigned char *silc_argument_get_next_arg(SilcArgumentPayload payload,
310 * Returns next argument from the Argument Payload. The length of
311 * the argument is returned to `ret_len'. The caller must not free
312 * the returned argument. This returns NULL when there are no more
313 * arguments in the payload.
316 unsigned char *silc_argument_get_next_arg(SilcArgumentPayload payload,
319 /****f* silccore/SilcGenericPayloadAPI/silc_argument_get_arg_type
323 * unsigned char *silc_argument_get_arg_type(SilcArgumentPayload payload,
329 * Returns argument by type. The returned argument has type `type'
330 * in the Argument Payload. Each argument has their own type (or zero
331 * if no specific type is set). The length of the argument is returned
332 * to the `ret_len'. The caller must not free the returned argument.
333 * Returns NULL on error.
336 unsigned char *silc_argument_get_arg_type(SilcArgumentPayload payload,