Files
libcoap/include/coap2/coap_event.h
T
Jon Shallow 9cb2f62a3e RFC7641: Move block handling logic down into libcoap
This change removes the need for applications having to know about handling
requests for the next block etc.  It also gives the application the ability
to pass a large body of data to be transmitted and be told when this body is
no longer required.

This logic is enabled in libcoap by setting COAP_BLOCK_USE_LIBCOAP using
coap_context_set_block_mode()

This change breaks down into 4 specific areas

1) Client doing a PUT/POST etc. of a large amount of data (BLOCK1).

coap_add_data_large_request() is used which provides a 'finished with data'
callback function as well as adding required options to the PDUs.  This
function calls coap_add_data_large_internal().

Internal coap_handle_response_send_block() sends off the subsequent blocks
(using session->lg_xmit).

2) Server receiving PUT/POST etc. of a large amount of data (BLOCK1).

Internal coap_handle_request_get_block() acknowledges the appropriate blocks
(using session->lg_srcv) and either passes in the individual blocks or the body
depending on whether COAP_BLOCK_SINGLE_BODY is set or not using
coap_context_set_block_mode().

3) Server sending a large data response to GET / observe (BLOCK2)

coap_add_data_large_response() is used which provides a 'finished with data'
callback function.  This function calls coap_add_data_large_internal() as well
as filling in the necessary options for each PDU.

Interal coap_handle_request_send_block() will then send the next requested block
(using session->lg_xmit).

4) Client receiving a large data response (BLOCK2)

coap_send_large() for the initial request sets this up.

Internal coap_handle_response_get_block() will then request the next block when
previous block received (using session->lg_crcv) and either passes the
individual blocks or the body depending on COAP_BLOCK_SINGLE_BODY being set in
coap_context_set_block_mode().

----

The following new internal functions have been added

coap_handle_request_get_block()
coap_handle_request_send_block()
coap_handle_response_get_block()
coap_handle_response_send_block()
coap_add_data_large_internal()

The following new functions have been added.

coap_add_data_large_request()
coap_add_data_large_response()
coap_context_set_block_mode()
coap_get_data_large()
coap_pdu_duplicate()
coap_send_large()
coap_session_init_token()
coap_session_new_token()

The coap_session_init_token() and coap_session_new_token() were added to make
the handling of unique tokens for each request/response easier.
https://datatracker.ietf.org/doc/html/draft-ietf-core-echo-request-tag-10#section-4

New files

include/coap2/coap_block_internal.h:
man/coap_block.txt.in:

New memory types

COAP_LG_XMIT
COAP_LG_SRCV
COAP_LG_CRCV
2021-02-23 18:01:04 +00:00

105 lines
3.1 KiB
C

/*
* coap_event.h -- libcoap Event API
*
* Copyright (C) 2016 Olaf Bergmann <bergmann@tzi.org>
*
* This file is part of the CoAP library libcoap. Please see README for terms
* of use.
*/
#ifndef COAP_EVENT_H_
#define COAP_EVENT_H_
#include "libcoap.h"
/**
* @defgroup events Event API
* API functions for event delivery from lower-layer library functions.
* @{
*/
/**
* Scalar type to represent different events, e.g. DTLS events or
* retransmission timeouts.
*/
typedef unsigned int coap_event_t;
/**
* (D)TLS events for COAP_PROTO_DTLS and COAP_PROTO_TLS
*/
#define COAP_EVENT_DTLS_CLOSED 0x0000
#define COAP_EVENT_DTLS_CONNECTED 0x01DE
#define COAP_EVENT_DTLS_RENEGOTIATE 0x01DF
#define COAP_EVENT_DTLS_ERROR 0x0200
/**
* TCP events for COAP_PROTO_TCP and COAP_PROTO_TLS
*/
#define COAP_EVENT_TCP_CONNECTED 0x1001
#define COAP_EVENT_TCP_CLOSED 0x1002
#define COAP_EVENT_TCP_FAILED 0x1003
/**
* CSM exchange events for reliable protocols only
*/
#define COAP_EVENT_SESSION_CONNECTED 0x2001
#define COAP_EVENT_SESSION_CLOSED 0x2002
#define COAP_EVENT_SESSION_FAILED 0x2003
/**
* BLOCK2 receive errors
*/
#define COAP_EVENT_PARTIAL_BLOCK 0x3001
/**
* Type for event handler functions that can be registered with a CoAP
* context using the unction coap_set_event_handler(). When called by
* the library, the first argument will be the coap_context_t object
* where the handler function has been registered. The second argument
* is the event type that may be complemented by event-specific data
* passed as the third argument.
*/
typedef int (*coap_event_handler_t)(struct coap_context_t *,
coap_event_t event,
struct coap_session_t *session);
/**
* Registers the function @p hnd as callback for events from the given
* CoAP context @p context. Any event handler that has previously been
* registered with @p context will be overwritten by this operation.
*
* @param context The CoAP context to register the event handler with.
* @param hnd The event handler to be registered. @c NULL if to be
* de-registered.
*/
void coap_register_event_handler(struct coap_context_t *context,
coap_event_handler_t hnd);
/** @} */
/**
* Registers the function @p hnd as callback for events from the given
* CoAP context @p context. Any event handler that has previously been
* registered with @p context will be overwritten by this operation.
*
* @deprecated Use coap_register_event_handler() instead.
*
* @param context The CoAP context to register the event handler with.
* @param hnd The event handler to be registered.
*/
COAP_DEPRECATED
void coap_set_event_handler(struct coap_context_t *context,
coap_event_handler_t hnd);
/**
* Clears the event handler registered with @p context.
*
* @deprecated Use coap_register_event_handler() instead with NULL for hnd.
*
* @param context The CoAP context whose event handler is to be removed.
*/
COAP_DEPRECATED
void coap_clear_event_handler(struct coap_context_t *context);
#endif /* COAP_EVENT_H */