openthread/include/openthread/ping_sender.h

/*
 *  Copyright (c) 2021, The OpenThread Authors.
 *  All rights reserved.
 *
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions are met:
 *  1. Redistributions of source code must retain the above copyright
 *     notice, this list of conditions and the following disclaimer.
 *  2. Redistributions in binary form must reproduce the above copyright
 *     notice, this list of conditions and the following disclaimer in the
 *     documentation and/or other materials provided with the distribution.
 *  3. Neither the name of the copyright holder nor the
 *     names of its contributors may be used to endorse or promote products
 *     derived from this software without specific prior written permission.
 *
 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 *  POSSIBILITY OF SUCH DAMAGE.
 */

/**
 * @file
 * @brief
 *   This file includes the OpenThread API for ping sender module.
 */

#ifndef OPENTHREAD_PING_SENDER_H_
#define OPENTHREAD_PING_SENDER_H_

#include <stdint.h>

#include <openthread/error.h>
#include <openthread/instance.h>
#include <openthread/ip6.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @addtogroup api-ping-sender
 *
 * @brief
 *   This file includes the OpenThread API for the ping sender module.
 *
 * @{
 */

/**
 * Represents a ping reply.
 */
typedef struct otPingSenderReply
{
    otIp6Address mSenderAddress;  ///< Sender IPv6 address (address from which ping reply was received).
    uint16_t     mRoundTripTime;  ///< Round trip time in msec.
    uint16_t     mSize;           ///< Data size (number of bytes) in reply (excluding IPv6 and ICMP6 headers).
    uint16_t     mSequenceNumber; ///< Sequence number.
    uint8_t      mHopLimit;       ///< Hop limit.
} otPingSenderReply;

/**
 * Represents statistics of a ping request.
 */
typedef struct otPingSenderStatistics
{
    uint16_t mSentCount;          ///< The number of ping requests already sent.
    uint16_t mReceivedCount;      ///< The number of ping replies received.
    uint32_t mTotalRoundTripTime; ///< The total round trip time of ping requests.
    uint16_t mMinRoundTripTime;   ///< The min round trip time among ping requests.
    uint16_t mMaxRoundTripTime;   ///< The max round trip time among ping requests.
    bool     mIsMulticast;        ///< Whether this is a multicast ping request.
} otPingSenderStatistics;

/**
 * Pointer type specifies the callback to notify receipt of a ping reply.
 *
 * @param[in] aReply      A pointer to a `otPingSenderReply` containing info about the received ping reply.
 * @param[in] aContext    A pointer to application-specific context.
 */
typedef void (*otPingSenderReplyCallback)(const otPingSenderReply *aReply, void *aContext);

/**
 * Pointer type specifies the callback to report the ping statistics.
 *
 * @param[in] aStatistics      A pointer to a `otPingSenderStatistics` containing info about the received ping
 *                             statistics.
 * @param[in] aContext         A pointer to application-specific context.
 */
typedef void (*otPingSenderStatisticsCallback)(const otPingSenderStatistics *aStatistics, void *aContext);

/**
 * Represents a ping request configuration.
 */
typedef struct otPingSenderConfig
{
    otIp6Address              mSource;        ///< Source address of the ping.
    otIp6Address              mDestination;   ///< Destination address to ping.
    otPingSenderReplyCallback mReplyCallback; ///< Callback function to report replies (can be NULL if not needed).
    otPingSenderStatisticsCallback
             mStatisticsCallback; ///< Callback function to report statistics (can be NULL if not needed).
    void    *mCallbackContext;    ///< A pointer to the callback application-specific context.
    uint16_t mSize;               ///< Data size (# of bytes) excludes IPv6/ICMPv6 header. Zero for default.
    uint16_t mCount;              ///< Number of ping messages to send. Zero to use default.
    uint32_t mInterval;           ///< Ping tx interval in milliseconds. Zero to use default.
    uint16_t mTimeout;            ///< Time in milliseconds to wait for final reply after sending final request.
                                  ///< Zero to use default.
    uint8_t mHopLimit;            ///< Hop limit (used if `mAllowZeroHopLimit` is false). Zero for default.
    bool    mAllowZeroHopLimit;   ///< Indicates whether hop limit is zero.
    bool    mMulticastLoop;       ///< Allow looping back pings to multicast address that device is subscribed to.
} otPingSenderConfig;

/**
 * Starts a ping.
 *
 * @param[in] aInstance            A pointer to an OpenThread instance.
 * @param[in] aConfig              The ping config to use.
 *
 * @retval OT_ERROR_NONE           The ping started successfully.
 * @retval OT_ERROR_BUSY           Could not start since busy with a previous ongoing ping request.
 * @retval OT_ERROR_INVALID_ARGS   The @p aConfig contains invalid parameters (e.g., ping interval is too long).

 */
otError otPingSenderPing(otInstance *aInstance, const otPingSenderConfig *aConfig);

/**
 * Stops an ongoing ping.
 *
 * @param[in] aInstance            A pointer to an OpenThread instance.
 */
void otPingSenderStop(otInstance *aInstance);

/**
 * @}
 */

#ifdef __cplusplus
} // extern "C"
#endif

#endif // OPENTHREAD_PING_SENDER_H_