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