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 
378 #ifndef NET_GCOAP_H
379 #define NET_GCOAP_H
380 
381 #include <stdint.h>
382 
383 #include "event/callback.h"
384 #include "event/timeout.h"
385 #include "net/ipv6/addr.h"
386 #include "net/sock/udp.h"
387 #include "net/nanocoap.h"
388 #include "xtimer.h"
389 
390 #ifdef __cplusplus
391 extern "C" {
392 #endif
393 
403 #ifndef CONFIG_GCOAP_PORT
404 #define CONFIG_GCOAP_PORT (5683)
405 #endif
406 
410 #ifndef CONFIG_GCOAP_PDU_BUF_SIZE
411 #define CONFIG_GCOAP_PDU_BUF_SIZE (128)
412 #endif
413 
417 #ifndef CONFIG_GCOAP_REQ_WAITING_MAX
418 #define CONFIG_GCOAP_REQ_WAITING_MAX (2)
419 #endif
420 
425 #define GCOAP_TOKENLEN_MAX (8)
426 
430 #define GCOAP_HEADER_MAXLEN (sizeof(coap_hdr_t) + GCOAP_TOKENLEN_MAX)
431 
438 #ifndef CONFIG_GCOAP_TOKENLEN
439 #define CONFIG_GCOAP_TOKENLEN (2)
440 #endif
441 
445 #define GCOAP_PAYLOAD_MARKER (0xFF)
446 
453 #ifndef CONFIG_GCOAP_NO_AUTO_INIT
454 #define CONFIG_GCOAP_NO_AUTO_INIT 0
455 #endif
456 
461 #define GCOAP_MEMO_UNUSED (0)
462 #define GCOAP_MEMO_WAIT (1)
463 #define GCOAP_MEMO_RESP (2)
464 #define GCOAP_MEMO_TIMEOUT (3)
465 #define GCOAP_MEMO_ERR (4)
471 #define GCOAP_SEND_LIMIT_NON (-1)
472 
473 #ifdef DOXYGEN
474 
483 #define CONFIG_GCOAP_NO_RETRANS_BACKOFF
484 #endif
485 
492 #ifndef CONFIG_GCOAP_NON_TIMEOUT
493 #define CONFIG_GCOAP_NON_TIMEOUT (5000000U)
494 #endif
495 
500 #ifndef CONFIG_GCOAP_OBS_CLIENTS_MAX
501 #define CONFIG_GCOAP_OBS_CLIENTS_MAX (2)
502 #endif
503 
508 #ifndef CONFIG_GCOAP_OBS_REGISTRATIONS_MAX
509 #define CONFIG_GCOAP_OBS_REGISTRATIONS_MAX (2)
510 #endif
511 
516 #define GCOAP_OBS_MEMO_UNUSED (0)
517 #define GCOAP_OBS_MEMO_IDLE (1)
518 #define GCOAP_OBS_MEMO_PENDING (2)
541 #ifndef CONFIG_GCOAP_OBS_VALUE_WIDTH
542 #define CONFIG_GCOAP_OBS_VALUE_WIDTH (3)
543 #endif
544 
548 #if (CONFIG_GCOAP_OBS_VALUE_WIDTH == 3)
549 #define GCOAP_OBS_TICK_EXPONENT (5)
550 #elif (CONFIG_GCOAP_OBS_VALUE_WIDTH == 2)
551 #define GCOAP_OBS_TICK_EXPONENT (16)
552 #elif (CONFIG_GCOAP_OBS_VALUE_WIDTH == 1)
553 #define GCOAP_OBS_TICK_EXPONENT (24)
554 #endif
555 
560 #define GCOAP_OBS_INIT_OK (0)
561 #define GCOAP_OBS_INIT_ERR (-1)
562 #define GCOAP_OBS_INIT_UNUSED (-2)
563 
568 #ifndef GCOAP_STACK_SIZE
569 #define GCOAP_STACK_SIZE (THREAD_STACKSIZE_DEFAULT + DEBUG_EXTRA_STACKSIZE \
570  + sizeof(coap_pkt_t))
571 #endif
572 
577 #ifndef CONFIG_GCOAP_RESEND_BUFS_MAX
578 #define CONFIG_GCOAP_RESEND_BUFS_MAX (1)
579 #endif
580 
586 #define COAP_LINK_FLAG_INIT_RESLIST (1)
593 typedef struct {
594  unsigned content_format;
595  size_t link_pos;
596  uint16_t flags;
599 
611 typedef ssize_t (*gcoap_link_encoder_t)(const coap_resource_t *resource, char *buf,
612  size_t maxlen, coap_link_encoder_ctx_t *context);
613 
617 typedef struct gcoap_listener {
620  size_t resources_len;
624 
636 typedef void (*gcoap_resp_handler_t)(const gcoap_request_memo_t *memo,
638  const sock_udp_ep_t *remote);
639 
643 typedef struct {
644  uint8_t *pdu_buf;
645  size_t pdu_len;
647 
651 struct gcoap_request_memo {
652  unsigned state;
653  int send_limit;
655  union {
656  uint8_t hdr_buf[GCOAP_HEADER_MAXLEN];
658  gcoap_resend_t data;
659  } msg;
661  sock_udp_ep_t remote_ep;
662  gcoap_resp_handler_t resp_handler;
663  void *context;
664  event_timeout_t resp_evt_tmout;
665  event_callback_t resp_tmout_cb;
666 };
667 
671 typedef struct {
672  sock_udp_ep_t *observer;
673  const coap_resource_t *resource;
674  uint8_t token[GCOAP_TOKENLEN_MAX];
675  unsigned token_len;
677 
688 
695 
714 int gcoap_req_init(coap_pkt_t *pdu, uint8_t *buf, size_t len,
715  unsigned code, const char *path);
716 
729 static inline ssize_t gcoap_request(coap_pkt_t *pdu, uint8_t *buf, size_t len,
730  unsigned code, char *path)
731 {
732  return (gcoap_req_init(pdu, buf, len, code, path) == 0)
734  : -1;
735 }
736 
749 size_t gcoap_req_send(const uint8_t *buf, size_t len,
750  const sock_udp_ep_t *remote,
751  gcoap_resp_handler_t resp_handler, void *context);
752 
766 int gcoap_resp_init(coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code);
767 
779 static inline ssize_t gcoap_response(coap_pkt_t *pdu, uint8_t *buf,
780  size_t len, unsigned code)
781 {
782  return (gcoap_resp_init(pdu, buf, len, code) == 0)
784  : -1;
785 }
786 
802 int gcoap_obs_init(coap_pkt_t *pdu, uint8_t *buf, size_t len,
803  const coap_resource_t *resource);
804 
818 size_t gcoap_obs_send(const uint8_t *buf, size_t len,
819  const coap_resource_t *resource);
820 
828 uint8_t gcoap_op_state(void);
829 
848 int gcoap_get_resource_list(void *buf, size_t maxlen, uint8_t cf);
849 
863 ssize_t gcoap_encode_link(const coap_resource_t *resource, char *buf,
864  size_t maxlen, coap_link_encoder_ctx_t *context);
865 
884 int gcoap_add_qstring(coap_pkt_t *pdu, const char *key, const char *val);
885 
886 #ifdef __cplusplus
887 }
888 #endif
889 
890 #endif /* NET_GCOAP_H */
891 
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:612
struct gcoap_listener * next
Next listener in list.
Definition: gcoap.h:623
Definitions for IPv6 addresses.
#define GCOAP_HEADER_MAXLEN
Maximum length in bytes for a header, including the token.
Definition: gcoap.h:430
Provides functionality to trigger events after timeout.
#define COAP_OPT_FINISH_NONE
no special handling required
Definition: nanocoap.h:161
Memo for Observe registration and notifications.
Definition: gcoap.h:672
Callback Event structure definition.
Definition: callback.h:48
UDP sock definitions.
uint8_t gcoap_op_state(void)
Provides important operational statistics.
size_t resources_len
Length of array.
Definition: gcoap.h:621
#define GCOAP_TOKENLEN_MAX
Maximum length in bytes for a token.
Definition: gcoap.h:425
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:730
Provides a callback-with-argument event type.
Memo to handle a response for a request.
Definition: gcoap.h:652
int16_t kernel_pid_t
Unique process identifier.
Definition: kernel_types.h:83
Type for CoAP resource entry.
Definition: nanocoap.h:224
void gcoap_register_listener(gcoap_listener_t *listener)
Starts listening for resource paths.
A modular collection of resources for a server.
Definition: gcoap.h:618
int gcoap_resp_init(coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code)
Initializes a CoAP response packet on a buffer.
void(* gcoap_resp_handler_t)(const gcoap_request_memo_t *memo, coap_pkt_t *pdu, const sock_udp_ep_t *remote)
Handler function for a server response, including the state for the originating request.
Definition: gcoap.h:637
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:622
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
const coap_resource_t * resources
First element in the array of resources; must order alphabetically.
Definition: gcoap.h:619
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:644
struct gcoap_listener gcoap_listener_t
A modular collection of resources for a server.
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:780
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...
size_t gcoap_req_send(const uint8_t *buf, size_t len, const sock_udp_ep_t *remote, gcoap_resp_handler_t resp_handler, void *context)
Sends a buffer containing a CoAP request to the provided endpoint.
Timeout Event structure.
Definition: timeout.h:50
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.