1 /*
2  *  Copyright (c) 2021, 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  * @brief
32  *   This file includes the OpenThread API for ping sender module.
33  */
34 
35 #ifndef OPENTHREAD_PING_SENDER_H_
36 #define OPENTHREAD_PING_SENDER_H_
37 
38 #include <stdint.h>
39 
40 #include <openthread/error.h>
41 #include <openthread/instance.h>
42 #include <openthread/ip6.h>
43 
44 #ifdef __cplusplus
45 extern "C" {
46 #endif
47 
48 /**
49  * @addtogroup api-ping-sender
50  *
51  * @brief
52  *   This file includes the OpenThread API for the ping sender module.
53  *
54  * @{
55  */
56 
57 /**
58  * Represents a ping reply.
59  */
60 typedef struct otPingSenderReply
61 {
62     otIp6Address mSenderAddress;  ///< Sender IPv6 address (address from which ping reply was received).
63     uint16_t     mRoundTripTime;  ///< Round trip time in msec.
64     uint16_t     mSize;           ///< Data size (number of bytes) in reply (excluding IPv6 and ICMP6 headers).
65     uint16_t     mSequenceNumber; ///< Sequence number.
66     uint8_t      mHopLimit;       ///< Hop limit.
67 } otPingSenderReply;
68 
69 /**
70  * Represents statistics of a ping request.
71  */
72 typedef struct otPingSenderStatistics
73 {
74     uint16_t mSentCount;          ///< The number of ping requests already sent.
75     uint16_t mReceivedCount;      ///< The number of ping replies received.
76     uint32_t mTotalRoundTripTime; ///< The total round trip time of ping requests.
77     uint16_t mMinRoundTripTime;   ///< The min round trip time among ping requests.
78     uint16_t mMaxRoundTripTime;   ///< The max round trip time among ping requests.
79     bool     mIsMulticast;        ///< Whether this is a multicast ping request.
80 } otPingSenderStatistics;
81 
82 /**
83  * Pointer type specifies the callback to notify receipt of a ping reply.
84  *
85  * @param[in] aReply      A pointer to a `otPingSenderReply` containing info about the received ping reply.
86  * @param[in] aContext    A pointer to application-specific context.
87  */
88 typedef void (*otPingSenderReplyCallback)(const otPingSenderReply *aReply, void *aContext);
89 
90 /**
91  * Pointer type specifies the callback to report the ping statistics.
92  *
93  * @param[in] aStatistics      A pointer to a `otPingSenderStatistics` containing info about the received ping
94  *                             statistics.
95  * @param[in] aContext         A pointer to application-specific context.
96  */
97 typedef void (*otPingSenderStatisticsCallback)(const otPingSenderStatistics *aStatistics, void *aContext);
98 
99 /**
100  * Represents a ping request configuration.
101  */
102 typedef struct otPingSenderConfig
103 {
104     otIp6Address              mSource;        ///< Source address of the ping.
105     otIp6Address              mDestination;   ///< Destination address to ping.
106     otPingSenderReplyCallback mReplyCallback; ///< Callback function to report replies (can be NULL if not needed).
107     otPingSenderStatisticsCallback
108              mStatisticsCallback; ///< Callback function to report statistics (can be NULL if not needed).
109     void    *mCallbackContext;    ///< A pointer to the callback application-specific context.
110     uint16_t mSize;               ///< Data size (# of bytes) excludes IPv6/ICMPv6 header. Zero for default.
111     uint16_t mCount;              ///< Number of ping messages to send. Zero to use default.
112     uint32_t mInterval;           ///< Ping tx interval in milliseconds. Zero to use default.
113     uint16_t mTimeout;            ///< Time in milliseconds to wait for final reply after sending final request.
114                                   ///< Zero to use default.
115     uint8_t mHopLimit;            ///< Hop limit (used if `mAllowZeroHopLimit` is false). Zero for default.
116     bool    mAllowZeroHopLimit;   ///< Indicates whether hop limit is zero.
117     bool    mMulticastLoop;       ///< Allow looping back pings to multicast address that device is subscribed to.
118 } otPingSenderConfig;
119 
120 /**
121  * Starts a ping.
122  *
123  * @param[in] aInstance            A pointer to an OpenThread instance.
124  * @param[in] aConfig              The ping config to use.
125  *
126  * @retval OT_ERROR_NONE           The ping started successfully.
127  * @retval OT_ERROR_BUSY           Could not start since busy with a previous ongoing ping request.
128  * @retval OT_ERROR_INVALID_ARGS   The @p aConfig contains invalid parameters (e.g., ping interval is too long).
129 
130  */
131 otError otPingSenderPing(otInstance *aInstance, const otPingSenderConfig *aConfig);
132 
133 /**
134  * Stops an ongoing ping.
135  *
136  * @param[in] aInstance            A pointer to an OpenThread instance.
137  */
138 void otPingSenderStop(otInstance *aInstance);
139 
140 /**
141  * @}
142  */
143 
144 #ifdef __cplusplus
145 } // extern "C"
146 #endif
147 
148 #endif // OPENTHREAD_PING_SENDER_H_
149