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
