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
47extern "C" {
48#endif
49
50/**
51 * @brief Enumerates the types of data changes that can be observed.
52 *
53 * @since 13
54 */
55typedef 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 */
73typedef 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 */
80typedef void (*Pasteboard_Finalize)(void* context);
81
82/**
83 * @brief Defines the Pasteboard subscriber information
84 *
85 * @since 13
86 */
87typedef 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 */
97OH_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 */
109int 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 */
125int 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 */
133typedef 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 */
143OH_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 */
152void 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 */
167int 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 */
182int 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 */
194bool 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 */
208int 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 */
221bool 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 */
233bool 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 */
244OH_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 */
257int 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 */
269int OH_Pasteboard_ClearData(OH_Pasteboard* pasteboard);
270#ifdef __cplusplus
271};
272#endif
273
274/** @} */
275#endif