1 /* 2 * Copyright (c) 2023 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 "trans_type.h" 48 49 #ifdef __cplusplus 50 extern "C" { 51 #endif 52 53 /** 54 * @brief Enumerates the QoS feedback types. 55 * 56 * @since 2.0 57 * @version 2.0 58 */ 59 typedef enum { 60 QOS_SATISFIED, /**< Feedback on satisfied quality */ 61 QOS_NOT_SATISFIED, /**< Feedback on not satisfied quality */ 62 } QoSEvent; 63 64 /** 65 * @brief Defines socket callbacks. 66 * 67 * When a socket is opened or closed, or there is data to process, the related callback is invoked. 68 * 69 * @since 2.0 70 * @version 2.0 71 */ 72 typedef struct { 73 /** 74 * @brief Called when a socket is bind. 75 * 76 * This callback is invoked to verify the socket or initialize resources related to the socket. 77 * When the connection is successful, this callback be called on the server side. 78 * The server side refers to the side that called {@Listen} function. 79 * 80 * @param socket Indicates the unique socket fd. 81 * @param info Indicates the information of peer socket. 82 * @since 2.0 83 * @version 2.0 84 */ 85 void (*OnBind)(int32_t socket, PeerSocketInfo info); 86 87 /** 88 * @brief Called when a socket is closed. 89 * 90 * This callback is invoked to release resources related to the socket. 91 * 92 * @param socket Indicates the unique socket fd. 93 * @param reason Indicates the reason for closing the socket. 94 * @since 2.0 95 * @version 2.0 96 */ 97 void (*OnShutdown)(int32_t socket, ShutdownReason reason); 98 99 /** 100 * @brief Called when bytes data is received. 101 * 102 * This callback is invoked to notify that data is received. 103 * 104 * @param socket Indicates the unique socket fd. 105 * @param data Indicates the pointer to the bytes data received. 106 * @param dataLen Indicates the length of the bytes data received. 107 * @since 2.0 108 * @version 2.0 109 */ 110 void (*OnBytes)(int32_t socket, const void *data, uint32_t dataLen); 111 112 /** 113 * @brief Called when message data is received. 114 * 115 * This callback is invoked to notify that message data is received. 116 * 117 * @param socket Indicates the unique socket fd. 118 * @param data Indicates the pointer to the message data received. 119 * @param dataLen Indicates the length of the message data received. 120 * @since 2.0 121 * @version 2.0 122 */ 123 void (*OnMessage)(int32_t socket, const void *data, uint32_t dataLen); 124 125 /** 126 * @brief Called when stream data is received. 127 * 128 * This callback is invoked to notify that stream data is received. 129 * 130 * @param socket Indicates the unique socket fd. 131 * @param data Indicates the pointer to the stream data received. 132 * @param ext Indicates the pointer to the extended service data received. 133 * @param param Indicates the pointer to the stream data frame information. 134 * @since 2.0 135 * @version 2.0 136 */ 137 void (*OnStream)(int32_t socket, const StreamData *data, const StreamData *ext, const StreamFrameInfo *param); 138 139 /** 140 * @brief Called when file data is received. 141 * 142 * This callback is invoked to notify that file data is received. 143 * 144 * @param socket Indicates the unique socket fd. 145 * @param event Indicates the file event. 146 * @param data Indicates the pointer to the file data received. 147 * @since 2.0 148 * @version 2.0 149 */ 150 void (*OnFile)(int32_t socket, FileEvent *event); 151 152 /** 153 * @brief Called when QoS state is changed. 154 * 155 * This callback is invoked to notify that QoS state is changed. 156 * 157 * @param socket Indicates the unique socket fd. 158 * @param event Indicates the type of QoS state change. 159 * @param qos Indicates the QoS status that we can provide. 160 * @param qosCount Indicates the number of the third parameter <b>qos</b>. 161 * @since 2.0 162 * @version 2.0 163 */ 164 void (*OnQos)(int32_t socket, QoSEvent eventId, const QosTV *qos, uint32_t qosCount); 165 } ISocketListener; 166 167 /** 168 * @brief Creates a socket. 169 * 170 * A maximum of 15 socket can be created. 171 * 172 * @param info Indicates the description of the socket structure. 173 * It is the unique identifier of the upper-layer service. The value cannot be empty or exceed 64 characters. 174 * 175 * @return Returns <b>socket fd</b> if the socket creation is successful; 176 * returns an error code less than zero otherwise. 177 * @since 2.0 178 * @version 2.0 179 */ 180 int32_t Socket(SocketInfo info); 181 182 /** 183 * @brief Listens a socket, which is called by server. 184 * 185 * @param socket Indicates the the unique socket fd. 186 * @param qos Indicates the QoS requirements for socket. The value cannot be empty. 187 * @param qosCount Indicates the number of the second parameter <b>qos</b>. 188 * @param listener Indicates the pointer to the socket callback. 189 * 190 * @return Returns <b>SOFTBUS_OK</b> if the listen creation is successful; 191 * returns an error code less than zero otherwise. 192 * @since 2.0 193 * @version 2.0 194 */ 195 int32_t Listen(int32_t socket, const QosTV qos[], uint32_t qosCount, const ISocketListener *listener); 196 197 /** 198 * @brief Binds a socket, which is called by client. 199 * 200 * When the connection is successful, this function return <b>SOFTBUS_OK</b> and 201 * {@link OnBind} be called on the server side. 202 * 203 * @param socket Indicates the the unique socket fd. 204 * @param qos Indicates the QoS requirements for socket. The value cannot be empty. 205 * @param qosCount Indicates the number of the second parameter <b>qos</b>. 206 * @param listener Indicates the pointer to the socket callback. 207 * 208 * @return Returns <b>SOFTBUS_TRANS_INVALID_PARAM</b> if invalid parameters are detected. 209 * @return Returns <b>INVALID_SOCKET</b> if the operation fails. 210 * @return Returns <b>SOFTBUS_OK</b> if the socket is bind; 211 * returns an error code otherwise. 212 * @since 2.0 213 * @version 2.0 214 */ 215 int32_t Bind(int32_t socket, const QosTV qos[], uint32_t qosCount, const ISocketListener *listener); 216 217 /** 218 * @example sendbytes_message_demo.c 219 */ 220 221 /** 222 * @brief Sends bytes data. 223 * 224 * @param socket Indicates the unique socket fd. 225 * @param data Indicates the pointer to the bytes data to send, which cannot be <b>NULL</b>. 226 * @param len Indicates the length of the bytes data to send. 227 * 228 * @return Returns <b>SOFTBUS_INVALID_PARAM</b> if invalid parameters are detected. 229 * @return Returns <b>SOFTBUS_TRANS_SEND_LEN_BEYOND_LIMIT</b> if the bytes data exceeds the maximum limit. 230 * @return Returns <b>SOFTBUS_TRANS_INVALID_SOCKET</b> if <b>socket</b> is invalid. 231 * @return Returns <b>SOFTBUS_TRANS_SOCKET_NO_ENABLE</b> if the socket is not bind. 232 * @return Returns <b>SOFTBUS_OK</b> if the operation is successful; returns an error code otherwise. 233 * @since 2.0 234 * @version 2.0 235 */ 236 int32_t SendBytes(int32_t socket, const void *data, uint32_t len); 237 238 /** 239 * @brief Sends message data. 240 * 241 * @param socket Indicates the unique socket fd. 242 * @param data Indicates the pointer to the message data to send, which cannot be <b>NULL</b>. 243 * @param len Indicates the length of the message data to send. 244 * 245 * @return Returns <b>SOFTBUS_INVALID_PARAM</b> if <b>data</b> is <b>NULL</b> or <b>len</b> is zero. 246 * @return Returns <b>SOFTBUS_TRANS_SEND_LEN_BEYOND_LIMIT</b> if the message data length exceeds the limit. 247 * @return Returns <b>SOFTBUS_INVALID_SOCKET</b> if <b>socket</b> is invalid. 248 * @return Returns <b>SOFTBUS_TRANS_SOCKET_NO_ENABLE</b> if the socket is not bind. 249 * @return Returns <b>SOFTBUS_OK</b> if the operation is successful; returns an error code otherwise. 250 * @since 2.0 251 * @version 2.0 252 */ 253 int32_t SendMessage(int32_t socket, const void *data, uint32_t len); 254 255 /** 256 * @example sendstream_demo.c 257 */ 258 259 /** 260 * @brief Sends stream data. 261 * 262 * @param socket Indicates the unique socket fd. 263 * @param data Indicates the pointer to the stream data to send, which cannot be <b>NULL</b>. 264 * @param ext Indicates the pointer to the extended stream data to send, which cannot be <b>NULL</b>. 265 * @param param Indicates the pointer to the stream frame information, which cannot be <b>NULL</b>. 266 * 267 * @return Returns <b>SOFTBUS_INVALID_PARAM</b> if any of the input parameters is <b>NULL</b>. 268 * @return Returns <b>SOFTBUS_INVALID_SOCKET</b> if <b>socket</b> is invalid. 269 * @return Returns <b>SOFTBUS_TRANS_SOCKET_NO_ENABLE</b> if the socket is not bind. 270 * @return Returns <b>SOFTBUS_OK</b> if the operation is successful; returns an error code otherwise. 271 * @since 2.0 272 * @version 2.0 273 */ 274 int32_t SendStream(int32_t socket, const StreamData *data, const StreamData *ext, const StreamFrameInfo *param); 275 276 /** 277 * @example sendfile_demo.c 278 */ 279 280 /** 281 * @brief Sends files data. 282 * 283 * @param socket Indicates the unique socket fd. 284 * @param sFileList Indicates the pointer to the source files data to send, which cannot be <b>NULL</b>. 285 * @param dFileList Indicates the pointer to the destination files data, which cannot be <b>NULL</b>. 286 * @param fileCnt Indicates the number of files data to send, which cannot be <b>0</b>. 287 * 288 * @return Returns <b>SOFTBUS_INVALID_PARAM</b> if <b>sFileList</b> is <b>NULL</b> or <b>fileCnt</b> is <b>0</b>. 289 * @return Returns <b>SOFTBUS_INVALID_SOCKET</b> if <b>socket</b> is invalid. 290 * @return Returns <b>SOFTBUS_TRANS_SOCKET</b> if the socket is not bind. 291 * @return Returns <b>SOFTBUS_OK</b> if the operation is successful; returns an error code otherwise. 292 * @since 2.0 293 * @version 2.0 294 */ 295 int32_t SendFile(int32_t socket, const char *sFileList[], const char *dFileList[], uint32_t fileCnt); 296 297 /** 298 * @brief Get socket based on a socket fd. 299 * 300 * @param socket Indicates the unique socket fd. 301 * 302 * @return Returns no value. 303 * @since 2.0 304 * @version 2.0 305 */ 306 void Shutdown(int32_t socket); 307 308 /** 309 * @brief Evaluate quality of service. 310 * 311 * @param peerNetworkId Indicates the pointer to the remote device ID. 312 * @param dataType Indicates the type of data. 313 * @param qos Indicates the expected quality of service. 314 * @param qosCount Indicates the number of the fourth parameter <b>qos</b>. 315 * 316 * @return Returns no value. 317 * @since 2.0 318 * @version 2.0 319 */ 320 int32_t EvaluateQos(const char *peerNetworkId, TransDataType dataType, const QosTV *qos, uint32_t qosCount); 321 #ifdef __cplusplus 322 } 323 #endif 324 #endif // SOCKET_H 325