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. 213 * @param observer - Pointer to the observer information, which specifies the callback used to 214 * reporting the pasteboard data change. For details, see {@link OH_PasteboardObserver}. 215 * @return Returns the status code of the execution. For details, {@link PASTEBOARD_ErrCode}. 216 * Returns {@link ERR_OK} if the operation is successful. 217 * Returns {@link ERR_INVALID_PARAMETER} if invalid args are detected. 218 * @see OH_Pasteboard OH_PasteboardObserver PASTEBOARD_ErrCode. 219 * @since 13 220 */ 221 int OH_Pasteboard_Subscribe(OH_Pasteboard* pasteboard, int type, const OH_PasteboardObserver* observer); 222 223 /** 224 * @brief Unsubscribes from the Pasteboard data change. 225 * 226 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 227 * @param type Event type to subscribe to. 228 * @param observer - Pointer to the observer information, which specifies the callback used to 229 * reporting the pasteboard data change. For details, see {@link OH_PasteboardObserver}. 230 * @return Returns the status code of the execution. For details, {@link PASTEBOARD_ErrCode}. 231 * Returns {@link ERR_OK} if the operation is successful. 232 * Returns {@link ERR_INVALID_PARAMETER} if invalid args are detected. 233 * @see OH_Pasteboard OH_PasteboardObserver PASTEBOARD_ErrCode. 234 * @since 13 235 */ 236 int OH_Pasteboard_Unsubscribe(OH_Pasteboard* pasteboard, int type, const OH_PasteboardObserver* observer); 237 238 /** 239 * @brief Checks whether the Pasteboard data is from a remote device. 240 * 241 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 242 * @return Returns a boolean value, which indicates whether the the data is from a remote device. 243 * The value {@code false} means Pasteboard data is not from a remote device. 244 * The value {@code true} means the opposite. 245 * @see OH_Pasteboard. 246 * @since 13 247 */ 248 bool OH_Pasteboard_IsRemoteData(OH_Pasteboard* pasteboard); 249 250 /** 251 * @brief Obtains the source of Pasteboard data. 252 * 253 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 254 * @param source Pointer to the source data. 255 * @param len Length of the source data. 256 * @return Returns the status code of the execution. For details, see {@link PASTEBOARD_ErrCode}. 257 * Returns {@link ERR_OK} if the operation is successful. 258 * Returns {@link ERR_INVALID_PARAMETER} if invalid args are detected. 259 * @see OH_Pasteboard PASTEBOARD_ErrCode. 260 * @since 13 261 */ 262 int OH_Pasteboard_GetDataSource(OH_Pasteboard* pasteboard, char* source, unsigned int len); 263 264 /** 265 * @brief Checks whether the Pasteboard has the specified type of data. 266 * 267 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 268 * @param type Poniter to the type of data to check. 269 * @return Returns a boolean value, which indicates whether the Pasteboard has the specified type of data. 270 * The value {@code true} means the Pasteboard has the specified type of data. 271 * The value {@code false} means the opposite. 272 * @see OH_Pasteboard. 273 * @since 13 274 */ 275 bool OH_Pasteboard_HasType(OH_Pasteboard* pasteboard, const char* type); 276 277 /** 278 * @brief Checks whether there is data in the Pasteboard. 279 * 280 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 281 * @return Returns a boolean value, which indicates whether there is data in the Pasteboard. 282 * The value {@code true} means there is data in Pasteboard. 283 * The value {@code false} means the opposite. 284 * @see OH_Pasteboard. 285 * @since 13 286 */ 287 bool OH_Pasteboard_HasData(OH_Pasteboard* pasteboard); 288 289 /** 290 * @brief Obtains data from the Pasteboard. 291 * 292 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 293 * @param status The status code of the execution. For details, see {@link PASTEBOARD_ErrCode}. 294 * @return Returns the pointer to the {@link OH_UdmfData} instance. 295 * @see OH_Pasteboard OH_UdmfData PASTEBOARD_ErrCode. 296 * @since 13 297 */ 298 OH_UdmfData* OH_Pasteboard_GetData(OH_Pasteboard* pasteboard, int* status); 299 300 /** 301 * @brief Writes data to the Pasteboard. 302 * 303 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 304 * @param data Pointer to the {@link OH_UdmfData} instance. 305 * @return Returns the status code of the execution. For details, see {@link PASTEBOARD_ErrCode}. 306 * Returns {@link ERR_OK} if the operation is successful. 307 * Returns {@link ERR_INVALID_PARAMETER} if invalid args are detected. 308 * @see OH_Pasteboard OH_UdmfData PASTEBOARD_ErrCode. 309 * @since 13 310 */ 311 int OH_Pasteboard_SetData(OH_Pasteboard* pasteboard, OH_UdmfData* data); 312 313 /** 314 * @brief Clears the data in the Pastedboard. 315 * 316 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 317 * @return Returns the status code of the execution. For details, see {@link PASTEBOARD_ErrCode}. 318 * Returns {@link ERR_OK} if the operation is successful. 319 * Returns {@link ERR_INVALID_PARAMETER} if invalid args are detected. 320 * @see OH_Pasteboard PASTEBOARD_ErrCode. 321 * @since 13 322 */ 323 int OH_Pasteboard_ClearData(OH_Pasteboard* pasteboard); 324 325 /** 326 * @brief Obtains all MIME types of Pasteboard data. 327 * 328 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 329 * @param count Poniter to the count of MIME types. 330 * @return Returns char array of MIME types in the Pasteboard. 331 * Returns nullptr if the operation is failed. 332 * @see OH_Pasteboard. 333 * @since 14 334 */ 335 char **OH_Pasteboard_GetMimeTypes(OH_Pasteboard *pasteboard, unsigned int *count); 336 337 /** 338 * @brief Gets the number of Pasteboard data changes. 339 * 340 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 341 * @return the number of Pasteboard data changes. 342 * Returns 0 means initial value or invalid value.In this case, no action is required. 343 * @since 18 344 */ 345 uint32_t OH_Pasteboard_GetChangeCount(OH_Pasteboard *pasteboard); 346 347 /** 348 * @brief Create a pointer to the instance of the {@link Pasteboard_GetDataParams}. 349 * 350 * @return If the operation is successful, a pointer to the instance of the {@link Pasteboard_GetDataParams} 351 * structure is returned. If the operation is failed, nullptr is returned. 352 * @see Pasteboard_GetDataParams 353 * @since 15 354 */ 355 Pasteboard_GetDataParams *OH_Pasteboard_GetDataParams_Create(void); 356 357 /** 358 * @brief Destroy a pointer that points to an instance of {@link Pasteboard_GetDataParams}. 359 * 360 * @param params Represents a pointer to an instance of {@link Pasteboard_GetDataParams}. 361 * @see Pasteboard_GetDataParams 362 * @since 15 363 */ 364 void OH_Pasteboard_GetDataParams_Destroy(Pasteboard_GetDataParams* params); 365 366 /** 367 * @brief Set the progress indicator to the {@link Pasteboard_GetDataParams}. 368 * 369 * @param params Represents a pointer to an instance of {@link Pasteboard_GetDataParams}. 370 * @param progressIndicator Represents to the progress indicator. 371 * @see Pasteboard_GetDataParams Pasteboard_ProgressIndicator 372 * @since 15 373 */ 374 void OH_Pasteboard_GetDataParams_SetProgressIndicator(Pasteboard_GetDataParams* params, 375 Pasteboard_ProgressIndicator progressIndicator); 376 377 /** 378 * @brief Set the destination uri to the {@link Pasteboard_GetDataParams}. 379 * 380 * @param params Represents a pointer to an instance of {@link Pasteboard_GetDataParams}. 381 * @param destUri Pointer to a destination uri. 382 * @param destUriLen Indicates the length of destination uri. 383 * @see Pasteboard_GetDataParams 384 * @since 15 385 */ 386 void OH_Pasteboard_GetDataParams_SetDestUri(Pasteboard_GetDataParams* params, const char* destUri, uint32_t destUriLen); 387 388 /** 389 * @brief Set the file conflict options to the {@link Pasteboard_GetDataParams}. 390 * 391 * @param params Represents a pointer to an instance of {@link Pasteboard_GetDataParams}. 392 * @param option Represents to the file conflict options. 393 * @see Pasteboard_GetDataParams Pasteboard_FileConflictOptions 394 * @since 15 395 */ 396 void OH_Pasteboard_GetDataParams_SetFileConflictOptions(Pasteboard_GetDataParams* params, 397 Pasteboard_FileConflictOptions option); 398 399 /** 400 * @brief Set the progress indicator to the {@link Pasteboard_GetDataParams}. 401 * 402 * @param params Represents a pointer to an instance of {@link Pasteboard_GetDataParams}. 403 * @param listener Represents to the data progress listener. 404 * @see Pasteboard_GetDataParams OH_Pasteboard_ProgressListener 405 * @since 15 406 */ 407 void OH_Pasteboard_GetDataParams_SetProgressListener(Pasteboard_GetDataParams* params, 408 const OH_Pasteboard_ProgressListener listener); 409 410 /** 411 * @brief Get the progress from the {@link Pasteboard_ProgressInfo}. 412 * 413 * @param progressInfo Represents a pointer to an instance of {@link Pasteboard_ProgressInfo}. 414 * @return Returns the progress. 415 * @see Pasteboard_ProgressInfo 416 * @since 15 417 */ 418 int OH_Pasteboard_ProgressInfo_GetProgress(Pasteboard_ProgressInfo* progressInfo); 419 420 /** 421 * @brief Defines the cancel function used to cancel the progress when getting PasteData. 422 * 423 * @param params Pointer to indicates the {@link Pasteboard_GetDataParams}. 424 * @see Pasteboard_GetDataParams. 425 * @since 15 426 */ 427 void OH_Pasteboard_ProgressCancel(Pasteboard_GetDataParams* params); 428 429 /** 430 * @brief Obtains data from the Pasteboard with system progress indicator. 431 * 432 * @permission ohos.permission.READ_PASTEBOARD 433 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 434 * @param params Pointer to indicates the {@link OH_Pasteboard_GetDataParams}. 435 * @param status The status code of the execution. For details, see {@link PASTEBOARD_Errcode}. 436 * @return Returns the pointer to the {@link OH_PasteData} instance. 437 * @see OH_Pasteboard OH_PasteData PASTEBOARD_ErrCode. 438 * @since 15 439 */ 440 OH_UdmfData* OH_Pasteboard_GetDataWithProgress(OH_Pasteboard* pasteboard, Pasteboard_GetDataParams* params, 441 int* status); 442 #ifdef __cplusplus 443 }; 444 #endif 445 446 /** @} */ 447 #endif