1 /*
2  *  Copyright (c) 2022, 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  *   This file includes definitions for infrastructure network interface.
32  *
33  */
34 
35 #ifndef INFRA_IF_HPP_
36 #define INFRA_IF_HPP_
37 
38 #include "openthread-core-config.h"
39 
40 #if OPENTHREAD_CONFIG_BORDER_ROUTING_ENABLE
41 
42 #include <openthread/platform/infra_if.h>
43 
44 #include "common/data.hpp"
45 #include "common/error.hpp"
46 #include "common/locator.hpp"
47 #include "common/string.hpp"
48 #include "net/ip6.hpp"
49 
50 namespace ot {
51 namespace BorderRouter {
52 
53 /**
54  * Represents the infrastructure network interface on a border router.
55  *
56  */
57 class InfraIf : public InstanceLocator
58 {
59 public:
60     static constexpr uint16_t kInfoStringSize = 20; ///< Max chars for the info string (`ToString()`).
61 
62     typedef String<kInfoStringSize> InfoString;  ///< String type returned from `ToString()`.
63     typedef Data<kWithUint16Length> Icmp6Packet; ///< An IMCPv6 packet (data containing the IP payload)
64 
65     /**
66      * Initializes the `InfraIf`.
67      *
68      * @param[in]  aInstance  A OpenThread instance.
69      *
70      */
71     explicit InfraIf(Instance &aInstance);
72 
73     /**
74      * Initializes the `InfraIf`.
75      *
76      * @param[in]  aIfIndex        The infrastructure interface index.
77      *
78      * @retval  kErrorNone         Successfully initialized the `InfraIf`.
79      * @retval  kErrorInvalidArgs  The index of the infra interface is not valid.
80      * @retval  kErrorInvalidState The `InfraIf` is already initialized.
81      *
82      */
83     Error Init(uint32_t aIfIndex);
84 
85     /**
86      * Deinitilaizes the `InfraIf`.
87      *
88      */
89     void Deinit(void);
90 
91     /**
92      * Indicates whether or not the `InfraIf` is initialized.
93      *
94      * @retval TRUE    The `InfraIf` is initialized.
95      * @retval FALSE   The `InfraIf` is not initialized.
96      *
97      */
IsInitialized(void) const98     bool IsInitialized(void) const { return mInitialized; }
99 
100     /**
101      * Indicates whether or not the infra interface is running.
102      *
103      * @retval TRUE   The infrastructure interface is running.
104      * @retval FALSE  The infrastructure interface is not running.
105      *
106      */
IsRunning(void) const107     bool IsRunning(void) const { return mIsRunning; }
108 
109     /**
110      * Returns the infrastructure interface index.
111      *
112      * @returns The interface index or zero if not initialized.
113      *
114      */
GetIfIndex(void) const115     uint32_t GetIfIndex(void) const { return mIfIndex; }
116 
117     /**
118      * Sets the infrastructure interface index.
119      *
120      * @param[in]  aIfIndex        The infrastructure interface index.
121      *
122      */
SetIfIndex(uint32_t aIfIndex)123     void SetIfIndex(uint32_t aIfIndex) { mIfIndex = aIfIndex; }
124 
125     /**
126      * Indicates whether or not the infra interface has the given IPv6 address assigned.
127      *
128      * MUST be used when interface is initialized.
129      *
130      * @param[in]  aAddress       The IPv6 address.
131      *
132      * @retval TRUE   The infrastructure interface has @p aAddress.
133      * @retval FALSE  The infrastructure interface does not have @p aAddress.
134      *
135      */
136     bool HasAddress(const Ip6::Address &aAddress) const;
137 
138     /**
139      * Sends an ICMPv6 Neighbor Discovery packet on the infrastructure interface.
140      *
141      * MUST be used when interface is initialized.
142      *
143      * @param[in]  aPacket        The ICMPv6 packet to send.
144      * @param[in]  aDestination   The destination address.
145      *
146      * @retval kErrorNone    Successfully sent the ICMPv6 message.
147      * @retval kErrorFailed  Failed to send the ICMPv6 message.
148      *
149      */
150     Error Send(const Icmp6Packet &aPacket, const Ip6::Address &aDestination) const;
151 
152     /**
153      * Processes a received ICMPv6 Neighbor Discovery packet from an infrastructure interface.
154      *
155      * @param[in]  aIfIndex       The infrastructure interface index on which the ICMPv6 message is received.
156      * @param[in]  aSource        The IPv6 source address.
157      * @param[in]  aPacket        The ICMPv6 packet.
158      *
159      */
160     void HandledReceived(uint32_t aIfIndex, const Ip6::Address &aSource, const Icmp6Packet &aPacket);
161 
162     /**
163      * Sends a request to discover the NAT64 prefix on the infrastructure interface.
164      *
165      * @note  This method MUST be used when interface is initialized.
166      *
167      * @retval  kErrorNone    Successfully request NAT64 prefix discovery.
168      * @retval  kErrorFailed  Failed to request NAT64 prefix discovery.
169      *
170      */
171     Error DiscoverNat64Prefix(void) const;
172 
173     /**
174      * Processes the discovered NAT64 prefix.
175      *
176      * @param[in]  aIfIndex    The infrastructure interface index on which the host address is received.
177      * @param[in]  aPrefix     The NAT64 prefix on the infrastructure link.
178      *
179      */
180     void DiscoverNat64PrefixDone(uint32_t aIfIndex, const Ip6::Prefix &aPrefix);
181 
182     /**
183      * Handles infrastructure interface state changes.
184      *
185      * @param[in]  aIfIndex         The infrastructure interface index.
186      * @param[in]  aIsRunning       A boolean that indicates whether the infrastructure interface is running.
187      *
188      * @retval  kErrorNone          Successfully updated the infra interface status.
189      * @retval  kErrorInvalidState  The `InfraIf` is not initialized.
190      * @retval  kErrorInvalidArgs   The @p IfIndex does not match the interface index of `InfraIf`.
191      *
192      */
193     Error HandleStateChanged(uint32_t aIfIndex, bool aIsRunning);
194 
195     /**
196      * Converts the `InfraIf` to a human-readable string.
197      *
198      * @returns The string representation of `InfraIf`.
199      *
200      */
201     InfoString ToString(void) const;
202 
203 private:
204     bool     mInitialized : 1;
205     bool     mIsRunning : 1;
206     uint32_t mIfIndex;
207 };
208 
209 } // namespace BorderRouter
210 } // namespace ot
211 
212 #endif // OPENTHREAD_CONFIG_BORDER_ROUTING_ENABLE
213 
214 #endif // INFRA_IF_HPP_
215