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