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