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