1 /* 2 * Copyright (c) 2016, 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 defines the top-level ICMPv6 functions for the OpenThread library. 33 */ 34 35 #ifndef OPENTHREAD_ICMP6_H_ 36 #define OPENTHREAD_ICMP6_H_ 37 38 #include <openthread/ip6.h> 39 #include <openthread/message.h> 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 /** 46 * @addtogroup api-icmp6 47 * 48 * @brief 49 * This module includes functions that control ICMPv6 communication. 50 * 51 * @{ 52 * 53 */ 54 55 /** 56 * ICMPv6 Message Types 57 * 58 */ 59 typedef enum otIcmp6Type 60 { 61 OT_ICMP6_TYPE_DST_UNREACH = 1, ///< Destination Unreachable 62 OT_ICMP6_TYPE_PACKET_TO_BIG = 2, ///< Packet To Big 63 OT_ICMP6_TYPE_TIME_EXCEEDED = 3, ///< Time Exceeded 64 OT_ICMP6_TYPE_PARAMETER_PROBLEM = 4, ///< Parameter Problem 65 OT_ICMP6_TYPE_ECHO_REQUEST = 128, ///< Echo Request 66 OT_ICMP6_TYPE_ECHO_REPLY = 129, ///< Echo Reply 67 OT_ICMP6_TYPE_ROUTER_SOLICIT = 133, ///< Router Solicitation 68 OT_ICMP6_TYPE_ROUTER_ADVERT = 134, ///< Router Advertisement 69 } otIcmp6Type; 70 71 /** 72 * ICMPv6 Message Codes 73 * 74 */ 75 typedef enum otIcmp6Code 76 { 77 OT_ICMP6_CODE_DST_UNREACH_NO_ROUTE = 0, ///< Destination Unreachable No Route 78 OT_ICMP6_CODE_FRAGM_REAS_TIME_EX = 1, ///< Fragment Reassembly Time Exceeded 79 } otIcmp6Code; 80 81 #define OT_ICMP6_HEADER_DATA_SIZE 4 ///< Size of an message specific data of ICMPv6 Header. 82 83 /** 84 * @struct otIcmp6Header 85 * 86 * This structure represents an ICMPv6 header. 87 * 88 */ 89 OT_TOOL_PACKED_BEGIN 90 struct otIcmp6Header 91 { 92 uint8_t mType; ///< Type 93 uint8_t mCode; ///< Code 94 uint16_t mChecksum; ///< Checksum 95 union OT_TOOL_PACKED_FIELD 96 { 97 uint8_t m8[OT_ICMP6_HEADER_DATA_SIZE / sizeof(uint8_t)]; 98 uint16_t m16[OT_ICMP6_HEADER_DATA_SIZE / sizeof(uint16_t)]; 99 uint32_t m32[OT_ICMP6_HEADER_DATA_SIZE / sizeof(uint32_t)]; 100 } mData; ///< Message-specific data 101 } OT_TOOL_PACKED_END; 102 103 /** 104 * This type represents an ICMPv6 header. 105 * 106 */ 107 typedef struct otIcmp6Header otIcmp6Header; 108 109 /** 110 * This callback allows OpenThread to inform the application of a received ICMPv6 message. 111 * 112 * @param[in] aContext A pointer to arbitrary context information. 113 * @param[in] aMessage A pointer to the received message. 114 * @param[in] aMessageInfo A pointer to message information associated with @p aMessage. 115 * @param[in] aIcmpHeader A pointer to the received ICMPv6 header. 116 * 117 */ 118 typedef void (*otIcmp6ReceiveCallback)(void * aContext, 119 otMessage * aMessage, 120 const otMessageInfo *aMessageInfo, 121 const otIcmp6Header *aIcmpHeader); 122 123 /** 124 * This structure implements ICMPv6 message handler. 125 * 126 */ 127 typedef struct otIcmp6Handler 128 { 129 otIcmp6ReceiveCallback mReceiveCallback; ///< The ICMPv6 received callback 130 void * mContext; ///< A pointer to arbitrary context information. 131 struct otIcmp6Handler *mNext; ///< A pointer to the next handler in the list. 132 } otIcmp6Handler; 133 134 /** 135 * ICMPv6 Echo Reply Modes 136 * 137 */ 138 typedef enum otIcmp6EchoMode 139 { 140 OT_ICMP6_ECHO_HANDLER_DISABLED = 0, ///< ICMPv6 Echo processing disabled 141 OT_ICMP6_ECHO_HANDLER_UNICAST_ONLY = 1, ///< ICMPv6 Echo processing enabled only for unicast requests only 142 OT_ICMP6_ECHO_HANDLER_MULTICAST_ONLY = 2, ///< ICMPv6 Echo processing enabled only for multicast requests only 143 OT_ICMP6_ECHO_HANDLER_ALL = 3, ///< ICMPv6 Echo processing enabled for unicast and multicast requests 144 } otIcmp6EchoMode; 145 146 /** 147 * This function indicates whether or not ICMPv6 Echo processing is enabled. 148 * 149 * @param[in] aInstance A pointer to an OpenThread instance. 150 * 151 * @retval OT_ICMP6_ECHO_HANDLER_DISABLED ICMPv6 Echo processing is disabled. 152 * @retval OT_ICMP6_ECHO_HANDLER_UNICAST_ONLY ICMPv6 Echo processing enabled for unicast requests only 153 * @retval OT_ICMP6_ECHO_HANDLER_MULTICAST_ONLY ICMPv6 Echo processing enabled for multicast requests only 154 * @retval OT_ICMP6_ECHO_HANDLER_ALL ICMPv6 Echo processing enabled for unicast and multicast requests 155 * 156 */ 157 otIcmp6EchoMode otIcmp6GetEchoMode(otInstance *aInstance); 158 159 /** 160 * This function sets whether or not ICMPv6 Echo processing is enabled. 161 * 162 * @param[in] aInstance A pointer to an OpenThread instance. 163 * @param[in] aMode The ICMPv6 Echo processing mode. 164 * 165 */ 166 void otIcmp6SetEchoMode(otInstance *aInstance, otIcmp6EchoMode aMode); 167 168 /** 169 * This function registers a handler to provide received ICMPv6 messages. 170 * 171 * @note A handler structure @p aHandler has to be stored in persistent (static) memory. 172 * OpenThread does not make a copy of handler structure. 173 * 174 * @param[in] aInstance A pointer to an OpenThread instance. 175 * @param[in] aHandler A pointer to a handler containing callback that is called when 176 * an ICMPv6 message is received. 177 * 178 */ 179 otError otIcmp6RegisterHandler(otInstance *aInstance, otIcmp6Handler *aHandler); 180 181 /** 182 * This function sends an ICMPv6 Echo Request via the Thread interface. 183 * 184 * @param[in] aInstance A pointer to an OpenThread instance. 185 * @param[in] aMessage A pointer to the message buffer containing the ICMPv6 payload. 186 * @param[in] aMessageInfo A reference to message information associated with @p aMessage. 187 * @param[in] aIdentifier An identifier to aid in matching Echo Replies to this Echo Request. 188 * May be zero. 189 * 190 */ 191 otError otIcmp6SendEchoRequest(otInstance * aInstance, 192 otMessage * aMessage, 193 const otMessageInfo *aMessageInfo, 194 uint16_t aIdentifier); 195 196 /** 197 * @} 198 * 199 */ 200 201 #ifdef __cplusplus 202 } // extern "C" 203 #endif 204 205 #endif // OPENTHREAD_ICMP6_H_ 206
