1 /*
2  *  Copyright (c) 2022, The OpenThread Authors.
3  *  All rights reserved.
4  *
5  *  Redistribution and use in source and binary forms, with or without
6  *  modification, are permitted provided that the following conditions are met:
7  *  1. Redistributions of source code must retain the above copyright
8  *     notice, this list of conditions and the following disclaimer.
9  *  2. Redistributions in binary form must reproduce the above copyright
10  *     notice, this list of conditions and the following disclaimer in the
11  *     documentation and/or other materials provided with the distribution.
12  *  3. Neither the name of the copyright holder nor the
13  *     names of its contributors may be used to endorse or promote products
14  *     derived from this software without specific prior written permission.
15  *
16  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17  *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18  *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19  *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
20  *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21  *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22  *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23  *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24  *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25  *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26  *  POSSIBILITY OF SUCH DAMAGE.
27  */
28 
29 /**
30  * @file
31  *   This file includes definitions for TCP/IPv6 socket extensions.
32  */
33 
34 #ifndef TCP6_EXT_HPP_
35 #define TCP6_EXT_HPP_
36 
37 #include "openthread-core-config.h"
38 
39 #include <openthread/tcp_ext.h>
40 
41 #include "net/tcp6.hpp"
42 
43 namespace ot {
44 namespace Ip6 {
45 
46 /**
47  * @addtogroup core-tcp-ext
48  *
49  * @brief
50  *   This module includes definitions for TCP/IPv6 socket extensions.
51  *
52  * @{
53  *
54  */
55 
56 /**
57  * Represents a TCP circular send buffer.
58  *
59  */
60 class TcpCircularSendBuffer : public otTcpCircularSendBuffer
61 {
62 public:
63     /**
64      * Initializes a TCP circular send buffer.
65      *
66      * @sa otTcpCircularSendBufferInitialize
67      *
68      * @param[in]  aDataBuffer      A pointer to memory to use to store data in the TCP circular send buffer.
69      * @param[in]  aCapacity        The capacity, in bytes, of the TCP circular send buffer, which must equal the size
70      *                              of the memory pointed to by @p aDataBuffer .
71      */
72     void Initialize(void *aDataBuffer, size_t aCapacity);
73 
74     /**
75      * Sends out data on a TCP endpoint, using this TCP circular send buffer to manage buffering.
76      *
77      * @sa otTcpCircularSendBufferWrite, particularly for guidance on how @p aEndpoint must be chosen.
78      *
79      * @param[in]   aEndpoint The TCP endpoint on which to send out data.
80      * @param[in]   aData     A pointer to data to copy into the TCP circular send buffer.
81      * @param[in]   aLength   The length of the data pointed to by @p aData to copy into the TCP circular send buffer.
82      * @param[out]  aWritten  Populated with the amount of data copied into the send buffer, which might be less than
83      *                        @p aLength if the send buffer reaches capacity.
84      * @param[in]   aFlags    Flags specifying options for this operation.
85      *
86      * @retval kErrorNone on success, or the error returned by the TCP endpoint on failure.
87      */
88     Error Write(Tcp::Endpoint &aEndpoint, const void *aData, size_t aLength, size_t &aWritten, uint32_t aFlags);
89 
90     /**
91      * Performs circular-send-buffer-specific handling in the otTcpForwardProgress callback.
92      *
93      * @sa otTcpCircularSendBufferHandleForwardProgress
94      *
95      * @param[in]  aInSendBuffer  Value of @p aInSendBuffer passed to the otTcpForwardProgress() callback.
96      */
97     void HandleForwardProgress(size_t aInSendBuffer);
98 
99     /**
100      * Returns the amount of free space in this TCP circular send buffer.
101      *
102      * @sa otTcpCircularSendBufferFreeSpace
103      *
104      * @return The amount of free space in the send buffer.
105      */
106     size_t GetFreeSpace(void) const;
107 
108     /**
109      * Forcibly discards all data in this TCP circular send buffer.
110      *
111      * @sa otTcpCircularSendBufferForceDiscardAll
112      *
113      */
114     void ForceDiscardAll(void);
115 
116     /**
117      * Deinitializes this TCP circular send buffer.
118      *
119      * @sa otTcpCircularSendBufferDeinitialize
120      *
121      * @retval kErrorNone    Successfully deinitialized this TCP circular send buffer.
122      * @retval kErrorFailed  Failed to deinitialize the TCP circular send buffer.
123      */
124     Error Deinitialize(void);
125 
126 private:
127     size_t GetIndex(size_t aStart, size_t aOffsetFromStart) const;
128 };
129 
130 } // namespace Ip6
131 
132 DefineCoreType(otTcpCircularSendBuffer, Ip6::TcpCircularSendBuffer);
133 
134 } // namespace ot
135 
136 #endif // TCP6_HPP_
137