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 * ICMPv6 Message Types 56 */ 57 typedef enum otIcmp6Type 58 { 59 OT_ICMP6_TYPE_DST_UNREACH = 1, ///< Destination Unreachable 60 OT_ICMP6_TYPE_PACKET_TO_BIG = 2, ///< Packet To Big 61 OT_ICMP6_TYPE_TIME_EXCEEDED = 3, ///< Time Exceeded 62 OT_ICMP6_TYPE_PARAMETER_PROBLEM = 4, ///< Parameter Problem 63 OT_ICMP6_TYPE_ECHO_REQUEST = 128, ///< Echo Request 64 OT_ICMP6_TYPE_ECHO_REPLY = 129, ///< Echo Reply 65 OT_ICMP6_TYPE_ROUTER_SOLICIT = 133, ///< Router Solicitation 66 OT_ICMP6_TYPE_ROUTER_ADVERT = 134, ///< Router Advertisement 67 OT_ICMP6_TYPE_NEIGHBOR_SOLICIT = 135, ///< Neighbor Solicitation 68 OT_ICMP6_TYPE_NEIGHBOR_ADVERT = 136, ///< Neighbor Advertisement 69 } otIcmp6Type; 70 71 /** 72 * ICMPv6 Message Codes 73 */ 74 typedef enum otIcmp6Code 75 { 76 OT_ICMP6_CODE_DST_UNREACH_NO_ROUTE = 0, ///< Destination Unreachable (Type 1) - No Route 77 OT_ICMP6_CODE_DST_UNREACH_PROHIBITED = 1, ///< Destination Unreachable (Type 1) - Administratively Prohibited 78 OT_ICMP6_CODE_FRAGM_REAS_TIME_EX = 1, ///< Time Exceeded (Type 3) - Fragment Reassembly 79 } otIcmp6Code; 80 81 #define OT_ICMP6_HEADER_DATA_SIZE 4 ///< Size of ICMPv6 Header. 82 #define OT_ICMP6_ROUTER_ADVERT_MIN_SIZE 16 ///< Size of a Router Advertisement message without any options. 83 84 /** 85 * @struct otIcmp6Header 86 * 87 * Represents an ICMPv6 header. 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 * Represents an ICMPv6 header. 105 */ 106 typedef struct otIcmp6Header otIcmp6Header; 107 108 /** 109 * This callback allows OpenThread to inform the application of a received ICMPv6 message. 110 * 111 * @param[in] aContext A pointer to arbitrary context information. 112 * @param[in] aMessage A pointer to the received message. 113 * @param[in] aMessageInfo A pointer to message information associated with @p aMessage. 114 * @param[in] aIcmpHeader A pointer to the received ICMPv6 header. 115 */ 116 typedef void (*otIcmp6ReceiveCallback)(void *aContext, 117 otMessage *aMessage, 118 const otMessageInfo *aMessageInfo, 119 const otIcmp6Header *aIcmpHeader); 120 121 /** 122 * Implements ICMPv6 message handler. 123 */ 124 typedef struct otIcmp6Handler 125 { 126 otIcmp6ReceiveCallback mReceiveCallback; ///< The ICMPv6 received callback 127 void *mContext; ///< A pointer to arbitrary context information. 128 struct otIcmp6Handler *mNext; ///< A pointer to the next handler in the list. 129 } otIcmp6Handler; 130 131 /** 132 * ICMPv6 Echo Reply Modes 133 */ 134 typedef enum otIcmp6EchoMode 135 { 136 OT_ICMP6_ECHO_HANDLER_DISABLED = 0, ///< ICMPv6 Echo processing disabled 137 OT_ICMP6_ECHO_HANDLER_UNICAST_ONLY = 1, ///< ICMPv6 Echo processing enabled only for unicast requests only 138 OT_ICMP6_ECHO_HANDLER_MULTICAST_ONLY = 2, ///< ICMPv6 Echo processing enabled only for multicast requests only 139 OT_ICMP6_ECHO_HANDLER_ALL = 3, ///< ICMPv6 Echo processing enabled for unicast and multicast requests 140 OT_ICMP6_ECHO_HANDLER_RLOC_ALOC_ONLY = 4, ///< ICMPv6 Echo processing enabled for RLOC/ALOC destinations only 141 } otIcmp6EchoMode; 142 143 /** 144 * Indicates whether or not ICMPv6 Echo processing is enabled. 145 * 146 * @param[in] aInstance A pointer to an OpenThread instance. 147 * 148 * @retval OT_ICMP6_ECHO_HANDLER_DISABLED ICMPv6 Echo processing is disabled. 149 * @retval OT_ICMP6_ECHO_HANDLER_UNICAST_ONLY ICMPv6 Echo processing enabled for unicast requests only 150 * @retval OT_ICMP6_ECHO_HANDLER_MULTICAST_ONLY ICMPv6 Echo processing enabled for multicast requests only 151 * @retval OT_ICMP6_ECHO_HANDLER_ALL ICMPv6 Echo processing enabled for unicast and multicast requests 152 */ 153 otIcmp6EchoMode otIcmp6GetEchoMode(otInstance *aInstance); 154 155 /** 156 * Sets whether or not ICMPv6 Echo processing is enabled. 157 * 158 * @param[in] aInstance A pointer to an OpenThread instance. 159 * @param[in] aMode The ICMPv6 Echo processing mode. 160 */ 161 void otIcmp6SetEchoMode(otInstance *aInstance, otIcmp6EchoMode aMode); 162 163 /** 164 * Registers a handler to provide received ICMPv6 messages. 165 * 166 * @note A handler structure @p aHandler has to be stored in persistent (static) memory. 167 * OpenThread does not make a copy of handler structure. 168 * 169 * @param[in] aInstance A pointer to an OpenThread instance. 170 * @param[in] aHandler A pointer to a handler containing callback that is called when 171 * an ICMPv6 message is received. 172 */ 173 otError otIcmp6RegisterHandler(otInstance *aInstance, otIcmp6Handler *aHandler); 174 175 /** 176 * Sends an ICMPv6 Echo Request via the Thread interface. 177 * 178 * @param[in] aInstance A pointer to an OpenThread instance. 179 * @param[in] aMessage A pointer to the message buffer containing the ICMPv6 payload. 180 * @param[in] aMessageInfo A reference to message information associated with @p aMessage. 181 * @param[in] aIdentifier An identifier to aid in matching Echo Replies to this Echo Request. 182 * May be zero. 183 */ 184 otError otIcmp6SendEchoRequest(otInstance *aInstance, 185 otMessage *aMessage, 186 const otMessageInfo *aMessageInfo, 187 uint16_t aIdentifier); 188 189 /** 190 * @} 191 */ 192 193 #ifdef __cplusplus 194 } // extern "C" 195 #endif 196 197 #endif // OPENTHREAD_ICMP6_H_ 198
