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

/* 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_proto_t proto;            /* CoAP protocol to use */
  coap_address_t addr;           /* The address to connect / bind to */
} coap_addr_info_t;

Structure coap_sockaddr_un

#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.

Enum coap_resolve_type_t

typedef enum coap_resolve_type_t {
  COAP_RESOLVE_TYPE_LOCAL,   /* local side of session */
  COAP_RESOLVE_TYPE_REMOTE,  /* remote side of session */
} coap_resolve_type_t;

Used when determining how to do an address lookup when calling coap_resolve_address_info().

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_address_copy()

The coap_address_copy() function copies the address src into dst.

Function: coap_address_equals()

The coap_address_equals() function checks whether the addresses a and b are identical.

Function: coap_address_get_port()

The coap_address_get_port() function gets the the port from addr if addr is AF_INET or AF_INET6.

Function: coap_address_set_port()

The coap_address_set_port() function sets the the port in addr if addr is AF_INET or AF_INET6.

Function: coap_get_available_scheme_hint_bits()

The coap_get_available_scheme_hint_bits() function is used for servers to determine what coap schemes are supported in the underlying libcoap library. have_pki_psk can be set to 1 to check for (D)DTLS support, else 0. ws_check can be set to 1 to check for WebSockets support, else 0. use_unix_proto, if not set to COAP_PROTO_NONE, hints at the specific CoAP protocol to use over a Unix socket. The output is suitable for input for the coap_address_resolve_info()'s scheme_hint_bits.

Function: coap_resolve_address_info()

The coap_resolve_address_info() function resolves the address address into a set of one or more coap_addr_info_t structures. Depending on the scheme as abstracted from scheme_hint_bits, port, secure_port, ws_port (WebSockets) or ws_secure_port (WebSockets) 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 if type is set to COAP_RESOLVE_TYPE_LOCAL. 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. _scheme_hint_bits can also (for servers) be the output from coap_get_available_scheme_hint_bits().

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 /.

Function: coap_host_is_unix_domain()

The coap_host_is_unix_domain() function checks whether host is an an AF_UNIX file name (encoded using %2F to indicate a /).

Function: coap_is_mcast()

The coap_is_mcast() function checks whether addr is a multicast address.

Function: coap_is_bcast()

The coap_is_mcast() function checks whether addr is a broadcast address.

Function: coap_is_af_unix()

The coap_is_mcast() function checks whether addr is of the type AF_UNIX.

RETURN VALUES

coap_address_equals() returns 1 if the addresses are equal or 0 if not.

coap_address_get_port() returns the port in network byte order.

coap_get_available_scheme_hint_bits() returns a set of COAP_URI_SCHEME_*_BIT or’d together based on the supported libcoap functionality.

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() returns 1 on success or 0 on failure.

coap_host_is_unix_domain() returns 1 if encoded unix path name or 0 if not.

coap_is_mcast() returns 1 if address is multicast or 0 if not.

coap_is_bcast() returns 1 if address is broadcast or 0 if not.

coap_is_af_unix() returns 1 if address is of type AF_UNIX or 0 if not.

EXAMPLES

Get client 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,
                                        uri->port, uri->port,0,
                                        1 << uri->scheme, COAP_RESOLVE_TYPE_LOCAL);
  if (info_list == NULL)
    return 0;
  memcpy(dst, &info_list->addr, sizeof(*dst));
  coap_free_address_info(info_list);
  return 1;
}

SEE ALSO

coap_endpoint_client(3), coap_endpoint_server(3) and coap_uri(3)

FURTHER INFORMATION

See

"RFC7252: The Constrained Application Protocol (CoAP)"

for further information.

BUGS

Please raise an issue on GitHub at https://github.com/obgm/libcoap/issues to report any bugs.

Please raise a Pull Request at https://github.com/obgm/libcoap/pulls for any fixes.

AUTHORS

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