uri.h 5.5 KB

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