diff --git a/en/device_api/hdi/bluetooth/a2dp/v1_0/BluetoothAudioTypes.idl b/en/device_api/hdi/bluetooth/a2dp/v1_0/BluetoothAudioTypes.idl new file mode 100644 index 0000000000000000000000000000000000000000..2e7fa0e25ecf86fdc511651958891d171acf6f00 --- /dev/null +++ b/en/device_api/hdi/bluetooth/a2dp/v1_0/BluetoothAudioTypes.idl @@ -0,0 +1,75 @@ +/* + * Copyright (c) 2022 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/* + * @addtogroup HdiA2dp + * @{ + * + * @brief Provides unified APIs for the A2DP service. + * + * The Host can use the interface provided by the module to create an audio session, + * and exchange data with the audio subsystem. + * + * @since 4.0 + */ + +/* + * @file BluetoothAudioTypes.idl + * + * @brief Defines the data structure. + * + * @since 4.0 + * @version 1.0 + */ + +package ohos.hdi.bluetooth.a2dp.v1_0; + +/* + * @brief Defines the operation. + * + * @since 4.0 + */ +enum Operation { + /** suspend render */ + SUSPEND_RENDER = 0, + /** start render */ + START_RENDER = 1, +}; + +/* + * @brief Defines the operation result of the interface. + * + * @since 4.0 + */ +enum Status { + /** status is success */ + SUCCESS = 0, + /** status is failure */ + FAILURE = 1, +}; + +/* + * @brief Defines the type of audio session. + * + * @since 4.0 + */ +enum SessionType { + /** unkown type */ + UNKNOWN_TYPE, + /** software encoding */ + SOFTWARE_ENCODING, + /** hardware encoding */ + HARDWARE_ENCODING, +}; \ No newline at end of file diff --git a/en/device_api/hdi/bluetooth/a2dp/v1_0/IBluetoothAudioCallback.idl b/en/device_api/hdi/bluetooth/a2dp/v1_0/IBluetoothAudioCallback.idl new file mode 100644 index 0000000000000000000000000000000000000000..a73a7b819b55a08337050aae87104aca1a69f454 --- /dev/null +++ b/en/device_api/hdi/bluetooth/a2dp/v1_0/IBluetoothAudioCallback.idl @@ -0,0 +1,74 @@ +/* + * Copyright (c) 2022 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/* + * @addtogroup HdiA2dp + * @{ + * + * @brief Provides unified APIs for the A2DP service. + * + * The Host can use the interface provided by the module to create an audio session, + * and exchange data with the audio subsystem. + * + * @since 4.0 + */ + +/** + * @file IBluetoothAudioCallback.idl + * + * @brief Defines the callback function, including the start, suspend, stop operations from audio. + * + * @since 4.0 + * @version 1.0 + */ + +package ohos.hdi.bluetooth.a2dp.v1_0; + +/** + * @brief Defines the callback function to start, suspend, stop audio render. + * + * @since 4.0 + */ +[callback] interface IBluetoothAudioCallback { + /** + * @brief Start audio render callback function. + * + * @return Returns 0 if the result is returned successfully; returns a negative value otherwise. + * + * @since 4.0 + * @version 1.0 + */ + StartRender(); + + /** + * @brief Suspend audio render callback function. + * + * @return Returns 0 if the result is returned successfully; returns a negative value otherwise. + * + * @since 4.0 + * @version 1.0 + */ + SuspendRender(); + + /** + * @brief Stop audio render callback function. + * + * @return Returns 0 if the result is returned successfully; returns a negative value otherwise. + * + * @since 4.0 + * @version 1.0 + */ + StopRender(); +} diff --git a/en/device_api/hdi/bluetooth/a2dp/v1_0/IBluetoothAudioSession.idl b/en/device_api/hdi/bluetooth/a2dp/v1_0/IBluetoothAudioSession.idl new file mode 100644 index 0000000000000000000000000000000000000000..87205c77019b531e72654c7964ce505a8f9bc4dd --- /dev/null +++ b/en/device_api/hdi/bluetooth/a2dp/v1_0/IBluetoothAudioSession.idl @@ -0,0 +1,86 @@ +/* + * Copyright (c) 2022 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/* + * @addtogroup HdiA2dp + * @{ + * + * @brief Provides unified APIs for the A2DP service. + * + * The Host can use the interface provided by the module to create an audio session, + * and exchange data with the audio. + * + * @since 4.0 + */ + +/** + * @file IBluetoothAudioSession.idl + * + * @brief Defines the interfaces to start audio session, send render operation result, + * and stop the audio session. + * + * @since 4.0 + * @version 1.0 + */ + +package ohos.hdi.bluetooth.a2dp.v1_0; + +import ohos.hdi.bluetooth.a2dp.v1_0.IBluetoothAudioCallback; +import ohos.hdi.bluetooth.a2dp.v1_0.BluetoothAudioTypes; + +/** + * @brief Defines the interfaces to start audio session, send render operation result, + * and stop the audio session. + * + * @since 4.0 + */ +interface IBluetoothAudioSession { + /** + * @brief Start audio session and register the callback function. + * + * @param sessionType Indicates the session type. + * @param callbackObj Indicates the callback function. For details, see {@link IBluetoothAudioCallback}. + * @param queue Returns sharedMemQueue for audio data. + * @return Returns 0 if the operation is successfully; returns a negative value otherwise. + * + * @since 4.0 + * @version 1.0 + */ + StartSession([in] enum SessionType sessionType, [in] IBluetoothAudioCallback callbackObj, + [out] SharedMemQueue queue); + + /** + * @brief Stop audio session. + * + * @param sessionType Indicates the session type. + * @return Returns 0 if the operation is successfully; returns a negative value otherwise. + * + * @since 4.0 + * @version 1.0 + */ + StopSession([in] enum SessionType sessionType); + + /** + * @brief send the render operation result. + * + * @param operation Indicates the render operation. + * @param Status SUCCESS or FAILURE for operation. + * @return Returns 0 if the operation is successfully; returns a negative value otherwise. + * + * @since 4.0 + * @version 1.0 + */ + RenderOperationResult([in] enum Operation operation, [in] enum Status status); +} diff --git a/en/device_api/hdi/bluetooth/hci/v1_0/HciTypes.idl b/en/device_api/hdi/bluetooth/hci/v1_0/HciTypes.idl new file mode 100644 index 0000000000000000000000000000000000000000..43a75ef2ca665624bee5bbf011b205a5e62ed9dd --- /dev/null +++ b/en/device_api/hdi/bluetooth/hci/v1_0/HciTypes.idl @@ -0,0 +1,69 @@ +/* + * Copyright (c) 2022 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/* + * @addtogroup HdiHci + * @{ + * + * @brief Provides unified APIs for the HCI service. + * + * The Host can use the interface provided by the module to initialize the HCI(Host Controller Interface), + * and exchange data with the Controller through the service. + * + * @since 3.2 + */ + +/* + * @file HciTypes.idl + * + * @brief Defines the data structure used by the HCI module. + * + * @since 3.2 + * @version 1.0 + */ + +package ohos.hdi.bluetooth.hci.v1_0; + +/* + * @brief Defines the operation result of the interface. + * + * @since 3.2 + */ +enum BtStatus { + /** status is success */ + SUCCESS = 0, + /** initial error */ + INITIAL_ERROR = 1, + /** unknown status */ + UNKNOWN = 2, +}; + +/* + * @brief Defines the data type transmitted over the HCI. + * + * @since 3.2 + */ +enum BtType { + /** HCI command */ + HCI_CMD = 1, + /** ACL data */ + ACL_DATA = 2, + /** SCO data */ + SCO_DATA = 3, + /** HCI event */ + HCI_EVENT = 4, + /** ISO data */ + ISO_DATA = 5, +}; \ No newline at end of file diff --git a/en/device_api/hdi/bluetooth/hci/v1_0/IHciCallback.idl b/en/device_api/hdi/bluetooth/hci/v1_0/IHciCallback.idl new file mode 100644 index 0000000000000000000000000000000000000000..033c5ed3d411907987aabd960587d24567a5370c --- /dev/null +++ b/en/device_api/hdi/bluetooth/hci/v1_0/IHciCallback.idl @@ -0,0 +1,69 @@ +/* + * Copyright (c) 2022 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup HdiHci + * @{ + * + * @brief Provides unified APIs for the HCI service. + * + * The Host can use the interface provided by the module to initialize the HCI(Host Controller Interface), + * and exchange data with the Controller through the service. + * + * @since 3.2 + */ + +/** + * @file IHciCallback.idl + * + * @brief Defines the HCI callback function, including the initialization result and data received from the controller. + * + * @since 3.2 + * @version 1.0 + */ + +package ohos.hdi.bluetooth.hci.v1_0; + +import ohos.hdi.bluetooth.hci.v1_0.HciTypes; + +/** + * @brief Defines the HCI callback function, including the initialization result and data received from the controller. + * + * @since 3.2 + */ +[callback] interface IHciCallback { + /** + * @brief HCI initialization callback function. + * + * @param status Indicates the HCI initialization result. For details, see {@link BtStatus}. + * @return Returns 0 if the initialization result is returned successfully; returns a negative value otherwise. + * + * @since 3.2 + * @version 1.0 + */ + OnInited([in] enum BtStatus status); + + /** + * @brief Receives data packets sent by the controller.. + * + * @param type Indicates the HCI packet type. For details, see {@link BtType}. + * @param data Indicates the HCI data packets received from the Controller. + * @return Returns 0 if the data is received successfully; returns a negative value otherwise. + * + * @since 3.2 + * @version 1.0 + */ + OnReceivedHciPacket([in] enum BtType type, [in] unsigned char[] data); +} diff --git a/en/device_api/hdi/bluetooth/hci/v1_0/IHciInterface.idl b/en/device_api/hdi/bluetooth/hci/v1_0/IHciInterface.idl new file mode 100644 index 0000000000000000000000000000000000000000..e6cc2c975898b2a9dbc14a5ffb8ae56ae7766487 --- /dev/null +++ b/en/device_api/hdi/bluetooth/hci/v1_0/IHciInterface.idl @@ -0,0 +1,82 @@ +/* + * Copyright (c) 2022 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup HdiHci + * @{ + * + * @brief Provides unified APIs for the HCI service. + * + * The Host can use the interface provided by the module to initialize the HCI(Host Controller Interface), + * and exchange data with the Controller through the service. + * + * @since 3.2 + */ + +/** + * @file IHciInterface.idl + * + * @brief Defines the interfaces to initialize the HCI, send data to the Controller, + * and disable the HCI interface. + * + * @since 3.2 + * @version 1.0 + */ + +package ohos.hdi.bluetooth.hci.v1_0; + +import ohos.hdi.bluetooth.hci.v1_0.IHciCallback; +import ohos.hdi.bluetooth.hci.v1_0.HciTypes; + +/** + * @brief Defines the interfaces to initialize the HCI, send data to the Controller, + * and disable the HCI interface. + * + * @since 3.2 + */ +interface IHciInterface { + /** + * @brief Initialize the HCI and register the callback function. + * + * @param callbackObj Indicates the callback function. For details, see {@link IHciCallback}. + * @return Returns 0 if the HCI is initialized successfully; returns a negative value otherwise. + * + * @since 3.2 + * @version 1.0 + */ + Init([in] IHciCallback callbackObj); + + /** + * @brief Sends data packets to the Controller. + * + * @param type Indicates the HCI packet type. For details, see {@link BtType}. + * @param data Indicates the HCI data packets sent to the Controller. + * @return Returns 0 if the HCI data packets is sent successfully; returns a negative value otherwise. + * + * @since 3.2 + * @version 1.0 + */ + SendHciPacket([in] enum BtType type, [in] unsigned char[] data); + + /** + * @brief Disable the HCI interface. + * + * @return Returns 0 if the HCI is disabled successfully; returns a negative value otherwise. + * + * @since 3.2 + * @version 1.0 + */ + Close(); +} diff --git a/en/device_api/hdi/distributed_camera/v1_0/DCameraTypes.idl b/en/device_api/hdi/distributed_camera/v1_0/DCameraTypes.idl new file mode 100644 index 0000000000000000000000000000000000000000..cfb2f9131813102dd77af58bace82ec984bdc24a --- /dev/null +++ b/en/device_api/hdi/distributed_camera/v1_0/DCameraTypes.idl @@ -0,0 +1,307 @@ +/* + * Copyright (c) 2022 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + + /** + * @addtogroup Distributed Camera + * @{ + * + * @brief Provides APIs for the Distributed Camera module. + * + * You can use the APIs which are consistent with camera APIs to perform operations on + * distributed camera devices and streams, and implement various callbacks. + * Communicate with Source SA through IDCameraProvider to achieve distributed functionality. + * + * @since 3.2 + * @version 1.0 + */ + +/** + * @file DCameraTypes.idl + * + * @brief Declares data types used by the Hardware Driver Interfaces (HDIs) of the distributed camera module. + * + * @since 3.2 + * @version 1.0 + */ + +/** + * @brief Defines the package path of the distributed camera module APIs. + * + * @since 3.2 + * @version 1.0 + */ +package ohos.hdi.distributed_camera.v1_0; + +/** + * @brief Enumerates distributed camera metadata updating types. + */ +enum DCSettingsType { + /** + * Set the whole package metadata. + */ + UPDATE_METADATA = 0, + /** + * Enable metadata configuration. + */ + ENABLE_METADATA = 1, + /** + * Disable metadata configuration. + */ + DISABLE_METADATA = 2, + /** + * Return metadata result from distributed camera. + */ + METADATA_RESULT = 3, + /** + * Set flash light to distribtued camera. + */ + SET_FLASH_LIGHT = 4, + /** + * Set fps range to distributed camera. + */ + FPS_RANGE = 5, + /** + * Set the frame metadata to distributed camera. + */ + UPDATE_FRAME_METADATA = 6, +}; + +/** + * @brief Enumerates return values of the HDIs. + */ +enum DCamRetCode { + /** + * Successful call. + */ + SUCCESS = 0, + /** + * The camera device is busy. + */ + CAMERA_BUSY = 1, + /** + * Invalid parameters. + */ + INVALID_ARGUMENT = 2, + /** + * Unsupported function. + */ + METHOD_NOT_SUPPORTED = 3, + /** + * The camera device is offlined. + */ + CAMERA_OFFLINE = 4, + /** + * The number of distributed camera devices enabled exceeds the limit. + */ + EXCEED_MAX_NUMBER = 5, + /** + * The device is not initialized. + */ + DEVICE_NOT_INIT = 6, + /** + * Failed call. + */ + FAILED = 7, +}; + +/** + * @brief Enumerates encoding types of stream data. + */ +enum DCEncodeType { + /** + * Unspecified encode type. + */ + ENCODE_TYPE_NULL = 0, + /** + * H.264 encode type. + */ + ENCODE_TYPE_H264 = 1, + /** + * H.265 encode type. + */ + ENCODE_TYPE_H265 = 2, + /** + * JPEG encode type. + */ + ENCODE_TYPE_JPEG = 3, + /** + * mpeg4-es encode type. + */ + ENCODE_TYPE_MPEG4_ES = 4, +}; + +/** + * @brief Enumerates distributed camera inner stream types. + */ +enum DCStreamType { + /** + * Continuous capture stream. For example preview streams, video streams. + */ + CONTINUOUS_FRAME = 0, + /** + * Single capture stream. For example photographing streams. + */ + SNAPSHOT_FRAME = 1, +}; + +/** + * @brief Distributed hardware device base info. + */ +struct DHBase { + /** + * The device id, here is networkId. + */ + String deviceId_; + /** + * The distributed hardware id. + */ + String dhId_; +}; + +/** + * @brief The control settings of the distributed camera device. + */ +struct DCameraSettings { + /** + * Settings type, see {@link DCSettingsType}. + */ + enum DCSettingsType type_; + /** + * Settings value. Serialized from bool, array, structure, etc. + */ + String value_; +}; + +/** + * @brief Defines the inner stream information of the distributed camera, + * which is used to pass configuration parameters during stream creation. + */ +struct DCStreamInfo { + /** + * Stream ID, which uniquely identifies a stream on a camera device. + */ + int streamId_; + /** + * Image width，see {@link StreamInfo}. + */ + int width_; + /** + * Image height，see {@link StreamInfo}. + */ + int height_; + /** + * Image stride，see {@link StreamInfo}. + */ + int stride_; + /** + * Image format，see {@link StreamInfo}. + */ + int format_; + /** + * Image color space，see {@link StreamInfo}. + */ + int dataspace_; + /** + * Encoding type, see {@link DCEncodeType}. + */ + enum DCEncodeType encodeType_; + /** + * Stream type, see {@link DCStreamType}. + */ + enum DCStreamType type_; +}; + +/** + * @brief Defines the information about a inner capture request of the distributed camera. + */ +struct DCCaptureInfo { + /** + * IDs of captured streams. + */ + int[] streamIds_; + /** + * Image width. + */ + int width_; + /** + * Image height. + */ + int height_; + /** + * Image stride. + */ + int stride_; + /** + * Image format. + */ + int format_; + /** + * Image color space. + */ + int dataspace_; + /** + * Is trigger sink capture. + */ + boolean isCapture_; + /** + * Encoding type, see {@link DCEncodeType}. + */ + enum DCEncodeType encodeType_; + /** + * Stream type, see {@link DCStreamType}. + */ + enum DCStreamType type_; + /** + * Stream settings, see {@link DCameraSettings}. + */ + struct DCameraSettings[] captureSettings_; +}; + +/** + * @brief Defines the inner buffer of the distributed camera, + * which is used to acquire buffer during processing capture requests. + */ +struct DCameraBuffer { + /** + * Buffer index. + */ + int index_; + /** + * Buffer size. + */ + unsigned int size_; + /** + * Native buffer, see {@link NativeBuffer}. + */ + NativeBuffer bufferHandle_; +}; + +/** + * @brief Notification event of the distributed camera. + */ +struct DCameraHDFEvent { + /** + * Event type. + */ + int type_; + /** + * Event result. + */ + int result_; + /** + * Extended content (optional). + */ + String content_; +}; diff --git a/en/device_api/hdi/distributed_camera/v1_0/IDCameraProvider.idl b/en/device_api/hdi/distributed_camera/v1_0/IDCameraProvider.idl new file mode 100644 index 0000000000000000000000000000000000000000..352313696ca6d6f02752e3a024aedee9a16c02ae --- /dev/null +++ b/en/device_api/hdi/distributed_camera/v1_0/IDCameraProvider.idl @@ -0,0 +1,144 @@ +/* + * Copyright (c) 2022 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + + /** + * @addtogroup Distributed Camera + * @{ + * + * @brief Provides APIs for the Distributed Camera module. + * + * You can use the APIs which are consistent with camera APIs to perform operations on + * distributed camera devices and streams, and implement various callbacks. + * Communicate with Source SA through IDCameraProvider to achieve distributed functionality. + * + * @since 3.2 + * @version 1.0 + */ + +/** + * @file IDCameraProvider.idl + * + * @brief Transfer interfaces call between distributed camera SA service and distributed camera HDF service, + * and provide Hardware Driver Interfaces (HDIs) for the upper layer. + * + * @since 3.2 + * @version 1.0 + */ + +/** + * @brief Defines the package path of the distributed camera module APIs. + * + * @since 3.2 + * @version 1.0 + */ +package ohos.hdi.distributed_camera.v1_0; + +import ohos.hdi.distributed_camera.v1_0.DCameraTypes; +import ohos.hdi.distributed_camera.v1_0.IDCameraProviderCallback; + +/** + * @brief Defines the basic operations available for distributed camera devices. + * + * You can set Enable distributed camera devices, set stream processing, update control parameters, + * execute metadata and other related operations. + */ +interface IDCameraProvider { + /** + * @brief Enable distributed camera device and set callback. For details about the callbacks, + * see {@link IDCameraProviderCallback}. + * + * @param dhBase Distributed hardware device base info. + * @param abilityInfo The static capability info of the distributed camera device to be enabled. + * @param callbackObj Indicates the callbacks to set. + * + * @return Returns NO_ERROR if the operation is successful, + * @return an error code defined in {@link DCamRetCode} otherwise. + * + * @since 3.2 + * @version 1.0 + */ + EnableDCameraDevice([in] struct DHBase dhBase,[in] String abilityInfo,[in] IDCameraProviderCallback callbackObj); + + /** + * @brief Disable distributed camera device. + * + * @param dhBase Distributed hardware device base info. + * + * @return Returns NO_ERROR if the operation is successful, + * @return an error code defined in {@link DCamRetCode} otherwise. + * + * @since 3.2 + * @version 1.0 + */ + DisableDCameraDevice([in] struct DHBase dhBase); + + /** + * @brief Acquire a frame buffer from the procedure handle which attached to the streamId. + * + * @param dhBase Distributed hardware device base info. + * @param streamId Indicates the ID of the stream to which the procedure handle is to be attached. + * @param buffer A frame buffer. + * + * @return Returns NO_ERROR if the operation is successful, + * @return an error code defined in {@link DCamRetCode} otherwise. + * + * @since 3.2 + * @version 1.0 + */ + AcquireBuffer([in] struct DHBase dhBase,[in] int streamId,[out] struct DCameraBuffer buffer); + + /** + * @brief Notify distributed camera HDF service when a frame buffer has been filled. + * + * @param dhBase Distributed hardware device base info. + * @param streamId Indicates the ID of the stream to which the frame buffer is to be attached. + * @param buffer output frame buffer. + * + * @return Returns NO_ERROR if the operation is successful, + * @return an error code defined in {@link DCamRetCode} otherwise. + * + * @since 3.2 + * @version 1.0 + */ + ShutterBuffer([in] struct DHBase dhBase,[in] int streamId,[in] struct DCameraBuffer buffer); + + /** + * @brief Called to report metadata related to the distributed camera device. + * + * @param dhBase Distributed hardware device base info. + * @param result Indicates the metadata reported. + * + * @return Returns NO_ERROR if the operation is successful, + * @return an error code defined in {@link DCamRetCode} otherwise. + * + * @since 3.2 + * @version 1.0 + */ + OnSettingsResult([in] struct DHBase dhBase,[in] struct DCameraSettings result); + + /** + * @brief Called to notify some events from distributed camera SA service to distributed camera HDF service. + * + * @param dhBase Distributed hardware device base info. + * @param event Detail event contents. + * + * @return Returns NO_ERROR if the operation is successful, + * @return an error code defined in {@link DCamRetCode} otherwise. + * + * @since 3.2 + * @version 1.0 + */ + Notify([in] struct DHBase dhBase,[in] struct DCameraHDFEvent event); +} diff --git a/en/device_api/hdi/distributed_camera/v1_0/IDCameraProviderCallback.idl b/en/device_api/hdi/distributed_camera/v1_0/IDCameraProviderCallback.idl new file mode 100644 index 0000000000000000000000000000000000000000..1a42f7a4fe97ad9e5172f9054e7ebe998700dbde --- /dev/null +++ b/en/device_api/hdi/distributed_camera/v1_0/IDCameraProviderCallback.idl @@ -0,0 +1,156 @@ +/* + * Copyright (c) 2022 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + + /** + * @addtogroup Distributed Camera + * @{ + * + * @brief Provides APIs for the Distributed Camera module. + * + * You can use the APIs which are consistent with camera APIs to perform operations on + * distributed camera devices and streams, and implement various callbacks. + * Communicate with Source SA through IDCameraProvider to achieve distributed functionality. + * + * @since 3.2 + * @version 1.0 + */ + +/** + * @file IDCameraProviderCallback.idl + * + * @brief Declares callbacks for distributed camera SA service. The caller needs to implement the callbacks. + * + * @since 3.2 + * @version 1.0 + */ + +/** + * @brief Defines the package path of the distributed camera module APIs. + * + * @since 3.2 + * @version 1.0 + */ +package ohos.hdi.distributed_camera.v1_0; + +import ohos.hdi.distributed_camera.v1_0.DCameraTypes; + +/** + * @brief Define the callback operation for the Distributed Camera device. + * + * Perform operations such as creating channels, creating streams, capturing images, + * and updating settings on the Distributed Camera device. + */ +[callback] interface IDCameraProviderCallback { + /** + * @brief Create the transmission channel between the source device and the sink device. + * Open and initialize the distributed camera session. + * + * @param dhBase Distributed hardware device base info. + * + * @return Returns NO_ERROR if the operation is successful, + * @return an error code defined in {@link DCamRetCode} otherwise. + * + * @since 3.2 + * @version 1.0 + */ + OpenSession([in] struct DHBase dhBase); + + /** + * @brief Close the distributed camera session, and destroy the transmission channel between. + * the source device and the sink device. + * + * @param dhBase Distributed hardware device base info. + * + * @return Returns NO_ERROR if the operation is successful, + * @return an error code defined in {@link DCamRetCode} otherwise. + * + * @since 3.2 + * @version 1.0 + */ + CloseSession([in] struct DHBase dhBase); + + /** + * @brief Configures streams. + * + * @param dhBase Distributed hardware device base info. + * @param streamInfos Indicates the list of stream information, which is defined by {@link DCStreamInfo}. + * + * @return Returns NO_ERROR if the operation is successful, + * @return an error code defined in {@link DCamRetCode} otherwise. + * + * @since 3.2 + * @version 1.0 + */ + ConfigureStreams([in] struct DHBase dhBase,[in] struct DCStreamInfo[] streamInfos); + + /** + * @brief Releases streams. + * + * @param dhBase Distributed hardware device base info. + * @param streamIds Indicates the IDs of the streams to release. + * + * @return Returns NO_ERROR if the operation is successful, + * @return an error code defined in {@link DCamRetCode} otherwise. + * + * @since 3.2 + * @version 1.0 + */ + ReleaseStreams([in] struct DHBase dhBase,[in] int[] streamIds); + + /** + * @brief Start capture images. + * This function must be called after {@link ConfigStreams}. + * There are two image capture modes: continuous capture and single capture. + * + * @param dhBase Distributed hardware device base info. + * @param captureInfos Indicates the capture request configuration information. + * For details, see {@link DCCaptureInfo}. + * + * @return Returns NO_ERROR if the operation is successful, + * @return an error code defined in {@link DCamRetCode} otherwise. + * + * @since 3.2 + * @version 1.0 + */ + StartCapture([in] struct DHBase dhBase,[in] struct DCCaptureInfo[] captureInfos); + + /** + * @brief Stop capture images. + * + * @param dhBase Distributed hardware device base info. + * + * @return Returns NO_ERROR if the operation is successful, + * @return an error code defined in {@link DCamRetCode} otherwise. + * + * @since 3.2 + * @version 1.0 + */ + StopCapture([in] struct DHBase dhBase,[in] int[] streamIds); + + /** + * @brief Updates distributed camera device control parameters. + * + * @param dhBase Distributed hardware device base info. + * @param settings Indicates the camera parameters, including the sensor frame rate and 3A parameters. + * For details about the settings, see {@link DCameraSettings}. + * + * @return Returns NO_ERROR if the operation is successful, + * @return an error code defined in {@link DCamRetCode} otherwise. + * + * @since 3.2 + * @version 1.0 + */ + UpdateSettings([in] struct DHBase dhBase,[in] struct DCameraSettings[] settings); +} diff --git a/en/device_api/hdi/usb/v1_0/IUsbInterface.idl b/en/device_api/hdi/usb/v1_0/IUsbInterface.idl index b556b6663e3efba5b84768bf9d4955fa6797b722..df5778d108dc1b3deb38c08c9791f2ced5ceb35d 100644 --- a/en/device_api/hdi/usb/v1_0/IUsbInterface.idl +++ b/en/device_api/hdi/usb/v1_0/IUsbInterface.idl @@ -215,6 +215,21 @@ interface IUsbInterface { */ ReleaseInterface([in] struct UsbDev dev, [in] unsigned char interfaceid); + /** + * @brief Set USB device interface startup status. + * + * @param dev USB device address. For details, see {@link UsbDev}. + * @param interfaceid USB interface ID. + * @param disable Is the USB device interface disabled? True indicates disabled, false indicates not disabled. + * + * @return Returns 0 if the operation is successful. + * @return Returns a non-0 value if the operation fails. + * + * @since 3.2 + * @version 1.0 + */ + ManageInterface([in] struct UsbDev dev, [in] unsigned char interfaceid, [in] bool disable); + /** * @brief Sets the alternate settings for the specified interface of a USB device. This allows you to switch between * two interfaces with the same ID but different alternate settings. diff --git a/en/native_sdk/AbilityKit/ability_runtime/ability_runtime_common.h b/en/native_sdk/AbilityKit/ability_runtime/ability_runtime_common.h new file mode 100644 index 0000000000000000000000000000000000000000..d9e85da4dc2bcd16d9a650c3de70f363ce16ef55 --- /dev/null +++ b/en/native_sdk/AbilityKit/ability_runtime/ability_runtime_common.h @@ -0,0 +1,61 @@ +/* +* Copyright (C) 2024 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup AbilityRuntime + * @{ + * + * @brief Provides the error codes of the AbilityRuntime module. + * + * @syscap SystemCapability.Ability.AbilityRuntime.Core + * @since 13 + */ + +/** + * @file ability_runtime_common.h + * + * @brief Declares the error codes of the AbilityRuntime module. + * + * @library libability_runtime.so + * @kit AbilityKit + * @syscap SystemCapability.Ability.AbilityRuntime.Core + * @since 13 + */ + +#ifndef ABILITY_RUNTIME_COMMON_H +#define ABILITY_RUNTIME_COMMON_H + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Enumerates the error codes of the AbilityRuntime module. + * + * @since 13 + */ +typedef enum { + /** @error Operation successful. */ + ABILITY_RUNTIME_ERROR_CODE_NO_ERROR = 0, + /** @error Invalid parameter. */ + ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID = 401, +} AbilityRuntime_ErrorCode; + +#ifdef __cplusplus +} +#endif + +/** @} */ +#endif // ABILITY_RUNTIME_COMMON_H diff --git a/en/native_sdk/AbilityKit/ability_runtime/application_context.h b/en/native_sdk/AbilityKit/ability_runtime/application_context.h new file mode 100644 index 0000000000000000000000000000000000000000..cf676f75e25e0634ed12213374674aa03db1ac41 --- /dev/null +++ b/en/native_sdk/AbilityKit/ability_runtime/application_context.h @@ -0,0 +1,97 @@ +/* + * Copyright (c) 2024 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup AbilityRuntime + * @{ + * + * @brief Provides the APIs related to the application-level context. + * + * @syscap SystemCapability.Ability.AbilityRuntime.Core + * @since 13 + */ + +/** + * @file application_context.h + * + * @brief Declares the APIs related to the application-level context. + * + * @library libability_runtime.so + * @kit AbilityKit + * @syscap SystemCapability.Ability.AbilityRuntime.Core + * @since 13 + */ + +#ifndef ABILITY_RUNTIME_APPLICATION_CONTEXT_H +#define ABILITY_RUNTIME_APPLICATION_CONTEXT_H + +#include +#include +#include "ability_runtime_common.h" +#include "context_constant.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Obtains the cache directory of the application-level context. + * + * @param buffer Pointer to the buffer, which is used to receive the cache directory. + * @param bufferSize Buffer size, in bytes. + * @param writeLength Pointer to the length of the string written to the buffer when + * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} is returned. + * @return Returns one of the following error codes: + * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR}: The operation is successful. + * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID}: The passed-in value of buffer or writeLength + * is null, or the buffer size is less than the size of the string to be written. + * @since 13 + */ +AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetCacheDir( + char* buffer, int32_t bufferSize, int32_t* writeLength); + +/** + * @brief Obtains the data encryption level of the application-level context. + * + * @param areaMode Pointer to the encryption level of the received data. + * @return Returns one of the following error codes: + * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR}: The operation is successful. + * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID}: The passed-in value of areaMode is null. + * @since 13 + */ +AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetAreaMode(AbilityRuntime_AreaMode* areaMode); + +/** + * @brief Obtains the bundle name of the application. + * + * @param buffer Pointer to the buffer, which is used to receive the bundle name. + * @param bufferSize Buffer size, in bytes. + * @param writeLength Pointer to the length of the string written to the buffer when + * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR} is returned. + * @return Returns one of the following error codes: + * {@link ABILITY_RUNTIME_ERROR_CODE_NO_ERROR}: The operation is successful. + * {@link ABILITY_RUNTIME_ERROR_CODE_PARAM_INVALID}: The passed-in value of buffer or writeLength + * is null, or the buffer size is less than the size of the string to be written. + * @since 13 + */ +AbilityRuntime_ErrorCode OH_AbilityRuntime_ApplicationContextGetBundleName( + char* buffer, int32_t bufferSize, int32_t* writeLength); + +#ifdef __cplusplus +} // extern "C" +#endif + +/** @} */ +#endif // ABILITY_RUNTIME_APPLICATION_CONTEXT_H diff --git a/en/native_sdk/AbilityKit/ability_runtime/context_constant.h b/en/native_sdk/AbilityKit/ability_runtime/context_constant.h new file mode 100644 index 0000000000000000000000000000000000000000..2a0baff2701bdf25eaa2937ca812496ebe66dfd0 --- /dev/null +++ b/en/native_sdk/AbilityKit/ability_runtime/context_constant.h @@ -0,0 +1,93 @@ +/* + * Copyright (c) 2024 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup AbilityRuntime + * @{ + * + * @brief Provides the context constants of the AbilityRuntime module. + * + * @syscap SystemCapability.Ability.AbilityRuntime.Core + * @since 13 + */ + +/** + * @file context_constant.h + * + * @brief Declares the context constants of the AbilityRuntime module. + * + * @library libability_runtime.so + * @kit AbilityKit + * @syscap SystemCapability.Ability.AbilityRuntime.Core + * @since 13 + */ + +#ifndef ABILITY_RUNTIME_CONTEXT_CONSTANT_H +#define ABILITY_RUNTIME_CONTEXT_CONSTANT_H + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Enumerates the data encryption levels. + * + * @since 13 + */ +typedef enum { + /** + * Device-level encryption. Directories with this encryption level are accessible after the device is powered on. + */ + ABILITY_RUNTIME_AREA_MODE_EL1 = 0, + /** + * User-level encryption. Directories with this encryption level are accessible only after the device is powered on + * and the password is entered (for the first time). + */ + ABILITY_RUNTIME_AREA_MODE_EL2 = 1, + /** + * User-level encryption. The file permissions vary according to their scenarios. + * An open file is always readable and writable regardless of whether the screen is locked. + * When the screen is locked, a closed file cannot be opened, read, or written. When the screen is unlocked, + * such a file can be opened, read, and written. + * When the screen is locked, a file can be created and then opened and written but not read. When the screen is + * unlocked, a file can be created and then opened, read, and written. + */ + ABILITY_RUNTIME_AREA_MODE_EL3 = 2, + /** + * User-level encryption. The file permissions vary according to their scenarios. + * When the screen is locked, an open file is readable and writable in FEB2.0, but not in FEB3.0. When the screen is + * unlocked, such a file is always readable and writable. + * When the screen is locked, a closed file cannot be opened, read, or written. When the screen is unlocked, such + * a file can be opened, read, and written. + * When the screen is locked, a file cannot be created. When the screen is unlocked, a file can be created and then + * opened, read, and written. + */ + ABILITY_RUNTIME_AREA_MODE_EL4 = 3, + /** + * Application-level encryption. The file permissions vary according to their scenarios. + * An open file is always readable and writable regardless of whether the screen is locked. + * When the screen is locked, a closed file can be opened, read, and written only if a DataAccessLock (JS API) is + * obtained. When the screen is unlocked, such a file can be opened, read, and written. + * A file can be created and then opened, read, and written regardless of whether the screen is locked. + */ + ABILITY_RUNTIME_AREA_MODE_EL5 = 4, +} AbilityRuntime_AreaMode; + +#ifdef __cplusplus +} // extern "C" +#endif + +/** @} */ +#endif // ABILITY_RUNTIME_CONTEXT_CONSTANT_H diff --git a/en/native_sdk/IPCKit/ipc_cparcel.h b/en/native_sdk/IPCKit/ipc_cparcel.h new file mode 100644 index 0000000000000000000000000000000000000000..8cd6e1932e41f55e2b580cb23ca7d260100c23eb --- /dev/null +++ b/en/native_sdk/IPCKit/ipc_cparcel.h @@ -0,0 +1,507 @@ +/* + * Copyright (c) 2024 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#ifndef CAPI_INCLUDE_IPC_CPARCEL_H +#define CAPI_INCLUDE_IPC_CPARCEL_H + +/** + * @addtogroup OHIPCParcel + * @{ + * + * @brief Defines C interfaces for IPC serialization and deserialization. + * + * @syscap SystemCapability.Communication.IPC.Core + * @since 12 + */ + +/** + * @file ipc_cparcel.h + * + * @brief Defines C interfaces for IPC serialization and deserialization. + * + * @library libipc_capi.so + * @syscap SystemCapability.Communication.IPC.Core + * @since 12 + */ + +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** +* @brief Defines an IPC serialized object. +* +* @syscap SystemCapability.Communication.IPC.Core +* @since 12 +*/ +struct OHIPCParcel; + +/** +* @brief Defines an IPC remote proxy object. +* +* @syscap SystemCapability.Communication.IPC.Core +* @since 12 +*/ +struct OHIPCRemoteProxy; + +/** +* @brief Defines an IPC remote service object. +* +* @syscap SystemCapability.Communication.IPC.Core +* @since 12 +*/ +struct OHIPCRemoteStub; + +/** + * @brief Allocates memory. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param len Length of the memory to allocate. + * @return Returns the address of the memory allocated if the operation is successful; returns NULL otherwise. + * @since 12 + */ +typedef void* (*OH_IPC_MemAllocator)(int32_t len); + +/** + * @brief Creates an OHIPCParcel object, which cannot exceed 204,800 bytes. + * + * @syscap SystemCapability.Communication.IPC.Core + * @return Returns the pointer to the OHIPCParcel object created if the operation is successful; + * returns NULL otherwise. + * @since 12 + */ +OHIPCParcel* OH_IPCParcel_Create(void); + +/** + * @brief Destroys an OHIPCParcel object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the OHIPCParcel object to destroy. + * @since 12 + */ +void OH_IPCParcel_Destroy(OHIPCParcel *parcel); + +/** + * @brief Obtains the size of the data contained in an OHIPCParcel object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @return Returns the data size obtained if the operation is successful.\n + * Returns -1 if invalid parameters are found. + * @since 12 + */ +int OH_IPCParcel_GetDataSize(const OHIPCParcel *parcel); + +/** + * @brief Obtains the number of bytes that can be written to an OHIPCParcel object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @return Returns the number of bytes that can be written to the OHIPCParcel object. \n + * Returns -1 if invalid parameters are found. + * @since 12 + */ +int OH_IPCParcel_GetWritableBytes(const OHIPCParcel *parcel); + +/** + * @brief Obtains the number of bytes that can be read from an OHIPCParcel object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @return Returns the number of bytes that can be read from the OHIPCParcel object. \n + * Returns -1 if invalid parameters are found. + * @since 12 + */ +int OH_IPCParcel_GetReadableBytes(const OHIPCParcel *parcel); + +/** + * @brief Obtains the position where data is read in an OHIPCParcel object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @return Returns the position obtained if the operation is successful. \n + * Returns -1 if invalid parameters are found. + * @since 12 + */ +int OH_IPCParcel_GetReadPosition(const OHIPCParcel *parcel); + +/** + * @brief Obtains the position where data is written in an OHIPCParcel object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @return Returns the position obtained if the operation is successful. \n + * Returns -1 if invalid parameters are found. + * @since 12 + */ +int OH_IPCParcel_GetWritePosition(const OHIPCParcel *parcel); + +/** + * @brief Resets the position to read data in an IPC parcel. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param newReadPos New position to read data. The value ranges from 0 to the current data size. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. + * @since 12 + */ +int OH_IPCParcel_RewindReadPosition(OHIPCParcel *parcel, uint32_t newReadPos); + +/** + * @brief Resets the position to write data in an OHIPCParcel object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param newWritePos New position to write data. The value ranges from 0 to the current data size. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. + * @since 12 + */ +int OH_IPCParcel_RewindWritePosition(OHIPCParcel *parcel, uint32_t newWritePos); + +/** + * @brief Writes an int8_t value to an OHIPCParcel object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param value Value to write. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the data write operation fails. + * @since 12 + */ +int OH_IPCParcel_WriteInt8(OHIPCParcel *parcel, int8_t value); + +/** + * @brief Reads an int8_t value from an OHIPCParcel object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param value Pointer to the data to read. It cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR} if the read operation fails. + * @since 12 + */ +int OH_IPCParcel_ReadInt8(const OHIPCParcel *parcel, int8_t *value); + +/** + * @brief Writes an int16_t value to an OHIPCParcel object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param value Value to write. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the data write operation fails. + * @since 12 + */ +int OH_IPCParcel_WriteInt16(OHIPCParcel *parcel, int16_t value); + +/** + * @brief Reads an int16_t value from an OHIPCParcel object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param value Pointer to the data to read. It cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR} if the read operation fails. + * @since 12 + */ +int OH_IPCParcel_ReadInt16(const OHIPCParcel *parcel, int16_t *value); + +/** + * @brief Writes an int32_t value to an OHIPCParcel object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param value Value to write. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the data write operation fails. + * @since 12 + */ +int OH_IPCParcel_WriteInt32(OHIPCParcel *parcel, int32_t value); + +/** + * @brief Reads an int32_t value from an OHIPCParcel object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param value Pointer to the data to read. It cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR} if the read operation fails. + * @since 12 + */ +int OH_IPCParcel_ReadInt32(const OHIPCParcel *parcel, int32_t *value); + +/** + * @brief Writes an int64_t value to an OHIPCParcel object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param value Value to write. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the data write operation fails. + * @since 12 + */ +int OH_IPCParcel_WriteInt64(OHIPCParcel *parcel, int64_t value); + +/** + * @brief Reads an int64_t value from an OHIPCParcel object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param value Pointer to the data to read. It cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR} if the read operation fails. + * @since 12 + */ +int OH_IPCParcel_ReadInt64(const OHIPCParcel *parcel, int64_t *value); + +/** + * @brief Writes a float value to an OHIPCParcel object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param value Value to write. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the data write operation fails. + * @since 12 + */ +int OH_IPCParcel_WriteFloat(OHIPCParcel *parcel, float value); + +/** + * @brief Reads a float value from an OHIPCParcel object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param value Pointer to the data to read. It cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR} if the read operation fails. + * @since 12 + */ +int OH_IPCParcel_ReadFloat(const OHIPCParcel *parcel, float *value); + +/** + * @brief Writes a double value to an OHIPCParcel object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param value Value to write. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the data write operation fails. + * @since 12 + */ +int OH_IPCParcel_WriteDouble(OHIPCParcel *parcel, double value); + +/** + * @brief Reads a double value from an OHIPCParcel object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param value Pointer to the data to read. It cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR} if the read operation fails. + * @since 12 + */ +int OH_IPCParcel_ReadDouble(const OHIPCParcel *parcel, double *value); + +/** + * @brief Writes a string including a string terminator to an OHIPCParcel object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param str String to write, which cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the data write operation fails. + * @since 12 + */ +int OH_IPCParcel_WriteString(OHIPCParcel *parcel, const char *str); + +/** + * @brief Reads a string from an OHIPCParcel object. You can obtain the length of the string from strlen. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @return Returns the address of the string read if the operation is successful; + * returns NULL if the operation fails or invalid parameters are found. + * @since 12 + */ +const char* OH_IPCParcel_ReadString(const OHIPCParcel *parcel); + +/** + * @brief Writes data of the specified length from the memory to an OHIPCParcel object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param buffer Pointer to the address of the memory information to write. + * @param len Length of the data to write. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the data write operation fails. + * @since 12 + */ +int OH_IPCParcel_WriteBuffer(OHIPCParcel *parcel, const uint8_t *buffer, int32_t len); + +/** + * @brief Reads memory information of the specified length from an OHIPCParcel object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param len Length of the memory to be read. + * @return Returns the memory address read if the operation is successful; + * returns NULL if invalid parameters are found or len exceeds the readable length of parcel. + * @since 12 + */ +const uint8_t* OH_IPCParcel_ReadBuffer(const OHIPCParcel *parcel, int32_t len); + +/** + * @brief Writes an OHIPCRemoteStub object to an OHIPCParcel object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param stub Pointer to the OHIPCRemoteStub object to write. It cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the data write operation fails. + * @since 12 + */ +int OH_IPCParcel_WriteRemoteStub(OHIPCParcel *parcel, const OHIPCRemoteStub *stub); + +/** + * @brief Reads the OHIPCRemoteStub object from an OHIPCParcel object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @return Returns the pointer to the OHIPCRemoteStub object read if the operation is successful; + * returns NULL otherwise. + * @since 12 + */ +OHIPCRemoteStub* OH_IPCParcel_ReadRemoteStub(const OHIPCParcel *parcel); + +/** + * @brief Writes an OHIPCRemoteProxy object to an OHIPCParcel object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param proxy Pointer to the OHIPCRemoteProxy object to write. It cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the data write operation fails. + * @since 12 + */ +int OH_IPCParcel_WriteRemoteProxy(OHIPCParcel *parcel, const OHIPCRemoteProxy *proxy); + +/** + * @brief Reads the OHIPCRemoteProxy object from an OHIPCParcel object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @return Returns the pointer to the OHIPCRemoteProxy object read if the operation is successful; + * returns NULL otherwise. + * @since 12 + */ +OHIPCRemoteProxy* OH_IPCParcel_ReadRemoteProxy(const OHIPCParcel *parcel); + +/** + * @brief Writes a file descriptor to an OHIPCParcel object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param fd File descriptor to write. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the data write operation fails. + * @since 12 + */ +int OH_IPCParcel_WriteFileDescriptor(OHIPCParcel *parcel, int32_t fd); + +/** + * @brief Reads a file descriptor from an OHIPCParcel object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param fd Pointer to the file descriptor to read. It cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR} if the read operation fails. + * @since 12 + */ +int OH_IPCParcel_ReadFileDescriptor(const OHIPCParcel *parcel, int32_t *fd); + +/** + * @brief Appends data to an OHIPCParcel object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param data Pointer to the data to append. It cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the operation fails. + * @since 12 + */ +int OH_IPCParcel_Append(OHIPCParcel *parcel, const OHIPCParcel *data); + +/** + * @brief Writes an interface token to an OHIPCParcel object for interface identity verification. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param token Pointer to the interface token to write. It cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_WRITE_ERROR} if the data write operation fails. + * @since 12 + */ +int OH_IPCParcel_WriteInterfaceToken(OHIPCParcel *parcel, const char *token); + +/** + * @brief Reads an interface token from an OHIPCParcel object for interface identity verification. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param parcel Pointer to the target OHIPCParcel object. It cannot be NULL. + * @param token Pointer to the address of the memory for storing the interface token. + * The memory is allocated by the allocator provided by the user and needs to be released. This pointer cannot be NULL. + * If an error code is returned, you still need to check whether the memory is empty and release the memory. + * Otherwise, memory leaks may occur. + * @param len Pointer to the length of the interface token read, including the terminator. It cannot be NULL. + * @param allocator Memory allocator specified by the user for allocating memory for token. It cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR} if the read operation fails. + * @since 12 + */ +int OH_IPCParcel_ReadInterfaceToken(const OHIPCParcel *parcel, char **token, int32_t *len, + OH_IPC_MemAllocator allocator); + +#ifdef __cplusplus +} +#endif + +/** @} */ +#endif diff --git a/en/native_sdk/IPCKit/ipc_cremote_object.h b/en/native_sdk/IPCKit/ipc_cremote_object.h new file mode 100644 index 0000000000000000000000000000000000000000..77127a429ab49256c1960a1244e0377b2325c88d --- /dev/null +++ b/en/native_sdk/IPCKit/ipc_cremote_object.h @@ -0,0 +1,278 @@ +/* + * Copyright (c) 2024 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#ifndef CAPI_INCLUDE_IPC_CREMOTE_OBJECT_H +#define CAPI_INCLUDE_IPC_CREMOTE_OBJECT_H + +/** + * @addtogroup OHIPCRemoteObject + * @{ + * + * @brief Provides C interfaces for creating and destroying a remote object, transferring data, + * and observing the dead status of a remote object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @since 12 + */ + +/** + * @file ipc_cremote_object.h + * + * @brief Defines C interfaces for creating and destroying a remote object, transferring data, + * and observing the dead status of a remote object. + * + * @library libipc_capi.so + * @syscap SystemCapability.Communication.IPC.Core + * @since 12 + */ + +#include + +#include "ipc_cparcel.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** +* @brief Defines an OHIPCDeathRecipient object, which is used to receive a notification +* when the OHIPCRemoteStub object dies unexpectedly. +* +* @syscap SystemCapability.Communication.IPC.Core +* @since 12 +*/ +struct OHIPCDeathRecipient; + +/** + * @brief Called to process the remote data request at the stub. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param code Custom command word for communication, in the range [0x01, 0x00ffffff]. + * @param data Pointer to the request data object. It cannot be NULL or released in the function. + * @param reply Pointer to the response data object. It cannot be NULL or released in the function. + * If this function returns an error, data cannot be written to this parameter. + * @param userData Pointer to the user data. It can be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns a custom error code in the range [1909001, 1909999] or a system error code otherwise. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_INVALID_USER_ERROR_CODE} if the custom error code is out of the value range. + * @since 12 + */ +typedef int (*OH_OnRemoteRequestCallback)(uint32_t code, const OHIPCParcel *data, + OHIPCParcel *reply, void *userData); + +/** + * @brief Called when an observed object is destroyed. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param userData Pointer to the user data. It can be NULL. + * @since 12 + */ +typedef void (*OH_OnRemoteDestroyCallback)(void *userData); + +/** + * @brief Creates an OHIPCRemoteStub object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param descriptor Pointer to the descriptor of the OHIPCRemoteStub object to create. It cannot be NULL. + * @param requestCallback Callback used to process the data request. It cannot be NULL. + * @param destroyCallback Callback to be invoked when the object is destroyed. It can be NULL. + * @param userData Pointer to the user data. It can be NULL. + * @return Returns the pointer to the OHIPCRemoteStub object created if the operation is successful; + * returns NULL otherwise. + * @since 12 + */ +OHIPCRemoteStub* OH_IPCRemoteStub_Create(const char *descriptor, OH_OnRemoteRequestCallback requestCallback, + OH_OnRemoteDestroyCallback destroyCallback, void *userData); + +/** + * @brief Destroys an OHIPCRemoteStub object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param stub Pointer to the OHIPCRemoteStub object to destroy. + * @since 12 + */ +void OH_IPCRemoteStub_Destroy(OHIPCRemoteStub *stub); + +/** + * @brief Destroys an OHIPCRemoteProxy object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param proxy Pointer to the OHIPCRemoteProxy object to destroy. + * @since 12 + */ +void OH_IPCRemoteProxy_Destroy(OHIPCRemoteProxy *proxy); + +/** + * @brief Enumerates the IPC request modes. + * + * @since 12 + */ +enum OH_IPC_RequestMode { + /** Synchronous request. */ + OH_IPC_REQUEST_MODE_SYNC = 0, + /** Asynchronous request. */ + OH_IPC_REQUEST_MODE_ASYNC = 1, +}; + +/** + * @brief Defines the IPC message options. + * + * @since 12 + */ +#pragma pack(4) +struct OH_IPC_MessageOption { + /** Message request mode. */ + OH_IPC_RequestMode mode; + /** Parameter reserved for RPC, which is invalid for IPC. */ + uint32_t timeout; + /** Reserved parameter, which must be NULL. */ + void* reserved; +}; +#pragma pack() + +/** + * @brief Sends an IPC message. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param proxy Pointer to the OHIPCRemoteProxy object. It cannot be NULL. + * @param code Custom IPC command word, in the range [0x01, 0x00ffffff]. + * @param data Pointer to the request data object. It cannot be NULL. + * @param reply Pointer to the response data object. It cannot be NULL in the case of a synchronous request, + * and can be NULL in the case of an asynchronous request. + * @param option Pointer to the message options. It can be NULL, which indicates a synchronous request. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if invalid parameters are found. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_DEAD_REMOTE_OBJECT} if the OHIPCRemoteStub object is dead. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CODE_OUT_OF_RANGE} if the error code is out of the value range. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_INNER_ERROR} or a custom error code in other cases. + * @since 12 + */ +int OH_IPCRemoteProxy_SendRequest(const OHIPCRemoteProxy *proxy, uint32_t code, const OHIPCParcel *data, + OHIPCParcel *reply, const OH_IPC_MessageOption *option); + +/** + * @brief Obtains the interface descriptor from the stub. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param proxy Pointer to the OHIPCRemoteProxy object. It cannot be NULL. + * @param descriptor Double pointer to the address of the memory for holding the interface descriptor. + * The memory is allocated by the allocator provided by the user and needs to be released. This pointer cannot be NULL. + * If an error code is returned, you still need to check whether the memory is empty and release the memory. + * Otherwise, memory leaks may occur. + * @param len Pointer to the length of the data to be written to the descriptor, including the terminator. + * This parameter cannot be NULL. + * @param allocator Memory allocator specified by the user for allocating memory for descriptor. + * It cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if incorrect parameters are found. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_DEAD_REMOTE_OBJECT} if the OHIPCRemoteStub object is dead. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_MEM_ALLOCATOR_ERROR} if memory allocation fails. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_PARCEL_READ_ERROR} if the data in the serialized object failed to be read. + * @since 12 + */ +int OH_IPCRemoteProxy_GetInterfaceDescriptor(OHIPCRemoteProxy *proxy, char **descriptor, int32_t *len, + OH_IPC_MemAllocator allocator); + +/** + * @brief Called when the OHIPCRemoteStub object dies unexpectedly. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param userData Pointer to the user data. It can be NULL. + * @since 12 + */ +typedef void (*OH_OnDeathRecipientCallback)(void *userData); + +/** + * @brief Called when the OHIPCDeathRecipient object is destroyed. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param userData Pointer to the user data. It can be NULL. + * @since 12 + */ +typedef void (*OH_OnDeathRecipientDestroyCallback)(void *userData); + +/** + * @brief Creates an OHIPCDeathRecipient object, which allows a notification to be received + * when the OHIPCRemoteStub object dies unexpectedly. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param deathRecipientCallback Callback to be invoked when the OHIPCRemoteStub object is dead. + * It cannot be NULL. + * @param destroyCallback Callback to be invoked when the object is destroyed. It can be NULL. + * @param userData Pointer to the user data. It can be NULL. + * @return Returns the pointer to the OHIPCDeathRecipient object created if the operation is successful; + * returns NULL otherwise. + * @since 12 + */ +OHIPCDeathRecipient* OH_IPCDeathRecipient_Create(OH_OnDeathRecipientCallback deathRecipientCallback, + OH_OnDeathRecipientDestroyCallback destroyCallback, void *userData); + +/** + * @brief Destroys an OHIPCDeathRecipient object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param recipient Pointer to the OHIPCDeathRecipient object to destroy. + * @since 12 + */ +void OH_IPCDeathRecipient_Destroy(OHIPCDeathRecipient *recipient); + +/** + * @brief Subscribes to the death of an OHIPCRemoteStub object for an OHIPCRemoteProxy object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param proxy Pointer to the OHIPCRemoteProxy object that subscribes to the death notification. + * It cannot be NULL. + * @param recipient Pointer to the object that receives the death notification of the OHIPCRemoteStub object. + * It cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if incorrect parameters are found. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_INNER_ERROR} in other cases. + * @since 12 + */ +int OH_IPCRemoteProxy_AddDeathRecipient(OHIPCRemoteProxy *proxy, OHIPCDeathRecipient *recipient); + +/** + * @brief Unsubscribes from the death of the OHIPCRemoteStub object for an OHIPCRemoteProxy object. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param proxy Pointer to the OHIPCRemoteProxy object that unsubscribes from the death notification. + * It cannot be NULL. + * @param recipient Pointer to the object that receives the death notification of the OHIPCRemoteStub object. + * It cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if incorrect parameters are found. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_INNER_ERROR} in other cases. + * @since 12 + */ +int OH_IPCRemoteProxy_RemoveDeathRecipient(OHIPCRemoteProxy *proxy, OHIPCDeathRecipient *recipient); + +/** + * @brief Checks whether the OHIPCRemoteStub object corresponding to the OHIPCRemoteProxy object is dead. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param proxy Pointer to the OHIPCRemoteProxy object to check. It cannot be NULL. + * @return Returns 1 if the OHIPCRemoteStub object is dead; returns 0 otherwise. + * If an invalid parameter is found, the OHIPCRemoteStub object does not exist. + * In this case, 1 is returned. + * @since 12 + */ +int OH_IPCRemoteProxy_IsRemoteDead(const OHIPCRemoteProxy *proxy); + +#ifdef __cplusplus +} +#endif + +/** @} */ +#endif diff --git a/en/native_sdk/IPCKit/ipc_cskeleton.h b/en/native_sdk/IPCKit/ipc_cskeleton.h new file mode 100644 index 0000000000000000000000000000000000000000..bc70d2bb392cd7a955b472863366df5369067b48 --- /dev/null +++ b/en/native_sdk/IPCKit/ipc_cskeleton.h @@ -0,0 +1,180 @@ +/* + * Copyright (c) 2024 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#ifndef CAPI_INCLUDE_IPC_CSKELETON_H +#define CAPI_INCLUDE_IPC_CSKELETON_H + +/** + * @addtogroup OHIPCSkeleton + * @{ + * + * @brief Provides C interfaces for managing the token IDs, credentials, process IDs (PIDs), + * user IDs (UIDs), and thread pool in the IPC framework. + * + * @syscap SystemCapability.Communication.IPC.Core + * @since 12 + */ + +/** + * @file ipc_cskeleton.h + * + * @brief Defines C interfaces for managing the token IDs, credentials, PIDs, UIDs, and thread + * pool in the IPC framework. + * + * @library libipc_capi.so + * @syscap SystemCapability.Communication.IPC.Core + * @since 12 + */ + +#include + +#include "ipc_cparcel.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Joints this thread to the IPC worker thread pool. + * + * @syscap SystemCapability.Communication.IPC.Core + * @since 12 + */ +void OH_IPCSkeleton_JoinWorkThread(void); + +/** + * @brief Stops this thread. + * + * @syscap SystemCapability.Communication.IPC.Core + * @since 12 + */ +void OH_IPCSkeleton_StopWorkThread(void); + +/** + * @brief Obtains the token ID of the caller. This function must be called in the IPC context. + * Otherwise, the local token ID is returned. + * + * @syscap SystemCapability.Communication.IPC.Core + * @return Returns the token ID of the caller. + * @since 12 + */ +uint64_t OH_IPCSkeleton_GetCallingTokenId(void); + +/** + * @brief Obtains the token ID of the first caller. + * + * @syscap SystemCapability.Communication.IPC.Core + * @return Returns the token ID obtained. + * @since 12 + */ +uint64_t OH_IPCSkeleton_GetFirstTokenId(void); + +/** + * @brief Obtains the local token ID. + * + * @syscap SystemCapability.Communication.IPC.Core + * @return Returns the token ID obtained. + * @since 12 + */ +uint64_t OH_IPCSkeleton_GetSelfTokenId(void); + +/** + * @brief Obtains the process ID of the caller. This function must be called in the IPC context. + * Otherwise, the current process ID is returned. + * + * @syscap SystemCapability.Communication.IPC.Core + * @return Returns the process ID of the caller. + * @since 12 + */ +uint64_t OH_IPCSkeleton_GetCallingPid(void); + +/** + * @brief Obtains the UID of the caller. This function must be called in the IPC context. + * Otherwise, the current UID is returned. + * + * @syscap SystemCapability.Communication.IPC.Core + * @return Returns the UID of the caller. + * @since 12 + */ +uint64_t OH_IPCSkeleton_GetCallingUid(void); + +/** + * @brief Checks whether a local calling is being made. + * + * @syscap SystemCapability.Communication.IPC.Core + * @return Returns 1 if a local calling is in progress; returns 0 otherwise. + * @since 12 + */ +int OH_IPCSkeleton_IsLocalCalling(void); + +/** + * @brief Sets the maximum number of worker threads. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param maxThreadNum Maximum number of worker threads to set. The default value is 16. + * The value range is [1, 32]. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if incorrect parameters are found. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_INNER_ERROR} in other cases. + * @since 12 + */ +int OH_IPCSkeleton_SetMaxWorkThreadNum(const int maxThreadNum); + +/** + * @brief Resets the caller identity credential (including the token ID, UID, and PID) to that of this process and + * returns the caller credential information. + * The identity information is used in OH_IPCSkeleton_SetCallingIdentity. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param identity Pointer to the address of the memory for holding the caller identity information. + * The memory is allocated by the allocator provided by the user and needs to be released. This pointer cannot be NULL. + * @param len Pointer to the length of the identity information. It cannot be NULL. + * @param allocator Memory allocator specified by the user for allocating memory for identity. It cannot be NULL. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if incorrect parameters are found. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_MEM_ALLOCATOR_ERROR} if memory allocation fails. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_INNER_ERROR} in other cases. + * @since 12 + */ +int OH_IPCSkeleton_ResetCallingIdentity(char **identity, int32_t *len, OH_IPC_MemAllocator allocator); + +/** + * @brief Sets the caller credential information to the IPC context. + * + * @syscap SystemCapability.Communication.IPC.Core + * @param identity Pointer to the caller identity, which cannot be NULL. + * The value is returned by OH_IPCSkeleton_ResetCallingIdentity. + * @return Returns {@link OH_IPC_ErrorCode#OH_IPC_SUCCESS} if the operation is successful. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_CHECK_PARAM_ERROR} if incorrect parameters are found. \n + * Returns {@link OH_IPC_ErrorCode#OH_IPC_INNER_ERROR} in other cases. + * @since 12 + */ +int OH_IPCSkeleton_SetCallingIdentity(const char *identity); + +/** + * @brief Checks whether an IPC request is being handled. + * + * @syscap SystemCapability.Communication.IPC.Core + * @return Returns 1 if an IPC request is being handled; returns 0 otherwise. + * @since 12 + */ +int OH_IPCSkeleton_IsHandlingTransaction(void); + +#ifdef __cplusplus +} +#endif + +/** @} */ +#endif diff --git a/en/native_sdk/IPCKit/ipc_error_code.h b/en/native_sdk/IPCKit/ipc_error_code.h new file mode 100644 index 0000000000000000000000000000000000000000..62f8f89ab726e7c7759bcc2cf36a00deac08635f --- /dev/null +++ b/en/native_sdk/IPCKit/ipc_error_code.h @@ -0,0 +1,74 @@ +/* + * Copyright (c) 2024 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#ifndef CAPI_INCLUDE_IPC_ERROR_CODE_H +#define CAPI_INCLUDE_IPC_ERROR_CODE_H + +/** + * @addtogroup OHIPCErrorCode + * @{ + * + * @brief Provides IPC error codes. + * + * @syscap SystemCapability.Communication.IPC.Core + * @since 12 + */ + +/** + * @file ipc_error_code.h + * + * @brief Defines IPC error codes. + * + * @library libipc_capi.so + * @syscap SystemCapability.Communication.IPC.Core + * @since 12 + */ + +/** +* @brief Enumerates IPC error codes. +* +* @since 12 +*/ +enum OH_IPC_ErrorCode { + /** Execution successful. */ + OH_IPC_SUCCESS = 0, + /** Start error code. */ + OH_IPC_ERROR_CODE_BASE = 1901000, + /** Invalid parameters. */ + OH_IPC_CHECK_PARAM_ERROR = OH_IPC_ERROR_CODE_BASE, + /** Failed to write data to the serialized object. */ + OH_IPC_PARCEL_WRITE_ERROR = OH_IPC_ERROR_CODE_BASE + 1, + /** Failed to read data from the serialized object. */ + OH_IPC_PARCEL_READ_ERROR = OH_IPC_ERROR_CODE_BASE + 2, + /** Failed to allocate memory. */ + OH_IPC_MEM_ALLOCATOR_ERROR = OH_IPC_ERROR_CODE_BASE + 3, + /** The command word is out of the value range [0x01,0x00ffffff]. */ + OH_IPC_CODE_OUT_OF_RANGE = OH_IPC_ERROR_CODE_BASE + 4, + /** The remote object is dead. */ + OH_IPC_DEAD_REMOTE_OBJECT = OH_IPC_ERROR_CODE_BASE + 5, + /** The custom error code is out of range [1900001, 1999999]. */ + OH_IPC_INVALID_USER_ERROR_CODE = OH_IPC_ERROR_CODE_BASE + 6, + /** IPC internal error. */ + OH_IPC_INNER_ERROR = OH_IPC_ERROR_CODE_BASE + 7, + /** Maximum error code. */ + OH_IPC_ERROR_CODE_MAX = OH_IPC_ERROR_CODE_BASE + 1000, + /** Minimum value for a custom error code. */ + OH_IPC_USER_ERROR_CODE_MIN = 1909000, + /** Maximum value for a custom error code. */ + OH_IPC_USER_ERROR_CODE_MAX = 1909999, +}; + +/** @} */ +#endif diff --git a/en/native_sdk/IPCKit/ipc_kit.h b/en/native_sdk/IPCKit/ipc_kit.h new file mode 100644 index 0000000000000000000000000000000000000000..71b0aa4956464ce2465fc8d17124093be4ccb679 --- /dev/null +++ b/en/native_sdk/IPCKit/ipc_kit.h @@ -0,0 +1,45 @@ +/* + * Copyright (c) 2024 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#ifndef CAPI_INCLUDE_IPC_KIT_H +#define CAPI_INCLUDE_IPC_KIT_H + +/** + * @addtogroup IPCKit + * @{ + * + * @brief Provides an entry to the IPC header files for you to reference. + * + * @syscap SystemCapability.Communication.IPC.Core + * @since 12 + */ + +/** + * @file ipc_kit.h + * + * @brief Provides an entry to the IPC header files for you to reference. + * + * @library libipc_capi.so + * @syscap SystemCapability.Communication.IPC.Core + * @since 12 + */ + +#include "ipc_error_code.h" +#include "ipc_cparcel.h" +#include "ipc_cremote_object.h" +#include "ipc_cskeleton.h" + +/** @} */ +#endif diff --git a/en/native_sdk/ability/ability_runtime/child_process/native_child_process.h b/en/native_sdk/ability/ability_runtime/child_process/native_child_process.h new file mode 100644 index 0000000000000000000000000000000000000000..6378f7776947512c1791879d7a744c69270ecc76 --- /dev/null +++ b/en/native_sdk/ability/ability_runtime/child_process/native_child_process.h @@ -0,0 +1,181 @@ +/* + * Copyright (c) 2024 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#ifndef OHOS_ABILITY_RUNTIME_C_NATIVE_CHILD_PROCESS_H +#define OHOS_ABILITY_RUNTIME_C_NATIVE_CHILD_PROCESS_H + +#include "IPCKit/ipc_cparcel.h" + +/** + * @addtogroup ChildProcess + * @{ + * + * @brief Provides the APIs to manage child processes. + * + * @syscap SystemCapability.Ability.AbilityRuntime.Core + * @since 12 + */ + +/** + * @file native_child_process.h + * + * @brief Declares the APIs used to create a native child process and establish an IPC channel between the parent and + * child processes. + * + * @library libchild_process.so + * @syscap SystemCapability.Ability.AbilityRuntime.Core + * @since 12 + */ + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Enumerates the error codes used by the native child process module. + * @since 12 + */ +typedef enum Ability_NativeChildProcess_ErrCode { + /** + * @error Operation successful. + */ + NCP_NO_ERROR = 0, + + /** + * @error Invalid parameter. + */ + NCP_ERR_INVALID_PARAM = 401, + + /** + * @error Creating a native child process is not supported. + */ + NCP_ERR_NOT_SUPPORTED = 801, + + /** + * @error Internal error. + */ + NCP_ERR_INTERNAL = 16000050, + + /** + * @error A new child process cannot be created during the startup of another native child process. + * You can try again after the child process is started. + */ + NCP_ERR_BUSY = 16010001, + + /** + * @error Starting the native child process times out. + */ + NCP_ERR_TIMEOUT = 16010002, + + /** + * @error Server error. + */ + NCP_ERR_SERVICE_ERROR = 16010003, + + /** + * @error The multi-process mode is disabled. A child process cannot be started. + */ + NCP_ERR_MULTI_PROCESS_DISABLED = 16010004, + + /** + * @error A process cannot be created in a child process. + */ + NCP_ERR_ALREADY_IN_CHILD = 16010005, + + /** + * @error The number of native child processes reaches the maximum. + */ + NCP_ERR_MAX_CHILD_PROCESSES_REACHED = 16010006, + + /** + * @error The child process fails to load the dynamic library because the file does not exist + * or the corresponding method is not implemented or exported. + */ + NCP_ERR_LIB_LOADING_FAILED = 16010007, + + /** + * @error The child process fails to call the OnConnect method of the dynamic library. + * An invalid IPC object pointer may be returned. + */ + NCP_ERR_CONNECTION_FAILED = 16010008, +} Ability_NativeChildProcess_ErrCode; + + +/** + * @brief Defines a callback function for notifying the child process startup result. + * + * @param errCode Error code corresponding to the callback function. The following values are available: + * {@link NCP_NO_ERROR} if the child process is created successfully.\n + * {@link NCP_ERR_LIB_LOADING_FAILED} if loading the dynamic library file fails or the necessary export function + * is not implemented in the dynamic library.\n + * {@link NCP_ERR_CONNECTION_FAILED} if the OnConnect method implemented in the dynamic library does not return + * a valid IPC stub pointer.\n + * For details, see {@link Ability_NativeChildProcess_ErrCode}. + * @param remoteProxy Pointer to the IPC object of the child process. If an exception occurs, the value may be nullptr. + * The object must be released by calling {@link OH_IPCRemoteProxy_Destory} when it is no longer needed. + * @see OH_Ability_CreateNativeChildProcess + * @see OH_IPCRemoteProxy_Destory + * @since 12 + */ +typedef void (*OH_Ability_OnNativeChildProcessStarted)(int errCode, OHIPCRemoteProxy *remoteProxy); + +/** + * @brief Creates a child process, loads the specified dynamic library file, and returns the startup result + * asynchronously through a callback parameter. + * The callback notification is an independent thread. When implementing the callback function, + * pay attention to thread synchronization and do not perform time-consuming operations to avoid long-time blocking. + * + * The dynamic library specified must implement and export the following functions:\n + * 1. OHIPCRemoteStub* NativeChildProcess_OnConnect()\n + * 2. void NativeChildProcess_MainProc()\n + * + * The processing logic sequence is shown in the following pseudocode: \n + * Main process: \n + * 1. OH_Ability_CreateNativeChildProcess(libName, onProcessStartedCallback)\n + * Child process: \n + * 2. dlopen(libName)\n + * 3. dlsym("NativeChildProcess_OnConnect")\n + * 4. dlsym("NativeChildProcess_MainProc")\n + * 5. ipcRemote = NativeChildProcess_OnConnect()\n + * 6. NativeChildProcess_MainProc()\n + * Main process: \n + * 7. onProcessStartedCallback(ipcRemote, errCode)\n + * Child process: \n + * 8. The child process exits after the NativeChildProcess_MainProc() function is returned. \n + * + * @param libName Name of the dynamic library file loaded in the child process. The value cannot be nullptr. + * @param onProcessStarted Pointer to the callback function for notifying the child process startup result. + * The value cannot be nullptr. For details, see {@link OH_Ability_OnNativeChildProcessStarted}. + * @return Returns {@link NCP_NO_ERROR} if the call is successful, but the actual startup result is notified by the + * callback function.\n + * Returns {@link NCP_ERR_INVALID_PARAM} if the dynamic library name or callback function pointer is invalid.\n + * Returns {@link NCP_ERR_NOT_SUPPORTED} if the device does not support the creation of native child processes.\n + * Returns {@link NCP_ERR_MULTI_PROCESS_DISABLED} if the multi-process mode is disabled on the device.\n + * Returns {@link NCP_ERR_ALREADY_IN_CHILD} if it is not allowed to create another child process in the child process.\n + * Returns {@link NCP_ERR_MAX_CHILD_PROCESSES_REACHED} if the maximum number of native child processes is reached.\n + * For details, see {@link Ability_NativeChildProcess_ErrCode}. + * @see OH_Ability_OnNativeChildProcessStarted + * @since 12 + */ +int OH_Ability_CreateNativeChildProcess(const char* libName, + OH_Ability_OnNativeChildProcessStarted onProcessStarted); + + +#ifdef __cplusplus +} // extern "C" +#endif + +/** @} */ +#endif // OHOS_ABILITY_RUNTIME_C_NATIVE_CHILD_PROCESS_H diff --git a/en/native_sdk/ace/drag_and_drop.h b/en/native_sdk/ace/drag_and_drop.h new file mode 100644 index 0000000000000000000000000000000000000000..fcd1b96f0b1970d8e4a9ab9a48fc8c76903dbd98 --- /dev/null +++ b/en/native_sdk/ace/drag_and_drop.h @@ -0,0 +1,810 @@ +/* + * Copyright (c) 2024 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup ArkUI_NativeModule + * @{ + * + * @brief Provides drag and drop APIs of ArkUI on the native side. + * + * @since 12 + */ + +/** + * @file drag_and_drop.h + * + * @brief Defines the native drag and drop APIs. + * + * @library libace_ndk.z.so + * @kit ArkUI + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 12 + */ + +#ifndef ARKUI_NATIVE_DRAG_AND_DROP_H +#define ARKUI_NATIVE_DRAG_AND_DROP_H + +#include + +#include "native_type.h" +#include "database/udmf/udmf.h" +#include "multimedia/image_framework/image/pixelmap_native.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Defines an enum for drag results, which are set by the data receiver and transferred by the system to the + * drag source so that the drag source is aware of the data processing result of the receiver. + * + * @since 12 + */ +typedef enum { + /** The drag and drop operation succeeded. */ + ARKUI_DRAG_RESULT_SUCCESSFUL = 0, + /** The drag and drop operation failed. */ + ARKUI_DRAG_RESULT_FAILED, + /** The drag and drop operation was canceled. */ + ARKUI_DRAG_RESULT_CANCELED, +} ArkUI_DragResult; + +/** + * @brief Defines an enum for data processing modes used when data is dropped, which affects the display of the badge. + * + * @since 12 + */ +typedef enum { + /** Copy. */ + ARKUI_DROP_OPERATION_COPY = 0, + /** Cut. */ + ARKUI_DROP_OPERATION_MOVE, +} ArkUI_DropOperation; + +/** + * @brief Defines an enum for interaction states prior to a drop and drop operation. + * + * @since 12 + */ +typedef enum { + /** Unknown. */ + ARKUI_PRE_DRAG_STATUS_UNKNOWN = -1, + /** A drag gesture is being detected. */ + ARKUI_PRE_DRAG_STATUS_ACTION_DETECTING, + /** The component is ready to be dragged. */ + ARKUI_PRE_DRAG_STATUS_READY_TO_TRIGGER_DRAG, + /** A lift animation is started. */ + ARKUI_PRE_DRAG_STATUS_PREVIEW_LIFT_STARTED, + /** A lift animation is finished. */ + ARKUI_PRE_DRAG_STATUS_PREVIEW_LIFT_FINISHED, + /** A drop animation is started. */ + ARKUI_PRE_DRAG_STATUS_PREVIEW_LANDING_STARTED, + /** A drop animation is finished. */ + ARKUI_PRE_DRAG_STATUS_PREVIEW_LANDING_FINISHED, + /** A drop animation is terminated. */ + ARKUI_PRE_DRAG_STATUS_CANCELED_BEFORE_DRAG, +} ArkUI_PreDragStatus; + +/** + * @brief Defines an enum for drag preview scale modes. + * + * @since 12 + */ +typedef enum { + /** The system automatically changes the position of the dragged point based on the scenario and + * scales the drag preview based on set rules. + ARKUI_DRAG_PREVIEW_SCALE_AUTO = 0, + /** The system does not scale the drag preview. */ + ARKUI_DRAG_PREVIEW_SCALE_DISABLED, +} ArkUI_DragPreviewScaleMode; + +/** + * @brief Defines an enum for drag states. + * + * @since 12 + */ +typedef enum { + /** Unknown. */ + ARKUI_DRAG_STATUS_UNKNOWN = -1, + /** Started. */ + ARKUI_DRAG_STATUS_STARTED, + /** Ended. */ + ARKUI_DRAG_STATUS_ENDED, +} ArkUI_DragStatus; + +/** + * @brief Defines a struct for a component event. + * + * @since 12 + */ +typedef struct ArkUI_NodeEvent ArkUI_NodeEvent; + +/** + * @brief Defines a struct for a UI context object. + * + * @since 12 + */ +typedef struct ArkUI_Context ArkUI_Context; + +/** + * @brief Defines a struct for a UI context object pointer. + * + * @since 12 + */ +typedef struct ArkUI_Context* ArkUI_ContextHandle; + +/** + * @brief Defines a struct for a drag event. + * + * @since 12 + */ +typedef struct ArkUI_DragEvent ArkUI_DragEvent; + +/** + * @brief Defines a struct for custom drag preview options. + * + * @since 12 + */ +typedef struct ArkUI_DragPreviewOption ArkUI_DragPreviewOption; + +/** + * @brief Defines a struct for a drag action. + * + * @since 12 + */ +typedef struct ArkUI_DragAction ArkUI_DragAction; + +/** + * @brief Defines a struct for drag and drop information returned through a drag status listener. + * + * @since 12 + */ +typedef struct ArkUI_DragAndDropInfo ArkUI_DragAndDropInfo; + +/** + * @brief Obtains an ArkUI_DragEvent object from the specified ArkUI_NodeEvent object. + * + * @param node Indicates the pointer to an ArkUI_NodeEvent object. + * @return Returns the pointer to an ArkUI_DragEvent object. + * Returns null if the parameter passed in is invalid or is not a drag-related event. + * @since 12 + */ +ArkUI_DragEvent* OH_ArkUI_NodeEvent_GetDragEvent(ArkUI_NodeEvent* nodeEvent); + +/** + * @brief Obtains the interaction state prior to a drop and drop operation. + * + * @param node Indicates the pointer to an ArkUI_NodeEvent object. + * @return Returns the interaction state prior to the drop and drop operation. + * @since 12 + */ +ArkUI_PreDragStatus OH_ArkUI_NodeEvent_GetPreDragStatus(ArkUI_NodeEvent* nodeEvent); + +/** + * @brief Sets whether to disable the default drop animation. + * The default drop animation is enabled by default and can be disabled to apply a custom drop animation. + * + * @param event Indicates the pointer to an ArkUI_DragEvent object. + * @param disable Indicates whether to disable the default drop animation. + * The value true means to disable the default drop animation, and false means the opposite. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_DragEvent_DisableDefaultDropAnimation(ArkUI_DragEvent* event, bool disable); + +/** + * @brief Sets the data processing mode. + * + * @param event Indicates the pointer to an ArkUI_DragEvent object. + * @param proposal Indicates the data processing mode. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_DragEvent_SetSuggestedDropOperation(ArkUI_DragEvent* event, ArkUI_DropOperation dropOperation); + +/** + * @brief Sets the result for a drag event. + * + * @param event Indicates the pointer to an ArkUI_DragEvent object. + * @param result Indicates the drag result. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_DragEvent_SetDragResult(ArkUI_DragEvent* event, ArkUI_DragResult result); + +/** + * @brief Set drag data for a drag event. + * + * @param event Indicates the pointer to an ArkUI_DragEvent object. + * @param data Indicates the drag data. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_DragEvent_SetData(ArkUI_DragEvent* event, OH_UdmfData* data); + +/** + * @brief Obtains the default drag data from a drag event. + * + * @param event Indicates the pointer to an ArkUI_DragEvent object. + * @param data Indicates the pointer to an OH_UdmfData object. The application needs to create a pointer + * for receiving data by using the {@link OH_UdmfData_Create} method. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_DragEvent_GetUdmfData(ArkUI_DragEvent* event, OH_UdmfData *data); + +/** + * @brief Obtains the number of drag data types from a drag event. + * + * @param event Indicates the pointer to an ArkUI_DragEvent object. + * @param count Indicates the number of drag data types returned. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_DragEvent_GetDataTypeCount(ArkUI_DragEvent* event, int32_t* count); + +/** + * @brief Obtains the list of drag data types from a drag event. + * + * @param event Indicates the pointer to an ArkUI_DragEvent object. + * @param char Indicates the list of the drag data types. You need to create a string array first. + * @param length Indicates the total length of the list array. It must be greater than or equal to the number obtained + * by using {@link OH_ArkUI_DragEvent_GetDataTypesCount}. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_DragEvent_GetDataTypes( + ArkUI_DragEvent *event, char *eventTypeArray[], int32_t length, int32_t maxStrLen); + +/** + * @brief Obtains the drag result from a drag event. + * + * @param event Indicates the pointer to an ArkUI_DragEvent object. + * @param result Indicates the drag result returned. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_DragEvent_GetDragResult(ArkUI_DragEvent* event, ArkUI_DragResult* result); + +/** + * @brief Obtains the X coordinate of the touch point for a drag preview from a drag event. + * + * @param event Indicates the pointer to an ArkUI_DragEvent object. + * @return Returns the X coordinate of the touch point, in px. + * Returns the default value 0 if the input parameter is invalid. + * @since 12 + */ +float OH_ArkUI_DragEvent_GetPreviewTouchPointX(ArkUI_DragEvent* event); + +/** + * @brief Obtains the Y coordinate of the touch point for a drag preview from a drag event. + * + * @param event Indicates the pointer to an ArkUI_DragEvent object. + * @return Returns the Y coordinate of the touch point, in px. + * Returns the default value 0 if the input parameter is invalid. + * @since 12 + */ +float OH_ArkUI_DragEvent_GetPreviewTouchPointY(ArkUI_DragEvent* event); + +/** + * @brief Obtains the width of a drag preview from a drag event. + * + * @param event Indicates the pointer to an ArkUI_DragEvent object. + * @return Returns the width of the drag preview, in px. + * Returns the default value 0 if the input parameter is invalid. + * @since 12 + */ +float OH_ArkUI_DragEvent_GetPreviewRectWidth(ArkUI_DragEvent* event); + +/** + * @brief Obtains the height of a drag preview from a drag event. + * + * @param event Indicates the pointer to an ArkUI_DragEvent object. + * @return Returns the height of the drag preview, in px. + * Returns the default value 0 if the input parameter is invalid. + * @since 12 + */ +float OH_ArkUI_DragEvent_GetPreviewRectHeight(ArkUI_DragEvent* event); + +/** + * @brief Obtains the X coordinate of the touch point relative to the window from a drag event. + * + * @param event Indicates the pointer to an ArkUI_DragEvent object. + * @return Returns the X coordinate of the touch point relative to the window, in px. + * Returns the default value 0 if the input parameter is invalid. + * @since 12 + */ +float OH_ArkUI_DragEvent_GetTouchPointXToWindow(ArkUI_DragEvent* event); + +/** + * @brief Obtains the Y coordinate of the touch point relative to the window from a drag event. + * + * @param event Indicates the pointer to an ArkUI_DragEvent object. + * @return Returns the Y coordinate of the touch point relative to the window, in px. + * Returns the default value 0 if the input parameter is invalid. + * @since 12 + */ +float OH_ArkUI_DragEvent_GetTouchPointYToWindow(ArkUI_DragEvent* event); + +/** + * @brief Obtains the X coordinate of the touch point relative to the current display from a drag event. + * + * @param event Indicates the pointer to an ArkUI_DragEvent object. + * @return Returns the X coordinate of the touch point relative to the current display, in px. + * Returns the default value 0 if the input parameter is invalid. + * @since 12 + */ +float OH_ArkUI_DragEvent_GetTouchPointXToDisplay(ArkUI_DragEvent* event); + +/** + * @brief Obtains the Y coordinate of the touch point relative to the current display from a drag event. + * + * @param event Indicates the pointer to an ArkUI_DragEvent object. + * @return Returns the Y coordinate of the touch point relative to the current display, in px. + * Returns the default value 0 if the input parameter is invalid. + * @since 12 + */ +float OH_ArkUI_DragEvent_GetTouchPointYToDisplay(ArkUI_DragEvent* event); + +/** + * @brief Obtains the dragging velocity along the x-axis. + * + * @param event Indicates the pointer to an ArkUI_DragEvent object. + * @return Returns the dragging velocity along the x-axis, in px. + * Returns the default value 0 if the input parameter is invalid. + * @since 12 + */ +float OH_ArkUI_DragEvent_GetVelocityX(ArkUI_DragEvent* event); + +/** + * @brief Obtains the dragging velocity along the y-axis. + * + * @param event Indicates the pointer to an ArkUI_DragEvent object. + * @return Returns the dragging velocity along the y-axis, in px. + * Returns the default value 0 if the input parameter is invalid. + * @since 12 + */ +float OH_ArkUI_DragEvent_GetVelocityY(ArkUI_DragEvent* event); + +/** + * @brief Obtains the dragging velocity along the main axis. + * + * @param event Indicates the pointer to an ArkUI_DragEvent object. + * @return Returns the dragging velocity along the main axis, in px. + * Returns the default value 0 if the input parameter is invalid. + * @since 12 + */ +float OH_ArkUI_DragEvent_GetVelocity(ArkUI_DragEvent* event); + +/** + * @brief Obtains the pressed status of modifier keys from a drag event. + * + * @param event Indicates the pointer to an ArkUI_DragEvent object. + * @param keys Indicates the returned combination of modifier keys that are currently pressed. + * The application can determine the pressed modifier keys through bitwise operations. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_DragEvent_GetModifierKeyStates(ArkUI_DragEvent* event, uint64_t* keys); + +/** + * @brief Sets whether to enable strict reporting on drag events. + * This feature is disabled by default, and you are advised to enable it. + * If this feature is disabled, the parent component is not notified when an item in it is dragged over its child + * component. If this feature is enabled, the component is notified of the dragged item's leaving, and the child + * component to which the dragged item is dropped is notified of the item's entering. This configuration is + * related to a specific UI instance. You can pass in a specific component node on the current UI instance + * for association. + * + * @param node Indicates the pointer to a component node. + * @param enabled Indicates whether to enable strict reporting on drag events. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_SetDragEventStrictReportWithNode(ArkUI_NodeHandle node, bool enabled); + +/** + * @brief Sets whether to enable strict reporting on drag events. + * This feature is disabled by default, and you are advised to enable it. + * If this feature is disabled, the parent component is not notified when an item in it is dragged over its child + * component. If this feature is enabled, the component is notified of the dragged item's leaving, and the child + * component to which the dragged item is dropped is notified of the item's entering. This configuration is + * related to a specific UI instance. You can pass in a specific UI instance for association. + * + * @param uiContext Indicates the pointer to a UI instance. + * @param enabled Indicates whether to enable strict reporting on drag events. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_SetDragEventStrictReportWithContext(ArkUI_ContextHandle uiContext, bool enabled); + +/** + * @brief Sets the types of data that can be dropped to the specified component. This API resets the settings configured + * through {@link OH_ArkUI_DisallowNodeAnyDropDataTypes} and {@link OH_ArkUI_AllowNodeAllDropDataTypes}. + * + * @param node Indicates the pointer to a component node. + * @param typesArray Indicates the array of types of data that can be dropped. + * @param count Indicates length of an array. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_SetNodeAllowedDropDataTypes(ArkUI_NodeHandle node, const char* typesArray[], int32_t count); + +/** + * @brief Configures the specified component to disallow any data types. This API resets the settings configured through + * {@link OH_ArkUI_SetNodeAllowedDropDataTypes}. + * + * @param node Indicates the pointer to a component node. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_DisallowNodeAnyDropDataTypes(ArkUI_NodeHandle node); + +/** + * @brief Configures the specified component to allow any data types. This API resets the settings configured through + * {@link OH_ArkUI_SetNodeAllowedDropDataTypes}. + * + * @param node Indicates the pointer to a component node. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_AllowNodeAllDropDataTypes(ArkUI_NodeHandle node); + +/** + * @brief Sets whether the specified component is draggable. + * + * @param node Indicates the pointer to a component node. + * @param bool Indicates whether the component is draggable. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_SetNodeDraggable(ArkUI_NodeHandle node, bool enabled); + +/** + * @brief Sets a custom drag preview for the specified component. + * + * @param node Indicates the pointer to a component node. + * @param preview Indicates the custom drag preview, which is a pixel map. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_SetNodeDragPreview(ArkUI_NodeHandle node, OH_PixelmapNative* preview); + +/** + * @brief Creates an ArkUI_DragPreviewOption object. + * + * @return Returns the created ArkUI_DragPreviewOption object. + * @since 12 + */ +ArkUI_DragPreviewOption* OH_ArkUI_CreateDragPreviewOption(void); + +/** + * @brief Disposes of an ArkUI_DragPreviewOption object. + * + * @param option Indicates the pointer to an ArkUI_DragPreviewOption object. + * @since 12 + */ +void OH_ArkUI_DragPreviewOption_Dispose(ArkUI_DragPreviewOption* option); + +/** + * @brief Sets the scale mode for an ArkUI_DragPreviewOption object. + * + * @param option Indicates the pointer to an ArkUI_DragPreviewOption object. + * @param scaleMode Indicates the scale mode. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_DragPreviewOption_SetScaleMode(ArkUI_DragPreviewOption* option, ArkUI_DragPreviewScaleMode scaleMode); + +/** + * @brief Sets whether to enable the shadow effect for an ArkUI_DragPreviewOption object. + * The shadow effect is enabled by default. + * + * @param option Indicates the pointer to an ArkUI_DragPreviewOption object. + * @param enabled Indicates whether to enable the shadow effect. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_DragPreviewOption_SetDefaultShadowEnabled(ArkUI_DragPreviewOption* option, bool enabled); + +/** + * @brief Sets whether to enable the rounded corner effect for an ArkUI_DragPreviewOption object. + * The rounded corner effect is enabled by default. + * + * @param option Indicates the pointer to an ArkUI_DragPreviewOption object. + * @param enabled Indicates whether to enable the rounded corner effect. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_DragPreviewOption_SetDefaultRadiusEnabled(ArkUI_DragPreviewOption* option, bool enabled); + +/** + * @brief Sets whether to enable the badge for an ArkUI_DragPreviewOption object. + * If this feature is enabled, a badge that contains the number of dragged items is displayed. + * + * @param option Indicates the pointer to an ArkUI_DragPreviewOption object. + * @param enabled Indicates whether to enable badge. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_DragPreviewOption_SetNumberBadgeEnabled(ArkUI_DragPreviewOption* option, bool enabled); + +/** + * @brief Sets the count on the badge. + * The settings will overwrite the value in the SetDragPreviewNumberBadgeEnabled API. + * + * @param option Indicates the pointer to an ArkUI_DragPreviewOption object. + * @param forcedNumber Indicates the count on the badge. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_DragPreviewOption_SetBadgeNumber(ArkUI_DragPreviewOption* option, uint32_t forcedNumber); + +/** + * @brief Sets whether to enable the default animation on a click or touch. + * + * @param option Indicates the pointer to an ArkUI_DragPreviewOption object. + * @param enabled Indicates whether to enable the default animation on a click or touch. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_DragPreviewOption_SetDefaultAnimationBeforeLiftingEnabled( + ArkUI_DragPreviewOption* option, bool enabled); +/** + * @brief Sets an ArkUI_DragPreviewOption object for the specified component. + * + * @param node Indicates the pointer to a component node. + * @param option Indicates the pointer to an ArkUI_DragPreviewOption object. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_SetNodeDragPreviewOption(ArkUI_NodeHandle node, ArkUI_DragPreviewOption* option); + +/** + * @brief Creates a drag action object for a UI instance based on the specified component node of the current + * UI instance. + * + * @param node Indicates the pointer to a component node. + * @return Returns the pointer to the created drag action object; returns null if the operation fails. + * @since 12 + */ +ArkUI_DragAction* OH_ArkUI_CreateDragActionWithNode(ArkUI_NodeHandle node); + +/** + * @brief Creates a drag action object for the specified UI instance. + * + * @param uiContext Indicates the pointer to a UI instance. + * @return Returns the pointer to the created drag action object; returns null if the operation fails. + * @since 12 + */ +ArkUI_DragAction* OH_ArkUI_CreateDragActionWithContext(ArkUI_ContextHandle uiContext); + +/** + * @brief Disposes of a drag action object. + * + * @param dragAction Indicates the pointer to the target drag action object. + * @since 12 + */ +void OH_ArkUI_DragAction_Dispose(ArkUI_DragAction* dragAction); + +/** + * @brief Sets the pointer ID. If only one finger is operating on the screen, the pointer ID is 0. + * In general cases, you can set the pointer ID to 0. + * + * @param dragAction Indicates the pointer to the target drag action object. + * @param pointer Indicates the pointer ID. The value ranges from 0 to 9. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_DragAction_SetPointerId(ArkUI_DragAction* dragAction, int32_t pointer); + +/** + * @brief Sets the drag previews for a drag action. + * + * @param dragAction Indicates the pointer to the target drag action object. + * @param pixelmapArray Indicates the array of the drag previews to set, which must be pixel maps. + * @param size Indicates the size of the drag preview array. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_DragAction_SetPixelMaps( + ArkUI_DragAction* dragAction, OH_PixelmapNative* pixelmapArray[], int32_t size); + +/** + * @brief Sets the touch point relative to the upper left corner of the first drag preview (pixel map). + * + * @param dragAction Indicates the pointer to the target drag action object. + * @param x Indicates the X coordinate of the touch point. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_DragAction_SetTouchPointX(ArkUI_DragAction* dragAction, float x); + +/** + * @brief Sets the touch point relative to the upper left corner of the first drag preview (pixel map). + * + * @param dragAction Indicates the pointer to the target drag action object. + * @param y Indicates the Y coordinate of the touch point. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_DragAction_SetTouchPointY(ArkUI_DragAction* dragAction, float y); + +/** + * @brief Sets the drag data. + * + * @param dragAction Indicates the pointer to the target drag action object. + * @param data Indicates the drag data. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_DragAction_SetData(ArkUI_DragAction* dragAction, OH_UdmfData* data); + +/** + * @brief Sets an ArkUI_DragPreviewOption object for the specified drag action object. + * + * @param dragAction Indicates the pointer to the target drag action object. + * @param option Indicates the pointer to an ArkUI_DragPreviewOption object. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_DragAction_SetDragPreviewOption(ArkUI_DragAction* dragAction, ArkUI_DragPreviewOption* option); + +/** + * @brief Registers a drag status listener. + * This listener can be used to check whether the data is successfully received and processed. + * + * @param dragAction Indicates the pointer to the target drag action object. + * @param userData Indicates the custom user data. + * @param listener + * Indicates the listener to register. When the callback is invoked, the system returns a pointer to the drag status + * object. The pointer is destroyed after the callback is complete and the application should not hold it anymore. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_DragAction_RegisterStatusListener(ArkUI_DragAction* dragAction, void* userData, + void(*listener)(ArkUI_DragAndDropInfo* dragAndDropInfo, void* userData)); + +/** + * @brief Obtains the display ID of the screen for the specified drag event. + * + * @param event Pointer to an ArkUI_DragEvent object. + * @param displayId Display ID of the screen. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 20 + */ +ArkUI_ErrorCode OH_ArkUI_DragEvent_GetDisplayId(ArkUI_DragEvent event, int32_t* displayId); + +/** + * @brief Unregisters a drag status listener. + * + * @param dragAction Indicates the pointer to the target drag action object. + * @since 12 + */ +void OH_ArkUI_DragAction_UnregisterStatusListener(ArkUI_DragAction* dragAction); + +/** + * @brief Obtains the drag status of a drag action. + * + * @param dragAndDropInfo Indicates the drag and drop information returned by the drag status listener. + * @return Returns an ArkUI_DragStatus object; returns ArkUI_DRAG_STATUS_UNKNOWN if an error occurs. + * @since 12 + */ +ArkUI_DragStatus OH_ArkUI_DragAndDropInfo_GetDragStatus(ArkUI_DragAndDropInfo* dragAndDropInfo); + +/** + * @brief Obtains a drag event based on the specified drag and drop information. + * The drag event can then be used to obtain the drag result. + * + * @param dragAndDropInfo Indicates the drag and drop information returned by the drag status listener. + * @return Returns an ArkUI_DragEvent object; returns null if an error occurs. + * @since 12 + */ +ArkUI_DragEvent* OH_ArkUI_DragAndDropInfo_GetDragEvent(ArkUI_DragAndDropInfo* dragAndDropInfo); + +/** + * @brief Initiates a drag action through the specified drag action object. + * + * @param dragAction Indicates a drag action object. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_StartDrag(ArkUI_DragAction* dragAction); + +/** + * @brief Sets whether to enable the display of a disallow status icon. By default, if a component cannot receive or + * process the data being dragged by the user, the system will display a matching icon without showing the + * disallowed status. Applications can call this API on the corresponding UI instance to explicitly declare + * that a clear "disallowed" indicator should be displayed when data cannot be processed. + * + * @param uiContext Pointer to a UI instance. + * @param enabled Whether to enable the display of the disallowed status icon. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 20 + */ +ArkUI_ErrorCode OH_ArkUI_SetDragDisallowStatusShowingEnabled(ArkUI_ContextHandle uiContext, bool enabled); + +#ifdef __cplusplus +}; +#endif + +#endif // ARKUI_NATIVE_DRAG_AND_DROP_H +/** @} */ diff --git a/en/native_sdk/ace/native_animate.h b/en/native_sdk/ace/native_animate.h new file mode 100644 index 0000000000000000000000000000000000000000..7fa5d72b550ba58fe6cb1193e025b5d1d5a14496 --- /dev/null +++ b/en/native_sdk/ace/native_animate.h @@ -0,0 +1,1144 @@ +/* + * Copyright (c) 2024 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup ArkUI_NativeModule + * @{ + * + * @brief Provides animation callbacks of ArkUI on the native side. + * + * @since 12 + */ + +/** + * @file native_animate.h + * + * @brief Defines a set of animation APIs of ArkUI on the native side. + * + * @library libace_ndk.z.so + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 12 + */ + +#ifndef ARKUI_NATIVE_ANIMATE_H +#define ARKUI_NATIVE_ANIMATE_H + +#include + +#include "native_type.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** +* @brief Defines the expected frame rate range of the animation. +* +* @since 12 +*/ +typedef struct { + /** Expected minimum frame rate. */ + uint32_t min; + /** Expected maximum frame rate. */ + uint32_t max; + /** Expected optimal frame rate. */ + uint32_t expected; +} ArkUI_ExpectedFrameRateRange; + + +/** +* @brief Defines the callback type for when the animation playback is complete. +* +* @since 12 +*/ +typedef struct { + /** Type of the onFinish callback. */ + ArkUI_FinishCallbackType type; + /** Callback invoked when the animation playback is complete. */ + void (*callback)(void* userData); + /** Custom type. */ + void* userData; +} ArkUI_AnimateCompleteCallback; + +/** +* @brief Defines the animation configuration. +* +* @since 12 +*/ +typedef struct ArkUI_AnimateOption ArkUI_AnimateOption; + +/** +* @brief Defines an interpolation curve. +* +* @since 12 +*/ +struct ArkUI_Curve; + +/** + * @brief Defines the pointer to an interpolation curve. + * + * @since 12 + */ +typedef struct ArkUI_Curve* ArkUI_CurveHandle; + +/** + * @brief Defines the keyframe animation parameter object. + * + * @since 12 + */ +typedef struct ArkUI_KeyframeAnimateOption ArkUI_KeyframeAnimateOption; + +/** + * @brief Defines the animator parameter object. + * + * @since 12 + */ +typedef struct ArkUI_AnimatorOption ArkUI_AnimatorOption; + +/** + * @brief Defines the pointer to an animator object. + * + * @since 12 + */ +typedef struct ArkUI_Animator* ArkUI_AnimatorHandle; + +/** +* @brief Defines the animator callback event object. +* +* @since 12 +*/ +struct ArkUI_AnimatorEvent; + +/** +* @brief Defines the callback object when the animator receives a frame. +* +* @since 12 +*/ +struct ArkUI_AnimatorOnFrameEvent; + +/** + * @brief Defines the transition effect. + * + * @since 12 + */ +typedef struct ArkUI_TransitionEffect ArkUI_TransitionEffect; + +/** + * @brief Implements the native animation APIs provided by ArkUI. + * + * @version 1 + * @since 12 + */ +typedef struct { + /** + * @brief Defines an explicit animation. + * + * @note Make sure the component attributes to be set in the event closure have been set before. + * + * @param context Indicates a UIContext instance. + * @param option Indicates the pointer to an animation configuration. + * @param update Indicates the animation closure. The system automatically inserts a transition animation for the + * state change caused by the closure. + * @param complete Indicates the callback to be invoked when the animation playback is complete. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ + int32_t (*animateTo)(ArkUI_ContextHandle context, ArkUI_AnimateOption* option, ArkUI_ContextCallback* update, + ArkUI_AnimateCompleteCallback* complete); + + /** + * @brief Sets the keyframe animation. + * + * + * @param context Indicates a UIContext instance. + * @param option Indicates the keyframe animation parameters. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ + int32_t (*keyframeAnimateTo)(ArkUI_ContextHandle context, ArkUI_KeyframeAnimateOption* option); + + /** + * @brief Creates an animator object. + * + * @param context Indicates a UIContext instance. + * @param option Indicates the animator parameters. + * @return Returns the pointer to the animator object; returns NULL if a function parameter error occurs. + */ + ArkUI_AnimatorHandle (*createAnimator)(ArkUI_ContextHandle context, ArkUI_AnimatorOption* option); + + /** + * @brief Disposes of an animator object. + * + * @param animator Indicates the target animator object. + */ + void (*disposeAnimator)(ArkUI_AnimatorHandle animator); +} ArkUI_NativeAnimateAPI_1; + +/** +* @brief Creates an animation configuration. +* +* @return Returns the pointer to the created animation configuration. +* @since 12 +*/ +ArkUI_AnimateOption* OH_ArkUI_AnimateOption_Create(); + +/** +* @brief Disposes of an animation configuration. +* +* @since 12 +*/ +void OH_ArkUI_AnimateOption_Dispose(ArkUI_AnimateOption* option); + +/** +* @brief Obtains the animation duration, in milliseconds. +* +* @param option Indicates the pointer to an animation configuration. +* @return Returns the duration. +* @since 12 +*/ +uint32_t OH_ArkUI_AnimateOption_GetDuration(ArkUI_AnimateOption* option); + +/** +* @brief Obtains the animation playback speed. +* +* @param option Indicates the pointer to an animation configuration. +* @return Returns the animation playback speed. +* @since 12 +*/ +float OH_ArkUI_AnimateOption_GetTempo(ArkUI_AnimateOption* option); + +/** +* @brief Obtains the animation curve. +* +* @param option Indicates the pointer to an animation configuration. +* @return Returns the animated curve. +* @since 12 +*/ +ArkUI_AnimationCurve OH_ArkUI_AnimateOption_GetCurve(ArkUI_AnimateOption* option); + +/** +* @brief Obtains the animation delay, in milliseconds. +* +* @param option Indicates the pointer to an animation configuration. +* @return Returns the animation delay. +* @since 12 +*/ +uint32_t OH_ArkUI_AnimateOption_GetDelay(ArkUI_AnimateOption* option); + +/** +* @brief Obtains the number of times that an animation is played. +* +* @param option Indicates the pointer to an animation configuration. +* @return Returns the number of times that the animation is played. +* @since 12 +*/ +uint32_t OH_ArkUI_AnimateOption_GetIterations(ArkUI_AnimateOption* option); + +/** +* @brief Obtains the animation playback mode. +* +* @param option Indicates the pointer to an animation configuration. +* @return Returns the animation playback mode. +* @since 12 +*/ +ArkUI_AnimationPlayMode OH_ArkUI_AnimateOption_GetPlayMode(ArkUI_AnimateOption* option); + +/** +* @brief Obtains the expected frame rate range of an animation. +* +* @param option Indicates the pointer to an animation configuration. +* @return Returns the expected frame rate range. +* @since 12 +*/ +ArkUI_ExpectedFrameRateRange* OH_ArkUI_AnimateOption_GetExpectedFrameRateRange(ArkUI_AnimateOption* option); + +/** +* @brief Sets the animation duration. +* +* @param option Indicates the pointer to an animation configuration. +* @param value Indicates the duration, in milliseconds. +* @since 12 +*/ +void OH_ArkUI_AnimateOption_SetDuration(ArkUI_AnimateOption* option, uint32_t value); + +/** +* @brief Sets the animation playback speed. +* +* @param option Indicates the pointer to an animation configuration. +* @param value Indicates the animation playback speed. +* @since 12 +*/ +void OH_ArkUI_AnimateOption_SetTempo(ArkUI_AnimateOption* option, float value); + +/** +* @brief Sets the animation curve. +* +* @param option Indicates the pointer to an animation configuration. +* @param value Indicates the animated curve. Default value: ARKUI_CURVE_LINEAR. +* @since 12 +*/ +void OH_ArkUI_AnimateOption_SetCurve(ArkUI_AnimateOption* option, ArkUI_AnimationCurve value); + +/** +* @brief Sets the animation delay. +* +* @param option Indicates the pointer to an animation configuration. +* @param value Indicates the animation delay. +* @since 12 +*/ +void OH_ArkUI_AnimateOption_SetDelay(ArkUI_AnimateOption* option, uint32_t value); + +/** +* @brief Sets the number of times that an animation is played. +* +* @param option Indicates the pointer to an animation configuration. +* @param value Indicates the number of times that the animation is played. +* @since 12 +*/ +void OH_ArkUI_AnimateOption_SetIterations(ArkUI_AnimateOption* option, uint32_t value); + +/** +* @brief Sets the animation playback mode. +* +* @param option Indicates the pointer to an animation configuration. +* @param value Indicates the animation playback mode. +* @since 12 +*/ +void OH_ArkUI_AnimateOption_SetPlayMode(ArkUI_AnimateOption* option, ArkUI_AnimationPlayMode value); + +/** +* @brief Sets the expected frame rate range of an animation. +* +* @param option Indicates the pointer to an animation configuration. +* @param value Indicates the expected frame rate range. +* @since 12 +*/ +void OH_ArkUI_AnimateOption_SetExpectedFrameRateRange(ArkUI_AnimateOption* option, ArkUI_ExpectedFrameRateRange* value); + +/** +* @brief Sets the animation curve for the animation of an animator. +* +* @note This API is preferred over the value set by OH_ArkUI_AnimateOption_SetCurve. +* @param option Indicates the animator parameters. +* @param value Indicates the animation curve settings. +* @since 12 +*/ +void OH_ArkUI_AnimateOption_SetICurve(ArkUI_AnimateOption* option, ArkUI_CurveHandle value); + +/** +* @brief Obtains the animation curve of the animation of an animator. +* +* @param option Indicates the animator parameters. +* @return Returns the animation curve of the specified animation. +* @since 12 +*/ +ArkUI_CurveHandle OH_ArkUI_AnimateOption_GetICurve(ArkUI_AnimateOption* option); + +/** + * @brief Obtains the keyframe animation parameters. + * + * @param size Indicates the number of keyframe animation states. + * @return Returns the keyframe animation parameter object; returns NULL if the value of size is less than + * 0. + * @since 12 + */ +ArkUI_KeyframeAnimateOption* OH_ArkUI_KeyframeAnimateOption_Create(int32_t size); + +/** + * @brief Disposes of a keyframe animation parameter object. + * + * @param option Indicates the keyframe animation parameter object. + * @since 12 + */ +void OH_ArkUI_KeyframeAnimateOption_Dispose(ArkUI_KeyframeAnimateOption* option); + +/** + * @brief Sets the overall delay of a keyframe animation, in milliseconds. By default, the keyframe animation is played + * without delay. + * + * @param option Indicates the keyframe animation parameters. + * @param value Indicates the delay, in milliseconds. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ +int32_t OH_ArkUI_KeyframeAnimateOption_SetDelay(ArkUI_KeyframeAnimateOption* option, int32_t value); + +/** + * @brief Sets the number of times that the keyframe animation is played. By default, the animation is played once. + * The value -1 indicates that the animation is played for an unlimited number of times. The value 0 + * indicates that there is no animation. + * + * @param option Indicates the keyframe animation parameters. + * @param value Indicates the number of times that the animation is played. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ +int32_t OH_ArkUI_KeyframeAnimateOption_SetIterations(ArkUI_KeyframeAnimateOption* option, int32_t value); + +/** + * @brief Sets the callback invoked when the keyframe animation playback is complete. This API is called after the + * keyframe animation has played for the specified number of times. + * + * @param option Indicates the keyframe animation parameters. + * @param userData Indicates the pointer to a custom object. + * @param onFinish Indicates the callback. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ +int32_t OH_ArkUI_KeyframeAnimateOption_RegisterOnFinishCallback( + ArkUI_KeyframeAnimateOption* option, void* userData, void (*onFinish)(void* userData)); + +/** + * @brief Sets the duration of a keyframe animation, in milliseconds. + * + * @param option Indicates the keyframe animation parameters. + * @param value Indicates the duration to set, in milliseconds. + * @param index Indicates a state index. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ +int32_t OH_ArkUI_KeyframeAnimateOption_SetDuration(ArkUI_KeyframeAnimateOption* option, int32_t value, int32_t index); + +/** + * @brief Sets the animation curve for a specific keyframe in a keyframe animation. + * + * @note Because the springMotion, responsiveSpringMotion, and interpolatingSpring curves do not + * have effective duration settings, they are not supported. + * @param option Indicates the keyframe animation parameters. + * @param value Indicates the animation curve to set. Default value: EASE_IN_OUT. + * @param index Indicates a state index. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ +int32_t OH_ArkUI_KeyframeAnimateOption_SetCurve( + ArkUI_KeyframeAnimateOption* option, ArkUI_CurveHandle value, int32_t index); + +/** + * @brief Sets the closure function of the state at the time of the keyframe, that is, the state to be reached at the + * time of the keyframe. + * + * @param option Indicates the keyframe animation parameters. + * @param event Indicates a closure function. + * @param userData Indicates the pointer to a custom object. + * @param index Indicates a state index. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ +int32_t OH_ArkUI_KeyframeAnimateOption_RegisterOnEventCallback( + ArkUI_KeyframeAnimateOption* option, void* userData, void (*event)(void* userData), int32_t index); + +/** + * @brief Obtains the overall delay of a keyframe animation + * + * @param option Indicates the keyframe animation parameters. + * @return Returns the overall delay. + * @since 12 + */ +int32_t OH_ArkUI_KeyframeAnimateOption_GetDelay(ArkUI_KeyframeAnimateOption* option); + +/** + * @brief Obtains the number of times that a keyframe animation is played. + * + * @param option Indicates the keyframe animation parameters. + * @return Returns the number of times that the animation is played. + * @since 12 + */ +int32_t OH_ArkUI_KeyframeAnimateOption_GetIterations(ArkUI_KeyframeAnimateOption* option); + +/** + * @brief Obtains the duration of a specific state in a keyframe animation. + * + * @param option Indicates the keyframe animation parameters. + * @param index Indicates a state index. + * @return Returns the duration. The unit is millisecond. + * @since 12 + */ +int32_t OH_ArkUI_KeyframeAnimateOption_GetDuration(ArkUI_KeyframeAnimateOption* option, int32_t index); + +/** + * @brief Obtains the animation curve of a specific state in a keyframe animation. + * + * @param option Indicates the keyframe animation parameters. + * @param index Indicates a state index. + * @return Returns the animated curve. + * @since 12 + */ +ArkUI_CurveHandle OH_ArkUI_KeyframeAnimateOption_GetCurve(ArkUI_KeyframeAnimateOption* option, int32_t index); + +/** + * @brief Creates an animator parameter object. + * + * @note When keyframeSize is greater than 0, the animation interpolation start point is 0, and the animation + * interpolation end point is 1; no setting is allowed. + * @param keyframeSize Indicates the number of keyframes. + * @return Returns the pointer to the animator parameter object. + * @since 12 + */ +ArkUI_AnimatorOption* OH_ArkUI_AnimatorOption_Create(int32_t keyframeSize); + +/** + * @brief Disposes of an animator parameter object. + * + * @since 12 + */ +void OH_ArkUI_AnimatorOption_Dispose(ArkUI_AnimatorOption* option); + +/** + * @brief Sets the duration for the animation of an animator, in milliseconds. + * + * @param option Indicates the target animator parameter object. + * @param value Indicates the playback duration, in milliseconds. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ +int32_t OH_ArkUI_AnimatorOption_SetDuration(ArkUI_AnimatorOption* option, int32_t value); + +/** + * @brief Sets the delay for playing the animation of an animator, in milliseconds. + * + * @param option Indicates an animator parameter object. + * @param value Indicates the delay to set, in milliseconds. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ +int32_t OH_ArkUI_AnimatorOption_SetDelay(ArkUI_AnimatorOption* option, int32_t value); + +/** + * @brief Sets the number of times that the animation of an animator is played. The value 0 means not to play the + * animation, and -1 means to play the animation for an unlimited number of times. + * + * @note If this parameter is set to a negative value other than -1, the value is invalid. In this case, the + * animation is played once. + * @param option Indicates an animator parameter object. + * @param value Indicates the number of times that the animation is played. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ +int32_t OH_ArkUI_AnimatorOption_SetIterations(ArkUI_AnimatorOption* option, int32_t value); + +/** + * @brief Sets whether the animation of an animator is restored to the initial state after being executed. + * + * @param option Indicates an animator parameter object. + * @param value Indicates whether to restore the animation to the initial state after the animation is executed. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ +int32_t OH_ArkUI_AnimatorOption_SetFill(ArkUI_AnimatorOption* option, ArkUI_AnimationFill value); + +/** + * @brief Sets the playback direction for the animation of an animator. + * + * @param option Indicates an animator parameter object. + * @param value Indicates the animation playback direction. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ +int32_t OH_ArkUI_AnimatorOption_SetDirection(ArkUI_AnimatorOption* option, ArkUI_AnimationDirection value); + +/** + * @brief Sets the interpolation curve for the animation of an animator. + * + * @note springCurve, springMotion, responsiveSpringMotion, interpolatingSpring, + * and customCurve curves are not supported. + * + * @param option Indicates an animator parameter object. + * @param value Indicates the target interpolation curve. Default value: ARKUI_CURVE_LINEAR. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ +int32_t OH_ArkUI_AnimatorOption_SetCurve(ArkUI_AnimatorOption* option, ArkUI_CurveHandle value); + +/** + * @brief Sets the interpolation start point for the animation of an animator. + * @note This API does not take effect when the animation is a keyframe animation. + * + * @param option Indicates an animator parameter object. + * @param value Indicates the interpolation start point to set. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ +int32_t OH_ArkUI_AnimatorOption_SetBegin(ArkUI_AnimatorOption* option, float value); + +/** + * @brief Sets the interpolation end point for the animation of an animator. + * @note This API does not take effect when the animation is a keyframe animation. + * + * @param option Indicates an animator parameter object. + * @param value Indicates the interpolation end point to set. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ +int32_t OH_ArkUI_AnimatorOption_SetEnd(ArkUI_AnimatorOption* option, float value); + +/** + * @brief Sets the expected frame rate range for the animation of an animator. + * + * @param option Indicates an animator parameter object. + * @param value Indicates the expected frame rate range to set. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ +int32_t OH_ArkUI_AnimatorOption_SetExpectedFrameRateRange( + ArkUI_AnimatorOption* option, ArkUI_ExpectedFrameRateRange* value); + +/** + * @brief Sets the keyframe parameters for the animation of an animator. + * + * @param option Indicates an animator parameter object. + * @param time Indicates the keyframe time. Value range: [0,1]. + * @param value Indicates the keyframe value. + * @param index Indicates the keyframe index. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ +int32_t OH_ArkUI_AnimatorOption_SetKeyframe( + ArkUI_AnimatorOption* option, float time, float value, int32_t index); + +/** + * @brief Sets the keyframe curve type for the animation of an animator. + * + * @note springCurve, springMotion, responsiveSpringMotion, interpolatingSpring, + * and customCurve curves are not supported. + * + * @param option Indicates an animator parameter object. + * @param value Indicates the target interpolation curve. + * @param index Indicates the keyframe index. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ +int32_t OH_ArkUI_AnimatorOption_SetKeyframeCurve(ArkUI_AnimatorOption* option, ArkUI_CurveHandle value, int32_t index); +/** + * @brief Obtains the duration for playing an animation. + * + * @param option Indicates the animator parameters. + * @return Returns the duration for playing the animation, in milliseconds. + * @since 12 + */ +int32_t OH_ArkUI_AnimatorOption_GetDuration(ArkUI_AnimatorOption* option); + +/** + * @brief Obtains the delay for playing the animation of an animator. + * + * @param option Indicates the animator parameters. + * @return Returns the delay for playing the animation, in milliseconds. + * @since 12 + */ +int32_t OH_ArkUI_AnimatorOption_GetDelay(ArkUI_AnimatorOption* option); + +/** + * @brief Obtains the number of times that an animation is played. + * + * @param option Animator animation parameter. + * @return Returns the number of times that the animation is played. + * @since 12 + */ +int32_t OH_ArkUI_AnimatorOption_GetIterations(ArkUI_AnimatorOption* option); + +/** + * @brief Obtains whether the animator animation is restored to the initial state after being executed. + * + * @param option Indicates the animator parameters. + * @return Returns whether the animator animation is restored to the initial state after being executed. + * @since 12 + */ +ArkUI_AnimationFill OH_ArkUI_AnimatorOption_GetFill(ArkUI_AnimatorOption* option); + +/** + * @brief Obtains the playback direction of an animation. + * + * @param option Indicates the animator parameters. + * @return Returns the animation playback direction. + * @since 12 + */ +ArkUI_AnimationDirection OH_ArkUI_AnimatorOption_GetDirection(ArkUI_AnimatorOption* option); + +/** + * @brief Obtains the interpolation curve of the animation of an animator. + * + * @param option Indicates the animator parameters. + * @return Returns the interpolation curve of the animation. + * @since 12 + */ +ArkUI_CurveHandle OH_ArkUI_AnimatorOption_GetCurve(ArkUI_AnimatorOption* option); + +/** + * @brief Obtains the interpolation start point of an animation. + * + * @param option Indicates the animator parameters. + * @return Returns the interpolation start point of the animation. + * @since 12 + */ +float OH_ArkUI_AnimatorOption_GetBegin(ArkUI_AnimatorOption* option); + +/** + * @brief Obtains the interpolation end point of an animation. + * + * @param option Indicates the animator parameters. + * @return Returns the interpolation end point of the animation. + * @since 12 + */ +float OH_ArkUI_AnimatorOption_GetEnd(ArkUI_AnimatorOption* option); + +/** + * @brief Obtains the expected frame rate range of an animation. + * + * @param option Indicates the animator parameters. + * @return Returns the pointer to the expected frame rate range object. + * @since 12 + */ +ArkUI_ExpectedFrameRateRange* OH_ArkUI_AnimatorOption_GetExpectedFrameRateRange(ArkUI_AnimatorOption* option); + +/** + * @brief Obtains the keyframe time of an animation. + * + * @param option Indicates an animator parameter object. + * @param index Indicates the keyframe index. + * @return Returns the keyframe time. + * @since 12 + */ +float OH_ArkUI_AnimatorOption_GetKeyframeTime(ArkUI_AnimatorOption* option, int32_t index); + +/** + * @brief Obtains the keyframe value of an animation. + * + * @param option Indicates an animator parameter object. + * @param index Indicates the keyframe index. + * @return Returns the keyframe value. + * @since 12 + */ +float OH_ArkUI_AnimatorOption_GetKeyframeValue(ArkUI_AnimatorOption* option, int32_t index); + +/** + * @brief Obtains the interpolation curve for a keyframe in the animation of an animator. + * + * @param option Indicates an animator parameter object. + * @param index Indicates the keyframe index. + * @return Returns the interpolation curve. + * @since 12 + */ +ArkUI_CurveHandle OH_ArkUI_AnimatorOption_GetKeyframeCurve(ArkUI_AnimatorOption* option, int32_t index); + +/** + * @brief Obtains the custom object in an animation event object. + * + * @param event Indicates an animation event object. + * @return Returns the custom object. + * @since 12 + */ +void* OH_ArkUI_AnimatorEvent_GetUserData(ArkUI_AnimatorEvent* event); + +/** + * @brief Obtains the custom object in an animation event object. + * + * @param event Indicates an animation event object. + * @return Returns the custom object. + * @since 12 + */ +void* OH_ArkUI_AnimatorOnFrameEvent_GetUserData(ArkUI_AnimatorOnFrameEvent* event); + +/** + * @brief Obtains the current progress in an animation event object. + * + * @param event Indicates an animation event object. + * @return Returns the animation progress. + * @since 12 + */ +float OH_ArkUI_AnimatorOnFrameEvent_GetValue(ArkUI_AnimatorOnFrameEvent* event); + +/** + * @brief Sets the callback invoked when the animator receives a frame. + * + * @param option Indicates the animator parameters. + * @param userData Indicates the custom parameter. + * @param callback Indicates the callback to set. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ +int32_t OH_ArkUI_AnimatorOption_RegisterOnFrameCallback( + ArkUI_AnimatorOption* option, void* userData, void (*callback)(ArkUI_AnimatorOnFrameEvent* event)); + +/** + * @brief Sets the callback invoked when the animation playback is complete. + * + * @param option Indicates the animator parameters. + * @param userData Indicates the custom parameter. + * @param callback Indicates the callback to set. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ +int32_t OH_ArkUI_AnimatorOption_RegisterOnFinishCallback( + ArkUI_AnimatorOption* option, void* userData, void (*callback)(ArkUI_AnimatorEvent* event)); + +/** + * @brief Sets the callback invoked when the animation playback is canceled. + * + * @param option Indicates the animator parameters. + * @param userData Indicates the custom parameter. + * @param callback Indicates the callback to set. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ +int32_t OH_ArkUI_AnimatorOption_RegisterOnCancelCallback( + ArkUI_AnimatorOption* option, void* userData, void (*callback)(ArkUI_AnimatorEvent* event)); + +/** + * @brief Sets the callback invoked when the animation playback is repeated. + * + * @param option Indicates the animator parameters. + * @param userData Indicates the custom parameter. + * @param callback Indicates the callback to set. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ +int32_t OH_ArkUI_AnimatorOption_RegisterOnRepeatCallback( + ArkUI_AnimatorOption* option, void* userData, void (*callback)(ArkUI_AnimatorEvent* event)); + +/** + * @brief Resets the animation of an animator. + * + * @param animator Indicates an animator object. + * @param option Indicates the animator parameters. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ +int32_t OH_ArkUI_Animator_ResetAnimatorOption( + ArkUI_AnimatorHandle animator, ArkUI_AnimatorOption* option); + +/** + * @brief Starts the animation of an animator. + * + * @param animator Indicates an animator object. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ +int32_t OH_ArkUI_Animator_Play(ArkUI_AnimatorHandle animator); + +/** + * @brief Ends the animation of an animator. + * + * @param animator Indicates an animator object. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ +int32_t OH_ArkUI_Animator_Finish(ArkUI_AnimatorHandle animator); + +/** + * @brief Pauses the animation of an animator. + * + * @param animator Indicates an animator object. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ +int32_t OH_ArkUI_Animator_Pause(ArkUI_AnimatorHandle animator); + +/** + * @brief Cancels the animation of an animator. + * + * @param animator Indicates an animator object. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ +int32_t OH_ArkUI_Animator_Cancel(ArkUI_AnimatorHandle animator); + +/** + * @brief Plays the animation of an animator in reverse order. + * + * @param animator Indicates an animator object. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ +int32_t OH_ArkUI_Animator_Reverse(ArkUI_AnimatorHandle animator); + +/** + * @brief Implements initialization for the interpolation curve, which is used to create an interpolation curve based on + * the input parameter. + * + * @param curve Indicates the curve type. + * @return Returns the pointer to the interpolation object of the curve. + * Returns NULL if a parameter error occurs. + */ +ArkUI_CurveHandle OH_ArkUI_Curve_CreateCurveByType(ArkUI_AnimationCurve curve); + +/** + * @brief Creates a step curve. + * + * @param count Indicates the number of steps. The value must be a positive integer. Value range: [1, +∞). + * @param end Indicates whether jumping occurs when the interpolation ends. + * true: Jumping occurs when the interpolation ends. false: Jumping occurs when the interpolation starts. + * @return Returns the pointer to the interpolation object of the curve. + * Returns NULL if a parameter error occurs. + */ +ArkUI_CurveHandle OH_ArkUI_Curve_CreateStepsCurve(int32_t count, bool end); + +/** + * @brief Creates a cubic Bezier curve. + * + * + * @param x1 Indicates the X coordinate of the first point on the Bezier curve. Value range: [0, 1]. + * A value less than 0 is handed as 0. A value greater than 1 is handed as 1. + * @param y1 Indicates the Y coordinate of the first point on the Bezier curve. + * @param x2 Indicates the X coordinate of the second point on the Bezier curve. Value range: [0, 1]. + * A value less than 0 is handed as 0. A value greater than 1 is handed as 1. + * @param y2 Indicates the Y coordinate of the second point on the Bezier curve. + * @return Returns the pointer to the interpolation object of the curve. + * Returns NULL if a parameter error occurs. + */ +ArkUI_CurveHandle OH_ArkUI_Curve_CreateCubicBezierCurve(float x1, float y1, float x2, float y2); + +/** + * @brief Creates a spring curve. The curve shape is subject to the spring parameters, and the animation duration is + * subject to the duration parameter in animation and animateTo. + * + * @param velocity Indicates the initial velocity of the spring. It is applied by external factors to the spring + * animation, designed to help ensure the smooth transition from the previous motion state. The velocity is the + * normalized velocity, and its value is equal to the actual velocity at the beginning of the animation divided by the + * animation attribute change value. + * @param mass Indicates the mass, which influences the inertia in the spring system. The greater the mass, the greater + * the amplitude of the oscillation, and the slower the speed of restoring to the equilibrium position. + * @param stiffness Indicates the stiffness. It is the degree to which an object deforms by resisting the force applied. + * In an elastic system, the greater the stiffness, the stronger the ability to resist deformation, and the faster the + * speed of restoring to the equilibrium position. + * @param damping Indicates the damping. It is used to describe the oscillation and attenuation of the system after + * being disturbed. The larger the damping, the smaller the number of oscillations of elastic motion, and the smaller + * the oscillation amplitude. + * @return Returns the pointer to the interpolation object of the curve. + * Returns NULL if a parameter error occurs. + */ +ArkUI_CurveHandle OH_ArkUI_Curve_CreateSpringCurve(float velocity, float mass, float stiffness, float damping); + +/** + * @brief Creates a spring animation curve. If multiple spring animations are applied to the same attribute of an + * object, each animation replaces their predecessor and inherits the velocity. + * @note The animation duration is subject to the curve parameters, rather than the duration parameter in + * animation or animateTo. + * + * @param response Indicates the duration of one complete oscillation. + * @param dampingFraction Indicates the damping coefficient. + * > 0 and < 1: underdamped. In this case, the spring overshoots the equilibrium position. + * 1: critically damped. + * > 1: overdamped. In this case, the spring approaches equilibrium gradually. + * @param overlapDuration Indicates the duration for animations to overlap. When animations overlap, the response + * values of these animations will transit smoothly over this duration if they are different. + * @return Returns the pointer to the interpolation object of the curve. + * Returns NULL if a parameter error occurs. + */ +ArkUI_CurveHandle OH_ArkUI_Curve_CreateSpringMotion(float response, float dampingFraction, float overlapDuration); + +/** + * @brief Creates a responsive spring animation curve. It is a special case of springMotion, with the only + * difference in the default values. It can be used together with springMotion. + * @note The animation duration is subject to the curve parameters, rather than the duration parameter in + * animation or animateTo. + * + * @param response Indicates the duration of one complete oscillation. + * @param dampingFraction Indicates the damping coefficient. + * > 0 and < 1: underdamped. In this case, the spring overshoots the equilibrium position. + * 1: critically damped. + * > 1: overdamped. In this case, the spring approaches equilibrium gradually. + * @param overlapDuration Indicates the duration for animations to overlap. When animations overlap, the + * response values of these animations will + * transit smoothly over this duration if they are different. + * @return Returns the pointer to the interpolation object of the curve. + * Returns NULL if a parameter error occurs. + */ +ArkUI_CurveHandle OH_ArkUI_Curve_CreateResponsiveSpringMotion( + float response, float dampingFraction, float overlapDuration); + +/** + * @brief Creates an interpolating spring curve animated from 0 to 1. The actual animation value is calculated based on + * the curve. + * @note The animation duration is subject to the curve parameters, rather than the duration parameter in + * animation or animateTo. + * + * + * @param velocity Indicates the initial velocity of the spring. It is applied by external factors to the spring + * animation, esigned to help ensure the smooth transition from the previous motion state. The velocity is the + * normalized velocity, and its value is equal to the actual velocity + * at the beginning of the animation divided by the animation attribute change value. + * @param mass Indicates the mass, which influences the inertia in the spring system. + * The greater the mass, the greater the amplitude of the oscillation, and the slower the speed of restoring to the + * equilibrium position. + * @param stiffness Indicates the stiffness. It is the degree to which an object deforms by resisting the force applied. + * In an elastic system, the greater the stiffness, the stronger the ability to resist deformation, and the faster the + * speed of restoring to the equilibrium position. + * @param damping Indicates the damping. It is used to describe the oscillation and attenuation of the system after + * being disturbed. The larger the damping, the smaller the number of oscillations of elastic motion, and the smaller + * the oscillation amplitude. + * @return Returns the pointer to the interpolation object of the curve. + * Returns NULL if a parameter error occurs. + */ +ArkUI_CurveHandle OH_ArkUI_Curve_CreateInterpolatingSpring(float velocity, float mass, float stiffness, float damping); + +/** + * @brief Creates a custom curve. + * + * @param userData Indicates the custom data. + * @param interpolate Indicates the custom interpolation callback. fraction indicates the input x value for + * interpolation when the animation starts; value range: [0,1]. + * The return value is the y value of the curve; value range: [0,1]. + * If fraction is 0, the return value 0 corresponds to the animation start point; any other return + * value means that the animation jumps at the start point. + * If fraction is 1, the return value 1 corresponds to the animation end point; any other return + * value means that the end value of the animation is not the value of the state variable, + * which will result in an effect of transition from that end value to the value of the state variable. + * @return Returns the pointer to the interpolation object of the curve. + * Returns NULL if a parameter error occurs. + */ +ArkUI_CurveHandle OH_ArkUI_Curve_CreateCustomCurve( + void* userData, float (*interpolate)(float fraction, void* userdata)); + +/** + * @brief Disposes of a custom curve. + * + * @param curve Indicates the pointer to the interpolation object of the curve. + */ +void OH_ArkUI_Curve_DisposeCurve(ArkUI_CurveHandle curveHandle); + + +/** + * @brief Creates an opacity transition effect. + * + * @note If the value specified is less than 0, the value 0 is used. If the value specified is greater than 1, + * the value 1 is used. + * @param opacity Indicates the opacity. Value range: [0, 1]. + * @return Returns the created opacity transition effect. + * @since 12 + */ +ArkUI_TransitionEffect* OH_ArkUI_CreateOpacityTransitionEffect(float opacity); + +/** + * @brief Creates a translation transition effect. + * + * @param translate Indicates the translation settings for component transition. + * @return Returns the created translation transition effect. + * Returns NULL if a parameter error occurs. + * @since 12 + */ +ArkUI_TransitionEffect* OH_ArkUI_CreateTranslationTransitionEffect(ArkUI_TranslationOptions* translate); + +/** + * @brief Creates a scaling transition effect. + * + * @param scale Indicates the scaling settings for component transition. + * @return Returns the created scaling transition effect. + * Returns NULL if a parameter error occurs. + * @since 12 + */ +ArkUI_TransitionEffect* OH_ArkUI_CreateScaleTransitionEffect(ArkUI_ScaleOptions* scale); + +/** + * @brief Creates a rotation transition effect. + * + * @param rotate Indicates the rotation settings for component transition. + * @return Returns the created rotation transition effect. + * Returns NULL if a parameter error occurs. + * @since 12 + */ +ArkUI_TransitionEffect* OH_ArkUI_CreateRotationTransitionEffect(ArkUI_RotationOptions* rotate); + +/** + * @brief Creates a movement transition effect. + * + * @param move Indicates the movement type. + * @return Returns the created movement transition effect. + * Returns NULL if a parameter error occurs. + * @since 12 + */ +ArkUI_TransitionEffect* OH_ArkUI_CreateMovementTransitionEffect(ArkUI_TransitionEdge move); + +/** + * @brief Creates an asymmetric transition effect. + * + * @note If the asymmetric function is not used for TransitionEffect, the transition effect takes effect + * for both appearance and disappearance of the component. + * @param appear Indicates the transition effect for appearance. + * @param disappear Indicates the transition effect for disappearance. + * @return Returns the created asymmetric transition effect; returns NULL if a parameter error occurs. + * @since 12 + */ +ArkUI_TransitionEffect* OH_ArkUI_CreateAsymmetricTransitionEffect( + ArkUI_TransitionEffect* appear, ArkUI_TransitionEffect* disappear); + +/** + * @brief Disposes of a transition effect. + * + * @param option Indicates the transition effect to dispose of. + * @since 12 + */ +void OH_ArkUI_TransitionEffect_Dispose(ArkUI_TransitionEffect* option); + +/** + * @brief Sets a combination of transition effects. + * + * @param option Indicates the transition effect options. + * @param combine Indicates the combination of transition effects. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_TransitionEffect_Combine( + ArkUI_TransitionEffect* option, ArkUI_TransitionEffect* combine); + +/** + * @brief Sets transition effect animation settings. + * + * @note If combine is used for combining transition effects, the animation settings of a transition effect are + * applicable to the one following it. + * @param option Indicates the transition effect options. + * @param animation Indicates the animation settings. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 12 + */ +int32_t OH_ArkUI_TransitionEffect_SetAnimation( + ArkUI_TransitionEffect* option, ArkUI_AnimateOption* animation); +#ifdef __cplusplus +}; +#endif + +#endif // ARKUI_NATIVE_ANIMATE_H +/** @} */ diff --git a/en/native_sdk/ace/native_dialog.h b/en/native_sdk/ace/native_dialog.h new file mode 100644 index 0000000000000000000000000000000000000000..e3cd5b97d6aacdb87385cf3795bf7158355ac377 --- /dev/null +++ b/en/native_sdk/ace/native_dialog.h @@ -0,0 +1,1005 @@ +/* + * Copyright (c) 2024 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup ArkUI_NativeModule + * @{ + * + * @brief Provides UI capabilities of ArkUI on the native side, such as UI component creation and destruction, + * tree node operations, attribute setting, and event listening. + * + * @since 12 + */ + +/** + * @file native_dialog.h + * + * @brief Defines a set of custom dialog box APIs of ArkUI on the native side. + * + * @library libace_ndk.z.so + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @kit ArkUI + * @since 12 + */ + +#ifndef ARKUI_NATIVE_DIALOG_H +#define ARKUI_NATIVE_DIALOG_H + +#include +#include "native_type.h" +#include "native_node.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** +* @brief Enumerates the actions for triggering closure of the dialog box. +* +* @since 12 +*/ +typedef enum { + /** Touching the system-defined Back button or pressing the Esc key. */ + DIALOG_DISMISS_BACK_PRESS = 0, + /** Touching the mask. */ + DIALOG_DISMISS_TOUCH_OUTSIDE, + /** Touching the Close button. */ + DIALOG_DISMISS_CLOSE_BUTTON, + /** Sliding down. */ + DIALOG_DISMISS_SLIDE_DOWN, +} ArkUI_DismissReason; + +/** +* @brief Invoked when the dialog box is closed. +* +* @since 12 +*/ +typedef bool (*ArkUI_OnWillDismissEvent)(int32_t reason); + +/** + * @brief Defines a struct for a dialog box dismiss event. + * + * @since 12 + */ +typedef struct ArkUI_DialogDismissEvent ArkUI_DialogDismissEvent; + +/** + * @brief Defines a struct for the content object of a custom dialog box. + * + * @since 18 + */ +typedef struct ArkUI_CustomDialogOptions ArkUI_CustomDialogOptions; + +/** + * @brief Provides the custom dialog box APIs for the native side. + * + * @version 1 + * @since 12 + */ +typedef struct { + /** + * @brief Creates a custom dialog box and returns the pointer to the created dialog box. + * + * @note This method must be called before the show method. + * @return Returns the pointer to the created custom dialog box; returns a null pointer if the creation fails. + */ + ArkUI_NativeDialogHandle (*create)(); + /** + * @brief Disposes of a custom dialog box. + * + * @param handle Indicates the pointer to the custom dialog box controller. + */ + void (*dispose)(ArkUI_NativeDialogHandle handle); + /** + * @brief Attaches the content of a custom dialog box. + * + * @note This method must be called before the show method. + * @param handle Indicates the pointer to the custom dialog box controller. + * @param content Indicates the pointer to the root node of the custom dialog box content. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ + int32_t (*setContent)(ArkUI_NativeDialogHandle handle, ArkUI_NodeHandle content); + /** + * @brief Detaches the content of a custom dialog box. + * + * @note This method must be called before the show method. + * @param handle Indicates the pointer to the custom dialog box controller. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ + int32_t (*removeContent)(ArkUI_NativeDialogHandle handle); + /** + * @brief Sets the alignment mode for a custom dialog box. + * + * @note This method must be called before the show method. + * @param handle Indicates the pointer to the custom dialog box controller. + * @param alignment Indicates the alignment mode. The parameter type is {@link ArkUI_Alignment}. + * @param offsetX Indicates the horizontal offset of the custom dialog box. The value is a floating point number. + * @param offsetY Indicates the vertical offset of the custom dialog box. The value is a floating point number. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ + int32_t (*setContentAlignment)(ArkUI_NativeDialogHandle handle, int32_t alignment, float offsetX, float offsetY); + /** + * @brief Resets the alignment mode of a custom dialog box to its default settings. + * + * @note This method must be called before the show method. + * @param handle Indicates the pointer to the custom dialog box controller. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ + int32_t (*resetContentAlignment)(ArkUI_NativeDialogHandle handle); + /** + * @brief Sets the modal mode for a custom dialog box. + * + * @note This method must be called before the show method. + * @param handle Indicates the pointer to the custom dialog box controller. + * @param isModal Specifies whether the custom dialog box is a modal, which has a mask applied. The value true + * means that the custom dialog box is a modal, and false means the opposite. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ + int32_t (*setModalMode)(ArkUI_NativeDialogHandle handle, bool isModal); + /** + * @brief Specifies whether to allow users to touch the mask to dismiss the custom dialog box. + * + * @note This method must be called before the show method. + * @param handle Indicates the pointer to the custom dialog box controller. + * @param autoCancel Specifies whether to allow users to touch the mask to dismiss the dialog box. The value + * true means to allow users to do so, and false means the opposite. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ + int32_t (*setAutoCancel)(ArkUI_NativeDialogHandle handle, bool autoCancel); + /** + * @brief Sets the mask for a custom dialog box. + * + * @note This method must be called before the show method. + * @param handle Indicates the pointer to the custom dialog box controller. + * @param maskColor Indicates the mask color, in 0xARGB format. + * @param maskRect Indicates the pointer to the mask area. Events outside the mask area are transparently + * transmitted, and events within the mask area are not. The parameter type is {@link ArkUI_Rect}. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ + int32_t (*setMask)(ArkUI_NativeDialogHandle handle, uint32_t maskColor, const ArkUI_Rect* maskRect); + /** + * @brief Sets the background color for a custom dialog box. + * + * @note This method must be called before the show method. + * @param handle Indicates the pointer to the custom dialog box controller. + * @param backgroundColor Indicates the background color of the custom dialog box, in 0xARGB format. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ + int32_t (*setBackgroundColor)(ArkUI_NativeDialogHandle handle, uint32_t backgroundColor); + /** + * @brief Sets the background corner radius for a custom dialog box. + * + * @note This method must be called before the show method. + * @param handle Indicates the pointer to the custom dialog box controller. + * @param topLeft Indicates the radius of the upper left corner of the custom dialog box background. + * @param topRight Indicates the radius of the upper right corner of the custom dialog box background. + * @param bottomLeft Indicates the radius of the lower left corner of the custom dialog box background. + * @param bottomRight Indicates the radius of the lower right corner of the custom dialog box background. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ + int32_t (*setCornerRadius)(ArkUI_NativeDialogHandle handle, float topLeft, float topRight, + float bottomLeft, float bottomRight); + /** + * @brief Sets the number of grid columns occupied by a custom dialog box. + * + * @note This method must be called before the show method. + * @param handle Indicates the pointer to the custom dialog box controller. + * @param gridCount Indicates the number of grid columns occupied by the dialog box. The default value is subject to + * the window size, and the maximum value is the maximum number of columns supported by the system. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ + int32_t (*setGridColumnCount)(ArkUI_NativeDialogHandle handle, int32_t gridCount); + /** + * @brief Specifies whether to use a custom style for the custom dialog box. + * + * @note This method must be called before the show method. + * @param handle Indicates the pointer to the custom dialog box controller. + * @param enableCustomStyle Specifies whether to use a custom style for the dialog box. + * true: The dialog box automatically adapts its width to the child components; the rounded corner is 0; + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ + int32_t (*enableCustomStyle)(ArkUI_NativeDialogHandle handle, bool enableCustomStyle); + /** + * @brief Specifies whether to use a custom animation for a custom dialog box. + * + * @note This method must be called before the show method. + * @param handle Indicates the pointer to the custom dialog box controller. + * @param enableCustomAnimation Specifies whether to use a custom animation. The value true means to use a + * custom animation, and false means to use the default animation. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ + int32_t (*enableCustomAnimation)(ArkUI_NativeDialogHandle handle, bool enableCustomAnimation); + /** + * @brief Registers a callback for a custom dialog box so that the user can decide whether to close the dialog box + * after they touch the Back button or press the Esc key. + * + * @note This method must be called before the show method. + * @param handle Indicates the pointer to the custom dialog box controller. + * @param eventHandler Indicates the callback to register. The parameter type is {@link OnWillDismissEvent}. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ + int32_t (*registerOnWillDismiss)(ArkUI_NativeDialogHandle handle, ArkUI_OnWillDismissEvent eventHandler); + /** + * @brief Shows a custom dialog box. + * + * @param handle Indicates the pointer to the custom dialog box controller. + * @param showInSubWindow Specifies whether to show the dialog box in a sub-window. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ + int32_t (*show)(ArkUI_NativeDialogHandle handle, bool showInSubWindow); + /** + * @brief Closes a custom dialog box. If the dialog box has been closed, this API does not take effect. + * + * @param handle Indicates the pointer to the custom dialog box controller. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ + int32_t (*close)(ArkUI_NativeDialogHandle handle); + /** + * @brief Registers a listener for the dismiss event of the custom dialog box. + * + * @param handle Indicates the pointer to the custom dialog box controller. + * @param userData Indicates the pointer to the custom data. + * @param callback Indicates the callback for the dismiss event of the custom dialog box. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + */ + int32_t (*registerOnWillDismissWithUserData)( + ArkUI_NativeDialogHandle handle, void* userData, void (*callback)(ArkUI_DialogDismissEvent* event)); +} ArkUI_NativeDialogAPI_1; + +/** + * @brief Provides the custom dialog box APIs for the native side. + * + * @version 2 + * @since 15 + */ +typedef struct { + ArkUI_NativeDialogAPI_1 nativeDialogAPI1; + /** + * @brief Sets the distance for the custom dialog box to avoid the system keyboard. + * + * @note This method must be called before the show method. + * @param handle Indicates the pointer to the custom dialog box controller. + * @param distance Distance to avoid the keyboard. The default value is vp. + * @param unit Unit of the avoidance distance. The parameter type is {@link ArkUI_LengthMetricUnit}. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 16 + */ + int32_t (*setKeyboardAvoidDistance)(ArkUI_NativeDialogHandle handle, float distance, ArkUI_LengthMetricUnit unit); + /** + * @brief Sets the border width of the dialog box. + * + * @note This method must be called before the show method. + * @param handle Pointer to the dialog box controller. + * @param top Width of the top border. + * @param right Width of the right border. + * @param bottom Width of the bottom border. + * @param left Width of the left border. + * @param unit Unit of the width. The default value is vp. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ + int32_t (*setBorderWidth)( + ArkUI_NativeDialogHandle handle, float top, float right, float bottom, float left, ArkUI_LengthMetricUnit unit); + /** + * @brief Sets the border color of the dialog box. + * + * @note This method must be called before the show method. + * @param handle Pointer to the dialog box controller. + * @param top Color of the top border. + * @param right Color of the right border. + * @param bottom Color of the bottom border. + * @param left Color of the left border. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ + int32_t (*setBorderColor)( + ArkUI_NativeDialogHandle handle, uint32_t top, uint32_t right, uint32_t bottom, uint32_t left); + /** + * @brief Sets the border style of the dialog box. + * + * @note This method must be called before the show method. + * @param handle Pointer to the dialog box controller. + * @param top Style of the top border. + * @param right Style of the right border. + * @param bottom Style of the bottom border. + * @param left Style of the left border. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ + int32_t (*setBorderStyle)( + ArkUI_NativeDialogHandle handle, int32_t top, int32_t right, int32_t bottom, int32_t left); + /** + * @brief Sets the width of the dialog box background. + * + * @note This method must be called before the show method. + * @param handle Pointer to the dialog box controller. + * @param width Width of the background. + * @param unit Unit of the width. The default value is vp. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ + int32_t (*setWidth)(ArkUI_NativeDialogHandle handle, float width, ArkUI_LengthMetricUnit unit); + /** + * @brief Sets the height of the dialog box background. + * + * @note This method must be called before the show method. + * @param handle Pointer to the dialog box controller. + * @param height Height of the background. + * @param unit Unit of the height. The default value is vp. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ + int32_t (*setHeight)(ArkUI_NativeDialogHandle handle, float height, ArkUI_LengthMetricUnit unit); + /** + * @brief Sets the shadow of the dialog box background. + * + * @note This method must be called before the show method. + * @param handle Pointer to the dialog box controller. + * @param shadow Shadow style of the background, specified by an enumerated value. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ + int32_t (*setShadow)(ArkUI_NativeDialogHandle handle, ArkUI_ShadowStyle shadow); + /** + * @brief Sets the custom shadow of the dialog box background. + * + * @note This method must be called before the show method. + * @param handle Pointer to the dialog box controller. + * @param customShadow Custom shadow parameter. The format is the same as that of the NODE_SHADOW property. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ + int32_t (*setCustomShadow)(ArkUI_NativeDialogHandle handle, const ArkUI_AttributeItem* customShadow); + /** + * @brief Sets the background blur style of the dialog box. + * + * @note This method must be called before the show method. + * @param handle Pointer to the dialog box controller. + * @param blurStyle Background blur style, specified by an enumerated value. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ + int32_t (*setBackgroundBlurStyle)(ArkUI_NativeDialogHandle handle, ArkUI_BlurStyle blurStyle); + /** + * @brief Sets the keyboard avoidance mode of the dialog box. + * + * @note This method must be called before the show method. + * @param handle Pointer to the dialog box controller. + * @param keyboardAvoidMode Keyboard avoidance mode, specified by an enumerated value. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ + int32_t (*setKeyboardAvoidMode)(ArkUI_NativeDialogHandle handle, ArkUI_KeyboardAvoidMode keyboardAvoidMode); + /** + * @brief Sets whether to enable the hover mode for the dialog box. + * + * @note This method must be called before the show method. + * @param handle Pointer to the dialog box controller. + * @param enableHoverMode Whether to enable the hover mode. The default value is false. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ + int32_t (*enableHoverMode)(ArkUI_NativeDialogHandle handle, bool enableHoverMode); + /** + * @brief Sets the default display area of the dialog box in hover mode. + * + * @note This method must be called before the show method. + * @param handle Pointer to the dialog box controller. + * @param hoverModeAreaType Display area in hover mode, specified by an enumerated value. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ + int32_t (*setHoverModeArea)(ArkUI_NativeDialogHandle handle, ArkUI_HoverModeAreaType hoverModeAreaType); + /** + * @brief Sets the background blur effect for a custom dialog box. + * + * @note This method must be called before the show method. + * @param handle Pointer to the custom dialog box controller. + * @param backgroundBlurStyleOptions Background blur effect options. + * Format of the {@link ArkUI_AttributeItem} parameter: \n + * .value[0].i32: color mode. The value is an enum of {@link ArkUI_ColorMode}. \n + * .value[1]?.i32: adaptive color mode. The value is an enum of {@link ArkUI_AdaptiveColor}. \n + * .value[2]?.f32: blur degree. The value range is [0.0, 1.0]. \n + * .value[3]?.u32: brightness of black in the grayscale blur. The value range is [0, 127]. \n + * .value[4]?.u32: degree of darkening the white color in the grayscale blur. The value range is [0, 127]. \n + * .value[5]?.i32: blur activation policy. The value is an enum of {@link ArkUI_BlurStyleActivePolicy}. \n + * .value[6]?.u32: background color, in 0xARGB format, of the components within the window after the window + * loses focus (in which case, the blur effect on the components within the window is + * removed). \n + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ + int32_t (*setBackgroundBlurStyleOptions)( + ArkUI_NativeDialogHandle handle, const ArkUI_AttributeItem* backgroundBlurStyleOptions); + /** + * @brief Sets the background effect parameters for a custom dialog box. + * + * @note This method must be called before the show method. + * @param handle Pointer to the custom dialog box controller. + * @param backgroundEffect Background effect. + * Format of the {@link ArkUI_AttributeItem} parameter: \n + * .value[0].f32: blur radius, in vp. \n + * .value[1]?.f32: saturation. \n + * .value[2]?.f32: brightness. \n + * .value[3]?.u32: color, in 0xARGB format. \n + * .value[4]?.i32: adaptive color mode. The value is an enum of {@link ArkUI_AdaptiveColor}. \n + * .value[5]?.u32: brightness of black in the grayscale blur. The value range is [0, 127]. \n + * .value[6]?.u32: degree of darkening the white color in the grayscale blur. The value range is [0, 127]. \n + * .value[7]?.i32: blur activation policy. The value is an enum of {@link ArkUI_BlurStyleActivePolicy}. \n + * .value[8]?.u32: background color, in 0xARGB format, of the components within the window after the window + * loses focus (in which case, the blur effect on the components within the window is + * removed). \n + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ + int32_t (*setBackgroundEffect)(ArkUI_NativeDialogHandle handle, const ArkUI_AttributeItem* backgroundEffect); +} ArkUI_NativeDialogAPI_3; + +/** + * @brief Sets whether to block the system behavior of dismissing a dialog box. + * + * @param event Pointer to a dialog box dismiss event object. + * @param shouldBlockDismiss Indicates whether to block the system behavior of dismissing the dialog box. The value + * true means to block the system behavior, and false means the opposite. + * @since 12 + */ +void OH_ArkUI_DialogDismissEvent_SetShouldBlockDismiss(ArkUI_DialogDismissEvent* event, bool shouldBlockDismiss); + +/** + * @brief Obtains the pointer to user data in a dialog box dismiss event object. + * + * @param event Pointer to a dialog box dismiss event object. + * + * @return Returns the pointer to user data. + * @since 12 + */ +void* OH_ArkUI_DialogDismissEvent_GetUserData(ArkUI_DialogDismissEvent* event); + +/** + * @brief Obtains the dismissal reason from a dialog box dismiss event object. + * + * @param event Pointer to a dialog box dismiss event object. + * + * @return Returns the dismissal reason. Returns -1 if an exception occurs. + * {@link DIALOG_DISMISS_BACK_PRESS}: touching the Back button, swiping left or right on the screen, or + * pressing the Esc key. + * {@link DIALOG_DISMISS_TOUCH_OUTSIDE}: touching the mask. + * {@link DIALOG_DISMISS_CLOSE_BUTTON}: touching the Close button. + * {@link DIALOG_DISMISS_SLIDE_DOWN}: sliding down. + * @since 12 + */ +int32_t OH_ArkUI_DialogDismissEvent_GetDismissReason(ArkUI_DialogDismissEvent* event); + +/** + * @brief Displays a custom dialog box. + * + * @param options Dialog box parameters. + * @param callback Callback invoked when the dialog box is displayed. The parameter is the dialog box ID. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ +int32_t OH_ArkUI_CustomDialog_OpenDialog(ArkUI_CustomDialogOptions* options, void (*callback)(int32_t dialogId)); + +/** + * @brief Updates a custom dialog box. + * + * @param options Dialog box parameters. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ +int32_t OH_ArkUI_CustomDialog_UpdateDialog(ArkUI_CustomDialogOptions* options); + +/** + * @brief Closes a custom dialog box. + * + * @param dialogId ID of the dialog box to close. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ +int32_t OH_ArkUI_CustomDialog_CloseDialog(int32_t dialogId); + +/** + * @brief Creates custom dialog box options. + * + * @param content Content of the custom dialog box. + * @return Returns the pointer to the custom dialog box options. + * @since 18 + */ +ArkUI_CustomDialogOptions* OH_ArkUI_CustomDialog_CreateOptions(ArkUI_NodeHandle content); + +/** + * @brief Destroys custom dialog box options. + * + * @param options Pointer to the custom dialog box options. + * @since 18 + */ +void OH_ArkUI_CustomDialog_DisposeOptions(ArkUI_CustomDialogOptions* options); + +/** + * @brief Sets the display level mode of a custom dialog box. + * + * @note This method must be called before the show method. + * @param options Pointer to the custom dialog box options. + * @param levelMode Display level mode, specified by an enumeration value of {@link ArkUI_LevelMode}. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 15 + */ +int32_t OH_ArkUI_CustomDialog_SetLevelMode(ArkUI_CustomDialogOptions* options, ArkUI_LevelMode levelMode); + +/** + * @brief Sets the ID of the node under the dialog box's display level. + * + * @note This method must be called before the show method. + * @param options Pointer to the custom dialog box options. + * @param uniqueId ID of the node under the dialog box's display level. + * The dialog box will be displayed on the same page as this node. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 15 + */ +int32_t OH_ArkUI_CustomDialog_SetLevelUniqueId(ArkUI_CustomDialogOptions* options, int32_t uniqueId); + +/** + * @brief Sets the display area of the embedded dialog box overlay. + * + * @note This method must be called before the show method. + * @param options Pointer to the custom dialog box options. + * @param immersiveMode Display area, specified by an enumeration value of {@link ArkUI_ImmersiveMode}. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 15 + */ +int32_t OH_ArkUI_CustomDialog_SetImmersiveMode(ArkUI_CustomDialogOptions* options, ArkUI_ImmersiveMode immersiveMode); + +/** + * @brief Sets the background color of the dialog box. + * + * @param options Dialog box parameters. + * @param backgroundColor Background color of the dialog box. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ +int32_t OH_ArkUI_CustomDialog_SetBackgroundColor(ArkUI_CustomDialogOptions* options, uint32_t backgroundColor); + +/** + * @brief Sets the corner radius for a custom dialog box. + * + * @param options Dialog box parameters. + * @param topLeft Corner radius of the upper left corner. + * @param topRight Corner radius of the upper right corner. + * @param bottomLeft Corner radius of the lower left corner. + * @param bottomRight Corner radius of the lower right corner. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ +int32_t OH_ArkUI_CustomDialog_SetCornerRadius( + ArkUI_CustomDialogOptions* options, float topLeft, float topRight, float bottomLeft, float bottomRight); + +/** + * @brief Sets the border width of the dialog box. + * + * @param options Dialog box parameters. + * @param top Width of the top border. + * @param right Width of the right border. + * @param bottom Width of the bottom border. + * @param left Width of the left op border. + * @param unit Unit of the width. The default value is vp. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ +int32_t OH_ArkUI_CustomDialog_SetBorderWidth( + ArkUI_CustomDialogOptions* options, float top, float right, float bottom, float left, ArkUI_LengthMetricUnit unit); + +/** + * @brief Sets the border color of the dialog box. + * + * @param options Dialog box parameters. + * @param top Color of the top border. + * @param right Color of the right border. + * @param bottom Color of the bottom border. + * @param left Color of the left border. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ +int32_t OH_ArkUI_CustomDialog_SetBorderColor( + ArkUI_CustomDialogOptions* options, uint32_t top, uint32_t right, uint32_t bottom, uint32_t left); + +/** + * @brief Sets the border style of the dialog box. + * + * @param options Dialog box parameters. + * @param top Style of the top border. + * @param right Style of the right border. + * @param bottom Style of the bottom border. + * @param left Style of the left border. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ +int32_t OH_ArkUI_CustomDialog_SetBorderStyle( + ArkUI_CustomDialogOptions* options, int32_t top, int32_t right, int32_t bottom, int32_t left); + +/** + * @brief Sets the width of the dialog box background. + * + * @param options Dialog box parameters. + * @param width Width of the background. + * @param unit Unit of the width. The default value is vp. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ +int32_t OH_ArkUI_CustomDialog_SetWidth(ArkUI_CustomDialogOptions* options, float width, ArkUI_LengthMetricUnit unit); + +/** + * @brief Sets the height of the dialog box background. + * + * @param options Dialog box parameters. + * @param height Height of the dialog box background. + * @param unit Unit of the width. The default value is vp. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ +int32_t OH_ArkUI_CustomDialog_SetHeight(ArkUI_CustomDialogOptions* options, float height, ArkUI_LengthMetricUnit unit); + +/** + * @brief Sets the shadow of the dialog box background. + * + * @param options Dialog box parameters. + * @param shadow Shadow style of the background, specified by an enumerated value. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ +int32_t OH_ArkUI_CustomDialog_SetShadow(ArkUI_CustomDialogOptions* options, ArkUI_ShadowStyle shadow); + +/** + * @brief Sets the shadow of the dialog box background. + * + * @param options Dialog box parameters. + * @param customShadow Custom shadow parameter. The format is the same as that of the NODE_SHADOW property. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ +int32_t OH_ArkUI_CustomDialog_SetCustomShadow( + ArkUI_CustomDialogOptions* options, const ArkUI_AttributeItem* customShadow); + +/** + * @brief Sets the background blur style of the dialog box. + * + * @param options Dialog box parameters. + * @param blurStyle Background blur style, specified by an enumerated value. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ +int32_t OH_ArkUI_CustomDialog_SetBackgroundBlurStyle(ArkUI_CustomDialogOptions* options, ArkUI_BlurStyle blurStyle); + +/** + * @brief Sets the alignment mode of the dialog box. + * + * @param options Dialog box parameters. + * @param alignment Alignment mode of the dialog box. The parameter type is {@link ArkUI_Alignment}. + * @param offsetX Indicates the horizontal offset of the custom dialog box. The value is a floating point number. + * @param offsetY Indicates the vertical offset of the custom dialog box. The value is a floating point number. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ +int32_t OH_ArkUI_CustomDialog_SetAlignment( + ArkUI_CustomDialogOptions* options, int32_t alignment, float offsetX, float offsetY); + +/** + * @brief Sets the modal mode for a custom dialog box. + * + * @param options Dialog box parameters. + * @param isModal Whether the dialog box is a modal. A modal dialog box has a mask applied, + * while a non-modal dialog box does not. The value true means that the dialog box is a modal. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ +int32_t OH_ArkUI_CustomDialog_SetModalMode(ArkUI_CustomDialogOptions* options, bool isModal); + +/** + * @brief Specifies whether to allow users to touch the mask to dismiss the custom dialog box. + * + * @param options Dialog box parameters. + * @param autoCancel Specifies whether to allow users to touch the mask to dismiss the dialog box. + * The value true means to allow users to do so, and false means the opposite. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ +int32_t OH_ArkUI_CustomDialog_SetAutoCancel(ArkUI_CustomDialogOptions* options, bool autoCancel); + +/** + * @brief Sets whether to display the dialog box in a subwindow. + * + * @param options Dialog box parameters. + * @param isShowInSubwindow Whether to display the dialog box in a subwindow when it is not in the main window. + * The default value is false, meaning the dialog box is displayed within the application, not in a + * separate subwindow. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ +int32_t OH_ArkUI_CustomDialog_SetSubwindowMode(ArkUI_CustomDialogOptions* options, bool showInSubwindow); + +/** + * @brief Sets the mask for a custom dialog box. + * + * @param options Dialog box parameters. + * @param maskColor Mask color, in 0xargb format. + * @param maskRect Pointer to the mask area. Events outside the mask area are transparently transmitted, + * and events within the mask area are not. The parameter type is {@link ArkUI_Rect}. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ +int32_t OH_ArkUI_CustomDialog_SetMask( + ArkUI_CustomDialogOptions* options, uint32_t maskColor, const ArkUI_Rect* maskRect); + +/** + * @brief Sets the keyboard avoidance mode of the dialog box. + * + * @param options Dialog box parameters. + * @param keyboardAvoidMode Keyboard avoidance mode, specified by an enumerated value. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ +int32_t OH_ArkUI_CustomDialog_SetKeyboardAvoidMode( + ArkUI_CustomDialogOptions* options, ArkUI_KeyboardAvoidMode keyboardAvoidMode); + +/** + * @brief Sets whether to enable the hover mode for the dialog box. + * + * @param options Dialog box parameters. + * @param enabled Whether to enable the hover mode. The default value is false. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ +int32_t OH_ArkUI_CustomDialog_SetHoverModeEnabled(ArkUI_CustomDialogOptions* options, bool enabled); + +/** + * @brief Sets the default display area of the dialog box in hover mode. + * + * @param options Dialog box parameters. + * @param hoverModeAreaType Display area in hover mode, specified by an enumerated value. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ +int32_t OH_ArkUI_CustomDialog_SetHoverModeArea( + ArkUI_CustomDialogOptions* options, ArkUI_HoverModeAreaType hoverModeAreaType); + +/** + * @brief Registers a callback for the dismissal event of the custom dialog box. + * + * @param options Dialog box parameters. + * @param userData Pointer to the user-defined data. + * @param callback Callback for the dismissal event of the custom dialog box. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ +int32_t OH_ArkUI_CustomDialog_RegisterOnWillDismissCallback( + ArkUI_CustomDialogOptions* options, void* userData, void (*callback)(ArkUI_DialogDismissEvent* event)); + +/** + * @brief Registers a callback to be invoked when the custom dialog box is about to appear. + * + * @param options Dialog box parameters. + * @param userData Pointer to the user-defined data. + * @param callback Callback to be invoked when the dialog box is about to appear. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ +int32_t OH_ArkUI_CustomDialog_RegisterOnWillAppearCallback( + ArkUI_CustomDialogOptions* options, void* userData, void (*callback)(void* userData)); + +/** + * @brief Registers a callback to be invoked when the custom dialog box appears. + * + * @param options Dialog box parameters. + * @param userData Pointer to the user-defined data. + * @param callback Callback to be invoked when the custom dialog box appears. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ +int32_t OH_ArkUI_CustomDialog_RegisterOnDidAppearCallback( + ArkUI_CustomDialogOptions* options, void* userData, void (*callback)(void* userData)); + +/** + * @brief Registers a callback to be invoked when the custom dialog box is about to disappear. + * + * @param options Dialog box parameters. + * @param userData Pointer to the user-defined data. + * @param callback Callback to be invoked when the dialog box is about to disappear. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ +int32_t OH_ArkUI_CustomDialog_RegisterOnWillDisappearCallback( + ArkUI_CustomDialogOptions* options, void* userData, void (*callback)(void* userData)); + +/** + * @brief Registers a callback to be invoked when the custom dialog box disappears. + * + * @param options Dialog box parameters. + * @param userData Pointer to the user-defined data. + * @param callback Callback to be invoked when the custom dialog box disappears. + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ +int32_t OH_ArkUI_CustomDialog_RegisterOnDidDisappearCallback( + ArkUI_CustomDialogOptions* options, void* userData, void (*callback)(void* userData)); + +/** + * @brief Sets the background blur effect for a dialog box. + * + * @param options Dialog box parameters. + * @param backgroundBlurStyleOptions Background blur effect options of the dialog box. + * Format of the {@link ArkUI_AttributeItem} parameter: \n + * .value[0].i32: color mode. The value is an enum of {@link ArkUI_ColorMode}. \n + * .value[1]?.i32: adaptive color mode. The value is an enum of {@link ArkUI_AdaptiveColor}. \n + * .value[2]?.f32: blur degree. The value range is [0.0, 1.0]. \n + * .value[3]?.u32: brightness of black in the grayscale blur. The value range is [0, 127]. \n + * .value[4]?.u32: degree of darkening the white color in the grayscale blur. The value range is [0, 127]. \n + * .value[5]?.i32: blur activation policy. The value is an enum of {@link ArkUI_BlurStyleActivePolicy}. \n + * .value[6]?.u32: background color, in 0xARGB format, of the components within the window after the window loses + * focus (in which case, the blur effect on the components within the window is removed). \n + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ +int32_t OH_ArkUI_CustomDialog_SetBackgroundBlurStyleOptions( + ArkUI_CustomDialogOptions* options, const ArkUI_AttributeItem* backgroundBlurStyleOptions); + +/** + * @brief Sets the background effect parameters for a dialog box. + * + * @param options Dialog box parameters. + * @param backgroundEffect Background effect of the dialog box. + * Format of the {@link ArkUI_AttributeItem} parameter: \n + * .value[0].f32: blur radius, in vp. \n + * .value[1]?.f32: saturation. \n + * .value[2]?.f32: brightness. \n + * .value[3]?.u32: color, in 0xARGB format. \n + * .value[4]?.i32: adaptive color mode. The value is an enum of {@link ArkUI_AdaptiveColor}. \n + * .value[5]?.u32: brightness of black in the grayscale blur. The value range is [0, 127]. \n + * .value[6]?.u32: degree of darkening the white color in the grayscale blur. The value range is [0, 127]. \n + * .value[7]?.i32: blur activation policy. The value is an enum of {@link ArkUI_BlurStyleActivePolicy}. \n + * .value[8]?.u32: background color, in 0xARGB format, of the components within the window after the window loses + * focus (in which case, the blur effect on the components within the window is removed). \n + * @return Returns the result code. + * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. + * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. + * @since 18 + */ +int32_t OH_ArkUI_CustomDialog_SetBackgroundEffect( + ArkUI_CustomDialogOptions* options, const ArkUI_AttributeItem* backgroundEffect); + +#ifdef __cplusplus +}; +#endif + +#endif // ARKUI_NATIVE_DIALOG_H +/** @} */ diff --git a/en/native_sdk/ace/native_gesture.h b/en/native_sdk/ace/native_gesture.h new file mode 100644 index 0000000000000000000000000000000000000000..cf402b5e34326b43590b80039a5c61430feeb6e0 --- /dev/null +++ b/en/native_sdk/ace/native_gesture.h @@ -0,0 +1,1169 @@ +/* + * Copyright (c) 2024 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup ArkUI_NativeModule + * @{ + * + * @brief Defines APIs for ArkUI to register gesture callbacks on the native side. + * + * @since 12 + */ + +/** + * @file native_gesture.h + * + * @brief Provides type definitions for NativeGesture APIs. + * + * @library libace_ndk.z.so + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @kit ArkUI + * @since 12 + */ + +#ifndef ARKUI_NATIVE_GESTTURE_H +#define ARKUI_NATIVE_GESTTURE_H + +#include "ui_input_event.h" +#include "native_type.h" +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Defines a gesture recognizer. + * + * @since 12 + */ +typedef struct ArkUI_GestureRecognizer ArkUI_GestureRecognizer; + +/** + * @brief Defines the gesture interruption information. + * + * @since 12 + */ +typedef struct ArkUI_GestureInterruptInfo ArkUI_GestureInterruptInfo; + +/** + * @brief Defines the gesture event. + * + * @since 12 + */ +typedef struct ArkUI_GestureEvent ArkUI_GestureEvent; + +/** + * @brief Enumerates gesture event types. + * + * @since 12 + */ +typedef enum { + /** Triggered. */ + GESTURE_EVENT_ACTION_ACCEPT = 0x01, + + /** Updated. */ + GESTURE_EVENT_ACTION_UPDATE = 0x02, + + /** Ended. */ + GESTURE_EVENT_ACTION_END = 0x04, + + /** Canceled. */ + GESTURE_EVENT_ACTION_CANCEL = 0x08, +} ArkUI_GestureEventActionType; + +/** + * @brief Defines a set of gesture event types. + * + * Example: ArkUI_GestureEventActionTypeMask actions = GESTURE_EVENT_ACTION_ACCEPT | GESTURE_EVENT_ACTION_UPDATE;\n + * + * @since 12 + */ +typedef uint32_t ArkUI_GestureEventActionTypeMask; + +/** + * @brief Enumerates gesture event modes. + * + * @since 12 + */ +typedef enum { + /** Normal. */ + NORMAL = 0, + + /** High-priority. */ + PRIORITY = 1, + + /** Parallel. */ + PARALLEL = 2, +} ArkUI_GesturePriority; + +/** + * @brief Enumerates gesture group modes. + * + * @since 12 + */ +typedef enum { + /** Sequential recognition. Gestures are recognized in the registration sequence until all gestures are recognized + * successfully. Once one gesture fails to be recognized, all subsequent gestures fail to be recognized. + * Only the last gesture in the gesture group can respond to the end event. */ + SEQUENTIAL_GROUP = 0, + + /** Parallel recognition. Registered gestures are recognized concurrently until all gestures are recognized. + * The recognition result of each gesture does not affect each other. */ + PARALLEL_GROUP = 1, + + /** Exclusive recognition. Registered gestures are identified concurrently. + * If one gesture is successfully recognized, gesture recognition ends. */ + EXCLUSIVE_GROUP = 2, +} ArkUI_GroupGestureMode; + +/** + * @brief Enumerates gesture directions. + * + * @since 12 + */ +typedef enum { + /** All directions. */ + GESTURE_DIRECTION_ALL = 0b1111, + + /** Horizontal direction. */ + GESTURE_DIRECTION_HORIZONTAL = 0b0011, + + /** Vertical direction. */ + GESTURE_DIRECTION_VERTICAL = 0b1100, + + /** Leftward. */ + GESTURE_DIRECTION_LEFT = 0b0001, + + /** Rightward. */ + GESTURE_DIRECTION_RIGHT = 0b0010, + + /** Upward. */ + GESTURE_DIRECTION_UP = 0b0100, + + /** Downward. */ + GESTURE_DIRECTION_DOWN = 0b1000, + + /** None. */ + GESTURE_DIRECTION_NONE = 0, +} ArkUI_GestureDirection; + +/** + * @brief Defines a set of gesture directions. + * + * Example: ArkUI_GestureDirectionMask directions = GESTURE_DIRECTION_LEFT | GESTURE_DIRECTION_RIGHT \n + * This example indicates that the leftward and rightward directions are supported. \n + * + * @since 12 + */ +typedef uint32_t ArkUI_GestureDirectionMask; + +/** + * @brief Enumerates gesture masking modes. + * + * @since 12 + */ +typedef enum { + /** The gestures of child components are enabled and recognized based on the default gesture recognition sequence.*/ + NORMAL_GESTURE_MASK = 0, + + /** The gestures of child components are disabled, including the built-in gestures. */ + IGNORE_INTERNAL_GESTURE_MASK, +} ArkUI_GestureMask; + +/** + * @brief Enumerates gesture types. + * + * @since 12 + */ +typedef enum { + /** Tap. */ + TAP_GESTURE = 0, + + /** Long press. */ + LONG_PRESS_GESTURE, + + /** Pan. */ + PAN_GESTURE, + + /** Pinch. */ + PINCH_GESTURE, + + /** Rotate. */ + ROTATION_GESTURE, + + /** Swipe. */ + SWIPE_GESTURE, + + /** A group of gestures. */ + GROUP_GESTURE, +} ArkUI_GestureRecognizerType; + +/** + * @brief Enumerates gesture interruption results. + * + * @since 12 + */ +typedef enum { + /** The gesture recognition process continues. */ + GESTURE_INTERRUPT_RESULT_CONTINUE = 0, + + /** The gesture recognition process is paused. */ + GESTURE_INTERRUPT_RESULT_REJECT, +} ArkUI_GestureInterruptResult; + +/** + * @brief Enumerates the gesture recognizer states. + * + * @since 12 + */ +typedef enum { + /** Ready. */ + ARKUI_GESTURE_RECOGNIZER_STATE_READY = 0, + + /** Detecting. */ + ARKUI_GESTURE_RECOGNIZER_STATE_DETECTING = 1, + + /** Pending. */ + ARKUI_GESTURE_RECOGNIZER_STATE_PENDING = 2, + + /** Blocked. */ + ARKUI_GESTURE_RECOGNIZER_STATE_BLOCKED = 3, + + /** Successful. */ + ARKUI_GESTURE_RECOGNIZER_STATE_SUCCESSFUL = 4, + + /** Failed. */ + ARKUI_GESTURE_RECOGNIZER_STATE_FAILED = 5, +} ArkUI_GestureRecognizerState; + +/** + * @brief Defines the gesture recognizer handle. + * + * @since 12 + */ +typedef ArkUI_GestureRecognizer* ArkUI_GestureRecognizerHandle; + +/** + * @brief Defines the gesture recognizer handle array. + * + * @since 12 + */ +typedef ArkUI_GestureRecognizerHandle* ArkUI_GestureRecognizerHandleArray; + +/** + * @brief Defines a GestureEventTargetInfo object that provides information about a gesture event target. + * + * @since 12 + */ +typedef struct ArkUI_GestureEventTargetInfo ArkUI_GestureEventTargetInfo; + +/** + * @brief Defines a parallel internal gesture event. + * + * @since 12 + */ +typedef struct ArkUI_ParallelInnerGestureEvent ArkUI_ParallelInnerGestureEvent; + +/** + * @brief Defines a touch recognizer. + * + * @since 15 + */ +typedef struct ArkUI_TouchRecognizer ArkUI_TouchRecognizer; + +/** + * @brief Defines a touch recognizer handle. + * + * @since 15 + */ +typedef ArkUI_TouchRecognizer* ArkUI_TouchRecognizerHandle; + +/** + * @brief Defines an array of touch recognizer handles. + * + * @since 15 + */ +typedef ArkUI_TouchRecognizerHandle* ArkUI_TouchRecognizerHandleArray; + +/** + * @brief Defines a callback function for notifying gesture recognizer destruction. + * @since 12 + */ +typedef void (*ArkUI_GestureRecognizerDisposeNotifyCallback)(ArkUI_GestureRecognizer* recognizer, void* userData); + +/** +* @brief Checks whether a gesture is a built-in gesture of the component. +* +* @param event Indicates the pointer to the gesture interruption information. +* @return Returns true if the gesture is a built-in gesture; returns false otherwise. + +* @since 12 +*/ +bool OH_ArkUI_GestureInterruptInfo_GetSystemFlag(const ArkUI_GestureInterruptInfo* event); + +/** +* @brief Obtains the pointer to interrupted gesture recognizer. +* +* @param event Indicates the pointer to the gesture interruption information. +* @return Returns the pointer to interrupted gesture recognizer. +* @since 12 +*/ +ArkUI_GestureRecognizer* OH_ArkUI_GestureInterruptInfo_GetRecognizer(const ArkUI_GestureInterruptInfo* event); + +/** +* @brief Obtains the pointer to the interrupted gesture event. +* +* @param event Indicates the pointer to the gesture interruption information. +* @return Returns the pointer to the interrupted gesture event. +* @since 12 +*/ +ArkUI_GestureEvent* OH_ArkUI_GestureInterruptInfo_GetGestureEvent(const ArkUI_GestureInterruptInfo* event); + +/** +* @brief Obtains the type of the system gesture to trigger. +* +* @param event Indicates the pointer to the gesture interruption information. +* @return Returns the type of the system gesture to trigger. If the gesture to trigger is not a system gesture, +* -1 is returned. +* @since 12 +*/ +int32_t OH_ArkUI_GestureInterruptInfo_GetSystemRecognizerType(const ArkUI_GestureInterruptInfo* event); + +/** +* @brief Obtains touch recognizers from gesture interruption information. +* +* @param info Pointer to the gesture interruption information. +* @param recognizers Pointer to the array of touch recognizers. +* @param size Pointer to the size of the touch recognizer array. +* @return Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. +* Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. +* @since 15 +*/ +int32_t OH_ArkUI_GestureInterruptInfo_GetTouchRecognizers(const ArkUI_GestureInterruptInfo* info, + ArkUI_TouchRecognizerHandleArray* recognizers, int32_t* size); + +/** +* @brief Obtains the component handle corresponding to a touch recognizer. +* +* @param recognizer Handle to the touch recognizer. +* @return Returns the component handle corresponding to the touch recognizer. +* @since 15 +*/ +ArkUI_NodeHandle OH_ArkUI_TouchRecognizer_GetNodeHandle(const ArkUI_TouchRecognizerHandle recognizer); + +/** +* @brief Sends a cancel touch event to a touch recognizer in a gesture interruption callback. +* +* @param recognizer Handle to the touch recognizer. +* @param info Pointer to the gesture interruption information. +* @return Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. +* Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. +* @since 15 +*/ +int32_t OH_ArkUI_TouchRecognizer_CancelTouch(ArkUI_TouchRecognizerHandle recognizer, ArkUI_GestureInterruptInfo* info); + +/** +* @brief Obtains the gesture event type. +* +* @param event Indicates the pointer to the gesture event. +* @return Returns the gesture event type. +* @since 12 +*/ +ArkUI_GestureEventActionType OH_ArkUI_GestureEvent_GetActionType(const ArkUI_GestureEvent* event); + +/** +* @brief Obtains gesture input. +* +* @param event Indicates the pointer to the gesture event. +* @return Returns the pointer to the input event of the gesture event. +* @since 12 +*/ +const ArkUI_UIInputEvent* OH_ArkUI_GestureEvent_GetRawInputEvent(const ArkUI_GestureEvent* event); + +/** +* @brief Obtains the number of times that a long press gesture is triggered periodically. +* +* @param event Indicates the pointer to the gesture event. +* @return Returns the number of times that the long press gesture is triggered periodically. +* @since 12 +*/ +int32_t OH_ArkUI_LongPress_GetRepeatCount(const ArkUI_GestureEvent* event); + +/** +* @brief Obtains the velocity of a pan gesture along the main axis. +* +* @param event Indicates the pointer to the gesture event. +* @return Returns the velocity of the pan gesture along the main axis, in px/s. +* The value is the square root of the sum of the squares of the velocity on the x-axis and y-axis. +* @since 12 +*/ +float OH_ArkUI_PanGesture_GetVelocity(const ArkUI_GestureEvent* event); + +/** +* @brief Obtains the velocity of a pan gesture along the x-axis. +* +* @param event Indicates the pointer to the gesture event. +* @return Returns the velocity of the pan gesture along the x-axis, in px/s. +* @since 12 +*/ +float OH_ArkUI_PanGesture_GetVelocityX(const ArkUI_GestureEvent* event); + +/** +* @brief Obtains the velocity of a pan gesture along the y-axis. +* +* @param event Indicates the pointer to the gesture event. +* @return Returns the velocity of the pan gesture along the y-axis, in px/s. +* @since 12 +*/ +float OH_ArkUI_PanGesture_GetVelocityY(const ArkUI_GestureEvent* event); + +/** +* @brief Obtains the relative offset of a pan gesture along the x-axis. +* +* @param event Indicates the pointer to the gesture event. +* @return Returns the relative offset of the gesture along the x-axis, in px. +* @since 12 +*/ +float OH_ArkUI_PanGesture_GetOffsetX(const ArkUI_GestureEvent* event); + +/** +* @brief Obtains the relative offset of a pan gesture along the y-axis. +* +* @param event Indicates the pointer to the gesture event. +* @return Returns the relative offset of the gesture along the y-axis, in px. +* @since 12 +*/ +float OH_ArkUI_PanGesture_GetOffsetY(const ArkUI_GestureEvent* event); + +/** +* @brief Obtains the angle information of the swipe gesture. +* +* After a swipe gesture is recognized, a line connecting the two fingers is identified as the initial line. +* As the fingers swipe, the line between the fingers rotates. \n +* Based on the coordinates of the initial line's and current line's end points, the arc tangent function is used to +* calculate the respective included angle of the points relative to the horizontal direction \n +* by using the following formula: Rotation angle = arctan2(cy2-cy1,cx2-cx1) - arctan2(y2-y1,x2-x1). \n +* The initial line is used as the coordinate system. Values from 0 to 180 degrees represent clockwise rotation, +* while values from –180 to 0 degrees represent counterclockwise rotation. \n +* +* @param event Indicates the pointer to the gesture event. +* @return Returns the angle of the swipe gesture, which is the result obtained based on the aforementioned formula. +* @since 12 +*/ +float OH_ArkUI_SwipeGesture_GetAngle(const ArkUI_GestureEvent* event); + +/** +* @brief Obtains the average velocity of all fingers used in the swipe gesture. +* +* @param event Indicates the pointer to the gesture event. +* @return Returns the average velocity of all fingers used in the swipe gesture, in px/s. +* @since 12 +*/ +float OH_ArkUI_SwipeGesture_GetVelocity(const ArkUI_GestureEvent* event); + +/** +* @brief Obtains the angle information of a rotation gesture. +* +* @param event Indicates the pointer to the gesture event. +* @return Returns the rotation angle. +* @since 12 +*/ +float OH_ArkUI_RotationGesture_GetAngle(const ArkUI_GestureEvent* event); + +/** +* @brief Obtains the scale ratio of a pinch gesture. +* +* @param event Indicates the pointer to the gesture event. +* @return Returns the scale ratio. +* @since 12 +*/ +float OH_ArkUI_PinchGesture_GetScale(const ArkUI_GestureEvent* event); + +/** +* @brief Obtains the X coordinate of the center of the pinch gesture, in vp, +* relative to the upper left corner of the current component. +* +* @param event Indicates the pointer to the gesture event. +* @return Returns the X coordinate of the center of the pinch gesture, in vp, +* relative to the upper left corner of the current component. +* @since 12 +*/ +float OH_ArkUI_PinchGesture_GetCenterX(const ArkUI_GestureEvent* event); + +/** +* @brief Obtains the Y coordinate of the center of the pinch gesture, in vp, +* relative to the upper left corner of the current component. +* +* @param event Indicates the pointer to the gesture event. +* @return Returns the Y coordinate of the center of the pinch gesture, in vp, +* relative to the upper left corner of the current component. +* @since 12 +*/ +float OH_ArkUI_PinchGesture_GetCenterY(const ArkUI_GestureEvent* event); + +/** +* @brief Obtains the component to which the specified gesture is bound. +* +* @param event Indicates the pointer to the gesture event. +* @return Returns the component to which the specified gesture is bound. +* @since 12 +*/ +ArkUI_NodeHandle OH_ArkUI_GestureEvent_GetNode(const ArkUI_GestureEvent* event); + +/** +* @brief Obtains information about a gesture response chain. +* +* @param event Indicates the pointer to the gesture interruption information. +* @param responseChain Indicates the pointer to an array of gesture recognizers on the response chain. +* @param count Indicates the pointer to the number of gesture recognizers on the response chain. +* @return Returns 0 if success. +* Returns 401 if a parameter error occurs. +* @since 12 +*/ +int32_t OH_ArkUI_GetResponseRecognizersFromInterruptInfo(const ArkUI_GestureInterruptInfo* event, + ArkUI_GestureRecognizerHandleArray* responseChain, int32_t* count); + +/** +* @brief Sets the enabled state of a gesture recognizer. +* +* @param recognizer Indicates the pointer to a gesture recognizer. + * @param enable Indicates the enabled state. +* @return Returns 0 if success. +* Returns 401 if a parameter error occurs. +* @since 12 +*/ +int32_t OH_ArkUI_SetGestureRecognizerEnabled(ArkUI_GestureRecognizer* recognizer, bool enabled); + +/** +* @brief Sets whether to enable strict finger count checking. If this feature is enabled and the actual number of touch +* fingers does not match the set number, the gesture recognition fails. +* +* @param recognizer Indicates the pointer to a gesture recognizer. +* @param limitFingerCount Indicates whether to enable strict finger count checking. +* @return Returns 0 if the operation is successful. +* Returns 401 if a parameter error occurs. +* @since 15 +*/ +int32_t OH_ArkUI_SetGestureRecognizerLimitFingerCount(ArkUI_GestureRecognizer* recognizer, bool limitFingerCount); + +/** +* @brief Obtains the enabled state of a gesture recognizer. +* +* @param recognizer Indicates the pointer to a gesture recognizer. +* @return Returns true if the gesture recognizer is enabled. +* Returns false if the gesture recognizer is disabled. +* @since 12 +*/ +bool OH_ArkUI_GetGestureRecognizerEnabled(ArkUI_GestureRecognizer* recognizer); + +/** +* @brief Obtains the state of a gesture recognizer. +* +* @param recognizer Indicates the pointer to a gesture recognizer. +* @param state Indicates the pointer to the state of the gesture recognizer. +* @return Returns 0 if success. +* Returns 401 if a parameter error occurs. +* @since 12 +*/ +int32_t OH_ArkUI_GetGestureRecognizerState(ArkUI_GestureRecognizer* recognizer, ArkUI_GestureRecognizerState* state); + +/** +* @brief Obtains the information about a gesture event target. +* +* @param recognizer Indicates the pointer to a gesture recognizer. +* @param info Indicates the information about a gesture event target. +* @return Returns 0 if success. +* Returns 401 if a parameter error occurs. +* @since 12 +*/ +int32_t OH_ArkUI_GetGestureEventTargetInfo(ArkUI_GestureRecognizer* recognizer, ArkUI_GestureEventTargetInfo** info); + +/** +* @brief Obtains whether this scroll container is scrolled to the top. +* +* @param info Indicates the information about a gesture event target. +* @param ret Indicates whether the scroll container is scrolled to the top. +* @return Returns 0 if success. +* Returns 401 if a parameter error occurs. +* Returns 180001 if the component is not a scroll container. +* @since 12 +*/ +int32_t OH_ArkUI_GestureEventTargetInfo_IsScrollBegin(ArkUI_GestureEventTargetInfo* info, bool* ret); + +/** +* @brief Obtains whether this scroll container is scrolled to the bottom. +* +* @param info Indicates the information about a gesture event target. +* @param ret Indicates whether the scroll container is scrolled to the bottom. +* @return Returns 0 if success. +* Returns 401 if a parameter error occurs. +* Returns 180001 if the component is not a scroll container. +* @since 12 +*/ +int32_t OH_ArkUI_GestureEventTargetInfo_IsScrollEnd(ArkUI_GestureEventTargetInfo* info, bool* ret); + +/** +* @brief Obtains the direction of a pan gesture. +* +* @param recognizer Indicates the pointer to a gesture recognizer. +* @param directionMask Indicates the pan direction. +* @return Returns 0 if success. +* Returns 401 if a parameter error occurs. +* @since 12 +*/ +int32_t OH_ArkUI_GetPanGestureDirectionMask(ArkUI_GestureRecognizer* recognizer, + ArkUI_GestureDirectionMask* directionMask); + +/** +* @brief Obtains whether a gesture is a built-in gesture. +* +* @param recognizer Indicates the pointer to a gesture recognizer. +* @return Returns true if the gesture is a built-in gesture; returns false otherwise. + +* @since 12 +*/ +bool OH_ArkUI_IsBuiltInGesture(ArkUI_GestureRecognizer* recognizer); + +/** +* @brief Obtains the tag of a gesture recognizer. +* +* @param recognizer Indicates the pointer to a gesture recognizer. +* @param buffer Indicates the buffer. +* @param bufferSize Indicates the buffer size. +* @param result Indicates the length of the string to be written to the buffer. +* @return Returns 0 if success. +* Returns 401 if a parameter error occurs. +* Returns 180002 if the buffer is not large enough. +* @since 12 +*/ +int32_t OH_ArkUI_GetGestureTag(ArkUI_GestureRecognizer* recognizer, char* buffer, int32_t bufferSize, int32_t* result); + +/** +* @brief Obtains the ID of the component linked to a gesture recognizer. +* +* @param recognizer Indicates the pointer to a gesture recognizer. +* @param nodeId Indicates the component ID. +* @param size Indicates the buffer size. +* @param result Indicates the length of the string to be written to the buffer. +* @return Returns 0 if success. +* Returns 401 if a parameter error occurs. +* Returns 180002 if the buffer is not large enough. +* @since 12 +*/ +int32_t OH_ArkUI_GetGestureBindNodeId(ArkUI_GestureRecognizer* recognizer, char* nodeId, int32_t size, + int32_t* result); + +/** +* @brief Obtains whether a gesture recognizer is valid. +* +* @param recognizer Indicates the pointer to a gesture recognizer. +* @return Returns true if the gesture recognizer is valid. +* Returns false if the gesture recognizer is invalid. +* @since 12 +*/ +bool OH_ArkUI_IsGestureRecognizerValid(ArkUI_GestureRecognizer* recognizer); + +/** +* @brief Obtains custom data in the parallel internal gesture event. +* +* @param event Indicates the pointer to a parallel internal gesture event. +* @return Returns the pointer to custom data. +* @since 12 +*/ +void* OH_ArkUI_ParallelInnerGestureEvent_GetUserData(ArkUI_ParallelInnerGestureEvent* event); + +/** +* @brief Obtains the current gesture recognizer in a parallel internal gesture event. +* +* @param event Indicates the pointer to a parallel internal gesture event. +* @return Returns the pointer to the current gesture recognizer. +* @since 12 +*/ +ArkUI_GestureRecognizer* OH_ArkUI_ParallelInnerGestureEvent_GetCurrentRecognizer( + ArkUI_ParallelInnerGestureEvent* event); + +/** +* @brief Obtains the conflicting gesture recognizers in a parallel internal gesture event. +* +* @param event Indicates the pointer to a parallel internal gesture event. +* @param array Indicates the pointer to the array of conflicting gesture recognizers. +* @param size Indicates the size of the array of conflicting gesture recognizers. +* @return Returns 0 if success. +* Returns 401 if a parameter error occurs. +* @since 12 +*/ +int32_t OH_ArkUI_ParallelInnerGestureEvent_GetConflictRecognizers(ArkUI_ParallelInnerGestureEvent* event, + ArkUI_GestureRecognizerHandleArray* array, int32_t* size); + +/** +* @brief Sets a callback function for notifying gesture recognizer destruction. +* +* @param recognizer Indicates the pointer to a gesture recognizer. +* @param callback Indicates the callback function for notifying gesture recognizer destruction. +* @param userData Indicates the custom data. +* @return Returns 0 if success. +* Returns 401 if a parameter error occurs. +*/ +int32_t OH_ArkUI_SetArkUIGestureRecognizerDisposeNotify(ArkUI_GestureRecognizer* recognizer, + ArkUI_GestureRecognizerDisposeNotifyCallback callback, void* userData); + +/** +* @brief Obtains the swipe direction of a gesture recognizer. +* +* @param recognizer Pointer to a gesture recognizer. +* @param dictMask Swipe direction of the gesture recognizer. +* @return Returns the result code. +* Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. +* Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. +* @since 18 +*/ +int32_t OH_ArkUI_GetGestureParam_DirectMask( + ArkUI_GestureRecognizer* recognizer, ArkUI_GestureDirectionMask* directMask); + +/** +* @brief Obtains the number of fingers used by a gesture recognizer. +* +* @param recognizer Pointer to a gesture recognizer. +* @param finger Number of fingers used by the gesture recognizer. +* @return Returns the result code. +* Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. +* Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. +* @since 18 +*/ +int32_t OH_ArkUI_GetGestureParam_FingerCount(ArkUI_GestureRecognizer* recognizer, int* finger); + +/** +* @brief Checks whether a gesture recognizer has a finger count limit. +* +* @param recognizer Pointer to a gesture recognizer. +* @param isLimited Whether the gesture recognizer has a finger count limit. +* @return Returns the result code. +* Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. +* Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. +* @since 18 +*/ +int32_t OH_ArkUI_GetGestureParam_limitFingerCount(ArkUI_GestureRecognizer* recognizer, bool* isLimited); + +/** +* @brief Checks whether a gesture recognizer supports repeated event callbacks. +* +* @param recognizer Pointer to a gesture recognizer. +* @param isRepeat Whether the gesture recognizer supports repeated event callbacks. +* @return Returns the result code. +* Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. +* Returns {@link ARKUI_ERROR_CODE_RECOGNIZER_TYPE_NOT_SUPPORTED} if the gesture recognizer type +* is not supported. +* @since 18 +*/ +int32_t OH_ArkUI_GetGestureParam_repeat(ArkUI_GestureRecognizer* recognizer, bool* isRepeat); + +/** +* @brief Obtains the allowed movement distance range for a gesture recognizer. +* +* @param recognizer Pointer to a gesture recognizer. +* @param distance Allowed movement distance range of the gesture recognizer. +* @return Returns the result code. +* Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. +* Returns {@link ARKUI_ERROR_CODE_RECOGNIZER_TYPE_NOT_SUPPORTED} if the gesture recognizer type +* is not supported. +* @since 18 +*/ +int32_t OH_ArkUI_GetGestureParam_distance(ArkUI_GestureRecognizer* recognizer, double* distance); + +/** +* @brief Obtains the minimum swipe speed recognized by a gesture recognizer. +* +* @param recognizer Pointer to a gesture recognizer. +* @param speed Minimum swipe speed recognized by a gesture recognizer. +* @return Returns the result code. +* Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. +* Returns {@link ARKUI_ERROR_CODE_RECOGNIZER_TYPE_NOT_SUPPORTED} if the gesture recognizer type +* is not supported. +* @since 18 +*/ +int32_t OH_ArkUI_GetGestureParam_speed(ArkUI_GestureRecognizer* recognizer, double* speed); + +/** +* @brief Obtains the minimum duration required to trigger a long press by a gesture recognizer. +* +* @param recognizer Pointer to a gesture recognizer. +* @param duration Minimum duration for a long press. +* @return Returns the result code. +* Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. +* Returns {@link ARKUI_ERROR_CODE_RECOGNIZER_TYPE_NOT_SUPPORTED} if the gesture recognizer type +* is not supported. +* @since 18 +*/ +int32_t OH_ArkUI_GetGestureParam_duration(ArkUI_GestureRecognizer* recognizer, int* duration); + +/** +* @brief Obtains the minimum angle change required for a rotation gesture to be recognized by a gesture recognizer. +* +* @param recognizer Pointer to a gesture recognizer. +* @param angle Minimum angle change. +* @return Returns the result code. +* Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. +* Returns {@link ARKUI_ERROR_CODE_RECOGNIZER_TYPE_NOT_SUPPORTED} if the gesture recognizer type +* is not supported. +* @since 18 +*/ +int32_t OH_ArkUI_GetGestureParam_angle(ArkUI_GestureRecognizer* recognizer, double* angle); + +/** +* @brief Obtains the movement threshold for gestures to be recognized by a gesture recognizer. +* +* @param recognizer Pointer to a gesture recognizer. +* @param distanceThreshold Gesture movement threshold of the gesture recognizer. +* @return Returns the result code. +* Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. +* Returns {@link ARKUI_ERROR_CODE_RECOGNIZER_TYPE_NOT_SUPPORTED} if the gesture recognizer type +* is not supported. +* @since 18 +*/ +int32_t OH_ArkUI_GetGestureParam_distanceThreshold(ArkUI_GestureRecognizer* recognizer, double* distanceThreshold); + +/** +* @brief Sets the minimum movement distance thresholds for gestures to be recognized by a gesture recognizer. +* +* @param recognizer Indicates the pointer to a gesture recognizer. +* @param size Size of the array of minimum movement distance thresholds. +* @param toolTypeArray Pointer to the array of tool types for which thresholds are set. +* @param distanceArray Pointer to the array of minimum movement distances. +* @return Returns the result code. +* Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. +* Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. +* Returns {@link ARKUI_ERROR_CODE_RECOGNIZER_TYPE_NOT_SUPPORTED} if the gesture recognizer type is +* not supported. +* @since 18 +*/ +int32_t OH_ArkUI_SetGestureParamDistanceMap(ArkUI_GestureRecognizer* recognizer, int size, int* toolTypeArray, double* distanceArray); + +/** +* @brief Obtains the movement threshold for gestures to be recognized by a gesture recognizer for a specific tool type. +* +* @param recognizer Indicates the pointer to a gesture recognizer. +* @param tooltype Tool type for which you want to obtain the threshold. +* @param distance Gesture movement threshold of the gesture recognizer. +* @return Returns the result code. +* Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. +* Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. +* Returns {@link ARKUI_ERROR_CODE_RECOGNIZER_TYPE_NOT_SUPPORTED} if the gesture recognizer type is +* not supported. +* @since 18 +*/ +int32_t OH_ArkUI_GetGestureParam_DistanceByKey(ArkUI_GestureRecognizer* recognizer, int toolType, double* distance); + +/** + * @brief Defines the gesture APIs. + * + * @since 12 + */ +typedef struct { + /** The struct version is 1. */ + int32_t version; + + /** + * @brief Creates a tap gesture. + * + * 1. This API is used to trigger a tap gesture with one, two, or more taps. \n + * 2. If multi-tap is configured, the timeout interval between a lift and the next tap is 300 ms. \n + * 3. If the distance between the last tapped position and the current tapped position exceeds 60 vp, + * gesture recognition fails. \n + * 4. If the value is greater than 1, the tap gesture will fail to be recognized when the number of fingers + * touching the screen within 300 ms of the first finger touch is less than the required number, \n + * or when the number of fingers lifted from the screen within 300 ms of the first finger's being lifted + * is less than the required number. \n + * 5. When the number of fingers touching the screen exceeds the set value, the gesture can be recognized. \n + * + * @param countNum Number of consecutive taps. If the value is less than 1 or is not set, + * the default value 1 is used. + * @param fingersNum Number of fingers required to trigger a tap. The value ranges from 1 to 10. + * If the value is less than 1 or is not set, the default value 1 is used. + * @return Returns the pointer to the created gesture. + */ + ArkUI_GestureRecognizer* (*createTapGesture)(int32_t countNum, int32_t fingersNum); + + /** + * @brief Creates a long press gesture. + * + * 1. This API is used to trigger a long press gesture, which requires one or more fingers with a minimum + * The value ranges 500 ms hold-down time. \n + * 2. In components that support drag actions by default, such as , , + *