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 
216 #ifndef NET_GCOAP_H
217 #define NET_GCOAP_H
218 
219 #include <stdint.h>
220 
221 #include "net/ipv6/addr.h"
222 #include "net/sock/udp.h"
223 #include "net/nanocoap.h"
224 #include "xtimer.h"
225 
226 #ifdef __cplusplus
227 extern "C" {
228 #endif
229 
239 #ifndef GCOAP_MSG_QUEUE_SIZE
240 #define GCOAP_MSG_QUEUE_SIZE (4)
241 #endif
242 
246 #ifndef GCOAP_PORT
247 #define GCOAP_PORT (5683)
248 #endif
249 
253 #ifndef GCOAP_PDU_BUF_SIZE
254 #define GCOAP_PDU_BUF_SIZE (128)
255 #endif
256 
263 #ifndef GCOAP_REQ_OPTIONS_BUF
264 #define GCOAP_REQ_OPTIONS_BUF (4)
265 #endif
266 
273 #ifndef GCOAP_RESP_OPTIONS_BUF
274 #define GCOAP_RESP_OPTIONS_BUF (4)
275 #endif
276 
283 #ifndef GCOAP_OBS_OPTIONS_BUF
284 #define GCOAP_OBS_OPTIONS_BUF (4)
285 #endif
286 
290 #ifndef GCOAP_REQ_WAITING_MAX
291 #define GCOAP_REQ_WAITING_MAX (2)
292 #endif
293 
298 #define GCOAP_TOKENLEN_MAX (8)
299 
303 #define GCOAP_HEADER_MAXLEN (sizeof(coap_hdr_t) + GCOAP_TOKENLEN_MAX)
304 
311 #ifndef GCOAP_TOKENLEN
312 #define GCOAP_TOKENLEN (2)
313 #endif
314 
318 #define GCOAP_PAYLOAD_MARKER (0xFF)
319 
324 #define GCOAP_MEMO_UNUSED (0)
325 #define GCOAP_MEMO_WAIT (1)
326 #define GCOAP_MEMO_RESP (2)
327 #define GCOAP_MEMO_TIMEOUT (3)
328 #define GCOAP_MEMO_ERR (4)
334 #define GCOAP_SEND_LIMIT_NON (-1)
335 
340 #ifndef GCOAP_RECV_TIMEOUT
341 #define GCOAP_RECV_TIMEOUT (1 * US_PER_SEC)
342 #endif
343 
350 #ifndef GCOAP_NON_TIMEOUT
351 #define GCOAP_NON_TIMEOUT (5000000U)
352 #endif
353 
357 #define GCOAP_MSG_TYPE_TIMEOUT (0x1501)
358 
365 #define GCOAP_MSG_TYPE_INTR (0x1502)
366 
371 #ifndef GCOAP_OBS_CLIENTS_MAX
372 #define GCOAP_OBS_CLIENTS_MAX (2)
373 #endif
374 
379 #ifndef GCOAP_OBS_REGISTRATIONS_MAX
380 #define GCOAP_OBS_REGISTRATIONS_MAX (2)
381 #endif
382 
387 #define GCOAP_OBS_MEMO_UNUSED (0)
388 #define GCOAP_OBS_MEMO_IDLE (1)
389 #define GCOAP_OBS_MEMO_PENDING (2)
412 #ifndef GCOAP_OBS_VALUE_WIDTH
413 #define GCOAP_OBS_VALUE_WIDTH (3)
414 #endif
415 
419 #if (GCOAP_OBS_VALUE_WIDTH == 3)
420 #define GCOAP_OBS_TICK_EXPONENT (5)
421 #elif (GCOAP_OBS_VALUE_WIDTH == 2)
422 #define GCOAP_OBS_TICK_EXPONENT (16)
423 #elif (GCOAP_OBS_VALUE_WIDTH == 1)
424 #define GCOAP_OBS_TICK_EXPONENT (24)
425 #endif
426 
431 #define GCOAP_OBS_INIT_OK (0)
432 #define GCOAP_OBS_INIT_ERR (-1)
433 #define GCOAP_OBS_INIT_UNUSED (-2)
434 
439 #ifndef GCOAP_STACK_SIZE
440 #define GCOAP_STACK_SIZE (THREAD_STACKSIZE_DEFAULT + DEBUG_EXTRA_STACKSIZE \
441  + sizeof(coap_pkt_t))
442 #endif
443 
448 #ifndef GCOAP_RESEND_BUFS_MAX
449 #define GCOAP_RESEND_BUFS_MAX (1)
450 #endif
451 
455 typedef struct gcoap_listener {
458  size_t resources_len;
461 
468 typedef void (*gcoap_resp_handler_t)(unsigned req_state, coap_pkt_t* pdu,
469  sock_udp_ep_t *remote);
470 
474 typedef struct {
475  uint8_t *pdu_buf;
476  size_t pdu_len;
478 
482 typedef struct {
483  unsigned state;
486  union {
487  uint8_t hdr_buf[GCOAP_HEADER_MAXLEN];
490  } msg;
497 
501 typedef struct {
504  uint8_t token[GCOAP_TOKENLEN_MAX];
505  unsigned token_len;
507 
518 
525 
540 int gcoap_req_init(coap_pkt_t *pdu, uint8_t *buf, size_t len,
541  unsigned code, const char *path);
542 
563 ssize_t gcoap_finish(coap_pkt_t *pdu, size_t payload_len, unsigned format);
564 
577 static inline ssize_t gcoap_request(coap_pkt_t *pdu, uint8_t *buf, size_t len,
578  unsigned code, char *path)
579 {
580  return (gcoap_req_init(pdu, buf, len, code, path) == 0)
582  : -1;
583 }
584 
596 size_t gcoap_req_send(const uint8_t *buf, size_t len,
597  const sock_udp_ep_t *remote,
598  gcoap_resp_handler_t resp_handler);
599 
614 static inline size_t gcoap_req_send2(const uint8_t *buf, size_t len,
615  const sock_udp_ep_t *remote,
616  gcoap_resp_handler_t resp_handler)
617 {
618  return gcoap_req_send(buf, len, remote, resp_handler);
619 }
620 
634 int gcoap_resp_init(coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code);
635 
647 static inline ssize_t gcoap_response(coap_pkt_t *pdu, uint8_t *buf,
648  size_t len, unsigned code)
649 {
650  return (gcoap_resp_init(pdu, buf, len, code) == 0)
652  : -1;
653 }
654 
670 int gcoap_obs_init(coap_pkt_t *pdu, uint8_t *buf, size_t len,
671  const coap_resource_t *resource);
672 
686 size_t gcoap_obs_send(const uint8_t *buf, size_t len,
687  const coap_resource_t *resource);
688 
696 uint8_t gcoap_op_state(void);
697 
716 int gcoap_get_resource_list(void *buf, size_t maxlen, uint8_t cf);
717 
733 int gcoap_add_qstring(coap_pkt_t *pdu, const char *key, const char *val);
734 
735 #ifdef __cplusplus
736 }
737 #endif
738 
739 #endif /* NET_GCOAP_H */
740 
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...
struct gcoap_listener * next
Next listener in list.
Definition: gcoap.h:459
Definitions for IPv6 addresses.
#define GCOAP_HEADER_MAXLEN
Maximum length in bytes for a header, including the token.
Definition: gcoap.h:303
#define COAP_OPT_FINISH_NONE
no special handling required
Definition: nanocoap.h:159
Memo for Observe registration and notifications.
Definition: gcoap.h:501
xtimer_t response_timer
Limits wait for response.
Definition: gcoap.h:494
UDP sock definitions.
uint8_t gcoap_op_state(void)
Provides important operational statistics.
size_t resources_len
Length of array.
Definition: gcoap.h:458
#define GCOAP_TOKENLEN_MAX
Maximum length in bytes for a token.
Definition: gcoap.h:298
size_t pdu_len
Length of pdu_buf.
Definition: gcoap.h:476
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:577
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:204
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:483
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:468
A modular collection of resources for a server.
Definition: gcoap.h:455
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
uint8_t * pdu_buf
Buffer containing the PDU.
Definition: gcoap.h:475
Common IP-based transport layer end point.
Definition: sock.h:195
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:456
Extends request memo for resending a confirmable request.
Definition: gcoap.h:474
const coap_resource_t * resource
Entity being observed.
Definition: gcoap.h:503
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:614
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:505
Memo to handle a response for a request.
Definition: gcoap.h:482
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:647
sock_udp_ep_t remote_ep
Remote endpoint.
Definition: gcoap.h:492
sock_udp_ep_t * observer
Client endpoint; unused if null.
Definition: gcoap.h:502
gcoap_resp_handler_t resp_handler
Callback for the response.
Definition: gcoap.h:493
gcoap_resend_t data
Endpoint and PDU buffer, for resend.
Definition: gcoap.h:489
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
int send_limit
Remaining resends, 0 if none; GCOAP_SEND_LIMIT_NON if non-confirmable.
Definition: gcoap.h:484
kernel_pid_t gcoap_init(void)
Initializes the gcoap thread and device.
msg_t timeout_msg
For response timer.
Definition: gcoap.h:495
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:184
int gcoap_add_qstring(coap_pkt_t *pdu, const char *key, const char *val)
Adds a single Uri-Query option to a CoAP request.