1 /* 2 * Copyright (c) 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 Pasteboard 18 * @{ 19 * 20 * @brief Provides the copy and paste support for the system Pasteboard. 21 * You can use the APIs of this module to operate the Pasteboard content of the plain text, HTML, 22 * URI, Want, pixel map, and other types. 23 * 24 * @since 13 25 */ 26 27 /** 28 * @file OH_Pasteboard.h 29 * 30 * @brief Provides APIs and enums of the Pasteboard module. 31 * 32 * @kit BasicServicesKit 33 * @library libpasteboard.so 34 * @syscap SystemCapability.MiscServices.Pasteboard 35 * 36 * @since 13 37 */ 38 39 #ifndef OH_PASTEBOARD_H 40 #define OH_PASTEBOARD_H 41 42 #include <inttypes.h> 43 #include <stdbool.h> 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 /** 50 * @brief Introduces the UDMF data defined by ArkData Kit. 51 * 52 * @since 13 53 */ 54 struct OH_UdmfData; 55 56 /** 57 * @brief Enumerates the types of data changes that can be observed. 58 * 59 * @since 13 60 */ 61 typedef enum Pasteboard_NotifyType { 62 /** 63 * @brief Change of the Pasteboard data in the local device. 64 */ 65 NOTIFY_LOCAL_DATA_CHANGE = 1, 66 /** 67 * @brief Change of the Pasteboard data in the remote devices. 68 */ 69 NOTIFY_REMOTE_DATA_CHANGE = 2 70 } Pasteboard_NotifyType; 71 72 /** 73 * @brief Enumerates the types of file confilct options when getting data from the Pastedboard. 74 * 75 * @since 15 76 */ 77 typedef enum Pasteboard_FileConflictOptions { 78 /** 79 * @brief Overwrite when destUir has file with same name. 80 */ 81 PASTEBOARD_OVERWRITE = 0, 82 /** 83 * @brief Skip when destUir has file with same name. 84 */ 85 PASTEBOARD_SKIP = 1 86 } Pasteboard_FileConflictOptions; 87 88 /** 89 * @brief Enumerates the types of progress indicator when getting data from the Pastedboard. 90 * 91 * @since 15 92 */ 93 typedef enum Pasteboard_ProgressIndicator { 94 /** 95 * @brief Getting data without system default progress indicator. 96 */ 97 PASTEBOARD_NONE = 0, 98 /** 99 * @brief Getting data with system default progress indicator. 100 */ 101 PASTEBOARD_DEFAULT = 1 102 } Pasteboard_ProgressIndicator; 103 104 /** 105 * @brief Represents the Pasteboard progress information. 106 * 107 * @since 15 108 */ 109 typedef struct Pasteboard_ProgressInfo Pasteboard_ProgressInfo; 110 111 /** 112 * @brief Defines the callback function used to return the progress information when getting PasteData. 113 * 114 * @param progressInfo The progress information notified to Application. 115 * @since 15 116 */ 117 typedef void (*OH_Pasteboard_ProgressListener)(Pasteboard_ProgressInfo* progressInfo); 118 119 /** 120 * @brief Represents the pasteboard get data parameters when getting data from Pasteboard. 121 * 122 * @since 15 123 */ 124 typedef struct Pasteboard_GetDataParams Pasteboard_GetDataParams; 125 126 /** 127 * @brief Defines the callback function used to return the Pasteboard data changed. 128 * 129 * @param context The context set by {@link OH_PasteboardObserver_SetData} function. 130 * @param type The types of data changes. For details, see {@link Pasteboard_NotifyType}. 131 * @since 13 132 */ 133 typedef void (*Pasteboard_Notify)(void* context, Pasteboard_NotifyType type); 134 135 /** 136 * @brief Defines the callback function used free the context. 137 * @param context Pointer to the context which is to be free. 138 * @since 13 139 */ 140 typedef void (*Pasteboard_Finalize)(void* context); 141 142 /** 143 * @brief Defines the Pasteboard subscriber information 144 * 145 * @since 13 146 */ 147 typedef struct OH_PasteboardObserver OH_PasteboardObserver; 148 149 /** 150 * @brief Creates a {@link OH_PasteboardObserver} instance. 151 * 152 * @return Returns the pointer to the {@link OH_PasteboardObserver} instance created if the operation is successful. 153 * Returns nullptr if the operation is failed. 154 * @see OH_PasteboardObserver. 155 * @since 13 156 */ 157 OH_PasteboardObserver* OH_PasteboardObserver_Create(); 158 159 /** 160 * @brief Destroy a {@link OH_PasteboardObserver} instance. 161 * 162 * @param observer Pointer to the {@link OH_PasteboardObserver} instance to destroy. 163 * @return Returns the status code of the execution. For details, see {@link PASTEBOARD_ErrCode}. 164 * Returns {@link ERR_OK} if the operation is successful. 165 * Returns {@link ERR_INVALID_PARAMETER} if invalid args are detected. 166 * @see OH_PasteboardObserver PASTEBOARD_ErrCode. 167 * @since 13 168 */ 169 int OH_PasteboardObserver_Destroy(OH_PasteboardObserver* observer); 170 171 /** 172 * @brief Sets a callback function to return the Pasteboard data changed. 173 * 174 * @param observer Pointer to the {@link OH_PasteboardObserver} instance. 175 * @param context Pointer to the context set, which is the first parameter in Pasteboard_Notify. 176 * @param callback Callback to set. For details, see {@link Pasteboard_Notify}. 177 * @param finalize Optional callback that can free context when destroy observer. 178 * For details, see {@link Pasteboard_Finalize}. 179 * @return Returns the status code of the execution. For details, see {@link PASTEBOARD_ErrCode}. 180 * Returns {@link ERR_OK} if the operation is successful. 181 * Returns {@link ERR_INVALID_PARAMETER} if invalid args are detected. 182 * @see OH_PasteboardObserver Pasteboard_Notify PASTEBOARD_ErrCode. 183 * @since 13 184 */ 185 int OH_PasteboardObserver_SetData(OH_PasteboardObserver* observer, void* context, 186 const Pasteboard_Notify callback, const Pasteboard_Finalize finalize); 187 188 /** 189 * @brief Represents the Pasteboard information. 190 * 191 * @since 13 192 */ 193 typedef struct OH_Pasteboard OH_Pasteboard; 194 195 /** 196 * @brief Creates a {@link OH_Pasteboard} instance. 197 * 198 * @return Returns the pointer to the {@link OH_Pasteboard} instance created if the operation is successful. 199 * Returns nullptr if the memory is not enough. 200 * @see OH_Pasteboard. 201 * @since 13 202 */ 203 OH_Pasteboard* OH_Pasteboard_Create(); 204 205 /** 206 * @brief Destroy a {@link OH_Pasteboard} instance. 207 * 208 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance to destroy. 209 * @see OH_Pasteboard. 210 * @since 13 211 */ 212 void OH_Pasteboard_Destroy(OH_Pasteboard* pasteboard); 213 214 /** 215 * @brief Subscribes to the Pasteboard data change. 216 * 217 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 218 * @param type Event type to subscribe to. 219 * @param observer - Pointer to the observer information, which specifies the callback used to 220 * reporting the pasteboard data change. For details, see {@link OH_PasteboardObserver}. 221 * @return Returns the status code of the execution. For details, {@link PASTEBOARD_ErrCode}. 222 * Returns {@link ERR_OK} if the operation is successful. 223 * Returns {@link ERR_INVALID_PARAMETER} if invalid args are detected. 224 * @see OH_Pasteboard OH_PasteboardObserver PASTEBOARD_ErrCode. 225 * @since 13 226 */ 227 int OH_Pasteboard_Subscribe(OH_Pasteboard* pasteboard, int type, const OH_PasteboardObserver* observer); 228 229 /** 230 * @brief Unsubscribes from the Pasteboard data change. 231 * 232 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 233 * @param type Event type to subscribe to. 234 * @param observer - Pointer to the observer information, which specifies the callback used to 235 * reporting the pasteboard data change. For details, see {@link OH_PasteboardObserver}. 236 * @return Returns the status code of the execution. For details, {@link PASTEBOARD_ErrCode}. 237 * Returns {@link ERR_OK} if the operation is successful. 238 * Returns {@link ERR_INVALID_PARAMETER} if invalid args are detected. 239 * @see OH_Pasteboard OH_PasteboardObserver PASTEBOARD_ErrCode. 240 * @since 13 241 */ 242 int OH_Pasteboard_Unsubscribe(OH_Pasteboard* pasteboard, int type, const OH_PasteboardObserver* observer); 243 244 /** 245 * @brief Checks whether the Pasteboard data is from a remote device. 246 * 247 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 248 * @return Returns a boolean value, which indicates whether the the data is from a remote device. 249 * The value {@code false} means Pasteboard data is not from a remote device. 250 * The value {@code true} means the opposite. 251 * @see OH_Pasteboard. 252 * @since 13 253 */ 254 bool OH_Pasteboard_IsRemoteData(OH_Pasteboard* pasteboard); 255 256 /** 257 * @brief Obtains the source of Pasteboard data. 258 * 259 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 260 * @param source Pointer to the source data. 261 * @param len Length of the source data. 262 * @return Returns the status code of the execution. For details, see {@link PASTEBOARD_ErrCode}. 263 * Returns {@link ERR_OK} if the operation is successful. 264 * Returns {@link ERR_INVALID_PARAMETER} if invalid args are detected. 265 * @see OH_Pasteboard PASTEBOARD_ErrCode. 266 * @since 13 267 */ 268 int OH_Pasteboard_GetDataSource(OH_Pasteboard* pasteboard, char* source, unsigned int len); 269 270 /** 271 * @brief Checks whether the Pasteboard has the specified type of data. 272 * 273 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 274 * @param type Poniter to the type of data to check. 275 * @return Returns a boolean value, which indicates whether the Pasteboard has the specified type of data. 276 * The value {@code true} means the Pasteboard has the specified type of data. 277 * The value {@code false} means the opposite. 278 * @see OH_Pasteboard. 279 * @since 13 280 */ 281 bool OH_Pasteboard_HasType(OH_Pasteboard* pasteboard, const char* type); 282 283 /** 284 * @brief Checks whether there is data in the Pasteboard. 285 * 286 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 287 * @return Returns a boolean value, which indicates whether there is data in the Pasteboard. 288 * The value {@code true} means there is data in Pasteboard. 289 * The value {@code false} means the opposite. 290 * @see OH_Pasteboard. 291 * @since 13 292 */ 293 bool OH_Pasteboard_HasData(OH_Pasteboard* pasteboard); 294 295 /** 296 * @brief Obtains data from the Pasteboard. 297 * 298 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 299 * @param status The status code of the execution. For details, see {@link PASTEBOARD_ErrCode}. 300 * @return Returns the pointer to the {@link OH_UdmfData} instance. 301 * @see OH_Pasteboard OH_UdmfData PASTEBOARD_ErrCode. 302 * @since 13 303 */ 304 OH_UdmfData* OH_Pasteboard_GetData(OH_Pasteboard* pasteboard, int* status); 305 306 /** 307 * @brief Writes data to the Pasteboard. 308 * 309 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 310 * @param data Pointer to the {@link OH_UdmfData} instance. 311 * @return Returns the status code of the execution. For details, see {@link PASTEBOARD_ErrCode}. 312 * Returns {@link ERR_OK} if the operation is successful. 313 * Returns {@link ERR_INVALID_PARAMETER} if invalid args are detected. 314 * @see OH_Pasteboard OH_UdmfData PASTEBOARD_ErrCode. 315 * @since 13 316 */ 317 int OH_Pasteboard_SetData(OH_Pasteboard* pasteboard, OH_UdmfData* data); 318 319 /** 320 * @brief Clears the data in the Pastedboard. 321 * 322 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 323 * @return Returns the status code of the execution. For details, see {@link PASTEBOARD_ErrCode}. 324 * Returns {@link ERR_OK} if the operation is successful. 325 * Returns {@link ERR_INVALID_PARAMETER} if invalid args are detected. 326 * @see OH_Pasteboard PASTEBOARD_ErrCode. 327 * @since 13 328 */ 329 int OH_Pasteboard_ClearData(OH_Pasteboard* pasteboard); 330 331 /** 332 * @brief Obtains all MIME types of Pasteboard data. 333 * 334 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 335 * @param count Poniter to the count of MIME types. 336 * @return Returns char array of MIME types in the Pasteboard. 337 * Returns nullptr if the operation is failed. 338 * @see OH_Pasteboard. 339 * @since 14 340 */ 341 char **OH_Pasteboard_GetMimeTypes(OH_Pasteboard *pasteboard, unsigned int *count); 342 /** 343 * @brief Create a pointer to the instance of the {@link Pasteboard_GetDataParams}. 344 * 345 * @return If the operation is successful, a pointer to the instance of the {@link Pasteboard_GetDataParams} 346 * structure is returned. If the operation is failed, nullptr is returned. 347 * @see Pasteboard_GetDataParams 348 * @since 15 349 */ 350 Pasteboard_GetDataParams *OH_Pasteboard_GetDataParams_Create(void); 351 352 /** 353 * @brief Destroy a pointer that points to an instance of {@link Pasteboard_GetDataParams}. 354 * 355 * @param params Represents a pointer to an instance of {@link Pasteboard_GetDataParams}. 356 * @see Pasteboard_GetDataParams 357 * @since 15 358 */ 359 void OH_Pasteboard_GetDataParams_Destroy(Pasteboard_GetDataParams* params); 360 361 /** 362 * @brief Set the progress indicator to the {@link Pasteboard_GetDataParams}. 363 * 364 * @param params Represents a pointer to an instance of {@link Pasteboard_GetDataParams}. 365 * @param progressIndicator Represents to the progress indicator. 366 * @see Pasteboard_GetDataParams Pasteboard_ProgressIndicator 367 * @since 15 368 */ 369 void OH_Pasteboard_GetDataParams_SetProgressIndicator(Pasteboard_GetDataParams* params, 370 Pasteboard_ProgressIndicator progressIndicator); 371 372 /** 373 * @brief Set the destination uri to the {@link Pasteboard_GetDataParams}. 374 * 375 * @param params Represents a pointer to an instance of {@link Pasteboard_GetDataParams}. 376 * @param destUri Pointer to a destination uri. 377 * @param destUriLen Indicates the length of destination uri. 378 * @see Pasteboard_GetDataParams 379 * @since 15 380 */ 381 void OH_Pasteboard_GetDataParams_SetDestUri(Pasteboard_GetDataParams* params, const char* destUri, uint32_t destUriLen); 382 383 /** 384 * @brief Set the file conflict options to the {@link Pasteboard_GetDataParams}. 385 * 386 * @param params Represents a pointer to an instance of {@link Pasteboard_GetDataParams}. 387 * @param option Represents to the file conflict options. 388 * @see Pasteboard_GetDataParams Pasteboard_FileConflictOptions 389 * @since 15 390 */ 391 void OH_Pasteboard_GetDataParams_SetFileConflictOptions(Pasteboard_GetDataParams* params, 392 Pasteboard_FileConflictOptions option); 393 394 /** 395 * @brief Set the progress indicator to the {@link Pasteboard_GetDataParams}. 396 * 397 * @param params Represents a pointer to an instance of {@link Pasteboard_GetDataParams}. 398 * @param listener Represents to the data progress listener. 399 * @see Pasteboard_GetDataParams OH_Pasteboard_ProgressListener 400 * @since 15 401 */ 402 void OH_Pasteboard_GetDataParams_SetProgressListener(Pasteboard_GetDataParams* params, 403 const OH_Pasteboard_ProgressListener listener); 404 405 /** 406 * @brief Get the progress from the {@link Pasteboard_ProgressInfo}. 407 * 408 * @param progressInfo Represents a pointer to an instance of {@link Pasteboard_ProgressInfo}. 409 * @return Returns the progress. 410 * @see Pasteboard_ProgressInfo 411 * @since 15 412 */ 413 int OH_Pasteboard_ProgressInfo_GetProgress(Pasteboard_ProgressInfo* progressInfo); 414 415 /** 416 * @brief Defines the cancel function used to cancel the progress when getting PasteData. 417 * 418 * @param params Pointer to indicates the {@link Pasteboard_GetDataParams}. 419 * @see Pasteboard_GetDataParams. 420 * @since 15 421 */ 422 void OH_Pasteboard_ProgressCancel(Pasteboard_GetDataParams* params); 423 424 /** 425 * @brief Obtains data from the Pasteboard with system progress indicator. 426 * 427 * @permission ohos.permission.READ_PASTEBOARD 428 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 429 * @param params Pointer to indicates the {@link Pasteboard_GetDataParams}. 430 * @param status The status code of the execution. For details, see {@link PASTEBOARD_Errcode}. 431 * @return Returns the pointer to the {@link OH_UdmfData} instance. 432 * @see OH_Pasteboard OH_UdmfData PASTEBOARD_ErrCode. 433 * @since 15 434 */ 435 OH_UdmfData* OH_Pasteboard_GetDataWithProgress(OH_Pasteboard* pasteboard, Pasteboard_GetDataParams* params, 436 int* status); 437 #ifdef __cplusplus 438 }; 439 #endif 440 441 /** @} */ 442 #endif