1 /* 2 * uri.h -- helper functions for URI treatment 3 * 4 * Copyright (C) 2010-2011 Olaf Bergmann <bergmann@tzi.org> 5 * 6 * This file is part of the CoAP library libcoap. Please see README for terms 7 * of use. 8 */ 9 10 #ifndef _COAP_URI_H_ 11 #define _COAP_URI_H_ 12 13 #include "hashkey.h" 14 #include "str.h" 15 16 /** 17 * Representation of parsed URI. Components may be filled from a string with 18 * coap_split_uri() and can be used as input for option-creation functions. 19 */ 20 typedef struct { 21 str host; /**< host part of the URI */ 22 unsigned short port; /**< The port in host byte order */ 23 str path; /**< Beginning of the first path segment. 24 Use coap_split_path() to create Uri-Path options */ 25 str query; /**< The query part if present */ 26 } coap_uri_t; 27 28 /** 29 * Creates a new coap_uri_t object from the specified URI. Returns the new 30 * object or NULL on error. The memory allocated by the new coap_uri_t 31 * must be released using coap_free(). 32 * 33 * @param uri The URI path to copy. 34 * @param length The length of uri. 35 * 36 * @return New URI object or NULL on error. 37 */ 38 coap_uri_t *coap_new_uri(const unsigned char *uri, unsigned int length); 39 40 /** 41 * Clones the specified coap_uri_t object. Thie function allocates sufficient 42 * memory to hold the coap_uri_t structure and its contents. The object must 43 * be released with coap_free(). */ 44 coap_uri_t *coap_clone_uri(const coap_uri_t *uri); 45 46 /** 47 * Calculates a hash over the given path and stores the result in 48 * @p key. This function returns @c 0 on error or @c 1 on success. 49 * 50 * @param path The URI path to generate hash for. 51 * @param len The length of @p path. 52 * @param key The output buffer. 53 * 54 * @return @c 1 if @p key was set, @c 0 otherwise. 55 */ 56 int coap_hash_path(const unsigned char *path, size_t len, coap_key_t key); 57 58 /** 59 * @defgroup uri_parse URI Parsing Functions 60 * 61 * CoAP PDUs contain normalized URIs with their path and query split into 62 * multiple segments. The functions in this module help splitting strings. 63 * @{ 64 */ 65 66 /** 67 * Parses a given string into URI components. The identified syntactic 68 * components are stored in the result parameter @p uri. Optional URI 69 * components that are not specified will be set to { 0, 0 }, except for the 70 * port which is set to @c COAP_DEFAULT_PORT. This function returns @p 0 if 71 * parsing succeeded, a value less than zero otherwise. 72 * 73 * @param str_var The string to split up. 74 * @param len The actual length of @p str_var 75 * @param uri The coap_uri_t object to store the result. 76 * @return @c 0 on success, or < 0 on error. 77 * 78 * @note The host name part will be converted to lower case by this 79 * function. 80 */ 81 int coap_split_uri(unsigned char *str_var, size_t len, coap_uri_t *uri); 82 83 /** 84 * Splits the given URI path into segments. Each segment is preceded 85 * by an option pseudo-header with delta-value 0 and the actual length 86 * of the respective segment after percent-decoding. 87 * 88 * @param s The path string to split. 89 * @param length The actual length of @p s. 90 * @param buf Result buffer for parsed segments. 91 * @param buflen Maximum length of @p buf. Will be set to the actual number 92 * of bytes written into buf on success. 93 * 94 * @return The number of segments created or @c -1 on error. 95 */ 96 int coap_split_path(const unsigned char *s, 97 size_t length, 98 unsigned char *buf, 99 size_t *buflen); 100 101 /** 102 * Splits the given URI query into segments. Each segment is preceded 103 * by an option pseudo-header with delta-value 0 and the actual length 104 * of the respective query term. 105 * 106 * @param s The query string to split. 107 * @param length The actual length of @p s. 108 * @param buf Result buffer for parsed segments. 109 * @param buflen Maximum length of @p buf. Will be set to the actual number 110 * of bytes written into buf on success. 111 * 112 * @return The number of segments created or @c -1 on error. 113 * 114 * @bug This function does not reserve additional space for delta > 12. 115 */ 116 int coap_split_query(const unsigned char *s, 117 size_t length, 118 unsigned char *buf, 119 size_t *buflen); 120 121 /** @} */ 122 123 #endif /* _COAP_URI_H_ */ 124
