1// -*- mode:doc; -*- 2// vim: set syntax=asciidoc tw=0 3 4coap_address(3) 5=============== 6:doctype: manpage 7:man source: coap_address 8:man version: @PACKAGE_VERSION@ 9:man manual: libcoap Manual 10 11NAME 12---- 13coap_address, 14coap_address_t, 15coap_address_init, 16coap_address_copy, 17coap_address_equals, 18coap_address_get_port, 19coap_address_set_port, 20coap_get_available_scheme_hint_bits, 21coap_resolve_address_info, 22coap_free_address_info, 23coap_sockaddr_un, 24coap_address_set_unix_domain, 25coap_host_is_unix_domain, 26coap_is_bcast, 27coap_is_mcast, 28coap_is_af_unix 29- Work with CoAP Socket Address Types 30 31SYNOPSIS 32-------- 33*#include <coap@LIBCOAP_API_VERSION@/coap.h>* 34 35*struct coap_address_t;* 36 37*struct coap_sockaddr_un;* 38 39*void coap_address_init(coap_address_t *_addr_);* 40 41*void coap_address_copy(coap_address_t *_dst_, const coap_address_t *_src_);* 42 43*int coap_address_equals(const coap_address_t *_a_, const coap_address_t *_b_);* 44 45*uint16_t coap_address_get_port(const coap_address_t *_addr_);* 46 47*void coap_address_set_port(coap_address_t *_addr_, uint16_t _port_);* 48 49*uint32_t coap_get_available_scheme_hint_bits(int _have_pki_psk_, 50int _ws_check_, coap_proto_t _use_unix_proto_);* 51 52*coap_addr_info_t *coap_resolve_address_info(const coap_str_const_t *_address_, 53uint16_t _port_, uint16_t _secure_port_, uint16_t _ws_port_, 54uint16_t _ws_secure_port_, int _ai_hints_flags_, 55int _scheme_hint_bits_, coap_resolve_type_t _type_);* 56 57*void coap_free_address_info(coap_addr_info_t *_info_list_);* 58 59*int coap_host_is_unix_domain(const coap_str_const_t *_host_);* 60 61*int coap_address_set_unix_domain(coap_address_t *_addr_, 62const uint8_t *_host_, size_t _host_len_);* 63 64*int coap_is_bcast(const coap_address_t *_addr_);* 65 66*int coap_is_mcast(const coap_address_t *_addr_);* 67 68*int coap_is_af_unix(const coap_address_t *_addr_);* 69 70For specific (D)TLS library support, link with 71*-lcoap-@LIBCOAP_API_VERSION@-notls*, *-lcoap-@LIBCOAP_API_VERSION@-gnutls*, 72*-lcoap-@LIBCOAP_API_VERSION@-openssl*, *-lcoap-@LIBCOAP_API_VERSION@-mbedtls* 73or *-lcoap-@LIBCOAP_API_VERSION@-tinydtls*. Otherwise, link with 74*-lcoap-@LIBCOAP_API_VERSION@* to get the default (D)TLS library support. 75 76DESCRIPTION 77----------- 78This man page focuses on setting up CoAP endpoint address definitions. 79 80*Supported Socket Types* 81 82Libcoap supports 3 different socket types that can be used: 83 84[source, c] 85---- 86AF_INET IPv4 IP addresses and ports 87AF_INET6 IPv6 IP addresses and ports and can be dual IPv4/IPv6 stacked 88AF_UNIX Unix Domain using file path names 89---- 90 91which are all handled by the *coap_address_t* structure. 92 93*Structure coap_address_t* 94 95[source, c] 96---- 97/* Multi-purpose address abstraction */ 98typedef struct coap_address_t { 99 socklen_t size; /* size of addr */ 100 union { 101 struct sockaddr sa; 102 struct sockaddr_in sin; 103 struct sockaddr_in6 sin6; 104 struct coap_sockaddr_un cun; /* CoAP shortened special */ 105 } addr; 106} coap_address_t; 107 108which is used in the *coap_addr_info_t* structure as returned by 109*coap_resolve_address_info()*. 110---- 111 112*Structure coap_addr_info_t* 113 114[source, c] 115---- 116/* Resolved addresses information */ 117typedef struct coap_addr_info_t { 118 struct coap_addr_info_t *next; /* Next entry in the chain */ 119 coap_uri_scheme_t scheme; /* CoAP scheme to use */ 120 coap_proto_t proto; /* CoAP protocol to use */ 121 coap_address_t addr; /* The address to connect / bind to */ 122} coap_addr_info_t; 123---- 124 125*Structure coap_sockaddr_un* 126 127[source, c] 128---- 129#define COAP_UNIX_PATH_MAX (sizeof(struct sockaddr_in6) - sizeof(sa_family_t)) 130 131struct coap_sockaddr_un { 132 sa_family_t sun_family; /* AF_UNIX */ 133 char sun_path[COAP_UNIX_PATH_MAX]; /* pathname max 26 with NUL byte */ 134}; 135---- 136 137The *coap_sockaddr_un* structure is modeled on the *sockaddr_un* structure 138(see *unix*(7)) but has a smaller sun_path so that the overall size of 139*coap_address_t* is not changed by its inclusion. COAP_UNIX_MAX_PATH includes 140the trailing zero terminator of a domain unix file name. 141 142*Enum coap_resolve_type_t* 143 144[source, c] 145---- 146typedef enum coap_resolve_type_t { 147 COAP_RESOLVE_TYPE_LOCAL, /* local side of session */ 148 COAP_RESOLVE_TYPE_REMOTE, /* remote side of session */ 149} coap_resolve_type_t; 150---- 151 152Used when determining how to do an address lookup when calling 153*coap_resolve_address_info()*. 154 155FUNCTIONS 156--------- 157 158*Function: coap_address_init()* 159 160The *coap_address_init*() function initializes _addr_ for later use. In 161particular it sets the _size_ variable and sets all other values to be 0. 162 163It is then the responsibility of the application to set the address family 164in addr.sa.sa_family and then fill in the the appropriate union structure 165based on the address family before the coap_address_t _addr_ is used. 166 167*Function: coap_address_copy()* 168 169The *coap_address_copy*() function copies the address _src_ into _dst_. 170 171*Function: coap_address_equals()* 172 173The *coap_address_equals*() function checks whether the addresses _a_ and _b_ 174are identical. 175 176*Function: coap_address_get_port()* 177 178The *coap_address_get_port*() function gets the the port from _addr_ if 179_addr_ is AF_INET or AF_INET6. 180 181*Function: coap_address_set_port()* 182 183The *coap_address_set_port*() function sets the the _port_ in _addr_ if 184_addr_ is AF_INET or AF_INET6. 185 186*Function: coap_get_available_scheme_hint_bits()* 187 188The *coap_get_available_scheme_hint_bits*() function is used for servers to 189determine what coap schemes are supported in the underlying libcoap library. 190_have_pki_psk_ can be set to 1 to check for (D)DTLS support, else 0. 191_ws_check_ can be set to 1 to check for WebSockets support, else 0. 192_use_unix_proto_, if not set to COAP_PROTO_NONE, hints at the specific CoAP 193protocol to use over a Unix socket. The output is suitable for input for the 194*coap_address_resolve_info*()'s _scheme_hint_bits_. 195 196*Function: coap_resolve_address_info()* 197 198The *coap_resolve_address_info*() function resolves the address _address_ into 199a set of one or more coap_addr_info_t structures. Depending on the scheme as 200abstracted from _scheme_hint_bits_, _port_, _secure_port_, _ws_port_ 201(WebSockets) or _ws_secure_port_ (WebSockets) is used to 202update the addr variable of coap_addr_info_t. If _port_ (or _secure_port_) is 2030, then the default port for the scheme is used if _type_ is set to 204COAP_RESOLVE_TYPE_LOCAL. _ai_hints_flags_ is used for 205the internally called getaddrinfo(3) function. _scheme_hint_bits_ is a set of 206one or more COAP_URI_SCHEME_*_BIT or'd together. _scheme_hint_bits_ can also 207(for servers) be the output from *coap_get_available_scheme_hint_bits*(). 208 209The returned set of coap_addr_info_t structures must be freed off by the 210caller using *coap_free_address_info*(). 211 212*Function: coap_free_address_info()* 213 214The *coap_free_address_info*() function frees off all the _info_list_ 215linked entries. 216 217*Function: coap_address_set_unix_domain()* 218 219The *coap_address_set_unix_domain*() function initializes _addr_ and then 220populates _addr_ with all the appropriate information for a Unix Domain Socket. 221The _host_ information with length _host_len_ abstracted from a CoAP URI 222is copied into _addr_'s _sun_path_ translating any %2F encoding to /. 223 224*Function: coap_host_is_unix_domain()* 225 226The *coap_host_is_unix_domain*() function checks whether _host_ is an 227an AF_UNIX file name (encoded using %2F to indicate a /). 228 229*Function: coap_is_mcast()* 230 231The *coap_is_mcast*() function checks whether _addr_ is a multicast 232address. 233 234*Function: coap_is_bcast()* 235 236The *coap_is_mcast*() function checks whether _addr_ is a broadcast 237address. 238 239*Function: coap_is_af_unix()* 240 241The *coap_is_mcast*() function checks whether _addr_ is of the type AF_UNIX. 242 243RETURN VALUES 244------------- 245*coap_address_equals*() returns 1 if the addresses are equal or 0 if not. 246 247*coap_address_get_port*() returns the port in network byte order. 248 249*coap_get_available_scheme_hint_bits*() returns a set of COAP_URI_SCHEME_*_BIT 250or'd together based on the supported libcoap functionality. 251 252*coap_resolve_address_info*() returns a linked list of addresses that can be 253used for session setup or NULL if there is a failure. 254 255*coap_address_set_unix_domain*() returns 1 on success or 0 on failure. 256 257*coap_host_is_unix_domain*() returns 1 if encoded unix path name or 0 if not. 258 259*coap_is_mcast*() returns 1 if address is multicast or 0 if not. 260 261*coap_is_bcast*() returns 1 if address is broadcast or 0 if not. 262 263*coap_is_af_unix*() returns 1 if address is of type AF_UNIX or 0 if not. 264 265EXAMPLES 266-------- 267*Get client target address from uri* 268[source, c] 269---- 270#include <coap@LIBCOAP_API_VERSION@/coap.h> 271 272static int 273get_address(coap_uri_t *uri, coap_address_t *dst) { 274 coap_addr_info_t *info_list; 275 276 info_list = coap_resolve_address_info(&uri->host, uri->port, uri->port, 277 uri->port, uri->port,0, 278 1 << uri->scheme, COAP_RESOLVE_TYPE_LOCAL); 279 if (info_list == NULL) 280 return 0; 281 memcpy(dst, &info_list->addr, sizeof(*dst)); 282 coap_free_address_info(info_list); 283 return 1; 284} 285---- 286 287SEE ALSO 288-------- 289*coap_endpoint_client*(3), *coap_endpoint_server*(3) and *coap_uri*(3) 290 291FURTHER INFORMATION 292------------------- 293See 294 295"https://rfc-editor.org/rfc/rfc7252[RFC7252: The Constrained Application Protocol (CoAP)]" 296 297for further information. 298 299BUGS 300---- 301Please report bugs on the mailing list for libcoap: 302libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at 303https://github.com/obgm/libcoap/issues 304 305AUTHORS 306------- 307The libcoap project <libcoap-developers@lists.sourceforge.net> 308