rpi.git - Gitblit

guowenxue

2024-04-11 69b42a43ca4b2d93be203c34f6b45f5de1e32a15

commit \| author \| age
d6b4a7	1	/*
G	2	* coreMQTT v2.1.1
	3	* Copyright (C) 2022 Amazon.com, Inc. or its affiliates. All Rights Reserved.
	4	*
	5	* SPDX-License-Identifier: MIT
	6	*
	7	* Permission is hereby granted, free of charge, to any person obtaining a copy of
	8	* this software and associated documentation files (the "Software"), to deal in
	9	* the Software without restriction, including without limitation the rights to
	10	* use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
	11	* the Software, and to permit persons to whom the Software is furnished to do so,
	12	* subject to the following conditions:
	13	*
	14	* The above copyright notice and this permission notice shall be included in all
	15	* copies or substantial portions of the Software.
	16	*
	17	* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
	18	* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
	19	* FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
	20	* COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
	21	* IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
	22	* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
	23	*/
	24
	25	/**
	26	* @file transport_interface.h
	27	* @brief Transport interface definitions to send and receive data over the
	28	* network.
	29	*/
	30	#ifndef TRANSPORT_INTERFACE_H_
	31	#define TRANSPORT_INTERFACE_H_
	32
	33	#include <stdint.h>
	34	#include <stddef.h>
	35
	36	/* INDENT-OFF */
	37	#ifdef __cplusplus
	38	extern "C" {
	39	#endif
	40	/* INDENT-ON */
	41
	42	/**
	43	* @transportpage
	44	* @brief The transport interface definition.
	45	*
	46	* @transportsectionoverview
	47	*
	48	* The transport interface is a set of APIs that must be implemented using an
	49	* external transport layer protocol. The transport interface is defined in
	50	* @ref transport_interface.h. This interface allows protocols like MQTT and
	51	* HTTP to send and receive data over the transport layer. This
	52	* interface does not handle connection and disconnection to the server of
	53	* interest. The connection, disconnection, and other transport settings, like
	54	* timeout and TLS setup, must be handled in the user application.
	55	* <br>
	56	*
	57	* The functions that must be implemented are:<br>
	58	* - [Transport Receive](@ref TransportRecv_t)
	59	* - [Transport Send](@ref TransportSend_t)
	60	*
	61	* Each of the functions above take in an opaque context @ref NetworkContext_t.
	62	* The functions above and the context are also grouped together in the
	63	* @ref TransportInterface_t structure:<br><br>
	64	* @snippet this define_transportinterface
	65	* <br>
	66	*
	67	* @transportsectionimplementation
	68	*
	69	* The following steps give guidance on implementing the transport interface:
	70	*
	71	* -# Implementing @ref NetworkContext_t<br><br>
	72	* @snippet this define_networkcontext
	73	* <br>
	74	* @ref NetworkContext_t is the incomplete type <b>struct NetworkContext</b>.
	75	* The implemented struct NetworkContext must contain all of the information
	76	* that is needed to receive and send data with the @ref TransportRecv_t
	77	* and the @ref TransportSend_t implementations.<br>
	78	* In the case of TLS over TCP, struct NetworkContext is typically implemented
	79	* with the TCP socket context and a TLS context.<br><br>
	80	* <b>Example code:</b>
	81	* @code{c}
	82	* struct NetworkContext
	83	* {
	84	* struct MyTCPSocketContext tcpSocketContext;
	85	* struct MyTLSContext tlsContext;
	86	* };
	87	* @endcode
	88	* <br>
	89	* -# Implementing @ref TransportRecv_t<br><br>
	90	* @snippet this define_transportrecv
	91	* <br>
	92	* This function is expected to populate a buffer, with bytes received from the
	93	* transport, and return the number of bytes placed in the buffer.
	94	* In the case of TLS over TCP, @ref TransportRecv_t is typically implemented by
	95	* calling the TLS layer function to receive data. In case of plaintext TCP
	96	* without TLS, it is typically implemented by calling the TCP layer receive
	97	* function. @ref TransportRecv_t may be invoked multiple times by the protocol
	98	* library, if fewer bytes than were requested to receive are returned.
	99	* <br><br>
	100	* <b>Example code:</b>
	101	* @code{c}
	102	* int32_t myNetworkRecvImplementation( NetworkContext_t * pNetworkContext,
	103	* void * pBuffer,
	104	* size_t bytesToRecv )
	105	* {
	106	* int32_t bytesReceived = 0;
	107	* bool callTlsRecvFunc = true;
	108	*
	109	* // For a single byte read request, check if data is available on the network.
	110	* if( bytesToRecv == 1 )
	111	* {
	112	* // If no data is available on the network, do not call TLSRecv
	113	* // to avoid blocking for socket timeout.
	114	* if( TLSRecvCount( pNetworkContext->tlsContext ) == 0 )
	115	* {
	116	* callTlsRecvFunc = false;
	117	* }
	118	* }
	119	*
	120	* if( callTlsRecvFunc == true )
	121	* {
	122	* bytesReceived = TLSRecv( pNetworkContext->tlsContext,
	123	* pBuffer,
	124	* bytesToRecv,
	125	* MY_SOCKET_TIMEOUT );
	126	* if( bytesReceived < 0 )
	127	* {
	128	* // If the error code represents a timeout, then the return
	129	* // code should be translated to zero so that the caller
	130	* // can retry the read operation.
	131	* if( bytesReceived == MY_SOCKET_ERROR_TIMEOUT )
	132	* {
	133	* bytesReceived = 0;
	134	* }
	135	* }
	136	* // Handle other cases.
	137	* }
	138	* return bytesReceived;
	139	* }
	140	* @endcode
	141	* <br>
	142	* -# Implementing @ref TransportSend_t<br><br>
	143	* @snippet this define_transportsend
	144	* <br>
	145	* This function is expected to send the bytes, in the given buffer over the
	146	* transport, and return the number of bytes sent.
	147	* In the case of TLS over TCP, @ref TransportSend_t is typically implemented by
	148	* calling the TLS layer function to send data. In case of plaintext TCP
	149	* without TLS, it is typically implemented by calling the TCP layer send
	150	* function. @ref TransportSend_t may be invoked multiple times by the protocol
	151	* library, if fewer bytes than were requested to send are returned.
	152	* <br><br>
	153	* <b>Example code:</b>
	154	* @code{c}
	155	* int32_t myNetworkSendImplementation( NetworkContext_t * pNetworkContext,
	156	* const void * pBuffer,
	157	* size_t bytesToSend )
	158	* {
	159	* int32_t bytesSent = 0;
	160	* bytesSent = TLSSend( pNetworkContext->tlsContext,
	161	* pBuffer,
	162	* bytesToSend,
	163	* MY_SOCKET_TIMEOUT );
	164	*
	165	* // If underlying TCP buffer is full, set the return value to zero
	166	* // so that caller can retry the send operation.
	167	* if( bytesSent == MY_SOCKET_ERROR_BUFFER_FULL )
	168	* {
	169	* bytesSent = 0;
	170	* }
	171	* else if( bytesSent < 0 )
	172	* {
	173	* // Handle socket error.
	174	* }
	175	* // Handle other cases.
	176	*
	177	* return bytesSent;
	178	* }
	179	* @endcode
	180	*/
	181
	182	/**
	183	* @transportstruct
	184	* @typedef NetworkContext_t
	185	* @brief The NetworkContext is an incomplete type. An implementation of this
	186	* interface must define struct NetworkContext for the system requirements.
	187	* This context is passed into the network interface functions.
	188	*/
	189	/* @[define_networkcontext] */
	190	struct NetworkContext;
	191	typedef struct NetworkContext NetworkContext_t;
	192	/* @[define_networkcontext] */
	193
	194	/**
	195	* @transportcallback
	196	* @brief Transport interface for receiving data on the network.
	197	*
	198	* @note It is RECOMMENDED that the transport receive implementation
	199	* does NOT block when requested to read a single byte. A single byte
	200	* read request can be made by the caller to check whether there is a
	201	* new frame available on the network for reading.
	202	* However, the receive implementation MAY block for a timeout period when
	203	* it is requested to read more than 1 byte. This is because once the caller
	204	* is aware that a new frame is available to read on the network, then
	205	* the likelihood of reading more than one byte over the network becomes high.
	206	*
	207	* @param[in] pNetworkContext Implementation-defined network context.
	208	* @param[in] pBuffer Buffer to receive the data into.
	209	* @param[in] bytesToRecv Number of bytes requested from the network.
	210	*
	211	* @return The number of bytes received or a negative value to indicate
	212	* error.
	213	*
	214	* @note If no data is available on the network to read and no error
	215	* has occurred, zero MUST be the return value. A zero return value
	216	* SHOULD represent that the read operation can be retried by calling
	217	* the API function. Zero MUST NOT be returned if a network disconnection
	218	* has occurred.
	219	*/
	220	/* @[define_transportrecv] */
	221	typedef int32_t ( * TransportRecv_t )( NetworkContext_t * pNetworkContext,
	222	void * pBuffer,
	223	size_t bytesToRecv );
	224	/* @[define_transportrecv] */
	225
	226	/**
	227	* @transportcallback
	228	* @brief Transport interface for sending data over the network.
	229	*
	230	* @param[in] pNetworkContext Implementation-defined network context.
	231	* @param[in] pBuffer Buffer containing the bytes to send over the network stack.
	232	* @param[in] bytesToSend Number of bytes to send over the network.
	233	*
	234	* @return The number of bytes sent or a negative value to indicate error.
	235	*
	236	* @note If no data is transmitted over the network due to a full TX buffer and
	237	* no network error has occurred, this MUST return zero as the return value.
	238	* A zero return value SHOULD represent that the send operation can be retried
	239	* by calling the API function. Zero MUST NOT be returned if a network disconnection
	240	* has occurred.
	241	*/
	242	/* @[define_transportsend] */
	243	typedef int32_t ( * TransportSend_t )( NetworkContext_t * pNetworkContext,
	244	const void * pBuffer,
	245	size_t bytesToSend );
	246	/* @[define_transportsend] */
	247
	248	/**
	249	* @brief Transport vector structure for sending multiple messages.
	250	*/
	251	typedef struct TransportOutVector
	252	{
	253	/**
	254	* @brief Base address of data.
	255	*/
	256	const void * iov_base;
	257
	258	/**
	259	* @brief Length of data in buffer.
	260	*/
	261	size_t iov_len;
	262	} TransportOutVector_t;
	263
	264	/**
	265	* @transportcallback
	266	* @brief Transport interface function for "vectored" / scatter-gather based
	267	* writes. This function is expected to iterate over the list of vectors pIoVec
	268	* having ioVecCount entries containing portions of one MQTT message at a maximum.
	269	* If the proper functionality is available, then the data in the list should be
	270	* copied to the underlying TCP buffer before flushing the buffer. Implementing it
	271	* in this fashion will lead to sending of fewer TCP packets for all the values
	272	* in the list.
	273	*
	274	* @note If the proper write functionality is not present for a given device/IP-stack,
	275	* then there is no strict requirement to implement write. Only the send and recv
	276	* interfaces must be defined for the application to work properly.
	277	*
	278	* @param[in] pNetworkContext Implementation-defined network context.
	279	* @param[in] pIoVec An array of TransportIoVector_t structs.
	280	* @param[in] ioVecCount Number of TransportIoVector_t in pIoVec.
	281	*
	282	* @return The number of bytes written or a negative value to indicate error.
	283	*
	284	* @note If no data is written to the buffer due to the buffer being full this MUST
	285	* return zero as the return value.
	286	* A zero return value SHOULD represent that the write operation can be retried
	287	* by calling the API function. Zero MUST NOT be returned if a network disconnection
	288	* has occurred.
	289	*/
	290	/* @[define_transportwritev] */
	291	typedef int32_t ( * TransportWritev_t )( NetworkContext_t * pNetworkContext,
	292	TransportOutVector_t * pIoVec,
	293	size_t ioVecCount );
	294	/* @[define_transportwritev] */
	295
	296	/**
	297	* @transportstruct
	298	* @brief The transport layer interface.
	299	*/
	300	/* @[define_transportinterface] */
	301	typedef struct TransportInterface
	302	{
	303	TransportRecv_t recv; /*< Transport receive function pointer. /
	304	TransportSend_t send; /*< Transport send function pointer. /
	305	TransportWritev_t writev; /*< Transport writev function pointer. /
	306	NetworkContext_t * pNetworkContext; /*< Implementation-defined network context. /
	307	} TransportInterface_t;
	308	/* @[define_transportinterface] */
	309
	310	/* INDENT-OFF */
	311	#ifdef __cplusplus
	312	}
	313	#endif
	314	/* INDENT-ON */
	315
	316	#endif /* ifndef TRANSPORT_INTERFACE_H_ */