1COAP_ADDRESS(3) libcoap Manual COAP_ADDRESS(3)
2
6 coap_address, coap_address_t, coap_address_init, coap_address_copy,
7 coap_address_equals, coap_address_get_port, coap_address_set_port,
8 coap_get_available_scheme_hint_bits, coap_resolve_address_info,
9 coap_free_address_info, coap_sockaddr_un, coap_address_set_unix_domain,
10 coap_host_is_unix_domain, coap_is_bcast, coap_is_mcast, coap_is_af_unix
11 - Work with CoAP Socket Address Types
12
14 #include <coap3/coap.h>
15 struct coap_address_t;
17 struct coap_sockaddr_un;
19 void coap_address_init(coap_address_t *addr);
21 void coap_address_copy(coap_address_t *dst, const coap_address_t *src);
23 int coap_address_equals(const coap_address_t *a, const coap_address_t
25 *b);
26 uint16_t coap_address_get_port(const coap_address_t *addr);
28 void coap_address_set_port(coap_address_t *addr, uint16_t port);
30 uint32_t coap_get_available_scheme_hint_bits(int have_pki_psk, int
32 ws_check, coap_proto_t use_unix_proto);
33 coap_addr_info_t *coap_resolve_address_info(const coap_str_const_t
35 *address, uint16_t port, uint16_t secure_port, uint16_t ws_port,
36 uint16_t ws_secure_port, int ai_hints_flags, int scheme_hint_bits,
37 coap_resolve_type_t type);
38 void coap_free_address_info(coap_addr_info_t *info_list);
40 int coap_host_is_unix_domain(const coap_str_const_t *host);
42 int coap_address_set_unix_domain(coap_address_t *addr, const uint8_t
44 *host, size_t host_len);
45 int coap_is_bcast(const coap_address_t *addr);
47 int coap_is_mcast(const coap_address_t *addr);
49 int coap_is_af_unix(const coap_address_t *addr);
51 For specific (D)TLS library support, link with -lcoap-3-notls,
53 -lcoap-3-gnutls, -lcoap-3-openssl, -lcoap-3-mbedtls or
54 -lcoap-3-tinydtls. Otherwise, link with -lcoap-3 to get the default
55 (D)TLS library support.
56
58 This man page focuses on setting up CoAP endpoint address definitions.
59 Supported Socket Types
61 Libcoap supports 3 different socket types that can be used:
63 AF_INET IPv4 IP addresses and ports
65 AF_INET6 IPv6 IP addresses and ports and can be dual IPv4/IPv6 stacked
66 AF_UNIX Unix Domain using file path names
67 which are all handled by the coap_address_t structure.
69 Structure coap_address_t
71 /* Multi-purpose address abstraction */
73 typedef struct coap_address_t {
74 socklen_t size; /* size of addr */
75 union {
76 struct sockaddr sa;
77 struct sockaddr_in sin;
78 struct sockaddr_in6 sin6;
79 struct coap_sockaddr_un cun; /* CoAP shortened special */
80 } addr;
81 } coap_address_t;
82 which is used in the *coap_addr_info_t* structure as returned by
84 *coap_resolve_address_info()*.
85 Structure coap_addr_info_t
87 /* Resolved addresses information */
89 typedef struct coap_addr_info_t {
90 struct coap_addr_info_t *next; /* Next entry in the chain */
91 coap_uri_scheme_t scheme; /* CoAP scheme to use */
92 coap_proto_t proto; /* CoAP protocol to use */
93 coap_address_t addr; /* The address to connect / bind to */
94 } coap_addr_info_t;
95 Structure coap_sockaddr_un
97 #define COAP_UNIX_PATH_MAX (sizeof(struct sockaddr_in6) - sizeof(sa_family_t))
99 struct coap_sockaddr_un {
101 sa_family_t sun_family; /* AF_UNIX */
102 char sun_path[COAP_UNIX_PATH_MAX]; /* pathname max 26 with NUL byte */
103 };
104 The coap_sockaddr_un structure is modeled on the sockaddr_un structure
106 (see unix(7)) but has a smaller sun_path so that the overall size of
107 coap_address_t is not changed by its inclusion. COAP_UNIX_MAX_PATH
108 includes the trailing zero terminator of a domain unix file name.
109 Enum coap_resolve_type_t
111 typedef enum coap_resolve_type_t {
113 COAP_RESOLVE_TYPE_LOCAL, /* local side of session */
114 COAP_RESOLVE_TYPE_REMOTE, /* remote side of session */
115 } coap_resolve_type_t;
116 Used when determining how to do an address lookup when calling
118 coap_resolve_address_info().
119
121 Function: coap_address_init()
122 The coap_address_init() function initializes addr for later use. In
124 particular it sets the size variable and sets all other values to be 0.
125 It is then the responsibility of the application to set the address
127 family in addr.sa.sa_family and then fill in the the appropriate union
128 structure based on the address family before the coap_address_t addr is
129 used.
130 Function: coap_address_copy()
132 The coap_address_copy() function copies the address src into dst.
134 Function: coap_address_equals()
136 The coap_address_equals() function checks whether the addresses a and b
138 are identical.
139 Function: coap_address_get_port()
141 The coap_address_get_port() function gets the the port from addr if
143 addr is AF_INET or AF_INET6.
144 Function: coap_address_set_port()
146 The coap_address_set_port() function sets the the port in addr if addr
148 is AF_INET or AF_INET6.
149 Function: coap_get_available_scheme_hint_bits()
151 The coap_get_available_scheme_hint_bits() function is used for servers
153 to determine what coap schemes are supported in the underlying libcoap
154 library. have_pki_psk can be set to 1 to check for (D)DTLS support,
155 else 0. ws_check can be set to 1 to check for WebSockets support, else
156 0. use_unix_proto, if not set to COAP_PROTO_NONE, hints at the specific
157 CoAP protocol to use over a Unix socket. The output is suitable for
158 input for the coap_address_resolve_info()'s scheme_hint_bits.
159 Function: coap_resolve_address_info()
161 The coap_resolve_address_info() function resolves the address address
163 into a set of one or more coap_addr_info_t structures. Depending on the
164 scheme as abstracted from scheme_hint_bits, port, secure_port, ws_port
165 (WebSockets) or ws_secure_port (WebSockets) is used to update the addr
166 variable of coap_addr_info_t. If port (or secure_port) is 0, then the
167 default port for the scheme is used if type is set to
168 COAP_RESOLVE_TYPE_LOCAL. ai_hints_flags is used for the internally
169 called getaddrinfo(3) function. scheme_hint_bits is a set of one or
170 more COAP_URI_SCHEME_*BIT or’d together. _scheme_hint_bits can also
171 (for servers) be the output from coap_get_available_scheme_hint_bits().
172 The returned set of coap_addr_info_t structures must be freed off by
174 the caller using coap_free_address_info().
175 Function: coap_free_address_info()
177 The coap_free_address_info() function frees off all the info_list
179 linked entries.
180 Function: coap_address_set_unix_domain()
182 The coap_address_set_unix_domain() function initializes addr and then
184 populates addr with all the appropriate information for a Unix Domain
185 Socket. The host information with length host_len abstracted from a
186 CoAP URI is copied into addr's sun_path translating any %2F encoding to
187 /.
188 Function: coap_host_is_unix_domain()
190 The coap_host_is_unix_domain() function checks whether host is an an
192 AF_UNIX file name (encoded using %2F to indicate a /).
193 Function: coap_is_mcast()
195 The coap_is_mcast() function checks whether addr is a multicast
197 address.
198 Function: coap_is_bcast()
200 The coap_is_mcast() function checks whether addr is a broadcast
202 address.
203 Function: coap_is_af_unix()
205 The coap_is_mcast() function checks whether addr is of the type
207 AF_UNIX.
208
210 coap_address_equals() returns 1 if the addresses are equal or 0 if not.
211 coap_address_get_port() returns the port in network byte order.
213 coap_get_available_scheme_hint_bits() returns a set of
215 COAP_URI_SCHEME_*_BIT or’d together based on the supported libcoap
216 functionality.
217 coap_resolve_address_info() returns a linked list of addresses that can
219 be used for session setup or NULL if there is a failure.
220 coap_address_set_unix_domain() returns 1 on success or 0 on failure.
222 coap_host_is_unix_domain() returns 1 if encoded unix path name or 0 if
224 not.
225 coap_is_mcast() returns 1 if address is multicast or 0 if not.
227 coap_is_bcast() returns 1 if address is broadcast or 0 if not.
229 coap_is_af_unix() returns 1 if address is of type AF_UNIX or 0 if not.
231
233 Get client target address from uri
234 #include <coap3/coap.h>
236 static int
238 get_address(coap_uri_t *uri, coap_address_t *dst) {
239 coap_addr_info_t *info_list;
240 info_list = coap_resolve_address_info(&uri->host, uri->port, uri->port,
242 uri->port, uri->port,0,
243 1 << uri->scheme, COAP_RESOLVE_TYPE_LOCAL);
244 if (info_list == NULL)
245 return 0;
246 memcpy(dst, &info_list->addr, sizeof(*dst));
247 coap_free_address_info(info_list);
248 return 1;
249 }
250
252 coap_endpoint_client(3), coap_endpoint_server(3) and coap_uri(3)
253
255 See
256 "RFC7252: The Constrained Application Protocol (CoAP)"
258 for further information.
260
262 Please report bugs on the mailing list for libcoap:
263 libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
264 https://github.com/obgm/libcoap/issues
265
267 The libcoap project <libcoap-developers@lists.sourceforge.net>
268coap_address 4.3.4 10/09/2023 COAP_ADDRESS(3)