123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166 |
- /* uri.h -- helper functions for URI treatment
- *
- * Copyright (C) 2010,2011 Olaf Bergmann <bergmann@tzi.org>
- *
- * This file is part of the CoAP library libcoap. Please see
- * README for terms of use.
- */
- #ifndef _COAP_URI_H_
- #define _COAP_URI_H_
- #define COAP_DEFAULT_SCHEME "coap" /* the default scheme for CoAP URIs */
- #define COAP_DEFAULT_PORT 5683
- #include "str.h"
- /** Representation of parsed URI. Components may be filled from a
- * string with coap_split_uri() and can be used as input for
- * option-creation functions. */
- typedef struct {
- str host; /**< host part of the URI */
- unsigned short port; /**< The port in host byte order */
- str path; /**< Beginning of the first path segment.
- Use coap_split_path() to create Uri-Path options */
- str query; /**< The query part if present */
- } coap_uri_t;
- /**
- * Creates a new coap_uri_t object from the specified URI. Returns the new
- * object or NULL on error. The memory allocated by the new coap_uri_t
- * must be released using coap_free().
- * @param uri The URI path to copy.
- * @para length The length of uri.
- *
- * @return New URI object or NULL on error.
- */
- coap_uri_t *coap_new_uri(const unsigned char *uri, unsigned int length);
- /**
- * @defgroup uri_parse URI Parsing Functions
- *
- * CoAP PDUs contain normalized URIs with their path and query split into
- * multiple segments. The functions in this module help splitting strings.
- * @{
- */
- /**
- * Iterator to for tokenizing a URI path or query. This structure must
- * be initialized with coap_parse_iterator_init(). Call
- * coap_parse_next() to walk through the tokens.
- *
- * @code
- * unsigned char *token;
- * coap_parse_iterator_t pi;
- * coap_parse_iterator_init(uri.path.s, uri.path.length, '/', "?#", 2, &pi);
- *
- * while ((token = coap_parse_next(&pi))) {
- * ... do something with token ...
- * }
- * @endcode
- */
- typedef struct {
- size_t n; /**< number of remaining characters in buffer */
- unsigned char separator; /**< segment separators */
- unsigned char *delim; /**< delimiters where to split the string */
- size_t dlen; /**< length of separator */
- unsigned char *pos; /**< current position in buffer */
- size_t segment_length; /**< length of current segment */
- } coap_parse_iterator_t;
- /**
- * Initializes the given iterator @p pi.
- *
- * @param s The string to tokenize.
- * @param n The length of @p s.
- * @param separator The separator character that delimits tokens.
- * @param delim A set of characters that delimit @s.
- * @param dlen The length of @p delim.
- * @param pi The iterator object to initialize.
- *
- * @return The initialized iterator object @p pi.
- */
- coap_parse_iterator_t *
- coap_parse_iterator_init(unsigned char *s, size_t n,
- unsigned char separator,
- unsigned char *delim, size_t dlen,
- coap_parse_iterator_t *pi);
- /**
- * Updates the iterator @p pi to point to the next token. This
- * function returns a pointer to that token or @c NULL if no more
- * tokens exist. The contents of @p pi will be updated. In particular,
- * @c pi->segment_length specifies the length of the current token, @c
- * pi->pos points to its beginning.
- *
- * @param pi The iterator to update.
- *
- * @return The next token or @c NULL if no more tokens exist.
- */
- unsigned char *coap_parse_next(coap_parse_iterator_t *pi);
- /**
- * Parses a given string into URI components. The identified syntactic
- * components are stored in the result parameter @p uri. Optional URI
- * components that are not specified will be set to { 0, 0 }, except
- * for the port which is set to @c COAP_DEFAULT_PORT. This function
- * returns @p 0 if parsing succeeded, a value less than zero
- * otherwise.
- *
- * @param str_var The string to split up.
- * @param len The actual length of @p str_var
- * @param uri The coap_uri_t object to store the result.
- * @return @c 0 on success, or < 0 on error.
- *
- * @note The host name part will be converted to lower case by this
- * function.
- */
- int
- coap_split_uri(unsigned char *str_var, size_t len, coap_uri_t *uri);
- /**
- * Splits the given URI path into segments. Each segment is preceded
- * by an option pseudo-header with delta-value 0 and the actual length
- * of the respective segment after percent-decoding.
- *
- * @param s The path string to split.
- * @param length The actual length of @p s.
- * @param buf Result buffer for parsed segments.
- * @param buflen Maximum length of @p buf. Will be set to the actual number
- * of bytes written into buf on success.
- *
- * @return The number of segments created or @c -1 on error.
- */
- #if 0
- int coap_split_path(const unsigned char *s, size_t length,
- unsigned char *buf, size_t *buflen);
- #else
- int
- coap_split_path(coap_rw_buffer_t *scratch, coap_packet_t *pkt,
- const unsigned char *s, size_t length);
- #endif
- /**
- * Splits the given URI query into segments. Each segment is preceded
- * by an option pseudo-header with delta-value 0 and the actual length
- * of the respective query term.
- *
- * @param s The query string to split.
- * @param length The actual length of @p s.
- * @param buf Result buffer for parsed segments.
- * @param buflen Maximum length of @p buf. Will be set to the actual number
- * of bytes written into buf on success.
- *
- * @return The number of segments created or @c -1 on error.
- *
- * @bug This function does not reserve additional space for delta > 12.
- */
- #if 0
- int coap_split_query(const unsigned char *s, size_t length,
- unsigned char *buf, size_t *buflen);
- #else
- int coap_split_query(coap_rw_buffer_t *scratch, coap_packet_t *pkt,
- const unsigned char *s, size_t length);
- #endif
- /** @} */
- #endif /* _COAP_URI_H_ */
|