1/*
2 * encode.h -- encoding and decoding of CoAP data types
3 *
4 * Copyright (C) 2010-2012 Olaf Bergmann <bergmann@tzi.org>
5 *
6 * SPDX-License-Identifier: BSD-2-Clause
7 *
8 * This file is part of the CoAP library libcoap. Please see README for terms
9 * of use.
10 */
11
12/**
13 * @file coap_encode.h
14 * @brief Encoding and decoding of CoAP data types
15 */
16
17#ifndef COAP_ENCODE_H_
18#define COAP_ENCODE_H_
19
20#if (BSD >= 199103) || defined(WITH_CONTIKI) || defined(_WIN32)
21# include <string.h>
22#else
23# include <strings.h>
24#endif
25
26#include <stdint.h>
27
28#ifndef HAVE_FLS
29/* include this only if fls() is not available */
30extern int coap_fls(unsigned int i);
31#else
32#define coap_fls(i) fls(i)
33#endif
34
35#ifndef HAVE_FLSLL
36/* include this only if flsll() is not available */
37extern int coap_flsll(long long i);
38#else
39#define coap_flsll(i) flsll(i)
40#endif
41
42/**
43 * @ingroup application_api
44 * @defgroup encode Encode / Decode API
45 * API for endoding/decoding CoAP options.
46 * @{
47 */
48
49/**
50 * Decodes multiple-length byte sequences. @p buf points to an input byte
51 * sequence of length @p length. Returns the up to 4 byte decoded value.
52 *
53 * @param buf The input byte sequence to decode from
54 * @param length The length of the input byte sequence
55 *
56 * @return      The decoded value
57 */
58unsigned int coap_decode_var_bytes(const uint8_t *buf, size_t length);
59
60/**
61 * Decodes multiple-length byte sequences. @p buf points to an input byte
62 * sequence of length @p length. Returns the up to 8 byte decoded value.
63 *
64 * @param buf The input byte sequence to decode from
65 * @param length The length of the input byte sequence
66 *
67 * @return      The decoded value
68 */
69uint64_t coap_decode_var_bytes8(const uint8_t *buf, size_t length);
70
71/**
72 * Encodes multiple-length byte sequences. @p buf points to an output buffer of
73 * sufficient length to store the encoded bytes. @p value is the 4 byte value
74 * to encode.
75 * Returns the number of bytes used to encode @p value or 0 on error.
76 *
77 * @param buf    The output buffer to encode into
78 * @param length The output buffer size to encode into (must be sufficient)
79 * @param value  The value to encode into the buffer
80 *
81 * @return       The number of bytes used to encode @p value (which can be 0
82 *               when encoding value of 0) or @c 0 on error.
83 */
84unsigned int coap_encode_var_safe(uint8_t *buf,
85                                  size_t length,
86                                  unsigned int value);
87
88/**
89 * Encodes multiple-length byte sequences. @p buf points to an output buffer of
90 * sufficient length to store the encoded bytes. @p value is the 8 byte value
91 * to encode.
92 * Returns the number of bytes used to encode @p value or 0 on error.
93 *
94 * @param buf    The output buffer to encode into
95 * @param length The output buffer size to encode into (must be sufficient)
96 * @param value  The value to encode into the buffer
97 *
98 * @return       The number of bytes used to encode @p value (which can be 0
99 *               when encoding value of 0) or @c 0 on error.
100 */
101unsigned int coap_encode_var_safe8(uint8_t *buf,
102                                   size_t length,
103                                   uint64_t value);
104
105/** @} */
106
107/**
108 * @deprecated Use coap_encode_var_safe() instead.
109 * Provided for backward compatibility.  As @p value has a
110 * maximum value of 0xffffffff, and buf is usually defined as an array, it
111 * is unsafe to continue to use this variant if buf[] is less than buf[4].
112 *
113 * For example
114 *  char buf[1],oops;
115 *  ..
116 *  coap_encode_var_bytes(buf, 0xfff);
117 * would cause oops to get overwritten.  This error can only be found by code
118 * inspection.
119 *   coap_encode_var_safe(buf, sizeof(buf), 0xfff);
120 * would catch this error at run-time and should be used instead.
121 */
122COAP_STATIC_INLINE COAP_DEPRECATED int
123coap_encode_var_bytes(uint8_t *buf, unsigned int value) {
124  return (int)coap_encode_var_safe(buf, sizeof(value), value);
125}
126
127#endif /* COAP_ENCODE_H_ */
128