/* silcargument.h Author: Pekka Riikonen Copyright (C) 2001 - 2007 Pekka Riikonen This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; version 2 of the License. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. */ /****h* silccore/SILC Argument Interface * * DESCRIPTION * * Implementations of the Argument Payload and Argument List Payload, that * is used to include arguments to other payload that needs arguments. * ***/ #ifndef SILCARGUMENT_H #define SILCARGUMENT_H /****s* silccore/SilcArgumentAPI/SilcArgumentPayload * * NAME * * typedef struct SilcArgumentPayloadStruct *SilcArgumentPayload; * * DESCRIPTION * * This context is the actual Argument Payload and is allocated * by silc_argument_payload_parse and given as argument usually to * all silc_argument_payload_* functions. It is freed by the * silc_argument_payload_free function. * ***/ typedef struct SilcArgumentPayloadStruct *SilcArgumentPayload; /****f* silccore/SilcArgumentAPI/silc_argument_payload_parse * * SYNOPSIS * * SilcArgumentPayload * silc_argument_payload_parse(const unsigned char *payload, * SilcUInt32 payload_len, * SilcUInt32 argc); * * DESCRIPTION * * Parses arguments and returns them into Argument Payload structure. * the `buffer' is raw Argument Payload data buffer. The `argc' is * the number of arguments in the Argument Payload. The caller must * know the number of the arguments. This is always known as the * Argument payload is associated with other payloads which defines * the number of the arguments. * ***/ SilcArgumentPayload silc_argument_payload_parse(const unsigned char *payload, SilcUInt32 payload_len, SilcUInt32 argc); /****f* silccore/SilcArgumentAPI/silc_argument_payload_encode * * SYNOPSIS * * SilcBuffer silc_argument_payload_encode(SilcUInt32 argc, * unsigned char **argv, * SilcUInt32 *argv_lens, * SilcUInt32 *argv_types); * * DESCRIPTION * * Encodes arguments in to Argument Paylods returning them to SilcBuffer. * The `argv' is the array of the arguments, the `argv_lens' array of * the length of the `argv' arguments and the `argv_types' array of * the argument types of the `argv' arguments. The `argc' is the * number of arguments. * ***/ SilcBuffer silc_argument_payload_encode(SilcUInt32 argc, unsigned char **argv, SilcUInt32 *argv_lens, SilcUInt32 *argv_types); /****f* silccore/SilcArgumentAPI/silc_argument_payload_encode_one * * SYNOPSIS * * SilcBuffer silc_argument_payload_encode_one(SilcBuffer args, * unsigned char *arg, * SilcUInt32 arg_len, * SilcUInt32 arg_type); * * DESCRIPTION * * Same as silc_argument_payload_encode but encodes one argument to * the buffer `args' and returns the buffer. The returned buffer * may be different than the `args'. If `args' is NULL for the first * argument this allocates the buffer and returns it. * ***/ SilcBuffer silc_argument_payload_encode_one(SilcBuffer args, unsigned char *arg, SilcUInt32 arg_len, SilcUInt32 arg_type); /****f* silccore/SilcArgumentAPI/silc_argument_payload_encode_payload * * SYNOPSIS * * SilcBuffer * silc_argument_payload_encode_payload(SilcArgumentPayload payload); * * DESCRIPTION * * Same as silc_argument_payload_encode but encodes the payload from * already allocated SilcArgumentPayload structure instead of raw data. * ***/ SilcBuffer silc_argument_payload_encode_payload(SilcArgumentPayload payload); /****f* silccore/SilcArgumentAPI/silc_argument_payload_free * * SYNOPSIS * * void silc_argument_payload_free(SilcArgumentPayload payload); * * DESCRIPTION * * Frees the Argument Payload and all data in it. * ***/ void silc_argument_payload_free(SilcArgumentPayload payload); /****f* silccore/SilcArgumentAPI/silc_argument_get_arg_num * * SYNOPSIS * * SilcUInt32 silc_argument_get_arg_num(SilcArgumentPayload payload); * * DESCRIPTION * * Returns the number of arguments in the Argument Payload. * ***/ SilcUInt32 silc_argument_get_arg_num(SilcArgumentPayload payload); /****f* silccore/SilcArgumentAPI/silc_argument_get_first_arg * * SYNOPSIS * * unsigned char *silc_argument_get_first_arg(SilcArgumentPayload payload, * SilcUInt32 *type, * SilcUInt32 *ret_len); * * DESCRIPTION * * Returns the first argument in the Argument Payload. The lenght * of the argument is returned to `ret_len'. The caller must not * free the returned argument. Returns NULL on error. * ***/ unsigned char *silc_argument_get_first_arg(SilcArgumentPayload payload, SilcUInt32 *type, SilcUInt32 *ret_len); /****f* silccore/SilcArgumentAPI/silc_argument_get_next_arg * * SYNOPSIS * * unsigned char *silc_argument_get_next_arg(SilcArgumentPayload payload, * SilcUInt32 *ret_len); * * DESCRIPTION * * Returns next argument from the Argument Payload. The length of * the argument is returned to `ret_len'. The caller must not free * the returned argument. This returns NULL when there are no more * arguments in the payload. * ***/ unsigned char *silc_argument_get_next_arg(SilcArgumentPayload payload, SilcUInt32 *type, SilcUInt32 *ret_len); /****f* silccore/SilcArgumentAPI/silc_argument_get_arg_type * * SYNOPSIS * * unsigned char *silc_argument_get_arg_type(SilcArgumentPayload payload, * SilcUInt32 type, * SilcUInt32 *ret_len); * * DESCRIPTION * * Returns argument by type. The returned argument has type `type' * in the Argument Payload. Each argument has their own type (or zero * if no specific type is set). The length of the argument is returned * to the `ret_len'. The caller must not free the returned argument. * Returns NULL on error. * ***/ unsigned char *silc_argument_get_arg_type(SilcArgumentPayload payload, SilcUInt32 type, SilcUInt32 *ret_len); /****d* silccore/SilcArgumentAPI/SilcArgumentDecodeType * * NAME * * typedef enum { ... } SilcArgumentDecodeType; * * DESCRIPTION * * Argument decode types used with silc_argument_get_decoded. * * SOURCE */ typedef enum { SILC_ARGUMENT_ID, /* SilcID */ SILC_ARGUMENT_PUBLIC_KEY, /* SilcPublicKey (always alloc) */ SILC_ARGUMENT_ATTRIBUTES, /* SilcDList (always alloc) */ SILC_ARGUMENT_UINT32, /* SilcUInt32 */ SILC_ARGUMENT_BOOL, /* SilcBool */ } SilcArgumentDecodeType; /***/ /****f* silccore/SilcArgumentAPI/silc_argument_get_decoded * * SYNOPSIS * * SilcBool silc_argument_get_decoded(SilcArgumentPayload payload, * SilcUInt32 type, * SilcArgumentDecodeType dec_type, * void *ret_arg, * void *ret_arg_alloc); * * DESCRIPTION * * Returns decoded argument by type. This is a helper function to * decode common argument types directly. The `type' is the argument * type number in the payload, and the `dec_type' is the type the * argument is decoded to. If the `ret_arg' is non-NULL then the * decodec data is returned into that pointer. If the `ret_arg_alloc' * is non-NULL then this function will allocate the decoded data and * will return the pointer into `ret_arg_alloc'. Some types must always * be allocated; see SilcArgumentDecodeType. * * Return TRUE if the argument was present and waa successfully decoded. * FALSE if it is not present, or could not be decoded. * * EXAMPLE * * SilcID id; * SilcPublicKey public_key; * * if (!silc_argument_get_decoded(args, 2, SILC_ARGUMENT_ID, &id, NULL)) * error; * * if (!silc_argument_get_decoded(args, 4, SILC_ARGUMENT_PUBLIC_KEY, * NULL, &public_key)) * error; * ***/ SilcBool silc_argument_get_decoded(SilcArgumentPayload payload, SilcUInt32 type, SilcArgumentDecodeType dec_type, void *ret_arg, void **ret_arg_alloc); /****f* silccore/SilcArgumentAPI/silc_argument_list_parse * * SYNOPSIS * * SilcArgumentPayload * silc_argument_list_parse(const unsigned char *payload, * SilcUInt32 payload_len); * * DESCRIPTION * * Parses argument list payload. Returns parsed SilcArgumentPayload which * contains all the arguments from the list. The caller must free the * returned context with silc_argument_payload_free. * ***/ SilcArgumentPayload silc_argument_list_parse(const unsigned char *payload, SilcUInt32 payload_len); /****s* silccore/SilcArgumentAPI/SilcArgumentDecodedList * * NAME * * typedef struct { ... } *SilcArgumentDecodedList; * * DESCRIPTION * * This structure is in the list returned by the function * silc_argument_list_payload_parse_decoded. The caller is responsible * of freeing the contents of the structure and the structure itself. * ***/ typedef struct SilcArgumentDecodedListStruct { void *argument; /* Decoded argument, caller must know its type */ SilcUInt32 arg_type; /* Argument type number from the payload */ } *SilcArgumentDecodedList; /****f* silccore/SilcArgumentAPI/silc_argument_list_parse_decoded * * SYNOPSIS * * SilcDList * silc_argument_list_parse_decoded(const unsigned char *payload, * SilcUInt32 payload_len, * SilcArgumentDecodeType dec_type); * * DESCRIPTION * * Parses argument list payload of arguments of the type `dec_type'. * The returned list includes the already decoded arguments. The caller * is responsible of freeing the the contents of the list and the list * itself. Each entry in the list is SilcArgumentDecodedList. The * caller must free the returned list with silc_argument_list_free. * ***/ SilcDList silc_argument_list_parse_decoded(const unsigned char *payload, SilcUInt32 payload_len, SilcArgumentDecodeType dec_type); /****f* silccore/SilcArgumentAPI/silc_argument_list_free * * SYNOPSIS * * void * silc_argument_list_free(SilcDList list, SilcArgumentDecodeType dec_type); * * DESCRIPTION * * Free's the decoded argument list and its contents. * ***/ void silc_argument_list_free(SilcDList list, SilcArgumentDecodeType dec_type); #endif /* SILCARGUMENT_H */