1 /* 2 * coap_netif_internal.h -- Netif Transport Layer Support for libcoap 3 * 4 * Copyright (C) 2023 Jon Shallow <supjps-libcoap@jpshallow.com> 5 * 6 * SPDX-License-Identifier: BSD-2-Clause 7 * 8 * This file is part of the CoAP library libcoap. Please see README for terms 9 * of use. 10 */ 11 12 /** 13 * @file coap_netif_internal.h 14 * @brief Internal CoAP Netif support 15 */ 16 17 #ifndef COAP_NETIF_INTERNAL_H_ 18 #define COAP_NETIF_INTERNAL_H_ 19 20 #include "coap_internal.h" 21 22 /** 23 * @ingroup internal_api 24 * @defgroup netif_internal Netif Support 25 * Internal API for Netif Support. 26 * This provides a layer that sits between CoAP/DTLS and Sockets. 27 * @{ 28 */ 29 30 /** 31 * Function interface to check whether netif for session is still available. 32 * 33 * @param session Session to check against. 34 * 35 * @return 1 If netif is available, else 0. 36 */ 37 int coap_netif_available(coap_session_t *session); 38 39 /** 40 * Function interface to check whether netif for endpoint is still available. 41 * 42 * @param endpoint Endpoint to check against. 43 * 44 * @return 1 If netif is available, else 0. 45 */ 46 int coap_netif_available_ep(coap_endpoint_t *endpoint); 47 48 /** 49 * Layer function interface for Netif datagram listem (udp). 50 * 51 * @param endpoint Endpoint to do the listen on. 52 * @param listen_addr The local address to bind. 53 * 54 * @return @c 1 OK, 0 on failure. 55 */ 56 int coap_netif_dgrm_listen(coap_endpoint_t *endpoint, 57 const coap_address_t *listen_addr); 58 59 /** 60 * Layer function interface for Netif datagram connect (udp). 61 * 62 * @param session Session to do the connect on. 63 * @param local_if The local interface to bind to or NULL. 64 * @param server The server to connect to. 65 * @param default_port The Port to connect to if not defined. 66 * 67 * @return @c 1 OK, 0 on failure. 68 */ 69 int coap_netif_dgrm_connect(coap_session_t *session, 70 const coap_address_t *local_if, 71 const coap_address_t *server, int default_port); 72 73 /** 74 * Function interface for layer data datagram receiving for sessions. This 75 * function returns the number of bytes that have been read, or -1 on error. 76 * 77 * @param session Session to receive data on. 78 * @param packet Where to put the received information 79 * 80 * @return >=0 Number of bytes read. 81 * -1 Error of some sort (see errno). 82 * -2 ICMP error response 83 */ 84 ssize_t coap_netif_dgrm_read(coap_session_t *session, coap_packet_t *packet); 85 86 /** 87 * Function interface for layer data datagram receiving for endpoints. This 88 * function returns the number of bytes that have been read, or -1 on error. 89 * 90 * @param endpoint Endpoint to receive data on. 91 * @param packet Where to put the received information 92 * 93 * @return >=0 Number of bytes read. 94 * -1 Error of some sort (see errno). 95 * -2 ICMP error response 96 */ 97 ssize_t coap_netif_dgrm_read_ep(coap_endpoint_t *endpoint, 98 coap_packet_t *packet); 99 100 /** 101 * Function interface for netif datagram data transmission. This function 102 * returns the number of bytes that have been transmitted, or a value less 103 * than zero on error. 104 * 105 * @param session Session to send data on. 106 * @param data The data to send. 107 * @param datalen The actual length of @p data. 108 * 109 * @return The number of bytes written on success, or a value 110 * less than zero on error. 111 */ 112 ssize_t coap_netif_dgrm_write(coap_session_t *session, const uint8_t *data, 113 size_t datalen); 114 115 /** 116 * Layer function interface for Netif stream listem (tcp). 117 * 118 * @param endpoint Endpoint to do the listen on. 119 * @param listen_addr The local address to bind. 120 * 121 * @return @c 1 OK, 0 on failure. 122 */ 123 int coap_netif_strm_listen(coap_endpoint_t *endpoint, 124 const coap_address_t *listen_addr); 125 126 /** 127 * Layer function interface for Netif stream accept. 128 * 129 * @param endpoint Endpoint to to do the accept on. 130 * @param session Session to to do the accept update on. 131 * 132 * @return @c 1 OK, 0 on failure. 133 */ 134 int coap_netif_strm_accept(coap_endpoint_t *endpoint, coap_session_t *session); 135 136 /** 137 * Layer function interface for Netif stream connect (tcp). 138 * Step 1 - initiate the connection. 139 * 140 * @param session Session to do the connect on. 141 * @param local_if The local interface to bind to or NULL. 142 * @param server The server to connect to. 143 * @param default_port The Port to connect to if not defined. 144 * 145 * @return @c 1 OK, 0 on failure. 146 */ 147 int coap_netif_strm_connect1(coap_session_t *session, 148 const coap_address_t *local_if, 149 const coap_address_t *server, int default_port); 150 151 /** 152 * Layer function interface for Netif stream connect (tcp). 153 * Step 2 - complete the connection. 154 * 155 * @param session Session to do the connect complete on. 156 * 157 * @return @c 1 OK, 0 on failure. 158 */ 159 int coap_netif_strm_connect2(coap_session_t *session); 160 161 /** 162 * Function interface for layer data stream receiving. This function returns 163 * the number of bytes that have been read, or -1 on error. 164 * 165 * @param session Session to receive data on. 166 * @param data The data to receive. 167 * @param datalen The maximum length of @p data. 168 * 169 * @return >=0 Number of bytes read. 170 * -1 Error of some sort (see errno). 171 */ 172 ssize_t coap_netif_strm_read(coap_session_t *session, uint8_t *data, 173 size_t datalen); 174 175 /** 176 * Function interface for netif stream data transmission. This function returns 177 * the number of bytes that have been transmitted, or a value less than zero 178 * on error. The number of bytes written may be less than datalen because of 179 * congestion control. 180 * 181 * @param session Session to send data on. 182 * @param data The data to send. 183 * @param datalen The actual length of @p data. 184 * 185 * @return The number of bytes written on success, or a value 186 * less than zero on error. 187 */ 188 ssize_t coap_netif_strm_write(coap_session_t *session, 189 const uint8_t *data, size_t datalen); 190 191 /** 192 * Layer function interface for Netif close for a session. 193 * 194 * @param session Session to do the netif close on. 195 */ 196 void coap_netif_close(coap_session_t *session); 197 198 /** 199 * Layer function interface for Netif close for a endpoint. 200 * 201 * @param endpoint Endpoint to do the netif close on. 202 */ 203 void coap_netif_close_ep(coap_endpoint_t *endpoint); 204 205 /** @} */ 206 207 #endif /* COAP_NETIF_INTERNAL_H */ 208