lib/silccore/silcchannel.h

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