The **WindowAnimationManager** module provides APIs to listen for application start/exit events and window minimization/maximization events and associate animations with these events.
> **NOTE**
>
> The APIs of this module are supported since API version 9. Updates will be marked with a superscript to indicate their earliest API version.
>
> The APIs provided by this module are system APIs.
Hardware device interface (HDI) provides a set of interfaces that function as a bridge between drivers and system services for data transmission. They have a direct impact on system efficiency, stability, compatibility, and reliability, as well as data accuracy and integrity. This document aims to standardize the design and development of OpenHarmony HDI interfaces, thereby ensuring consistent styles and complete functionalities for the interfaces.
This document is developed by the [driver SIG](https://gitee.com/openharmony/community/blob/master/sig/sig-driver/sig_driver.md) and approved by the [PMC](https://gitee.com/link?target=https%3A%2F%2Fwww.openharmony.cn%2Fcommunity%2Fpmc%2F). Any revision to this document must be reviewed by the driver SIG and approved by the PMC.
**Acronyms**
| Acronym | Full Spelling |
| --- | ------------------------------ |
| HDI | Hardware Device Interface |
| IDL | Interface Description Language |
**Conventions**
**Rule**: a convention that must be complied with
**Rec**: a convention that should be considered
**Note**: an explanation to a rule or rec
**Change History**
| Version | Change Description |
| --- | --------------------- |
| v1.0 Beta | This issue is the initial version. |
Located between the system service layer and the device driver layer, HDI provides unified device function abstract interfaces for device developers. It shields the differences of devices from system services.
## General Rules
### Version Control
The HDI version number must be in the format of `major.minor`, where `major` must be an integer increased in ascending order and `minor` is a one-digit integer.
- A change in `major` indicates architecture adjustment or interface definition that is not backward compatible.
- A change in `minor` indicates enhanced or extended interface definitions that are backward compatible.
If the update to the existing interfaces does not affect version compatibility, for example, adding a function, adding an enum definition, or changing a variable name, change only `minor`, for example, to `ohos.hdi.vibrator.v1_1`, as follows:
HDI interfaces are provided to implement upper-layer system service requirements and perform hardware operations (such as initialization). New and updated interfaces must be fully reviewed and strictly controlled. Only interfaces that meet universal requirements can be added.
| Contributor | Write HDI code and submit the code and design documents for review. |
| Committer | Review the HDI code, and submit the code to the domain SIG for further review. |
| Domain SIG | Review the new or updated HDI code.|
| Driver SIG | Review the new or updated HDI code. |
| PMC | Revise and publish this design specifications. |
### Release
- HDI review process
The main process is as follows:
1. The contributor commits code and initiates a review. In addition to the code of new or updated HDI interfaces, the contributor must provide information about the HDI requirement source, usage scenario, permission design, and privacy protection design. For details, see "Review application composites" below. To increase the review efficiency, the contributor can email the design documents to the committer, domain SIG, and driver SIG before submitting the review application.
2. The committer reviews the code and HDI interfaces.
3. The domain SIG reviews the new or updated HDI interfaces.
4. The driver SIG reviews and approves the new or updated HDI interfaces.
5. The review is complete, and the code is merged.
- Review application composites
After the HDI design is complete, the domain SIG must organize an effective review and provide the following documents before HDI release:
- Complete and reasonable test cases
- **HDI version differences, with a clear addition or change scope**
- Complete interface context, which must be provided in the design document to specify when and how to use each interface
- Resource status transition diagram in the design document for resource-oriented interfaces
- Compliance with the HDI design constraints proposed in this document
- Requirements
1. Change `major` for any release that is incompatible with earlier versions.
2. Change `minor` for any interface released for function extension.
3. To deprecate any released interface:
- The `deprecated` flag must be provided.
- The deprecated interfaces must be retained in at least four OpenHarmony HDI versions.
## HDI Design Constraints
### Consistency
#### [Rule] Use consistent nouns for terms.
Multiple nouns with similar semantic meanings are not allowed to represent the same service object. Similarly, to avoid confusion, it is not allowed to use the same noun or linguistically close nouns for different service objects.
#### [Rule] Keep the parameter sequence consistent.
The sequence of a parameter or parameter group in multiple interfaces must be the same.
For object-oriented C programming, place the interface object as the first parameter by convention.
#### [Rule] Keep the memory ownership consistent.
If the memory (storage data) passed through the input parameter (in) or output parameter (out) is allocated by the caller, the memory must be released by the caller. If the memory is allocated by the callee, it must be released by the callee. Regardless of whether data is passed from a service to a driver or received from a driver, the ownership of the data should not be changed, which must always be the memory allocator.
When **OpenLayer** is called, the graphics layer data memory is allocated based on the input parameter **layerInfo**, and a layer ID is returned.
```cpp
int(*CloseLayer)(uint32_tdevId,uint32_tlayerId);
```
A **CloseLayer** interface must be provided to release the graphics layer data memory when the caller finishes the operation.
#### [Rule] Provide a specific return value for every synchronous interface.
When defining a synchronous interface, you must define the return value and provide necessary invocation status information to specify whether the invocation is successful. If the invocation fails, specify the cause of the failure. You can define a return value based on the actual error cause.
[Exceptions]
If an interface is unidirectional, which means that a value can be returned without waiting for the interface to be executed, use the keyword `one way` in the comment. Example:
```cpp
/* one way */
voidWriteReady();
```
### Naming
#### [Rule] Name an interface in the format of "I" + "*interface name*".
Interface names must be concise, easy to understand, and accurate. Avoid redundant and misleading words, or rare abbreviations.
[Example]
```
/* Good */
interface IBattery {
...
}
/* Bad: The Interface suffix is redundant. */
interface IBatteryInterface {
...
}
```
#### [Rule] Name the HDI package in the format of "package ohos.hdi.[interface_name].v[major_version]_[minor_version]".
#### [Rule] Name classes, structs, functions, and parameters in camel case.
**Camel case style**
Camel case is the practice of writing words without spaces. It indicates the separation of words with a single capitalized letter, and the first word starts with either case, bringing about **UpperCamelCase** and **lowerCamelCase**.
| Interface types, functions, struct types, enum types, and union types | UpperCamelCase |
| Parameters, and member variables in a struct or union| lowerCamelCase |
| Constants and enums | All uppercase letters, separated by underscores (_)|
#### [Rule] Use the interface class name as the interface file name and `.idl` as the file name extension.
- An independent interface file must be provided for every interface class, and the file name must be the same as that of the interface class (UpperCamelCase) and end with `.idl`.
- The description file of the type definition must be named `Types.idl` or `ExampleTypes.idl`.
[Example]
```
packageohos.hdi.battery.v1_0;
interfaceIBattery{
...
}
```
The interface description file must be named `IBattery.idl`.
### Ease to Use
#### [Rule] Follow the single responsibility principle.
The functionalities of each interface must be stable and clear, and the trigger source of interface changes must be unique.
[Example]
When the device status consists of the power status and port status, use two interfaces rather than one.
**Correct Example**
```cpp
intUpdatePowerState(int_tdeviceId,intstatus);// This interface is used to update the power status of the device.
intUpdatePortStatus(intdeviceId,intstatus);// This interface is used to update the port status of the device.
#### [Rule] Consider cohesion during interface parameter design.
When defining an interface parameter, consider whether to pass the parameter separately or encapsulate the parameter in a struct based on the following factors:
1. Is there a meaningful encapsulation boundary?
If there is obvious cohesion or association between parameters, you can encapsulate these parameters in a struct.
2. Is there any other use of this struct if structured parameters are used?
If no, pass the parameter separately.
3. Does a parameter group occur in multiple interfaces?
If yes, you can pass these parameters as a struct. In this case, you also need to consider whether these parameter groups are cohesive.
4. Is there a large number of optional parameters, or do they usually be assigned a default value?
If yes, you can use a struct to simplify the invocation.
[Example]
Audio sampling attributes include the sampling format, sampling frequency, and number of channels. These attributes are also sampling related and can be passed as a struct.
```cpp
structAudioSampleAttributes
{
enumAudioFormatformat;
uint32_tsampleRate;
uint32_tchannelCount;
};
```
#### [Rule] Make interfaces of different device types independent from each other.
Interfaces are managed by driver type, such as `Camera`, `Input`, `Display`, `Audio`, `Sensor`, and `Storage`. Interfaces of different device types should not depend on each other. It is recommended that common capabilities that may be used by more than two types of driver modules be abstracted as common interfaces and archived to the common interface capability library for management.
[Exceptions]
There is no restriction on the interfaces that provide common capabilities. For example, the definition of primitive types and the declaration of interfaces can be referenced by all interfaces.
### Privacy Protection
### [Rule] Consider privacy security.
System services can access data such as device information and identifiers through drivers. Certain information, such as device names, serial numbers, and device addresses, is sensitive data defined in privacy protection specifications. During HDI design, pay attention to the use of these fields and review them carefully and thoroughly to ensure that the interfaces will never expose sensitive information.
[Example]
`Bluetooth` addresses are mainly used in device discovery and connection scenarios. When a device is discoverable, the `Bluetooth` address could be used for personal tracking.
The major purpose of obtaining a `Bluetooth` address is to uniquely identify a device. Therefore, you can convert the `Bluetooth` address into a unique identifier for invocation or restrict the application scope of this interface.
### Permission Control
#### [Rule] Minimize the interface permissions.
All behaviors across application sandboxes must be controlled by permissions. A specific permission can be granted only to applications that have legitimate service requirements.
### Performance
#### [Rule] Consider data transmission efficiency.
Drivers have a large number of data transmission interfaces. Data transmission may involve inter-process communication (IPC), which increases system overheads or even trigger system scheduling. Therefore, you need to consider all situations when defining interfaces. For the data that must be transmitted between processes with low overhead and low latency, you can use the shared memory or message queue.
[Example]
Define a data transmission interface for a driver module as follows:
```cpp
// IPC is not involved (direct interface calling).
intWriteData(...);// Define the data address pointer and data length as input parameters.
/*
* IPC is involved.
*
* Define a shared memory or message queue object as the input parameter.
* In this way, data can be efficiently transmitted (since repetitive operations can be minimized).
*/
intPrepareWriteData(…);
```
#### [Rec] Consider the interface execution time.
To improve IPC performance, you are advised to use asynchronous processing for time-consuming services on the server. If the client needs to wait for the result synchronously, you are advised to add a block on the client and use the asynchronous callback mode so that the IPC channel can be released in time.
[Example]
The `Camera` driver provides a device initialization interface, the execution of which takes more than 150 ms due to software and hardware reasons. If this interface uses synchronous mode, the camera HDI service IPC thread may be occupied for a long time, and other requests fail to be responded in time. It is more reasonable to design this interface as an asynchronous one. A callback can be used to return the initialization result to the client. If the client needs to wait for the return value before continuing other operations, it can block the process and wait for the callback result.
#### [Rec] Minimize the number of new process entities.
To reduce the system overhead, interfaces of the same type in the same subsystem must be deployed in the same process. Add processes only when they are necessary.
### Power Consumption
#### [Rule] Consider system power consumption.
When the caller releases hardware resources, the corresponding driver module should release the wake lock so the system will not be prevented from sleeping.
### Reliability
#### [Rule] Mutual dependency is forbidden for the lifecycle of interface parameters.
The lifecycle of interface parameters must be independent. Mutual dependency is prohibited. Pointer parameters should not point to the memory of other objects, for example, the serialized memory. This is because when the serialized memory is passed to the peer function, the memory block lifecycle disappears after the parameter is parsed, but the pointer may be passed between different functions, resulting in vulnerabilities such as Used After Free (UAF).
[Example]
Both `ReadUnpadBuffer` and `ReadCString` return a pointer variable that points to the internal memory of the serialized object. When the server callback is triggered, the serialized object used to pass the parameters is destroyed and the memory is free. If other processes on the server still use the pointers returned by the two interfaces, crash may occur due to the UAF.
The correct practice is to copy the data to the memory managed by the service before using the data after the service response interface returns the data.
#### [Rule] Consider reentrancy.
Interfaces often need to support multiple clients, and a single client may have concurrent requests. Therefore, you must consider reentrancy during HDI design. To ensure correct processing of reentrant interfaces, use locks or semaphores to protect critical resources.
[Example]
A driver service provides resource request and release interfaces. When two clients request resources at the same time, if reentrancy is not considered for critical resources on the server, resources may be released in advance or cannot be released due to management data read/write competition. The correct practice is to lock critical resources.
#### [Rec] Consider the transmission buffer capability.
No flow control is posed on the amount of data sent in an interface or callback. However, if the data volume of an interface exceeds the maximum transmission buffer size, consider using a block until the resource is available.
[Example]
When memory application fails, you can use a semaphore to block the current thread until the memory is available.
#### [Rule] Do not pass function pointers across address spaces.
Virtual address space isolation is used between processes. Passing function pointers through IPC will cause access exceptions. Therefore, do not pass function pointers. To implement a callback function, use a callback object instead.
[Example]
The Wi-Fi module provides an interface to receive a callback triggered when the client accepts the server request. An incorrect practice is to write the function pointer implemented by the client to the serialized object, which causes a crash when the function pointer is called on the server.
The correct practice is to design and implement the callback interface using a callback object, and pass the callback object to the server through the serialization interface, so the server can trigger the callback when needed.
### Compatibility
#### [Rule] Verify the version number before the client calls an interface.
Due to the independent component update policy, the version number of an interface on the client may be different from that on the server. This requires the client to verify the version number on the server and use the matching version to call the interface on the server.
[Example]
Assume that the TP module provides interfaces of versions 1.0 and 1.1. The later version has new interfaces. The components on the client have updated to 1.1, and the server still uses 1.0. If the client directly calls an interface of 1.1 on the server, an error may occur. Instead, the client must use the service version query interface to check the server version. If the server version is 1.0, the client must use the interface of 1.0 to call the server.
#### [Rule] Release HDI interfaces in .idl format.
Currently, Unix-like drivers use virtual file system (VFS) interfaces to expose internal interfaces. The user mode and kernel mode communicate with each other using system calls. They are packed in different images, and two sets of interfaces are maintained separately. To ensure the consistency of the interface definition and parameter format between the two and consider the design objective of cross-kernel hardware driver foundation (HDF) deployment, release interfaces in .idl format and use a tool to generate interfaces of the target form. In addition, the user-mode caller is not allowed to operate the driver VFS interfaces through the file interface. This causes the framework to strongly depend on the kernel and violates the principle of depending on the interface instead of the implementation.
Recommended practice: The driver provides interfaces in .idl format and encapsulates the access to the kernel device in the interface implementation.
[Example]
An input device provides query interfaces for attributes such as the device type and data precision. The input service should not directly access the VFS interface created by the kernel in open-ioctl mode. Instead, the input driver should provide an interface to abstract the input device as an object. Then the input service calls this interface to implement the required functionalities.
### Documentation
#### [Rule] Release HDI interfaces in .idl format.
To ensure interface compatibility and consistency, release interfaces in .idl format. It is prohibited to directly release interfaces in C/C++ header files.
#### [Rule] Provide an interface description during interface release.
The interface description must contain the interface functionality, parameter value range, return values, and precautions. The description text must be placed above the interface description in the .idl file and released with the interface.
[Example]
```
/**
* @brief Obtains the executor information.
*
* @param executorInfo Indicates the executor information. For details, see {@link ExecutorInfo}.
*
* @return Returns <b>0</b> if the operation is successful.
* @return Returns a non-zero value if the operation fails.
To ensure data interworking between interfaces implemented in different programming languages, follow the restrictions below when using data types in the interface description.
#### Constraints on using basic data types
| IDL Data Type | C++ Data Type | C Data Type | Data Length (Bytes)|
OpenHarmony 3.0.5 LTS is a maintenance version of OpenHarmony 3.0 LTS. This version has rectified certain issues detected in OpenHarmony 3.0.3 LTS and provides the following capability updates.
**Enhanced capabilities for the small system**
The DFX subsystem supports native crash information collection and device restart fault locating. The communication subsystem supports basic STA capabilities.
2. Register an SSH public key for access to Gitee.
3. Install the [git client](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) and [git-lfs](https://gitee.com/vcs-all-in-one/git-lfs?_from=gitee_search#downloading), and configure user information.
4. Run the following commands to install the **repo** tool:
```
curl -s https://gitee.com/oschina/repo/raw/fork_flow/repo-py3 > /usr/local/bin/repo # If you do not have the permission, download the tool to another directory and configure it as an environment variable by running the chmod a+x /usr/local/bin/repo command.
| Full code base (for mini, small, and standard systems)| 3.0.5 | [Download](https://repo.huaweicloud.com/openharmony/os/3.0.5/code-v3.0.5-LTS.tar.gz) | [Download](https://repo.huaweicloud.com/openharmony/os/3.0.5/code-v3.0.5-LTS.tar.gz.sha256)|
| Standard system Hi3516 solution (binary)| 3.0.5 | [Download](https://repo.huaweicloud.com/openharmony/os/3.0.5/standard.tar.gz)| [Download](https://repo.huaweicloud.com/openharmony/os/3.0.5/standard.tar.gz.sha256)|
| Mini system Hi3861 solution (binary)| 3.0.5 | [Download](https://repo.huaweicloud.com/openharmony/os/3.0.5/hispark_pegasus.tar.gz)| [Download](https://repo.huaweicloud.com/openharmony/os/3.0.5/hispark_pegasus.tar.gz.sha256)|
| Small system Hi3516 solution - LiteOS (binary)| 3.0.5 | [Download](https://repo.huaweicloud.com/openharmony/os/3.0.5/hispark_taurus.tar.gz)| [Download](https://repo.huaweicloud.com/openharmony/os/3.0.5/hispark_taurus.tar.gz.sha256)|
| Small system Hi3516 solution - Linux (binary)| 3.0.5 | [Download](https://repo.huaweicloud.com/openharmony/os/3.0.5/hispark_taurus_linux.tar.gz)| [Download](https://repo.huaweicloud.com/openharmony/os/3.0.5/hispark_taurus_linux.tar.gz.sha256)|
## What's New
### Feature Updates
**Table 3** New and enhanced features
| Subsystem| Standard System| Mini and Small Systems|
| -------- | -------- | -------- |
| Communication| NA | Added basic STA capabilities for small-system devices (Linux).<br>The following requirements are involved:<br>I5AAFQ Supporting STA features such as scanning, connection, and automatic reconnection<br>I5AAFQ Dynamically obtaining IPv4 addresses for STA connections|
| DFX| NA | Added native crash information collection and device restart fault locating for small-system devices (Linux).<br>The following requirements are involved:<br>I57I8Y/I57TOE Collecting native crash information<br>I5C0QR Locating device restart faults on Linux 5.10|
### API Updates
This version does not involve API updates.
### Chip and Development Board Adaptation
For details about the adaptation status, see [SIG-Devboard](https://gitee.com/openharmony/community/blob/master/sig/sig-devboard/sig_devboard.md).
## Resolved Issues
**Table 4** Resolved issues
| Issue No.| Description|
| -------- | -------- |
| [I4YBB0](https://gitee.com/openharmony/multimedia_camera_lite/issues/I4YBB0) | No image is generated and the recorded video cannot be played when the system camera is used to take a photo and record a video. This issue occurs only for the Hi3516D V300 development board running on a small-system device (Linux).|
| [I4YB87](https://gitee.com/openharmony/multimedia_camera_lite/issues/I4YB87) | No image is generated when the system camera is used to take a photo. This issue occurs only for the Hi3516D V300 development board running on a small-system device (Linux).|
| [I4YAGS](https://gitee.com/openharmony/multimedia_camera_lite/issues/I4YAGS?from=project-issue) | A blue screen is displayed when the system camera is accessed. This issue occurs only for the Hi3516D V300 development board running on a small-system device (Linux).|
| [I59FZ7](https://gitee.com/openharmony/telephony_core_service/issues/I59FZ7) | Test cases of the telephony subsystem fail to run on standard-system devices.|
| [I4Z2MI](https://gitee.com/openharmony/xts_acts/issues/I4Z2MI) | All test cases of the actsWifiJSApiTest, ActsHotSpotJSApiTest, and ActsP2PJSApiTest modules fail to run on standard-system devices.|
## Fixed Security Vulnerabilities
The following vulnerabilities are reported by the project teams. For details about the affected versions and patches released to fix the vulnerabilities, see [Security Vulnerability Disclosure](https://gitee.com/openharmony/security/tree/master/en/security-disclosure/2022).
| OpenHarmony-SA-2022-0501 | The DSoftBus subsystem has a heap overflow vulnerability.| Attackers can launch attacks locally, causing out-of-bounds memory access and obtaining system control rights.| communication_dsoftbus |
| OpenHarmony-SA-2022-0502 | The DSoftBus subsystem has a heap overflow vulnerability when receiving TCP messages.| Attackers can launch attacks on the LAN to remotely execute code and obtain system control rights.| communication_dsoftbus |
| OpenHarmony-SA-2022-0503 | The DSoftBus subsystem has an out-of-bounds access vulnerability when processing device synchronization messages.| Attackers can launch DoS attacks on the LAN, causing out-of-bounds memory access.| communication_dsoftbus |
| OpenHarmony-SA-2022-0504 | A pointer member contained in the **Lock** class is repeatedly released.| Attackers can launch attacks locally to obtain system control rights.| global_resmgr_standard |
| OpenHarmony-SA-2022-0601 | The common event and notification subsystem has an authentication bypass vulnerability when deserializing objects.| Attackers can launch attacks locally to bypass permissions, causing server process breakdown.| notification_ces_standard |
| OpenHarmony-SA-2022-0602 | The common event and notification subsystem has a verification bypass vulnerability, which can initiate SA relay attacks.| Attackers can launch attacks locally to bypass verification and obtain system control rights.| notification_ces_standard |
| OpenHarmony-SA-2022-0603 | The update module has a verification bypass vulnerability, which can initiate SA relay attacks.| Attackers can launch attacks locally to bypass verification and obtain system control rights.| update_updateservice |
| OpenHarmony-SA-2022-0604 | The multimedia subsystem has a verification bypass vulnerability, which can initiate SA relay attacks.| Attackers can launch attacks locally to bypass verification and obtain system control rights.| multimedia_media_standard |
