167 lines
5.5 KiB
C
167 lines
5.5 KiB
C
/* 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_ */
|