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 */
30 extern 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 */
37 extern 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 */
58 unsigned 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 */
69 uint64_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 */
84 unsigned 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 */
101 unsigned 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 */
122 COAP_STATIC_INLINE COAP_DEPRECATED int
coap_encode_var_bytes(uint8_t * buf,unsigned int value)123 coap_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