5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 1997 - 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/SILC Command Interface
25 * Implementation of the Command Payload. The Command Payload is used to
26 * send commands and also command replies usually between client and
34 /****f* silccore/SilcCommandAPI/SilcCommandCb
38 * typedef void (*SilcCommandCb)(void *context, void *context2);
42 * Command function callback. The actual command function pointer.
43 * This is generic command callback that the application may choose to
44 * use with its command routines. However, none of the generic
45 * routines depend on this callback so application may freely define
46 * their own command callback if desired.
49 typedef void (*SilcCommandCb)(void *context, void *context2);
51 /****s* silccore/SilcCommandAPI/SilcCommandPayload
55 * typedef struct SilcCommandPayloadStruct *SilcCommandPayload;
59 * This context is the actual Command Payload and is allocated
60 * by silc_command_payload_parse and given as argument usually to
61 * all silc_command_payload_* functions. It is freed by the
62 * silc_command_payload_free function.
65 typedef struct SilcCommandPayloadStruct *SilcCommandPayload;
67 /****d* silccore/SilcCommandAPI/SilcCommandFlags
71 * typedef enum { ... } SilcCommandFlags;
75 * Command flags that set how the commands behave on different
76 * situations. These can be OR'es together to set multiple flags.
77 * The application is resoponsible of implementing the behaviour
78 * of these flags. These are here just to define generic flags.
79 * The server usually makes use of these flags.
86 /* Command may only be used once per (about) 2 seconds. Bursts up
87 to 5 commands are allowed though. */
88 SILC_CF_LAG = (1L << 1),
90 /* Command may only be used once per (about) 2 seconds. No bursts
91 are allowed at all. */
92 SILC_CF_LAG_STRICT = (1L << 2),
94 /* Command is available for registered connections (connections
95 whose ID has been created. */
96 SILC_CF_REG = (1L << 3),
98 /* Command is available only for server operators */
99 SILC_CF_OPER = (1L << 4),
101 /* Command is available only for SILC (router) operators. If this
102 is set SILC_CF_OPER is not necessary to be set. */
103 SILC_CF_SILC_OPER = (1L << 5),
108 /****d* silccore/SilcCommandAPI/SilcCommand
112 * typedef unsigned char SilcCommand;
116 * The SilcCommand type definition and the commands. The commands
117 * listed here are the official SILC Commands and they have client
118 * and server counterparts.
122 typedef unsigned char SilcCommand;
124 /* All SILC commands. These are commands that have client and server
126 #define SILC_COMMAND_NONE 0
127 #define SILC_COMMAND_WHOIS 1
128 #define SILC_COMMAND_WHOWAS 2
129 #define SILC_COMMAND_IDENTIFY 3
130 #define SILC_COMMAND_NICK 4
131 #define SILC_COMMAND_LIST 5
132 #define SILC_COMMAND_TOPIC 6
133 #define SILC_COMMAND_INVITE 7
134 #define SILC_COMMAND_QUIT 8
135 #define SILC_COMMAND_KILL 9
136 #define SILC_COMMAND_INFO 10
137 #define SILC_COMMAND_STATS 11
138 #define SILC_COMMAND_PING 12
139 #define SILC_COMMAND_OPER 13
140 #define SILC_COMMAND_JOIN 14
141 #define SILC_COMMAND_MOTD 15
142 #define SILC_COMMAND_UMODE 16
143 #define SILC_COMMAND_CMODE 17
144 #define SILC_COMMAND_CUMODE 18
145 #define SILC_COMMAND_KICK 19
146 #define SILC_COMMAND_BAN 20
147 #define SILC_COMMAND_DETACH 21
148 #define SILC_COMMAND_SILCOPER 23
149 #define SILC_COMMAND_LEAVE 24
150 #define SILC_COMMAND_USERS 25
151 #define SILC_COMMAND_GETKEY 26
153 /* Private range start */
154 #define SILC_COMMAND_PRIV_CONNECT 200
155 #define SILC_COMMAND_PRIV_CLOSE 201
156 #define SILC_COMMAND_PRIV_SHUTDOWN 202
159 #define SILC_COMMAND_RESERVED 255
162 /****d* silccore/SilcCommandAPI/SilcCommandStatus
166 * typedef SilcUInt8 SilcCommandStatus;
170 * The SilcCommandStatus type definition and the status defines.
171 * The server returns a status in each Command Payload indicating
172 * the status of the command.
176 typedef SilcUInt8 SilcCommandStatus;
178 /* Command Status messages */
179 #define SILC_STATUS_OK 0
180 #define SILC_STATUS_LIST_START 1
181 #define SILC_STATUS_LIST_ITEM 2
182 #define SILC_STATUS_LIST_END 3
183 #define SILC_STATUS_ERR_NO_SUCH_NICK 10
184 #define SILC_STATUS_ERR_NO_SUCH_CHANNEL 11
185 #define SILC_STATUS_ERR_NO_SUCH_SERVER 12
186 #define SILC_STATUS_ERR_TOO_MANY_TARGETS 13
187 #define SILC_STATUS_ERR_NO_RECIPIENT 14
188 #define SILC_STATUS_ERR_UNKNOWN_COMMAND 15
189 #define SILC_STATUS_ERR_WILDCARDS 16
190 #define SILC_STATUS_ERR_NO_CLIENT_ID 17
191 #define SILC_STATUS_ERR_NO_CHANNEL_ID 18
192 #define SILC_STATUS_ERR_NO_SERVER_ID 19
193 #define SILC_STATUS_ERR_BAD_CLIENT_ID 20
194 #define SILC_STATUS_ERR_BAD_CHANNEL_ID 21
195 #define SILC_STATUS_ERR_NO_SUCH_CLIENT_ID 22
196 #define SILC_STATUS_ERR_NO_SUCH_CHANNEL_ID 23
197 #define SILC_STATUS_ERR_NICKNAME_IN_USE 24
198 #define SILC_STATUS_ERR_NOT_ON_CHANNEL 25
199 #define SILC_STATUS_ERR_USER_NOT_ON_CHANNEL 26
200 #define SILC_STATUS_ERR_USER_ON_CHANNEL 27
201 #define SILC_STATUS_ERR_NOT_REGISTERED 28
202 #define SILC_STATUS_ERR_NOT_ENOUGH_PARAMS 29
203 #define SILC_STATUS_ERR_TOO_MANY_PARAMS 30
204 #define SILC_STATUS_ERR_PERM_DENIED 31
205 #define SILC_STATUS_ERR_BANNED_FROM_SERVER 32
206 #define SILC_STATUS_ERR_BAD_PASSWORD 33
207 #define SILC_STATUS_ERR_CHANNEL_IS_FULL 34
208 #define SILC_STATUS_ERR_NOT_INVITED 35
209 #define SILC_STATUS_ERR_BANNED_FROM_CHANNEL 36
210 #define SILC_STATUS_ERR_UNKNOWN_MODE 37
211 #define SILC_STATUS_ERR_NOT_YOU 38
212 #define SILC_STATUS_ERR_NO_CHANNEL_PRIV 39
213 #define SILC_STATUS_ERR_NO_CHANNEL_FOPRIV 40
214 #define SILC_STATUS_ERR_NO_SERVER_PRIV 41
215 #define SILC_STATUS_ERR_NO_ROUTER_PRIV 42
216 #define SILC_STATUS_ERR_BAD_NICKNAME 43
217 #define SILC_STATUS_ERR_BAD_CHANNEL 44
218 #define SILC_STATUS_ERR_AUTH_FAILED 45
219 #define SILC_STATUS_ERR_UNKNOWN_ALGORITHM 46
220 #define SILC_STATUS_ERR_NO_SUCH_SERVER_ID 47
225 /****f* silccore/SilcCommandAPI/silc_command_payload_parse
230 * silc_command_payload_parse(const unsigned char *payload,
231 * SilcUInt32 payload_len);
235 * Parses command payload returning new command payload structure. The
236 * `buffer' is the raw payload.
239 SilcCommandPayload silc_command_payload_parse(const unsigned char *payload,
240 SilcUInt32 payload_len);
242 /****f* silccore/SilcCommandAPI/silc_command_payload_encode
246 * SilcBuffer silc_command_payload_encode(SilcCommand cmd,
248 * unsigned char **argv,
249 * SilcUInt32 *argv_lens,
250 * SilcUInt32 *argv_types,
255 * Encodes Command Payload returning it to SilcBuffer.
258 SilcBuffer silc_command_payload_encode(SilcCommand cmd,
260 unsigned char **argv,
261 SilcUInt32 *argv_lens,
262 SilcUInt32 *argv_types,
265 /****f* silccore/SilcCommandAPI/silc_command_payload_encode_payload
270 * silc_command_payload_encode_payload(SilcCommandPayload payload);
274 * Same as silc_command_payload_encode but encodes the buffer from
275 * SilcCommandPayload structure instead of raw data.
278 SilcBuffer silc_command_payload_encode_payload(SilcCommandPayload payload);
280 /****f* silccore/SilcCommandAPI/silc_command_payload_encode_va
284 * SilcBuffer silc_command_payload_encode_va(SilcCommand cmd,
286 * SilcUInt32 argc, ...);
290 * Encodes Command payload with variable argument list. The arguments
291 * must be: SilcUInt32, unsigned char *, unsigned int, ... One
292 * {SilcUInt32, unsigned char * and unsigned int} forms one argument,
293 * thus `argc' in case when sending one {SilcUInt32, unsigned char *
294 * and SilcUInt32} equals one (1) and when sending two of those it
295 * equals two (2), and so on. This has to be preserved or bad things
296 * will happen. The variable arguments is: {type, data, data_len}.
299 SilcBuffer silc_command_payload_encode_va(SilcCommand cmd,
301 SilcUInt32 argc, ...);
303 /****f* silccore/SilcCommandAPI/silc_command_payload_encode_vap
307 * SilcBuffer silc_command_payload_encode_vap(SilcCommand cmd,
309 * SilcUInt32 argc, va_list ap);
313 * This is equivalent to the silc_command_payload_encode_va except
314 * takes the va_list as argument.
317 SilcBuffer silc_command_payload_encode_vap(SilcCommand cmd,
319 SilcUInt32 argc, va_list ap);
321 /****f* silccore/SilcCommandAPI/silc_command_reply_payload_encode_va
326 * silc_command_reply_payload_encode_va(SilcCommand cmd,
327 * SilcCommandStatus status,
328 * SilcCommandStatus error,
330 * SilcUInt32 argc, ...);
334 * Same as silc_command_payload_encode_va except that this is used to
335 * encode strictly command reply packets. The `argc' must not count
336 * `status' and `error' as arguments. The `status' includes the
337 * command reply status. If single reply will be sent then it includes
338 * SILC_STATUS_OK if error did not occur. It includes an error value
339 * if error did occur. In this case `error' field is ignored. If
340 * there will be multiple successful command replies then the `status'
341 * includes a list value and `error' is ignored. If there will
342 * multiple error replies the `status' includes a list value, and
343 * the `error' includes an error value. Thus, the `error' value is
344 * specified only if there will be list of errors.
348 * Protocol defines that it is possible to send both list of successful
349 * and list of error replies at the same time, as long as the error
350 * replies are sent after the successful replies.
354 silc_command_reply_payload_encode_va(SilcCommand cmd,
355 SilcCommandStatus status,
356 SilcCommandStatus error,
358 SilcUInt32 argc, ...);
360 /****f* silccore/SilcCommandAPI/silc_command_reply_payload_encode_vap
365 * silc_command_reply_payload_encode_vap(SilcCommand cmd,
366 * SilcCommandStatus status,
367 * SilcCommandStatus error,
368 * SilcUInt16 ident, SilcUInt32 argc,
373 * This is equivalent to the silc_command_reply_payload_encode_va except
374 * takes the va_list as argument.
378 silc_command_reply_payload_encode_vap(SilcCommand cmd,
379 SilcCommandStatus status,
380 SilcCommandStatus error,
381 SilcUInt16 ident, SilcUInt32 argc,
384 /****f* silccore/SilcCommandAPI/silc_command_free
388 * void silc_command_payload_free(SilcCommandPayload payload);
392 * Frees the Command Payload and all data in it.
395 void silc_command_payload_free(SilcCommandPayload payload);
397 /****f* silccore/SilcCommandAPI/silc_command_get
401 * SilcCommand silc_command_get(SilcCommandPayload payload);
405 * Return the command from the payload.
408 SilcCommand silc_command_get(SilcCommandPayload payload);
410 /****f* silccore/SilcCommandAPI/silc_command_get_args
414 * SilcArgumentPayload silc_command_get_args(SilcCommandPayload payload);
418 * Return the Arguments Payload containing the arguments from the
419 * Command Payload. The caller must not free it.
422 SilcArgumentPayload silc_command_get_args(SilcCommandPayload payload);
424 /****f* silccore/SilcCommandAPI/silc_command_get_ident
428 * SilcUInt16 silc_command_get_ident(SilcCommandPayload payload);
432 * Return the command identifier from the payload. The identifier can
433 * be used to identify which command reply belongs to which command.
434 * The client sets the identifier to the payload and server must return
435 * the same identifier in the command reply.
438 SilcUInt16 silc_command_get_ident(SilcCommandPayload payload);
440 /****f* silccore/SilcCommandAPI/silc_command_get_status
444 * bool silc_command_get_status(SilcCommandPayload payload,
445 * SilcCommandStatus *status,
446 * SilcCommandStatus *error);
450 * This function returns the command reply status into `status' and
451 * error status, if error occurred into the `error'. The function
452 * returns TRUE if command reply status is not error, and FALSE if
453 * error occurred. In this case the `error' will include the actual
454 * error status. The `status' can be in this case some list value
455 * which indicates that there will be list of errors.
458 bool silc_command_get_status(SilcCommandPayload payload,
459 SilcCommandStatus *status,
460 SilcCommandStatus *error);
462 /****f* silccore/SilcCommandAPI/silc_command_set_ident
466 * void silc_command_set_ident(SilcCommandPayload payload,
471 * Function to set identifier to already allocated Command Payload. Command
472 * payloads are frequentlly resent in SILC and thusly this makes it easy
473 * to set the identifier without encoding new Command Payload.
476 void silc_command_set_ident(SilcCommandPayload payload, SilcUInt16 ident);
478 /****f* silccore/SilcCommandAPI/silc_command_set_command
482 * void silc_command_set_command(SilcCommandPayload payload,
483 * SilcCommand command);
487 * Function to set the command to already allocated Command Payload. This
488 * makes it easy to change the command in the payload without encoding new
492 void silc_command_set_command(SilcCommandPayload payload, SilcCommand command);