1 /* net.c -- CoAP network interface
3 * Copyright (C) 2010--2014 Olaf Bergmann <bergmann@tzi.org>
5 * This file is part of the CoAP library libcoap. Please see
6 * README for terms of use.
18 #elif HAVE_SYS_UNISTD_H
19 #include <sys/unistd.h>
21 #include <sys/types.h>
22 #ifdef HAVE_SYS_SOCKET_H
23 #include <sys/socket.h>
25 #ifdef HAVE_NETINET_IN_H
26 #include <netinet/in.h>
28 #ifdef HAVE_ARPA_INET_H
29 #include <arpa/inet.h>
33 #include <lwip/pbuf.h>
35 #include <lwip/timers.h>
48 #if defined(WITH_POSIX)
53 #define MOD_NAME ("net.c")
57 static inline coap_queue_t *
59 return (coap_queue_t *)coap_malloc(sizeof(coap_queue_t));
63 coap_free_node(coap_queue_t *node) {
66 #endif /* WITH_POSIX */
69 #include <lwip/memp.h>
71 static void coap_retransmittimer_execute(void *arg);
72 static void coap_retransmittimer_restart(coap_context_t *ctx);
74 static inline coap_queue_t *
76 return (coap_queue_t *)memp_malloc(MEMP_COAP_NODE);
80 coap_free_node(coap_queue_t *node) {
81 memp_free(MEMP_COAP_NODE, node);
84 #endif /* WITH_LWIP */
87 # define DEBUG DEBUG_PRINT
91 #include "net/uip-debug.h"
93 clock_time_t clock_offset;
95 #define UIP_IP_BUF ((struct uip_ip_hdr *)&uip_buf[UIP_LLH_LEN])
96 #define UIP_UDP_BUF ((struct uip_udp_hdr *)&uip_buf[UIP_LLIPH_LEN])
98 void coap_resources_init();
99 void coap_pdu_resources_init();
101 unsigned char initialized = 0;
102 coap_context_t the_coap_context;
104 MEMB(node_storage, coap_queue_t, COAP_PDU_MAXCNT);
106 PROCESS(coap_retransmit_process, "message retransmit process");
108 static inline coap_queue_t *
110 return (coap_queue_t *)memb_alloc(&node_storage);
114 coap_free_node(coap_queue_t *node) {
115 memb_free(&node_storage, node);
117 #endif /* WITH_CONTIKI */
120 /** Callback to udp_recv when using lwIP. Gets called by lwIP on arriving
121 * packages, places a reference in context->pending_package, and calls
122 * coap_read to process the package. Thus, coap_read needs not be called in
123 * lwIP main loops. (When modifying this for thread-like operation, ie. if you
124 * remove the coap_read call from this, make sure that coap_read gets a chance
125 * to run before this callback is entered the next time.)
127 static void received_package(void *arg, struct udp_pcb *upcb, struct pbuf *p, ip_addr_t *addr, u16_t port)
129 struct coap_context_t *context = (coap_context_t *)arg;
131 LWIP_ASSERT("pending_package was not cleared.", context->pending_package == NULL);
133 context->pending_package = p; /* we don't free it, coap_read has to do that */
134 context->pending_address.addr = addr->addr; /* FIXME: this has to become address-type independent, probably there'll be an lwip function for that */
135 context->pending_port = port;
137 coap_read(context, -1); /* we want to read from unicast socket */
140 #endif /* WITH_LWIP */
142 int print_wellknown(coap_context_t *, unsigned char *, size_t *, size_t,
145 void coap_handle_failed_notify(coap_context_t *, const coap_address_t *,
148 unsigned int coap_adjust_basetime(coap_context_t *ctx, coap_tick_t now) {
149 unsigned int result = 0;
150 coap_tick_diff_t delta = now - ctx->sendqueue_basetime;
152 if (ctx->sendqueue) {
153 /* delta < 0 means that the new time stamp is before the old. */
155 ctx->sendqueue->t -= delta;
157 /* This case is more complex: The time must be advanced forward,
158 * thus possibly leading to timed out elements at the queue's
159 * start. For every element that has timed out, its relative
160 * time is set to zero and the result counter is increased. */
162 coap_queue_t *q = ctx->sendqueue;
164 while (q && (t + q->t < (coap_tick_t) delta)) {
171 /* finally adjust the first element that has not expired */
173 q->t = (coap_tick_t) delta - t;
178 /* adjust basetime */
179 ctx->sendqueue_basetime += delta;
184 int coap_insert_node(coap_queue_t **queue, coap_queue_t *node) {
189 /* set queue head if empty */
195 /* replace queue head if PDU's time is less than head's time */
197 if (node->t < q->t) {
200 q->t -= node->t; /* make q->t relative to node->t */
204 /* search for right place to insert */
206 node->t -= q->t; /* make node-> relative to q->t */
209 } while (q && q->t <= node->t);
211 /* insert new item */
213 q->t -= node->t; /* make q->t relative to node->t */
220 int coap_delete_node(coap_queue_t *node) {
224 coap_delete_pdu(node->pdu);
225 coap_free_node(node);
230 void coap_delete_all(coap_queue_t *queue) {
234 coap_delete_all(queue->next);
235 coap_delete_node(queue);
241 node = coap_malloc_node();
245 coap_log(LOG_WARNING, "coap_new_node: malloc\n");
250 memset(node, 0, sizeof *node);
255 coap_peek_next(coap_context_t *context) {
256 if (!context || !context->sendqueue)
259 return context->sendqueue;
263 coap_pop_next(coap_context_t *context) {
266 if (!context || !context->sendqueue)
269 next = context->sendqueue;
270 context->sendqueue = context->sendqueue->next;
271 if (context->sendqueue) {
272 context->sendqueue->t += next->t;
278 #ifdef COAP_DEFAULT_WKC_HASHKEY
279 /** Checks if @p Key is equal to the pre-defined hash key for.well-known/core. */
280 #define is_wkc(Key) \
281 (memcmp((Key), COAP_DEFAULT_WKC_HASHKEY, sizeof(coap_key_t)) == 0)
283 /* Implements a singleton to store a hash key for the .wellknown/core
286 is_wkc(coap_key_t k) {
287 static coap_key_t wkc;
288 static unsigned char _initialized = 0;
290 _initialized = coap_hash_path((unsigned char *)COAP_DEFAULT_URI_WELLKNOWN,
291 sizeof(COAP_DEFAULT_URI_WELLKNOWN) - 1, wkc);
293 return memcmp(k, wkc, sizeof(coap_key_t)) == 0;
298 coap_new_context(const coap_address_t *listen_addr) {
300 coap_context_t *c = (coap_context_t*)coap_malloc( sizeof( coap_context_t ) );
302 #endif /* WITH_POSIX */
304 coap_context_t *c = memp_malloc(MEMP_COAP_CONTEXT);
305 #endif /* WITH_LWIP */
311 #endif /* WITH_CONTIKI */
314 coap_log(LOG_EMERG, "no listen address specified\n");
320 prng_init(LWIP_RAND());
321 #else /* WITH_LWIP */
322 prng_init((unsigned long)listen_addr ^ clock_offset);
323 #endif /* WITH_LWIP */
328 coap_log(LOG_EMERG, "coap_init: malloc:\n");
332 #endif /* not WITH_CONTIKI */
334 coap_resources_init();
335 coap_pdu_resources_init();
337 c = &the_coap_context;
339 #endif /* WITH_CONTIKI */
341 memset(c, 0, sizeof(coap_context_t));
343 /* set well-known sockfd to uninitialize value */
344 c->sockfd_wellknown = -1;
346 /* initialize message id */
347 prng((unsigned char * )&c->message_id, sizeof(unsigned short));
349 /* register the critical options that we know */
350 coap_register_option(c, COAP_OPTION_IF_MATCH);
351 coap_register_option(c, COAP_OPTION_URI_HOST);
352 coap_register_option(c, COAP_OPTION_IF_NONE_MATCH);
353 coap_register_option(c, COAP_OPTION_URI_PORT);
354 coap_register_option(c, COAP_OPTION_URI_PATH);
355 coap_register_option(c, COAP_OPTION_URI_QUERY);
356 coap_register_option(c, COAP_OPTION_ACCEPT);
357 coap_register_option(c, COAP_OPTION_PROXY_URI);
358 coap_register_option(c, COAP_OPTION_PROXY_SCHEME);
359 coap_register_option(c, COAP_OPTION_BLOCK2);
360 coap_register_option(c, COAP_OPTION_BLOCK1);
364 c->sockfd = socket(listen_addr->addr.sa.sa_family, SOCK_DGRAM, 0);
365 if ( c->sockfd < 0 ) {
367 coap_log(LOG_EMERG, "coap_new_context: socket\n");
368 #endif /* WITH_NDEBUG */
372 if ( setsockopt( c->sockfd, SOL_SOCKET, SO_REUSEADDR, &reuse, sizeof(reuse) ) < 0 ) {
374 coap_log(LOG_WARNING, "setsockopt SO_REUSEADDR\n");
378 if (bind(c->sockfd, &listen_addr->addr.sa, listen_addr->size) < 0) {
380 coap_log(LOG_EMERG, "coap_new_context: bind\n");
388 if ( c->sockfd >= 0 )
393 if (OCInitUDP((OCDevAddr *)listen_addr, (int32_t *)&(c->sockfd)) != ERR_SUCCESS) {
401 #endif /* WITH_POSIX */
403 c->conn = udp_new(NULL, 0, NULL);
404 udp_bind(c->conn, listen_addr->port);
406 process_start(&coap_retransmit_process, (char *)c);
408 PROCESS_CONTEXT_BEGIN(&coap_retransmit_process);
409 #ifndef WITHOUT_OBSERVE
410 etimer_set(&c->notify_timer, COAP_RESOURCE_CHECK_TIME * COAP_TICKS_PER_SECOND);
411 #endif /* WITHOUT_OBSERVE */
412 /* the retransmit timer must be initialized to some large value */
413 etimer_set(&the_coap_context.retransmit_timer, 0xFFFF);
414 PROCESS_CONTEXT_END(&coap_retransmit_process);
416 #endif /* WITH_CONTIKI */
419 /* hard assert: this is not expected to fail dynamically */
420 LWIP_ASSERT("Failed to allocate PCB for CoAP", c->pcb != NULL);
422 udp_recv(c->pcb, received_package, (void*)c);
423 udp_bind(c->pcb, &listen_addr->addr, listen_addr->port);
425 c->timer_configured = 0;
431 void coap_free_context(coap_context_t *context) {
432 #if defined(WITH_POSIX) || defined(WITH_LWIP)
433 coap_resource_t *res;
434 #ifndef COAP_RESOURCES_NOHASH
435 coap_resource_t *rtmp;
437 #endif /* WITH_POSIX || WITH_LWIP */
441 coap_delete_all(context->recvqueue);
442 coap_delete_all(context->sendqueue);
445 context->sendqueue = NULL;
446 coap_retransmittimer_restart(context);
449 #if defined(WITH_POSIX) || defined(WITH_LWIP)
450 #ifdef COAP_RESOURCES_NOHASH
451 LL_FOREACH(context->resources, res) {
453 HASH_ITER(hh, context->resources, res, rtmp) {
455 coap_delete_resource(context, res->key);
457 #endif /* WITH_POSIX || WITH_LWIP */
460 /* coap_delete_list(context->subscriptions); */
461 OCClose( context->sockfd );
462 if (context->sockfd_wellknown != -1) {
463 OCClose( context->sockfd_wellknown );
465 coap_free( context );
468 udp_remove(context->pcb);
469 memp_free(MEMP_COAP_CONTEXT, context);
472 memset(&the_coap_context, 0, sizeof(coap_context_t));
474 #endif /* WITH_CONTIKI */
477 int coap_join_wellknown_group(coap_context_t *ctx,
478 const coap_address_t *multicast_addr) {
480 if (OCInitUDPMulticast((OCDevAddr *)multicast_addr,
481 (int32_t *)&(ctx->sockfd_wellknown)) != ERR_SUCCESS) {
488 int coap_option_check_critical(coap_context_t *ctx, coap_pdu_t *pdu,
489 coap_opt_filter_t unknown) {
491 coap_opt_iterator_t opt_iter;
494 coap_option_iterator_init(pdu, &opt_iter, COAP_OPT_ALL);
496 while (coap_option_next(&opt_iter)) {
498 /* The following condition makes use of the fact that
499 * coap_option_getb() returns -1 if type exceeds the bit-vector
500 * filter. As the vector is supposed to be large enough to hold
501 * the largest known option, we know that everything beyond is
504 if (opt_iter.type & 0x01
505 && coap_option_getb(ctx->known_options, opt_iter.type) < 1) {
506 debug("unknown critical option %d\n", opt_iter.type);
510 /* When opt_iter.type is beyond our known option range,
511 * coap_option_setb() will return -1 and we are safe to leave
513 if (coap_option_setb(unknown, opt_iter.type) == -1)
521 void coap_transaction_id(const coap_address_t *peer, const coap_pdu_t *pdu,
525 memset(h, 0, sizeof(coap_key_t));
527 /* Compare the complete address structure in case of IPv4. For IPv6,
528 * we need to look at the transport address only. */
531 switch (peer->addr.sa.sa_family) {
533 coap_hash((const unsigned char *)&peer->addr.sa, peer->size, h);
536 coap_hash((const unsigned char *)&peer->addr.sin6.sin6_port,
537 sizeof(peer->addr.sin6.sin6_port), h);
538 coap_hash((const unsigned char *)&peer->addr.sin6.sin6_addr,
539 sizeof(peer->addr.sin6.sin6_addr), h);
545 #if defined(WITH_LWIP) || defined(WITH_CONTIKI)
546 /* FIXME: with lwip, we can do better */
547 coap_hash((const unsigned char *)&peer->port, sizeof(peer->port), h);
548 coap_hash((const unsigned char *)&peer->addr, sizeof(peer->addr), h);
549 #endif /* WITH_LWIP || WITH_CONTIKI */
551 coap_hash((const unsigned char * )&pdu->hdr->id, sizeof(unsigned short), h);
553 *id = ((h[0] << 8) | h[1]) ^ ((h[2] << 8) | h[3]);
556 coap_tid_t coap_send_ack(coap_context_t *context, const coap_address_t *dst,
557 coap_pdu_t *request) {
558 coap_pdu_t *response;
559 coap_tid_t result = COAP_INVALID_TID;
561 if (request && request->hdr->type == COAP_MESSAGE_CON) {
562 response = coap_pdu_init(COAP_MESSAGE_ACK, 0, request->hdr->id,
565 result = coap_send(context, dst, response);
566 coap_delete_pdu(response);
573 /* releases space allocated by PDU if free_pdu is set */
575 coap_send_impl(coap_context_t *context,
576 const coap_address_t *dst,
578 ssize_t bytes_written;
579 coap_tid_t id = COAP_INVALID_TID;
581 if ( !context || !dst || !pdu )
584 //bytes_written = sendto( context->sockfd, pdu->hdr, pdu->length, 0,
585 // &dst->addr.sa, dst->size);
586 bytes_written = OCSendTo( context->sockfd, (uint8_t*)(pdu->hdr), pdu->length, 0,
588 printf("bytes_written %d\n", (int)bytes_written);
590 if (bytes_written >= 0) {
591 coap_transaction_id(dst, pdu, &id);
593 coap_log(LOG_CRIT, "coap_send: sendto\n");
598 #endif /* WITH_POSIX */
600 /* releases space allocated by PDU if free_pdu is set */
602 coap_send_impl(coap_context_t *context,
603 const coap_address_t *dst,
605 coap_tid_t id = COAP_INVALID_TID;
607 if ( !context || !dst || !pdu )
610 /* FIXME: is there a way to check if send was successful? */
611 uip_udp_packet_sendto(context->conn, pdu->hdr, pdu->length,
612 &dst->addr, dst->port);
614 coap_transaction_id(dst, pdu, &id);
618 #endif /* WITH_CONTIKI */
621 coap_send_impl(coap_context_t *context,
622 const coap_address_t *dst,
624 coap_tid_t id = COAP_INVALID_TID;
629 if ( !context || !dst || !pdu )
634 data_backup = pdu->data;
636 /* FIXME: we can't check this here with the existing infrastructure, but we
637 * should actually check that the pdu is not held by anyone but us. the
638 * respective pbuf is already exclusively owned by the pdu. */
641 LWIP_ASSERT("The PDU header is not where it is expected", pdu->hdr == p->payload + sizeof(coap_pdu_t));
643 err = pbuf_header(p, -sizeof(coap_pdu_t));
646 debug("coap_send_impl: pbuf_header failed\n");
651 coap_transaction_id(dst, pdu, &id);
653 pbuf_realloc(p, pdu->length);
655 udp_sendto(context->pcb, p,
656 &dst->addr, dst->port);
658 pbuf_header(p, -(ptrdiff_t)((uint8_t*)pdu - (uint8_t*)p->payload) - sizeof(coap_pdu_t)); /* FIXME hack around udp_sendto not restoring; see http://lists.gnu.org/archive/html/lwip-users/2013-06/msg00008.html. for udp over ip over ethernet, this was -42; as we're doing ppp too, this has to be calculated generically */
660 err = pbuf_header(p, sizeof(coap_pdu_t));
661 LWIP_ASSERT("Cannot undo pbuf_header", err == 0);
663 /* restore destroyed pdu data */
664 LWIP_ASSERT("PDU not restored", p->payload == pdu);
665 pdu->max_size = p->tot_len - sizeof(coap_pdu_t); /* reduced after pbuf_realloc */
666 pdu->hdr = p->payload + sizeof(coap_pdu_t);
667 pdu->max_delta = 0; /* won't be used any more */
668 pdu->length = pdu->max_size;
669 pdu->data = data_backup;
674 #endif /* WITH_LWIP */
676 coap_tid_t coap_send(coap_context_t *context, const coap_address_t *dst,
678 return coap_send_impl(context, dst, pdu);
681 coap_tid_t coap_send_error(coap_context_t *context, coap_pdu_t *request,
682 const coap_address_t *dst, unsigned char code, coap_opt_filter_t opts) {
683 coap_pdu_t *response;
684 coap_tid_t result = COAP_INVALID_TID;
689 response = coap_new_error_response(request, code, opts);
691 result = coap_send(context, dst, response);
692 coap_delete_pdu(response);
698 coap_tid_t coap_send_message_type(coap_context_t *context,
699 const coap_address_t *dst, coap_pdu_t *request, unsigned char type) {
700 coap_pdu_t *response;
701 coap_tid_t result = COAP_INVALID_TID;
704 response = coap_pdu_init(type, 0, request->hdr->id, sizeof(coap_pdu_t));
706 result = coap_send(context, dst, response);
707 coap_delete_pdu(response);
713 coap_tid_t coap_send_confirmed(coap_context_t *context,
714 const coap_address_t *dst, coap_pdu_t *pdu) {
719 node = coap_new_node();
721 debug("coap_send_confirmed: insufficient memory\n");
722 return COAP_INVALID_TID;
725 node->id = coap_send_impl(context, dst, pdu);
726 if (COAP_INVALID_TID == node->id) {
727 debug("coap_send_confirmed: error sending pdu\n");
728 coap_free_node(node);
729 return COAP_INVALID_TID;
732 prng((unsigned char * )&r, sizeof(r));
734 /* add randomized RESPONSE_TIMEOUT to determine retransmission timeout */
735 node->timeout = COAP_DEFAULT_RESPONSE_TIMEOUT * COAP_TICKS_PER_SECOND
736 + (COAP_DEFAULT_RESPONSE_TIMEOUT >> 1)
737 * ((COAP_TICKS_PER_SECOND * (r & 0xFF)) >> 8);
739 memcpy(&node->remote, dst, sizeof(coap_address_t));
742 /* Set timer for pdu retransmission. If this is the first element in
743 * the retransmission queue, the base time is set to the current
744 * time and the retransmission time is node->timeout. If there is
745 * already an entry in the sendqueue, we must check if this node is
746 * to be retransmitted earlier. Therefore, node->timeout is first
747 * normalized to the base time and then inserted into the queue with
748 * an adjusted relative time.
750 if (context->sendqueue == NULL) {
751 node->t = node->timeout;
752 context->sendqueue_basetime = now;
754 /* make node->t relative to context->sendqueue_basetime */
755 node->t = (now - context->sendqueue_basetime) + node->timeout;
758 coap_insert_node(&context->sendqueue, node);
761 if (node == context->sendqueue) /* don't bother with timer stuff if there are earlier retransmits */
762 coap_retransmittimer_restart(context);
766 { /* (re-)initialize retransmission timer */
767 coap_queue_t *nextpdu;
769 nextpdu = coap_peek_next(context);
770 assert(nextpdu); /* we have just inserted a node */
772 /* must set timer within the context of the retransmit process */
773 PROCESS_CONTEXT_BEGIN(&coap_retransmit_process);
774 etimer_set(&context->retransmit_timer, nextpdu->t);
775 PROCESS_CONTEXT_END(&coap_retransmit_process);
777 #endif /* WITH_CONTIKI */
782 coap_tid_t coap_retransmit(coap_context_t *context, coap_queue_t *node) {
783 if (!context || !node)
784 return COAP_INVALID_TID;
786 /* re-initialize timeout when maximum number of retransmissions are not reached yet */
787 if (node->retransmit_cnt < COAP_DEFAULT_MAX_RETRANSMIT) {
788 node->retransmit_cnt++;
789 node->t = node->timeout << node->retransmit_cnt;
790 coap_insert_node(&context->sendqueue, node);
792 if (node == context->sendqueue) /* don't bother with timer stuff if there are earlier retransmits */
793 coap_retransmittimer_restart(context);
796 debug("** retransmission #%d of transaction %d\n", node->retransmit_cnt,
797 ntohs(node->pdu->hdr->id));
799 node->id = coap_send_impl(context, &node->remote, node->pdu);
803 /* no more retransmissions, remove node from system */
806 debug("** removed transaction %d\n", ntohs(node->id));
809 #ifndef WITHOUT_OBSERVE
810 /* Check if subscriptions exist that should be canceled after
811 COAP_MAX_NOTIFY_FAILURES */
812 if (node->pdu->hdr->code >= 64) {
813 str token = { 0, NULL };
815 token.length = node->pdu->hdr->token_length;
816 token.s = node->pdu->hdr->token;
818 coap_handle_failed_notify(context, &node->remote, &token);
820 #endif /* WITHOUT_OBSERVE */
822 /* And finally delete the node */
823 coap_delete_node(node);
824 return COAP_INVALID_TID;
828 * Checks if @p opt fits into the message that ends with @p maxpos.
829 * This function returns @c 1 on success, or @c 0 if the option @p opt
830 * would exceed @p maxpos.
832 static inline int check_opt_size(coap_opt_t *opt, unsigned char *maxpos) {
833 if (opt && opt < maxpos) {
834 if (((*opt & 0x0f) < 0x0f) || (opt + 1 < maxpos))
835 return opt + COAP_OPT_SIZE(opt) < maxpos;
840 int coap_read(coap_context_t *ctx, int sockfd) {
842 static char buf[COAP_MAX_PDU_SIZE];
844 #if defined(WITH_LWIP) || defined(WITH_CONTIKI)
848 ssize_t bytes_read = -1;
849 coap_address_t src, dst;
854 #endif /* WITH_CONTIKI */
856 LWIP_ASSERT("No package pending", ctx->pending_package != NULL);
857 LWIP_ASSERT("Can only deal with contiguous PBUFs to read the initial details", ctx->pending_package->tot_len == ctx->pending_package->len);
858 buf = ctx->pending_package->payload;
859 #endif /* WITH_LWIP */
861 pdu = (coap_hdr_t *) buf;
863 coap_address_init(&src);
866 //bytes_read = recvfrom(ctx->sockfd, buf, sizeof(buf), 0,
867 // &src.addr.sa, &src.size);
869 bytes_read = OCRecvFrom( sockfd, (uint8_t*)buf, sizeof(buf), 0,
871 #endif /* WITH_POSIX */
874 uip_ipaddr_copy(&src.addr, &UIP_IP_BUF->srcipaddr);
875 src.port = UIP_UDP_BUF->srcport;
876 uip_ipaddr_copy(&dst.addr, &UIP_IP_BUF->destipaddr);
877 dst.port = UIP_UDP_BUF->destport;
879 bytes_read = uip_datalen();
880 ((char *)uip_appdata)[bytes_read] = 0;
881 PRINTF("Server received %d bytes from [", (int)bytes_read);
882 PRINT6ADDR(&src.addr);
883 PRINTF("]:%d\n", uip_ntohs(src.port));
885 #endif /* WITH_CONTIKI */
887 /* FIXME: use lwip address operation functions */
888 src.addr.addr = ctx->pending_address.addr;
889 src.port = ctx->pending_port;
890 bytes_read = ctx->pending_package->tot_len;
891 #endif /* WITH_LWIP */
893 if (bytes_read < 0) {
894 warn("coap_read: recvfrom");
898 if ((size_t) bytes_read < sizeof(coap_hdr_t)) {
899 debug("coap_read: discarded invalid frame\n");
903 if (pdu->version != COAP_DEFAULT_VERSION) {
904 debug("coap_read: unknown protocol version\n");
908 node = coap_new_node();
913 node->pdu = coap_pdu_from_pbuf(ctx->pending_package);
914 ctx->pending_package = NULL;
916 node->pdu = coap_pdu_init(0, 0, 0, bytes_read);
921 coap_ticks(&node->t);
922 memcpy(&node->local, &dst, sizeof(coap_address_t));
923 memcpy(&node->remote, &src, sizeof(coap_address_t));
925 if (!coap_pdu_parse((unsigned char *) buf, bytes_read, node->pdu)) {
926 warn("discard malformed PDU");
930 /* and add new node to receive queue */
931 coap_transaction_id(&node->remote, node->pdu, &node->id);
932 coap_insert_node(&ctx->recvqueue, node);
935 if (LOG_DEBUG <= coap_get_log_level()) {
936 #ifndef INET6_ADDRSTRLEN
937 #define INET6_ADDRSTRLEN 40
939 unsigned char addr[INET6_ADDRSTRLEN + 8];
941 if (coap_print_addr(&src, addr, INET6_ADDRSTRLEN + 8))
942 debug("** received %d bytes from %s:\n", (int )bytes_read, addr);
944 coap_show_pdu(node->pdu);
951 /* FIXME: send back RST? */
952 coap_delete_node(node);
956 /* even if there was an error, clean up */
957 pbuf_free(ctx->pending_package);
958 ctx->pending_package = NULL;
963 int coap_remove_from_queue(coap_queue_t **queue, coap_tid_t id,
964 coap_queue_t **node) {
967 if (!queue || !*queue)
970 /* replace queue head if PDU's time is less than head's time */
972 if (id == (*queue)->id) { /* found transaction */
974 *queue = (*queue)->next;
975 if (*queue) { /* adjust relative time of new queue head */
976 (*queue)->t += (*node)->t;
978 (*node)->next = NULL;
979 /* coap_delete_node( q ); */
980 debug("*** removed transaction %u\n", id);
984 /* search transaction to remove (only first occurence will be removed) */
989 } while (q && id != q->id);
991 if (q) { /* found transaction */
993 if (p->next) { /* must update relative time of p->next */
998 /* coap_delete_node( q ); */
999 debug("*** removed transaction %u\n", id);
1007 static inline int token_match(const unsigned char *a, size_t alen,
1008 const unsigned char *b, size_t blen) {
1009 return alen == blen && (alen == 0 || memcmp(a, b, alen) == 0);
1012 void coap_cancel_all_messages(coap_context_t *context,
1013 const coap_address_t *dst, const unsigned char *token,
1014 size_t token_length) {
1015 /* cancel all messages in sendqueue that are for dst
1016 * and use the specified token */
1017 coap_queue_t *p, *q;
1019 debug("cancel_all_messages\n");
1020 while (context->sendqueue
1021 && coap_address_equals(dst, &context->sendqueue->remote)
1022 && token_match(token, token_length,
1023 context->sendqueue->pdu->hdr->token,
1024 context->sendqueue->pdu->hdr->token_length)) {
1025 q = context->sendqueue;
1026 context->sendqueue = q->next;
1027 debug("**** removed transaction %d\n", ntohs(q->pdu->hdr->id));
1028 coap_delete_node(q);
1031 if (!context->sendqueue)
1034 p = context->sendqueue;
1037 /* when q is not NULL, it does not match (dst, token), so we can skip it */
1039 if (coap_address_equals(dst, &q->remote)
1040 && token_match(token, token_length, q->pdu->hdr->token,
1041 q->pdu->hdr->token_length)) {
1043 debug("**** removed transaction %d\n", ntohs(q->pdu->hdr->id));
1044 coap_delete_node(q);
1054 coap_find_transaction(coap_queue_t *queue, coap_tid_t id) {
1055 while (queue && queue->id != id)
1056 queue = queue->next;
1062 coap_new_error_response(coap_pdu_t *request, unsigned char code,
1063 coap_opt_filter_t opts) {
1064 coap_opt_iterator_t opt_iter;
1065 coap_pdu_t *response;
1066 size_t size = sizeof(coap_hdr_t) + request->hdr->token_length;
1069 unsigned short opt_type = 0; /* used for calculating delta-storage */
1071 #if COAP_ERROR_PHRASE_LENGTH > 0
1072 char *phrase = coap_response_phrase(code);
1074 /* Need some more space for the error phrase and payload start marker */
1076 size += strlen(phrase) + 1;
1081 /* cannot send ACK if original request was not confirmable */
1082 type = request->hdr->type == COAP_MESSAGE_CON ?
1083 COAP_MESSAGE_ACK : COAP_MESSAGE_NON;
1085 /* Estimate how much space we need for options to copy from
1086 * request. We always need the Token, for 4.02 the unknown critical
1087 * options must be included as well. */
1088 coap_option_clrb(opts, COAP_OPTION_CONTENT_TYPE); /* we do not want this */
1090 coap_option_iterator_init(request, &opt_iter, opts);
1092 /* Add size of each unknown critical option. As known critical
1093 options as well as elective options are not copied, the delta
1096 while ((option = coap_option_next(&opt_iter))) {
1097 unsigned short delta = opt_iter.type - opt_type;
1098 /* calculate space required to encode (opt_iter.type - opt_type) */
1101 } else if (delta < 269) {
1107 /* add coap_opt_length(option) and the number of additional bytes
1108 * required to encode the option length */
1110 size += coap_opt_length(option);
1111 switch (*option & 0x0f) {
1122 opt_type = opt_iter.type;
1125 /* Now create the response and fill with options and payload data. */
1126 response = coap_pdu_init(type, code, request->hdr->id, size);
1129 if (!coap_add_token(response, request->hdr->token_length,
1130 request->hdr->token)) {
1131 debug("cannot add token to error response\n");
1132 coap_delete_pdu(response);
1136 /* copy all options */
1137 coap_option_iterator_init(request, &opt_iter, opts);
1138 while ((option = coap_option_next(&opt_iter)))
1139 coap_add_option(response, opt_iter.type, COAP_OPT_LENGTH(option),
1140 COAP_OPT_VALUE(option));
1142 #if COAP_ERROR_PHRASE_LENGTH > 0
1143 /* note that diagnostic messages do not need a Content-Format option. */
1145 coap_add_data(response, strlen(phrase), (unsigned char *) phrase);
1153 * Quick hack to determine the size of the resource description for
1156 static inline size_t get_wkc_len(coap_context_t *context,
1157 coap_opt_t *query_filter) {
1158 unsigned char buf[1];
1161 if (print_wellknown(context, buf, &len, UINT_MAX,
1162 query_filter) & COAP_PRINT_STATUS_ERROR) {
1163 warn("cannot determine length of /.well-known/core\n");
1167 debug("get_wkc_len: print_wellknown() returned %zu\n", len);
1172 #define SZX_TO_BYTES(SZX) ((size_t)(1 << ((SZX) + 4)))
1175 wellknown_response(coap_context_t *context, coap_pdu_t *request) {
1177 coap_opt_iterator_t opt_iter;
1178 size_t len, wkc_len;
1179 unsigned char buf[2];
1181 int need_block2 = 0; /* set to 1 if Block2 option is required */
1183 coap_opt_t *query_filter;
1186 resp = coap_pdu_init(
1187 request->hdr->type == COAP_MESSAGE_CON ?
1188 COAP_MESSAGE_ACK : COAP_MESSAGE_NON,
1189 COAP_RESPONSE_CODE(205), request->hdr->id, COAP_MAX_PDU_SIZE);
1191 debug("wellknown_response: cannot create PDU\n");
1195 if (!coap_add_token(resp, request->hdr->token_length,
1196 request->hdr->token)) {
1197 debug("wellknown_response: cannot add token\n");
1201 query_filter = coap_check_option(request, COAP_OPTION_URI_QUERY, &opt_iter);
1202 wkc_len = get_wkc_len(context, query_filter);
1204 /* check whether the request contains the Block2 option */
1205 if (coap_get_block(request, COAP_OPTION_BLOCK2, &block)) {
1206 offset = block.num << (block.szx + 4);
1207 if (block.szx > 6) { /* invalid, MUST lead to 4.00 Bad Request */
1208 resp->hdr->code = COAP_RESPONSE_CODE(400);
1210 } else if (block.szx > COAP_MAX_BLOCK_SZX) {
1211 block.szx = COAP_MAX_BLOCK_SZX;
1212 block.num = offset >> (block.szx + 4);
1218 /* Check if there is sufficient space to add Content-Format option
1219 * and data. We do this before adding the Content-Format option to
1220 * avoid sending error responses with that option but no actual
1222 if (resp->max_size <= (size_t) resp->length + 3) {
1223 debug("wellknown_response: insufficient storage space\n");
1227 /* Add Content-Format. As we have checked for available storage,
1228 * nothing should go wrong here. */
1230 coap_encode_var_bytes(buf, COAP_MEDIATYPE_APPLICATION_LINK_FORMAT)
1232 coap_add_option(resp, COAP_OPTION_CONTENT_FORMAT,
1233 coap_encode_var_bytes(buf, COAP_MEDIATYPE_APPLICATION_LINK_FORMAT),
1236 /* check if Block2 option is required even if not requested */
1237 if (!need_block2 && (resp->max_size - (size_t) resp->length < wkc_len)) {
1238 assert(resp->length <= resp->max_size);
1239 const size_t payloadlen = resp->max_size - resp->length;
1240 /* yes, need block-wise transfer */
1242 block.m = 0; /* the M bit is set by coap_write_block_opt() */
1243 block.szx = COAP_MAX_BLOCK_SZX;
1244 while (payloadlen < SZX_TO_BYTES(block.szx)) {
1245 if (block.szx == 0) {
1247 "wellknown_response: message to small even for szx == 0\n");
1257 /* write Block2 option if necessary */
1259 if (coap_write_block_opt(&block, COAP_OPTION_BLOCK2, resp, wkc_len)
1261 debug("wellknown_response: cannot add Block2 option\n");
1266 /* Manually set payload of response to let print_wellknown() write,
1267 * into our buffer without copying data. */
1269 resp->data = (unsigned char *) resp->hdr + resp->length;
1270 *resp->data = COAP_PAYLOAD_START;
1273 len = need_block2 ? SZX_TO_BYTES(block.szx) : resp->max_size - resp->length;
1275 result = print_wellknown(context, resp->data, &len, offset, query_filter);
1276 if ((result & COAP_PRINT_STATUS_ERROR) != 0) {
1277 debug("print_wellknown failed\n");
1281 resp->length += COAP_PRINT_OUTPUT_LENGTH(result);
1285 /* set error code 5.03 and remove all options and data from response */
1286 resp->hdr->code = COAP_RESPONSE_CODE(503);
1287 resp->length = sizeof(coap_hdr_t) + resp->hdr->token_length;
1291 #define WANT_WKC(Pdu,Key) \
1292 (((Pdu)->hdr->code == COAP_REQUEST_GET) && is_wkc(Key))
1296 handle_request(coap_context_t *context, coap_queue_t *node) {
1297 coap_method_handler_t h = NULL;
1298 coap_pdu_t *response = NULL;
1299 coap_opt_filter_t opt_filter;
1300 coap_resource_t *resource;
1303 coap_option_filter_clear(opt_filter);
1305 /* try to find the resource from the request URI */
1306 coap_hash_request_uri(node->pdu, key);
1307 resource = coap_get_resource_from_key(context, key);
1310 /* The resource was not found. Check if the request URI happens to
1311 * be the well-known URI. In that case, we generate a default
1312 * response, otherwise, we return 4.04 */
1314 switch(node->pdu->hdr->code) {
1316 case COAP_REQUEST_GET:
1317 if (is_wkc(key)) { /* GET request for .well-known/core */
1318 info("create default response for %s\n", COAP_DEFAULT_URI_WELLKNOWN);
1319 response = wellknown_response(context, node->pdu);
1321 } else { /* GET request for any another resource, return 4.04 */
1323 debug("GET for unknown resource 0x%02x%02x%02x%02x, return 4.04\n",
1324 key[0], key[1], key[2], key[3]);
1326 coap_new_error_response(node->pdu, COAP_RESPONSE_CODE(404),
1331 default: /* any other request type */
1333 debug("unhandled request for unknown resource 0x%02x%02x%02x%02x\r\n",
1334 key[0], key[1], key[2], key[3]);
1335 if (!coap_is_mcast(&node->local))
1336 response = coap_new_error_response(node->pdu, COAP_RESPONSE_CODE(405),
1340 if (response && coap_send(context, &node->remote, response) == COAP_INVALID_TID) {
1341 warn("cannot send response for transaction %u\n", node->id);
1343 coap_delete_pdu(response);
1348 /* the resource was found, check if there is a registered handler */
1349 if ((size_t)node->pdu->hdr->code - 1 <
1350 sizeof(resource->handler)/sizeof(coap_method_handler_t))
1351 h = resource->handler[node->pdu->hdr->code - 1];
1354 debug("call custom handler for resource 0x%02x%02x%02x%02x\n",
1355 key[0], key[1], key[2], key[3]);
1356 response = coap_pdu_init(node->pdu->hdr->type == COAP_MESSAGE_CON
1359 0, node->pdu->hdr->id, COAP_MAX_PDU_SIZE);
1361 /* Implementation detail: coap_add_token() immediately returns 0
1362 if response == NULL */
1363 if (coap_add_token(response, node->pdu->hdr->token_length,
1364 node->pdu->hdr->token)) {
1365 str token = {node->pdu->hdr->token_length, node->pdu->hdr->token};
1367 h(context, resource, &node->remote,
1368 node->pdu, &token, response);
1369 if (response->hdr->type != COAP_MESSAGE_NON ||
1370 (response->hdr->code >= 64
1371 && !coap_is_mcast(&node->local))) {
1372 if (coap_send(context, &node->remote, response) == COAP_INVALID_TID) {
1373 debug("cannot send response for message %d\n", node->pdu->hdr->id);
1377 coap_delete_pdu(response);
1379 warn("cannot generate response\r\n");
1382 if (WANT_WKC(node->pdu, key)) {
1383 debug("create default response for %s\n", COAP_DEFAULT_URI_WELLKNOWN);
1384 response = wellknown_response(context, node->pdu);
1386 response = coap_new_error_response(node->pdu, COAP_RESPONSE_CODE(405),
1389 if (!response || (coap_send(context, &node->remote, response)
1390 == COAP_INVALID_TID)) {
1391 debug("cannot send response for transaction %u\n", node->id);
1393 coap_delete_pdu(response);
1397 static inline void handle_request(coap_context_t *context, coap_queue_t *rcvd) {
1399 /* Call application-specific reponse handler when available. If
1400 * not, we must acknowledge confirmable messages. */
1401 if (context->request_handler) {
1402 context->request_handler(context, rcvd);
1404 /* send ACK if rcvd is confirmable (i.e. a separate response) */
1405 coap_send_ack(context, &rcvd->remote, rcvd->pdu);
1409 static inline void handle_response(coap_context_t *context, coap_queue_t *rcvd) {
1411 /* Call application-specific reponse handler when available. If
1412 * not, we must acknowledge confirmable messages. */
1413 if (context->response_handler) {
1414 context->response_handler(context, rcvd);
1416 /* send ACK if rcvd is confirmable (i.e. a separate response) */
1417 coap_send_ack(context, &rcvd->remote, rcvd->pdu);
1423 handle_locally(coap_context_t *context __attribute__ ((unused)),
1424 coap_queue_t *node __attribute__ ((unused))) {
1425 #else /* not a GCC */
1426 handle_locally(coap_context_t *context, coap_queue_t *node) {
1428 /* this function can be used to check if node->pdu is really for us */
1433 * This function handles RST messages received for the message passed
1436 static void coap_handle_rst(coap_context_t *context,
1437 const coap_queue_t *sent) {
1438 #ifndef WITHOUT_OBSERVE
1440 #ifndef COAP_RESOURCES_NOHASH
1441 coap_resource_t *tmp;
1443 str token = { 0, NULL };
1445 /* remove observer for this resource, if any
1446 * get token from sent and try to find a matching resource. Uh!
1449 COAP_SET_STR(&token, sent->pdu->hdr->token_length,
1450 sent->pdu->hdr->token);
1452 #ifndef WITH_CONTIKI
1453 #ifdef COAP_RESOURCES_NOHASH
1454 LL_FOREACH(context->resources, r) {
1456 HASH_ITER(hh, context->resources, r, tmp)
1459 coap_delete_observer(r, &sent->remote, &token);
1460 coap_cancel_all_messages(context, &sent->remote, token.s,
1463 #else /* WITH_CONTIKI */
1464 r = (coap_resource_t *)resource_storage.mem;
1465 for (i = 0; i < resource_storage.num; ++i, ++r) {
1466 if (resource_storage.count[i]) {
1467 coap_delete_observer(r, &sent->remote, &token);
1468 coap_cancel_all_messages(context, &sent->remote, token.s, token.length);
1471 #endif /* WITH_CONTIKI */
1472 #endif /* WITOUT_OBSERVE */
1475 void coap_dispatch(coap_context_t *context) {
1476 coap_queue_t *rcvd = NULL, *sent = NULL;
1477 coap_pdu_t *response;
1478 coap_opt_filter_t opt_filter;
1483 memset(opt_filter, 0, sizeof(coap_opt_filter_t));
1485 while (context->recvqueue) {
1486 rcvd = context->recvqueue;
1488 /* remove node from recvqueue */
1489 context->recvqueue = context->recvqueue->next;
1492 if (rcvd->pdu->hdr->version != COAP_DEFAULT_VERSION) {
1493 debug("dropped packet with unknown version %u\n",
1494 rcvd->pdu->hdr->version);
1498 switch (rcvd->pdu->hdr->type) {
1499 case COAP_MESSAGE_NON: /* check for unknown critical options */
1500 if (coap_option_check_critical(context, rcvd->pdu, opt_filter)
1505 // TODO : need to handle other message types in coap_dispatch;;;;;;;;;;;;;;;;
1506 debug("Need to handle other message types in coap_dispatch;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;");
1509 switch (rcvd->pdu->hdr->type) {
1510 case COAP_MESSAGE_ACK:
1511 /* find transaction in sendqueue to stop retransmission */
1512 coap_remove_from_queue(&context->sendqueue, rcvd->id, &sent);
1514 if (rcvd->pdu->hdr->code == 0)
1517 /* FIXME: if sent code was >= 64 the message might have been a
1518 * notification. Then, we must flag the observer to be alive
1519 * by setting obs->fail_cnt = 0. */
1520 if (sent && COAP_RESPONSE_CLASS(sent->pdu->hdr->code) == 2) {
1521 const str token = {sent->pdu->hdr->token_length,
1522 sent->pdu->hdr->token};
1523 coap_touch_observer(context, &sent->remote, &token);
1527 case COAP_MESSAGE_RST:
1528 /* We have sent something the receiver disliked, so we remove
1529 * not only the transaction but also the subscriptions we might
1532 coap_log(LOG_ALERT, "got RST for message %u\n",
1533 ntohs(rcvd->pdu->hdr->id));
1535 /* find transaction in sendqueue to stop retransmission */
1536 coap_remove_from_queue(&context->sendqueue, rcvd->id, &sent);
1539 coap_handle_rst(context, sent);
1542 case COAP_MESSAGE_NON: /* check for unknown critical options */
1543 if (coap_option_check_critical(context, rcvd->pdu, opt_filter)
1548 case COAP_MESSAGE_CON: /* check for unknown critical options */
1549 if (coap_option_check_critical(context, rcvd->pdu, opt_filter)
1552 /* FIXME: send response only if we have received a request. Otherwise,
1554 response = coap_new_error_response(rcvd->pdu,
1555 COAP_RESPONSE_CODE(402), opt_filter);
1558 warn("coap_dispatch: cannot create error reponse\n");
1560 if (coap_send(context, &rcvd->remote,
1561 response) == COAP_INVALID_TID) {
1562 warn("coap_dispatch: error sending reponse\n");
1564 coap_delete_pdu(response);
1573 /* Pass message to upper layer if a specific handler was
1574 * registered for a request that should be handled locally. */
1575 if (handle_locally(context, rcvd)) {
1576 if (COAP_MESSAGE_IS_REQUEST(rcvd->pdu->hdr))
1577 handle_request(context, rcvd);
1578 else if (COAP_MESSAGE_IS_RESPONSE(rcvd->pdu->hdr))
1579 handle_response(context, rcvd);
1581 debug("dropped message with invalid code\n");
1582 coap_send_message_type(context, &rcvd->remote, rcvd->pdu,
1587 // we should not retrying responses.....
1588 cleanup: coap_delete_node(sent);
1589 coap_delete_node(rcvd);
1593 int coap_can_exit(coap_context_t *context) {
1595 || (context->recvqueue == NULL && context->sendqueue == NULL);
1600 /*---------------------------------------------------------------------------*/
1601 /* CoAP message retransmission */
1602 /*---------------------------------------------------------------------------*/
1603 PROCESS_THREAD(coap_retransmit_process, ev, data)
1606 coap_queue_t *nextpdu;
1610 debug("Started retransmit process\r\n");
1614 if (ev == PROCESS_EVENT_TIMER) {
1615 if (etimer_expired(&the_coap_context.retransmit_timer)) {
1617 nextpdu = coap_peek_next(&the_coap_context);
1620 while (nextpdu && nextpdu->t <= now) {
1621 coap_retransmit(&the_coap_context, coap_pop_next(&the_coap_context));
1622 nextpdu = coap_peek_next(&the_coap_context);
1625 /* need to set timer to some value even if no nextpdu is available */
1626 etimer_set(&the_coap_context.retransmit_timer,
1627 nextpdu ? nextpdu->t - now : 0xFFFF);
1629 #ifndef WITHOUT_OBSERVE
1630 if (etimer_expired(&the_coap_context.notify_timer)) {
1631 coap_check_notify(&the_coap_context);
1632 etimer_reset(&the_coap_context.notify_timer);
1634 #endif /* WITHOUT_OBSERVE */
1640 /*---------------------------------------------------------------------------*/
1642 #endif /* WITH_CONTIKI */
1645 /* FIXME: retransmits that are not required any more due to incoming packages
1646 * do *not* get cleared at the moment, the wakeup when the transmission is due
1647 * is silently accepted. this is mainly due to the fact that the required
1648 * checks are similar in two places in the code (when receiving ACK and RST)
1649 * and that they cause more than one patch chunk, as it must be first checked
1650 * whether the sendqueue item to be dropped is the next one pending, and later
1651 * the restart function has to be called. nothing insurmountable, but it can
1652 * also be implemented when things have stabilized, and the performance
1653 * penality is minimal
1655 * also, this completely ignores COAP_RESOURCE_CHECK_TIME.
1658 static void coap_retransmittimer_execute(void *arg)
1660 coap_context_t *ctx = (coap_context_t*)arg;
1662 coap_tick_t elapsed;
1663 coap_queue_t *nextinqueue;
1665 ctx->timer_configured = 0;
1669 elapsed = now - ctx->sendqueue_basetime; /* that's positive for sure, and unless we haven't been called for a complete wrapping cycle, did not wrap */
1671 nextinqueue = coap_peek_next(ctx);
1672 while (nextinqueue != NULL)
1674 if (nextinqueue->t > elapsed) {
1675 nextinqueue->t -= elapsed;
1678 elapsed -= nextinqueue->t;
1679 coap_retransmit(ctx, coap_pop_next(ctx));
1680 nextinqueue = coap_peek_next(ctx);
1684 ctx->sendqueue_basetime = now;
1686 coap_retransmittimer_restart(ctx);
1689 static void coap_retransmittimer_restart(coap_context_t *ctx)
1691 coap_tick_t now, elapsed, delay;
1693 if (ctx->timer_configured)
1695 printf("clearing\n");
1696 sys_untimeout(coap_retransmittimer_execute, (void*)ctx);
1697 ctx->timer_configured = 0;
1699 if (ctx->sendqueue != NULL)
1702 elapsed = now - ctx->sendqueue_basetime;
1703 if (ctx->sendqueue->t >= elapsed) {
1704 delay = ctx->sendqueue->t - elapsed;
1706 /* a strange situation, but not completely impossible.
1708 * this happens, for example, right after
1709 * coap_retransmittimer_execute, when a retransmission
1710 * was *just not yet* due, and the clock ticked before
1711 * our coap_ticks was called.
1713 * not trying to retransmit anything now, as it might
1714 * cause uncontrollable recursion; let's just try again
1715 * with the next main loop run.
1720 printf("scheduling for %d ticks\n", delay);
1721 sys_timeout(delay, coap_retransmittimer_execute, (void*)ctx);
1722 ctx->timer_configured = 1;