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