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 
233 #ifndef NET_GCOAP_H
234 #define NET_GCOAP_H
235 
236 #include <stdint.h>
237 
238 #include "net/ipv6/addr.h"
239 #include "net/sock/udp.h"
240 #include "net/nanocoap.h"
241 #include "xtimer.h"
242 
243 #ifdef __cplusplus
244 extern "C" {
245 #endif
246 
256 #ifndef GCOAP_MSG_QUEUE_SIZE
257 #define GCOAP_MSG_QUEUE_SIZE (4)
258 #endif
259 
263 #ifndef GCOAP_PORT
264 #define GCOAP_PORT (5683)
265 #endif
266 
270 #ifndef GCOAP_PDU_BUF_SIZE
271 #define GCOAP_PDU_BUF_SIZE (128)
272 #endif
273 
280 #ifndef GCOAP_REQ_OPTIONS_BUF
281 #define GCOAP_REQ_OPTIONS_BUF (4)
282 #endif
283 
290 #ifndef GCOAP_RESP_OPTIONS_BUF
291 #define GCOAP_RESP_OPTIONS_BUF (4)
292 #endif
293 
300 #ifndef GCOAP_OBS_OPTIONS_BUF
301 #define GCOAP_OBS_OPTIONS_BUF (4)
302 #endif
303 
307 #ifndef GCOAP_REQ_WAITING_MAX
308 #define GCOAP_REQ_WAITING_MAX (2)
309 #endif
310 
315 #define GCOAP_TOKENLEN_MAX (8)
316 
320 #define GCOAP_HEADER_MAXLEN (sizeof(coap_hdr_t) + GCOAP_TOKENLEN_MAX)
321 
328 #ifndef GCOAP_TOKENLEN
329 #define GCOAP_TOKENLEN (2)
330 #endif
331 
335 #define GCOAP_PAYLOAD_MARKER (0xFF)
336 
341 #define GCOAP_MEMO_UNUSED (0)
342 #define GCOAP_MEMO_WAIT (1)
343 #define GCOAP_MEMO_RESP (2)
344 #define GCOAP_MEMO_TIMEOUT (3)
345 #define GCOAP_MEMO_ERR (4)
351 #define GCOAP_SEND_LIMIT_NON (-1)
352 
357 #ifndef GCOAP_RECV_TIMEOUT
358 #define GCOAP_RECV_TIMEOUT (1 * US_PER_SEC)
359 #endif
360 
361 #ifdef DOXYGEN
362 
372 #define GCOAP_NO_RETRANS_BACKOFF
373 #endif
374 
381 #ifndef GCOAP_NON_TIMEOUT
382 #define GCOAP_NON_TIMEOUT (5000000U)
383 #endif
384 
388 #define GCOAP_MSG_TYPE_TIMEOUT (0x1501)
389 
396 #define GCOAP_MSG_TYPE_INTR (0x1502)
397 
402 #ifndef GCOAP_OBS_CLIENTS_MAX
403 #define GCOAP_OBS_CLIENTS_MAX (2)
404 #endif
405 
410 #ifndef GCOAP_OBS_REGISTRATIONS_MAX
411 #define GCOAP_OBS_REGISTRATIONS_MAX (2)
412 #endif
413 
418 #define GCOAP_OBS_MEMO_UNUSED (0)
419 #define GCOAP_OBS_MEMO_IDLE (1)
420 #define GCOAP_OBS_MEMO_PENDING (2)
443 #ifndef GCOAP_OBS_VALUE_WIDTH
444 #define GCOAP_OBS_VALUE_WIDTH (3)
445 #endif
446 
450 #if (GCOAP_OBS_VALUE_WIDTH == 3)
451 #define GCOAP_OBS_TICK_EXPONENT (5)
452 #elif (GCOAP_OBS_VALUE_WIDTH == 2)
453 #define GCOAP_OBS_TICK_EXPONENT (16)
454 #elif (GCOAP_OBS_VALUE_WIDTH == 1)
455 #define GCOAP_OBS_TICK_EXPONENT (24)
456 #endif
457 
462 #define GCOAP_OBS_INIT_OK (0)
463 #define GCOAP_OBS_INIT_ERR (-1)
464 #define GCOAP_OBS_INIT_UNUSED (-2)
465 
470 #ifndef GCOAP_STACK_SIZE
471 #define GCOAP_STACK_SIZE (THREAD_STACKSIZE_DEFAULT + DEBUG_EXTRA_STACKSIZE \
472  + sizeof(coap_pkt_t))
473 #endif
474 
479 #ifndef GCOAP_RESEND_BUFS_MAX
480 #define GCOAP_RESEND_BUFS_MAX (1)
481 #endif
482 
487 #define COAP_LINK_FLAG_INIT_RESLIST (1)
494 typedef struct {
495  unsigned content_format;
496  size_t link_pos;
497  uint16_t flags;
500 
512 typedef ssize_t (*gcoap_link_encoder_t)(const coap_resource_t *resource, char *buf,
513  size_t maxlen, coap_link_encoder_ctx_t *context);
514 
518 typedef struct gcoap_listener {
521  size_t resources_len;
525 
532 typedef void (*gcoap_resp_handler_t)(unsigned req_state, coap_pkt_t* pdu,
533  sock_udp_ep_t *remote);
534 
538 typedef struct {
539  uint8_t *pdu_buf;
540  size_t pdu_len;
542 
546 typedef struct {
547  unsigned state;
548  int send_limit;
550  union {
551  uint8_t hdr_buf[GCOAP_HEADER_MAXLEN];
553  gcoap_resend_t data;
554  } msg;
556  sock_udp_ep_t remote_ep;
557  gcoap_resp_handler_t resp_handler;
558  xtimer_t response_timer;
559  msg_t timeout_msg;
561 
565 typedef struct {
566  sock_udp_ep_t *observer;
567  const coap_resource_t *resource;
568  uint8_t token[GCOAP_TOKENLEN_MAX];
569  unsigned token_len;
571 
582 
589 
604 int gcoap_req_init(coap_pkt_t *pdu, uint8_t *buf, size_t len,
605  unsigned code, const char *path);
606 
627 ssize_t gcoap_finish(coap_pkt_t *pdu, size_t payload_len, unsigned format);
628 
641 static inline ssize_t gcoap_request(coap_pkt_t *pdu, uint8_t *buf, size_t len,
642  unsigned code, char *path)
643 {
644  return (gcoap_req_init(pdu, buf, len, code, path) == 0)
646  : -1;
647 }
648 
660 size_t gcoap_req_send(const uint8_t *buf, size_t len,
661  const sock_udp_ep_t *remote,
662  gcoap_resp_handler_t resp_handler);
663 
678 static inline size_t gcoap_req_send2(const uint8_t *buf, size_t len,
679  const sock_udp_ep_t *remote,
680  gcoap_resp_handler_t resp_handler)
681 {
682  return gcoap_req_send(buf, len, remote, resp_handler);
683 }
684 
698 int gcoap_resp_init(coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code);
699 
711 static inline ssize_t gcoap_response(coap_pkt_t *pdu, uint8_t *buf,
712  size_t len, unsigned code)
713 {
714  return (gcoap_resp_init(pdu, buf, len, code) == 0)
716  : -1;
717 }
718 
734 int gcoap_obs_init(coap_pkt_t *pdu, uint8_t *buf, size_t len,
735  const coap_resource_t *resource);
736 
750 size_t gcoap_obs_send(const uint8_t *buf, size_t len,
751  const coap_resource_t *resource);
752 
760 uint8_t gcoap_op_state(void);
761 
780 int gcoap_get_resource_list(void *buf, size_t maxlen, uint8_t cf);
781 
795 ssize_t gcoap_encode_link(const coap_resource_t *resource, char *buf,
796  size_t maxlen, coap_link_encoder_ctx_t *context);
797 
813 int gcoap_add_qstring(coap_pkt_t *pdu, const char *key, const char *val);
814 
815 #ifdef __cplusplus
816 }
817 #endif
818 
819 #endif /* NET_GCOAP_H */
820 
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:513
struct gcoap_listener * next
Next listener in list.
Definition: gcoap.h:524
Definitions for IPv6 addresses.
#define GCOAP_HEADER_MAXLEN
Maximum length in bytes for a header, including the token.
Definition: gcoap.h:320
#define COAP_OPT_FINISH_NONE
no special handling required
Definition: nanocoap.h:166
Memo for Observe registration and notifications.
Definition: gcoap.h:566
UDP sock definitions.
uint8_t gcoap_op_state(void)
Provides important operational statistics.
size_t resources_len
Length of array.
Definition: gcoap.h:522
#define GCOAP_TOKENLEN_MAX
Maximum length in bytes for a token.
Definition: gcoap.h:315
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:642
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:218
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:533
A modular collection of resources for a server.
Definition: gcoap.h:519
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:523
Common IP-based transport layer end point.
Definition: sock.h:196
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:520
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:539
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:679
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:547
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:712
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:70
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:191
int gcoap_add_qstring(coap_pkt_t *pdu, const char *key, const char *val)
Adds a single Uri-Query option to a CoAP request.