1/*
2 * Copyright (C) 2023 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 AVScreenCapture
18 * @{
19 *
20 * @brief Provides APIs of request capability for Screen Capture.
21 * @since 10
22 */
23
24/**
25 * @file native_avscreen_capture.h
26 *
27 * @brief Declare screen capture related interfaces.
28 *
29 * @library libnative_avscreen_capture.so
30 * @syscap SystemCapability.Multimedia.Media.AVScreenCapture
31 * @kit MediaKit
32 * @since 10
33 */
34
35#ifndef NATIVE_AVSCREEN_CAPTURE_H
36#define NATIVE_AVSCREEN_CAPTURE_H
37
38#include <stdbool.h>
39#include <stdint.h>
40#include <stdio.h>
41#include "native_avscreen_capture_errors.h"
42#include "native_avscreen_capture_base.h"
43#include "native_window/external_window.h"
44
45#ifdef __cplusplus
46extern "C" {
47#endif
48
49/**
50 * @brief Create a screen capture
51 * @syscap SystemCapability.Multimedia.Media.AVScreenCapture
52 * @return Returns a pointer to an OH_AVScreenCapture instance
53 * @since 10
54 * @version 1.0
55 */
56struct OH_AVScreenCapture *OH_AVScreenCapture_Create(void);
57
58/**
59 * @brief To init the screen capture, typically, you need to configure the description information of the audio
60 * and video, which can be extracted from the container. This interface must be called before StartAVScreenCapture
61 * called.
62 * @syscap SystemCapability.Multimedia.Media.AVScreenCapture
63 * @param capture Pointer to an OH_AVScreenCapture instance
64 * @param config Information describing the audio and video config
65 * @return Function result code.
66 *         {@link AV_SCREEN_CAPTURE_ERR_OK} if the execution is successful.
67 *         {@link AV_SCREEN_CAPTURE_ERR_INVALID_VAL} input capture is nullptr.
68 *         {@link AV_SCREEN_CAPTURE_ERR_OPERATE_NOT_PERMIT} opertation not be permitted, init config failed.
69 * @since 10
70 * @version 1.0
71 */
72OH_AVSCREEN_CAPTURE_ErrCode OH_AVScreenCapture_Init(struct OH_AVScreenCapture *capture,
73    OH_AVScreenCaptureConfig config);
74
75/**
76 * @brief Start the av screen capture
77 * @syscap SystemCapability.Multimedia.Media.AVScreenCapture
78 * @param capture Pointer to an OH_AVScreenCapture instance
79 * @param type Information describing the data type of the capture
80 * @return Function result code.
81 *         {@link AV_SCREEN_CAPTURE_ERR_OK} if the execution is successful.
82 *         {@link AV_SCREEN_CAPTURE_ERR_INVALID_VAL} input capture is nullptr.
83 *         {@link AV_SCREEN_CAPTURE_ERR_OPERATE_NOT_PERMIT} opertation not be permitted, set privacy authority enabled
84 *         failed or start ScreenCapture failed.
85 * @since 10
86 * @version 1.0
87 */
88OH_AVSCREEN_CAPTURE_ErrCode OH_AVScreenCapture_StartScreenCapture(struct OH_AVScreenCapture *capture);
89
90/**
91 * @brief Stop the av screen capture
92 * @syscap SystemCapability.Multimedia.Media.AVScreenCapture
93 * @param capture Pointer to an OH_AVScreenCapture instance
94 * @return Function result code.
95 *         {@link AV_SCREEN_CAPTURE_ERR_OK} if the execution is successful.
96 *         {@link AV_SCREEN_CAPTURE_ERR_INVALID_VAL} input capture is nullptr.
97 *         {@link AV_SCREEN_CAPTURE_ERR_OPERATE_NOT_PERMIT} opertation not be permitted, stop ScreenCapture failed.
98 * @since 10
99 * @version 1.0
100 */
101OH_AVSCREEN_CAPTURE_ErrCode OH_AVScreenCapture_StopScreenCapture(struct OH_AVScreenCapture *capture);
102
103/**
104 * @brief Start av screen record use to start save screen record file.
105 * @syscap SystemCapability.Multimedia.Media.AVScreenCapture
106 * @param capture Pointer to an OH_AVScreenCapture instance
107 * @return Function result code.
108 *         {@link AV_SCREEN_CAPTURE_ERR_OK} if the execution is successful.
109 *         {@link AV_SCREEN_CAPTURE_ERR_INVALID_VAL} input capture is nullptr.
110 *         {@link AV_SCREEN_CAPTURE_ERR_OPERATE_NOT_PERMIT} opertation not be permitted, set privacy authority enabled
111 *         failed or start ScreenRecording failed.
112 * @since 10
113 * @version 1.0
114 */
115OH_AVSCREEN_CAPTURE_ErrCode OH_AVScreenCapture_StartScreenRecording(struct OH_AVScreenCapture *capture);
116
117/**
118 * @brief Start av screen record use to stop save screen record file.
119 * @syscap SystemCapability.Multimedia.Media.AVScreenCapture
120 * @param capture Pointer to an OH_AVScreenCapture instance
121 * @return Function result code.
122 *         {@link AV_SCREEN_CAPTURE_ERR_OK} if the execution is successful.
123 *         {@link AV_SCREEN_CAPTURE_ERR_INVALID_VAL} input capture is nullptr.
124 *         {@link AV_SCREEN_CAPTURE_ERR_OPERATE_NOT_PERMIT} opertation not be permitted, stop ScreenRecording failed.
125 * @since 10
126 * @version 1.0
127 */
128OH_AVSCREEN_CAPTURE_ErrCode OH_AVScreenCapture_StopScreenRecording(struct OH_AVScreenCapture *capture);
129
130/**
131 * @brief Acquire the audio buffer for the av screen capture
132 * @syscap SystemCapability.Multimedia.Media.AVScreenCapture
133 * @param capture Pointer to an OH_AVScreenCapture instance
134 * @param audiobuffer Information describing the audio buffer of the capture
135 * @param type Information describing the audio source type
136 * @return Function result code.
137 *         {@link AV_SCREEN_CAPTURE_ERR_OK} if the execution is successful.
138 *         {@link AV_SCREEN_CAPTURE_ERR_INVALID_VAL} input capture is nullptr or input **audiobuffer is nullptr.
139 *         {@link AV_SCREEN_CAPTURE_ERR_NO_MEMORY} no memory, audiobuffer allocate failed.
140 *         {@link AV_SCREEN_CAPTURE_ERR_OPERATE_NOT_PERMIT} opertation not be permitted, not permit for has set
141 *         DataCallback or acquire AudioBuffer failed.
142 * @since 10
143 * @version 1.0
144 */
145OH_AVSCREEN_CAPTURE_ErrCode OH_AVScreenCapture_AcquireAudioBuffer(struct OH_AVScreenCapture *capture,
146    OH_AudioBuffer **audiobuffer, OH_AudioCaptureSourceType type);
147
148/**
149 * @brief Acquire the video buffer for the av screen capture
150 * @syscap SystemCapability.Multimedia.Media.AVScreenCapture
151 * @param capture Pointer to an OH_AVScreenCapture instance
152 * @param fence A processing state of display buffer
153 * @param timestamp Information about the video buffer
154 * @param region Information about the video buffer
155 * @return Returns a pointer to an OH_NativeBuffer instance
156 * @since 10
157 * @version 1.0
158 */
159OH_NativeBuffer* OH_AVScreenCapture_AcquireVideoBuffer(struct OH_AVScreenCapture *capture,
160    int32_t *fence, int64_t *timestamp, struct OH_Rect *region);
161
162/**
163 * @brief Release the audio buffer for the av screen capture
164 * @syscap SystemCapability.Multimedia.Media.AVScreenCapture
165 * @param capture Pointer to an OH_AVScreenCapture instance
166 * @param type Information describing the audio source type
167 * @return Function result code.
168 *         {@link AV_SCREEN_CAPTURE_ERR_OK} if the execution is successful.
169 *         {@link AV_SCREEN_CAPTURE_ERR_INVALID_VAL} input capture is nullptr.
170 *         {@link AV_SCREEN_CAPTURE_ERR_OPERATE_NOT_PERMIT} opertation not be permitted, not permit for has set
171 *         DataCallback or Release AudioBuffer failed.
172 * @since 10
173 * @version 1.0
174 */
175OH_AVSCREEN_CAPTURE_ErrCode OH_AVScreenCapture_ReleaseAudioBuffer(struct OH_AVScreenCapture *capture,
176    OH_AudioCaptureSourceType type);
177
178/**
179 * @brief Release the video buffer for the av screen capture
180 * @syscap SystemCapability.Multimedia.Media.AVScreenCapture
181 * @param capture Pointer to an OH_AVScreenCapture instance
182 * @return Function result code.
183 *         {@link AV_SCREEN_CAPTURE_ERR_OK} if the execution is successful.
184 *         {@link AV_SCREEN_CAPTURE_ERR_INVALID_VAL} input capture is nullptr.
185 *         {@link AV_SCREEN_CAPTURE_ERR_OPERATE_NOT_PERMIT} opertation not be permitted, not permit for has set
186 *         DataCallback or Release VideoBuffer failed.
187 * @since 10
188 * @version 1.0
189 */
190OH_AVSCREEN_CAPTURE_ErrCode OH_AVScreenCapture_ReleaseVideoBuffer(struct OH_AVScreenCapture *capture);
191
192/**
193 * @brief Set the callback function so that your application
194 * can respond to the events generated by the av screen capture. This interface must be called before Init is called.
195 * @syscap SystemCapability.Multimedia.Media.AVScreenCapture
196 * @param capture Pointer to an OH_AVScreenCapture instance
197 * @param callback A collection of all callback functions, see {@link OH_AVScreenCaptureCallback}
198 * @return Function result code.
199 *         {@link AV_SCREEN_CAPTURE_ERR_OK} if the execution is successful.
200 *         {@link AV_SCREEN_CAPTURE_ERR_INVALID_VAL} input capture is nullptr or input callback is nullptr.
201 *         {@link AV_SCREEN_CAPTURE_ERR_OPERATE_NOT_PERMIT} opertation not be permitted, set callback failed.
202 * @since 10
203 * @version 1.0
204 */
205OH_AVSCREEN_CAPTURE_ErrCode OH_AVScreenCapture_SetCallback(struct OH_AVScreenCapture *capture,
206    struct OH_AVScreenCaptureCallback callback);
207
208/**
209 * @brief Release the av screen capture
210 * @syscap SystemCapability.Multimedia.Media.AVScreenCapture
211 * @param capture Pointer to an OH_AVScreenCapture instance
212 * @return Function result code.
213 *         {@link AV_SCREEN_CAPTURE_ERR_OK} if the execution is successful.
214 *         {@link AV_SCREEN_CAPTURE_ERR_INVALID_VAL} input capture is nullptr.
215 *         {@link AV_SCREEN_CAPTURE_ERR_OPERATE_NOT_PERMIT} opertation not be permitted, screen capture release failed.
216 * @since 10
217 * @version 1.0
218 */
219OH_AVSCREEN_CAPTURE_ErrCode OH_AVScreenCapture_Release(struct OH_AVScreenCapture *capture);
220
221/**
222 * @brief Controls the switch of the microphone, which is turned on by default
223 * @syscap SystemCapability.Multimedia.Media.AVScreenCapture
224 * @param capture Pointer to an OH_AVScreenCapture instance
225 * @param isMicrophone The switch of the microphone
226 * @return Function result code.
227 *         {@link AV_SCREEN_CAPTURE_ERR_OK} if the execution is successful.
228 *         {@link AV_SCREEN_CAPTURE_ERR_INVALID_VAL} input capture is nullptr.
229 *         {@link AV_SCREEN_CAPTURE_ERR_OPERATE_NOT_PERMIT} opertation not be permitted, set microphone enable failed.
230 * @since 10
231 * @version 1.0
232 */
233OH_AVSCREEN_CAPTURE_ErrCode OH_AVScreenCapture_SetMicrophoneEnabled(struct OH_AVScreenCapture *capture,
234    bool isMicrophone);
235
236/**
237 * @brief Set the state callback function so that your application can respond to the
238 * state change events generated by the av screen capture. This interface must be called before Start is called.
239 * @syscap SystemCapability.Multimedia.Media.AVScreenCapture
240 * @param capture Pointer to an OH_AVScreenCapture instance
241 * @param callback State callback function, see {@link OH_AVScreenCapture_OnStateChange}
242 * @param userData Pointer to user specific data
243 * @return Function result code.
244 *         {@link AV_SCREEN_CAPTURE_ERR_OK} if the execution is successful.
245 *         {@link AV_SCREEN_CAPTURE_ERR_INVALID_VAL} input capture is nullptr or input callback is nullptr.
246 *         {@link AV_SCREEN_CAPTURE_ERR_NO_MEMORY} no memory, mem allocate failed.
247 *         {@link AV_SCREEN_CAPTURE_ERR_OPERATE_NOT_PERMIT} opertation not be permitted, set StateCallback failed.
248 * @since 12
249 * @version 1.0
250 */
251OH_AVSCREEN_CAPTURE_ErrCode OH_AVScreenCapture_SetStateCallback(struct OH_AVScreenCapture *capture,
252    OH_AVScreenCapture_OnStateChange callback, void *userData);
253
254/**
255 * @brief Set the data callback function so that your application can respond to the
256 * data available events generated by the av screen capture. This interface must be called before Start is called.
257 * @syscap SystemCapability.Multimedia.Media.AVScreenCapture
258 * @param capture Pointer to an OH_AVScreenCapture instance
259 * @param callback Data callback function, see {@link OH_AVScreenCapture_OnBufferAvailable}
260 * @param userData Pointer to user specific data
261 * @return Function result code.
262 *         {@link AV_SCREEN_CAPTURE_ERR_OK} if the execution is successful.
263 *         {@link AV_SCREEN_CAPTURE_ERR_INVALID_VAL} input capture is nullptr or input callback is nullptr.
264 *         {@link AV_SCREEN_CAPTURE_ERR_NO_MEMORY} no memory, mem allocate failed.
265 *         {@link AV_SCREEN_CAPTURE_ERR_OPERATE_NOT_PERMIT} opertation not be permitted, set DataCallback failed.
266 * @since 12
267 * @version 1.0
268 */
269OH_AVSCREEN_CAPTURE_ErrCode OH_AVScreenCapture_SetDataCallback(struct OH_AVScreenCapture *capture,
270    OH_AVScreenCapture_OnBufferAvailable callback, void *userData);
271
272/**
273 * @brief Set the error callback function so that your application can respond to the
274 * error events generated by the av screen capture. This interface must be called before Start is called.
275 * @syscap SystemCapability.Multimedia.Media.AVScreenCapture
276 * @param capture Pointer to an OH_AVScreenCapture instance
277 * @param callback Error callback function, see {@link OH_AVScreenCapture_OnError}
278 * @param userData Pointer to user specific data
279 * @return Function result code.
280 *         {@link AV_SCREEN_CAPTURE_ERR_OK} if the execution is successful.
281 *         {@link AV_SCREEN_CAPTURE_ERR_INVALID_VAL} input capture is nullptr or input callback is nullptr.
282 *         {@link AV_SCREEN_CAPTURE_ERR_NO_MEMORY} no memory, mem allocate failed.
283 *         {@link AV_SCREEN_CAPTURE_ERR_OPERATE_NOT_PERMIT} opertation not be permitted, set ErrorCallback failed.
284 * @since 12
285 * @version 1.0
286 */
287OH_AVSCREEN_CAPTURE_ErrCode OH_AVScreenCapture_SetErrorCallback(struct OH_AVScreenCapture *capture,
288    OH_AVScreenCapture_OnError callback, void *userData);
289
290/**
291 * @brief Start the av screen capture, video data provided by OHNativeWindow
292 * @syscap SystemCapability.Multimedia.Media.AVScreenCapture
293 * @param capture Pointer to an OH_AVScreenCapture instance
294 * @param window Pointer to an OHNativeWindow instance
295 * @return Function result code.
296 *         {@link AV_SCREEN_CAPTURE_ERR_OK} if the execution is successful.
297 *         {@link AV_SCREEN_CAPTURE_ERR_INVALID_VAL} input capture is nullptr or input window is nullptr or
298 *         input windowSurface is nullptr.
299 *         {@link AV_SCREEN_CAPTURE_ERR_OPERATE_NOT_PERMIT} opertation not be permitted, set privacy authority enabled
300 *         failed or start ScreenCaptureWithSurface failed.
301 * @since 12
302 * @version 1.0
303 */
304OH_AVSCREEN_CAPTURE_ErrCode OH_AVScreenCapture_StartScreenCaptureWithSurface(struct OH_AVScreenCapture *capture,
305    OHNativeWindow *window);
306
307/**
308 * @brief Set canvas rotation when capturing screen
309 * @syscap SystemCapability.Multimedia.Media.AVScreenCapture
310 * @param capture Pointer to an OH_AVScreenCapture instance
311 * @param canvasRotation whether to rotate the canvas
312 * @return Function result code.
313 *         {@link AV_SCREEN_CAPTURE_ERR_OK} if the execution is successful.
314 *         {@link AV_SCREEN_CAPTURE_ERR_INVALID_VAL} input capture is nullptr.
315 *         {@link AV_SCREEN_CAPTURE_ERR_OPERATE_NOT_PERMIT} opertation not be permitted, set CanvasRotation failed.
316 * @since 12
317 * @version 1.0
318 */
319OH_AVSCREEN_CAPTURE_ErrCode OH_AVScreenCapture_SetCanvasRotation(struct OH_AVScreenCapture *capture,
320    bool canvasRotation);
321
322/**
323 * @brief Create a screen capture content filter
324 * @syscap SystemCapability.Multimedia.Media.AVScreenCapture
325 * @return Returns a pointer to an OH_AVScreenCapture_ContentFilter instance
326 * @since 12
327 * @version 1.0
328 */
329struct OH_AVScreenCapture_ContentFilter *OH_AVScreenCapture_CreateContentFilter(void);
330
331/**
332 * @brief Release the screen capture content filter
333 * @syscap SystemCapability.Multimedia.Media.AVScreenCapture
334 * @param filter Pointer to an OH_AVScreenCapture_ContentFilter instance
335 * @return Function result code.
336 *         {@link AV_SCREEN_CAPTURE_ERR_OK} if the execution is successful.
337 *         {@link AV_SCREEN_CAPTURE_ERR_INVALID_VAL} input filter is nullptr.
338 * @since 12
339 * @version 1.0
340 */
341OH_AVSCREEN_CAPTURE_ErrCode OH_AVScreenCapture_ReleaseContentFilter(struct OH_AVScreenCapture_ContentFilter *filter);
342
343/**
344 * @brief Add content to the screen capture content filter
345 * @syscap SystemCapability.Multimedia.Media.AVScreenCapture
346 * @param filter Pointer to an OH_AVScreenCapture_ContentFilter instance
347 * @param content content to be added
348 * @return Function result code.
349 *         {@link AV_SCREEN_CAPTURE_ERR_OK} if the execution is successful.
350 *         {@link AV_SCREEN_CAPTURE_ERR_INVALID_VAL} input filter is nullptr or input content invalid.
351 * @since 12
352 * @version 1.0
353 */
354OH_AVSCREEN_CAPTURE_ErrCode OH_AVScreenCapture_ContentFilter_AddAudioContent(
355    struct OH_AVScreenCapture_ContentFilter *filter, OH_AVScreenCaptureFilterableAudioContent content);
356
357/**
358 * @brief Set content filter to screen capture
359 * @syscap SystemCapability.Multimedia.Media.AVScreenCapture
360 * @param capture Pointer to an OH_AVScreenCapture instance
361 * @param filter Pointer to an OH_AVScreenCapture_ContentFilter instance
362 * @return Function result code.
363 *         {@link AV_SCREEN_CAPTURE_ERR_OK} if the execution is successful.
364 *         {@link AV_SCREEN_CAPTURE_ERR_INVALID_VAL} input capture is nullptr or input filter is nullptr.
365 *         {@link AV_SCREEN_CAPTURE_ERR_UNSUPPORT} not support, for STREAM, should call AudioCapturer interface to make
366 *         effect when start, for CAPTURE FILE, should call Recorder interface to make effect when start.
367 * @since 12
368 * @version 1.0
369 */
370OH_AVSCREEN_CAPTURE_ErrCode OH_AVScreenCapture_ExcludeContent(struct OH_AVScreenCapture *capture,
371    struct OH_AVScreenCapture_ContentFilter *filter);
372
373/**
374 * @brief Add Window content to the screen capture content filter
375 * @syscap SystemCapability.Multimedia.Media.AVScreenCapture
376 * @param filter Pointer to an OH_AVScreenCapture_ContentFilter instance
377 * @param Pointer to windowIDs to be added
378 * @param windowCount to be added
379 * @return Returns AV_SCREEN_CAPTURE_ERR_OK if the execution is successful,
380 * otherwise returns a specific error code, refer to {@link OH_AVSCREEN_CAPTURE_ErrCode}
381 * @since 12
382 * @version 1.0
383 */
384OH_AVSCREEN_CAPTURE_ErrCode OH_AVScreenCapture_ContentFilter_AddWindowContent(
385    struct OH_AVScreenCapture_ContentFilter *filter, int32_t *windowIDs, int32_t windowCount);
386
387/**
388 * @brief Resize the Resolution of the Screen
389 * @syscap SystemCapability.Multimedia.Media.AVScreenCapture
390 * @param capture Pointer to an OH_AVScreenCapture instance
391 * @param width Video frame width of avscreeencapture
392 * @param height Video frame height of avscreeencapture
393 * @return Function result code.
394 *         {@link AV_SCREEN_CAPTURE_ERR_OK} if the execution is successful.
395 *         {@link AV_SCREEN_CAPTURE_ERR_INVALID_VAL} input capture is nullptr.
396 *         {@link AV_SCREEN_CAPTURE_ERR_OPERATE_NOT_PERMIT} opertation not be permitted.
397 * @since 12
398 * @version 1.0
399 */
400OH_AVSCREEN_CAPTURE_ErrCode OH_AVScreenCapture_ResizeCanvas(struct OH_AVScreenCapture *capture,
401    int32_t width, int32_t height);
402
403/**
404 * @brief skip some windows' privacy mode of current app during the screen recording
405 * @syscap SystemCapability.Multimedia.Media.AVScreenCapture
406 * @param capture Pointer to an OH_AVScreenCapture instance
407 * @param Pointer of windowID list
408 * @param length of windowID list
409 * @return Function result code.
410 *         {@link AV_SCREEN_CAPTURE_ERR_OK} if the execution is successful.
411 *         {@link AV_SCREEN_CAPTURE_ERR_INVALID_VAL} input capture is nullptr or input windowIDs are not belong current
412 *         app.
413 *         {@link AV_SCREEN_CAPTURE_ERR_OPERATE_NOT_PERMIT} opertation not be permitted.
414 * @since 12
415 * @version 1.0
416 */
417OH_AVSCREEN_CAPTURE_ErrCode OH_AVScreenCapture_SkipPrivacyMode(struct OH_AVScreenCapture *capture,
418    int32_t *windowIDs, int32_t windowCount);
419
420/**
421 * @brief set up the max number of video frame per second
422 * @syscap SystemCapability.Multimedia.Media.AVScreenCapture
423 * @param capture Pointer to an OH_AVScreenCapture instance
424 * @param max frame rate of video
425 * @return Function result code.
426 *         {@link AV_SCREEN_CAPTURE_ERR_OK} if the execution is successful.
427 *         {@link AV_SCREEN_CAPTURE_ERR_INVALID_VAL} input capture is nullptr or frameRate is not support.
428 *         {@link AV_SCREEN_CAPTURE_ERR_OPERATE_NOT_PERMIT} opertation not be permitted.
429 * @since 14
430 * @version 1.0
431 */
432OH_AVSCREEN_CAPTURE_ErrCode OH_AVScreenCapture_SetMaxVideoFrameRate(struct OH_AVScreenCapture *capture,
433    int32_t frameRate);
434#ifdef __cplusplus
435}
436#endif
437
438#endif // NATIVE_AVSCREEN_CAPTURE_H
439/** @} */