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