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 Defines the callback function used to return the Pasteboard data changed. 74 * 75 * @param context The context set by {@link OH_PasteboardObserver_SetData} function. 76 * @param type The types of data changes. For details, see {@link Pasteboard_NotifyType}. 77 * @since 13 78 */ 79 typedef void (*Pasteboard_Notify)(void* context, Pasteboard_NotifyType type); 80 81 /** 82 * @brief Defines the callback function used free the context. 83 * @param context Pointer to the context which is to be free. 84 * @since 13 85 */ 86 typedef void (*Pasteboard_Finalize)(void* context); 87 88 /** 89 * @brief Defines the Pasteboard subscriber information 90 * 91 * @since 13 92 */ 93 typedef struct OH_PasteboardObserver OH_PasteboardObserver; 94 95 /** 96 * @brief Creates a {@link OH_PasteboardObserver} instance. 97 * 98 * @return Returns the pointer to the {@link OH_PasteboardObserver} instance created if the operation is successful. 99 * Returns nullptr if the operation is failed. 100 * @see OH_PasteboardObserver. 101 * @since 13 102 */ 103 OH_PasteboardObserver* OH_PasteboardObserver_Create(); 104 105 /** 106 * @brief Destroy a {@link OH_PasteboardObserver} instance. 107 * 108 * @param observer Pointer to the {@link OH_PasteboardObserver} instance to destroy. 109 * @return Returns the status code of the execution. For details, see {@link PASTEBOARD_ErrCode}. 110 * Returns {@link ERR_OK} if the operation is successful. 111 * Returns {@link ERR_INVALID_PARAMETER} if invalid args are detected. 112 * @see OH_PasteboardObserver PASTEBOARD_ErrCode. 113 * @since 13 114 */ 115 int OH_PasteboardObserver_Destroy(OH_PasteboardObserver* observer); 116 117 /** 118 * @brief Sets a callback function to return the Pasteboard data changed. 119 * 120 * @param observer Pointer to the {@link OH_PasteboardObserver} instance. 121 * @param context Pointer to the context set, which is the first parameter in Pasteboard_Notify. 122 * @param callback Callback to set. For details, see {@link Pasteboard_Notify}. 123 * @param finalize Optional callback that can free context when destroy observer. 124 * For details, see {@link Pasteboard_Finalize}. 125 * @return Returns the status code of the execution. For details, see {@link PASTEBOARD_ErrCode}. 126 * Returns {@link ERR_OK} if the operation is successful. 127 * Returns {@link ERR_INVALID_PARAMETER} if invalid args are detected. 128 * @see OH_PasteboardObserver Pasteboard_Notify PASTEBOARD_ErrCode. 129 * @since 13 130 */ 131 int OH_PasteboardObserver_SetData(OH_PasteboardObserver* observer, void* context, 132 const Pasteboard_Notify callback, const Pasteboard_Finalize finalize); 133 134 /** 135 * @brief Represents the Pasteboard information. 136 * 137 * @since 13 138 */ 139 typedef struct OH_Pasteboard OH_Pasteboard; 140 141 /** 142 * @brief Creates a {@link OH_Pasteboard} instance. 143 * 144 * @return Returns the pointer to the {@link OH_Pasteboard} instance created if the operation is successful. 145 * Returns nullptr if the memory is not enough. 146 * @see OH_Pasteboard. 147 * @since 13 148 */ 149 OH_Pasteboard* OH_Pasteboard_Create(); 150 151 /** 152 * @brief Destroy a {@link OH_Pasteboard} instance. 153 * 154 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance to destroy. 155 * @see OH_Pasteboard. 156 * @since 13 157 */ 158 void OH_Pasteboard_Destroy(OH_Pasteboard* pasteboard); 159 160 /** 161 * @brief Subscribes to the Pasteboard data change. 162 * 163 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 164 * @param type Event type to subscribe to. 165 * @param observer - Pointer to the observer information, which specifies the callback used to 166 * reporting the pasteboard data change. For details, see {@link OH_PasteboardObserver}. 167 * @return Returns the status code of the execution. For details, {@link PASTEBOARD_ErrCode}. 168 * Returns {@link ERR_OK} if the operation is successful. 169 * Returns {@link ERR_INVALID_PARAMETER} if invalid args are detected. 170 * @see OH_Pasteboard OH_PasteboardObserver PASTEBOARD_ErrCode. 171 * @since 13 172 */ 173 int OH_Pasteboard_Subscribe(OH_Pasteboard* pasteboard, int type, const OH_PasteboardObserver* observer); 174 175 /** 176 * @brief Unsubscribes from the Pasteboard data change. 177 * 178 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 179 * @param type Event type to subscribe to. 180 * @param observer - Pointer to the observer information, which specifies the callback used to 181 * reporting the pasteboard data change. For details, see {@link OH_PasteboardObserver}. 182 * @return Returns the status code of the execution. For details, {@link PASTEBOARD_ErrCode}. 183 * Returns {@link ERR_OK} if the operation is successful. 184 * Returns {@link ERR_INVALID_PARAMETER} if invalid args are detected. 185 * @see OH_Pasteboard OH_PasteboardObserver PASTEBOARD_ErrCode. 186 * @since 13 187 */ 188 int OH_Pasteboard_Unsubscribe(OH_Pasteboard* pasteboard, int type, const OH_PasteboardObserver* observer); 189 190 /** 191 * @brief Checks whether the Pasteboard data is from a remote device. 192 * 193 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 194 * @return Returns a boolean value, which indicates whether the the data is from a remote device. 195 * The value {@code false} means Pasteboard data is not from a remote device. 196 * The value {@code true} means the opposite. 197 * @see OH_Pasteboard. 198 * @since 13 199 */ 200 bool OH_Pasteboard_IsRemoteData(OH_Pasteboard* pasteboard); 201 202 /** 203 * @brief Obtains the source of Pasteboard data. 204 * 205 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 206 * @param source Pointer to the source data. 207 * @param len Length of the source data. 208 * @return Returns the status code of the execution. For details, see {@link PASTEBOARD_ErrCode}. 209 * Returns {@link ERR_OK} if the operation is successful. 210 * Returns {@link ERR_INVALID_PARAMETER} if invalid args are detected. 211 * @see OH_Pasteboard PASTEBOARD_ErrCode. 212 * @since 13 213 */ 214 int OH_Pasteboard_GetDataSource(OH_Pasteboard* pasteboard, char* source, unsigned int len); 215 216 /** 217 * @brief Checks whether the Pasteboard has the specified type of data. 218 * 219 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 220 * @param type Poniter to the type of data to check. 221 * @return Returns a boolean value, which indicates whether the Pasteboard has the specified type of data. 222 * The value {@code true} means the Pasteboard has the specified type of data. 223 * The value {@code false} means the opposite. 224 * @see OH_Pasteboard. 225 * @since 13 226 */ 227 bool OH_Pasteboard_HasType(OH_Pasteboard* pasteboard, const char* type); 228 229 /** 230 * @brief Checks whether there is data in the Pasteboard. 231 * 232 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 233 * @return Returns a boolean value, which indicates whether there is data in the Pasteboard. 234 * The value {@code true} means there is data in Pasteboard. 235 * The value {@code false} means the opposite. 236 * @see OH_Pasteboard. 237 * @since 13 238 */ 239 bool OH_Pasteboard_HasData(OH_Pasteboard* pasteboard); 240 241 /** 242 * @brief Obtains data from the Pasteboard. 243 * 244 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 245 * @param status The status code of the execution. For details, see {@link PASTEBOARD_ErrCode}. 246 * @return Returns the pointer to the {@link OH_UdmfData} instance. 247 * @see OH_Pasteboard OH_UdmfData PASTEBOARD_ErrCode. 248 * @since 13 249 */ 250 OH_UdmfData* OH_Pasteboard_GetData(OH_Pasteboard* pasteboard, int* status); 251 252 /** 253 * @brief Writes data to the Pasteboard. 254 * 255 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 256 * @param data Pointer to the {@link OH_UdmfData} instance. 257 * @return Returns the status code of the execution. For details, see {@link PASTEBOARD_ErrCode}. 258 * Returns {@link ERR_OK} if the operation is successful. 259 * Returns {@link ERR_INVALID_PARAMETER} if invalid args are detected. 260 * @see OH_Pasteboard OH_UdmfData PASTEBOARD_ErrCode. 261 * @since 13 262 */ 263 int OH_Pasteboard_SetData(OH_Pasteboard* pasteboard, OH_UdmfData* data); 264 265 /** 266 * @brief Clears the data in the Pastedboard. 267 * 268 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 269 * @return Returns the status code of the execution. For details, see {@link PASTEBOARD_ErrCode}. 270 * Returns {@link ERR_OK} if the operation is successful. 271 * Returns {@link ERR_INVALID_PARAMETER} if invalid args are detected. 272 * @see OH_Pasteboard PASTEBOARD_ErrCode. 273 * @since 13 274 */ 275 int OH_Pasteboard_ClearData(OH_Pasteboard* pasteboard); 276 277 /** 278 * @brief Obtains all MIME types of Pasteboard data. 279 * 280 * @param pasteboard Pointer to the {@link OH_Pasteboard} instance. 281 * @param count Poniter to the count of MIME types. 282 * @return Returns char array of MIME types in the Pasteboard. 283 * Returns nullptr if the operation is failed. 284 * @see OH_Pasteboard. 285 * @since 14 286 */ 287 char **OH_Pasteboard_GetMimeTypes(OH_Pasteboard *pasteboard, unsigned int *count); 288 #ifdef __cplusplus 289 }; 290 #endif 291 292 /** @} */ 293 #endif