1 /****h* silccore/silcpayload.h
9 * Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
11 * Copyright (C) 2000 Pekka Riikonen
13 * This program is free software; you can redistribute it and/or modify
14 * it under the terms of the GNU General Public License as published by
15 * the Free Software Foundation; either version 2 of the License, or
16 * (at your option) any later version.
18 * This program is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 * GNU General Public License for more details.
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
44 * by silc_id_payload_parse and given as argument usually to
45 * all silc_id_payload_* functions. It is freed by the
46 * silc_id_payload_free function.
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(SilcBuffer buffer);
77 * Parses buffer and return ID payload into payload structure. The
78 * `buffer' is raw payload buffer.
81 SilcIDPayload silc_id_payload_parse(SilcBuffer buffer);
83 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_parse_data
87 * SilcIDPayload silc_id_payload_parse_data(unsigned char *data,
92 * Parses buffer and return ID payload into payload structure. The
93 * `data' and `len' are the raw payload buffer. This is equivalent
94 * to the silc_id_payload_parse function.
97 SilcIDPayload silc_id_payload_parse_data(unsigned char *data,
100 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_parse_id
104 * void *silc_id_payload_parse_id(unsigned char *data, uint32 len);
108 * Return ID directly from the raw ID Payload data buffer. The
109 * caller must free the returned ID.
112 void *silc_id_payload_parse_id(unsigned char *data, uint32 len);
114 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_encode
118 * SilcBuffer silc_id_payload_encode(void *id, SilcIdType type);
122 * Encodes ID Payload. The `id' is the ID of the type `type' to put
123 * into the payload. Returns the encoded payload buffer.
126 SilcBuffer silc_id_payload_encode(void *id, SilcIdType type);
128 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_free
132 * void silc_id_payload_free(SilcIDPayload payload);
136 * Frees the ID Payload and all data in it.
139 void silc_id_payload_free(SilcIDPayload payload);
141 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_get_type
145 * SilcIdType silc_id_payload_get_type(SilcIDPayload payload);
149 * Returns the ID type from the ID Payload. The type tells the
150 * type of the ID in the payload.
153 SilcIdType silc_id_payload_get_type(SilcIDPayload payload);
155 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_get_id
159 * void *silc_id_payload_get_id(SilcIDPayload payload);
163 * Returns the ID in the ID Payload. The caller must free the
167 void *silc_id_payload_get_id(SilcIDPayload payload);
169 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_get_data
173 * unsigned char *silc_id_payload_get_data(SilcIDPayload payload);
177 * Returns the raw ID data from the ID Payload. The data is duplicated
178 * and the caller must free it.
181 unsigned char *silc_id_payload_get_data(SilcIDPayload payload);
183 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_get_len
187 * uint32 silc_id_payload_get_len(SilcIDPayload payload);
191 * Returns the length of the ID in the ID Payload.
194 uint32 silc_id_payload_get_len(SilcIDPayload payload);
196 /****f* silccore/SilcGenericPayloadAPI/silc_argument_payload_parse
200 * SilcArgumentPayload silc_argument_payload_parse(SilcBuffer buffer,
205 * Parses arguments and returns them into Argument Payload structure.
206 * the `buffer' is raw Argument Payload data buffer. The `argc' is
207 * the number of arguments in the Argument Payload. The caller must
208 * know the number of the arguments. This is always known as the
209 * Argument payload is associated with other payloads which defines
210 * the number of the arguments.
213 SilcArgumentPayload silc_argument_payload_parse(SilcBuffer buffer,
216 /****f* silccore/SilcGenericPayloadAPI/silc_argument_payload_encode
220 * SilcBuffer silc_argument_payload_encode(uint32 argc,
221 * unsigned char **argv,
223 * uint32 *argv_types);
227 * Encodes arguments in to Argument Paylods returning them to SilcBuffer.
228 * The `argv' is the array of the arguments, the `argv_lens' array of
229 * the length of the `argv' arguments and the `argv_types' array of
230 * the argument types of the `argv' arguments. The `argc' is the
231 * number of arguments.
234 SilcBuffer silc_argument_payload_encode(uint32 argc,
235 unsigned char **argv,
239 /****f* silccore/SilcGenericPayloadAPI/silc_argument_payload_encode_payload
244 * silc_argument_payload_encode_payload(SilcArgumentPayload payload);
248 * Same as silc_argument_payload_encode but encodes the payload from
249 * already allocated SilcArgumentPayload structure instead of raw data.
252 SilcBuffer silc_argument_payload_encode_payload(SilcArgumentPayload payload);
254 /****f* silccore/SilcGenericPayloadAPI/silc_argument_payload_free
258 * void silc_argument_payload_free(SilcArgumentPayload payload);
262 * Frees the Argument Payload and all data in it.
265 void silc_argument_payload_free(SilcArgumentPayload payload);
267 /****f* silccore/SilcGenericPayloadAPI/silc_argument_get_arg_num
271 * uint32 silc_argument_get_arg_num(SilcArgumentPayload payload);
275 * Returns the number of argument in the Argument Payload.
278 uint32 silc_argument_get_arg_num(SilcArgumentPayload payload);
280 /****f* silccore/SilcGenericPayloadAPI/silc_argument_get_first_arg
284 * unsigned char *silc_argument_get_first_arg(SilcArgumentPayload payload,
289 * Returns the first argument in the Argument Payload. The lenght
290 * of the argument is returned to `ret_len'. The caller must not
291 * free the returned argument. Returns NULL on error.
294 unsigned char *silc_argument_get_first_arg(SilcArgumentPayload payload,
297 /****f* silccore/SilcGenericPayloadAPI/silc_argument_get_next_arg
301 * unsigned char *silc_argument_get_next_arg(SilcArgumentPayload payload,
306 * Returns next argument from the Argument Payload. The length of
307 * the argument is returned to `ret_len'. The caller must not free
308 * the returned argument. This returns NULL when there are no more
309 * arguments in the payload.
312 unsigned char *silc_argument_get_next_arg(SilcArgumentPayload payload,
315 /****f* silccore/SilcGenericPayloadAPI/silc_argument_get_arg_type
319 * unsigned char *silc_argument_get_arg_type(SilcArgumentPayload payload,
325 * Returns argument by type. The returned argument has type `type'
326 * in the Argument Payload. Each argument has their own type (or zero
327 * if no specific type is set). The length of the argument is returned
328 * to the `ret_len'. The caller must not free the returned argument.
329 * Returns NULL on error.
332 unsigned char *silc_argument_get_arg_type(SilcArgumentPayload payload,