1// -*- mode:doc; -*-
2// vim: set syntax=asciidoc tw=0
3
4coap_lwip(3)
5============
6:doctype: manpage
7:man source:   coap_lwip
8:man version:  @PACKAGE_VERSION@
9:man manual:   libcoap Manual
10
11NAME
12----
13coap_lwip,
14coap_lwip_dump_memory_pools,
15coap_lwip_set_input_wait_handler
16- Work with CoAP lwip specific API handler
17
18SYNOPSIS
19--------
20*#include <coap@LIBCOAP_API_VERSION@/coap.h>*
21
22*void coap_lwip_set_input_wait_handler(coap_context_t *_context_,
23coap_lwip_input_wait_handler_t _handler_, void *_input_arg_);*
24
25*void coap_lwip_dump_memory_pools(coap_log_t _log_level_);*
26
27DESCRIPTION
28-----------
29This man page describes the additional libcoap functions that are available
30for working with LwIP implementations.
31
32*NOTE:* If the following line is defined in lwipopts.h, then libcoap will
33reserve space for one response PDU when allocating coap_pdu_t structures.
34
35[source, c]
36----
37#define MEMP_STATS 1
38----
39
40CALLBACK HANDLER
41----------------
42
43*Callback Type: coap_lwip_input_wait_handler_t*
44
45[source, c]
46----
47/**
48 * LwIP callback handler that can be used to wait / timeout for the
49 * next input packet.
50 *
51 * @param arg The argument passed to the coap_lwip_set_input_wait_handler()
52 *            function.
53 * @param milli_secs Suggested number of milli secs to wait before returning
54 *                   if no input.
55 *
56 * @return @c 1 if packet received, @c 0 for timeout, else @c -1 on error.
57 */
58typedef int (*coap_lwip_input_wait_handler_t)(void* arg, uint32_t milli_secs);
59----
60
61FUNCTIONS
62---------
63
64*Function: coap_lwip_set_input_wait_handler()*
65
66The *coap_lwip_set_input_wait_handler*() function is used to define a callback
67_handler_ that is invoked by *coap_io_process*(3) which passes in the
68_input_arg_ parameter along with a suggested milli-sec wait time parameter
69in case there is no input.  This callback _handler_ is used to wait for
70(and probably times out) the next input packet.  This allows the application
71to define whatever mechanism it wants use for this process.
72
73*Function: coap_lwip_dump_memory_pools()*
74
75The *coap_lwip_dump_memory_pools*() function is used to dump out the current
76state of the LwIP memory pools at logging level _log_level_.
77
78This function is always invoked by *coap_free_context*(3) with a _log_level_ of
79COAP_LOG_DEBUG.
80
81*NOTE:* For information to be printed out, you need the following two lines in
82lwipopts.h
83
84[source, c]
85----
86#define MEMP_STATS         1
87#define LWIP_STATS_DISPLAY 1
88----
89
90SEE ALSO
91--------
92*coap_context*(3) and *coap_io*(3)
93
94FURTHER INFORMATION
95-------------------
96See
97
98"https://rfc-editor.org/rfc/rfc7252[RFC7252: The Constrained Application Protocol (CoAP)]"
99
100for further information.
101
102BUGS
103----
104Please report bugs on the mailing list for libcoap:
105libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
106https://github.com/obgm/libcoap/issues
107
108AUTHORS
109-------
110The libcoap project <libcoap-developers@lists.sourceforge.net>
111