lib/silccore/silcchannel.h

   1 /*
   2
   3   silcchannel.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 - 2001 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; either version 2 of the License, or
  12   (at your option) any later version.
  13
  14   This program is distributed in the hope that it will be useful,
  15   but WITHOUT ANY WARRANTY; without even the implied warranty of
  16   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17   GNU General Public License for more details.
  18
  19 */
  20
  21 /****h* silccore/SILC Channel Interface
  22  *
  23  * DESCRIPTION
  24  *
  25  * Implementations of the Channel Payload and Channel Key Payload.  The
  26  * Channel Payload represents new channel and is used to distribute the
  27  * information of the new channel.  The Channel Key Payload is used to
  28  * distribute a new key to the channel.  It is done for example every
  29  * time someone joins a channel or the old key expires.
  30  *
  31  ***/
  32
  33 #ifndef SILCCHANNEL_H
  34 #define SILCCHANNEL_H
  35
  36 #include "silcdlist.h"
  37
  38 /****s* silccore/SilcChannelAPI/SilcChannelPayload
  39  *
  40  * NAME
  41  *
  42  *    typedef struct SilcChannelPayloadStruct *SilcChannelPayload;
  43  *
  44  * DESCRIPTION
  45  *
  46  *    This context is the actual Channel Payload and is allocated
  47  *    by silc_channel_payload_parse and given as argument usually to
  48  *    all silc_channel_payload_* functions.  It is freed by the
  49  *    silc_channel_payload_free function.
  50  *
  51  ***/
  52 typedef struct SilcChannelPayloadStruct *SilcChannelPayload;
  53
  54 /****s* silccore/SilcChannelAPI/SilcChannelKeyPayload
  55  *
  56  * NAME
  57  *
  58  *    typedef struct SilcChannelKeyPayloadStruct *SilcChannelKeyPayload;
  59  *
  60  * DESCRIPTION
  61  *
  62  *    This context is the actual Channel Key Payload and is allocated
  63  *    by silc_channel_key_payload_parse and given as argument usually to
  64  *    all silc_channel_key_payload_* functions.  It is freed by the
  65  *    silc_channel_key_payload_free function.
  66  *
  67  ***/
  68 typedef struct SilcChannelKeyPayloadStruct *SilcChannelKeyPayload;
  69
  70 /* Prototypes */
  71
  72 /****f* silccore/SilcChannelAPI/silc_channel_payload_parse
  73  *
  74  * SYNOPSIS
  75  *
  76  *    SilcChannelPayload
  77  *    silc_channel_payload_parse(const unsigned char *payload,
  78  *                               SilcUInt32 payload_len);
  79  *
  80  * DESCRIPTION
  81  *
  82  *    Parses channel payload returning new channel payload structure. The
  83  *    `buffer' is the raw payload buffer.
  84  *
  85  ***/
  86 SilcChannelPayload silc_channel_payload_parse(const unsigned char *payload,
  87                                               SilcUInt32 payload_len);
  88
  89 /****f* silccore/SilcChannelAPI/silc_channel_payload_parse_list
  90  *
  91  * SYNOPSIS
  92  *
  93  *    SilcDList
  94  *    silc_channel_payload_parse_list(const unsigned char *payload,
  95  *                                    SilcUInt32 payload_len);
  96  *
  97  * DESCRIPTION
  98  *
  99  *    Parses list of channel payloads returning list of payloads. This
 100  *    is equivalent to the silc_channel_payload_parse except that the `buffer'
 101  *    now includes multiple Channel Payloads one after the other.
 102  *
 103  ***/
 104 SilcDList silc_channel_payload_parse_list(const unsigned char *payload,
 105                                           SilcUInt32 payload_len);
 106
 107 /****f* silccore/SilcChannelAPI/silc_channel_payload_encode
 108  *
 109  * SYNOPSIS
 110  *
 111  *    SilcBuffer silc_channel_payload_encode(const unsigned char *channel_name,
 112  *                                           SilcUInt16 channel_name_len,
 113  *                                           const unsigned char *channel_id,
 114  *                                           SilcUInt32 channel_id_len,
 115  *                                           SilcUInt32 mode);
 116  *
 117  * DESCRIPTION
 118  *
 119  *    Encode new channel payload and returns it as buffer.
 120  *
 121  ***/
 122 SilcBuffer silc_channel_payload_encode(const unsigned char *channel_name,
 123                                        SilcUInt16 channel_name_len,
 124                                        const unsigned char *channel_id,
 125                                        SilcUInt32 channel_id_len,
 126                                        SilcUInt32 mode);
 127
 128 /****f* silccore/SilcChannelAPI/silc_channel_payload_free
 129  *
 130  * SYNOPSIS
 131  *
 132  *    void silc_channel_payload_free(SilcChannelPayload payload);
 133  *
 134  * DESCRIPTION
 135  *
 136  *    Frees Channel Payload and all data in it.
 137  *
 138  ***/
 139 void silc_channel_payload_free(SilcChannelPayload payload);
 140
 141 /****f* silccore/SilcChannelAPI/silc_channel_payload_list_free
 142  *
 143  * SYNOPSIS
 144  *
 145  *    void silc_channel_payload_list_free(SilcDList list);
 146  *
 147  * DESCRIPTION
 148  *
 149  *    Frees list of Channel Payloads and all data in them.
 150  *
 151  ***/
 152 void silc_channel_payload_list_free(SilcDList list);
 153
 154 /****f* silccore/SilcChannelAPI/silc_channel_get_name
 155  *
 156  * SYNOPSIS
 157  *
 158  *    unsigned char *silc_channel_get_name(SilcChannelPayload payload,
 159  *                                         SilcUInt32 *channel_name_len);
 160  *
 161  * DESCRIPTION
 162  *
 163  *    Return the channel name from the payload. The caller must not free it.
 164  *
 165  ***/
 166 unsigned char *silc_channel_get_name(SilcChannelPayload payload,
 167                                      SilcUInt32 *channel_name_len);
 168
 169 /****f* silccore/SilcChannelAPI/silc_channel_get_id
 170  *
 171  * SYNOPSIS
 172  *
 173  *    unsigned char *silc_channel_get_id(SilcChannelPayload payload,
 174  *                                       SilcUInt32 *channel_id_len);
 175  *
 176  * DESCRIPTION
 177  *
 178  *    Return the Channel ID data from the payload. The caller must not free it.
 179  *
 180  ***/
 181 unsigned char *silc_channel_get_id(SilcChannelPayload payload,
 182                                    SilcUInt32 *channel_id_len);
 183
 184 /****f* silccore/SilcChannelAPI/silc_channel_get_id_parse
 185  *
 186  * SYNOPSIS
 187  *
 188  *    SilcChannelID *silc_channel_get_id_parse(SilcChannelPayload payload);
 189  *
 190  * DESCRIPTION
 191  *
 192  *    Return the Channel ID as parsed ID. This is equivalent to the
 193  *    silc_channel_get_id execpt that the ID is already parsed. The caller
 194  *    must free the parsed Channel ID.
 195  *
 196  ***/
 197 SilcChannelID *silc_channel_get_id_parse(SilcChannelPayload payload);
 198
 199 /****f* silccore/SilcChannelAPI/silc_channel_get_mode
 200  *
 201  * SYNOPSIS
 202  *
 203  *    SilcUInt32 silc_channel_get_mode(SilcChannelPayload payload);
 204  *
 205  * DESCRIPTION
 206  *
 207  *    Return the mode. The mode is arbitrary. It can be the mode of the
 208  *    channel or perhaps the mode of the client on the channel.  The protocol
 209  *    dictates what the usage of the mode is in different circumstances.
 210  *
 211  ***/
 212 SilcUInt32 silc_channel_get_mode(SilcChannelPayload payload);
 213
 214 /****f* silccore/SilcChannelAPI/silc_channel_key_payload_parse
 215  *
 216  * SYNOPSIS
 217  *
 218  *    SilcChannelKeyPayload
 219  *    silc_channel_key_payload_parse(const unsigned char *payload,
 220  *                                   uin32 payload_len);
 221  *
 222  * DESCRIPTION
 223  *
 224  *     Parses channel key payload returning new channel key payload
 225  *     structure.
 226  *
 227  ***/
 228 SilcChannelKeyPayload
 229 silc_channel_key_payload_parse(const unsigned char *payload,
 230                                SilcUInt32 payload_len);
 231
 232 /****f* silccore/SilcChannelAPI/silc_channel_key_payload_encode
 233  *
 234  * SYNOPSIS
 235  *
 236  *    SilcBuffer silc_channel_key_payload_encode(SilcUInt16 id_len,
 237  *                                               const unsigned char *id,
 238  *                                               SilcUInt16 cipher_len,
 239  *                                               const unsigned char *cipher,
 240  *                                               SilcUInt16 key_len,
 241  *                                               const unsigned char *key);
 242  *
 243  * DESCRIPTION
 244  *
 245  *    Encodes channel key payload into a buffer and returns it. This is used
 246  *    to add channel key payload into a packet.
 247  *
 248  ***/
 249 SilcBuffer silc_channel_key_payload_encode(SilcUInt16 id_len,
 250                                            const unsigned char *id,
 251                                            SilcUInt16 cipher_len,
 252                                            const unsigned char *cipher,
 253                                            SilcUInt16 key_len,
 254                                            const unsigned char *key);
 255
 256 /****f* silccore/SilcChannelAPI/silc_channel_key_payload_free
 257  *
 258  * SYNOPSIS
 259  *
 260  *    void silc_channel_key_payload_free(SilcChannelKeyPayload payload);
 261  *
 262  * DESCRIPTION
 263  *
 264  *    Frees the Channel Key Payload and all data in it.
 265  *
 266  ***/
 267 void silc_channel_key_payload_free(SilcChannelKeyPayload payload);
 268
 269 /****f* silccore/SilcChannelAPI/silc_channel_key_get_id
 270  *
 271  * SYNOPSIS
 272  *
 273  *    unsigned char *silc_channel_key_get_id(SilcChannelKeyPayload payload,
 274  *                                           SilcUInt32 *id_len);
 275  *
 276  * DESCRIPTION
 277  *
 278  *    Return the Channel ID data from the payload. The caller must not
 279  *    free it.
 280  *
 281  ***/
 282 unsigned char *silc_channel_key_get_id(SilcChannelKeyPayload payload,
 283                                        SilcUInt32 *id_len);
 284
 285 /****f* silccore/SilcChannelAPI/silc_channel_key_get_cipher
 286  *
 287  * SYNOPSIS
 288  *
 289  *    unsigned char *silc_channel_key_get_cipher(SilcChannelKeyPayload payload,
 290  *                                               SilcUInt32 *cipher_len);
 291  *
 292  * DESCRIPTION
 293  *
 294  *    Return the name of the cipher from the payload. The caller must not
 295  *    free it.
 296  *
 297  ***/
 298 unsigned char *silc_channel_key_get_cipher(SilcChannelKeyPayload payload,
 299                                            SilcUInt32 *cipher_len);
 300
 301 /****f* silccore/SilcChannelAPI/silc_channel_key_get_key
 302  *
 303  * SYNOPSIS
 304  *
 305  *    unsigned char *silc_channel_key_get_key(SilcChannelKeyPayload payload,
 306  *                                            SilcUInt32 *key_len);
 307  *
 308  * DESCRIPTION
 309  *
 310  *    Return the raw key material from the payload. The caller must not
 311  *    free it.
 312  *
 313  ***/
 314 unsigned char *silc_channel_key_get_key(SilcChannelKeyPayload payload,
 315                                         SilcUInt32 *key_len);
 316
 317 #endif