lib/silccore/silcargument.h

   1 /*
   2
   3   silcargument.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 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; 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/SilcArgumentAPI
  21  *
  22  * DESCRIPTION
  23  *
  24  * Implementation of the Argument Payload, that is used to include
  25  * argument to other payload that needs arguments.
  26  *
  27  ***/
  28
  29 #ifndef SILCPAYLOAD_H
  30 #define SILCPAYLOAD_H
  31
  32 /****f* silccore/SilcArgumentAPI/silc_argument_payload_parse
  33  *
  34  * SYNOPSIS
  35  *
  36  *    SilcArgumentPayload
  37  *    silc_argument_payload_parse(const unsigned char *payload,
  38  *                                SilcUInt32 payload_len,
  39  *                                SilcUInt32 argc);
  40  *
  41  * DESCRIPTION
  42  *
  43  *    Parses arguments and returns them into Argument Payload structure.
  44  *    the `buffer' is raw Argument Payload data buffer. The `argc' is
  45  *    the number of arguments in the Argument Payload. The caller must
  46  *    know the number of the arguments. This is always known as the
  47  *    Argument payload is associated with other payloads which defines
  48  *    the number of the arguments.
  49  *
  50  ***/
  51 SilcArgumentPayload silc_argument_payload_parse(const unsigned char *payload,
  52                                                 SilcUInt32 payload_len,
  53                                                 SilcUInt32 argc);
  54
  55 /****f* silccore/SilcArgumentAPI/silc_argument_payload_encode
  56  *
  57  * SYNOPSIS
  58  *
  59  *    SilcBuffer silc_argument_payload_encode(SilcUInt32 argc,
  60  *                                            unsigned char **argv,
  61  *                                            SilcUInt32 *argv_lens,
  62  *                                            SilcUInt32 *argv_types);
  63  *
  64  * DESCRIPTION
  65  *
  66  *    Encodes arguments in to Argument Paylods returning them to SilcBuffer.
  67  *    The `argv' is the array of the arguments, the `argv_lens' array of
  68  *    the length of the `argv' arguments and the `argv_types' array of
  69  *    the argument types of the `argv' arguments. The `argc' is the
  70  *    number of arguments.
  71  *
  72  ***/
  73 SilcBuffer silc_argument_payload_encode(SilcUInt32 argc,
  74                                         unsigned char **argv,
  75                                         SilcUInt32 *argv_lens,
  76                                         SilcUInt32 *argv_types);
  77
  78 /****f* silccore/SilcArgumentAPI/silc_argument_payload_encode_payload
  79  *
  80  * SYNOPSIS
  81  *
  82  *    SilcBuffer
  83  *    silc_argument_payload_encode_payload(SilcArgumentPayload payload);
  84  *
  85  * DESCRIPTION
  86  *
  87  *    Same as silc_argument_payload_encode but encodes the payload from
  88  *    already allocated SilcArgumentPayload structure instead of raw data.
  89  *
  90  ***/
  91 SilcBuffer silc_argument_payload_encode_payload(SilcArgumentPayload payload);
  92
  93 /****f* silccore/SilcArgumentAPI/silc_argument_payload_free
  94  *
  95  * SYNOPSIS
  96  *
  97  *    void silc_argument_payload_free(SilcArgumentPayload payload);
  98  *
  99  * DESCRIPTION
 100  *
 101  *    Frees the Argument Payload and all data in it.
 102  *
 103  ***/
 104 void silc_argument_payload_free(SilcArgumentPayload payload);
 105
 106 /****f* silccore/SilcArgumentAPI/silc_argument_get_arg_num
 107  *
 108  * SYNOPSIS
 109  *
 110  *    SilcUInt32 silc_argument_get_arg_num(SilcArgumentPayload payload);
 111  *
 112  * DESCRIPTION
 113  *
 114  *    Returns the number of argument in the Argument Payload.
 115  *
 116  ***/
 117 SilcUInt32 silc_argument_get_arg_num(SilcArgumentPayload payload);
 118
 119 /****f* silccore/SilcArgumentAPI/silc_argument_get_first_arg
 120  *
 121  * SYNOPSIS
 122  *
 123  *    unsigned char *silc_argument_get_first_arg(SilcArgumentPayload payload,
 124  *                                               SilcUInt32 *ret_len);
 125  *
 126  * DESCRIPTION
 127  *
 128  *    Returns the first argument in the Argument Payload. The lenght
 129  *    of the argument is returned to `ret_len'. The caller must not
 130  *    free the returned argument. Returns NULL on error.
 131  *
 132  ***/
 133 unsigned char *silc_argument_get_first_arg(SilcArgumentPayload payload,
 134                                            SilcUInt32 *ret_len);
 135
 136 /****f* silccore/SilcArgumentAPI/silc_argument_get_next_arg
 137  *
 138  * SYNOPSIS
 139  *
 140  *    unsigned char *silc_argument_get_next_arg(SilcArgumentPayload payload,
 141  *                                              SilcUInt32 *ret_len);
 142  *
 143  * DESCRIPTION
 144  *
 145  *    Returns next argument from the Argument Payload. The length of
 146  *    the argument is returned to `ret_len'. The caller must not free
 147  *    the returned argument. This returns NULL when there are no more
 148  *    arguments in the payload.
 149  *
 150  ***/
 151 unsigned char *silc_argument_get_next_arg(SilcArgumentPayload payload,
 152                                           SilcUInt32 *ret_len);
 153
 154 /****f* silccore/SilcArgumentAPI/silc_argument_get_arg_type
 155  *
 156  * SYNOPSIS
 157  *
 158  *    unsigned char *silc_argument_get_arg_type(SilcArgumentPayload payload,
 159  *                                              SilcUInt32 type,
 160  *                                              SilcUInt32 *ret_len);
 161  *
 162  * DESCRIPTION
 163  *
 164  *    Returns argument by type. The returned argument has type `type'
 165  *    in the Argument Payload. Each argument has their own type (or zero
 166  *    if no specific type is set). The length of the argument is returned
 167  *    to the `ret_len'. The caller must not free the returned argument.
 168  *    Returns NULL on error.
 169  *
 170  ***/
 171 unsigned char *silc_argument_get_arg_type(SilcArgumentPayload payload,
 172                                           SilcUInt32 type,
 173                                           SilcUInt32 *ret_len);
 174
 175 #endif