resource/csdk/connectivity/lib/libcoap-4.1.1/uri.h

   1 /* uri.h -- helper functions for URI treatment
   2  *
   3  * Copyright (C) 2010,2011 Olaf Bergmann <bergmann@tzi.org>
   4  *
   5  * This file is part of the CoAP library libcoap. Please see
   6  * README for terms of use.
   7  */
   8
   9 #ifndef _COAP_URI_H_
  10 #define _COAP_URI_H_
  11
  12 #include "hashkey.h"
  13 #include "str.h"
  14 #include <stdbool.h>
  15
  16 ///Separtor for multiple query string
  17 #define OC_QUERY_SEPARATOR                "&;"
  18
  19 /** Representation of parsed URI. Components may be filled from a
  20  * string with coap_split_uri() and can be used as input for
  21  * option-creation functions. */
  22 typedef struct
  23 {
  24     str host; /**< host part of the URI */
  25     unsigned short port; /**< The port in host byte order */
  26     str path; /**< Beginning of the first path segment.
  27      Use coap_split_path() to create Uri-Path options */
  28     str query; /**<  The query part if present */
  29 } coap_uri_t;
  30
  31 /**
  32  * Creates a new coap_uri_t object from the specified URI. Returns the new
  33  * object or NULL on error. The memory allocated by the new coap_uri_t
  34  * must be released using coap_free().
  35  * @param uri The URI path to copy.
  36  * @para length The length of uri.
  37  *
  38  * @return New URI object or NULL on error.
  39  */
  40 coap_uri_t *coap_new_uri(const unsigned char *uri, unsigned int length);
  41
  42 /**
  43  * Clones the specified coap_uri_t object. Thie function allocates sufficient
  44  * memory to hold the coap_uri_t structure and its contents. The object must
  45  * be released with coap_free(). */
  46 coap_uri_t *coap_clone_uri(const coap_uri_t *uri);
  47
  48 /**
  49  * Calculates a hash over the given path and stores the result in
  50  * @p key. This function returns @c 0 on error or @c 1 on success.
  51  *
  52  * @param path The URI path to generate hash for.
  53  * @param len  The length of @p path.
  54  * @param key  The output buffer.
  55  *
  56  * @return @c 1 if @p key was set, @c 0 otherwise.
  57  */
  58 int coap_hash_path(const unsigned char *path, size_t len, coap_key_t key);
  59
  60 /**
  61  * @defgroup uri_parse URI Parsing Functions
  62  *
  63  * CoAP PDUs contain normalized URIs with their path and query split into
  64  * multiple segments. The functions in this module help splitting strings.
  65  * @{
  66  */
  67
  68 /**
  69  * Iterator to for tokenizing a URI path or query. This structure must
  70  * be initialized with coap_parse_iterator_init(). Call
  71  * coap_parse_next() to walk through the tokens.
  72  *
  73  * @code
  74  * unsigned char *token;
  75  * coap_parse_iterator_t pi;
  76  * coap_parse_iterator_init(uri.path.s, uri.path.length, "/", "?#", 2, &pi);
  77  *
  78  * while ((token = coap_parse_next(&pi))) {
  79  *   ... do something with token ...
  80  * }
  81  * @endcode
  82  */
  83 typedef struct
  84 {
  85     size_t n; /**< number of remaining characters in buffer */
  86     unsigned char *separator; /**< segment separators */
  87     unsigned char *delim; /**< delimiters where to split the string */
  88     size_t dlen; /**< length of separator */
  89     unsigned char *pos; /**< current position in buffer */
  90     size_t segment_length; /**< length of current segment */
  91 } coap_parse_iterator_t;
  92
  93 /**
  94  * Initializes the given iterator @p pi.
  95  *
  96  * @param s         The string to tokenize.
  97  * @param n         The length of @p s.
  98  * @param separator The separator character that delimits tokens.
  99  * @param delim     A set of characters that delimit @s.
 100  * @param dlen      The length of @p delim.
 101  * @param pi        The iterator object to initialize.
 102  *
 103  * @return The initialized iterator object @p pi.
 104  */
 105 coap_parse_iterator_t *
 106 coap_parse_iterator_init(unsigned char *s, size_t n, unsigned char *separator, unsigned char *delim,
 107         size_t dlen, coap_parse_iterator_t *pi);
 108
 109 /**
 110  * Updates the iterator @p pi to point to the next token. This
 111  * function returns a pointer to that token or @c NULL if no more
 112  * tokens exist. The contents of @p pi will be updated. In particular,
 113  * @c pi->segment_length specifies the length of the current token, @c
 114  * pi->pos points to its beginning.
 115  *
 116  * @param pi The iterator to update.
 117  *
 118  * @return The next token or @c NULL if no more tokens exist.
 119  */
 120 unsigned char *coap_parse_next(coap_parse_iterator_t *pi);
 121
 122 /**
 123  * Parses a given string into URI components. The identified syntactic
 124  * components are stored in the result parameter @p uri. Optional URI
 125  * components that are not specified will be set to { 0, 0 }, except
 126  * for the port which is set to @c COAP_DEFAULT_PORT. This function
 127  * returns @p 0 if parsing succeeded, a value less than zero
 128  * otherwise.
 129  *
 130  * @param str_var The string to split up.
 131  * @param len     The actual length of @p str_var
 132  * @param uri     The coap_uri_t object to store the result.
 133  * @return @c 0 on success, or < 0 on error.
 134  *
 135  * @note The host name part will be converted to lower case by this
 136  * function.
 137  */
 138 int
 139 coap_split_uri(unsigned char *str_var, size_t len, coap_uri_t *uri);
 140
 141 /**
 142  * Splits the given URI path into segments. Each segment is preceded
 143  * by an option pseudo-header with delta-value 0 and the actual length
 144  * of the respective segment after percent-decoding.
 145  *
 146  * @param s      The path string to split.
 147  * @param length The actual length of @p s.
 148  * @param buf    Result buffer for parsed segments.
 149  * @param buflen Maximum length of @p buf. Will be set to the actual number
 150  * of bytes written into buf on success.
 151  *
 152  * @return The number of segments created or @c -1 on error.
 153  */
 154 int coap_split_path(const unsigned char *s, size_t length, unsigned char *buf, size_t *buflen);
 155
 156 /**
 157  * Splits the given URI query into segments. Each segment is preceded
 158  * by an option pseudo-header with delta-value 0 and the actual length
 159  * of the respective query term.
 160  *
 161  * @param s      The query string to split.
 162  * @param length The actual length of @p s.
 163  * @param buf    Result buffer for parsed segments.
 164  * @param buflen Maximum length of @p buf. Will be set to the actual number
 165  * of bytes written into buf on success.
 166  *
 167  * @return The number of segments created or @c -1 on error.
 168  *
 169  * @bug This function does not reserve additional space for delta > 12.
 170  */
 171 int coap_split_query(const unsigned char *s, size_t length, unsigned char *buf, size_t *buflen);
 172
 173 /** @} */
 174 #endif /* _COAP_URI_H_ */