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 
345 #ifndef NET_GCOAP_H
346 #define NET_GCOAP_H
347 
348 #include <stdint.h>
349 
350 #include "net/ipv6/addr.h"
351 #include "net/sock/udp.h"
352 #include "net/nanocoap.h"
353 #include "xtimer.h"
354 
355 #ifdef __cplusplus
356 extern "C" {
357 #endif
358 
368 #ifndef GCOAP_MSG_QUEUE_SIZE
369 #define GCOAP_MSG_QUEUE_SIZE (4)
370 #endif
371 
375 #ifndef GCOAP_PORT
376 #define GCOAP_PORT (5683)
377 #endif
378 
382 #ifndef GCOAP_PDU_BUF_SIZE
383 #define GCOAP_PDU_BUF_SIZE (128)
384 #endif
385 
392 #ifndef GCOAP_REQ_OPTIONS_BUF
393 #define GCOAP_REQ_OPTIONS_BUF (4)
394 #endif
395 
402 #ifndef GCOAP_RESP_OPTIONS_BUF
403 #define GCOAP_RESP_OPTIONS_BUF (4)
404 #endif
405 
412 #ifndef GCOAP_OBS_OPTIONS_BUF
413 #define GCOAP_OBS_OPTIONS_BUF (4)
414 #endif
415 
419 #ifndef GCOAP_REQ_WAITING_MAX
420 #define GCOAP_REQ_WAITING_MAX (2)
421 #endif
422 
427 #define GCOAP_TOKENLEN_MAX (8)
428 
432 #define GCOAP_HEADER_MAXLEN (sizeof(coap_hdr_t) + GCOAP_TOKENLEN_MAX)
433 
440 #ifndef GCOAP_TOKENLEN
441 #define GCOAP_TOKENLEN (2)
442 #endif
443 
447 #define GCOAP_PAYLOAD_MARKER (0xFF)
448 
453 #define GCOAP_MEMO_UNUSED (0)
454 #define GCOAP_MEMO_WAIT (1)
455 #define GCOAP_MEMO_RESP (2)
456 #define GCOAP_MEMO_TIMEOUT (3)
457 #define GCOAP_MEMO_ERR (4)
463 #define GCOAP_SEND_LIMIT_NON (-1)
464 
469 #ifndef GCOAP_RECV_TIMEOUT
470 #define GCOAP_RECV_TIMEOUT (1 * US_PER_SEC)
471 #endif
472 
473 #ifdef DOXYGEN
474 
484 #define GCOAP_NO_RETRANS_BACKOFF
485 #endif
486 
493 #ifndef GCOAP_NON_TIMEOUT
494 #define GCOAP_NON_TIMEOUT (5000000U)
495 #endif
496 
500 #define GCOAP_MSG_TYPE_TIMEOUT (0x1501)
501 
508 #define GCOAP_MSG_TYPE_INTR (0x1502)
509 
514 #ifndef GCOAP_OBS_CLIENTS_MAX
515 #define GCOAP_OBS_CLIENTS_MAX (2)
516 #endif
517 
522 #ifndef GCOAP_OBS_REGISTRATIONS_MAX
523 #define GCOAP_OBS_REGISTRATIONS_MAX (2)
524 #endif
525 
530 #define GCOAP_OBS_MEMO_UNUSED (0)
531 #define GCOAP_OBS_MEMO_IDLE (1)
532 #define GCOAP_OBS_MEMO_PENDING (2)
555 #ifndef GCOAP_OBS_VALUE_WIDTH
556 #define GCOAP_OBS_VALUE_WIDTH (3)
557 #endif
558 
562 #if (GCOAP_OBS_VALUE_WIDTH == 3)
563 #define GCOAP_OBS_TICK_EXPONENT (5)
564 #elif (GCOAP_OBS_VALUE_WIDTH == 2)
565 #define GCOAP_OBS_TICK_EXPONENT (16)
566 #elif (GCOAP_OBS_VALUE_WIDTH == 1)
567 #define GCOAP_OBS_TICK_EXPONENT (24)
568 #endif
569 
574 #define GCOAP_OBS_INIT_OK (0)
575 #define GCOAP_OBS_INIT_ERR (-1)
576 #define GCOAP_OBS_INIT_UNUSED (-2)
577 
582 #ifndef GCOAP_STACK_SIZE
583 #define GCOAP_STACK_SIZE (THREAD_STACKSIZE_DEFAULT + DEBUG_EXTRA_STACKSIZE \
584  + sizeof(coap_pkt_t))
585 #endif
586 
591 #ifndef GCOAP_RESEND_BUFS_MAX
592 #define GCOAP_RESEND_BUFS_MAX (1)
593 #endif
594 
599 #define COAP_LINK_FLAG_INIT_RESLIST (1)
606 typedef struct {
607  unsigned content_format;
608  size_t link_pos;
609  uint16_t flags;
612 
624 typedef ssize_t (*gcoap_link_encoder_t)(const coap_resource_t *resource, char *buf,
625  size_t maxlen, coap_link_encoder_ctx_t *context);
626 
630 typedef struct gcoap_listener {
633  size_t resources_len;
637 
644 typedef void (*gcoap_resp_handler_t)(unsigned req_state, coap_pkt_t* pdu,
645  sock_udp_ep_t *remote);
646 
650 typedef struct {
651  uint8_t *pdu_buf;
652  size_t pdu_len;
654 
658 typedef struct {
659  unsigned state;
660  int send_limit;
662  union {
663  uint8_t hdr_buf[GCOAP_HEADER_MAXLEN];
665  gcoap_resend_t data;
666  } msg;
668  sock_udp_ep_t remote_ep;
669  gcoap_resp_handler_t resp_handler;
670  xtimer_t response_timer;
671  msg_t timeout_msg;
673 
677 typedef struct {
678  sock_udp_ep_t *observer;
679  const coap_resource_t *resource;
680  uint8_t token[GCOAP_TOKENLEN_MAX];
681  unsigned token_len;
683 
694 
701 
716 int gcoap_req_init(coap_pkt_t *pdu, uint8_t *buf, size_t len,
717  unsigned code, const char *path);
718 
739 ssize_t gcoap_finish(coap_pkt_t *pdu, size_t payload_len, unsigned format);
740 
753 static inline ssize_t gcoap_request(coap_pkt_t *pdu, uint8_t *buf, size_t len,
754  unsigned code, char *path)
755 {
756  return (gcoap_req_init(pdu, buf, len, code, path) == 0)
758  : -1;
759 }
760 
772 size_t gcoap_req_send(const uint8_t *buf, size_t len,
773  const sock_udp_ep_t *remote,
774  gcoap_resp_handler_t resp_handler);
775 
790 static inline size_t gcoap_req_send2(const uint8_t *buf, size_t len,
791  const sock_udp_ep_t *remote,
792  gcoap_resp_handler_t resp_handler)
793 {
794  return gcoap_req_send(buf, len, remote, resp_handler);
795 }
796 
810 int gcoap_resp_init(coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code);
811 
823 static inline ssize_t gcoap_response(coap_pkt_t *pdu, uint8_t *buf,
824  size_t len, unsigned code)
825 {
826  return (gcoap_resp_init(pdu, buf, len, code) == 0)
828  : -1;
829 }
830 
846 int gcoap_obs_init(coap_pkt_t *pdu, uint8_t *buf, size_t len,
847  const coap_resource_t *resource);
848 
862 size_t gcoap_obs_send(const uint8_t *buf, size_t len,
863  const coap_resource_t *resource);
864 
872 uint8_t gcoap_op_state(void);
873 
892 int gcoap_get_resource_list(void *buf, size_t maxlen, uint8_t cf);
893 
907 ssize_t gcoap_encode_link(const coap_resource_t *resource, char *buf,
908  size_t maxlen, coap_link_encoder_ctx_t *context);
909 
925 int gcoap_add_qstring(coap_pkt_t *pdu, const char *key, const char *val);
926 
927 #ifdef __cplusplus
928 }
929 #endif
930 
931 #endif /* NET_GCOAP_H */
932 
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...
ssize_t(* gcoap_link_encoder_t)(const coap_resource_t *resource, char *buf, size_t maxlen, coap_link_encoder_ctx_t *context)
Handler function to write a resource link.
Definition: gcoap.h:625
struct gcoap_listener * next
Next listener in list.
Definition: gcoap.h:636
Definitions for IPv6 addresses.
#define GCOAP_HEADER_MAXLEN
Maximum length in bytes for a header, including the token.
Definition: gcoap.h:432
#define COAP_OPT_FINISH_NONE
no special handling required
Definition: nanocoap.h:161
Memo for Observe registration and notifications.
Definition: gcoap.h:678
UDP sock definitions.
uint8_t gcoap_op_state(void)
Provides important operational statistics.
size_t resources_len
Length of array.
Definition: gcoap.h:634
#define GCOAP_TOKENLEN_MAX
Maximum length in bytes for a token.
Definition: gcoap.h:427
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:754
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.
size_t gcoap_req_send(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.
int16_t kernel_pid_t
Unique process identifier.
Definition: kernel_types.h:83
Type for CoAP resource entry.
Definition: nanocoap.h:213
void gcoap_register_listener(gcoap_listener_t *listener)
Starts listening for resource paths.
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:645
A modular collection of resources for a server.
Definition: gcoap.h:631
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.
ssize_t coap_opt_finish(coap_pkt_t *pkt, uint16_t flags)
Finalizes options as required and prepares for payload.
nanocoap API
gcoap_link_encoder_t link_encoder
Writes a link for a resource.
Definition: gcoap.h:635
Common IP-based transport layer end point.
Definition: sock.h:213
int gcoap_req_init(coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code, const char *path)
Initializes a CoAP request PDU on a buffer.
xtimer interface definitions
Describes a message object which can be sent between threads.
Definition: msg.h:184
const coap_resource_t * resources
First element in the array of resources; must order alphabetically.
Definition: gcoap.h:632
ssize_t gcoap_encode_link(const coap_resource_t *resource, char *buf, size_t maxlen, coap_link_encoder_ctx_t *context)
Writes a resource in CoRE Link Format to a provided buffer.
Extends request memo for resending a confirmable request.
Definition: gcoap.h:651
static 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.
Definition: gcoap.h:791
struct gcoap_listener gcoap_listener_t
A modular collection of resources for a server.
Memo to handle a response for a request.
Definition: gcoap.h:659
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:824
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...
xtimer timer structure
Definition: xtimer.h:74
kernel_pid_t gcoap_init(void)
Initializes the gcoap thread and device.
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 PDU parsing context structure.
Definition: nanocoap.h:186
int gcoap_add_qstring(coap_pkt_t *pdu, const char *key, const char *val)
Adds a single Uri-Query option to a CoAP request.