lib/silccore/silcpayload.h

   1 /*
   2
   3   silcpayload.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2000 - 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/SilcGenericPayloadAPI
  22  *
  23  * DESCRIPTION
  24  *
  25  * Implementation of the generic payloads described in the protocol
  26  * specification; ID Payload and Argument Payload. The ID Payload is
  27  * used to represent an ID. The Argument Payload is used to include
  28  * arguments to other payloads that needs arguments.
  29  *
  30  ***/
  31
  32 #ifndef SILCPAYLOAD_H
  33 #define SILCPAYLOAD_H
  34
  35 /****s* silccore/SilcGenericPayloadAPI/SilcIDPayload
  36  *
  37  * NAME
  38  *
  39  *    typedef struct SilcIDPayloadStruct *SilcIDPayload;
  40  *
  41  * DESCRIPTION
  42  *
  43  *    This context is the actual ID Payload and is allocated by
  44  *    silc_id_payload_parse and given as argument usually to all
  45  *    silc_id_payload_* functions.  It is freed by the function
  46  *    silc_id_payload_free.
  47  *
  48  ***/
  49 typedef struct SilcIDPayloadStruct *SilcIDPayload;
  50
  51 /****s* silccore/SilcGenericPayloadAPI/SilcArgumentPayload
  52  *
  53  * NAME
  54  *
  55  *    typedef struct SilcArgumentPayloadStruct *SilcArgumentPayload;
  56  *
  57  * DESCRIPTION
  58  *
  59  *    This context is the actual Argument Payload and is allocated
  60  *    by silc_argument_payload_parse and given as argument usually to
  61  *    all silc_argument_payload_* functions.  It is freed by the
  62  *    silc_argument_payload_free function.
  63  *
  64  ***/
  65 typedef struct SilcArgumentPayloadStruct *SilcArgumentPayload;
  66
  67 /* Prototypes */
  68
  69 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_parse
  70  *
  71  * SYNOPSIS
  72  *
  73  *    SilcIDPayload silc_id_payload_parse(SilcBuffer buffer);
  74  *
  75  * DESCRIPTION
  76  *
  77  *    Parses buffer and return ID payload into payload structure. The
  78  *    `buffer' is raw payload buffer.
  79  *
  80  ***/
  81 SilcIDPayload silc_id_payload_parse(SilcBuffer buffer);
  82
  83 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_parse_data
  84  *
  85  * SYNOPSIS
  86  *
  87  *    SilcIDPayload silc_id_payload_parse_data(unsigned char *data,
  88  *                                             uint32 len);
  89  *
  90  * DESCRIPTION
  91  *
  92  *    Parses buffer and return ID payload into payload structure. The
  93  *    `data' and `len' are the raw payload buffer. This is equivalent
  94  *    to the silc_id_payload_parse function.
  95  *
  96  ***/
  97 SilcIDPayload silc_id_payload_parse_data(unsigned char *data,
  98                                          uint32 len);
  99
 100 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_parse_id
 101  *
 102  * SYNOPSIS
 103  *
 104  *    void *silc_id_payload_parse_id(unsigned char *data, uint32 len);
 105  *
 106  * DESCRIPTION
 107  *
 108  *    Return ID directly from the raw ID Payload data buffer. The
 109  *    caller must free the returned ID.
 110  *
 111  ***/
 112 void *silc_id_payload_parse_id(unsigned char *data, uint32 len);
 113
 114 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_encode
 115  *
 116  * SYNOPSIS
 117  *
 118  *    SilcBuffer silc_id_payload_encode(void *id, SilcIdType type);
 119  *
 120  * DESCRIPTION
 121  *
 122  *    Encodes ID Payload. The `id' is the ID of the type `type' to put
 123  *    into the payload. Returns the encoded payload buffer.
 124  *
 125  ***/
 126 SilcBuffer silc_id_payload_encode(void *id, SilcIdType type);
 127
 128 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_encode_data
 129  *
 130  * SYNOPSIS
 131  *
 132  *    SilcBuffer silc_id_payload_encode_data(const unsigned char *id,
 133  *                                           uin32 id_len, SilcIdType type);
 134  *
 135  * DESCRIPTION
 136  *
 137  *    Encodes ID Payload. The `id' is raw ID data of the length of `id_len'
 138  *    of type of `type'. Returns the encoded payload buffer.
 139  *
 140  ***/
 141 SilcBuffer silc_id_payload_encode_data(const unsigned char *id,
 142                                        uint32 id_len, SilcIdType type);
 143
 144 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_free
 145  *
 146  * SYNOPSIS
 147  *
 148  *    void silc_id_payload_free(SilcIDPayload payload);
 149  *
 150  * DESCRIPTION
 151  *
 152  *    Frees the ID Payload and all data in it.
 153  *
 154  ***/
 155 void silc_id_payload_free(SilcIDPayload payload);
 156
 157 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_get_type
 158  *
 159  * SYNOPSIS
 160  *
 161  *    SilcIdType silc_id_payload_get_type(SilcIDPayload payload);
 162  *
 163  * DESCRIPTION
 164  *
 165  *    Returns the ID type from the ID Payload. The type tells the
 166  *    type of the ID in the payload.
 167  *
 168  ***/
 169 SilcIdType silc_id_payload_get_type(SilcIDPayload payload);
 170
 171 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_get_id
 172  *
 173  * SYNOPSIS
 174  *
 175  *    void *silc_id_payload_get_id(SilcIDPayload payload);
 176  *
 177  * DESCRIPTION
 178  *
 179  *    Returns the ID in the ID Payload. The caller must free the
 180  *    returned ID.
 181  *
 182  ***/
 183 void *silc_id_payload_get_id(SilcIDPayload payload);
 184
 185 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_get_data
 186  *
 187  * SYNOPSIS
 188  *
 189  *    unsigned char *silc_id_payload_get_data(SilcIDPayload payload);
 190  *
 191  * DESCRIPTION
 192  *
 193  *    Returns the raw ID data from the ID Payload. The data is duplicated
 194  *    and the caller must free it.
 195  *
 196  ***/
 197 unsigned char *silc_id_payload_get_data(SilcIDPayload payload);
 198
 199 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_get_len
 200  *
 201  * SYNOPSIS
 202  *
 203  *    uint32 silc_id_payload_get_len(SilcIDPayload payload);
 204  *
 205  * DESCRIPTION
 206  *
 207  *    Returns the length of the ID in the ID Payload.
 208  *
 209  ***/
 210 uint32 silc_id_payload_get_len(SilcIDPayload payload);
 211
 212 /****f* silccore/SilcGenericPayloadAPI/silc_argument_payload_parse
 213  *
 214  * SYNOPSIS
 215  *
 216  *    SilcArgumentPayload silc_argument_payload_parse(SilcBuffer buffer,
 217  *                                                    uint32 argc);
 218  *
 219  * DESCRIPTION
 220  *
 221  *    Parses arguments and returns them into Argument Payload structure.
 222  *    the `buffer' is raw Argument Payload data buffer. The `argc' is
 223  *    the number of arguments in the Argument Payload. The caller must
 224  *    know the number of the arguments. This is always known as the
 225  *    Argument payload is associated with other payloads which defines
 226  *    the number of the arguments.
 227  *
 228  ***/
 229 SilcArgumentPayload silc_argument_payload_parse(SilcBuffer buffer,
 230                                                 uint32 argc);
 231
 232 /****f* silccore/SilcGenericPayloadAPI/silc_argument_payload_encode
 233  *
 234  * SYNOPSIS
 235  *
 236  *    SilcBuffer silc_argument_payload_encode(uint32 argc,
 237  *                                            unsigned char **argv,
 238  *                                            uint32 *argv_lens,
 239  *                                            uint32 *argv_types);
 240  *
 241  * DESCRIPTION
 242  *
 243  *    Encodes arguments in to Argument Paylods returning them to SilcBuffer.
 244  *    The `argv' is the array of the arguments, the `argv_lens' array of
 245  *    the length of the `argv' arguments and the `argv_types' array of
 246  *    the argument types of the `argv' arguments. The `argc' is the
 247  *    number of arguments.
 248  *
 249  ***/
 250 SilcBuffer silc_argument_payload_encode(uint32 argc,
 251                                         unsigned char **argv,
 252                                         uint32 *argv_lens,
 253                                         uint32 *argv_types);
 254
 255 /****f* silccore/SilcGenericPayloadAPI/silc_argument_payload_encode_payload
 256  *
 257  * SYNOPSIS
 258  *
 259  *    SilcBuffer
 260  *    silc_argument_payload_encode_payload(SilcArgumentPayload payload);
 261  *
 262  * DESCRIPTION
 263  *
 264  *    Same as silc_argument_payload_encode but encodes the payload from
 265  *    already allocated SilcArgumentPayload structure instead of raw data.
 266  *
 267  ***/
 268 SilcBuffer silc_argument_payload_encode_payload(SilcArgumentPayload payload);
 269
 270 /****f* silccore/SilcGenericPayloadAPI/silc_argument_payload_free
 271  *
 272  * SYNOPSIS
 273  *
 274  *    void silc_argument_payload_free(SilcArgumentPayload payload);
 275  *
 276  * DESCRIPTION
 277  *
 278  *    Frees the Argument Payload and all data in it.
 279  *
 280  ***/
 281 void silc_argument_payload_free(SilcArgumentPayload payload);
 282
 283 /****f* silccore/SilcGenericPayloadAPI/silc_argument_get_arg_num
 284  *
 285  * SYNOPSIS
 286  *
 287  *    uint32 silc_argument_get_arg_num(SilcArgumentPayload payload);
 288  *
 289  * DESCRIPTION
 290  *
 291  *    Returns the number of argument in the Argument Payload.
 292  *
 293  ***/
 294 uint32 silc_argument_get_arg_num(SilcArgumentPayload payload);
 295
 296 /****f* silccore/SilcGenericPayloadAPI/silc_argument_get_first_arg
 297  *
 298  * SYNOPSIS
 299  *
 300  *    unsigned char *silc_argument_get_first_arg(SilcArgumentPayload payload,
 301  *                                               uint32 *ret_len);
 302  *
 303  * DESCRIPTION
 304  *
 305  *    Returns the first argument in the Argument Payload. The lenght
 306  *    of the argument is returned to `ret_len'. The caller must not
 307  *    free the returned argument. Returns NULL on error.
 308  *
 309  ***/
 310 unsigned char *silc_argument_get_first_arg(SilcArgumentPayload payload,
 311                                            uint32 *ret_len);
 312
 313 /****f* silccore/SilcGenericPayloadAPI/silc_argument_get_next_arg
 314  *
 315  * SYNOPSIS
 316  *
 317  *    unsigned char *silc_argument_get_next_arg(SilcArgumentPayload payload,
 318  *                                              uint32 *ret_len);
 319  *
 320  * DESCRIPTION
 321  *
 322  *    Returns next argument from the Argument Payload. The length of
 323  *    the argument is returned to `ret_len'. The caller must not free
 324  *    the returned argument. This returns NULL when there are no more
 325  *    arguments in the payload.
 326  *
 327  ***/
 328 unsigned char *silc_argument_get_next_arg(SilcArgumentPayload payload,
 329                                           uint32 *ret_len);
 330
 331 /****f* silccore/SilcGenericPayloadAPI/silc_argument_get_arg_type
 332  *
 333  * SYNOPSIS
 334  *
 335  *    unsigned char *silc_argument_get_arg_type(SilcArgumentPayload payload,
 336  *                                              uint32 type,
 337  *                                              uint32 *ret_len);
 338  *
 339  * DESCRIPTION
 340  *
 341  *    Returns argument by type. The returned argument has type `type'
 342  *    in the Argument Payload. Each argument has their own type (or zero
 343  *    if no specific type is set). The length of the argument is returned
 344  *    to the `ret_len'. The caller must not free the returned argument.
 345  *    Returns NULL on error.
 346  *
 347  ***/
 348 unsigned char *silc_argument_get_arg_type(SilcArgumentPayload payload,
 349                                           uint32 type,
 350                                           uint32 *ret_len);
 351
 352 #endif