1 /*
2
3 silccommand.h
4
5 Author: Pekka Riikonen <priikone@silcnet.org>
6
7 Copyright (C) 1997 - 2006 Pekka Riikonen
8
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.
12
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.
17
18 */
19
20 /****h* silccore/SILC Command Interface
21 *
22 * DESCRIPTION
23 *
24 * Implementation of the Command Payload. The Command Payload is used to
25 * send commands and also command replies usually between client and
26 * server.
27 *
28 ***/
29
30 #ifndef SILCCOMMAND_H
31 #define SILCCOMMAND_H
32
33 /****f* silccore/SilcCommandAPI/SilcCommandCb
34 *
35 * SYNOPSIS
36 *
37 * typedef void (*SilcCommandCb)(void *context, void *context2);
38 *
39 * DESCRIPTION
40 *
41 * Command function callback. The actual command function pointer.
42 * This is generic command callback that the application may choose to
43 * use with its command routines. However, none of the generic
44 * routines depend on this callback so application may freely define
45 * their own command callback if desired.
46 *
47 ***/
48 typedef void (*SilcCommandCb)(void *context, void *context2);
49
50 /****s* silccore/SilcCommandAPI/SilcCommandPayload
51 *
52 * NAME
53 *
54 * typedef struct SilcCommandPayloadStruct *SilcCommandPayload;
55 *
56 * DESCRIPTION
57 *
58 * This context is the actual Command Payload and is allocated
59 * by silc_command_payload_parse and given as argument usually to
60 * all silc_command_payload_* functions. It is freed by the
61 * silc_command_payload_free function.
62 *
63 ***/
64 typedef struct SilcCommandPayloadStruct *SilcCommandPayload;
65
66 /****d* silccore/SilcCommandAPI/SilcCommandFlags
67 *
68 * NAME
69 *
70 * typedef enum { ... } SilcCommandFlags;
71 *
72 * DESCRIPTION
73 *
74 * Command flags that set how the commands behave on different
75 * situations. These can be OR'es together to set multiple flags.
76 * The application is resoponsible of implementing the behaviour
77 * of these flags. These are here just to define generic flags.
78 * The server usually makes use of these flags.
79 *
80 * SOURCE
81 */
82 typedef enum {
83 SILC_CF_NONE = 0,
84
85 /* Command may only be used once per (about) 2 seconds. Bursts up
86 to 5 commands are allowed though. */
87 SILC_CF_LAG = (1L << 1),
88
89 /* Command may only be used once per (about) 2 seconds. No bursts
90 are allowed at all. */
91 SILC_CF_LAG_STRICT = (1L << 2),
92
93 /* Command is available for registered connections (connections
94 whose ID has been created. */
95 SILC_CF_REG = (1L << 3),
96
97 /* Command is available only for server operators */
98 SILC_CF_OPER = (1L << 4),
99
100 /* Command is available only for SILC (router) operators. If this
101 is set SILC_CF_OPER is not necessary to be set. */
102 SILC_CF_SILC_OPER = (1L << 5),
103
104 } SilcCommandFlag;
105 /***/
106
107 /****d* silccore/SilcCommandAPI/SilcCommand
108 *
109 * NAME
110 *
111 * typedef SilcUInt8 SilcCommand;
112 *
113 * DESCRIPTION
114 *
115 * The SilcCommand type definition and the commands. The commands
116 * listed here are the official SILC Commands and they have client
117 * and server counterparts.
118 *
119 * SOURCE
120 */
121 typedef SilcUInt8 SilcCommand;
122
123 /* All SILC commands. These are commands that have client and server
124 counterparts. */
125 #define SILC_COMMAND_NONE 0
126 #define SILC_COMMAND_WHOIS 1
127 #define SILC_COMMAND_WHOWAS 2
128 #define SILC_COMMAND_IDENTIFY 3
129 #define SILC_COMMAND_NICK 4
130 #define SILC_COMMAND_LIST 5
131 #define SILC_COMMAND_TOPIC 6
132 #define SILC_COMMAND_INVITE 7
133 #define SILC_COMMAND_QUIT 8
134 #define SILC_COMMAND_KILL 9
135 #define SILC_COMMAND_INFO 10
136 #define SILC_COMMAND_STATS 11
137 #define SILC_COMMAND_PING 12
138 #define SILC_COMMAND_OPER 13
139 #define SILC_COMMAND_JOIN 14
140 #define SILC_COMMAND_MOTD 15
141 #define SILC_COMMAND_UMODE 16
142 #define SILC_COMMAND_CMODE 17
143 #define SILC_COMMAND_CUMODE 18
144 #define SILC_COMMAND_KICK 19
145 #define SILC_COMMAND_BAN 20
146 #define SILC_COMMAND_DETACH 21
147 #define SILC_COMMAND_WATCH 22
148 #define SILC_COMMAND_SILCOPER 23
149 #define SILC_COMMAND_LEAVE 24
150 #define SILC_COMMAND_USERS 25
151 #define SILC_COMMAND_GETKEY 26
152 #define SILC_COMMAND_SERVICE 27
153
154 /* Private range start */
155 #define SILC_COMMAND_PRIVATE 200
156 #define SILC_COMMAND_PRIV_CONNECT 200
157 #define SILC_COMMAND_PRIV_CLOSE 201
158 #define SILC_COMMAND_PRIV_SHUTDOWN 202
159
160 /* Reserved */
161 #define SILC_COMMAND_RESERVED 255
162 /***/
163
164 /* Prototypes */
165
166 /****f* silccore/SilcCommandAPI/silc_command_payload_parse
167 *
168 * SYNOPSIS
169 *
170 * SilcCommandPayload
171 * silc_command_payload_parse(const unsigned char *payload,
172 * SilcUInt32 payload_len);
173 *
174 * DESCRIPTION
175 *
176 * Parses command payload returning new command payload structure. The
177 * `buffer' is the raw payload.
178 *
179 ***/
180 SilcCommandPayload silc_command_payload_parse(const unsigned char *payload,
181 SilcUInt32 payload_len);
182
183 /****f* silccore/SilcCommandAPI/silc_command_payload_encode
184 *
185 * SYNOPSIS
186 *
187 * SilcBuffer silc_command_payload_encode(SilcCommand cmd,
188 * SilcUInt32 argc,
189 * unsigned char **argv,
190 * SilcUInt32 *argv_lens,
191 * SilcUInt32 *argv_types,
192 * SilcUInt16 ident);
193 *
194 * DESCRIPTION
195 *
196 * Encodes Command Payload returning it to SilcBuffer.
197 *
198 ***/
199 SilcBuffer silc_command_payload_encode(SilcCommand cmd,
200 SilcUInt32 argc,
201 unsigned char **argv,
202 SilcUInt32 *argv_lens,
203 SilcUInt32 *argv_types,
204 SilcUInt16 ident);
205
206 /****f* silccore/SilcCommandAPI/silc_command_payload_encode_payload
207 *
208 * SYNOPSIS
209 *
210 * SilcBuffer
211 * silc_command_payload_encode_payload(SilcCommandPayload payload);
212 *
213 * DESCRIPTION
214 *
215 * Same as silc_command_payload_encode but encodes the buffer from
216 * SilcCommandPayload structure instead of raw data.
217 *
218 ***/
219 SilcBuffer silc_command_payload_encode_payload(SilcCommandPayload payload);
220
221 /****f* silccore/SilcCommandAPI/silc_command_payload_encode_va
222 *
223 * SYNOPSIS
224 *
225 * SilcBuffer silc_command_payload_encode_va(SilcCommand cmd,
226 * SilcUInt16 ident,
227 * SilcUInt32 argc, ...);
228 *
229 * DESCRIPTION
230 *
231 * Encodes Command payload with variable argument list. The arguments
232 * must be: SilcUInt32, unsigned char *, unsigned int, ... One
233 * {SilcUInt32, unsigned char * and unsigned int} forms one argument,
234 * thus `argc' in case when sending one {SilcUInt32, unsigned char *
235 * and SilcUInt32} equals one (1) and when sending two of those it
236 * equals two (2), and so on. This has to be preserved or bad things
237 * will happen. The variable arguments is: {type, data, data_len}.
238 *
239 ***/
240 SilcBuffer silc_command_payload_encode_va(SilcCommand cmd,
241 SilcUInt16 ident,
242 SilcUInt32 argc, ...);
243
244 /****f* silccore/SilcCommandAPI/silc_command_payload_encode_vap
245 *
246 * SYNOPSIS
247 *
248 * SilcBuffer silc_command_payload_encode_vap(SilcCommand cmd,
249 * SilcUInt16 ident,
250 * SilcUInt32 argc, va_list ap);
251 *
252 * DESCRIPTION
253 *
254 * This is equivalent to the silc_command_payload_encode_va except
255 * takes the va_list as argument.
256 *
257 ***/
258 SilcBuffer silc_command_payload_encode_vap(SilcCommand cmd,
259 SilcUInt16 ident,
260 SilcUInt32 argc, va_list ap);
261
262 /****f* silccore/SilcCommandAPI/silc_command_reply_payload_encode_va
263 *
264 * SYNOPSIS
265 *
266 * SilcBuffer
267 * silc_command_reply_payload_encode_va(SilcCommand cmd,
268 * SilcStatus status,
269 * SilcStatus error,
270 * SilcUInt16 ident,
271 * SilcUInt32 argc, ...);
272 *
273 * DESCRIPTION
274 *
275 * Same as silc_command_payload_encode_va except that this is used to
276 * encode strictly command reply packets. The `argc' must not count
277 * `status' and `error' as arguments. The `status' includes the
278 * command reply status. If single reply will be sent then it includes
279 * SILC_STATUS_OK if error did not occur. It includes an error value
280 * if error did occur. In this case `error' field is ignored. If
281 * there will be multiple successful command replies then the `status'
282 * includes a list value and `error' is ignored. If there will
283 * multiple error replies the `status' includes a list value, and
284 * the `error' includes an error value. Thus, the `error' value is
285 * specified only if there will be list of errors.
286 *
287 * NOTES
288 *
289 * Protocol defines that it is possible to send both list of successful
290 * and list of error replies at the same time, as long as the error
291 * replies are sent after the successful replies.
292 *
293 ***/
294 SilcBuffer
295 silc_command_reply_payload_encode_va(SilcCommand cmd,
296 SilcStatus status,
297 SilcStatus error,
298 SilcUInt16 ident,
299 SilcUInt32 argc, ...);
300
301 /****f* silccore/SilcCommandAPI/silc_command_reply_payload_encode_vap
302 *
303 * SYNOPSIS
304 *
305 * SilcBuffer
306 * silc_command_reply_payload_encode_vap(SilcCommand cmd,
307 * SilcStatus status,
308 * SilcStatus error,
309 * SilcUInt16 ident, SilcUInt32 argc,
310 * va_list ap);
311 *
312 * DESCRIPTION
313 *
314 * This is equivalent to the silc_command_reply_payload_encode_va except
315 * takes the va_list as argument.
316 *
317 ***/
318 SilcBuffer
319 silc_command_reply_payload_encode_vap(SilcCommand cmd,
320 SilcStatus status,
321 SilcStatus error,
322 SilcUInt16 ident, SilcUInt32 argc,
323 va_list ap);
324
325 /****f* silccore/SilcCommandAPI/silc_command_free
326 *
327 * SYNOPSIS
328 *
329 * void silc_command_payload_free(SilcCommandPayload payload);
330 *
331 * DESCRIPTION
332 *
333 * Frees the Command Payload and all data in it.
334 *
335 ***/
336 void silc_command_payload_free(SilcCommandPayload payload);
337
338 /****f* silccore/SilcCommandAPI/silc_command_get
339 *
340 * SYNOPSIS
341 *
342 * SilcCommand silc_command_get(SilcCommandPayload payload);
343 *
344 * DESCRIPTION
345 *
346 * Return the command from the payload.
347 *
348 ***/
349 SilcCommand silc_command_get(SilcCommandPayload payload);
350
351 /****f* silccore/SilcCommandAPI/silc_command_get_args
352 *
353 * SYNOPSIS
354 *
355 * SilcArgumentPayload silc_command_get_args(SilcCommandPayload payload);
356 *
357 * DESCRIPTION
358 *
359 * Return the Arguments Payload containing the arguments from the
360 * Command Payload. The caller must not free it.
361 *
362 ***/
363 SilcArgumentPayload silc_command_get_args(SilcCommandPayload payload);
364
365 /****f* silccore/SilcCommandAPI/silc_command_get_ident
366 *
367 * SYNOPSIS
368 *
369 * SilcUInt16 silc_command_get_ident(SilcCommandPayload payload);
370 *
371 * DESCRIPTION
372 *
373 * Return the command identifier from the payload. The identifier can
374 * be used to identify which command reply belongs to which command.
375 * The client sets the identifier to the payload and server must return
376 * the same identifier in the command reply.
377 *
378 ***/
379 SilcUInt16 silc_command_get_ident(SilcCommandPayload payload);
380
381 /****f* silccore/SilcCommandAPI/silc_command_get_status
382 *
383 * SYNOPSIS
384 *
385 * SilcBool silc_command_get_status(SilcCommandPayload payload,
386 * SilcStatus *status,
387 * SilcStatus *error);
388 *
389 * DESCRIPTION
390 *
391 * This function returns the command reply status into `status' and
392 * error status, if error occurred into the `error'. The function
393 * returns TRUE if command reply status is not error, and FALSE if
394 * error occurred. In this case the `error' will include the actual
395 * error status. The `status' can be in this case some list value
396 * which indicates that there will be list of errors.
397 *
398 ***/
399 SilcBool silc_command_get_status(SilcCommandPayload payload,
400 SilcStatus *status,
401 SilcStatus *error);
402
403 /****f* silccore/SilcCommandAPI/silc_command_set_ident
404 *
405 * SYNOPSIS
406 *
407 * void silc_command_set_ident(SilcCommandPayload payload,
408 * SilcUInt16 ident);
409 *
410 * DESCRIPTION
411 *
412 * Function to set identifier to already allocated Command Payload. Command
413 * payloads are frequentlly resent in SILC and thusly this makes it easy
414 * to set the identifier without encoding new Command Payload.
415 *
416 ***/
417 void silc_command_set_ident(SilcCommandPayload payload, SilcUInt16 ident);
418
419 /****f* silccore/SilcCommandAPI/silc_command_set_command
420 *
421 * SYNOPSIS
422 *
423 * void silc_command_set_command(SilcCommandPayload payload,
424 * SilcCommand command);
425 *
426 * DESCRIPTION
427 *
428 * Function to set the command to already allocated Command Payload. This
429 * makes it easy to change the command in the payload without encoding new
430 * Command Payload.
431 *
432 ***/
433 void silc_command_set_command(SilcCommandPayload payload, SilcCommand command);
434
435 #endif
436
This page was automatically generated by the LXR engine.
Free-text search provided by Glimpse