gcoap.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2015-2017 Ken Bannister. All rights reserved.
3  * 2017 Freie Universit├Ąt Berlin
4  *
5  * This file is subject to the terms and conditions of the GNU Lesser
6  * General Public License v2.1. See the file LICENSE in the top level
7  * directory for more details.
8  */
9 
212 #ifndef NET_GCOAP_H
213 #define NET_GCOAP_H
214 
215 #include <stdint.h>
216 #include <stdatomic.h>
217 
218 #include "net/ipv6/addr.h"
219 #include "net/sock/udp.h"
220 #include "mutex.h"
221 #include "net/nanocoap.h"
222 #include "xtimer.h"
223 
224 #ifdef __cplusplus
225 extern "C" {
226 #endif
227 
231 #define GCOAP_MSG_QUEUE_SIZE (4)
232 
236 #ifndef GCOAP_PORT
237 #define GCOAP_PORT (5683)
238 #endif
239 
243 #ifndef GCOAP_PDU_BUF_SIZE
244 #define GCOAP_PDU_BUF_SIZE (128)
245 #endif
246 
253 #define GCOAP_REQ_OPTIONS_BUF (40)
254 
260 #define GCOAP_RESP_OPTIONS_BUF (8)
261 
267 #define GCOAP_OBS_OPTIONS_BUF (8)
268 
272 #ifndef GCOAP_REQ_WAITING_MAX
273 #define GCOAP_REQ_WAITING_MAX (2)
274 #endif
275 
279 #define GCOAP_TOKENLEN_MAX (8)
280 
284 #define GCOAP_HEADER_MAXLEN (sizeof(coap_hdr_t) + GCOAP_TOKENLEN_MAX)
285 
289 #ifndef GCOAP_TOKENLEN
290 #define GCOAP_TOKENLEN (2)
291 #endif
292 
296 #define GCOAP_PAYLOAD_MARKER (0xFF)
297 
302 #define GCOAP_MEMO_UNUSED (0)
303 #define GCOAP_MEMO_WAIT (1)
304 #define GCOAP_MEMO_RESP (2)
305 #define GCOAP_MEMO_TIMEOUT (3)
306 #define GCOAP_MEMO_ERR (4)
312 #define GCOAP_SEND_LIMIT_NON (-1)
313 
317 #ifndef GCOAP_RECV_TIMEOUT
318 #define GCOAP_RECV_TIMEOUT (1 * US_PER_SEC)
319 #endif
320 
326 #ifndef GCOAP_NON_TIMEOUT
327 #define GCOAP_NON_TIMEOUT (5000000U)
328 #endif
329 
333 #define GCOAP_MSG_TYPE_TIMEOUT (0x1501)
334 
341 #define GCOAP_MSG_TYPE_INTR (0x1502)
342 
346 #ifndef GCOAP_OBS_CLIENTS_MAX
347 #define GCOAP_OBS_CLIENTS_MAX (2)
348 #endif
349 
354 #ifndef GCOAP_OBS_REGISTRATIONS_MAX
355 #define GCOAP_OBS_REGISTRATIONS_MAX (2)
356 #endif
357 
362 #define GCOAP_OBS_MEMO_UNUSED (0)
363 #define GCOAP_OBS_MEMO_IDLE (1)
364 #define GCOAP_OBS_MEMO_PENDING (2)
386 #ifndef GCOAP_OBS_VALUE_WIDTH
387 #define GCOAP_OBS_VALUE_WIDTH (3)
388 #endif
389 
393 #if (GCOAP_OBS_VALUE_WIDTH == 3)
394 #define GCOAP_OBS_TICK_EXPONENT (5)
395 #elif (GCOAP_OBS_VALUE_WIDTH == 2)
396 #define GCOAP_OBS_TICK_EXPONENT (16)
397 #elif (GCOAP_OBS_VALUE_WIDTH == 1)
398 #define GCOAP_OBS_TICK_EXPONENT (24)
399 #endif
400 
405 #define GCOAP_OBS_INIT_OK (0)
406 #define GCOAP_OBS_INIT_ERR (-1)
407 #define GCOAP_OBS_INIT_UNUSED (-2)
408 
413 #ifndef GCOAP_STACK_SIZE
414 #define GCOAP_STACK_SIZE (THREAD_STACKSIZE_DEFAULT + DEBUG_EXTRA_STACKSIZE)
415 #endif
416 
420 #ifndef GCOAP_RESEND_BUFS_MAX
421 #define GCOAP_RESEND_BUFS_MAX (1)
422 #endif
423 
427 typedef struct gcoap_listener {
430  size_t resources_len;
433 
440 typedef void (*gcoap_resp_handler_t)(unsigned req_state, coap_pkt_t* pdu,
441  sock_udp_ep_t *remote);
442 
446 typedef struct {
447  uint8_t *pdu_buf;
448  size_t pdu_len;
450 
454 typedef struct {
455  unsigned state;
458  union {
459  uint8_t hdr_buf[GCOAP_HEADER_MAXLEN];
462  } msg;
469 
473 typedef struct {
476  uint8_t token[GCOAP_TOKENLEN_MAX];
477  unsigned token_len;
479 
483 typedef struct {
490  atomic_uint next_message_id;
500 } gcoap_state_t;
501 
512 
519 
532 int gcoap_req_init(coap_pkt_t *pdu, uint8_t *buf, size_t len,
533  unsigned code, char *path);
534 
549 ssize_t gcoap_finish(coap_pkt_t *pdu, size_t payload_len, unsigned format);
550 
563 static inline ssize_t gcoap_request(coap_pkt_t *pdu, uint8_t *buf, size_t len,
564  unsigned code, char *path)
565 {
566  return (gcoap_req_init(pdu, buf, len, code, path) == 0)
567  ? gcoap_finish(pdu, 0, COAP_FORMAT_NONE)
568  : -1;
569 }
570 
582 size_t gcoap_req_send2(const uint8_t *buf, size_t len,
583  const sock_udp_ep_t *remote,
584  gcoap_resp_handler_t resp_handler);
585 
600 size_t gcoap_req_send(const uint8_t *buf, size_t len, const ipv6_addr_t *addr,
601  uint16_t port, gcoap_resp_handler_t resp_handler);
602 
616 int gcoap_resp_init(coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code);
617 
629 static inline ssize_t gcoap_response(coap_pkt_t *pdu, uint8_t *buf,
630  size_t len, unsigned code)
631 {
632  return (gcoap_resp_init(pdu, buf, len, code) == 0)
633  ? gcoap_finish(pdu, 0, COAP_FORMAT_NONE)
634  : -1;
635 }
636 
652 int gcoap_obs_init(coap_pkt_t *pdu, uint8_t *buf, size_t len,
653  const coap_resource_t *resource);
654 
668 size_t gcoap_obs_send(const uint8_t *buf, size_t len,
669  const coap_resource_t *resource);
670 
678 uint8_t gcoap_op_state(void);
679 
698 int gcoap_get_resource_list(void *buf, size_t maxlen, uint8_t cf);
699 
715 int gcoap_add_qstring(coap_pkt_t *pdu, const char *key, const char *val);
716 
717 #ifdef __cplusplus
718 }
719 #endif
720 
721 #endif /* NET_GCOAP_H */
722 
int gcoap_obs_init(coap_pkt_t *pdu, uint8_t *buf, size_t len, const coap_resource_t *resource)
Initializes a CoAP Observe notification packet on a buffer, for the observer registered for a resourc...
coap_resource_t * resource
Entity being observed.
Definition: gcoap.h:475
struct gcoap_listener * next
Next listener in list.
Definition: gcoap.h:431
Definitions for IPv6 addresses.
#define GCOAP_HEADER_MAXLEN
Maximum length in bytes for a header, including the token.
Definition: gcoap.h:284
int16_t kernel_pid_t
Unique process identifier.
Definition: kernel_types.h:83
Memo for Observe registration and notifications.
Definition: gcoap.h:473
xtimer_t response_timer
Limits wait for response.
Definition: gcoap.h:466
UDP sock definitions.
mutex_t lock
Shares state attributes safely.
Definition: gcoap.h:484
uint8_t gcoap_op_state(void)
Provides important operational statistics.
size_t resources_len
Length of array.
Definition: gcoap.h:430
#define GCOAP_TOKENLEN_MAX
Maximum length in bytes for a token.
Definition: gcoap.h:279
size_t pdu_len
Length of pdu_buf.
Definition: gcoap.h:448
static ssize_t gcoap_request(coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code, char *path)
Writes a complete CoAP request PDU when there is not a payload.
Definition: gcoap.h:563
#define GCOAP_RESEND_BUFS_MAX
Count of PDU buffers available for resending confirmable messages.
Definition: gcoap.h:421
Container for the state of gcoap itself.
Definition: gcoap.h:483
#define GCOAP_OBS_REGISTRATIONS_MAX
Maximum number of registrations for Observable resources; use 2 if not defined.
Definition: gcoap.h:355
#define GCOAP_OBS_CLIENTS_MAX
Maximum number of Observe clients; use 2 if not defined.
Definition: gcoap.h:347
ssize_t gcoap_finish(coap_pkt_t *pdu, size_t payload_len, unsigned format)
Finishes formatting a CoAP PDU after the payload has been written.
Type for CoAP resource entry.
Definition: nanocoap.h:241
void gcoap_register_listener(gcoap_listener_t *listener)
Starts listening for resource paths.
unsigned state
State of this memo, a GCOAP_MEMO...
Definition: gcoap.h:455
void(* gcoap_resp_handler_t)(unsigned req_state, coap_pkt_t *pdu, sock_udp_ep_t *remote)
Handler function for a server response, including the state for the originating request.
Definition: gcoap.h:440
coap_resource_t * resources
First element in the array of resources; must order alphabetically.
Definition: gcoap.h:428
size_t gcoap_req_send(const uint8_t *buf, size_t len, const ipv6_addr_t *addr, uint16_t port, gcoap_resp_handler_t resp_handler)
Sends a buffer containing a CoAP request to the provided host/port.
A modular collection of resources for a server.
Definition: gcoap.h:427
signed int ssize_t
Used for a count of bytes or an error indication.
Definition: msp430_types.h:89
int gcoap_resp_init(coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code)
Initializes a CoAP response packet on a buffer.
atomic_uint next_message_id
Next message ID to use.
Definition: gcoap.h:490
#define GCOAP_PDU_BUF_SIZE
Size of the buffer used to build a CoAP request or response.
Definition: gcoap.h:244
nanocoap API
uint8_t * pdu_buf
Buffer containing the PDU.
Definition: gcoap.h:447
Common IP-based transport layer end point.
Definition: sock.h:195
xtimer interface definitions
Describes a message object which can be sent between threads.
Definition: msg.h:184
Extends request memo for resending a confirmable request.
Definition: gcoap.h:446
#define COAP_FORMAT_NONE
nanocoap-specific value to indicate no format specified.
Definition: nanocoap.h:178
#define GCOAP_REQ_WAITING_MAX
Maximum number of requests awaiting a response.
Definition: gcoap.h:273
RIOT synchronization API.
struct gcoap_listener gcoap_listener_t
A modular collection of resources for a server.
unsigned token_len
Actual length of token attribute.
Definition: gcoap.h:477
Memo to handle a response for a request.
Definition: gcoap.h:454
static ssize_t gcoap_response(coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code)
Writes a complete CoAP response PDU when there is no payload.
Definition: gcoap.h:629
sock_udp_ep_t remote_ep
Remote endpoint.
Definition: gcoap.h:464
gcoap_listener_t * listeners
List of registered listeners.
Definition: gcoap.h:485
sock_udp_ep_t * observer
Client endpoint; unused if null.
Definition: gcoap.h:474
gcoap_resp_handler_t resp_handler
Callback for the response.
Definition: gcoap.h:465
gcoap_resend_t data
Endpoint and PDU buffer, for resend.
Definition: gcoap.h:461
size_t gcoap_obs_send(const uint8_t *buf, size_t len, const coap_resource_t *resource)
Sends a buffer containing a CoAP Observe notification to the observer registered for a resource...
Data type to represent an IPv6 address.
Definition: ipv6/addr.h:74
xtimer timer structure
Definition: xtimer.h:70
Mutex structure.
Definition: mutex.h:36
int gcoap_req_init(coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code, char *path)
Initializes a CoAP request PDU on a buffer.
int send_limit
Remaining resends, 0 if none; GCOAP_SEND_LIMIT_NON if non-confirmable.
Definition: gcoap.h:456
kernel_pid_t gcoap_init(void)
Initializes the gcoap thread and device.
msg_t timeout_msg
For response timer.
Definition: gcoap.h:467
size_t gcoap_req_send2(const uint8_t *buf, size_t len, const sock_udp_ep_t *remote, gcoap_resp_handler_t resp_handler)
Sends a buffer containing a CoAP request to the provided endpoint.
int gcoap_get_resource_list(void *buf, size_t maxlen, uint8_t cf)
Get the resource list, currently only CoRE Link Format (COAP_FORMAT_LINK) supported.
CoAP option array entry.
Definition: nanocoap.h:222
int gcoap_add_qstring(coap_pkt_t *pdu, const char *key, const char *val)
Adds a single Uri-Query option to a CoAP request.