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