1 /* 2 * Copyright (c) 2023-2025 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 200 /** 201 * @brief Registration during Bind link establishment. 202 * 203 * This callback is invoked to notify that data is received. 204 * 205 * 206 * @param socket Indicates the unique socket fd. 207 * @param dataSeq Indicates the sequence number of the packet to be sent. 208 * @param errCode Indicates the error for the async bind socket. 209 * @since 2.0 210 * @version 2.0 211 */ 212 void (*OnBytesSent)(int32_t socket, uint32_t dataSeq, int32_t errCode); 213 214 /** 215 * @brief Called when a socket needs to check the access. 216 * 217 * @param socket Indicates the unique socket fd. 218 * @param info Indicates the information of peer socket. 219 * @param peerInfo Indicates the access information of peer socket. 220 * @param localInfo Indicates the access information of local socket. server side should set userId and tokenId. 221 * @return If true is returned, it indicates that the access is successful. 222 * If this method is not implemented, the negotiation is successful by default. 223 * If false is returned, access check fails and the app cannot establish a link. 224 * @since 2.0 225 * @version 2.0 226 */ 227 bool (*OnNegotiate2)(int32_t socket, PeerSocketInfo info, SocketAccessInfo *peerInfo, SocketAccessInfo *localInfo); 228 229 /** 230 * @brief Registration during Bind link establishment. 231 * 232 * This callback is invoked to notify that message is received. 233 * 234 * @param socket Indicates the unique socket fd. 235 * @param dataSeq Indicates the sequence number of the packet to be sent. 236 * @param errCode Indicates the error for the async bind socket. 237 * @since 2.0 238 * @version 2.0 239 */ 240 void (*OnMessageSent)(int32_t socket, uint16_t dataSeq, int32_t errCode); 241 } ISocketListener; 242 243 /** 244 * @brief Creates a socket. 245 * 246 * A maximum of 15 socket can be created. 247 * 248 * @param info Indicates the description of the socket structure. 249 * It is the unique identifier of the upper-layer service. The value cannot be empty or exceed 64 characters. 250 * 251 * @return Returns <b>socket fd</b> if the socket creation is successful; 252 * returns an error code less than zero otherwise. 253 * @since 2.0 254 * @version 2.0 255 */ 256 int32_t Socket(SocketInfo info); 257 258 /** 259 * @brief Listens a socket, which is called by server. 260 * 261 * @param socket Indicates the the unique socket fd. 262 * @param qos Indicates the QoS requirements for socket. The value cannot be empty. 263 * @param qosCount Indicates the number of the second parameter <b>qos</b>. 264 * @param listener Indicates the pointer to the socket callback. 265 * 266 * @return Returns <b>SOFTBUS_OK</b> if the listen creation is successful; 267 * returns an error code less than zero otherwise. 268 * @since 2.0 269 * @version 2.0 270 */ 271 int32_t Listen(int32_t socket, const QosTV qos[], uint32_t qosCount, const ISocketListener *listener); 272 273 /** 274 * @brief Binds a socket, which is called by client. 275 * 276 * When the connection is successful, this function return <b>SOFTBUS_OK</b> and 277 * {@link OnBind} be called on the server side. 278 * 279 * @param socket Indicates the the unique socket fd. 280 * @param qos Indicates the QoS requirements for socket. The value cannot be empty. 281 * @param qosCount Indicates the number of the second parameter <b>qos</b>. 282 * @param listener Indicates the pointer to the socket callback. 283 * 284 * @return Returns <b>SOFTBUS_TRANS_INVALID_PARAM</b> if invalid parameters are detected. 285 * @return Returns <b>INVALID_SOCKET</b> if the operation fails. 286 * @return Returns <b>SOFTBUS_OK</b> if the socket is bind; 287 * returns an error code otherwise. 288 * @since 2.0 289 * @version 2.0 290 */ 291 int32_t Bind(int32_t socket, const QosTV qos[], uint32_t qosCount, const ISocketListener *listener); 292 293 /** 294 * @brief Async bind a socket, which is called by client. 295 * 296 * {@link OnBind} is invoked to return whether the socket is successfully bind. 297 * Data can be transmitted only after the socket is successfully bind. 298 * 299 * @param socket Indicates the the unique socket fd. 300 * @param qos Indicates the QoS requirements for socket. The value cannot be empty. 301 * @param listener Indicates the pointer to the socket callback. 302 * 303 * @return Returns <b>SOFTBUS_TRANS_INVALID_PARAM</b> if invalid parameters are detected. 304 * @return Returns <b>INVALID_SOCKET</b> if the operation fails. 305 * @return Returns <b>SOFTBUS_OK</b>) if the socket is in binding status, 306 * returns an error code otherwise. 307 * @since 2.0 308 * @version 2.0 309 */ 310 int32_t BindAsync(int32_t socket, const QosTV qos[], uint32_t qosCount, const ISocketListener *listener); 311 312 /** 313 * @example sendbytes_message_demo.c 314 */ 315 316 /** 317 * @brief Sends bytes data. 318 * 319 * @param socket Indicates the unique socket fd. 320 * @param data Indicates the pointer to the bytes data to send, which cannot be <b>NULL</b>. 321 * @param len Indicates the length of the bytes data to send. 322 * 323 * @return Returns <b>SOFTBUS_INVALID_PARAM</b> if invalid parameters are detected. 324 * @return Returns <b>SOFTBUS_TRANS_SEND_LEN_BEYOND_LIMIT</b> if the bytes data exceeds the maximum limit. 325 * @return Returns <b>SOFTBUS_TRANS_INVALID_SOCKET</b> if <b>socket</b> is invalid. 326 * @return Returns <b>SOFTBUS_TRANS_SOCKET_NO_ENABLE</b> if the socket is not bind. 327 * @return Returns <b>SOFTBUS_OK</b> if the operation is successful; returns an error code otherwise. 328 * @since 2.0 329 * @version 2.0 330 */ 331 int32_t SendBytes(int32_t socket, const void *data, uint32_t len); 332 333 /** 334 * @brief Async Sends bytes data. 335 * 336 * @param socket Indicates the unique socket fd. 337 * @param dataSeq Indicates the unique seq number of the packet to be send. which cannot be zero. 338 * @param data Indicates the pointer to the bytes data to send, which cannot be <b>NULL</b>. 339 * @param len Indicates the length of the bytes data to send. 340 * 341 * @return Returns <b>SOFTBUS_INVALID_PARAM</b> if invalid parameters are detected. 342 * @return Returns <b>SOFTBUS_TRANS_SEND_LEN_BEYOND_LIMIT</b> if the bytes data exceeds the maximum limit. 343 * @return Returns <b>SOFTBUS_TRANS_INVALID_SOCKET</b> if <b>socket</b> is invalid. 344 * @return Returns <b>SOFTBUS_TRANS_SOCKET_NO_ENABLE</b> if the socket is not bind. 345 * @return Returns <b>SOFTBUS_OK</b> if the operation is successful; returns an error code otherwise. 346 * @since 2.0 347 * @version 2.0 348 */ 349 int32_t SendBytesAsync(int32_t socket, uint32_t dataSeq, const void *data, uint32_t len); 350 351 /** 352 * @brief Sends message data. 353 * 354 * @param socket Indicates the unique socket fd. 355 * @param data Indicates the pointer to the message data to send, which cannot be <b>NULL</b>. 356 * @param len Indicates the length of the message data to send. 357 * 358 * @return Returns <b>SOFTBUS_INVALID_PARAM</b> if <b>data</b> is <b>NULL</b> or <b>len</b> is zero. 359 * @return Returns <b>SOFTBUS_TRANS_SEND_LEN_BEYOND_LIMIT</b> if the message data length exceeds the limit. 360 * @return Returns <b>SOFTBUS_INVALID_SOCKET</b> if <b>socket</b> is invalid. 361 * @return Returns <b>SOFTBUS_TRANS_SOCKET_NO_ENABLE</b> if the socket is not bind. 362 * @return Returns <b>SOFTBUS_OK</b> if the operation is successful; returns an error code otherwise. 363 * @since 2.0 364 * @version 2.0 365 */ 366 int32_t SendMessage(int32_t socket, const void *data, uint32_t len); 367 368 /** 369 * @brief Async Sends message data. 370 * 371 * @param socket Indicates the unique socket fd. 372 * @param dataSeq Indicates the unique seq number of the packet to be send. which cannot be zero. 373 * @param data Indicates the pointer to the bytes data to send, which cannot be <b>NULL</b>. 374 * @param len Indicates the length of the bytes data to send. 375 * 376 * @return Returns <b>SOFTBUS_INVALID_PARAM</b> if invalid parameters are detected. 377 * @return Returns <b>SOFTBUS_TRANS_SEND_LEN_BEYOND_LIMIT</b> if the bytes data exceeds the maximum limit. 378 * @return Returns <b>SOFTBUS_TRANS_INVALID_SOCKET</b> if <b>socket</b> is invalid. 379 * @return Returns <b>SOFTBUS_TRANS_SOCKET_NO_ENABLE</b> if the socket is not bind. 380 * @return Returns <b>SOFTBUS_OK</b> if the operation is successful; returns an error code otherwise. 381 * @since 2.0 382 * @version 2.0 383 */ 384 int32_t SendMessageAsync(int32_t socket, uint16_t dataSeq, const void *data, uint32_t dataLen); 385 386 /** 387 * @example sendstream_demo.c 388 */ 389 390 /** 391 * @brief Sends stream data. 392 * 393 * @param socket Indicates the unique socket fd. 394 * @param data Indicates the pointer to the stream data to send, which cannot be <b>NULL</b>. 395 * @param ext Indicates the pointer to the extended stream data to send, which cannot be <b>NULL</b>. 396 * @param param Indicates the pointer to the stream frame information, which cannot be <b>NULL</b>. 397 * 398 * @return Returns <b>SOFTBUS_INVALID_PARAM</b> if any of the input parameters is <b>NULL</b>. 399 * @return Returns <b>SOFTBUS_INVALID_SOCKET</b> if <b>socket</b> is invalid. 400 * @return Returns <b>SOFTBUS_TRANS_SOCKET_NO_ENABLE</b> if the socket is not bind. 401 * @return Returns <b>SOFTBUS_OK</b> if the operation is successful; returns an error code otherwise. 402 * @since 2.0 403 * @version 2.0 404 */ 405 int32_t SendStream(int32_t socket, const StreamData *data, const StreamData *ext, const StreamFrameInfo *param); 406 407 /** 408 * @example sendfile_demo.c 409 */ 410 411 /** 412 * @brief Sends files data. 413 * 414 * @param socket Indicates the unique socket fd. 415 * @param sFileList Indicates the pointer to the source files data to send, which cannot be <b>NULL</b>. 416 * @param dFileList Indicates the pointer to the destination files data, which cannot be <b>NULL</b>. 417 * @param fileCnt Indicates the number of files data to send, which cannot be <b>0</b>. 418 * 419 * @return Returns <b>SOFTBUS_INVALID_PARAM</b> if <b>sFileList</b> is <b>NULL</b> or <b>fileCnt</b> is <b>0</b>. 420 * @return Returns <b>SOFTBUS_INVALID_SOCKET</b> if <b>socket</b> is invalid. 421 * @return Returns <b>SOFTBUS_TRANS_SOCKET</b> if the socket is not bind. 422 * @return Returns <b>SOFTBUS_OK</b> if the operation is successful; returns an error code otherwise. 423 * @since 2.0 424 * @version 2.0 425 */ 426 int32_t SendFile(int32_t socket, const char *sFileList[], const char *dFileList[], uint32_t fileCnt); 427 428 /** 429 * @brief Get socket based on a socket fd. 430 * 431 * @param socket Indicates the unique socket fd. 432 * 433 * @return Returns no value. 434 * @since 2.0 435 * @version 2.0 436 */ 437 void Shutdown(int32_t socket); 438 439 /** 440 * @brief Evaluate quality of service. 441 * 442 * @param peerNetworkId Indicates the pointer to the remote device ID. 443 * @param dataType Indicates the type of data. 444 * @param qos Indicates the expected quality of service. 445 * @param qosCount Indicates the number of the fourth parameter <b>qos</b>. 446 * 447 * @return Returns no value. 448 * @since 2.0 449 * @version 2.0 450 */ 451 int32_t EvaluateQos(const char *peerNetworkId, TransDataType dataType, const QosTV *qos, uint32_t qosCount); 452 453 /** 454 * @brief Set socket access information of service. 455 * 456 * @param socket Indicates the unique socket fd. 457 * @param accessInfo Indicates the socket access information. 458 * 459 * @return Returns no value. 460 * @since 2.0 461 * @version 2.0 462 */ 463 int32_t SetAccessInfo(int32_t socket, SocketAccessInfo accessInfo); 464 #ifdef __cplusplus 465 } 466 #endif 467 #endif // SOCKET_H 468