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(const unsigned char *payload,
  74  *                                        uint32 payload_len);
  75  *
  76  * DESCRIPTION
  77  *
  78  *    Parses buffer and return ID payload into payload structure. The
  79  *    `buffer' is raw payload buffer.
  80  *
  81  ***/
  82 SilcIDPayload silc_id_payload_parse(const unsigned char *payload,
  83                                     uint32 payload_len);
  84
  85 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_parse_id
  86  *
  87  * SYNOPSIS
  88  *
  89  *    void *silc_id_payload_parse_id(const unsigned char *data, uint32 len);
  90  *
  91  * DESCRIPTION
  92  *
  93  *    Return ID directly from the raw ID Payload data buffer. The
  94  *    caller must free the returned ID.
  95  *
  96  ***/
  97 void *silc_id_payload_parse_id(const unsigned char *data, uint32 len);
  98
  99 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_encode
 100  *
 101  * SYNOPSIS
 102  *
 103  *    SilcBuffer silc_id_payload_encode(const void *id, SilcIdType type);
 104  *
 105  * DESCRIPTION
 106  *
 107  *    Encodes ID Payload. The `id' is the ID of the type `type' to put
 108  *    into the payload. Returns the encoded payload buffer.
 109  *
 110  ***/
 111 SilcBuffer silc_id_payload_encode(const void *id, SilcIdType type);
 112
 113 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_encode_data
 114  *
 115  * SYNOPSIS
 116  *
 117  *    SilcBuffer silc_id_payload_encode_data(const unsigned char *id,
 118  *                                           uin32 id_len, SilcIdType type);
 119  *
 120  * DESCRIPTION
 121  *
 122  *    Encodes ID Payload. The `id' is raw ID data of the length of `id_len'
 123  *    of type of `type'. Returns the encoded payload buffer.
 124  *
 125  ***/
 126 SilcBuffer silc_id_payload_encode_data(const unsigned char *id,
 127                                        uint32 id_len, SilcIdType type);
 128
 129 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_free
 130  *
 131  * SYNOPSIS
 132  *
 133  *    void silc_id_payload_free(SilcIDPayload payload);
 134  *
 135  * DESCRIPTION
 136  *
 137  *    Frees the ID Payload and all data in it.
 138  *
 139  ***/
 140 void silc_id_payload_free(SilcIDPayload payload);
 141
 142 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_get_type
 143  *
 144  * SYNOPSIS
 145  *
 146  *    SilcIdType silc_id_payload_get_type(SilcIDPayload payload);
 147  *
 148  * DESCRIPTION
 149  *
 150  *    Returns the ID type from the ID Payload. The type tells the
 151  *    type of the ID in the payload.
 152  *
 153  ***/
 154 SilcIdType silc_id_payload_get_type(SilcIDPayload payload);
 155
 156 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_get_id
 157  *
 158  * SYNOPSIS
 159  *
 160  *    void *silc_id_payload_get_id(SilcIDPayload payload);
 161  *
 162  * DESCRIPTION
 163  *
 164  *    Returns the ID in the ID Payload. The caller must free the
 165  *    returned ID.
 166  *
 167  ***/
 168 void *silc_id_payload_get_id(SilcIDPayload payload);
 169
 170 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_get_data
 171  *
 172  * SYNOPSIS
 173  *
 174  *    unsigned char *silc_id_payload_get_data(SilcIDPayload payload);
 175  *
 176  * DESCRIPTION
 177  *
 178  *    Returns the raw ID data from the ID Payload. The data is duplicated
 179  *    and the caller must free it.
 180  *
 181  ***/
 182 unsigned char *silc_id_payload_get_data(SilcIDPayload payload);
 183
 184 /****f* silccore/SilcGenericPayloadAPI/silc_id_payload_get_len
 185  *
 186  * SYNOPSIS
 187  *
 188  *    uint32 silc_id_payload_get_len(SilcIDPayload payload);
 189  *
 190  * DESCRIPTION
 191  *
 192  *    Returns the length of the ID in the ID Payload.
 193  *
 194  ***/
 195 uint32 silc_id_payload_get_len(SilcIDPayload payload);
 196
 197 /****f* silccore/SilcGenericPayloadAPI/silc_argument_payload_parse
 198  *
 199  * SYNOPSIS
 200  *
 201  *    SilcArgumentPayload
 202  *    silc_argument_payload_parse(const unsigned char *payload,
 203  *                                uint32 payload_len,
 204  *                                uint32 argc);
 205  *
 206  * DESCRIPTION
 207  *
 208  *    Parses arguments and returns them into Argument Payload structure.
 209  *    the `buffer' is raw Argument Payload data buffer. The `argc' is
 210  *    the number of arguments in the Argument Payload. The caller must
 211  *    know the number of the arguments. This is always known as the
 212  *    Argument payload is associated with other payloads which defines
 213  *    the number of the arguments.
 214  *
 215  ***/
 216 SilcArgumentPayload silc_argument_payload_parse(const unsigned char *payload,
 217                                                 uint32 payload_len,
 218                                                 uint32 argc);
 219
 220 /****f* silccore/SilcGenericPayloadAPI/silc_argument_payload_encode
 221  *
 222  * SYNOPSIS
 223  *
 224  *    SilcBuffer silc_argument_payload_encode(uint32 argc,
 225  *                                            unsigned char **argv,
 226  *                                            uint32 *argv_lens,
 227  *                                            uint32 *argv_types);
 228  *
 229  * DESCRIPTION
 230  *
 231  *    Encodes arguments in to Argument Paylods returning them to SilcBuffer.
 232  *    The `argv' is the array of the arguments, the `argv_lens' array of
 233  *    the length of the `argv' arguments and the `argv_types' array of
 234  *    the argument types of the `argv' arguments. The `argc' is the
 235  *    number of arguments.
 236  *
 237  ***/
 238 SilcBuffer silc_argument_payload_encode(uint32 argc,
 239                                         unsigned char **argv,
 240                                         uint32 *argv_lens,
 241                                         uint32 *argv_types);
 242
 243 /****f* silccore/SilcGenericPayloadAPI/silc_argument_payload_encode_payload
 244  *
 245  * SYNOPSIS
 246  *
 247  *    SilcBuffer
 248  *    silc_argument_payload_encode_payload(SilcArgumentPayload payload);
 249  *
 250  * DESCRIPTION
 251  *
 252  *    Same as silc_argument_payload_encode but encodes the payload from
 253  *    already allocated SilcArgumentPayload structure instead of raw data.
 254  *
 255  ***/
 256 SilcBuffer silc_argument_payload_encode_payload(SilcArgumentPayload payload);
 257
 258 /****f* silccore/SilcGenericPayloadAPI/silc_argument_payload_free
 259  *
 260  * SYNOPSIS
 261  *
 262  *    void silc_argument_payload_free(SilcArgumentPayload payload);
 263  *
 264  * DESCRIPTION
 265  *
 266  *    Frees the Argument Payload and all data in it.
 267  *
 268  ***/
 269 void silc_argument_payload_free(SilcArgumentPayload payload);
 270
 271 /****f* silccore/SilcGenericPayloadAPI/silc_argument_get_arg_num
 272  *
 273  * SYNOPSIS
 274  *
 275  *    uint32 silc_argument_get_arg_num(SilcArgumentPayload payload);
 276  *
 277  * DESCRIPTION
 278  *
 279  *    Returns the number of argument in the Argument Payload.
 280  *
 281  ***/
 282 uint32 silc_argument_get_arg_num(SilcArgumentPayload payload);
 283
 284 /****f* silccore/SilcGenericPayloadAPI/silc_argument_get_first_arg
 285  *
 286  * SYNOPSIS
 287  *
 288  *    unsigned char *silc_argument_get_first_arg(SilcArgumentPayload payload,
 289  *                                               uint32 *ret_len);
 290  *
 291  * DESCRIPTION
 292  *
 293  *    Returns the first argument in the Argument Payload. The lenght
 294  *    of the argument is returned to `ret_len'. The caller must not
 295  *    free the returned argument. Returns NULL on error.
 296  *
 297  ***/
 298 unsigned char *silc_argument_get_first_arg(SilcArgumentPayload payload,
 299                                            uint32 *ret_len);
 300
 301 /****f* silccore/SilcGenericPayloadAPI/silc_argument_get_next_arg
 302  *
 303  * SYNOPSIS
 304  *
 305  *    unsigned char *silc_argument_get_next_arg(SilcArgumentPayload payload,
 306  *                                              uint32 *ret_len);
 307  *
 308  * DESCRIPTION
 309  *
 310  *    Returns next argument from the Argument Payload. The length of
 311  *    the argument is returned to `ret_len'. The caller must not free
 312  *    the returned argument. This returns NULL when there are no more
 313  *    arguments in the payload.
 314  *
 315  ***/
 316 unsigned char *silc_argument_get_next_arg(SilcArgumentPayload payload,
 317                                           uint32 *ret_len);
 318
 319 /****f* silccore/SilcGenericPayloadAPI/silc_argument_get_arg_type
 320  *
 321  * SYNOPSIS
 322  *
 323  *    unsigned char *silc_argument_get_arg_type(SilcArgumentPayload payload,
 324  *                                              uint32 type,
 325  *                                              uint32 *ret_len);
 326  *
 327  * DESCRIPTION
 328  *
 329  *    Returns argument by type. The returned argument has type `type'
 330  *    in the Argument Payload. Each argument has their own type (or zero
 331  *    if no specific type is set). The length of the argument is returned
 332  *    to the `ret_len'. The caller must not free the returned argument.
 333  *    Returns NULL on error.
 334  *
 335  ***/
 336 unsigned char *silc_argument_get_arg_type(SilcArgumentPayload payload,
 337                                           uint32 type,
 338                                           uint32 *ret_len);
 339
 340 #endif