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  *   This file includes definitions for IPv6 sockets.
32  */
33 
34 #ifndef NET_SOCKET_HPP_
35 #define NET_SOCKET_HPP_
36 
37 #include "openthread-core-config.h"
38 
39 #include "common/clearable.hpp"
40 #include "common/equatable.hpp"
41 #include "net/ip6_address.hpp"
42 
43 namespace ot {
44 
45 class ThreadLinkInfo;
46 
47 namespace Ip6 {
48 
49 /**
50  * @addtogroup core-ip6-ip6
51  *
52  * @{
53  *
54  */
55 
56 /**
57  * This class implements message information for an IPv6 message.
58  *
59  */
60 class MessageInfo : public otMessageInfo, public Clearable<MessageInfo>
61 {
62 public:
63     /**
64      * This constructor initializes the object.
65      *
66      */
MessageInfo(void)67     MessageInfo(void) { Clear(); }
68 
69     /**
70      * This method returns a reference to the local socket address.
71      *
72      * @returns A reference to the local socket address.
73      *
74      */
GetSockAddr(void)75     Address &GetSockAddr(void) { return *static_cast<Address *>(&mSockAddr); }
76 
77     /**
78      * This method returns a reference to the local socket address.
79      *
80      * @returns A reference to the local socket address.
81      *
82      */
GetSockAddr(void) const83     const Address &GetSockAddr(void) const { return *static_cast<const Address *>(&mSockAddr); }
84 
85     /**
86      * This method sets the local socket address.
87      *
88      * @param[in]  aAddress  The IPv6 address.
89      *
90      */
SetSockAddr(const Address & aAddress)91     void SetSockAddr(const Address &aAddress) { mSockAddr = aAddress; }
92 
93     /**
94      * This method gets the local socket port.
95      *
96      * @returns The local socket port.
97      *
98      */
GetSockPort(void) const99     uint16_t GetSockPort(void) const { return mSockPort; }
100 
101     /**
102      * This method gets the local socket port.
103      *
104      * @param[in]  aPort  The port value.
105      *
106      */
SetSockPort(uint16_t aPort)107     void SetSockPort(uint16_t aPort) { mSockPort = aPort; }
108 
109     /**
110      * This method returns a reference to the peer socket address.
111      *
112      * @returns A reference to the peer socket address.
113      *
114      */
GetPeerAddr(void)115     Address &GetPeerAddr(void) { return *static_cast<Address *>(&mPeerAddr); }
116 
117     /**
118      * This method returns a reference to the peer socket address.
119      *
120      * @returns A reference to the peer socket address.
121      *
122      */
GetPeerAddr(void) const123     const Address &GetPeerAddr(void) const { return *static_cast<const Address *>(&mPeerAddr); }
124 
125     /**
126      * This method sets the peer's socket address.
127      *
128      * @param[in]  aAddress  The IPv6 address.
129      *
130      */
SetPeerAddr(const Address & aAddress)131     void SetPeerAddr(const Address &aAddress) { mPeerAddr = aAddress; }
132 
133     /**
134      * This method gets the peer socket port.
135      *
136      * @returns The peer socket port.
137      *
138      */
GetPeerPort(void) const139     uint16_t GetPeerPort(void) const { return mPeerPort; }
140 
141     /**
142      * This method gets the peer socket port.
143      *
144      * @param[in]  aPort  The port value.
145      *
146      */
SetPeerPort(uint16_t aPort)147     void SetPeerPort(uint16_t aPort) { mPeerPort = aPort; }
148 
149     /**
150      * This method gets the Hop Limit.
151      *
152      * @returns The Hop Limit.
153      *
154      */
GetHopLimit(void) const155     uint8_t GetHopLimit(void) const { return mHopLimit; }
156 
157     /**
158      * This method sets the Hop Limit.
159      *
160      * @param[in]  aHopLimit  The Hop Limit.
161      *
162      */
SetHopLimit(uint8_t aHopLimit)163     void SetHopLimit(uint8_t aHopLimit) { mHopLimit = aHopLimit; }
164 
165     /**
166      * This method returns whether multicast may be looped back.
167      *
168      * @retval TRUE   If message may be looped back.
169      * @retval FALSE  If message must not be looped back.
170      *
171      */
GetMulticastLoop(void) const172     bool GetMulticastLoop(void) const { return mMulticastLoop; }
173 
174     /**
175      * This method sets whether multicast may be looped back.
176      *
177      * @param[in]  aMulticastLoop  Whether allow looping back multicast.
178      *
179      */
SetMulticastLoop(bool aMulticastLoop)180     void SetMulticastLoop(bool aMulticastLoop) { mMulticastLoop = aMulticastLoop; }
181 
182     /**
183      * This method returns a pointer to the link-specific information object.
184      *
185      * @returns A pointer to the link-specific information object.
186      *
187      */
GetLinkInfo(void) const188     const void *GetLinkInfo(void) const { return mLinkInfo; }
189 
190     /**
191      * This method sets the pointer to the link-specific information object.
192      *
193      * @param[in]  aLinkInfo  A pointer to the link-specific information object.
194      *
195      */
SetLinkInfo(const void * aLinkInfo)196     void SetLinkInfo(const void *aLinkInfo) { mLinkInfo = aLinkInfo; }
197 
198     /**
199      * This method returns a pointer to the link-specific information as a `ThreadLinkInfo`.
200      *
201      * @returns A pointer to to the link-specific information object as `ThreadLinkInfo`.
202      *
203      */
GetThreadLinkInfo(void) const204     const ThreadLinkInfo *GetThreadLinkInfo(void) const { return reinterpret_cast<const ThreadLinkInfo *>(mLinkInfo); }
205 
206     /**
207      * This method gets the ECN status.
208      *
209      * @returns The ECN status, as represented in the IP header.
210      *
211      */
GetEcn(void) const212     uint8_t GetEcn(void) const { return mEcn; }
213 
214     /**
215      * This method sets the ECN status.
216      *
217      * @param[in]  aEcn  The ECN status, as represented in the IP header.
218      *
219      */
SetEcn(uint8_t aEcn)220     void SetEcn(uint8_t aEcn) { mEcn = aEcn; }
221 
222     /**
223      * This method indicates whether peer is via the host interface.
224      *
225      * @retval TRUE if the peer is via the host interface.
226      * @retval FALSE if the peer is via the Thread interface.
227      *
228      */
IsHostInterface(void) const229     bool IsHostInterface(void) const { return mIsHostInterface; }
230 
231     /**
232      * This method indicates whether or not to apply hop limit 0.
233      *
234      * @retval TRUE  if applying hop limit 0 when `mHopLimit` field is 0.
235      * @retval FALSE if applying default `OPENTHREAD_CONFIG_IP6_HOP_LIMIT_DEFAULT` when `mHopLimit` field is 0.
236      *
237      */
ShouldAllowZeroHopLimit(void) const238     bool ShouldAllowZeroHopLimit(void) const { return mAllowZeroHopLimit; }
239 
240     /**
241      * This method sets whether the peer is via the host interface.
242      *
243      * @param[in]  aIsHost  TRUE if the peer is via the host interface, FALSE otherwise.
244      *
245      */
SetIsHostInterface(bool aIsHost)246     void SetIsHostInterface(bool aIsHost) { mIsHostInterface = aIsHost; }
247 };
248 
249 /**
250  * This class implements a socket address.
251  *
252  */
253 class SockAddr : public otSockAddr, public Clearable<SockAddr>, public Unequatable<SockAddr>
254 {
255 public:
256     static constexpr uint16_t kInfoStringSize = OT_IP6_SOCK_ADDR_STRING_SIZE; ///< Info string size (`ToString()`).
257 
258     /**
259      * This type defines the fixed-length `String` object returned from `ToString()`.
260      *
261      */
262     typedef String<kInfoStringSize> InfoString;
263 
264     /**
265      * This constructor initializes the socket address (all fields are set to zero).
266      *
267      */
SockAddr(void)268     SockAddr(void) { Clear(); }
269 
270     /**
271      * This constructor initializes the socket address with a given port number.
272      *
273      * @param[in] aPort   A port number.
274      *
275      */
SockAddr(uint16_t aPort)276     explicit SockAddr(uint16_t aPort)
277     {
278         mPort = aPort;
279         GetAddress().Clear();
280     }
281 
282     /**
283      * This constructor initializes the socket address with a given address and port number.
284      *
285      * @param[in] aAddress  An IPv6 address.
286      * @param[in] aPort     A port number.
287      *
288      */
SockAddr(const Address & aAddress,uint16_t aPort)289     SockAddr(const Address &aAddress, uint16_t aPort)
290     {
291         mAddress = aAddress;
292         mPort    = aPort;
293     }
294 
295     /**
296      * This method returns a reference to the IPv6 address.
297      *
298      * @returns A reference to the IPv6 address.
299      *
300      */
GetAddress(void)301     Address &GetAddress(void) { return *static_cast<Address *>(&mAddress); }
302 
303     /**
304      * This method returns a reference to the IPv6 address.
305      *
306      * @returns A reference to the IPv6 address.
307      *
308      */
GetAddress(void) const309     const Address &GetAddress(void) const { return *static_cast<const Address *>(&mAddress); }
310 
311     /**
312      * This method sets the IPv6 address.
313      *
314      * @param[in] aAddress The IPv6 address.
315      *
316      */
SetAddress(const Address & aAddress)317     void SetAddress(const Address &aAddress) { mAddress = aAddress; }
318 
319     /**
320      * This method returns the socket address port number.
321      *
322      * @returns The port number
323      *
324      */
GetPort(void) const325     uint16_t GetPort(void) const { return mPort; }
326 
327     /**
328      * This method sets the socket address port number.
329      *
330      * @param[in] aPort  The port number.
331      *
332      */
SetPort(uint16_t aPort)333     void SetPort(uint16_t aPort) { mPort = aPort; }
334 
335     /**
336      * This method overloads operator `==` to evaluate whether or not two `SockAddr` instances are equal (same address
337      * and port number).
338      *
339      * @param[in]  aOther  The other `SockAddr` instance to compare with.
340      *
341      * @retval TRUE   If the two `SockAddr` instances are equal.
342      * @retval FALSE  If the two `SockAddr` instances not equal.
343      *
344      */
operator ==(const SockAddr & aOther) const345     bool operator==(const SockAddr &aOther) const
346     {
347         return (GetPort() == aOther.GetPort()) && (GetAddress() == aOther.GetAddress());
348     }
349 
350     /**
351      * This method converts the socket address to a string.
352      *
353      * The string is formatted as "[<ipv6 address>]:<port number>".
354      *
355      * @returns An `InfoString` containing the string representation of the `SockAddr`
356      *
357      */
358     InfoString ToString(void) const;
359 
360     /**
361      * This method converts a given IPv6 socket address to a human-readable string.
362      *
363      * The IPv6 socket address string is formatted as "[<ipv6 address>]:<port>".
364      *
365      * If the resulting string does not fit in @p aBuffer (within its @p aSize characters), the string will be
366      * truncated but the outputted string is always null-terminated.
367      *
368      * @param[out] aBuffer   A pointer to a char array to output the string (MUST NOT be NULL).
369      * @param[in]  aSize     The size of @p aBuffer (in bytes).
370      *
371      */
372     void ToString(char *aBuffer, uint16_t aSize) const;
373 
374 private:
375     void ToString(StringWriter &aWriter) const;
376 };
377 
378 /**
379  * @}
380  */
381 
382 } // namespace Ip6
383 } // namespace ot
384 
385 #endif // NET_SOCKET_HPP_
386