5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2001 - 2002 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_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 argument 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,
162 * SilcUInt32 *ret_len);
166 * Returns the first argument in the Argument Payload. The lenght
167 * of the argument is returned to `ret_len'. The caller must not
168 * free the returned argument. Returns NULL on error.
171 unsigned char *silc_argument_get_first_arg(SilcArgumentPayload payload,
173 SilcUInt32 *ret_len);
175 /****f* silccore/SilcArgumentAPI/silc_argument_get_next_arg
179 * unsigned char *silc_argument_get_next_arg(SilcArgumentPayload payload,
180 * SilcUInt32 *ret_len);
184 * Returns next argument from the Argument Payload. The length of
185 * the argument is returned to `ret_len'. The caller must not free
186 * the returned argument. This returns NULL when there are no more
187 * arguments in the payload.
190 unsigned char *silc_argument_get_next_arg(SilcArgumentPayload payload,
192 SilcUInt32 *ret_len);
194 /****f* silccore/SilcArgumentAPI/silc_argument_get_arg_type
198 * unsigned char *silc_argument_get_arg_type(SilcArgumentPayload payload,
200 * SilcUInt32 *ret_len);
204 * Returns argument by type. The returned argument has type `type'
205 * in the Argument Payload. Each argument has their own type (or zero
206 * if no specific type is set). The length of the argument is returned
207 * to the `ret_len'. The caller must not free the returned argument.
208 * Returns NULL on error.
211 unsigned char *silc_argument_get_arg_type(SilcArgumentPayload payload,
213 SilcUInt32 *ret_len);