+Sat Jun 2 10:45:09 EEST 2001 Pekka Riikonen <priikone@poseidon.pspt.fi>
+
+ * 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 <priikone@poseidon.pspt.fi>
* Added checking to the server code not to start the server if
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;
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)
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);
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);
}
}
*
* NAME
*
- * SilcKeyAgreementStatus
+ * typedef enum { ... } SilcKeyAgreementStatus;
*
* DESCRIPTION
*
*
* NAME
*
- * SilcPrivateMessageKeys
+ * typedef struct { ... } SilcPrivateMessageKeys;
*
* DESCRIPTION
*
*
* NAME
*
- * SilcClientOperations
+ * typedef struct { ... } SilcClientOperations;
*
* DESCRIPTION
*
*
* 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);
return buffer;
}
-/* Free's Channel Payload */
+/* Frees Channel Payload */
void silc_channel_payload_free(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;
/* Return flags */
-uint16
+SilcMessageFlags
silc_channel_message_get_flags(SilcChannelMessagePayload payload)
{
return payload->flags;
return buffer;
}
-/* Free's Channel Key Payload */
+/* Frees Channel Key Payload */
void silc_channel_key_payload_free(SilcChannelKeyPayload payload)
{
-/*
-
- silcchannel.h
-
- Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
-
- 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 <priikone@poseidon.pspt.fi>
+ *
+ * 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) */
#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,
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);
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);
-/*
-
- silccommand.h
-
- Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
-
- 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 <priikone@poseidon.pspt.fi>
+ *
+ * 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,
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
/* 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 */
#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
-/*
+/****h* silccore/silcid.h
+ *
+ * NAME
+ *
+ * silcid.h
+ *
+ * COPYRIGHT
+ *
+ * Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
+ *
+ * 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 <priikone@poseidon.pspt.fi>
-
- 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. */
#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
return cache;
}
-/* Free's ID cache object and cache entries */
+/* Frees ID cache object and cache entries */
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)
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)
-/*
+/****h* silccore/silcidcache.h
+ *
+ * NAME
+ *
+ * silcidcache.h
+ *
+ * COPYRIGHT
+ *
+ * Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
+ *
+ * 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 <priikone@poseidon.pspt.fi>
-
- 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
projects / silc.git / commitdiff