mirror of
https://github.com/obgm/libcoap.git
synced 2026-11-01 23:45:48 +03:00
Carsten Schoenert
0e59edc231
Resume the cleaning of the public header files, no functional changes. Reformatting the infos in the head of the header files, restructure header inclusion check to be more generic. Reorder some include directives in a alphabetical order. Remove including instructions for C++ stuff, it's already done in the coap.h header, and the user only has to include this header file. Dropping the prefixing of the include guarding of uthash.h because it would cause trouble with the macro handling in TinyDLS. Thanks Olaf for reminding this!
124 lines
4.2 KiB
C
124 lines
4.2 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_
|
|
|
|
#include "hashkey.h"
|
|
#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.
|
|
* @param 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);
|
|
|
|
/**
|
|
* Clones the specified coap_uri_t object. Thie function allocates sufficient
|
|
* memory to hold the coap_uri_t structure and its contents. The object must
|
|
* be released with coap_free(). */
|
|
coap_uri_t *coap_clone_uri(const coap_uri_t *uri);
|
|
|
|
/**
|
|
* Calculates a hash over the given path and stores the result in
|
|
* @p key. This function returns @c 0 on error or @c 1 on success.
|
|
*
|
|
* @param path The URI path to generate hash for.
|
|
* @param len The length of @p path.
|
|
* @param key The output buffer.
|
|
*
|
|
* @return @c 1 if @p key was set, @c 0 otherwise.
|
|
*/
|
|
int coap_hash_path(const unsigned char *path, size_t len, coap_key_t key);
|
|
|
|
/**
|
|
* @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.
|
|
* @{
|
|
*/
|
|
|
|
/**
|
|
* 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.
|
|
*/
|
|
int coap_split_path(const unsigned char *s,
|
|
size_t length,
|
|
unsigned char *buf,
|
|
size_t *buflen);
|
|
|
|
/**
|
|
* 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.
|
|
*/
|
|
int coap_split_query(const unsigned char *s,
|
|
size_t length,
|
|
unsigned char *buf,
|
|
size_t *buflen);
|
|
|
|
/** @} */
|
|
|
|
#endif /* _COAP_URI_H_ */
|