gcoap.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2015-2016 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 
209 #ifndef NET_GCOAP_H
210 #define NET_GCOAP_H
211 
212 #include <stdint.h>
213 #include <stdatomic.h>
214 #include "net/sock/udp.h"
215 #include "mutex.h"
216 #include "nanocoap.h"
217 #include "xtimer.h"
218 
219 #ifdef __cplusplus
220 extern "C" {
221 #endif
222 
226 #define GCOAP_MSG_QUEUE_SIZE (4)
227 
231 #ifndef GCOAP_PORT
232 #define GCOAP_PORT (5683)
233 #endif
234 
238 #define GCOAP_PDU_BUF_SIZE (128)
239 
246 #define GCOAP_REQ_OPTIONS_BUF (8)
247 
253 #define GCOAP_RESP_OPTIONS_BUF (8)
254 
260 #define GCOAP_OBS_OPTIONS_BUF (8)
261 
265 #define GCOAP_REQ_WAITING_MAX (2)
266 
270 #define GCOAP_TOKENLEN_MAX (8)
271 
275 #define GCOAP_HEADER_MAXLEN (sizeof(coap_hdr_t) + GCOAP_TOKENLEN_MAX)
276 
280 #ifndef GCOAP_TOKENLEN
281 #define GCOAP_TOKENLEN (2)
282 #endif
283 
287 #define GCOAP_PAYLOAD_MARKER (0xFF)
288 
293 #define GCOAP_MEMO_UNUSED (0)
294 #define GCOAP_MEMO_WAIT (1)
295 #define GCOAP_MEMO_RESP (2)
296 #define GCOAP_MEMO_TIMEOUT (3)
297 #define GCOAP_MEMO_ERR (4)
303 #define GCOAP_RECV_TIMEOUT (1 * US_PER_SEC)
304 
310 #define GCOAP_NON_TIMEOUT (5000000U)
311 
315 #define GCOAP_MSG_TYPE_TIMEOUT (0x1501)
316 
323 #define GCOAP_MSG_TYPE_INTR (0x1502)
324 
328 #ifndef GCOAP_OBS_CLIENTS_MAX
329 #define GCOAP_OBS_CLIENTS_MAX (2)
330 #endif
331 
336 #ifndef GCOAP_OBS_REGISTRATIONS_MAX
337 #define GCOAP_OBS_REGISTRATIONS_MAX (2)
338 #endif
339 
344 #define GCOAP_OBS_MEMO_UNUSED (0)
345 #define GCOAP_OBS_MEMO_IDLE (1)
346 #define GCOAP_OBS_MEMO_PENDING (2)
368 #ifndef GCOAP_OBS_VALUE_WIDTH
369 #define GCOAP_OBS_VALUE_WIDTH (3)
370 #endif
371 
375 #if (GCOAP_OBS_VALUE_WIDTH == 3)
376 #define GCOAP_OBS_TICK_EXPONENT (5)
377 #elif (GCOAP_OBS_VALUE_WIDTH == 2)
378 #define GCOAP_OBS_TICK_EXPONENT (16)
379 #elif (GCOAP_OBS_VALUE_WIDTH == 1)
380 #define GCOAP_OBS_TICK_EXPONENT (24)
381 #endif
382 
387 #define GCOAP_OBS_INIT_OK (0)
388 #define GCOAP_OBS_INIT_ERR (-1)
389 #define GCOAP_OBS_INIT_UNUSED (-2)
390 
395 #ifndef GCOAP_STACK_SIZE
396 #define GCOAP_STACK_SIZE (THREAD_STACKSIZE_DEFAULT + DEBUG_EXTRA_STACKSIZE)
397 #endif
398 
402 typedef struct gcoap_listener {
403  coap_resource_t *resources;
405  size_t resources_len;
408 
415 typedef void (*gcoap_resp_handler_t)(unsigned req_state, coap_pkt_t* pdu);
416 
420 typedef struct {
421  unsigned state;
422  uint8_t hdr_buf[GCOAP_HEADER_MAXLEN];
428 
432 typedef struct {
434  coap_resource_t *resource;
435  uint8_t token[GCOAP_TOKENLEN_MAX];
436  unsigned token_len;
438 
442 typedef struct {
449  atomic_uint next_message_id;
455 } gcoap_state_t;
456 
467 
474 
487 int gcoap_req_init(coap_pkt_t *pdu, uint8_t *buf, size_t len,
488  unsigned code, char *path);
489 
504 ssize_t gcoap_finish(coap_pkt_t *pdu, size_t payload_len, unsigned format);
505 
518 static inline ssize_t gcoap_request(coap_pkt_t *pdu, uint8_t *buf, size_t len,
519  unsigned code, char *path)
520 {
521  return (gcoap_req_init(pdu, buf, len, code, path) == 0)
522  ? gcoap_finish(pdu, 0, COAP_FORMAT_NONE)
523  : -1;
524 }
525 
537 size_t gcoap_req_send2(const uint8_t *buf, size_t len,
538  const sock_udp_ep_t *remote,
539  gcoap_resp_handler_t resp_handler);
540 
555 size_t gcoap_req_send(const uint8_t *buf, size_t len, const ipv6_addr_t *addr,
556  uint16_t port, gcoap_resp_handler_t resp_handler);
557 
571 int gcoap_resp_init(coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code);
572 
584 static inline ssize_t gcoap_response(coap_pkt_t *pdu, uint8_t *buf,
585  size_t len, unsigned code)
586 {
587  return (gcoap_resp_init(pdu, buf, len, code) == 0)
588  ? gcoap_finish(pdu, 0, COAP_FORMAT_NONE)
589  : -1;
590 }
591 
607 int gcoap_obs_init(coap_pkt_t *pdu, uint8_t *buf, size_t len,
608  const coap_resource_t *resource);
609 
623 size_t gcoap_obs_send(const uint8_t *buf, size_t len,
624  const coap_resource_t *resource);
625 
633 uint8_t gcoap_op_state(void);
634 
635 #ifdef __cplusplus
636 }
637 #endif
638 
639 #endif /* NET_GCOAP_H */
640 
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:434
struct gcoap_listener * next
Next listener in list.
Definition: gcoap.h:406
#define GCOAP_HEADER_MAXLEN
Maximum length in bytes for a header, including the token.
Definition: gcoap.h:275
int16_t kernel_pid_t
Unique process identifier.
Definition: kernel_types.h:83
Memo for Observe registration and notifications.
Definition: gcoap.h:432
xtimer_t response_timer
Limits wait for response.
Definition: gcoap.h:425
UDP sock definitions.
mutex_t lock
Shares state attributes safely.
Definition: gcoap.h:443
uint8_t gcoap_op_state(void)
Provides important operational statistics.
size_t resources_len
Length of array.
Definition: gcoap.h:405
#define GCOAP_TOKENLEN_MAX
Maximum length in bytes for a token.
Definition: gcoap.h:270
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:518
Container for the state of gcoap itself.
Definition: gcoap.h:442
#define GCOAP_OBS_REGISTRATIONS_MAX
Maximum number of registrations for Observable resources; use 2 if not defined.
Definition: gcoap.h:337
#define GCOAP_OBS_CLIENTS_MAX
Maximum number of Observe clients; use 2 if not defined.
Definition: gcoap.h:329
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.
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:421
coap_resource_t * resources
First element in the array of resources; must order alphabetically.
Definition: gcoap.h:403
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:402
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:449
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
#define GCOAP_REQ_WAITING_MAX
Maximum number of requests awaiting a response.
Definition: gcoap.h:265
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:436
Memo to handle a response for a request.
Definition: gcoap.h:420
void(* gcoap_resp_handler_t)(unsigned req_state, coap_pkt_t *pdu)
Handler function for a server response, including the state for the originating request.
Definition: gcoap.h:415
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:584
gcoap_listener_t * listeners
List of registered listeners.
Definition: gcoap.h:444
sock_udp_ep_t * observer
Client endpoint; unused if null.
Definition: gcoap.h:433
gcoap_resp_handler_t resp_handler
Callback for the response.
Definition: gcoap.h:424
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.
kernel_pid_t gcoap_init(void)
Initializes the gcoap thread and device.
msg_t timeout_msg
For response timer.
Definition: gcoap.h:426
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.