1 // Copyright 2019 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #pragma once 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 #include <stdint.h> 22 #include "esp_err.h" 23 #include "lwip/ip_addr.h" 24 25 /** 26 * @brief Type of "ping" session handle 27 * 28 */ 29 typedef void *esp_ping_handle_t; 30 31 /** 32 * @brief Type of "ping" callback functions 33 * 34 */ 35 typedef struct { 36 /** 37 * @brief arguments for callback functions 38 * 39 */ 40 void *cb_args; 41 42 /** 43 * @brief Invoked by internal ping thread when received ICMP echo reply packet 44 * 45 */ 46 void (*on_ping_success)(esp_ping_handle_t hdl, void *args); 47 48 /** 49 * @brief Invoked by internal ping thread when receive ICMP echo reply packet timeout 50 * 51 */ 52 void (*on_ping_timeout)(esp_ping_handle_t hdl, void *args); 53 54 /** 55 * @brief Invoked by internal ping thread when a ping session is finished 56 * 57 */ 58 void (*on_ping_end)(esp_ping_handle_t hdl, void *args); 59 } esp_ping_callbacks_t; 60 61 /** 62 * @brief Type of "ping" configuration 63 * 64 */ 65 typedef struct { 66 uint32_t count; /*!< A "ping" session contains count procedures */ 67 uint32_t interval_ms; /*!< Milliseconds between each ping procedure */ 68 uint32_t timeout_ms; /*!< Timeout value (in milliseconds) of each ping procedure */ 69 uint32_t data_size; /*!< Size of the data next to ICMP packet header */ 70 uint8_t tos; /*!< Type of Service, a field specified in the IP header */ 71 ip_addr_t target_addr; /*!< Target IP address, either IPv4 or IPv6 */ 72 uint32_t task_stack_size; /*!< Stack size of internal ping task */ 73 uint32_t task_prio; /*!< Priority of internal ping task */ 74 uint32_t interface; /*!< Netif index, interface=0 means NETIF_NO_INDEX*/ 75 } esp_ping_config_t; 76 77 /** 78 * @brief Default ping configuration 79 * 80 */ 81 #define ESP_PING_DEFAULT_CONFIG() \ 82 { \ 83 .count = 5, \ 84 .interval_ms = 1000, \ 85 .timeout_ms = 1000, \ 86 .data_size = 64, \ 87 .tos = 0, \ 88 .target_addr = *(IP_ANY_TYPE), \ 89 .task_stack_size = 2048, \ 90 .task_prio = 2, \ 91 .interface = 0,\ 92 } 93 94 #define ESP_PING_COUNT_INFINITE (0) /*!< Set ping count to zero will ping target infinitely */ 95 96 /** 97 * @brief Profile of ping session 98 * 99 */ 100 typedef enum { 101 ESP_PING_PROF_SEQNO, /*!< Sequence number of a ping procedure */ 102 ESP_PING_PROF_TTL, /*!< Time to live of a ping procedure */ 103 ESP_PING_PROF_REQUEST, /*!< Number of request packets sent out */ 104 ESP_PING_PROF_REPLY, /*!< Number of reply packets received */ 105 ESP_PING_PROF_IPADDR, /*!< IP address of replied target */ 106 ESP_PING_PROF_SIZE, /*!< Size of received packet */ 107 ESP_PING_PROF_TIMEGAP, /*!< Elapsed time between request and reply packet */ 108 ESP_PING_PROF_DURATION /*!< Elapsed time of the whole ping session */ 109 } esp_ping_profile_t; 110 111 /** 112 * @brief Create a ping session 113 * 114 * @param config ping configuration 115 * @param cbs a bunch of callback functions invoked by internal ping task 116 * @param hdl_out handle of ping session 117 * @return 118 * - ESP_ERR_INVALID_ARG: invalid parameters (e.g. configuration is null, etc) 119 * - ESP_ERR_NO_MEM: out of memory 120 * - ESP_FAIL: other internal error (e.g. socket error) 121 * - ESP_OK: create ping session successfully, user can take the ping handle to do follow-on jobs 122 */ 123 esp_err_t esp_ping_new_session(const esp_ping_config_t *config, const esp_ping_callbacks_t *cbs, esp_ping_handle_t *hdl_out); 124 125 /** 126 * @brief Delete a ping session 127 * 128 * @param hdl handle of ping session 129 * @return 130 * - ESP_ERR_INVALID_ARG: invalid parameters (e.g. ping handle is null, etc) 131 * - ESP_OK: delete ping session successfully 132 */ 133 esp_err_t esp_ping_delete_session(esp_ping_handle_t hdl); 134 135 /** 136 * @brief Start the ping session 137 * 138 * @param hdl handle of ping session 139 * @return 140 * - ESP_ERR_INVALID_ARG: invalid parameters (e.g. ping handle is null, etc) 141 * - ESP_OK: start ping session successfully 142 */ 143 esp_err_t esp_ping_start(esp_ping_handle_t hdl); 144 145 /** 146 * @brief Stop the ping session 147 * 148 * @param hdl handle of ping session 149 * @return 150 * - ESP_ERR_INVALID_ARG: invalid parameters (e.g. ping handle is null, etc) 151 * - ESP_OK: stop ping session successfully 152 */ 153 esp_err_t esp_ping_stop(esp_ping_handle_t hdl); 154 155 /** 156 * @brief Get runtime profile of ping session 157 * 158 * @param hdl handle of ping session 159 * @param profile type of profile 160 * @param data profile data 161 * @param size profile data size 162 * @return 163 * - ESP_ERR_INVALID_ARG: invalid parameters (e.g. ping handle is null, etc) 164 * - ESP_ERR_INVALID_SIZE: the actual profile data size doesn't match the "size" parameter 165 * - ESP_OK: get profile successfully 166 */ 167 esp_err_t esp_ping_get_profile(esp_ping_handle_t hdl, esp_ping_profile_t profile, void *data, uint32_t size); 168 169 #ifdef __cplusplus 170 } 171 #endif 172
