lib/silccore/silcargument.h

   1 /*
   2
   3   silcargument.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2001 - 2007 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 Argument Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * Implementations of the Argument Payload and Argument List Payload, that
  25  * is used to include arguments to other payload that needs arguments.
  26  *
  27  ***/
  28
  29 #ifndef SILCARGUMENT_H
  30 #define SILCARGUMENT_H
  31
  32 /****s* silccore/SilcArgumentAPI/SilcArgumentPayload
  33  *
  34  * NAME
  35  *
  36  *    typedef struct SilcArgumentPayloadStruct *SilcArgumentPayload;
  37  *
  38  * DESCRIPTION
  39  *
  40  *    This context is the actual Argument Payload and is allocated
  41  *    by silc_argument_payload_parse and given as argument usually to
  42  *    all silc_argument_payload_* functions.  It is freed by the
  43  *    silc_argument_payload_free function.
  44  *
  45  ***/
  46 typedef struct SilcArgumentPayloadStruct *SilcArgumentPayload;
  47
  48 /****f* silccore/SilcArgumentAPI/silc_argument_payload_parse
  49  *
  50  * SYNOPSIS
  51  *
  52  *    SilcArgumentPayload
  53  *    silc_argument_payload_parse(const unsigned char *payload,
  54  *                                SilcUInt32 payload_len,
  55  *                                SilcUInt32 argc);
  56  *
  57  * DESCRIPTION
  58  *
  59  *    Parses arguments and returns them into Argument Payload structure.
  60  *    the `buffer' is raw Argument Payload data buffer. The `argc' is
  61  *    the number of arguments in the Argument Payload. The caller must
  62  *    know the number of the arguments. This is always known as the
  63  *    Argument payload is associated with other payloads which defines
  64  *    the number of the arguments.
  65  *
  66  ***/
  67 SilcArgumentPayload silc_argument_payload_parse(const unsigned char *payload,
  68                                                 SilcUInt32 payload_len,
  69                                                 SilcUInt32 argc);
  70
  71 /****f* silccore/SilcArgumentAPI/silc_argument_payload_encode
  72  *
  73  * SYNOPSIS
  74  *
  75  *    SilcBuffer silc_argument_payload_encode(SilcUInt32 argc,
  76  *                                            unsigned char **argv,
  77  *                                            SilcUInt32 *argv_lens,
  78  *                                            SilcUInt32 *argv_types);
  79  *
  80  * DESCRIPTION
  81  *
  82  *    Encodes arguments in to Argument Paylods returning them to SilcBuffer.
  83  *    The `argv' is the array of the arguments, the `argv_lens' array of
  84  *    the length of the `argv' arguments and the `argv_types' array of
  85  *    the argument types of the `argv' arguments. The `argc' is the
  86  *    number of arguments.
  87  *
  88  ***/
  89 SilcBuffer silc_argument_payload_encode(SilcUInt32 argc,
  90                                         unsigned char **argv,
  91                                         SilcUInt32 *argv_lens,
  92                                         SilcUInt32 *argv_types);
  93
  94 /****f* silccore/SilcArgumentAPI/silc_argument_payload_encode_one
  95  *
  96  * SYNOPSIS
  97  *
  98  *    SilcBuffer silc_argument_payload_encode_one(SilcBuffer args,
  99  *                                                unsigned char *arg,
 100  *                                                SilcUInt32 arg_len,
 101  *                                                SilcUInt32 arg_type);
 102  *
 103  * DESCRIPTION
 104  *
 105  *    Same as silc_argument_payload_encode but encodes one argument to
 106  *    the buffer `args' and returns the buffer.  The returned buffer
 107  *    may be different than the `args'.  If `args' is NULL for the first
 108  *    argument this allocates the buffer and returns it.
 109  *
 110  ***/
 111 SilcBuffer silc_argument_payload_encode_one(SilcBuffer args,
 112                                             unsigned char *arg,
 113                                             SilcUInt32 arg_len,
 114                                             SilcUInt32 arg_type);
 115
 116 /****f* silccore/SilcArgumentAPI/silc_argument_payload_encode_payload
 117  *
 118  * SYNOPSIS
 119  *
 120  *    SilcBuffer
 121  *    silc_argument_payload_encode_payload(SilcArgumentPayload payload);
 122  *
 123  * DESCRIPTION
 124  *
 125  *    Same as silc_argument_payload_encode but encodes the payload from
 126  *    already allocated SilcArgumentPayload structure instead of raw data.
 127  *
 128  ***/
 129 SilcBuffer silc_argument_payload_encode_payload(SilcArgumentPayload payload);
 130
 131 /****f* silccore/SilcArgumentAPI/silc_argument_payload_free
 132  *
 133  * SYNOPSIS
 134  *
 135  *    void silc_argument_payload_free(SilcArgumentPayload payload);
 136  *
 137  * DESCRIPTION
 138  *
 139  *    Frees the Argument Payload and all data in it.
 140  *
 141  ***/
 142 void silc_argument_payload_free(SilcArgumentPayload payload);
 143
 144 /****f* silccore/SilcArgumentAPI/silc_argument_get_arg_num
 145  *
 146  * SYNOPSIS
 147  *
 148  *    SilcUInt32 silc_argument_get_arg_num(SilcArgumentPayload payload);
 149  *
 150  * DESCRIPTION
 151  *
 152  *    Returns the number of arguments in the Argument Payload.
 153  *
 154  ***/
 155 SilcUInt32 silc_argument_get_arg_num(SilcArgumentPayload payload);
 156
 157 /****f* silccore/SilcArgumentAPI/silc_argument_get_first_arg
 158  *
 159  * SYNOPSIS
 160  *
 161  *    unsigned char *silc_argument_get_first_arg(SilcArgumentPayload payload,
 162  *                                               SilcUInt32 *type,
 163  *                                               SilcUInt32 *ret_len);
 164  *
 165  * DESCRIPTION
 166  *
 167  *    Returns the first argument in the Argument Payload. The lenght
 168  *    of the argument is returned to `ret_len'. The caller must not
 169  *    free the returned argument. Returns NULL on error.
 170  *
 171  ***/
 172 unsigned char *silc_argument_get_first_arg(SilcArgumentPayload payload,
 173                                            SilcUInt32 *type,
 174                                            SilcUInt32 *ret_len);
 175
 176 /****f* silccore/SilcArgumentAPI/silc_argument_get_next_arg
 177  *
 178  * SYNOPSIS
 179  *
 180  *    unsigned char *silc_argument_get_next_arg(SilcArgumentPayload payload,
 181  *                                              SilcUInt32 *ret_len);
 182  *
 183  * DESCRIPTION
 184  *
 185  *    Returns next argument from the Argument Payload. The length of
 186  *    the argument is returned to `ret_len'. The caller must not free
 187  *    the returned argument. This returns NULL when there are no more
 188  *    arguments in the payload.
 189  *
 190  ***/
 191 unsigned char *silc_argument_get_next_arg(SilcArgumentPayload payload,
 192                                           SilcUInt32 *type,
 193                                           SilcUInt32 *ret_len);
 194
 195 /****f* silccore/SilcArgumentAPI/silc_argument_get_arg_type
 196  *
 197  * SYNOPSIS
 198  *
 199  *    unsigned char *silc_argument_get_arg_type(SilcArgumentPayload payload,
 200  *                                              SilcUInt32 type,
 201  *                                              SilcUInt32 *ret_len);
 202  *
 203  * DESCRIPTION
 204  *
 205  *    Returns argument by type. The returned argument has type `type'
 206  *    in the Argument Payload. Each argument has their own type (or zero
 207  *    if no specific type is set). The length of the argument is returned
 208  *    to the `ret_len'. The caller must not free the returned argument.
 209  *    Returns NULL on error.
 210  *
 211  ***/
 212 unsigned char *silc_argument_get_arg_type(SilcArgumentPayload payload,
 213                                           SilcUInt32 type,
 214                                           SilcUInt32 *ret_len);
 215
 216 /****d* silccore/SilcArgumentAPI/SilcArgumentDecodeType
 217  *
 218  * NAME
 219  *
 220  *    typedef enum { ... } SilcArgumentDecodeType;
 221  *
 222  * DESCRIPTION
 223  *
 224  *    Argument decode types used with silc_argument_get_decoded.
 225  *
 226  * SOURCE
 227  */
 228 typedef enum {
 229   SILC_ARGUMENT_ID,             /* SilcID */
 230   SILC_ARGUMENT_PUBLIC_KEY,     /* SilcPublicKey (always alloc) */
 231   SILC_ARGUMENT_ATTRIBUTES,     /* SilcDList (always alloc) */
 232   SILC_ARGUMENT_UINT32,         /* SilcUInt32 */
 233   SILC_ARGUMENT_BOOL,           /* SilcBool */
 234 } SilcArgumentDecodeType;
 235 /***/
 236
 237 /****f* silccore/SilcArgumentAPI/silc_argument_get_decoded
 238  *
 239  * SYNOPSIS
 240  *
 241  *    SilcBool silc_argument_get_decoded(SilcArgumentPayload payload,
 242  *                                       SilcUInt32 type,
 243  *                                       SilcArgumentDecodeType dec_type,
 244  *                                       void *ret_arg,
 245  *                                       void *ret_arg_alloc);
 246  *
 247  * DESCRIPTION
 248  *
 249  *    Returns decoded argument by type.  This is a helper function to
 250  *    decode common argument types directly.  The `type' is the argument
 251  *    type number in the payload, and the `dec_type' is the type the
 252  *    argument is decoded to.  If the `ret_arg' is non-NULL then the
 253  *    decodec data is returned into that pointer.  If the `ret_arg_alloc'
 254  *    is non-NULL then this function will allocate the decoded data and
 255  *    will return the pointer into `ret_arg_alloc'.  Some types must always
 256  *    be allocated; see SilcArgumentDecodeType.
 257  *
 258  *    Return TRUE if the argument was present and waa successfully decoded.
 259  *    FALSE if it is not present, or could not be decoded.
 260  *
 261  * EXAMPLE
 262  *
 263  *    SilcID id;
 264  *    SilcPublicKey public_key;
 265  *
 266  *    if (!silc_argument_get_decoded(args, 2, SILC_ARGUMENT_ID, &id, NULL))
 267  *      error;
 268  *
 269  *    if (!silc_argument_get_decoded(args, 4, SILC_ARGUMENT_PUBLIC_KEY,
 270  *                                   NULL, &public_key))
 271  *      error;
 272  *
 273  ***/
 274 SilcBool silc_argument_get_decoded(SilcArgumentPayload payload,
 275                                    SilcUInt32 type,
 276                                    SilcArgumentDecodeType dec_type,
 277                                    void *ret_arg,
 278                                    void **ret_arg_alloc);
 279
 280 /****f* silccore/SilcArgumentAPI/silc_argument_list_parse
 281  *
 282  * SYNOPSIS
 283  *
 284  *    SilcArgumentPayload
 285  *    silc_argument_list_parse(const unsigned char *payload,
 286  *                             SilcUInt32 payload_len);
 287  *
 288  * DESCRIPTION
 289  *
 290  *    Parses argument list payload.  Returns parsed SilcArgumentPayload which
 291  *    contains all the arguments from the list.  The caller must free the
 292  *    returned context with silc_argument_payload_free.
 293  *
 294  ***/
 295 SilcArgumentPayload
 296 silc_argument_list_parse(const unsigned char *payload, SilcUInt32 payload_len);
 297
 298 /****s* silccore/SilcArgumentAPI/SilcArgumentDecodedList
 299  *
 300  * NAME
 301  *
 302  *    typedef struct { ... } *SilcArgumentDecodedList;
 303  *
 304  * DESCRIPTION
 305  *
 306  *    This structure is in the list returned by the function
 307  *    silc_argument_list_payload_parse_decoded.  The caller is responsible
 308  *    of freeing the contents of the structure and the structure itself.
 309  *
 310  ***/
 311 typedef struct SilcArgumentDecodedListStruct {
 312   void *argument;            /* Decoded argument, caller must know its type */
 313   SilcUInt32 arg_type;       /* Argument type number from the payload */
 314 } *SilcArgumentDecodedList;
 315
 316 /****f* silccore/SilcArgumentAPI/silc_argument_list_parse_decoded
 317  *
 318  * SYNOPSIS
 319  *
 320  *    SilcDList
 321  *    silc_argument_list_parse_decoded(const unsigned char *payload,
 322  *                                     SilcUInt32 payload_len,
 323  *                                     SilcArgumentDecodeType dec_type);
 324  *
 325  * DESCRIPTION
 326  *
 327  *    Parses argument list payload of arguments of the type `dec_type'.
 328  *    The returned list includes the already decoded arguments.  The caller
 329  *    is responsible of freeing the the contents of the list and the list
 330  *    itself.  Each entry in the list is SilcArgumentDecodedList.  The
 331  *    caller must free the returned list with silc_argument_list_free.
 332  *
 333  ***/
 334 SilcDList
 335 silc_argument_list_parse_decoded(const unsigned char *payload,
 336                                  SilcUInt32 payload_len,
 337                                  SilcArgumentDecodeType dec_type);
 338
 339 /****f* silccore/SilcArgumentAPI/silc_argument_list_free
 340  *
 341  * SYNOPSIS
 342  *
 343  *    void
 344  *    silc_argument_list_free(SilcDList list, SilcArgumentDecodeType dec_type);
 345  *
 346  * DESCRIPTION
 347  *
 348  *    Free's the decoded argument list and its contents.
 349  *
 350  ***/
 351 void silc_argument_list_free(SilcDList list, SilcArgumentDecodeType dec_type);
 352
 353 #endif /* SILCARGUMENT_H */