Use `URI` all caps in documentation
[iotivity.git] / resource / csdk / connectivity / inc / caedradapter_singlethread.h
1 /* ****************************************************************
2  *
3  * Copyright 2014 Samsung Electronics All Rights Reserved.
4  *
5  *
6  *
7  * Licensed under the Apache License, Version 2.0 (the "License");
8  * you may not use this file except in compliance with the License.
9  * You may obtain a copy of the License at
10  *
11  *      http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing, software
14  * distributed under the License is distributed on an "AS IS" BASIS,
15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16  * See the License for the specific language governing permissions and
17  * limitations under the License.
18  *
19  ******************************************************************/
20
21 /**
22  * @file
23  *
24  * This file contains the APIs for EDR adapters to be implemented.
25  */
26
27 #ifndef CA_EDRADAPTER_SINGLETHREAD_H_
28 #define CA_EDRADAPTER_SINGLETHREAD_H_
29
30 /**
31  * EDR Interface AP
32  **/
33 #include "cacommon.h"
34 #include "caadapterinterface.h"
35
36 #ifdef __cplusplus
37 extern "C"
38 {
39 #endif
40
41 /**
42  * @brief  Initialize EDR Interface.
43  * @param[in] registerCallback  Callback to register EDR interface to Connectivity
44  *                              Abstraction Layer
45  * @param[in] reqRespCallback   Callback to notify request and response messages from server(s)
46  *                              started at Connectivity Abstraction Layer.
47  * @param[in] netCallback       Callback to notify the network additions to Connectivity
48  *                              Abstraction Layer.
49  * @return #CA_STATUS_OK or Appropriate error code
50  * @retval #CA_STATUS_OK Successful
51  * @retval #CA_STATUS_INVALID_PARAM Invalid input parameters
52  * @retval #CA_ADAPTER_NOT_ENABLED Initialization is successful, but bluetooth adapter is not
53  *                                 enabled
54  * @retval #CA_STATUS_FAILED Operation failed
55  */
56 CAResult_t CAInitializeEDR(CARegisterConnectivityCallback registerCallback,
57                            CANetworkPacketReceivedCallback reqRespCallback,
58                            CAAdapterChangeCallback netCallback);
59
60 /**
61  * @brief  Starting EDR connectivity adapters. As its peer to peer it doesnot require to start
62  *         any servers.
63  * @return #CA_STATUS_OK or Appropriate error code
64  * @retval #CA_STATUS_OK  Successful
65  * @retval #CA_ADAPTER_NOT_ENABLED Bluetooth adapter is not enabled
66  * @retval #CA_STATUS_FAILED Operation failed
67  */
68 CAResult_t CAStartEDR(void);
69
70 /**
71  * @brief  Starts listening server for receiving multicast search requests.
72  *         Starts RFCOMM Server with prefixed UUID as per OIC specification.
73  * @return #CA_STATUS_OK or Appropriate error code
74  * @retval #CA_STATUS_OK  Successful
75  * @retval #CA_SERVER_STARTED_ALREADY  Server is already started and running for the predefined
76  *                                     service UUID
77  * @retval #CA_STATUS_FAILED Operation failed
78  */
79 CAResult_t CAStartEDRListeningServer(void);
80
81 /**
82  * @brief  Stops listening server for receiving multicast search requests.
83  *
84  * @return #CA_STATUS_OK or Appropriate error code
85  */
86 CAResult_t CAStopEDRListeningServer(void);
87
88 /**
89  * @brief  Starts discovery server for receiving multicast advertisements.
90  *         Starts RFCOMM Server with prefixed UUID as per OIC specification.
91  * @return #CA_STATUS_OK or Appropriate error code
92  * @retval #CA_STATUS_OK  Successful
93  * @retval #CA_SERVER_STARTED_ALREADY Server is already started and running for the predefined
94  *                                    service UUID
95  * @retval #CA_STATUS_FAILED Operation failed
96  */
97 CAResult_t CAStartEDRDiscoveryServer(void);
98
99 /**
100  * @brief  Sends data to the peer bluetooth OIC device using the adapter connectivity.
101  * @param[in]  endpoint    Remote Endpoint information (like ipaddress, port, reference URI and
102  *                         connectivity type) to which the unicast data has to be sent.
103  * @param[in]  data        Data to be sent.
104  * @param[in]  dataLength  Size of data to be sent.
105  * @return Number of bytes sent on the network. Returns -1 on error.
106  */
107 int32_t CASendEDRUnicastData(const CAEndpoint_t *remoteEndpoint, const void *data,
108                               uint32_t dataLength);
109
110 /**
111  * @brief  Sends multicast data to all discovered bluetooth OIC devices using the adapter
112  *         connectivity.
113  * @param[in]  data        Data which needs to be sent to all discovered bluetooth OIC device.
114  * @param[in]  dataLength  Length of data in bytes.
115  * @return Number of bytes sent on the network. Returns -1 on error.
116  */
117 int32_t CASendEDRMulticastData(const void *data, uint32_t dataLength);
118
119 /**
120  * @brief  Get EDR Connectivity network information.
121  *
122  * @param[out] info  Array of local connectivity information structures.
123  * @param[out] size  Size of the array @info.
124  *
125  * @return #CA_STATUS_OK or Appropriate error code
126  * @retval #CA_STATUS_OK  Successful
127  * @retval #CA_STATUS_INVALID_PARAM  Invalid input parameters
128  * @retval #CA_MEMORY_ALLOC_FAILED  Failed to allocate memory
129  * @retval #CA_STATUS_FAILED Operation failed
130  * @remarks info is allocated in this API and should be freed by the caller.
131  */
132 CAResult_t CAGetEDRInterfaceInformation(CAEndpoint_t **info, size_t *size);
133
134 /**
135  * @brief  Read Synchronous API callback.
136  * @return #CA_STATUS_OK on success otherwise proper error code.
137  * @retval #CA_STATUS_OK  Successful
138  * @retval #CA_STATUS_FAILED Operation failed
139  */
140 CAResult_t CAReadEDRData(void);
141
142 /**
143  * @brief  EDR Stops all RFCOMM servers and close sockets.
144  * @return #CA_STATUS_OK or Appropriate error code
145  */
146 CAResult_t CAStopEDR(void);
147
148 /**
149  * @brief  Terminate the EDR connectivity adapter.
150  * Configuration information will be deleted from further use.
151  * @return NONE
152  */
153 void CATerminateEDR(void);
154
155 #ifdef __cplusplus
156 } /* extern "C" */
157 #endif
158
159 #endif  /* CA_EDRADAPTER_SINGLETHREAD_H_ */
160