1 /* 2 * Copyright (c) 2023-2024 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup SoftBus 18 * @{ 19 * 20 * @brief Provides high-speed, secure communications between devices. 21 * 22 * This module implements unified distributed communication management of 23 * nearby devices, and provides link-independent device discovery and transmission interfaces 24 * to support service publishing and data transmission. 25 * 26 * @since 2.0 27 * @version 2.0 28 */ 29 30 /** 31 * @file socket.h 32 * 33 * @brief Declares unified data transmission interfaces. 34 * 35 * This file provides data transmission capabilities, including creating and removing a socket server, 36 * opening and closing sockets, receiving data, and querying basic socket information. \n 37 * You can use the interfaces to transmit data across the nearby devices that are discovered and networked. 38 * \n 39 * 40 * @since 2.0 41 * @version 2.0 42 */ 43 #ifndef SOCKET_H 44 #define SOCKET_H 45 46 #include <stdint.h> 47 #include <stdbool.h> 48 #include "trans_type.h" 49 50 #ifdef __cplusplus 51 extern "C" { 52 #endif 53 54 /** 55 * @brief Enumerates the QoS feedback types. 56 * 57 * @since 2.0 58 * @version 2.0 59 */ 60 typedef enum { 61 QOS_SATISFIED, /**< Feedback on satisfied quality */ 62 QOS_NOT_SATISFIED, /**< Feedback on not satisfied quality */ 63 } QoSEvent; 64 65 /** 66 * @brief Defines socket callbacks. 67 * 68 * When a socket is opened or closed, or there is data to process, the related callback is invoked. 69 * 70 * @since 2.0 71 * @version 2.0 72 */ 73 typedef struct { 74 /** 75 * @brief Called when a socket is bind. 76 * 77 * This callback is invoked to verify the socket or initialize resources related to the socket. 78 * When the connection is successful, this callback be called on the server side. 79 * The server side refers to the side that called {@Listen} function. 80 * 81 * When a socket is async bind, client side need implement this interface. 82 * 83 * @param socket Indicates the unique socket fd. 84 * @param info Indicates the information of peer socket. 85 * @since 2.0 86 * @version 2.0 87 */ 88 void (*OnBind)(int32_t socket, PeerSocketInfo info); 89 90 /** 91 * @brief Called when a socket is closed. 92 * 93 * This callback is invoked to release resources related to the socket. 94 * 95 * @param socket Indicates the unique socket fd. 96 * @param reason Indicates the reason for closing the socket. 97 * @since 2.0 98 * @version 2.0 99 */ 100 void (*OnShutdown)(int32_t socket, ShutdownReason reason); 101 102 /** 103 * @brief Called when bytes data is received. 104 * 105 * This callback is invoked to notify that data is received. 106 * 107 * @param socket Indicates the unique socket fd. 108 * @param data Indicates the pointer to the bytes data received. 109 * @param dataLen Indicates the length of the bytes data received. 110 * @since 2.0 111 * @version 2.0 112 */ 113 void (*OnBytes)(int32_t socket, const void *data, uint32_t dataLen); 114 115 /** 116 * @brief Called when message data is received. 117 * 118 * This callback is invoked to notify that message data is received. 119 * 120 * @param socket Indicates the unique socket fd. 121 * @param data Indicates the pointer to the message data received. 122 * @param dataLen Indicates the length of the message data received. 123 * @since 2.0 124 * @version 2.0 125 */ 126 void (*OnMessage)(int32_t socket, const void *data, uint32_t dataLen); 127 128 /** 129 * @brief Called when stream data is received. 130 * 131 * This callback is invoked to notify that stream data is received. 132 * 133 * @param socket Indicates the unique socket fd. 134 * @param data Indicates the pointer to the stream data received. 135 * @param ext Indicates the pointer to the extended service data received. 136 * @param param Indicates the pointer to the stream data frame information. 137 * @since 2.0 138 * @version 2.0 139 */ 140 void (*OnStream)(int32_t socket, const StreamData *data, const StreamData *ext, const StreamFrameInfo *param); 141 142 /** 143 * @brief Called when file data is received. 144 * 145 * This callback is invoked to notify that file data is received. 146 * 147 * @param socket Indicates the unique socket fd. 148 * @param event Indicates the file event. 149 * @param data Indicates the pointer to the file data received. 150 * @since 2.0 151 * @version 2.0 152 */ 153 void (*OnFile)(int32_t socket, FileEvent *event); 154 155 /** 156 * @brief Called when QoS state is changed. 157 * 158 * This callback is invoked to notify that QoS state is changed. 159 * 160 * @param socket Indicates the unique socket fd. 161 * @param event Indicates the type of QoS state change. 162 * @param qos Indicates the QoS status that we can provide. 163 * @param qosCount Indicates the number of the third parameter <b>qos</b>. 164 * @since 2.0 165 * @version 2.0 166 */ 167 void (*OnQos)(int32_t socket, QoSEvent eventId, const QosTV *qos, uint32_t qosCount); 168 169 /** 170 * @brief Called when an async bind socket is error. 171 * 172 * This callback is notice error for the socket. 173 * 174 * When a socket is async bind, client side need implement this interface. 175 * 176 * @param socket Indicates the unique socket fd. 177 * @param errCode Indicates the error for the async bind socket. 178 * @since 2.0 179 * @version 2.0 180 */ 181 void (*OnError)(int32_t socket, int32_t errCode); 182 183 /** 184 * @brief Called when a socket is negotiating. 185 * 186 * This callback is invoked to negotiating the socket, this callback be called on the server side. 187 * The server can determine whether to bind the socket based on the negotiation result. 188 * 189 * 190 * @param socket Indicates the unique socket fd. 191 * @param info Indicates the information of peer socket. 192 * @return If true is returned, it indicates that the negotiation is successful. If this method is not implemented, 193 * the negotiation is successful by default. if false is returned, the negotiation fails and the client is notified 194 * that the connection is rejected. 195 * @since 2.0 196 * @version 2.0 197 */ 198 bool (*OnNegotiate)(int32_t socket, PeerSocketInfo info); 199 } ISocketListener; 200 201 /** 202 * @brief Creates a socket. 203 * 204 * A maximum of 15 socket can be created. 205 * 206 * @param info Indicates the description of the socket structure. 207 * It is the unique identifier of the upper-layer service. The value cannot be empty or exceed 64 characters. 208 * 209 * @return Returns <b>socket fd</b> if the socket creation is successful; 210 * returns an error code less than zero otherwise. 211 * @since 2.0 212 * @version 2.0 213 */ 214 int32_t Socket(SocketInfo info); 215 216 /** 217 * @brief Listens a socket, which is called by server. 218 * 219 * @param socket Indicates the the unique socket fd. 220 * @param qos Indicates the QoS requirements for socket. The value cannot be empty. 221 * @param qosCount Indicates the number of the second parameter <b>qos</b>. 222 * @param listener Indicates the pointer to the socket callback. 223 * 224 * @return Returns <b>SOFTBUS_OK</b> if the listen creation is successful; 225 * returns an error code less than zero otherwise. 226 * @since 2.0 227 * @version 2.0 228 */ 229 int32_t Listen(int32_t socket, const QosTV qos[], uint32_t qosCount, const ISocketListener *listener); 230 231 /** 232 * @brief Binds a socket, which is called by client. 233 * 234 * When the connection is successful, this function return <b>SOFTBUS_OK</b> and 235 * {@link OnBind} be called on the server side. 236 * 237 * @param socket Indicates the the unique socket fd. 238 * @param qos Indicates the QoS requirements for socket. The value cannot be empty. 239 * @param qosCount Indicates the number of the second parameter <b>qos</b>. 240 * @param listener Indicates the pointer to the socket callback. 241 * 242 * @return Returns <b>SOFTBUS_TRANS_INVALID_PARAM</b> if invalid parameters are detected. 243 * @return Returns <b>INVALID_SOCKET</b> if the operation fails. 244 * @return Returns <b>SOFTBUS_OK</b> if the socket is bind; 245 * returns an error code otherwise. 246 * @since 2.0 247 * @version 2.0 248 */ 249 int32_t Bind(int32_t socket, const QosTV qos[], uint32_t qosCount, const ISocketListener *listener); 250 251 /** 252 * @brief Async bind a socket, which is called by client. 253 * 254 * {@link OnBind} is invoked to return whether the socket is successfully bind. 255 * Data can be transmitted only after the socket is successfully bind. 256 * 257 * @param socket Indicates the the unique socket fd. 258 * @param qos Indicates the QoS requirements for socket. The value cannot be empty. 259 * @param listener Indicates the pointer to the socket callback. 260 * 261 * @return Returns <b>SOFTBUS_TRANS_INVALID_PARAM</b> if invalid parameters are detected. 262 * @return Returns <b>INVALID_SOCKET</b> if the operation fails. 263 * @return Returns <b>SOFTBUS_OK</b>) if the socket is in binding status, 264 * returns an error code otherwise. 265 * @since 2.0 266 * @version 2.0 267 */ 268 int32_t BindAsync(int32_t socket, const QosTV qos[], uint32_t qosCount, const ISocketListener *listener); 269 270 /** 271 * @example sendbytes_message_demo.c 272 */ 273 274 /** 275 * @brief Sends bytes data. 276 * 277 * @param socket Indicates the unique socket fd. 278 * @param data Indicates the pointer to the bytes data to send, which cannot be <b>NULL</b>. 279 * @param len Indicates the length of the bytes data to send. 280 * 281 * @return Returns <b>SOFTBUS_INVALID_PARAM</b> if invalid parameters are detected. 282 * @return Returns <b>SOFTBUS_TRANS_SEND_LEN_BEYOND_LIMIT</b> if the bytes data exceeds the maximum limit. 283 * @return Returns <b>SOFTBUS_TRANS_INVALID_SOCKET</b> if <b>socket</b> is invalid. 284 * @return Returns <b>SOFTBUS_TRANS_SOCKET_NO_ENABLE</b> if the socket is not bind. 285 * @return Returns <b>SOFTBUS_OK</b> if the operation is successful; returns an error code otherwise. 286 * @since 2.0 287 * @version 2.0 288 */ 289 int32_t SendBytes(int32_t socket, const void *data, uint32_t len); 290 291 /** 292 * @brief Sends message data. 293 * 294 * @param socket Indicates the unique socket fd. 295 * @param data Indicates the pointer to the message data to send, which cannot be <b>NULL</b>. 296 * @param len Indicates the length of the message data to send. 297 * 298 * @return Returns <b>SOFTBUS_INVALID_PARAM</b> if <b>data</b> is <b>NULL</b> or <b>len</b> is zero. 299 * @return Returns <b>SOFTBUS_TRANS_SEND_LEN_BEYOND_LIMIT</b> if the message data length exceeds the limit. 300 * @return Returns <b>SOFTBUS_INVALID_SOCKET</b> if <b>socket</b> is invalid. 301 * @return Returns <b>SOFTBUS_TRANS_SOCKET_NO_ENABLE</b> if the socket is not bind. 302 * @return Returns <b>SOFTBUS_OK</b> if the operation is successful; returns an error code otherwise. 303 * @since 2.0 304 * @version 2.0 305 */ 306 int32_t SendMessage(int32_t socket, const void *data, uint32_t len); 307 308 /** 309 * @example sendstream_demo.c 310 */ 311 312 /** 313 * @brief Sends stream data. 314 * 315 * @param socket Indicates the unique socket fd. 316 * @param data Indicates the pointer to the stream data to send, which cannot be <b>NULL</b>. 317 * @param ext Indicates the pointer to the extended stream data to send, which cannot be <b>NULL</b>. 318 * @param param Indicates the pointer to the stream frame information, which cannot be <b>NULL</b>. 319 * 320 * @return Returns <b>SOFTBUS_INVALID_PARAM</b> if any of the input parameters is <b>NULL</b>. 321 * @return Returns <b>SOFTBUS_INVALID_SOCKET</b> if <b>socket</b> is invalid. 322 * @return Returns <b>SOFTBUS_TRANS_SOCKET_NO_ENABLE</b> if the socket is not bind. 323 * @return Returns <b>SOFTBUS_OK</b> if the operation is successful; returns an error code otherwise. 324 * @since 2.0 325 * @version 2.0 326 */ 327 int32_t SendStream(int32_t socket, const StreamData *data, const StreamData *ext, const StreamFrameInfo *param); 328 329 /** 330 * @example sendfile_demo.c 331 */ 332 333 /** 334 * @brief Sends files data. 335 * 336 * @param socket Indicates the unique socket fd. 337 * @param sFileList Indicates the pointer to the source files data to send, which cannot be <b>NULL</b>. 338 * @param dFileList Indicates the pointer to the destination files data, which cannot be <b>NULL</b>. 339 * @param fileCnt Indicates the number of files data to send, which cannot be <b>0</b>. 340 * 341 * @return Returns <b>SOFTBUS_INVALID_PARAM</b> if <b>sFileList</b> is <b>NULL</b> or <b>fileCnt</b> is <b>0</b>. 342 * @return Returns <b>SOFTBUS_INVALID_SOCKET</b> if <b>socket</b> is invalid. 343 * @return Returns <b>SOFTBUS_TRANS_SOCKET</b> if the socket is not bind. 344 * @return Returns <b>SOFTBUS_OK</b> if the operation is successful; returns an error code otherwise. 345 * @since 2.0 346 * @version 2.0 347 */ 348 int32_t SendFile(int32_t socket, const char *sFileList[], const char *dFileList[], uint32_t fileCnt); 349 350 /** 351 * @brief Get socket based on a socket fd. 352 * 353 * @param socket Indicates the unique socket fd. 354 * 355 * @return Returns no value. 356 * @since 2.0 357 * @version 2.0 358 */ 359 void Shutdown(int32_t socket); 360 361 /** 362 * @brief Evaluate quality of service. 363 * 364 * @param peerNetworkId Indicates the pointer to the remote device ID. 365 * @param dataType Indicates the type of data. 366 * @param qos Indicates the expected quality of service. 367 * @param qosCount Indicates the number of the fourth parameter <b>qos</b>. 368 * 369 * @return Returns no value. 370 * @since 2.0 371 * @version 2.0 372 */ 373 int32_t EvaluateQos(const char *peerNetworkId, TransDataType dataType, const QosTV *qos, uint32_t qosCount); 374 #ifdef __cplusplus 375 } 376 #endif 377 #endif // SOCKET_H 378