1 /*
2  *  Copyright (c) 2018, 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 includes the abstraction for the platform UDP service.
33  */
34 
35 #ifndef OPENTHREAD_PLATFORM_UDP_H_
36 #define OPENTHREAD_PLATFORM_UDP_H_
37 
38 #include <openthread/udp.h>
39 
40 #ifdef __cplusplus
41 extern "C" {
42 #endif
43 
44 /**
45  * Initializes the UDP socket by platform.
46  *
47  * @param[in]   aUdpSocket  A pointer to the UDP socket.
48  *
49  * @retval  OT_ERROR_NONE   Successfully initialized UDP socket by platform.
50  * @retval  OT_ERROR_FAILED Failed to initialize UDP Socket.
51  */
52 otError otPlatUdpSocket(otUdpSocket *aUdpSocket);
53 
54 /**
55  * Closes the UDP socket by platform.
56  *
57  * @param[in]   aUdpSocket  A pointer to the UDP socket.
58  *
59  * @retval  OT_ERROR_NONE   Successfully closed UDP socket by platform.
60  * @retval  OT_ERROR_FAILED Failed to close UDP Socket.
61  */
62 otError otPlatUdpClose(otUdpSocket *aUdpSocket);
63 
64 /**
65  * Binds the UDP socket by platform.
66  *
67  * @param[in]   aUdpSocket  A pointer to the UDP socket.
68  *
69  * @retval  OT_ERROR_NONE   Successfully bound UDP socket by platform.
70  * @retval  OT_ERROR_FAILED Failed to bind UDP socket.
71  */
72 otError otPlatUdpBind(otUdpSocket *aUdpSocket);
73 
74 /**
75  * Binds the UDP socket to a platform network interface.
76  *
77  * Note: only available when `OPENTHREAD_CONFIG_PLATFORM_UDP_ENABLE` is used.
78  *
79  * @param[in]   aUdpSocket          A pointer to the UDP socket.
80  * @param[in]   aNetifIdentifier    The network interface identifier.
81  *
82  * @retval  OT_ERROR_NONE   Successfully bound UDP socket.
83  * @retval  OT_ERROR_FAILED Failed to bind UDP.
84  */
85 otError otPlatUdpBindToNetif(otUdpSocket *aUdpSocket, otNetifIdentifier aNetifIdentifier);
86 
87 /**
88  * Connects UDP socket by platform.
89  *
90  * @param[in]   aUdpSocket  A pointer to the UDP socket.
91  *
92  * @retval  OT_ERROR_NONE   Successfully connected by platform.
93  * @retval  OT_ERROR_FAILED Failed to connect UDP socket.
94  */
95 otError otPlatUdpConnect(otUdpSocket *aUdpSocket);
96 
97 /**
98  * Sends UDP payload by platform.
99  *
100  * @param[in]   aUdpSocket      A pointer to the UDP socket.
101  * @param[in]   aMessage        A pointer to the message to send.
102  * @param[in]   aMessageInfo    A pointer to the message info associated with @p aMessage.
103  *
104  * @retval  OT_ERROR_NONE   Successfully sent by platform, and @p aMessage is freed.
105  * @retval  OT_ERROR_FAILED Failed to bind UDP socket.
106  */
107 otError otPlatUdpSend(otUdpSocket *aUdpSocket, otMessage *aMessage, const otMessageInfo *aMessageInfo);
108 
109 /**
110  * Configures the UDP socket to join a UDP multicast group.
111  *
112  * Note: only available when `OPENTHREAD_CONFIG_PLATFORM_UDP_ENABLE` is used.
113  *
114  * @param[in]   aUdpSocket          A pointer to the UDP socket.
115  * @param[in]   aNetifIdentifier    The network interface identifier.
116  * @param[in]   aAddress            The UDP multicast group address.
117  *
118  * @retval  OT_ERROR_NONE   Successfully joined the multicast group.
119  * @retval  OT_ERROR_FAILED Failed to join the multicast group.
120  */
121 otError otPlatUdpJoinMulticastGroup(otUdpSocket        *aUdpSocket,
122                                     otNetifIdentifier   aNetifIdentifier,
123                                     const otIp6Address *aAddress);
124 
125 /**
126  * Configures the UDP socket to leave a UDP multicast group.
127  *
128  * Note: only available when `OPENTHREAD_CONFIG_PLATFORM_UDP_ENABLE` is used.
129  *
130  * @param[in]   aUdpSocket          A pointer to the UDP socket.
131  * @param[in]   aNetifIdentifier    The network interface identifier.
132  * @param[in]   aAddress            The UDP multicast group address.
133  *
134  * @retval  OT_ERROR_NONE   Successfully left the multicast group.
135  * @retval  OT_ERROR_FAILED Failed to leave the multicast group.
136  */
137 otError otPlatUdpLeaveMulticastGroup(otUdpSocket        *aUdpSocket,
138                                      otNetifIdentifier   aNetifIdentifier,
139                                      const otIp6Address *aAddress);
140 
141 #ifdef __cplusplus
142 } // extern "C"
143 #endif
144 
145 #endif // OPENTHREAD_PLATFORM_UDP_H_
146