5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 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; 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 * Implementation of the Argument Payload, that is used to include
25 * argument to other payload that needs arguments.
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_payload
99 * silc_argument_payload_encode_payload(SilcArgumentPayload payload);
103 * Same as silc_argument_payload_encode but encodes the payload from
104 * already allocated SilcArgumentPayload structure instead of raw data.
107 SilcBuffer silc_argument_payload_encode_payload(SilcArgumentPayload payload);
109 /****f* silccore/SilcArgumentAPI/silc_argument_payload_free
113 * void silc_argument_payload_free(SilcArgumentPayload payload);
117 * Frees the Argument Payload and all data in it.
120 void silc_argument_payload_free(SilcArgumentPayload payload);
122 /****f* silccore/SilcArgumentAPI/silc_argument_get_arg_num
126 * SilcUInt32 silc_argument_get_arg_num(SilcArgumentPayload payload);
130 * Returns the number of argument in the Argument Payload.
133 SilcUInt32 silc_argument_get_arg_num(SilcArgumentPayload payload);
135 /****f* silccore/SilcArgumentAPI/silc_argument_get_first_arg
139 * unsigned char *silc_argument_get_first_arg(SilcArgumentPayload payload,
140 * SilcUInt32 *ret_len);
144 * Returns the first argument in the Argument Payload. The lenght
145 * of the argument is returned to `ret_len'. The caller must not
146 * free the returned argument. Returns NULL on error.
149 unsigned char *silc_argument_get_first_arg(SilcArgumentPayload payload,
150 SilcUInt32 *ret_len);
152 /****f* silccore/SilcArgumentAPI/silc_argument_get_next_arg
156 * unsigned char *silc_argument_get_next_arg(SilcArgumentPayload payload,
157 * SilcUInt32 *ret_len);
161 * Returns next argument from the Argument Payload. The length of
162 * the argument is returned to `ret_len'. The caller must not free
163 * the returned argument. This returns NULL when there are no more
164 * arguments in the payload.
167 unsigned char *silc_argument_get_next_arg(SilcArgumentPayload payload,
168 SilcUInt32 *ret_len);
170 /****f* silccore/SilcArgumentAPI/silc_argument_get_arg_type
174 * unsigned char *silc_argument_get_arg_type(SilcArgumentPayload payload,
176 * SilcUInt32 *ret_len);
180 * Returns argument by type. The returned argument has type `type'
181 * in the Argument Payload. Each argument has their own type (or zero
182 * if no specific type is set). The length of the argument is returned
183 * to the `ret_len'. The caller must not free the returned argument.
184 * Returns NULL on error.
187 unsigned char *silc_argument_get_arg_type(SilcArgumentPayload payload,
189 SilcUInt32 *ret_len);