coap_address

NAME

coap_address, coap_address_t, coap_address_init - Work with CoAP Socket Address Types

SYNOPSIS

#include <coap3/coap.h>

void coap_address_init(coap_address_t *addr);

coap_addr_info_t *coap_resolve_address_info(const coap_str_const_t *server, uint16_t port, uint16_t secure_port, int ai_hints_flags, int scheme_hint_bits);

void coap_free_address_info(coap_addr_info_t *info_list);

int coap_address_set_unix_domain(coap_address_t *addr, const uint8_t *host, size_t host_len);

For specific (D)TLS library support, link with -lcoap-3-notls, -lcoap-3-gnutls, -lcoap-3-openssl, -lcoap-3-mbedtls or -lcoap-3-tinydtls. Otherwise, link with -lcoap-3 to get the default (D)TLS library support.

DESCRIPTION

This man page focuses on setting up CoAP endpoint address definitions.

Supported Socket Types

Libcoap supports 3 different socket types that can be used:

AF_INET  IPv4 IP addresses and ports
AF_INET6 IPv6 IP addresses and ports and can be dual IPv4/IPv6 stacked
AF_UNIX  Unix Domain using file path names

which are all handled by the coap_address_t structure.

Structure coap_address_t

/* Multi-purpose address abstraction */
typedef struct coap_address_t {
  socklen_t size;           /* size of addr */
  union {
    struct sockaddr         sa;
    struct sockaddr_in      sin;
    struct sockaddr_in6     sin6;
    struct coap_sockaddr_un cun; /* CoAP shortened special */
  } addr;
} coap_address_t;

which is used in the *coap_addr_info_t* structure as returned by
*coap_resolve_address_info()*.

*Structure coap_addr_info_t*

[source, c]

/* Resolved addresses information / typedef struct coap_addr_info_t { struct coap_addr_info_t *next; / Next entry in the chain / coap_uri_scheme_t scheme; / CoAP scheme to use / coap_address_t addr; / The address to connect / bind to */ } coap_addr_info_t;

*Structure coap_sockaddr_un*

[source, c]

#define COAP_UNIX_PATH_MAX (sizeof(struct sockaddr_in6) - sizeof(sa_family_t))

struct coap_sockaddr_un { sa_family_t sun_family; /* AF_UNIX / char sun_path[COAP_UNIX_PATH_MAX]; / pathname max 26 with NUL byte */ };

The *coap_sockaddr_un* structure is modeled on the *sockaddr_un* structure
(see *unix*(7)) but has a smaller sun_path so that the overall size of
*coap_address_t* is not changed by its inclusion. COAP_UNIX_MAX_PATH includes
the trailing zero terminator of a domain unix file name.

FUNCTIONS

Function: coap_address_init()

The coap_address_init() function initializes addr for later use. In particular it sets the size variable and sets all other values to be 0.

It is then the responsibility of the application to set the address family in addr.sa.sa_family and then fill in the the appropriate union structure based on the address family before the coap_address_t addr is used.

Function: coap_resolve_address_info()

The coap_resolve_address_info() function resolves the address server into a set of one or more coap_addr_info_t structures. Depending on the scheme as abstracted from scheme_hint_bits either port or secure_port is used to update the addr variable of coap_addr_info_t. If port (or secure_port) is 0, then the default port for the scheme is used. ai_hints_flags is used for the internally called getaddrinfo(3) function. scheme_hint_bits is a set of one or more COAP_URI_SCHEME_*_BIT or’d together.

The returned set of coap_addr_info_t structures must be freed off by the caller using coap_free_address_info().

Function: coap_free_address_info()

The coap_free_address_info() function frees off all the info_list linked entries.

Function: coap_address_set_unix_domain()

The coap_address_set_unix_domain() function initializes addr and then populates addr with all the appropriate information for a Unix Domain Socket. The host information with length host_len abstracted from a CoAP URI is copied into addr's sun_path translating any %2F encoding to /.

RETURN VALUES

coap_resolve_address_info() returns a linked list of addresses that can be used for session setup or NULL if there is a failure.

coap_address_set_unix_domain() function returns 1 on success or 0 on failure.

EXAMPLES

Get target address from uri

#include <coap3/coap.h>

static int
get_address(coap_uri_t *uri, coap_address_t *dst) {
  coap_addr_info_t *info_list;

   info_list = coap_resolve_address_info(&uri->host, uri->port, uri->port, 0,
                                         1 << uri->scheme);
   if (info_list == NULL)
     return 0;
   memcpy(dst, &info_list->addr, sizeof(*dst));
   coap_free_address_info(info_list);
   return 1;
}

FURTHER INFORMATION

See

"RFC7252: The Constrained Application Protocol (CoAP)"

for further information.

BUGS

Please report bugs on the mailing list for libcoap: libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at https://github.com/obgm/libcoap/issues

AUTHORS

The libcoap project <libcoap-developers@lists.sourceforge.net>

coap_address_t(3)