1 /* 2 * Copyright (c) 2022 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 communication between devices. 21 * 22 * This module implements unified distributed communication capability management between 23 * nearby devices, and provides link-independent device discovery and transmission interfaces 24 * to support service publishing and data transmission. 25 * 26 * @since 1.0 27 * @version 1.0 28 */ 29 30 /** 31 * @file session.h 32 * 33 * @brief Declares unified data transmission interfaces. 34 * 35 * This file provides data transmission capabilities, including creating and removing a session server, 36 * opening and closing sessions, receiving data, and querying basic session information. \n 37 * After multiple nearby devices are discovered and networked, these interfaces can be used to 38 * transmit data across devices. \n 39 * 40 * @since 1.0 41 * @version 1.0 42 */ 43 #ifndef SESSION_H 44 #define SESSION_H 45 46 #include <stdint.h> 47 #include <string> 48 #ifdef __cplusplus 49 extern "C" { 50 #endif 51 /** 52 * @brief bussiness type of session 53 * 54 * @since 1.0 55 * @version 1.0 56 */ 57 typedef enum { 58 TYPE_MESSAGE = 1, 59 TYPE_BYTES, 60 TYPE_FILE, 61 TYPE_STREAM, 62 TYPE_BUTT, 63 } SessionType; 64 65 typedef enum { 66 INVALID = -1, 67 /* 68 * Send any segment of a frame each time. 69 */ 70 RAW_STREAM, 71 /* 72 * Send a whole video frame each time. 73 */ 74 COMMON_VIDEO_STREAM, 75 /* 76 * Send a whole audio frame each time. 77 */ 78 COMMON_AUDIO_STREAM, 79 /* 80 * Slice frame mode. 81 */ 82 VIDEO_SLICE_STREAM, 83 } StreamType; 84 85 typedef enum { 86 LINK_TYPE_WIFI_WLAN_5G = 1, 87 LINK_TYPE_WIFI_WLAN_2G = 2, 88 LINK_TYPE_WIFI_P2P = 3, 89 LINK_TYPE_BR = 4, 90 LINK_TYPE_MAX = 4, 91 } LinkType; 92 93 /** 94 * @brief session attribute. 95 * 96 * control the attribute of session。 97 * 98 * @since 1.0 99 * @version 1.0 100 */ 101 typedef struct { 102 /** @brief dataType{@link SessionType} */ 103 int dataType; 104 int linkTypeNum; 105 LinkType linkType[LINK_TYPE_MAX]; 106 union { 107 struct StreamAttr { 108 int streamType; 109 } streamAttr; 110 } attr; 111 } SessionAttribute; 112 113 typedef struct { 114 char *buf; 115 int bufLen; 116 } StreamData; 117 118 typedef struct { 119 int type; 120 int64_t value; 121 } TV; 122 123 typedef struct { 124 int frameType; 125 int64_t timeStamp; 126 int seqNum; 127 int seqSubNum; 128 int level; 129 int bitMap; 130 int tvCount; 131 TV *tvList; 132 } FrameInfo; 133 134 /** 135 * @brief Defines session callbacks. 136 * 137 * When a session is opened or closed, or there is data to process, the related callback is invoked. 138 * 139 * @since 1.0 140 * @version 1.0 141 */ 142 typedef struct { 143 /** 144 * @brief Called when a session is opened. 145 * 146 * This function can be used to verify the session or initialize resources related to the session. 147 * 148 * @param sessionId Indicates the session ID. 149 * @param result 0 if the session is opened successfully, returns an error code otherwise. 150 * @return Returns <b>0</b> if the session connection is accepted; returns a non-zero value 151 * otherwise (you do not need to call {@link CloseSession} to close the session). 152 * @since 1.0 153 * @version 1.0 154 */ 155 int (*OnSessionOpened)(int sessionId, int result); 156 157 /** 158 * @brief Called when a session is closed. 159 * 160 * This function can be used to release resources related to the session. 161 * You do not need to call {@link CloseSession}. 162 * 163 * @param sessionId Indicates the session ID. 164 * @since 1.0 165 * @version 1.0 166 */ 167 void (*OnSessionClosed)(int sessionId); 168 169 /** 170 * @brief Called when data is received. 171 * 172 * This function is used to notify that data is received. 173 * 174 * @param sessionId Indicates the session ID. 175 * @param data Indicates the pointer to the data received. 176 * @param dataLen Indicates the length of the data received. 177 * @since 1.0 178 * @version 1.0 179 */ 180 void (*OnBytesReceived)(int sessionId, const void *data, unsigned int dataLen); 181 182 /** 183 * @brief Called when message is received. 184 * 185 * This function is used to notify that message is received. 186 * 187 * @param sessionId Indicates the session ID. 188 * @param data Indicates the pointer to the message data received. 189 * @param dataLen Indicates the length of the message received. 190 * @since 1.0 191 * @version 1.0 192 */ 193 void (*OnMessageReceived)(int sessionId, const void *data, unsigned int dataLen); 194 195 void (*OnStreamReceived)(int sessionId, const StreamData *data, const StreamData *ext, const FrameInfo *param); 196 } ISessionListener; 197 198 typedef struct { 199 int (*OnReceiveFileStarted)(int sessionId, const char *files, int fileCnt); 200 int (*OnReceiveFileProcess)(int sessionId, const char *firstFile, uint64_t bytesUpload, uint64_t bytesTotal); 201 void (*OnReceiveFileFinished)(int sessionId, const char *files, int fileCnt); 202 void (*OnFileTransError)(int sessionId); 203 } IFileReceiveListener; 204 205 typedef struct { 206 int (*OnSendFileProcess)(int sessionId, uint64_t bytesUpload, uint64_t bytesTotal); 207 int (*OnSendFileFinished)(int sessionId, const char *firstFile); 208 void (*OnFileTransError)(int sessionId); 209 } IFileSendListener; 210 211 /** 212 * @brief Creates a session server based on a package name and session name. 213 * 214 * A maximum of 18 session servers can be created. 215 * 216 * @param pkgName Indicates the pointer to the package name, which can be used to check whether the 217 * session server is in this package. The value cannot be empty and can contain a maximum of 64 characters. 218 * @param sessionName Indicates the pointer to the session name, which is the unique ID of the session server. 219 * The value cannot be empty and can contain a maximum of 64 characters. 220 * @param listener Indicates the pointer to the session callback structure, which cannot be empty. 221 * @return Returns <b>0</b> if the operation is successful; returns <b>-1</b> otherwise. 222 * @see RemoveSessionServer 223 * @since 1.0 224 * @version 1.0 225 */ 226 int CreateSessionServer(const char *pkgName, const char *sessionName, const ISessionListener *listener); 227 228 /** 229 * @brief Removes a session server based on a package name and session name. 230 * 231 * @param pkgName Indicates the pointer to the name of the registered package, which can be used to check 232 * whether the session server is in this package. The value cannot be empty and can contain a maximum of 64 characters. 233 * @param sessionName Indicates the pointer to the session name. The value cannot be empty and can contain 234 * a maximum of 64 characters. 235 * @return Returns <b>0</b> if the operation is successful, returns <b>-1</b> otherwise. 236 * @see CreateSessionServer 237 * @since 1.0 238 * @version 1.0 239 */ 240 int RemoveSessionServer(const char *pkgName, const char *sessionName); 241 242 /** 243 * @brief Initiate a session open request, which is an asynchronous process. 244 * 245 * The session connection is opened based on the service name to trigger the first packet interaction process. 246 * According to the {@link OnSessionOpened} Notify the user whether the session is successfully opened. 247 * Data can be transmitted only after the session is successfully opened. 248 * 249 * @param mySessionName local session name. 250 * @param peerSessionName remote session name. 251 * @param peerDeviceId remote device id. 252 * @param groupId group id. 253 * @param attr session attribute {@link SessionAttribute}. 254 * @return return sessionId if the session is opened successfully, returns an error code otherwise. 255 * @since 1.0 256 * @version 1.0 257 */ 258 int OpenSession(const char *mySessionName, const char *peerSessionName, const char *peerDeviceId, const char *groupId, 259 const SessionAttribute *attr); 260 261 /** 262 * @brief Closes a connected session based on a session ID. 263 * 264 * @param sessionId Indicates the session ID. 265 * @return no return value. 266 * @since 1.0 267 * @version 1.0 268 */ 269 void CloseSession(int sessionId); 270 271 /** 272 * @brief Sends data based on a session ID. 273 * 274 * @param sessionId Indicates the session ID. 275 * @param data Indicates the pointer to the data to send, which cannot be <b>NULL</b>. 276 * @param len Indicates the length of the data to send. The maximum length cannot exceed 984 characters. 277 * @return Returns <b>0</b> if the function is called successfully; returns <b>-1</b> otherwise. 278 * @since 1.0 279 * @version 1.0 280 */ 281 int SendBytes(int sessionId, const void *data, unsigned int len); 282 283 /** 284 * @brief Sends message based on a session ID. 285 * 286 * @param sessionId Indicates the session ID. 287 * @param data Indicates the pointer to the message data to send, which cannot be <b>NULL</b>. 288 * @param len Indicates the length of the message to send. 289 * @return Returns <b>0</b> if the function is called successfully, returns an error code otherwise. 290 * @since 1.0 291 * @version 1.0 292 */ 293 int SendMessage(int sessionId, const void *data, unsigned int len); 294 295 int SendStream(int sessionId, const StreamData *data, const StreamData *ext, const FrameInfo *param); 296 297 /** 298 * @brief Obtains the session name registered by the local device based on the session ID. 299 * 300 * @param sessionId Indicates the session ID. 301 * @param sessionName Indicates the pointer to the buffer for storing the session name. 302 * @param len Indicates the length of the buffer. 303 * @return Returns <b>0</b> if the operation is successful; returns <b>-1</b> otherwise. 304 * @since 1.0 305 * @version 1.0 306 */ 307 int GetMySessionName(int sessionId, char *sessionName, unsigned int len); 308 309 /** 310 * @brief Obtains the session name registered by the peer device based on the session ID. 311 * 312 * @param sessionId Indicates the session ID. 313 * @param sessionName Indicates the pointer to the buffer for storing the session name. 314 * @param len Indicates the length of the buffer. 315 * @return Returns <b>0</b> if the operation is successful; returns <b>-1</b> otherwise. 316 * @since 1.0 317 * @version 1.0 318 */ 319 int GetPeerSessionName(int sessionId, char *sessionName, unsigned int len); 320 321 /** 322 * @brief Obtains the peer device ID based on a session ID. 323 * 324 * @param sessionId Indicates the session ID. 325 * @param devId Indicates the pointer to the buffer for storing the device ID. 326 * @param len Indicates the length of the buffer. 327 * @return Returns <b>0</b> if the operation is successful; returns <b>-1</b> otherwise. 328 * @since 1.0 329 * @version 1.0 330 */ 331 int GetPeerDeviceId(int sessionId, char *devId, unsigned int len); 332 333 int GetSessionSide(int sessionId); 334 335 int SetFileReceiveListener(const char *pkgName, const char *sessionName, const IFileReceiveListener *recvListener, 336 const char *rootDir); 337 338 int SetFileSendListener(const char *pkgName, const char *sessionName, const IFileSendListener *sendListener); 339 340 int SendFile(int sessionId, const char *sFileList[], const char *dFileList[], uint32_t fileCnt); 341 342 void DecompressMock(const unsigned char *bytes, const int length); 343 344 345 #ifdef __cplusplus 346 } 347 348 void CompressMock(const std::string &json, const unsigned char *compressedBytes, int &compressedLength); 349 std::string GetUuidMock(); 350 bool GetSendMessFlagMock(); 351 void ResetSendMessFlagMock(); 352 void ResetUuidMock(); 353 354 #endif 355 #endif // SESSION_H 356