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