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 functions for the Thread Border Agent role.
33  */
34 
35 #ifndef OPENTHREAD_BORDER_AGENT_H_
36 #define OPENTHREAD_BORDER_AGENT_H_
37 
38 #include <openthread/instance.h>
39 
40 #ifdef __cplusplus
41 extern "C" {
42 #endif
43 
44 /**
45  * @addtogroup api-border-agent
46  *
47  * @brief
48  *   This module includes functions for the Thread Border Agent role.
49  *
50  * @{
51  *
52  */
53 
54 /**
55  * The length of Border Agent/Router ID in bytes.
56  *
57  */
58 #define OT_BORDER_AGENT_ID_LENGTH (16)
59 
60 /**
61  * @struct otBorderAgentId
62  *
63  * Represents a Border Agent ID.
64  *
65  */
66 OT_TOOL_PACKED_BEGIN
67 struct otBorderAgentId
68 {
69     uint8_t mId[OT_BORDER_AGENT_ID_LENGTH];
70 } OT_TOOL_PACKED_END;
71 
72 /**
73  * Represents a Border Agent ID.
74  *
75  */
76 typedef struct otBorderAgentId otBorderAgentId;
77 
78 /**
79  * Defines the Border Agent state.
80  *
81  */
82 typedef enum otBorderAgentState
83 {
84     OT_BORDER_AGENT_STATE_STOPPED = 0, ///< Border agent role is disabled.
85     OT_BORDER_AGENT_STATE_STARTED = 1, ///< Border agent is started.
86     OT_BORDER_AGENT_STATE_ACTIVE  = 2, ///< Border agent is connected with external commissioner.
87 } otBorderAgentState;
88 
89 /**
90  * Gets the #otBorderAgentState of the Thread Border Agent role.
91  *
92  * @param[in]  aInstance  A pointer to an OpenThread instance.
93  *
94  * @returns The current #otBorderAgentState of the Border Agent.
95  *
96  */
97 otBorderAgentState otBorderAgentGetState(otInstance *aInstance);
98 
99 /**
100  * Gets the UDP port of the Thread Border Agent service.
101  *
102  * @param[in]  aInstance  A pointer to an OpenThread instance.
103  *
104  * @returns UDP port of the Border Agent.
105  *
106  */
107 uint16_t otBorderAgentGetUdpPort(otInstance *aInstance);
108 
109 /**
110  * Gets the randomly generated Border Agent ID.
111  *
112  * The ID is saved in persistent storage and survives reboots. The typical use case of the ID is to
113  * be published in the MeshCoP mDNS service as the `id` TXT value for the client to identify this
114  * Border Router/Agent device.
115  *
116  * @param[in]    aInstance  A pointer to an OpenThread instance.
117  * @param[out]   aId        A pointer to buffer to receive the ID.
118  *
119  * @retval OT_ERROR_NONE  If successfully retrieved the Border Agent ID.
120  * @retval ...            If failed to retrieve the Border Agent ID.
121  *
122  * @sa otBorderAgentSetId
123  *
124  */
125 otError otBorderAgentGetId(otInstance *aInstance, otBorderAgentId *aId);
126 
127 /**
128  * Sets the Border Agent ID.
129  *
130  * The Border Agent ID will be saved in persistent storage and survive reboots. It's required to
131  * set the ID only once after factory reset. If the ID has never been set by calling this function,
132  * a random ID will be generated and returned when `otBorderAgentGetId` is called.
133  *
134  * @param[in]    aInstance  A pointer to an OpenThread instance.
135  * @param[out]   aId        A pointer to the Border Agent ID.
136  *
137  * @retval OT_ERROR_NONE  If successfully set the Border Agent ID.
138  * @retval ...            If failed to set the Border Agent ID.
139  *
140  * @sa otBorderAgentGetId
141  *
142  */
143 otError otBorderAgentSetId(otInstance *aInstance, const otBorderAgentId *aId);
144 
145 /**
146  * @}
147  *
148  */
149 
150 #ifdef __cplusplus
151 } // end of extern "C"
152 #endif
153 
154 #endif // OPENTHREAD_BORDER_AGENT_H_
155