Files
libcoap/man/Makefile.am
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

118 lines
3.9 KiB
Makefile

# man/Makefile.am
#
# Copyright (C) 2018-2020 Jon Shallow <supjps-libcoap@jpshallow.com>
#
# This file is part of the CoAP C library libcoap. Please see README and
# COPYING for terms of use.
# picking up the default warning CFLAGS into AM_CFLAGS
AM_CFLAGS = -I$(top_builddir)/include -I$(top_srcdir)/include \
-I$(top_srcdir)/include/coap$(LIBCOAP_API_VERSION) \
$(WARNING_CFLAGS) $(DTLS_CFLAGS) -std=c99
# Build, not install
noinst_PROGRAMS = examples-code-check
# build manuals only if 'BUILD_MANPAGES' is defined
if BUILD_MANPAGES
# building the manpages
TXT3 = coap_attribute.txt \
coap_block.txt \
coap_cache.txt \
coap_context.txt \
coap_encryption.txt \
coap_handler.txt \
coap_io.txt \
coap_keepalive.txt \
coap_logging.txt \
coap_observe.txt \
coap_pdu_setup.txt \
coap_recovery.txt \
coap_resource.txt \
coap_session.txt \
coap_string.txt \
coap_tls_library.txt
MAN3 = $(TXT3:%.txt=%.3)
man3_MANS = $(MAN3)
TXT5 = coap-client.txt \
coap-rd.txt \
coap-server.txt
MAN5 = $(TXT5:%.txt=%.5)
man5_MANS = $(MAN5)
TXT7 = coap.txt
MAN7 = $(TXT7:%.txt=%.7)
man7_MANS = $(MAN7)
.txt.3:
$(A2X) --doctype manpage --format manpage $<
$(A2X) --doctype manpage --format xhtml $<
.txt.5:
$(A2X) --doctype manpage --format manpage $<
$(A2X) --doctype manpage --format xhtml $<
.txt.7:
$(A2X) --doctype manpage --format manpage $<
$(A2X) --doctype manpage --format xhtml $<
# Man pages built by a2x based on the NAMES section of the .txt file.
# Note - this list includes all the defined entries, but a2x only builds the first 10.
A2X_EXTRA_PAGES = @DOLLAR_SIGN@(shell for fil in $(TXT3) ; do sed -ne '/^NAME/,/^SYNOPSIS/p;/^SYNOPSIS/q' $${fil} | \
sed -ne '/coap_/{ s/ *, */\n/g; p }' | sed -ne 's/^\(coap_[a-zA-Z_0-9]\+\).*$$/\1.3/p' ; done)
# a2x builds alternative .3 files up to a limit of 10 names from the
# NAME section, so that 'man' works against the alternative different
# function names.
#
# However, if there are more alternative names, they need to be defined
# as per below
#
# Then all the alternative names as well as the extras defined below need
# to be cleaned up in a 'make unistall'.
install-man: install-man3 install-man5 install-man7
@echo ".so man3/coap_cache.3" > coap_cache_get_app_data.3
@echo ".so man3/coap_cache.3" > coap_cache_set_app_data.3
@echo ".so man3/coap_context.3" > coap_context_set_pki_root_cas.3
@echo ".so man3/coap_pdu_setup.3" > coap_encode_var_safe.3
@echo ".so man3/coap_pdu_setup.3" > coap_encode_var_safe8.3
@echo ".so man3/coap_pdu_setup.3" > coap_add_optlist_pdu.3
@echo ".so man3/coap_pdu_setup.3" > coap_add_option.3
@echo ".so man3/coap_pdu_setup.3" > coap_add_data.3
@echo ".so man3/coap_pdu_setup.3" > coap_add_data_blocked_response.3
@echo ".so man3/coap_pdu_setup.3" > coap_send.3
@echo ".so man3/coap_pdu_setup.3" > coap_split_path.3
@echo ".so man3/coap_pdu_setup.3" > coap_split_query.3
@echo ".so man3/coap_resource.3" > coap_resource_get_userdata.3
@echo ".so man3/coap_session.3" > coap_session_get_app_data.3
@echo ".so man3/coap_session.3" > coap_session_set_app_data.3
@echo ".so man3/coap_session.3" > coap_tcp_is_supported.3
@echo ".so man3/coap_string.3" > coap_delete_bin_const.3
@echo ".so man3/coap_string.3" > coap_make_str_const.3
@echo ".so man3/coap_string.3" > coap_string_equal.3
@echo ".so man3/coap_string.3" > coap_binary_equal.3
@echo ".so man3/coap_logging.3" > coap_endpoint_str.3
@echo ".so man3/coap_logging.3" > coap_session_str.3
$(INSTALL_DATA) $(A2X_EXTRA_PAGES) "$(DESTDIR)$(man3dir)"
# As well as removing the base 'man' pages, remove other .3 files built by
# a2x, as well as build by install-man specials.
uninstall-man: uninstall-man3 uninstall-man5 uninstall-man7
-(cd $(DESTDIR)$(man3dir) ; rm -f $(A2X_EXTRA_PAGES) )
endif # BUILD_MANPAGES
CLEANFILES = *.3 *.5 *.7 *.xml *.html docbook-xsl.css *.o examples-code-check
clean-local:
-rm -rf tmp