From: Pekka Riikonen Date: Sat, 2 Jun 2001 11:26:57 +0000 (+0000) Subject: updates. X-Git-Tag: robodoc-323~248 X-Git-Url: http://git.silcnet.org/gitweb/?p=silc.git;a=commitdiff_plain;h=af7267cc1671b856d4de21228f1a890a9d131e8f updates. --- diff --git a/CHANGES b/CHANGES index 1942c338..a441ef43 100644 --- a/CHANGES +++ b/CHANGES @@ -1,3 +1,19 @@ +Sat Jun 2 10:45:09 EEST 2001 Pekka Riikonen + + * Fixed a bug in Irssi SILC client; do not show that you are + server/router operator if you really are not. Affected file is + irssi/src/silc/core/client_ops.c. + + * Renamed silc_command_free_payload to silc_command_payload_free. + Affected file lib/silccore/silccommand.h + + * Changed the following headers to ROBODoc format: + + lib/silccore/silcchannel.h + lib/silccore/silccommand.h + lib/silccore/silcid.h + lib/silccore/silcidcache.h + Fri Jun 1 22:19:37 EEST 2001 Pekka Riikonen * Added checking to the server code not to start the server if diff --git a/apps/irssi/src/silc/core/client_ops.c b/apps/irssi/src/silc/core/client_ops.c index 62ba8be9..eac8f1c0 100644 --- a/apps/irssi/src/silc/core/client_ops.c +++ b/apps/irssi/src/silc/core/client_ops.c @@ -557,11 +557,17 @@ silc_command_reply(SilcClient client, SilcClientConnection conn, break; case SILC_COMMAND_OPER: + if (!success) + return; + printformat_module("fe-common/silc", server, NULL, MSGLEVEL_CRAP, SILCTXT_SERVER_OPER); break; case SILC_COMMAND_SILCOPER: + if (!success) + return; + printformat_module("fe-common/silc", server, NULL, MSGLEVEL_CRAP, SILCTXT_ROUTER_OPER); break; diff --git a/apps/silcd/command.c b/apps/silcd/command.c index c47c1caa..8e835507 100644 --- a/apps/silcd/command.c +++ b/apps/silcd/command.c @@ -249,7 +249,7 @@ void silc_server_command_free(SilcServerCommandContext ctx) ctx->users)); if (ctx->users < 1) { if (ctx->payload) - silc_command_free_payload(ctx->payload); + silc_command_payload_free(ctx->payload); if (ctx->packet) silc_packet_context_free(ctx->packet); if (ctx->sock) diff --git a/apps/silcd/command_reply.c b/apps/silcd/command_reply.c index 7b5ef117..4717e3b7 100644 --- a/apps/silcd/command_reply.c +++ b/apps/silcd/command_reply.c @@ -115,7 +115,7 @@ void silc_server_command_reply_process(SilcServer server, void silc_server_command_reply_free(SilcServerCommandReplyContext cmd) { if (cmd) { - silc_command_free_payload(cmd->payload); + silc_command_payload_free(cmd->payload); if (cmd->sock) silc_socket_free(cmd->sock); /* Decrease the reference counter */ silc_free(cmd); diff --git a/lib/silcclient/command_reply.c b/lib/silcclient/command_reply.c index b6c57b4c..676e9a25 100644 --- a/lib/silcclient/command_reply.c +++ b/lib/silcclient/command_reply.c @@ -193,7 +193,7 @@ char *silc_client_command_status_message(SilcCommandStatus status) void silc_client_command_reply_free(SilcClientCommandReplyContext cmd) { if (cmd) { - silc_command_free_payload(cmd->payload); + silc_command_payload_free(cmd->payload); silc_free(cmd); } } diff --git a/lib/silcclient/silcapi.h b/lib/silcclient/silcapi.h index 06704abd..b84c729b 100644 --- a/lib/silcclient/silcapi.h +++ b/lib/silcclient/silcapi.h @@ -59,7 +59,7 @@ * * NAME * - * SilcKeyAgreementStatus + * typedef enum { ... } SilcKeyAgreementStatus; * * DESCRIPTION * @@ -110,7 +110,7 @@ typedef void (*SilcKeyAgreementCallback)(SilcClient client, * * NAME * - * SilcPrivateMessageKeys + * typedef struct { ... } SilcPrivateMessageKeys; * * DESCRIPTION * @@ -170,7 +170,7 @@ typedef void (*SilcVerifyPublicKey)(bool success, void *context); * * NAME * - * SilcClientOperations + * typedef struct { ... } SilcClientOperations; * * DESCRIPTION * @@ -311,10 +311,10 @@ typedef struct { * * DESCRIPTION * - * Allocates new client object. This has to be done before client may - * work. After calling this one must call silc_client_init to initialize - * the client. The `application' is application specific user data pointer - * and caller must free it. + * Allocates new client object. This has to be done before client may + * work. After calling this one must call silc_client_init to initialize + * the client. The `application' is application specific user data pointer + * and caller must free it. * ***/ SilcClient silc_client_alloc(SilcClientOperations *ops, void *application); diff --git a/lib/silccore/silcchannel.c b/lib/silccore/silcchannel.c index c6a9d36c..dab8a83b 100644 --- a/lib/silccore/silcchannel.c +++ b/lib/silccore/silcchannel.c @@ -147,7 +147,7 @@ SilcBuffer silc_channel_payload_encode(unsigned char *channel_name, return buffer; } -/* Free's Channel Payload */ +/* Frees Channel Payload */ void silc_channel_payload_free(SilcChannelPayload payload) { @@ -221,7 +221,7 @@ uint32 silc_channel_get_mode(SilcChannelPayload payload) /* Channel Message Payload structure. Contents of this structure is parsed from SILC packets. */ struct SilcChannelMessagePayloadStruct { - uint16 flags; + SilcMessageFlags flags; uint16 data_len; unsigned char *data; unsigned char *mac; @@ -398,7 +398,7 @@ void silc_channel_message_payload_free(SilcChannelMessagePayload payload) /* Return flags */ -uint16 +SilcMessageFlags silc_channel_message_get_flags(SilcChannelMessagePayload payload) { return payload->flags; @@ -521,7 +521,7 @@ SilcBuffer silc_channel_key_payload_encode(uint16 id_len, return buffer; } -/* Free's Channel Key Payload */ +/* Frees Channel Key Payload */ void silc_channel_key_payload_free(SilcChannelKeyPayload payload) { diff --git a/lib/silccore/silcchannel.h b/lib/silccore/silcchannel.h index 60a19de9..349ae348 100644 --- a/lib/silccore/silcchannel.h +++ b/lib/silccore/silcchannel.h @@ -1,41 +1,106 @@ -/* - - silcchannel.h - - Author: Pekka Riikonen - - Copyright (C) 1997 - 2001 Pekka Riikonen - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - -*/ +/****h* silccore/silcchannel.h + * + * NAME + * + * silcchannel.h + * + * COPYRIGHT + * + * Author: Pekka Riikonen + * + * Copyright (C) 1997 - 2001 Pekka Riikonen + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * DESCRIPTION + * + * Implementations of the Channel Payload, Channel Message Payload and + * Channel Key Payload. The Channel Payload represents new channel and + * is used to distribute the information of the new channel. The Channel + * Message Payload is used to deliver messages to the channel. The routines + * for Channel Message Payload also handles the encryption and decryption + * of the payload. Last, the Channel Key Payload is used to distribute + * a new key to the channel. It is done for example every time someone + * joins a channel or the old key expires. + * + ***/ #ifndef SILCCHANNEL_H #define SILCCHANNEL_H #include "silcdlist.h" -/* Forward declaration for Channel Payload parsed from packet. The - actual structure is defined in source file and is private data. */ +/****s* silccore/SilcChannelAPI/SilcChannelPayload + * + * NAME + * + * typedef struct SilcChannelPayloadStruct *SilcChannelPayload; + * + * DESCRIPTION + * + * This context is the actual Channel Payload and is allocated + * by silc_channel_payload_parse and given as argument usually to + * all silc_channel_payload_* functions. It is freed by the + * silc_channel_payload_free function. + * + ***/ typedef struct SilcChannelPayloadStruct *SilcChannelPayload; -/* Forward declaration for Channel Message Payload parsed from packet. The - actual structure is defined in source file and is private data. */ +/****s* silccore/SilcChannelAPI/SilcChannelMessagePayload + * + * NAME + * + * typedef struct + * SilcChannelMessagePayloadStruct *SilcChannelMessagePayload; + * + * DESCRIPTION + * + * This context is the actual Channel Message Payload and is allocated + * by silc_channel_message_payload_parse and given as argument usually to + * all silc_channel_message_payload_* functions. It is freed by the + * silc_channel_message_payload_free function. + * + ***/ typedef struct SilcChannelMessagePayloadStruct *SilcChannelMessagePayload; -/* Forward declaration for Channel Key Payload parsed from packet. The - actual structure is defined in source file and is private data. */ +/****s* silccore/SilcChannelAPI/SilcChannelKeyPayload + * + * NAME + * + * typedef struct SilcChannelKeyPayloadStruct *SilcChannelKeyPayload; + * + * DESCRIPTION + * + * This context is the actual Channel Key Payload and is allocated + * by silc_channel_key_payload_parse and given as argument usually to + * all silc_channel_key_payload_* functions. It is freed by the + * silc_channel_key_payload_free function. + * + ***/ typedef struct SilcChannelKeyPayloadStruct *SilcChannelKeyPayload; -/* The Message flag type */ +/****d* silccore/SilcChannelAPI/SilcMessageFlags + * + * NAME + * + * typedef uint16 SilcMessageFlags; + * + * DESCRIPTION + * + * The message flags type definition and the message flags. The + * message flags are used to indicate some status of the message. + * These flags are also used by the private message interfaces. + * + * SOURCE + */ typedef uint16 SilcMessageFlags; /* The message flags (shared by both channel and private messages) */ @@ -47,31 +112,224 @@ typedef uint16 SilcMessageFlags; #define SILC_MESSAGE_FLAG_REQUEST 0x0010 #define SILC_MESSAGE_FLAG_RESERVED 0x0020 /* to 0x0200 */ #define SILC_MESSAGE_FLAG_PRIVATE 0x0400 /* to 0x8000 */ +/***/ /* Prototypes */ + +/****f* silccore/SilcChannelAPI/silc_channel_payload_parse + * + * SYNOPSIS + * + * SilcChannelPayload silc_channel_payload_parse(SilcBuffer buffer); + * + * DESCRIPTION + * + * Parses channel payload returning new channel payload structure. The + * `buffer' is the raw payload buffer. + * + ***/ SilcChannelPayload silc_channel_payload_parse(SilcBuffer buffer); + +/****f* silccore/SilcChannelAPI/silc_channel_payload_parse_list + * + * SYNOPSIS + * + * SilcDList silc_channel_payload_parse_list(SilcBuffer buffer); + * + * DESCRIPTION + * + * Parses list of channel payloads returning list of payloads. This + * is equivalent to the silc_channel_payload_parse except that the `buffer' + * now includes multiple Channel Payloads one after the other. + * + ***/ SilcDList silc_channel_payload_parse_list(SilcBuffer buffer); + +/****f* silccore/SilcChannelAPI/silc_channel_payload_encode + * + * SYNOPSIS + * + * SilcBuffer silc_channel_payload_encode(unsigned char *channel_name, + * uint16 channel_name_len, + * unsigned char *channel_id, + * uint32 channel_id_len, + * uint32 mode); + * + * DESCRIPTION + * + * Encode new channel payload and returns it as buffer. + * + ***/ SilcBuffer silc_channel_payload_encode(unsigned char *channel_name, uint16 channel_name_len, unsigned char *channel_id, uint32 channel_id_len, uint32 mode); + +/****f* silccore/SilcChannelAPI/silc_channel_payload_free + * + * SYNOPSIS + * + * void silc_channel_payload_free(SilcChannelPayload payload); + * + * DESCRIPTION + * + * Frees Channel Payload and all data in it. + * + ***/ void silc_channel_payload_free(SilcChannelPayload payload); + +/****f* silccore/SilcChannelAPI/silc_channel_payload_list_free + * + * SYNOPSIS + * + * void silc_channel_payload_list_free(SilcDList list); + * + * DESCRIPTION + * + * Frees list of Channel Payloads and all data in them. + * + ***/ void silc_channel_payload_list_free(SilcDList list); + +/****f* silccore/SilcChannelAPI/silc_channel_get_name + * + * SYNOPSIS + * + * unsigned char *silc_channel_get_name(SilcChannelPayload payload, + * uint32 *channel_name_len); + * + * DESCRIPTION + * + * Return the channel name from the payload. The caller must not free it. + * + ***/ unsigned char *silc_channel_get_name(SilcChannelPayload payload, uint32 *channel_name_len); + +/****f* silccore/SilcChannelAPI/silc_channel_get_id + * + * SYNOPSIS + * + * unsigned char *silc_channel_get_id(SilcChannelPayload payload, + * uint32 *channel_id_len); + * + * DESCRIPTION + * + * Return the Channel ID data from the payload. The caller must not free it. + * + ***/ unsigned char *silc_channel_get_id(SilcChannelPayload payload, uint32 *channel_id_len); + +/****f* silccore/SilcChannelAPI/silc_channel_get_id_parse + * + * SYNOPSIS + * + * SilcChannelID *silc_channel_get_id_parse(SilcChannelPayload payload); + * + * DESCRIPTION + * + * Return the Channel ID as parsed ID. This is equivalent to the + * silc_channel_get_id execpt that the ID is already parsed. The caller + * must free the parsed Channel ID. + * + ***/ SilcChannelID *silc_channel_get_id_parse(SilcChannelPayload payload); + +/****f* silccore/SilcChannelAPI/silc_channel_get_mode + * + * SYNOPSIS + * + * uint32 silc_channel_get_mode(SilcChannelPayload payload); + * + * DESCRIPTION + * + * Return the mode. The mode is arbitrary. It can be the mode of the + * channel or perhaps the mode of the client on the channel. The protocol + * dictates what the usage of the mode is in different circumstances. + * + ***/ uint32 silc_channel_get_mode(SilcChannelPayload payload); + +/****f* silccore/SilcChannelAPI/silc_channel_message_payload_decrypt + * + * SYNOPSIS + * + * int silc_channel_message_payload_decrypt(unsigned char *data, + * size_t data_len, + * SilcCipher cipher, + * SilcHmac hmac); + * + * DESCRIPTION + * + * Decrypt the channel message. First push the IV out of the packet `data'. + * The IV is used in the decryption process. Then decrypt the message. + * After decryption, take the MAC from the decrypted packet, compute MAC + * and compare the MACs. If they match, the decryption was successful + * and we have the channel message ready to be displayed. + * + * This is usually used by the Channel Message interface itself but can + * be called by the appliation if separate decryption process is required. + * For example server might need to call this directly in some + * circumstances. The `cipher' is used to decrypt the payload. + * + * If the `hmac' is no provided then the MAC of the channel message is + * not verified. + * + ***/ int silc_channel_message_payload_decrypt(unsigned char *data, size_t data_len, SilcCipher cipher, SilcHmac hmac); + +/****f* silccore/SilcChannelAPI/silc_channel_message_payload_parse + * + * SYNOPSIS + * + * SilcChannelMessagePayload + * silc_channel_message_payload_parse(SilcBuffer buffer, + * SilcCipher cipher, + * SilcHmac hmac); + * + * DESCRIPTION + * + * Parses channel message payload returning new channel payload structure. + * This also decrypts it and checks the MAC. The `cipher's is used to + * decrypt the payload. + * + * If the `hmac' is no provided then the MAC of the channel message is + * not verified. + * + ***/ SilcChannelMessagePayload silc_channel_message_payload_parse(SilcBuffer buffer, SilcCipher cipher, SilcHmac hmac); + +/****f* silccore/SilcChannelAPI/silc_channel_message_payload_encode + * + * SYNOPSIS + * + * SilcBuffer silc_channel_message_payload_encode(uint16 flags, + * uint16 data_len, + * unsigned char *data, + * uint16 iv_len, + * unsigned char *iv, + * SilcCipher cipher, + * SilcHmac hmac); + * + * DESCRIPTION + * + * Encodes channel message payload into a buffer and returns it. This + * is used to add channel message payload into a packet. As the channel + * payload is encrypted separately from other parts of the packet padding + * must be applied to the payload. The function generates the padding + * automatically from random data. The `cipher' is the cipher used + * encrypt the payload and `hmac' is used to compute the MAC for the + * payload. + * + ***/ SilcBuffer silc_channel_message_payload_encode(uint16 flags, uint16 data_len, unsigned char *data, @@ -79,25 +337,179 @@ SilcBuffer silc_channel_message_payload_encode(uint16 flags, unsigned char *iv, SilcCipher cipher, SilcHmac hmac); + +/****f* silccore/SilcChannelAPI/silc_channel_message_payload_free + * + * SYNOPSIS + * + * void + * silc_channel_message_payload_free(SilcChannelMessagePayload payload); + * + * DESCRIPTION + * + * Free's Channel Message Payload and all data in it. + * + ***/ void silc_channel_message_payload_free(SilcChannelMessagePayload payload); -uint16 + +/****f* silccore/SilcChannelAPI/silc_channel_message_get_flags + * + * SYNOPSIS + * + * SilcMessageFlags + * silc_channel_message_get_flags(SilcChannelMessagePayload payload); + * + * DESCRIPTION + * + * Returns the message flags from the payload. + * + ***/ +SilcMessageFlags silc_channel_message_get_flags(SilcChannelMessagePayload payload); + +/****f* silccore/SilcChannelAPI/silc_channel_message_get_data + * + * SYNOPSIS + * + * unsigned char * + * silc_channel_message_get_data(SilcChannelMessagePayload payload, + * uint32 *data_len); + * + * DESCRIPTION + * + * Return the data in the payload, that is, the actual channel message. + * The caller must not free it. + * + ***/ unsigned char *silc_channel_message_get_data(SilcChannelMessagePayload payload, uint32 *data_len); + +/****f* silccore/SilcChannelAPI/silc_channel_message_get_mac + * + * SYNOPSIS + * + * unsigned char * + * silc_channel_message_get_mac(SilcChannelMessagePayload payload); + * + * DESCRIPTION + * + * Return the MAC of the payload. The caller must already know the + * length of the MAC. The caller must not free the MAC. + * + ***/ unsigned char *silc_channel_message_get_mac(SilcChannelMessagePayload payload); + +/****f* silccore/SilcChannelAPI/silc_channel_message_get_iv + * + * SYNOPSIS + * + * unsigned char * + * silc_channel_message_get_iv(SilcChannelMessagePayload payload); + * + * DESCRIPTION + * + * Return the IV of the payload. The caller must already know the + * length of the IV. The caller must not free the IV. + * + ***/ unsigned char *silc_channel_message_get_iv(SilcChannelMessagePayload payload); + +/****f* silccore/SilcChannelAPI/silc_channel_key_payload_parse + * + * SYNOPSIS + * + * SilcChannelKeyPayload silc_channel_key_payload_parse(SilcBuffer buffer); + * + * DESCRIPTION + * + * Parses channel key payload returning new channel key payload + * structure. + * + ***/ SilcChannelKeyPayload silc_channel_key_payload_parse(SilcBuffer buffer); + +/****f* silccore/SilcChannelAPI/silc_channel_key_payload_encode + * + * SYNOPSIS + * + * SilcBuffer silc_channel_key_payload_encode(uint16 id_len, + * unsigned char *id, + * uint16 cipher_len, + * unsigned char *cipher, + * uint16 key_len, + * unsigned char *key); + * + * DESCRIPTION + * + * Encodes channel key payload into a buffer and returns it. This is used + * to add channel key payload into a packet. + * + ***/ SilcBuffer silc_channel_key_payload_encode(uint16 id_len, unsigned char *id, uint16 cipher_len, unsigned char *cipher, uint16 key_len, unsigned char *key); + +/****f* silccore/SilcChannelAPI/silc_channel_key_payload_free + * + * SYNOPSIS + * + * void silc_channel_key_payload_free(SilcChannelKeyPayload payload); + * + * DESCRIPTION + * + * Frees the Channel Key Payload and all data in it. + * + ***/ void silc_channel_key_payload_free(SilcChannelKeyPayload payload); + +/****f* silccore/SilcChannelAPI/silc_channel_key_get_id + * + * SYNOPSIS + * + * unsigned char *silc_channel_key_get_id(SilcChannelKeyPayload payload, + * uint32 *id_len); + * + * DESCRIPTION + * + * Return the Channel ID data from the payload. The caller must not + * free it. + * + ***/ unsigned char *silc_channel_key_get_id(SilcChannelKeyPayload payload, uint32 *id_len); + +/****f* silccore/SilcChannelAPI/silc_channel_key_get_cipher + * + * SYNOPSIS + * + * unsigned char *silc_channel_key_get_cipher(SilcChannelKeyPayload payload, + * uint32 *cipher_len); + * + * DESCRIPTION + * + * Return the name of the cipher from the payload. The caller must not + * free it. + * + ***/ unsigned char *silc_channel_key_get_cipher(SilcChannelKeyPayload payload, uint32 *cipher_len); + +/****f* silccore/SilcChannelAPI/silc_channel_key_get_key + * + * SYNOPSIS + * + * unsigned char *silc_channel_key_get_key(SilcChannelKeyPayload payload, + * uint32 *key_len); + * + * DESCRIPTION + * + * Return the raw key material from the payload. The caller must not + * free it. + * + ***/ unsigned char *silc_channel_key_get_key(SilcChannelKeyPayload payload, uint32 *key_len); diff --git a/lib/silccore/silccommand.c b/lib/silccore/silccommand.c index 422c9f20..c1ab6595 100644 --- a/lib/silccore/silccommand.c +++ b/lib/silccore/silccommand.c @@ -336,9 +336,9 @@ silc_command_reply_payload_encode_va(SilcCommand cmd, return buffer; } -/* Free's Command Payload */ +/* Frees Command Payload */ -void silc_command_free_payload(SilcCommandPayload payload) +void silc_command_payload_free(SilcCommandPayload payload) { if (payload) { silc_argument_payload_free(payload->args); diff --git a/lib/silccore/silccommand.h b/lib/silccore/silccommand.h index 2b069bc2..32ef4ba5 100644 --- a/lib/silccore/silccommand.h +++ b/lib/silccore/silccommand.h @@ -1,38 +1,83 @@ -/* - - silccommand.h - - Author: Pekka Riikonen - - Copyright (C) 1997 - 2000 Pekka Riikonen - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - -*/ +/****h* silccore/silccommand.h + * + * NAME + * + * silccommand.h + * + * COPYRIGHT + * + * Author: Pekka Riikonen + * + * Copyright (C) 1997 - 2000 Pekka Riikonen + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * DESCRIPTION + * + * Implementation of the Command Payload. The Command Payload is used to + * send commands and also command replies usually between client and + * server. + * + ***/ #ifndef SILCCOMMAND_H #define SILCCOMMAND_H -/* Command function callback. The actual command function pointer. */ +/****f* silccore/SilcCommandAPI/SilcCommandCb + * + * SYNOPSIS + * + * SilcChannelPayload silc_channel_payload_parse(SilcBuffer buffer); + * + * DESCRIPTION + * + * Command function callback. The actual command function pointer. + * This is generic command callback that the application may choose to + * use with its command routines. + * + ***/ typedef void (*SilcCommandCb)(void *context); -/* Typedefinition for SILC commands. */ -typedef unsigned char SilcCommand; - -/* Forward declaration for Command Payload parsed from packet. The - actual structure is defined in source file and is private data. */ +/****s* silccore/SilcCommandAPI/SilcCommandPayload + * + * NAME + * + * typedef struct SilcCommandPayloadStruct *SilcCommandPayload; + * + * DESCRIPTION + * + * This context is the actual Command Payload and is allocated + * by silc_command_payload_parse and given as argument usually to + * all silc_command_payload_* functions. It is freed by the + * silc_command_payload_free function. + * + ***/ typedef struct SilcCommandPayloadStruct *SilcCommandPayload; -/* Command flags. These set how the commands behave on different - situations. These can be OR'ed together to set multiple flags. */ +/****d* silccore/SilcCommandAPI/SilcCommandFlags + * + * NAME + * + * typedef enum { ... } SilcCommandFlags; + * + * DESCRIPTION + * + * Command flags that set how the commands behave on different + * situations. These can be OR'es together to set multiple flags. + * The application is resoponsible of implementing the behaviour + * of these flags. These are here just to define generic flags. + * The server usually makes use of these flags. + * + * SOURCE + */ typedef enum { SILC_CF_NONE = 0, @@ -56,9 +101,26 @@ typedef enum { SILC_CF_SILC_OPER = (1L << 5), } SilcCommandFlag; +/***/ + +/****d* silccore/SilcCommandAPI/SilcCommand + * + * NAME + * + * typedef unsigned char SilcCommand; + * + * DESCRIPTION + * + * The SilcCommand type definition and the commands. The commands + * listed here are the official SILC Commands and they have client + * and server counterparts. + * + * SOURCE + */ +typedef unsigned char SilcCommand; /* All SILC commands. These are commands that have client and server - counterparts. These are pretty much the same as in IRC. */ + counterparts. */ #define SILC_COMMAND_NONE 0 #define SILC_COMMAND_WHOIS 1 #define SILC_COMMAND_WHOWAS 2 @@ -89,8 +151,22 @@ typedef enum { /* Reserved */ #define SILC_COMMAND_RESERVED 255 +/***/ -/* Command Status type */ +/****d* silccore/SilcCommandAPI/SilcCommandStatus + * + * NAME + * + * typedef uint16 SilcCommandStatus; + * + * DESCRIPTION + * + * The SilcCommandStatus type definition and the status defines. + * The server returns a status in each Command Payload indicating + * the status of the command. + * + * SOURCE + */ typedef uint16 SilcCommandStatus; /* Command Status messages */ @@ -136,32 +212,212 @@ typedef uint16 SilcCommandStatus; #define SILC_STATUS_ERR_AUTH_FAILED 45 #define SILC_STATUS_ERR_UNKNOWN_ALGORITHM 46 #define SILC_STATUS_ERR_NO_SUCH_SERVER_ID 47 +/***/ /* Prototypes */ + +/****f* silccore/SilcCommandAPI/silc_command_payload_parse + * + * SYNOPSIS + * + * SilcCommandPayload silc_command_payload_parse(SilcBuffer buffer); + * + * DESCRIPTION + * + * Parses command payload returning new command payload structure. The + * `buffer' is the raw payload. + * + ***/ SilcCommandPayload silc_command_payload_parse(SilcBuffer buffer); + +/****f* silccore/SilcCommandAPI/silc_command_payload_encode + * + * SYNOPSIS + * + * SilcBuffer silc_command_payload_encode(SilcCommand cmd, + * uint32 argc, + * unsigned char **argv, + * uint32 *argv_lens, + * uint32 *argv_types, + * uint16 ident); + * + * DESCRIPTION + * + * Encodes Command Payload returning it to SilcBuffer. + * + ***/ SilcBuffer silc_command_payload_encode(SilcCommand cmd, uint32 argc, unsigned char **argv, uint32 *argv_lens, uint32 *argv_types, uint16 ident); + +/****f* silccore/SilcCommandAPI/silc_command_payload_encode_payload + * + * SYNOPSIS + * + * SilcBuffer + * silc_command_payload_encode_payload(SilcCommandPayload payload); + * + * DESCRIPTION + * + * Same as silc_command_payload_encode but encodes the buffer from + * SilcCommandPayload structure instead of raw data. + * + ***/ SilcBuffer silc_command_payload_encode_payload(SilcCommandPayload payload); + +/****f* silccore/SilcCommandAPI/silc_command_payload_encode_va + * + * SYNOPSIS + * + * SilcBuffer silc_command_payload_encode_va(SilcCommand cmd, + * uint16 ident, + * uint32 argc, ...); + * + * DESCRIPTION + * + * Encodes Command payload with variable argument list. The arguments + * must be: uint32, unsigned char *, unsigned int, ... One + * {uint32, unsigned char * and unsigned int} forms one argument, + * thus `argc' in case when sending one {uint32, unsigned char * + * and uint32} equals one (1) and when sending two of those it + * equals two (2), and so on. This has to be preserved or bad things + * will happen. The variable arguments is: {type, data, data_len}. + * + ***/ SilcBuffer silc_command_payload_encode_va(SilcCommand cmd, uint16 ident, uint32 argc, ...); + +/****f* silccore/SilcCommandAPI/silc_command_payload_encode_vap + * + * SYNOPSIS + * + * SilcBuffer silc_command_payload_encode_vap(SilcCommand cmd, + * uint16 ident, + * uint32 argc, va_list ap); + * + * DESCRIPTION + * + * This is equivalent to the silc_command_payload_encode_va except + * takes the va_list as argument. + * + ***/ SilcBuffer silc_command_payload_encode_vap(SilcCommand cmd, uint16 ident, uint32 argc, va_list ap); + +/****f* silccore/SilcCommandAPI/silc_command_reply_payload_encode_va + * + * SYNOPSIS + * + * SilcBuffer + * silc_command_reply_payload_encode_va(SilcCommand cmd, + * SilcCommandStatus status, + * uint16 ident, + * uint32 argc, ...); + * + * DESCRIPTION + * + * Same as silc_command_payload_encode_va except that this is used to + * encode strictly command reply packets. The command status message + * to be returned is sent as extra argument to this function. The `argc' + * must not count `status' as on argument. + * + ***/ SilcBuffer silc_command_reply_payload_encode_va(SilcCommand cmd, SilcCommandStatus status, uint16 ident, uint32 argc, ...); -void silc_command_free_payload(SilcCommandPayload payload); + +/****f* silccore/SilcCommandAPI/silc_command_free + * + * SYNOPSIS + * + * void silc_command_payload_free(SilcCommandPayload payload); + * + * DESCRIPTION + * + * Frees the Command Payload and all data in it. + * + ***/ +void silc_command_payload_free(SilcCommandPayload payload); + +/****f* silccore/SilcCommandAPI/silc_command_get + * + * SYNOPSIS + * + * SilcCommand silc_command_get(SilcCommandPayload payload); + * + * DESCRIPTION + * + * Return the command from the payload. + * + ***/ SilcCommand silc_command_get(SilcCommandPayload payload); + +/****f* silccore/SilcCommandAPI/silc_command_get_args + * + * SYNOPSIS + * + * SilcArgumentPayload silc_command_get_args(SilcCommandPayload payload); + * + * DESCRIPTION + * + * Return the Arguments Payload containing the arguments from the + * Command Payload. The caller must not free it. + * + ***/ SilcArgumentPayload silc_command_get_args(SilcCommandPayload payload); + +/****f* silccore/SilcCommandAPI/silc_command_get_ident + * + * SYNOPSIS + * + * uint16 silc_command_get_ident(SilcCommandPayload payload); + * + * DESCRIPTION + * + * Return the command identifier from the payload. The identifier can + * be used to identify which command reply belongs to which command. + * The client sets the identifier to the payload and server must return + * the same identifier in the command reply. + * + ***/ uint16 silc_command_get_ident(SilcCommandPayload payload); + +/****f* silccore/SilcCommandAPI/silc_command_set_ident + * + * SYNOPSIS + * + * void silc_command_set_ident(SilcCommandPayload payload, uint16 ident); + * + * DESCRIPTION + * + * Function to set identifier to already allocated Command Payload. Command + * payloads are frequentlly resent in SILC and thusly this makes it easy + * to set the identifier without encoding new Command Payload. + * + ***/ void silc_command_set_ident(SilcCommandPayload payload, uint16 ident); + +/****f* silccore/SilcCommandAPI/silc_command_set_command + * + * SYNOPSIS + * + * void silc_command_set_command(SilcCommandPayload payload, + * SilcCommand command); + * + * DESCRIPTION + * + * Function to set the command to already allocated Command Payload. This + * makes it easy to change the command in the payload without encoding new + * Command Payload. + * + ***/ void silc_command_set_command(SilcCommandPayload payload, SilcCommand command); #endif diff --git a/lib/silccore/silcid.h b/lib/silccore/silcid.h index 5604fd2a..49cf666e 100644 --- a/lib/silccore/silcid.h +++ b/lib/silccore/silcid.h @@ -1,40 +1,62 @@ -/* +/****h* silccore/silcid.h + * + * NAME + * + * silcid.h + * + * COPYRIGHT + * + * Author: Pekka Riikonen + * + * Copyright (C) 1997 - 2000 Pekka Riikonen + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * DESCRIPTION + * + * These are important ID types used in SILC. SILC server creates these + * but SILC client has to handle these as well since these are used in + * packet sending and reception. However, client never creates these + * but it receives the correct ID's from server. Clients, servers and + * channels are identified by the these ID's. + * + * The ID's are based on IP addresses. The IP address provides a good + * way to distinguish the ID's from other ID's. The ID's support both + * IPv4 and IPv6. + * + ***/ - silcid.h +#ifndef SILCID_H +#define SILCID_H - Author: Pekka Riikonen - - Copyright (C) 1997 - 2000 Pekka Riikonen - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - -*/ -/* These are important ID types used in SILC. SILC server creates these - but SILC client has to handle these as well since these are used in - packet sending and reception. However, client never creates these - but it receives the correct ID's from server. Clients, servers and - channels are identified by the these ID's. -*/ - -#ifndef ID_H -#define ID_H +/****d* silccore/SilcIDAPI/SilcIdType + * + * NAME + * + * typedef uint16 SilcIdType; + * + * DESCRIPTION + * + * SILC ID type definitions and the ID types. + * + * SOURCE + */ +typedef uint16 SilcIdType; /* The SILC ID Types */ #define SILC_ID_NONE 0 #define SILC_ID_SERVER 1 #define SILC_ID_CLIENT 2 #define SILC_ID_CHANNEL 3 - -/* Type definition for the ID types. */ -typedef uint16 SilcIdType; +/***/ /* The ID Lenghts. These are IPv4 based and should be noted if used directly that these cannot be used with IPv6. */ @@ -44,88 +66,253 @@ typedef uint16 SilcIdType; #define CLIENTID_HASH_LEN (88 / 8) /* Client ID's 88 bit MD5 hash */ -/* - SILC ID IP structure. - - Generic IP address structure to indicate either IPv4 or IPv6 address. - This structure is used inside all SILC ID's. The true length of the - ID depends of the length of the IP address. -*/ +/****s* silccore/SilcIDAPI/SilcIDIP + * + * NAME + * + * typedef struct { ... } SilcIDIP; + * + * DESCRIPTION + * + * Generic IP address structure to indicate either IPv4 or IPv6 address. + * This structure is used inside all SILC ID's. The true length of the + * ID depends of the length of the IP address. + * + * SOURCE + */ typedef struct { unsigned char data[16]; /* IP data (in MSB first order) */ uint8 data_len; /* Length of the data (4 or 16) */ } SilcIDIP; +/***/ -/* - 64 or 160 bit SilcServerID structure: - - n bit IP address - 16 bit port - 16 bit random number -*/ +/****s* silccore/SilcIDAPI/SilcServerID + * + * NAME + * + * typedef struct { ... } SilcServerID; + * + * DESCRIPTION + * + * 64 or 160 bit SilcServerID structure: + * + * n bit IP address + * 16 bit port + * 16 bit random number + * + * SOURCE + */ typedef struct { SilcIDIP ip; /* n bit IP address */ uint16 port; /* 16 bit port */ uint16 rnd; /* 16 bit random number */ } SilcServerID; +/***/ -/* - 128 or 224 bit SilcClientID structure: - - n bit ServerID IP address [bits 1-32 or bits 1-128] - 8 bit random number - 88 bit hash value from nickname -*/ +/****s* silccore/SilcIDAPI/SilcClientID + * + * NAME + * + * typedef struct { ... } SilcClientID; + * + * DESCRIPTION + * + * 128 or 224 bit SilcClientID structure: + * + * n bit ServerID IP address [bits 1-32 or bits 1-128] + * 8 bit random number + * 88 bit hash value from nickname + * + * SOURCE + */ typedef struct { SilcIDIP ip; /* n bit IP address */ unsigned char rnd; /* 8 bit random number */ unsigned char hash[CLIENTID_HASH_LEN]; /* 88 bit MD5 hash */ } SilcClientID; +/***/ -/* - 64 or 160 bit SilcChannel ID structure: - - n bit Router's ServerID IP address [bits 1-32 or bits 1-128] - 16 bit Router's ServerID port [bits 33-48 or bits 129-144] - 16 bit random number -*/ +/****s* silccore/SilcIDAPI/SilcChannelID + * + * NAME + * + * typedef struct { ... } SilcChannelID; + * + * DESCRIPTION + * + * 64 or 160 bit SilcChannel ID structure: + * + * n bit Router's ServerID IP address [bits 1-32 or bits 1-128] + * 16 bit Router's ServerID port [bits 33-48 or bits 129-144] + * 16 bit random number + * + * SOURCE + */ typedef struct { SilcIDIP ip; /* n bit IP address */ uint16 port; /* 16 bit port */ uint16 rnd; /* 16 bit random number */ } SilcChannelID; +/***/ /* Macros */ -/* Compares two ID's. */ +/****d* silccore/SilcIDAPI/SILC_ID_COMPARE + * + * NAME + * + * #define SILC_ID_COMPARE ... + * + * DESCRIPTION + * + * Compares two ID's. Returns TRUE if they match and FALSE if they do + * not. + * + * SOURCE + */ #define SILC_ID_COMPARE(id1, id2, len) (!memcmp(id1, id2, len)) +/***/ -/* Compares Client ID's */ +/****d* silccore/SilcIDAPI/SILC_ID_CLIENT_COMPARE + * + * NAME + * + * #define SILC_ID_CLIENT_COMPARE ... + * + * DESCRIPTION + * + * Compares Client ID's. Returns TRUE if they match. + * + * SOURCE + */ #define SILC_ID_CLIENT_COMPARE(id1, id2) \ SILC_ID_COMPARE(id1, id2, sizeof(SilcClientID)) +/***/ -/* Compares Server ID's */ +/****d* silccore/SilcIDAPI/SILC_ID_SERVER_COMPARE + * + * NAME + * + * #define SILC_ID_SERVER_COMPARE ... + * + * DESCRIPTION + * + * Compares Server ID's. Returns TRUE if they match. + * + * SOURCE + */ #define SILC_ID_SERVER_COMPARE(id1, id2) \ SILC_ID_COMPARE(id1, id2, sizeof(SilcServerID)) +/***/ -/* Compares Channel ID's */ +/****d* silccore/SilcIDAPI/SILC_ID_CHANNEL_COMPARE + * + * NAME + * + * #define SILC_ID_CHANNEL_COMPARE ... + * + * DESCRIPTION + * + * Compares Channel ID's. Returns TRUE if they match. + * + * SOURCE + */ #define SILC_ID_CHANNEL_COMPARE(id1, id2) \ SILC_ID_COMPARE(id1, id2, sizeof(SilcChannelID)) +/***/ -/* Compares two ID's by type */ +/****d* silccore/SilcIDAPI/SILC_ID_COMPARE_TYPE + * + * NAME + * + * #define SILC_ID_COMPARE_TYPE ... + * + * DESCRIPTION + * + * Compares two ID's by type. Returns TRUE if they match. + * + * SOURCE + */ #define SILC_ID_COMPARE_TYPE(id1, id2, type) \ (type == SILC_ID_SERVER ? SILC_ID_SERVER_COMPARE(id1, id2) : \ type == SILC_ID_CLIENT ? SILC_ID_CLIENT_COMPARE(id1, id2) : \ SILC_ID_CHANNEL_COMPARE(id1, id2)) +/***/ -/* Compare nickname hash from Client ID */ +/****d* silccore/SilcIDAPI/SILC_ID_COMPARE_HASH + * + * NAME + * + * #define SILC_ID_COMPARE_HASH ... + * + * DESCRIPTION + * + * Compares the nickname hash of the Client ID. Returns TRUE if + * they match. Since the nickname hash is based on the nickname of + * the client this can be used to search the ID by nickname (taking + * the hash out of it) or using the hash from the ID. + * + * SOURCE + */ #define SILC_ID_COMPARE_HASH(id1, id2) \ (!memcmp((id1)->hash, (id2)->hash, CLIENTID_HASH_LEN)) +/***/ /* Prototypes */ + +/****f* silccore/SilcIDAPI/silc_id_id2str + * + * SYNOPSIS + * + * unsigned char *silc_id_id2str(void *id, SilcIdType type); + * + * DESCRIPTION + * + * Converts an ID of type `type' to data. This can be used to + * convert the ID's to data for inclusion in the packets. + * + ***/ unsigned char *silc_id_id2str(void *id, SilcIdType type); + +/****f* silccore/SilcIDAPI/silc_id_str2id + * + * SYNOPSIS + * + * void *silc_id_str2id(unsigned char *id, uint32 id_len, SilcIdType type); + * + * DESCRIPTION + * + * Converts ID data string to an ID. This can be used to get the + * ID out of data that has been taken for example from packet. + * + ***/ void *silc_id_str2id(unsigned char *id, uint32 id_len, SilcIdType type); + +/****f* silccore/SilcIDAPI/silc_id_get_len + * + * SYNOPSIS + * + * uint32 silc_id_get_len(void *id, SilcIdType type); + * + * DESCRIPTION + * + * Returns the true length of the ID of the type `type'. + * + ***/ uint32 silc_id_get_len(void *id, SilcIdType type); + +/****f* silccore/SilcIDAPI/silc_id_dup + * + * SYNOPSIS + * + * void *silc_id_dup(void *id, SilcIdType type); + * + * DESCRIPTION + * + * Duplicates the ID of the type `type'. The caller must free the + * duplicated ID. + * + ***/ void *silc_id_dup(void *id, SilcIdType type); #endif diff --git a/lib/silccore/silcidcache.c b/lib/silccore/silcidcache.c index b99859b5..02ed07e0 100644 --- a/lib/silccore/silcidcache.c +++ b/lib/silccore/silcidcache.c @@ -122,7 +122,7 @@ SilcIDCache silc_idcache_alloc(uint32 count, SilcIdType id_type, return cache; } -/* Free's ID cache object and cache entries */ +/* Frees ID cache object and cache entries */ void silc_idcache_free(SilcIDCache cache) { @@ -134,7 +134,11 @@ void silc_idcache_free(SilcIDCache cache) } } -/* Add new entry to the cache. */ +/* Add new entry to the cache. Returns TRUE if the entry was added and + FALSE if it could not be added. The `name' is the name associated with + the ID, the `id' the actual ID and the `context' a used specific context. + If the `expire' is TRUE the entry expires in default time and if FALSE + the entry never expires from the cache. */ bool silc_idcache_add(SilcIDCache cache, char *name, void *id, void *context, int expire) @@ -559,7 +563,7 @@ bool silc_idcache_list_next(SilcIDCacheList list, SilcIDCacheEntry *ret) return TRUE; } -/* Free's ID cache list. User must free the list object returned by +/* Frees ID cache list. User must free the list object returned by any of the searching functions. */ void silc_idcache_list_free(SilcIDCacheList list) diff --git a/lib/silccore/silcidcache.h b/lib/silccore/silcidcache.h index c3608c4d..d2d0d063 100644 --- a/lib/silccore/silcidcache.h +++ b/lib/silccore/silcidcache.h @@ -1,116 +1,474 @@ -/* +/****h* silccore/silcidcache.h + * + * NAME + * + * silcidcache.h + * + * COPYRIGHT + * + * Author: Pekka Riikonen + * + * Copyright (C) 2000 - 2001 Pekka Riikonen + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * DESCRIPTION + * + * SILC ID Cache is an cache for all kinds of ID's used in the SILC + * protocol. Application can save here the ID's it uses and the interface + * provides fast retrieval of the ID's from the cache. + * + */ - silcidcache.h +#ifndef SILCIDCACHE_H +#define SILCIDCACHE_H - Author: Pekka Riikonen - - Copyright (C) 2000 - 2001 Pekka Riikonen - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - -*/ - -#ifndef IDCACHE_H -#define IDCACHE_H - -/* - Silc ID Cache Entry object. - - This is one entry in the SILC ID Cache system. Contents of this is - allocated outside the ID cache system, however, all the fields are - filled with ID cache utility functions. The ID cache system does not - allocate any of these fields nor free them. - - void *id - - The actual ID. - - char name - - A name associated with the ID. - - uint32 expire - - Time when this cache entry expires. This is normal time() value - plus the validity. Cache entry has expired if current time is - more than value in this field. If this value is zero (0) the - entry never expires. - - void *context - - Any caller specified context. - -*/ +/****s* silccore/SilcIDCacheAPI/SilcIDCacheEntry + * + * NAME + * + * typedef struct { ... } SilcIDCacheEntry; + * + * DESCRIPTION + * + * This is one entry in the SILC ID Cache system. Contents of this is + * allocated outside the ID cache system, however, all the fields are + * filled with ID cache utility functions. The ID cache system does not + * allocate any of these fields nor free them. + * + * void *id + * + * The actual ID. + * + * char name + * + * A name associated with the ID. + * + * uint32 expire + * + * Time when this cache entry expires. This is normal time() value + * plus the validity. Cache entry has expired if current time is + * more than value in this field. If this value is zero (0) the + * entry never expires. + * + * void *context + * + * Any caller specified context. + * + * SOURCE + */ typedef struct { void *id; char *name; uint32 expire; void *context; } *SilcIDCacheEntry; +/***/ -/* Forward declaration for SILC ID Cache object. */ +/****s* silccore/SilcIDCacheAPI/SilcIDCache + * + * NAME + * + * typedef struct SilcIDCacheStruct *SilcIDCache; + * + * DESCRIPTION + * + * This context is the actual ID Cache and is allocated by + * silc_idcache_alloc and given as argument usually to all + * silc_idcache_* functions. It is freed by the + * silc_idcache_free function. + * + ***/ typedef struct SilcIDCacheStruct *SilcIDCache; -/* Forward declaration for ID Cache List */ +/****s* silccore/SilcIDCacheAPI/SilcIDCacheList + * + * NAME + * + * typedef struct SilcIDCacheListStruct *SilcIDCacheList; + * + * DESCRIPTION + * + * This context is the ID Cache List and is allocated by + * some of the silc_idcache_* functions. Functions that may return + * multiple entries from the cache allocate the entries in to the + * SilcIDCacheList. The context is freed by silc_idcache_list_free + * function. + * + ***/ typedef struct SilcIDCacheListStruct *SilcIDCacheList; -/* Destructor callback that is called when an cache entry expires or is - purged from the ID cache. The application must not free cache entry - because the library will do it automatically. The appliation, however, - is responsible of freeing any data in the entry. */ +/****f* silccore/SilcIDCacheAPI/SilcIDCacheDestructor + * + * SYNOPSIS + * + * typedef void (*SilcIDCacheDestructor)(SilcIDCache cache, + * SilcIDCacheEntry entry); + * + * DESCRIPTION + * + * Destructor callback that is called when an cache entry expires or is + * purged from the ID cache. The application must not free cache entry + * because the library will do it automatically. The appliation, however, + * is responsible of freeing any data in the entry. + * + ***/ typedef void (*SilcIDCacheDestructor)(SilcIDCache cache, SilcIDCacheEntry entry); -#define SILC_ID_CACHE_ANY ((void *)1) - #define SILC_ID_CACHE_EXPIRE 3600 #define SILC_ID_CACHE_EXPIRE_DEF (time(NULL) + SILC_ID_CACHE_EXPIRE) /* Prototypes */ + +/****f* silccore/SilcIDCacheAPI/silc_idcache_alloc + * + * SYNOPSIS + * + * SilcIDCache silc_idcache_alloc(uint32 count, SilcIdType id_type, + * SilcIDCacheDestructor destructor); + * + * DESCRIPTION + * + * Allocates new ID cache object. The initial amount of allocated entries + * can be sent as argument. If `count' is 0 the system uses default values. + * The `id_type' defines the types of the ID's that will be saved to the + * cache. + * + ***/ SilcIDCache silc_idcache_alloc(uint32 count, SilcIdType id_type, SilcIDCacheDestructor destructor); + +/****f* silccore/SilcIDCacheAPI/silc_idcache_free + * + * SYNOPSIS + * + * void silc_idcache_free(SilcIDCache cache); + * + * DESCRIPTION + * + * Frees ID cache object and all cache entries. + * + ***/ void silc_idcache_free(SilcIDCache cache); + +/****f* silccore/SilcIDCacheAPI/silc_idcache_add + * + * SYNOPSIS + * + * bool silc_idcache_add(SilcIDCache cache, char *name, void *id, + * void *context, int expire); + * + * DESCRIPTION + * + * Add new entry to the cache. Returns TRUE if the entry was added and + * FALSE if it could not be added. The `name' is the name associated with + * the ID, the `id' the actual ID and the `context' a used specific context. + * If the `expire' is TRUE the entry expires in default time and if FALSE + * the entry never expires from the cache. + * + ***/ bool silc_idcache_add(SilcIDCache cache, char *name, void *id, void *context, int expire); + +/****f* silccore/SilcIDCacheAPI/silc_idcache_del + * + * SYNOPSIS + * + * bool silc_idcache_del(SilcIDCache cache, SilcIDCacheEntry old); + * + * DESCRIPTION + * + * Delete cache entry from cache. Returns TRUE if the entry was deleted. + * The destructor function is not called. + * + ***/ bool silc_idcache_del(SilcIDCache cache, SilcIDCacheEntry old); + +/****f* silccore/SilcIDCacheAPI/silc_idcache_del_by_id + * + * SYNOPSIS + * + * bool silc_idcache_del_by_id(SilcIDCache cache, void *id); + * + * DESCRIPTION + * + * Delete cache entry by ID. Returns TRUE if the entry was deleted. + * The destructor function is not called. + * + ***/ bool silc_idcache_del_by_id(SilcIDCache cache, void *id); + +/****f* silccore/SilcIDCacheAPI/silc_idcache_del_by_id_ext + * + * SYNOPSIS + * + * bool silc_idcache_del_by_id_ext(SilcIDCache cache, void *id, + * SilcHashFunction hash, + * void *hash_context, + * SilcHashCompare compare, + * void *compare_context); + * + * DESCRIPTION + * + * Same as silc_idcache_del_by_id but with specific hash and comparison + * functions. If the functions are NULL then default values are used. + * Returns TRUE if the entry was deleted. The destructor function is + * not called. + * + ***/ bool silc_idcache_del_by_id_ext(SilcIDCache cache, void *id, SilcHashFunction hash, void *hash_context, SilcHashCompare compare, void *compare_context); + +/****f* silccore/SilcIDCacheAPI/silc_idcache_del_by_context + * + * SYNOPSIS + * + * bool silc_idcache_del_by_context(SilcIDCache cache, void *context); + * + * DESCRIPTION + * + * Deletes cachen entry by the user specified context. Returns TRUE + * if the entry was deleted. The destructor function is not called. + * + ***/ bool silc_idcache_del_by_context(SilcIDCache cache, void *context); + +/****f* silccore/SilcIDCacheAPI/silc_idcache_del_all + * + * SYNOPSIS + * + * bool silc_idcache_del_all(SilcIDCache cache); + * + * DESCRIPTION + * + * Deletes all cache entries from the cache and frees all memory. + * The destructor function is not called. + * + ***/ bool silc_idcache_del_all(SilcIDCache cache); + +/****f* silccore/SilcIDCacheAPI/silc_idcache_purge + * + * SYNOPSIS + * + * bool silc_idcache_purge(SilcIDCache cache); + * + * DESCRIPTION + * + * Purges the cache by removing expired cache entires. Note that this + * may be very slow operation. Returns TRUE if the purging was successful. + * The destructor function is called for each purged cache entry. + * + ***/ bool silc_idcache_purge(SilcIDCache cache); + +/****f* silccore/SilcIDCacheAPI/silc_idcache_by_context + * + * SYNOPSIS + * + * bool silc_idcache_purge_by_context(SilcIDCache cache, void *context); + * + * DESCRIPTION + * + * Purges the cache by context and removes expired cache entires. + * Returns TRUE if the puring was successful. The destructor function + * is called for the purged cache entry. + * + ***/ bool silc_idcache_purge_by_context(SilcIDCache cache, void *context); + +/****f* silccore/SilcIDCacheAPI/silc_idcache_get_all + * + * SYNOPSIS + * + * bool silc_idcache_get_all(SilcIDCache cache, SilcIDCacheList *ret); + * + * DESCRIPTION + * + * Returns all cache entries from the ID cache to the `ret' SilcIDCacheList. + * Returns TRUE if the retrieval was successful. The caller must free + * the returned SilcIDCacheList. + * + ***/ bool silc_idcache_get_all(SilcIDCache cache, SilcIDCacheList *ret); + +/****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_id + * + * SYNOPSIS + * + * bool silc_idcache_find_by_id(SilcIDCache cache, void *id, + * SilcIDCacheList *ret); + * + * DESCRIPTION + * + * Find ID Cache entry by ID. This may return multiple entry and the + * `ret' SilcIDCacheList is allocated. Returns TRUE if the entry was + * found. The caller must free the returned SilcIDCacheList. + * + ***/ bool silc_idcache_find_by_id(SilcIDCache cache, void *id, SilcIDCacheList *ret); + +/****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_id_one + * + * SYNOPSIS + * + * bool silc_idcache_find_by_id_one(SilcIDCache cache, void *id, + * SilcIDCacheEntry *ret); + * + * DESCRIPTION + * + * Find ID Cache entry by ID. Returns only one entry from the cache + * and the found entry is considered to be exact match. Returns TRUE + * if the entry was found. + * + ***/ bool silc_idcache_find_by_id_one(SilcIDCache cache, void *id, SilcIDCacheEntry *ret); + +/****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_id_one_ext + * + * SYNOPSIS + * + * bool silc_idcache_find_by_id_one_ext(SilcIDCache cache, void *id, + * SilcHashFunction hash, + * void *hash_context, + * SilcHashCompare compare, + * void *compare_context, + * SilcIDCacheEntry *ret); + * + * DESCRIPTION + * + * Same as silc_idcache_find_by_id_one but with specific hash and + * comparison functions. If `hash' is NULL then the default hash + * funtion is used and if `compare' is NULL default comparison function + * is used. Returns TRUE if the entry was found. + * + ***/ bool silc_idcache_find_by_id_one_ext(SilcIDCache cache, void *id, SilcHashFunction hash, void *hash_context, SilcHashCompare compare, void *compare_context, SilcIDCacheEntry *ret); + +/****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_context + * + * SYNOPSIS + * + * bool silc_idcache_find_by_context(SilcIDCache cache, void *context, + * SilcIDCacheEntry *ret); + * + * DESCRIPTION + * + * Find cache entry by user specified context. Returns TRUE if the + * entry was found. + * + ***/ bool silc_idcache_find_by_context(SilcIDCache cache, void *context, SilcIDCacheEntry *ret); + +/****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_name + * + * SYNOPSIS + * + * bool silc_idcache_find_by_name(SilcIDCache cache, char *name, + * SilcIDCacheList *ret); + * + * DESCRIPTION + * + * Find cache entries by the name associated with the ID. This may + * return muliptle entries allocated to the SilcIDCacheList. Returns + * TRUE if the entry was found. The caller must free the SIlcIDCacheList. + * + ***/ bool silc_idcache_find_by_name(SilcIDCache cache, char *name, SilcIDCacheList *ret); + +/****f* silccore/SilcIDCacheAPI/silc_idcache_find_by_name_one + * + * SYNOPSIS + * + * bool silc_idcache_find_by_name_one(SilcIDCache cache, char *name, + * SilcIDCacheEntry *ret); + * + * DESCRIPTION + * + * Find cache entry by the name associated with the ID. This returns + * one entry and the found entry is considered to be exact match. + * return muliptle entries allocated to the SilcIDCacheList. Returns + * TRUE if the entry was found. + * + ***/ bool silc_idcache_find_by_name_one(SilcIDCache cache, char *name, SilcIDCacheEntry *ret); + +/****f* silccore/SilcIDCacheAPI/silc_idcache_list_count + * + * SYNOPSIS + * + * int silc_idcache_list_count(SilcIDCacheList list); + * + * DESCRIPTION + * + * Returns the number of cache entries in the ID cache list. + * + ***/ int silc_idcache_list_count(SilcIDCacheList list); + +/****f* silccore/SilcIDCacheAPI/silc_idcache_list_first + * + * SYNOPSIS + * + * bool silc_idcache_list_first(SilcIDCacheList list, + * SilcIDCacheEntry *ret); + * + * DESCRIPTION + * + * Returns the first cache entry from the ID cache list. Returns FALSE + * If the entry could not be retrieved. + * + ***/ bool silc_idcache_list_first(SilcIDCacheList list, SilcIDCacheEntry *ret); + +/****f* silccore/SilcIDCacheAPI/silc_idcache_list_next + * + * SYNOPSIS + * + * bool silc_idcache_list_next(SilcIDCacheList list, SilcIDCacheEntry *ret); + * + * DESCRIPTION + * + * Returns the next cache entry from the ID Cache list. Returns FALSE + * when there are not anymore entries in the list. + * + ***/ bool silc_idcache_list_next(SilcIDCacheList list, SilcIDCacheEntry *ret); + +/****f* silccore/SilcIDCacheAPI/silc_idcache_list_free + * + * SYNOPSIS + * + * void silc_idcache_list_free(SilcIDCacheList list); + * + * DESCRIPTION + * + * Frees ID cache list. User must free the list context returned by + * any of the searching functions. + * + ***/ void silc_idcache_list_free(SilcIDCacheList list); #endif