'\" t
.\" Title: coap_address
.\" Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\" Date: 10/28/2024
.\" Manual: libcoap Manual
.\" Source: coap_address 4.3.4
.\" Language: English
.\"
.TH "COAP_ADDRESS" "3" "10/28/2024" "coap_address 4\&.3\&.4" "libcoap Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
coap_address, coap_address_t, coap_address_init, coap_address_copy, coap_address_equals, coap_address_get_port, coap_address_set_port, coap_get_available_scheme_hint_bits, coap_resolve_address_info, coap_free_address_info, coap_sockaddr_un, coap_address_set_unix_domain, coap_host_is_unix_domain, coap_is_bcast, coap_is_mcast, coap_is_af_unix \- Work with CoAP Socket Address Types
.SH "SYNOPSIS"
.sp
\fB#include <coap3/coap\&.h>\fR
.sp
\fBstruct coap_address_t;\fR
.sp
\fBstruct coap_sockaddr_un;\fR
.sp
\fBvoid coap_address_init(coap_address_t *\fR\fB\fIaddr\fR\fR\fB);\fR
.sp
\fBvoid coap_address_copy(coap_address_t *\fR\fB\fIdst\fR\fR\fB, const coap_address_t *\fR\fB\fIsrc\fR\fR\fB);\fR
.sp
\fBint coap_address_equals(const coap_address_t *\fR\fB\fIa\fR\fR\fB, const coap_address_t *\fR\fB\fIb\fR\fR\fB);\fR
.sp
\fBuint16_t coap_address_get_port(const coap_address_t *\fR\fB\fIaddr\fR\fR\fB);\fR
.sp
\fBvoid coap_address_set_port(coap_address_t *\fR\fB\fIaddr\fR\fR\fB, uint16_t \fR\fB\fIport\fR\fR\fB);\fR
.sp
\fBuint32_t coap_get_available_scheme_hint_bits(int \fR\fB\fIhave_pki_psk\fR\fR\fB, int \fR\fB\fIws_check\fR\fR\fB, coap_proto_t \fR\fB\fIuse_unix_proto\fR\fR\fB);\fR
.sp
\fBcoap_addr_info_t *coap_resolve_address_info(const coap_str_const_t *\fR\fB\fIaddress\fR\fR\fB, uint16_t \fR\fB\fIport\fR\fR\fB, uint16_t \fR\fB\fIsecure_port\fR\fR\fB, uint16_t \fR\fB\fIws_port\fR\fR\fB, uint16_t \fR\fB\fIws_secure_port\fR\fR\fB, int \fR\fB\fIai_hints_flags\fR\fR\fB, int \fR\fB\fIscheme_hint_bits\fR\fR\fB, coap_resolve_type_t \fR\fB\fItype\fR\fR\fB);\fR
.sp
\fBvoid coap_free_address_info(coap_addr_info_t *\fR\fB\fIinfo_list\fR\fR\fB);\fR
.sp
\fBint coap_host_is_unix_domain(const coap_str_const_t *\fR\fB\fIhost\fR\fR\fB);\fR
.sp
\fBint coap_address_set_unix_domain(coap_address_t *\fR\fB\fIaddr\fR\fR\fB, const uint8_t *\fR\fB\fIhost\fR\fR\fB, size_t \fR\fB\fIhost_len\fR\fR\fB);\fR
.sp
\fBint coap_is_bcast(const coap_address_t *\fR\fB\fIaddr\fR\fR\fB);\fR
.sp
\fBint coap_is_mcast(const coap_address_t *\fR\fB\fIaddr\fR\fR\fB);\fR
.sp
\fBint coap_is_af_unix(const coap_address_t *\fR\fB\fIaddr\fR\fR\fB);\fR
.sp
For specific (D)TLS library support, link with \fB\-lcoap\-3\-notls\fR, \fB\-lcoap\-3\-gnutls\fR, \fB\-lcoap\-3\-openssl\fR, \fB\-lcoap\-3\-mbedtls\fR or \fB\-lcoap\-3\-tinydtls\fR\&. Otherwise, link with \fB\-lcoap\-3\fR to get the default (D)TLS library support\&.
.SH "DESCRIPTION"
.sp
This man page focuses on setting up CoAP endpoint address definitions\&.
.sp
\fBSupported Socket Types\fR
.sp
Libcoap supports 3 different socket types that can be used:
.sp
.if n \{\
.RS 4
.\}
.nf
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
.fi
.if n \{\
.RE
.\}
.sp
which are all handled by the \fBcoap_address_t\fR structure\&.
.sp
\fBStructure coap_address_t\fR
.sp
.if n \{\
.RS 4
.\}
.nf
/* 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()*\&.
.fi
.if n \{\
.RE
.\}
.sp
\fBStructure coap_addr_info_t\fR
.sp
.if n \{\
.RS 4
.\}
.nf
/* 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;
.fi
.if n \{\
.RE
.\}
.sp
\fBStructure coap_sockaddr_un\fR
.sp
.if n \{\
.RS 4
.\}
.nf
#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 */
};
.fi
.if n \{\
.RE
.\}
.sp
The \fBcoap_sockaddr_un\fR structure is modeled on the \fBsockaddr_un\fR structure (see \fBunix\fR(7)) but has a smaller sun_path so that the overall size of \fBcoap_address_t\fR is not changed by its inclusion\&. COAP_UNIX_MAX_PATH includes the trailing zero terminator of a domain unix file name\&.
.sp
\fBEnum coap_resolve_type_t\fR
.sp
.if n \{\
.RS 4
.\}
.nf
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;
.fi
.if n \{\
.RE
.\}
.sp
Used when determining how to do an address lookup when calling \fBcoap_resolve_address_info()\fR\&.
.SH "FUNCTIONS"
.sp
\fBFunction: coap_address_init()\fR
.sp
The \fBcoap_address_init\fR() function initializes \fIaddr\fR for later use\&. In particular it sets the \fIsize\fR variable and sets all other values to be 0\&.
.sp
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 \fIaddr\fR is used\&.
.sp
\fBFunction: coap_address_copy()\fR
.sp
The \fBcoap_address_copy\fR() function copies the address \fIsrc\fR into \fIdst\fR\&.
.sp
\fBFunction: coap_address_equals()\fR
.sp
The \fBcoap_address_equals\fR() function checks whether the addresses \fIa\fR and \fIb\fR are identical\&.
.sp
\fBFunction: coap_address_get_port()\fR
.sp
The \fBcoap_address_get_port\fR() function gets the the port from \fIaddr\fR if \fIaddr\fR is AF_INET or AF_INET6\&.
.sp
\fBFunction: coap_address_set_port()\fR
.sp
The \fBcoap_address_set_port\fR() function sets the the \fIport\fR in \fIaddr\fR if \fIaddr\fR is AF_INET or AF_INET6\&.
.sp
\fBFunction: coap_get_available_scheme_hint_bits()\fR
.sp
The \fBcoap_get_available_scheme_hint_bits\fR() function is used for servers to determine what coap schemes are supported in the underlying libcoap library\&. \fIhave_pki_psk\fR can be set to 1 to check for (D)DTLS support, else 0\&. \fIws_check\fR can be set to 1 to check for WebSockets support, else 0\&. \fIuse_unix_proto\fR, 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 \fBcoap_address_resolve_info\fR()\*(Aqs \fIscheme_hint_bits\fR\&.
.sp
\fBFunction: coap_resolve_address_info()\fR
.sp
The \fBcoap_resolve_address_info\fR() function resolves the address \fIaddress\fR into a set of one or more coap_addr_info_t structures\&. Depending on the scheme as abstracted from \fIscheme_hint_bits\fR, \fIport\fR, \fIsecure_port\fR, \fIws_port\fR (WebSockets) or \fIws_secure_port\fR (WebSockets) is used to update the addr variable of coap_addr_info_t\&. If \fIport\fR (or \fIsecure_port\fR) is 0, then the default port for the scheme is used if \fItype\fR is set to COAP_RESOLVE_TYPE_LOCAL\&. \fIai_hints_flags\fR is used for the internally called getaddrinfo(3) function\&. \fIscheme_hint_bits\fR is a set of one or more COAP_URI_SCHEME_*\fIBIT or\(cqd together\&. _scheme_hint_bits\fR can also (for servers) be the output from \fBcoap_get_available_scheme_hint_bits\fR()\&.
.sp
The returned set of coap_addr_info_t structures must be freed off by the caller using \fBcoap_free_address_info\fR()\&.
.sp
\fBFunction: coap_free_address_info()\fR
.sp
The \fBcoap_free_address_info\fR() function frees off all the \fIinfo_list\fR linked entries\&.
.sp
\fBFunction: coap_address_set_unix_domain()\fR
.sp
The \fBcoap_address_set_unix_domain\fR() function initializes \fIaddr\fR and then populates \fIaddr\fR with all the appropriate information for a Unix Domain Socket\&. The \fIhost\fR information with length \fIhost_len\fR abstracted from a CoAP URI is copied into \fIaddr\fR\*(Aqs \fIsun_path\fR translating any %2F encoding to /\&.
.sp
\fBFunction: coap_host_is_unix_domain()\fR
.sp
The \fBcoap_host_is_unix_domain\fR() function checks whether \fIhost\fR is an an AF_UNIX file name (encoded using %2F to indicate a /)\&.
.sp
\fBFunction: coap_is_mcast()\fR
.sp
The \fBcoap_is_mcast\fR() function checks whether \fIaddr\fR is a multicast address\&.
.sp
\fBFunction: coap_is_bcast()\fR
.sp
The \fBcoap_is_mcast\fR() function checks whether \fIaddr\fR is a broadcast address\&.
.sp
\fBFunction: coap_is_af_unix()\fR
.sp
The \fBcoap_is_mcast\fR() function checks whether \fIaddr\fR is of the type AF_UNIX\&.
.SH "RETURN VALUES"
.sp
\fBcoap_address_equals\fR() returns 1 if the addresses are equal or 0 if not\&.
.sp
\fBcoap_address_get_port\fR() returns the port in network byte order\&.
.sp
\fBcoap_get_available_scheme_hint_bits\fR() returns a set of COAP_URI_SCHEME_*_BIT or\(cqd together based on the supported libcoap functionality\&.
.sp
\fBcoap_resolve_address_info\fR() returns a linked list of addresses that can be used for session setup or NULL if there is a failure\&.
.sp
\fBcoap_address_set_unix_domain\fR() returns 1 on success or 0 on failure\&.
.sp
\fBcoap_host_is_unix_domain\fR() returns 1 if encoded unix path name or 0 if not\&.
.sp
\fBcoap_is_mcast\fR() returns 1 if address is multicast or 0 if not\&.
.sp
\fBcoap_is_bcast\fR() returns 1 if address is broadcast or 0 if not\&.
.sp
\fBcoap_is_af_unix\fR() returns 1 if address is of type AF_UNIX or 0 if not\&.
.SH "EXAMPLES"
.sp
\fBGet client target address from uri\fR
.sp
.if n \{\
.RS 4
.\}
.nf
#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;
}
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
\fBcoap_endpoint_client\fR(3), \fBcoap_endpoint_server\fR(3) and \fBcoap_uri\fR(3)
.SH "FURTHER INFORMATION"
.sp
See
.sp
"RFC7252: The Constrained Application Protocol (CoAP)"
.sp
for further information\&.
.SH "BUGS"
.sp
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
.SH "AUTHORS"
.sp
The libcoap project <libcoap\-developers@lists\&.sourceforge\&.net>