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