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 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 } ISocketListener; 214 215 /** 216 * @brief Creates a socket. 217 * 218 * A maximum of 15 socket can be created. 219 * 220 * @param info Indicates the description of the socket structure. 221 * It is the unique identifier of the upper-layer service. The value cannot be empty or exceed 64 characters. 222 * 223 * @return Returns <b>socket fd</b> if the socket creation is successful; 224 * returns an error code less than zero otherwise. 225 * @since 2.0 226 * @version 2.0 227 */ 228 int32_t Socket(SocketInfo info); 229 230 /** 231 * @brief Listens a socket, which is called by server. 232 * 233 * @param socket Indicates the the unique socket fd. 234 * @param qos Indicates the QoS requirements for socket. The value cannot be empty. 235 * @param qosCount Indicates the number of the second parameter <b>qos</b>. 236 * @param listener Indicates the pointer to the socket callback. 237 * 238 * @return Returns <b>SOFTBUS_OK</b> if the listen creation is successful; 239 * returns an error code less than zero otherwise. 240 * @since 2.0 241 * @version 2.0 242 */ 243 int32_t Listen(int32_t socket, const QosTV qos[], uint32_t qosCount, const ISocketListener *listener); 244 245 /** 246 * @brief Binds a socket, which is called by client. 247 * 248 * When the connection is successful, this function return <b>SOFTBUS_OK</b> and 249 * {@link OnBind} be called on the server side. 250 * 251 * @param socket Indicates the the unique socket fd. 252 * @param qos Indicates the QoS requirements for socket. The value cannot be empty. 253 * @param qosCount Indicates the number of the second parameter <b>qos</b>. 254 * @param listener Indicates the pointer to the socket callback. 255 * 256 * @return Returns <b>SOFTBUS_TRANS_INVALID_PARAM</b> if invalid parameters are detected. 257 * @return Returns <b>INVALID_SOCKET</b> if the operation fails. 258 * @return Returns <b>SOFTBUS_OK</b> if the socket is bind; 259 * returns an error code otherwise. 260 * @since 2.0 261 * @version 2.0 262 */ 263 int32_t Bind(int32_t socket, const QosTV qos[], uint32_t qosCount, const ISocketListener *listener); 264 265 /** 266 * @brief Async bind a socket, which is called by client. 267 * 268 * {@link OnBind} is invoked to return whether the socket is successfully bind. 269 * Data can be transmitted only after the socket is successfully bind. 270 * 271 * @param socket Indicates the the unique socket fd. 272 * @param qos Indicates the QoS requirements for socket. The value cannot be empty. 273 * @param listener Indicates the pointer to the socket callback. 274 * 275 * @return Returns <b>SOFTBUS_TRANS_INVALID_PARAM</b> if invalid parameters are detected. 276 * @return Returns <b>INVALID_SOCKET</b> if the operation fails. 277 * @return Returns <b>SOFTBUS_OK</b>) if the socket is in binding status, 278 * returns an error code otherwise. 279 * @since 2.0 280 * @version 2.0 281 */ 282 int32_t BindAsync(int32_t socket, const QosTV qos[], uint32_t qosCount, const ISocketListener *listener); 283 284 /** 285 * @example sendbytes_message_demo.c 286 */ 287 288 /** 289 * @brief Sends bytes data. 290 * 291 * @param socket Indicates the unique socket fd. 292 * @param data Indicates the pointer to the bytes data to send, which cannot be <b>NULL</b>. 293 * @param len Indicates the length of the bytes data to send. 294 * 295 * @return Returns <b>SOFTBUS_INVALID_PARAM</b> if invalid parameters are detected. 296 * @return Returns <b>SOFTBUS_TRANS_SEND_LEN_BEYOND_LIMIT</b> if the bytes data exceeds the maximum limit. 297 * @return Returns <b>SOFTBUS_TRANS_INVALID_SOCKET</b> if <b>socket</b> is invalid. 298 * @return Returns <b>SOFTBUS_TRANS_SOCKET_NO_ENABLE</b> if the socket is not bind. 299 * @return Returns <b>SOFTBUS_OK</b> if the operation is successful; returns an error code otherwise. 300 * @since 2.0 301 * @version 2.0 302 */ 303 int32_t SendBytes(int32_t socket, const void *data, uint32_t len); 304 305 /** 306 * @brief Async Sends bytes data. 307 * 308 * @param socket Indicates the unique socket fd. 309 * @param dataSeq Indicates the unique seq number of the packet to be send. which cannot be zero. 310 * @param data Indicates the pointer to the bytes data to send, which cannot be <b>NULL</b>. 311 * @param len Indicates the length of the bytes data to send. 312 * 313 * @return Returns <b>SOFTBUS_INVALID_PARAM</b> if invalid parameters are detected. 314 * @return Returns <b>SOFTBUS_TRANS_SEND_LEN_BEYOND_LIMIT</b> if the bytes data exceeds the maximum limit. 315 * @return Returns <b>SOFTBUS_TRANS_INVALID_SOCKET</b> if <b>socket</b> is invalid. 316 * @return Returns <b>SOFTBUS_TRANS_SOCKET_NO_ENABLE</b> if the socket is not bind. 317 * @return Returns <b>SOFTBUS_OK</b> if the operation is successful; returns an error code otherwise. 318 * @since 2.0 319 * @version 2.0 320 */ 321 int32_t SendBytesAsync(int32_t socket, uint32_t dataSeq, const void *data, uint32_t len); 322 323 /** 324 * @brief Sends message data. 325 * 326 * @param socket Indicates the unique socket fd. 327 * @param data Indicates the pointer to the message data to send, which cannot be <b>NULL</b>. 328 * @param len Indicates the length of the message data to send. 329 * 330 * @return Returns <b>SOFTBUS_INVALID_PARAM</b> if <b>data</b> is <b>NULL</b> or <b>len</b> is zero. 331 * @return Returns <b>SOFTBUS_TRANS_SEND_LEN_BEYOND_LIMIT</b> if the message data length exceeds the limit. 332 * @return Returns <b>SOFTBUS_INVALID_SOCKET</b> if <b>socket</b> is invalid. 333 * @return Returns <b>SOFTBUS_TRANS_SOCKET_NO_ENABLE</b> if the socket is not bind. 334 * @return Returns <b>SOFTBUS_OK</b> if the operation is successful; returns an error code otherwise. 335 * @since 2.0 336 * @version 2.0 337 */ 338 int32_t SendMessage(int32_t socket, const void *data, uint32_t len); 339 340 /** 341 * @example sendstream_demo.c 342 */ 343 344 /** 345 * @brief Sends stream data. 346 * 347 * @param socket Indicates the unique socket fd. 348 * @param data Indicates the pointer to the stream data to send, which cannot be <b>NULL</b>. 349 * @param ext Indicates the pointer to the extended stream data to send, which cannot be <b>NULL</b>. 350 * @param param Indicates the pointer to the stream frame information, which cannot be <b>NULL</b>. 351 * 352 * @return Returns <b>SOFTBUS_INVALID_PARAM</b> if any of the input parameters is <b>NULL</b>. 353 * @return Returns <b>SOFTBUS_INVALID_SOCKET</b> if <b>socket</b> is invalid. 354 * @return Returns <b>SOFTBUS_TRANS_SOCKET_NO_ENABLE</b> if the socket is not bind. 355 * @return Returns <b>SOFTBUS_OK</b> if the operation is successful; returns an error code otherwise. 356 * @since 2.0 357 * @version 2.0 358 */ 359 int32_t SendStream(int32_t socket, const StreamData *data, const StreamData *ext, const StreamFrameInfo *param); 360 361 /** 362 * @example sendfile_demo.c 363 */ 364 365 /** 366 * @brief Sends files data. 367 * 368 * @param socket Indicates the unique socket fd. 369 * @param sFileList Indicates the pointer to the source files data to send, which cannot be <b>NULL</b>. 370 * @param dFileList Indicates the pointer to the destination files data, which cannot be <b>NULL</b>. 371 * @param fileCnt Indicates the number of files data to send, which cannot be <b>0</b>. 372 * 373 * @return Returns <b>SOFTBUS_INVALID_PARAM</b> if <b>sFileList</b> is <b>NULL</b> or <b>fileCnt</b> is <b>0</b>. 374 * @return Returns <b>SOFTBUS_INVALID_SOCKET</b> if <b>socket</b> is invalid. 375 * @return Returns <b>SOFTBUS_TRANS_SOCKET</b> if the socket is not bind. 376 * @return Returns <b>SOFTBUS_OK</b> if the operation is successful; returns an error code otherwise. 377 * @since 2.0 378 * @version 2.0 379 */ 380 int32_t SendFile(int32_t socket, const char *sFileList[], const char *dFileList[], uint32_t fileCnt); 381 382 /** 383 * @brief Get socket based on a socket fd. 384 * 385 * @param socket Indicates the unique socket fd. 386 * 387 * @return Returns no value. 388 * @since 2.0 389 * @version 2.0 390 */ 391 void Shutdown(int32_t socket); 392 393 /** 394 * @brief Evaluate quality of service. 395 * 396 * @param peerNetworkId Indicates the pointer to the remote device ID. 397 * @param dataType Indicates the type of data. 398 * @param qos Indicates the expected quality of service. 399 * @param qosCount Indicates the number of the fourth parameter <b>qos</b>. 400 * 401 * @return Returns no value. 402 * @since 2.0 403 * @version 2.0 404 */ 405 int32_t EvaluateQos(const char *peerNetworkId, TransDataType dataType, const QosTV *qos, uint32_t qosCount); 406 #ifdef __cplusplus 407 } 408 #endif 409 #endif // SOCKET_H 410