coap_msg.h

00001 /*
00002  * Copyright (c) 2015 Keith Cullen.
00003  * All Rights Reserved.
00004  *
00005  * Redistribution and use in source and binary forms, with or without
00006  * modification, are permitted provided that the following conditions
00007  * are met:
00008  * 1. Redistributions of source code must retain the above copyright
00009  *    notice, this list of conditions and the following disclaimer.
00010  * 2. Redistributions in binary form must reproduce the above copyright
00011  *    notice, this list of conditions and the following disclaimer in the
00012  *    documentation and/or other materials provided with the distribution.
00013  * 3. The name of the author may not be used to endorse or promote products
00014  *    derived from this software without specific prior written permission.
00015  *
00016  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR
00017  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
00018  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
00019  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
00020  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
00021  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
00022  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
00023  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
00024  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
00025  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00026  */
00027 
00028 /**
00029  *  @file coap_msg.h
00030  *
00031  *  @brief Include file for the FreeCoAP message parser/formatter library
00032  */
00033 
00034 #ifndef COAP_MSG_H
00035 #define COAP_MSG_H
00036 
00037 #include <stddef.h>
00038 
00039 #define htons(n) (((((unsigned short)(n) & 0xFF)) << 8) | (((unsigned short)(n) & 0xFF00) >> 8))
00040 #define ntohs(n) (((((unsigned short)(n) & 0xFF)) << 8) | (((unsigned short)(n) & 0xFF00) >> 8))
00041 
00042 #define COAP_MSG_VER                           0x01                             /**< CoAP version */
00043 #define COAP_MSG_MAX_TOKEN_LEN                 8                                /**< Maximum token length */
00044 #define COAP_MSG_MAX_CODE_CLASS                7                                /**< Maximum code class */
00045 #define COAP_MSG_MAX_CODE_DETAIL               31                               /**< Maximum code detail */
00046 #define COAP_MSG_MAX_MSG_ID                    ((1 << 16) - 1)                  /**< Maximum message ID */
00047 
00048 #define COAP_MSG_OP_URI_PATH_NUM               11                               /**< Uri-path option number */
00049 #define COAP_MSG_OP_URI_PATH_MAX_LEN           256                              /**< Maximum buffer length for a reconstructed URI path */
00050 
00051 #define COAP_MSG_MAX_BUF_LEN                   1152                             /**< Maximum buffer length for header and payload */
00052 
00053 #define coap_msg_op_num_is_critical(num)       ((num) & 1)                      /**< Indicate if an option is critical */
00054 #define coap_msg_op_num_is_unsafe(num)         ((num) & 2)                      /**< Indicate if an option is unsafe to forward */
00055 #define coap_msg_op_num_no_cache_key(num)      ((num & 0x1e) == 0x1c)           /**< Indicate if an option is not part of the cache key */
00056 
00057 #define coap_msg_op_get_num(op)                ((op)->num)                      /**< Get the option number from an option */
00058 #define coap_msg_op_set_num(op, num)           ((op)->num = (num))              /**< Set the option number in an option */
00059 #define coap_msg_op_get_len(op)                ((op)->len)                      /**< Get the option length from an option */
00060 #define coap_msg_op_set_len(op, len)           ((op)->len = (len))              /**< Set the option length in an option */
00061 #define coap_msg_op_get_val(op)                ((op)->val)                      /**< Get the option value from an option */
00062 #define coap_msg_op_set_val(op, val)           ((op)->val = (val))              /**< Set the option value in an option */
00063 #define coap_msg_op_get_next(op)               ((op)->next)                     /**< Get the next pointer from an option */
00064 #define coap_msg_op_set_next(op, next_op)      ((op)->next = (next_op))         /**< Set the next pointer in an option */
00065 
00066 #define coap_msg_get_ver(msg)                  ((msg)->ver)                     /**< Get the version from a message */
00067 #define coap_msg_get_type(msg)                 ((msg)->type)                    /**< Get the type from a message */
00068 #define coap_msg_get_token_len(msg)            ((msg)->token_len)               /**< Get the token length from a message */
00069 #define coap_msg_get_code_class(msg)           ((msg)->code_class)              /**< Get the code class from a message */
00070 #define coap_msg_get_code_detail(msg)          ((msg)->code_detail)             /**< Get the code detail from a message */
00071 #define coap_msg_get_msg_id(msg)               ((msg)->msg_id)                  /**< Get the message ID from message */
00072 #define coap_msg_get_token(msg)                ((msg)->token)                   /**< Get the token from a message */
00073 #define coap_msg_get_first_op(msg)             ((msg)->op_list.first)           /**< Get the first option from a message */
00074 #define coap_msg_get_payload(msg)              ((msg)->payload)                 /**< Get the payload from a message */
00075 #define coap_msg_get_payload_len(msg)          ((msg)->payload_len)             /**< Get the payload length from a message */
00076 #define coap_msg_is_empty(msg)                 (((msg)->code_class == 0) && ((msg)->code_detail == 0))
00077                                                                                 /**< Indicate if a message is empty */
00078 
00079 /**
00080  *  @brief Message type enumeration
00081  */
00082 typedef enum
00083 {
00084     COAP_MSG_CON = 0x0,                                                         /**< Confirmable message */
00085     COAP_MSG_NON = 0x1,                                                         /**< Non-confirmable message */
00086     COAP_MSG_ACK = 0x2,                                                         /**< Acknowledgement message */
00087     COAP_MSG_RST = 0x3                                                          /**< Reset message */
00088 }
00089 coap_msg_type_t;
00090 
00091 /**
00092  *  @brief Code class enumeration
00093  */
00094 typedef enum
00095 {
00096     COAP_MSG_REQ = 0,                                                           /**< Request */
00097     COAP_MSG_SUCCESS = 2,                                                       /**< Success response */
00098     COAP_MSG_CLIENT_ERR = 4,                                                    /**< Client error response */
00099     COAP_MSG_SERVER_ERR = 5,                                                    /**< Server error response */
00100 }
00101 coap_msg_class_t;
00102 
00103 /**
00104  *  @brief Code detail enumeration
00105  */
00106 typedef enum
00107 {
00108     COAP_MSG_GET = 1,                                                           /**< Get request method */
00109     COAP_MSG_POST = 2,                                                          /**< Post request method */
00110     COAP_MSG_PUT = 3,                                                           /**< Put request method */
00111     COAP_MSG_DELETE =4                                                          /**< Delete request method */
00112 }
00113 coap_msg_method_t;
00114 
00115 /**
00116  *  @brief Success response code detail enumeration
00117  */
00118 typedef enum
00119 {
00120     COAP_MSG_CREATED = 1,                                                       /**< Created success response */
00121     COAP_MSG_DELETED = 2,                                                       /**< Deleted success response */
00122     COAP_MSG_VALID = 3,                                                         /**< Valid success response */
00123     COAP_MSG_CHANGED = 4,                                                       /**< Changed success response */
00124     COAP_MSG_CONTENT = 5                                                        /**< Content success response */
00125 }
00126 coap_msg_success_t;
00127 
00128 /**
00129  *  @brief Client error response code detail enumeration
00130  */
00131 typedef enum
00132 {
00133     COAP_MSG_BAD_REQ = 0,                                                       /**< Bad request client error */
00134     COAP_MSG_UNAUTHORIZED = 1,                                                  /**< Unauthorized client error */
00135     COAP_MSG_BAD_OPTION = 2,                                                    /**< Bad option client error */
00136     COAP_MSG_FORBIDDEN = 3,                                                     /**< Forbidden client error */
00137     COAP_MSG_NOT_FOUND = 4,                                                     /**< Not found client error */
00138     COAP_MSG_METHOD_NOT_ALLOWED = 5,                                            /**< Method not allowed client error */
00139     COAP_MSG_NOT_ACCEPTABLE = 6,                                                /**< Not acceptable client error */
00140     COAP_MSG_PRECOND_FAILED = 12,                                               /**< Precondition failed client error */
00141     COAP_MSG_REQ_ENT_TOO_LARGE = 13,                                            /**< Request entity too large client error */
00142     COAP_MSG_UNSUP_CONT_FMT = 15                                                /**< Unsupported content-format client error */
00143 }
00144 coap_msg_client_err_t;
00145 
00146 /**
00147  *  @brief Server error response code detail enumeration
00148  */
00149 typedef enum
00150 {
00151     COAP_MSG_INT_SERVER_ERR = 0,                                                /**< Internal server error */
00152     COAP_MSG_NOT_IMPL = 1,                                                      /**< Not implemented server error */
00153     COAP_MSG_BAD_GATEWAY = 2,                                                   /**< Bad gateway server error */
00154     COAP_MSG_SERV_UNAVAIL = 3,                                                  /**< Service unavailable server error */
00155     COAP_MSG_GATEWAY_TIMEOUT = 4,                                               /**< Gateway timeout server error */
00156     COAP_MSG_PROXY_NOT_SUP = 5                                                  /**< Proxying not supported server error */
00157 }
00158 coap_msg_server_err_t;
00159 
00160 /**
00161  *  @brief Option number enumeration
00162  */
00163 typedef enum
00164 {
00165     COAP_MSG_IF_MATCH = 1,                                                      /**< If-Match option number */
00166     COAP_MSG_URI_HOST = 3,                                                      /**< URI-Host option number */
00167     COAP_MSG_ETAG = 4,                                                          /**< Entity-Tag option number */
00168     COAP_MSG_IF_NONE_MATCH = 5,                                                 /**< If-None-Match option number */
00169     COAP_MSG_URI_PORT = 7,                                                      /**< URI-Port option number */
00170     COAP_MSG_LOCATION_PATH = 8,                                                 /**< Location-Path option number */
00171     COAP_MSG_URI_PATH = 11,                                                     /**< URI-Path option number */
00172     COAP_MSG_CONTENT_FORMAT = 12,                                               /**< Content-Format option number */
00173     COAP_MSG_MAX_AGE = 14,                                                      /**< Max-Age option number */
00174     COAP_MSG_URI_QUERY = 15,                                                    /**< URI-Query option number */
00175     COAP_MSG_ACCEPT = 17,                                                       /**< Accept option number */
00176     COAP_MSG_LOCATION_QUERY = 20,                                               /**< Location-Query option number */
00177     COAP_MSG_PROXY_URI = 35,                                                    /**< Proxy-URI option number */
00178     COAP_MSG_PROXY_SCHEME = 39,                                                 /**< Proxy-Scheme option number */
00179     COAP_MSG_SIZE1 = 60                                                         /**< Size1 option number */
00180 }
00181 coap_msg_op_num_t;
00182 
00183 /**
00184  *  @brief Option structure
00185  */
00186 typedef struct coap_msg_op
00187 {
00188     unsigned num;                                                               /**< Option number */
00189     unsigned len;                                                               /**< Option length */
00190     char *val;                                                                  /**< Pointer to a buffer containing the option value */
00191     struct coap_msg_op *next;                                                   /**< Pointer to the next option structure in the list */
00192 }
00193 coap_msg_op_t;
00194 
00195 /**
00196  *  @brief Option linked-list structure
00197  */
00198 typedef struct
00199 {
00200     coap_msg_op_t *first;                                                       /**< Pointer to the first option structure in the list */
00201     coap_msg_op_t *last;                                                        /**< Pointer to the last option structure in the list */
00202 }
00203 coap_msg_op_list_t;
00204 
00205 /**
00206  *  @brief Message structure
00207  */
00208 typedef struct
00209 {
00210     unsigned ver;                                                               /**< CoAP version */
00211     coap_msg_type_t type;                                                       /**< Message type */
00212     unsigned token_len;                                                         /**< Token length */
00213     unsigned code_class;                                                        /**< Code class */
00214     unsigned code_detail;                                                       /**< Code detail */
00215     unsigned msg_id;                                                            /**< Message ID */
00216     char token[COAP_MSG_MAX_TOKEN_LEN];                                         /**< Token value */
00217     coap_msg_op_list_t op_list;                                                 /**< Option list */
00218     char *payload;                                                              /**< Pointer to a buffer containing the payload */
00219     size_t payload_len;                                                         /**< Length of the payload */
00220 }
00221 coap_msg_t;
00222 
00223 /**
00224  *  @brief Check if option is recognized
00225  *
00226  *  @param[in] num Option number
00227  *
00228  *  @returns Operation status
00229  *  @retval 1 Option is recognized
00230  *  @retval 0 Option is not recognized
00231  */
00232 int coap_msg_op_num_is_recognized(unsigned num);
00233 
00234 /**
00235  *  @brief Generate a random string of bytes
00236  *
00237  *  @param[out] buf Pointer to the buffer to store the random string
00238  *  @param[in] len Length of the buffer
00239  */
00240 void coap_msg_gen_rand_str(char *buf, size_t len);
00241 
00242 /**
00243  *  @brief Initialise a message structure
00244  *
00245  *  @param[out] msg Pointer to a message structure
00246  */
00247 void coap_msg_create(coap_msg_t *msg);
00248 
00249 /**
00250  *  @brief Deinitialise a message structure
00251  *
00252  *  @param[in,out] msg Pointer to a message structure
00253  */
00254 void coap_msg_destroy(coap_msg_t *msg);
00255 
00256 /**
00257  *  @brief Deinitialise and initialise a message structure
00258  *
00259  *  @param[in,out] msg Pointer to a message structure
00260  */
00261 void coap_msg_reset(coap_msg_t *msg);
00262 
00263 /**
00264  *  @brief Check that all of the critical options in a message are recognized
00265  *
00266  *  @param[in] msg Pointer to message structure
00267  *
00268  *  @returns Operation status or bad option number
00269  *  @retval 0 Success
00270  *  @retval >0 Bad option number
00271  */
00272 unsigned coap_msg_check_critical_ops(coap_msg_t *msg);
00273 
00274 /**
00275  *  @brief Check that all of the unsafe options in a message are recognized
00276  *
00277  *  @param[in] msg Pointer to message structure
00278  *
00279  *  @returns Operation status or bad option number
00280  *  @retval 0 Success
00281  *  @retval >0 Bad option number
00282  */
00283 unsigned coap_msg_check_unsafe_ops(coap_msg_t *msg);
00284 
00285 /**
00286  *  @brief Extract the type and message ID values from a message
00287  *
00288  *  If a message contains a format error, this function
00289  *  will attempt to extract the type and message ID so
00290  *  that a reset message can be returned to the sender.
00291  *
00292  *  @param[in] buf Pointer to a buffer containing the message
00293  *  @param[in] len Length of the buffer
00294  *  @param[out] type Pointer to field to store the type value
00295  *  @param[out] msg_id Pointer to a field to store the message ID value
00296  *
00297  *  @returns Operation status
00298  *  @retval 0 Success
00299  *  @retval <0 Error
00300  */
00301 int coap_msg_parse_type_msg_id(char *buf, size_t len, unsigned *type, unsigned *msg_id);
00302 
00303 /**
00304  *  @brief Parse a message
00305  *
00306  *  @param[in,out] msg Pointer to a message structure
00307  *  @param[in] buf Pointer to a buffer containing the message
00308  *  @param[in] len Length of the buffer
00309  *
00310  *  @returns Operation status
00311  *  @retval 0 Success
00312  *  @retval <0 Error
00313  */
00314 int coap_msg_parse(coap_msg_t *msg, char *buf, size_t len);
00315 
00316 /**
00317  *  @brief Set the type in a message
00318  *
00319  *  @param[out] msg Pointer to a message structure
00320  *  @param[in] type Message type
00321  *
00322  *  @returns Operation status
00323  *  @retval 0 Success
00324  *  @retval <0 Error
00325  */
00326 int coap_msg_set_type(coap_msg_t *msg, unsigned type);
00327 
00328 /**
00329  *  @brief Set the code in a message
00330  *
00331  *  @param[out] msg Pointer to a message structure
00332  *  @param[in] code_class Code class
00333  *  @param[in] code_detail Code detail
00334  *
00335  *  @returns Operation status
00336  *  @retval 0 Success
00337  *  @retval <0 Error
00338  */
00339 int coap_msg_set_code(coap_msg_t *msg, unsigned code_class, unsigned code_detail);
00340 
00341 /**
00342  *  @brief Set the message ID in a message
00343  *
00344  *  @param[out] msg Pointer to a message structure
00345  *  @param[in] msg_id Message ID
00346  *
00347  *  @returns Operation status
00348  *  @retval 0 Success
00349  *  @retval <0 Error
00350  */
00351 int coap_msg_set_msg_id(coap_msg_t *msg, unsigned msg_id);
00352 
00353 /**
00354  *  @brief Set the token in a message
00355  *
00356  *  @param[out] msg Pointer to a message structure
00357  *  @param[in] buf Pointer to a buffer containing the token
00358  *  @param[in] len Length of the buffer
00359  *
00360  *  @returns Operation status
00361  *  @retval 0 Success
00362  *  @retval <0 Error
00363  */
00364 int coap_msg_set_token(coap_msg_t *msg, char *buf, size_t len);
00365 
00366 /**
00367  *  @brief Add a token to a message structure
00368  *
00369  *  @param[in,out] msg Pointer to a message structure
00370  *  @param[in] num Option number
00371  *  @param[in] len Option length
00372  *  @param[in] val Pointer to a buffer containing the option value
00373  *
00374  *  @returns Operation status
00375  *  @retval 0 Success
00376  *  @retval <0 Error
00377  */
00378 int coap_msg_add_op(coap_msg_t *msg, unsigned num, unsigned len, const char *val);
00379 
00380 /**
00381  *  @brief Set the payload in a message
00382  *
00383  *  Free the buffer in the message structure containing
00384  *  the current payload if there is one, allocate a buffer
00385  *  to contain the new payload and copy the buffer argument
00386  *  into the new payload buffer.
00387  *
00388  *  @param[in,out] msg Pointer to a message structure
00389  *  @param[in] buf Pointer to a buffer containing the payload
00390  *  @param[in] len Length of the buffer
00391  *
00392  *  @returns Operation status
00393  *  @retval 0 Success
00394  *  @retval <0 Error
00395  */
00396 int coap_msg_set_payload(coap_msg_t *msg, char *buf, size_t len);
00397 
00398 /**
00399  *  @brief Format a message
00400  *
00401  *  @param[in] msg Pointer to a message structure
00402  *  @param[out] buf Pointer to a buffer to contain the formatted message
00403  *  @param[in] len Length of the buffer
00404  *
00405  *  @returns Length of the formatted message or error code
00406  *  @retval >0 Length of the formatted message
00407  *  @retval <0 Error
00408  */
00409 int coap_msg_format(coap_msg_t *msg, char *buf, size_t len);
00410 
00411 /**
00412  *  @brief Copy a message
00413  *
00414  *  @param[in,out] dst Pointer to the destination message structure
00415  *  @param[in] src Pointer to the source message structure
00416  *
00417  *  @returns Operation status
00418  *  @retval 0 Success
00419  *  @retval <0 Error
00420  */
00421 int coap_msg_copy(coap_msg_t *dst, coap_msg_t *src);
00422 
00423 #endif
00424