1# Vibrator Development (C/C++)
2
3
4## When to Use
5
6You can set different vibration effects as needed, for example, customizing the vibration intensity, frequency, and duration for button touches, alarm clocks, and incoming calls.
7
8For details about the APIs, see [Vibrator API Reference](../../reference/apis-sensor-service-kit/vibrator_8h.md).
9
10
11## Function Description
12
13| Name                                                        | Description                          |
14| ------------------------------------------------------------ | ------------------------------ |
15| OHOS::Sensors::OH_Vibrator_PlayVibration(int32_t duration, Vibrator_Attribute attribute) | Configues the vibrator to vibrate continuously for a given duration.|
16| OHOS::Sensors::OH_Vibrator_PlayVibrationCustom(Vibrator_FileDescription fileDescription, Vibrator_Attribute vibrateAttribute) | Configues the vibrator to vibrate with the custom sequence.          |
17| OHOS::Sensors::OH_Vibrator_Cancel()                          | Stops the vibration.                |
18
19## Vibration Effect Description
20
21Currently, two types of vibration effects are supported.
22
23### Fixed-Duration Vibration
24
25Only a fixed duration is passed in, and the device vibrates based on the default intensity and frequency.
26
27### Custom Vibration
28
29Custom vibration enables you to design desired vibration effects by customizing a vibration configuration file and orchestrating vibration forms based on the corresponding rules.
30
31
32## How to Develop
33
341. Create a native C++ project.
35
36   ![Create a project](figures/004.png)
37
382. Before using the vibrator on a device, you must declare the **ohos.permission.VIBRATE** permission. For details, see [Declaring Permissions](../../security/AccessToken/declare-permissions.md).
39
40   ```json
41   "requestPermissions": [
42         {
43           "name": "ohos.permission.VIBRATE",
44         },
45       ]
46   ```
47
483. Add the dynamic dependency libraries into the **CMakeLists.txt** file.
49
50   ```c
51   target_link_libraries(entry PUBLIC libace_napi.z.so)
52   target_link_libraries(entry PUBLIC libhilog_ndk.z.so)
53   target_link_libraries(entry PUBLIC libohvibrator.z.so)
54   ```
55
564. Import modules.
57
58   ```c
59   #include <sensors/vibrator.h>
60   #include "napi/native_api.h"
61   #include "hilog/log.h"
62   #include <thread>
63   #include <fcntl.h>
64   #include <unistd.h>
65   #include <sys/stat.h>
66   ```
67
685. Define constants.
69
70   ```c
71   const int GLOBAL_RESMGR = 0xFF00;
72   const char *TAG = "[NativeVibratorTest]";
73   constexpr int32_t TIME_WAIT_FOR_OP = 2;
74   ```
75
766. Configure the vibrator to vibrate continuously for a given duration.
77
78   ```c
79   static napi_value Vibration_Test(napi_env env, napi_callback_info info)
80   {
81       Vibrator_Attribute vibrateAttribute;
82       vibrateAttribute.usage = VIBRATOR_USAGE_ALARM;
83
84       int32_t ret = OH_Vibrator_PlayVibration(0, vibrateAttribute); // Configure the vibrator to vibrate continuously for a given duration.
85       OH_LOG_Print(LOG_APP, LOG_INFO, GLOBAL_RESMGR, TAG, "Vibration successful");
86       if (ret != PARAMETER_ERROR) {
87           return nullptr;
88       }
89       std::this_thread::sleep_for(std::chrono::milliseconds(TIME_WAIT_FOR_OP));
90       ret = OH_Vibrator_Cancel(); // Stop vibration.
91       if (ret == 0) {
92           return nullptr;
93       }
94   }
95   ```
96
978. Configure the vibrator to vibrate with the custom sequence.
98
99   ```c
100   static napi_value VibrationCustom_Test(napi_env env, napi_callback_info info)
101   {
102       int32_t fd = open("/data/test/vibrator/coin_drop.json", O_RDONLY);
103       OH_LOG_Print(LOG_APP, LOG_INFO, GLOBAL_RESMGR, TAG, "Test fd:%{public}d", fd);
104       struct stat64 statbuf = { 0 };
105       if (fd == 0) {
106           close(fd);
107           return nullptr;
108       }
109       if (fstat64(fd, &statbuf) == 0) {
110           Vibrator_FileDescription fileDescription = {
111               .fd = fd,
112               .offset = 0,
113               .length = statbuf.st_size
114           };
115           Vibrator_Attribute vibrateAttribute = {
116               .usage = VIBRATOR_USAGE_RING
117           };
118           int32_t ret = OH_Vibrator_PlayVibrationCustom(fileDescription, vibrateAttribute); // Configure the vibrator to vibrate with the custom sequence.
119           OH_LOG_Print(LOG_APP, LOG_INFO, GLOBAL_RESMGR, TAG, "Vibratecustom successful");
120           bool isSuccess = ((ret == 0) || (ret == UNSUPPORTED));
121           if (isSuccess == true) {
122               close(fd);
123               return nullptr;
124           }
125       }
126       std::this_thread::sleep_for(std::chrono::milliseconds(TIME_WAIT_FOR_OP));
127       close(fd);
128       OH_Vibrator_Cancel(); // Stop vibration.
129   }
130   ```
131
1328. Introduce the NAPI APIs to the **index.d.ts** file in **types/libentry**.
133
134   ```c
135   export const vibration_Test: () => number;
136   export const vibrationCustom_Test: () => number;
137   ```
138
1399. Write JavaScript test cases to test the APIs.
140