From b8fc9523339baf7b20b50fcf6f66c0d23bf8352b Mon Sep 17 00:00:00 2001 From: shawn_he Date: Thu, 3 Jul 2025 10:16:48 +0800 Subject: [PATCH] update doc Signed-off-by: shawn_he --- .../mindspore-lite-supported-operators.md | 69 + .../contacts/contacts-addcontactviaui.md | 94 + .../driver/environmental-preparation.md | 6 +- .../device/driver/hid-ddk-guidelines.md | 6 +- .../device/input/keypressed-guidelines.md | 103 +- .../device/sensor/sensor-guidelines.md | 91 +- .../device/sensor/sensorservice-kit-intro.md | 7 + .../device/sensor/vibrator-guidelines.md | 126 +- .../stationary/userStatus-guidelines.md | 62 + .../apis-driverdevelopment-kit/_base_ddk.md | 171 -- .../apis-driverdevelopment-kit/_ddk_ashmem.md | 105 - .../_hid___abs_axes_array.md | 52 - .../_hid___device.md | 117 - .../_hid___emit_item.md | 65 - .../_hid___event_properties.md | 143 - .../_hid___event_type_array.md | 52 - .../_hid___key_code_array.md | 52 - .../_hid___msc_event_array.md | 52 - .../_hid___raw_dev_info.md | 24 - .../_hid___rel_axes_array.md | 52 - .../apis-driverdevelopment-kit/_hid_ddk.md | 1676 ------------ .../apis-driverdevelopment-kit/_s_c_s_i.md | 1016 ------- .../_scsi_peripheral___basic_sense_info.md | 96 - .../_scsi_peripheral___capacity_info.md | 48 - .../_scsi_peripheral___device_mem_map.md | 84 - .../_scsi_peripheral___i_o_request.md | 108 - .../_scsi_peripheral___inquiry_info.md | 84 - .../_scsi_peripheral___inquiry_request.md | 84 - ...scsi_peripheral___read_capacity_request.md | 72 - .../_scsi_peripheral___request.md | 84 - ...scsi_peripheral___request_sense_request.md | 72 - .../_scsi_peripheral___response.md | 132 - ...si_peripheral___test_unit_ready_request.md | 48 - .../_scsi_peripheral___verify_request.md | 96 - .../apis-driverdevelopment-kit/_serial_ddk.md | 670 ----- .../_usb_config_descriptor.md | 132 - .../_usb_control_request_setup.md | 93 - .../apis-driverdevelopment-kit/_usb_ddk.md | 667 ----- .../_usb_ddk_config_descriptor.md | 80 - .../_usb_ddk_endpoint_descriptor.md | 67 - .../_usb_ddk_interface.md | 54 - .../_usb_ddk_interface_descriptor.md | 80 - .../_usb_device_array.md | 51 - .../_usb_device_descriptor.md | 210 -- .../_usb_device_mem_map.md | 93 - .../_usb_endpoint_descriptor.md | 132 - .../_usb_interface_descriptor.md | 145 - .../_usb_request_pipe.md | 67 - .../_usb_serial___params.md | 72 - .../capi-baseddk-ddk-ashmem.md | 24 + .../capi-baseddk.md | 13 + .../capi-ddk-api-h.md | 131 + .../capi-ddk-types-h.md | 51 + .../capi-hid-ddk-api-h.md | 546 ++++ .../capi-hid-ddk-types-h.md | 388 +++ .../capi-hidddk-hid-absaxesarray.md | 20 + .../capi-hidddk-hid-device.md | 25 + .../capi-hidddk-hid-devicehandle.md | 11 + .../capi-hidddk-hid-emititem.md | 21 + .../capi-hidddk-hid-eventproperties.md | 27 + .../capi-hidddk-hid-eventtypearray.md | 20 + .../capi-hidddk-hid-keycodearray.md | 20 + .../capi-hidddk-hid-msceventarray.md | 20 + .../capi-hidddk-hid-rawdevinfo.md | 21 + .../capi-hidddk-hid-relaxesarray.md | 20 + .../apis-driverdevelopment-kit/capi-hidddk.md | 15 + .../capi-scsi-peripheral-api-h.md | 452 ++++ .../capi-scsi-peripheral-types-h.md | 92 + ...pheralddk-scsiperipheral-basicsenseinfo.md | 24 + ...ripheralddk-scsiperipheral-capacityinfo.md | 20 + ...scsiperipheralddk-scsiperipheral-device.md | 11 + ...ripheralddk-scsiperipheral-devicememmap.md | 23 + ...eripheralddk-scsiperipheral-inquiryinfo.md | 23 + ...pheralddk-scsiperipheral-inquiryrequest.md | 23 + ...iperipheralddk-scsiperipheral-iorequest.md | 25 + ...lddk-scsiperipheral-readcapacityrequest.md | 22 + ...csiperipheralddk-scsiperipheral-request.md | 23 + ...lddk-scsiperipheral-requestsenserequest.md | 22 + ...siperipheralddk-scsiperipheral-response.md | 27 + ...ddk-scsiperipheral-testunitreadyrequest.md | 20 + ...ipheralddk-scsiperipheral-verifyrequest.md | 24 + .../capi-scsiperipheralddk.md | 13 + .../capi-serialddk-usbserial-devicehandle.md | 11 + .../capi-serialddk-usbserial-params.md | 22 + .../capi-serialddk.md | 15 + .../capi-usb-ddk-api-h.md | 480 ++++ .../capi-usb-ddk-types-h.md | 65 + .../capi-usb-serial-api-h.md | 386 +++ .../capi-usb-serial-types-h.md | 94 + .../capi-usbddk-usb-devicearray.md | 20 + .../capi-usbddk-usbconfigdescriptor.md | 26 + .../capi-usbddk-usbcontrolrequestsetup.md | 23 + .../capi-usbddk-usbddkconfigdescriptor.md | 22 + .../capi-usbddk-usbddkendpointdescriptor.md | 21 + .../capi-usbddk-usbddkinterface.md | 20 + .../capi-usbddk-usbddkinterfacedescriptor.md | 22 + .../capi-usbddk-usbdevicedescriptor.md | 32 + .../capi-usbddk-usbdevicememmap.md | 23 + .../capi-usbddk-usbendpointdescriptor.md | 26 + .../capi-usbddk-usbinterfacedescriptor.md | 27 + .../capi-usbddk-usbrequestpipe.md | 21 + .../apis-driverdevelopment-kit/capi-usbddk.md | 15 + .../apis-driverdevelopment-kit/ddk_api.md | 25 - .../apis-driverdevelopment-kit/ddk_types.md | 52 - .../hid__ddk__api_8h.md | 24 - .../hid__ddk__types_8h.md | 57 - .../scsi__peripheral__api_8h.md | 40 - .../scsi__peripheral__types_8h.md | 77 - .../usb__ddk__api_8h.md | 42 - .../usb__ddk__types_8h.md | 620 ----- .../usb__serial__ddk__api_8h.md | 38 - .../usb__serial__ddk__types_8h.md | 100 - .../capi-input-input-axisevent.md | 11 + .../capi-input-input-deviceinfo.md | 11 + .../capi-input-input-devicelistener.md | 20 + .../apis-input-kit/capi-input-input-hotkey.md | 11 + ...pi-input-input-interceptoreventcallback.md | 143 + .../capi-input-input-interceptoroptions.md | 11 + .../capi-input-input-keyevent.md | 11 + .../capi-input-input-keystate.md | 11 + .../capi-input-input-mouseevent.md | 11 + .../capi-input-input-touchevent.md | 11 + .../errorcode-userStatus.md | 75 + .../js-apis-awareness-userStatus.md | 121 + .../apis-network-kit/errorcode-kernel.md | 69 + .../apis-sensor-service-kit/_sensor.md | 654 ++++- .../errorcode-sensor.md | 2 +- .../js-apis-sensor-sys.md | 185 +- .../apis-sensor-service-kit/js-apis-sensor.md | 2362 +++++++++++++++-- .../js-apis-system-sensor.md | 92 +- .../js-apis-vibrator.md | 1764 ++++++------ 131 files changed, 8599 insertions(+), 9401 deletions(-) create mode 100644 en/application-dev/ai/mindspore/mindspore-lite-supported-operators.md create mode 100644 en/application-dev/contacts/contacts-addcontactviaui.md create mode 100644 en/application-dev/device/stationary/userStatus-guidelines.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_base_ddk.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_ddk_ashmem.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_hid___abs_axes_array.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_hid___device.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_hid___emit_item.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_hid___event_properties.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_hid___event_type_array.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_hid___key_code_array.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_hid___msc_event_array.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_hid___raw_dev_info.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_hid___rel_axes_array.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_hid_ddk.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_s_c_s_i.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___basic_sense_info.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___capacity_info.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___device_mem_map.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___i_o_request.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___inquiry_info.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___inquiry_request.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___read_capacity_request.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___request.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___request_sense_request.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___response.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___test_unit_ready_request.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___verify_request.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_serial_ddk.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_usb_config_descriptor.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_usb_control_request_setup.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_usb_ddk.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_usb_ddk_config_descriptor.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_usb_ddk_endpoint_descriptor.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_usb_ddk_interface.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_usb_ddk_interface_descriptor.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_usb_device_array.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_usb_device_descriptor.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_usb_device_mem_map.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_usb_endpoint_descriptor.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_usb_interface_descriptor.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_usb_request_pipe.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/_usb_serial___params.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-baseddk-ddk-ashmem.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-baseddk.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-ddk-api-h.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-ddk-types-h.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-hid-ddk-api-h.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-hid-ddk-types-h.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-absaxesarray.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-device.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-devicehandle.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-emititem.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-eventproperties.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-eventtypearray.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-keycodearray.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-msceventarray.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-rawdevinfo.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-relaxesarray.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-scsi-peripheral-api-h.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-scsi-peripheral-types-h.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-basicsenseinfo.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-capacityinfo.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-device.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-devicememmap.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-inquiryinfo.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-inquiryrequest.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-iorequest.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-readcapacityrequest.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-request.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-requestsenserequest.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-response.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-testunitreadyrequest.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-verifyrequest.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-serialddk-usbserial-devicehandle.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-serialddk-usbserial-params.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-serialddk.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-usb-ddk-api-h.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-usb-ddk-types-h.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-usb-serial-api-h.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-usb-serial-types-h.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usb-devicearray.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbconfigdescriptor.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbcontrolrequestsetup.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbddkconfigdescriptor.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbddkendpointdescriptor.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbddkinterface.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbddkinterfacedescriptor.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbdevicedescriptor.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbdevicememmap.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbendpointdescriptor.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbinterfacedescriptor.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbrequestpipe.md create mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/ddk_api.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/ddk_types.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/hid__ddk__api_8h.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/hid__ddk__types_8h.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/scsi__peripheral__api_8h.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/scsi__peripheral__types_8h.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/usb__ddk__api_8h.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/usb__ddk__types_8h.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/usb__serial__ddk__api_8h.md delete mode 100644 en/application-dev/reference/apis-driverdevelopment-kit/usb__serial__ddk__types_8h.md create mode 100644 en/application-dev/reference/apis-input-kit/capi-input-input-axisevent.md create mode 100644 en/application-dev/reference/apis-input-kit/capi-input-input-deviceinfo.md create mode 100644 en/application-dev/reference/apis-input-kit/capi-input-input-devicelistener.md create mode 100644 en/application-dev/reference/apis-input-kit/capi-input-input-hotkey.md create mode 100644 en/application-dev/reference/apis-input-kit/capi-input-input-interceptoreventcallback.md create mode 100644 en/application-dev/reference/apis-input-kit/capi-input-input-interceptoroptions.md create mode 100644 en/application-dev/reference/apis-input-kit/capi-input-input-keyevent.md create mode 100644 en/application-dev/reference/apis-input-kit/capi-input-input-keystate.md create mode 100644 en/application-dev/reference/apis-input-kit/capi-input-input-mouseevent.md create mode 100644 en/application-dev/reference/apis-input-kit/capi-input-input-touchevent.md create mode 100644 en/application-dev/reference/apis-multimodalawareness-kit/errorcode-userStatus.md create mode 100644 en/application-dev/reference/apis-multimodalawareness-kit/js-apis-awareness-userStatus.md create mode 100644 en/application-dev/reference/apis-network-kit/errorcode-kernel.md diff --git a/en/application-dev/ai/mindspore/mindspore-lite-supported-operators.md b/en/application-dev/ai/mindspore/mindspore-lite-supported-operators.md new file mode 100644 index 00000000000..660116ba9bb --- /dev/null +++ b/en/application-dev/ai/mindspore/mindspore-lite-supported-operators.md @@ -0,0 +1,69 @@ +# MindSpore Lite Kit Operator List + +This document provides the CPU backend operators supported by MindSpore Lite Kit and their mapping to ONNX Opset 18 operators. When using the model conversion tool to convert an ONNX model to an MS model for deployment, you can refer to this list for the supported ONNX operators, thereby ensuring the success of model conversion. + +| MindSpore Lite Operator| Description | ONNX Operator | +| ---------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | +| Abs | Computes the absolute value element-wise. | Abs | +| Activation | Computes the activation function. | Celu
Clip
Elu
Gelu
HSigmoid
LeakyRelu
PRelu
Relu
Sigmoid
SoftMax
SoftPlus
SoftSign
Tanh | +| AddFusion | Computes element-wise addition. | Add | +| ArgMaxFusion | Computes the maximum value along a specified dimension. | ArgMax | +| AvgPoolFusion | Performs average pooling. | AveragePool
GlobalAveragePool
GlobalMaxPool
MaxPool | +| BatchNorm | Performs batch normalization. | BatchNormalization | +| BroadcastTo | Expands the dimensions of a tensor. | Expand | +| Cast | Converts the data type. | Cast | +| Ceil | Rounds up to an integer. | Ceil | +| Clip | Limits the element range. | Clip | +| Concat | Concatenates tensors. | Concat | +| Conv2DFusion | Performs 2D convolution. | Conv | +| Cos | Computes the cosine element-wise. | Cos | +| CumSum | Accumulates the elements. | CumSum | +| DepthToSpace | Rearranges data from depth into blocks of spatial data. | DepthToSpace | +| DivFusion | Computes element-wise division. | Div | +| Eltwise | Computes element-wise summation. | Sum | +| Equal | Checks whether the inputs are equal. | Equal | +| Erf | Computes the error function. | Erf | +| ExpFusion | Computes the exponential element-wise. | Exp | +| Flatten | Flattens data by dimension. | Flatten | +| Floor | Rounds down to the nearest integer. | Floor | +| FusedBatchNorm | Performs fused batch normalization. | BatchNormalization | +| Gather | Gathers elements from a tensor along a specified axis. | Gather | +| GatherD | Gathers elements from a tensor using dynamic indices. | GatherElements | +| GatherNd | Gathers elements from a tensor using N-dimensional indices. | GatherND | +| InstanceNorm | Performs instance normalization. | InstanceNormalization | +| Log | Computes the natural logarithm element-wise. | Log | +| LogicalNot | Computes the element-wise logical NOT. | Not | +| LogSoftmax | Applies Softmax followed by Log to the input tensor. | LogSoftmax | +| LRN | Applies local response normalization to reduce overfitting. | LRN | +| MatMulFusion | Performs matrix multiplication on two input tensors by computing the inner product using the input tensors and a set of learned weights, followed by adding a bias.| Gemm
MatMul | +| Maximum | Computes the element-wise maximum. | Max | +| MaxPoolFusion | Performs max pooling operation. | GlobalMaxPool
MaxPool | +| Minimum | Computes the element-wise minimum. | Min | +| Mod | Computes the element-wise modulus. | Mod | +| MulFusion | Computes the element-wise multiplication. | Mul | +| Neg | Computes the element-wise negation. | Neg | +| PadFusion | Adds padding to a tensor. | Pad | +| PowFusion | Computes the element-wise power. | Pow | +| PReLUFusion | Performs parametric ReLU activation. | PRelu | +| Range | Generates a sequence of numbers with a specified start, end, and step. | Range | +| Reciprocal | Computes the element-wise reciprocal. | Reciprocal | +| Reshape | Reshapes a tensor. | Reshape | +| Round | Rounds to the nearest integer. | Round | +| ScatterNdUpdate | Updates specified elements of a tensor using given indices and values. | ScatterND | +| Shape | Obtains the shape of a tensor. | Shape | +| Sin | Computes the element-wise sine. | Sin | +| Size | Obtains the size of a tensor. | Size | +| SliceFusion | Slices a tensor. | Slice | +| Softmax | Applies the Softmax function to normalize a tensor along a specified axis. | Softmax | +| SpaceToDepth | Rearranges blocks of spatial data into depth. | SpaceToDepth | +| Sqrt | Computes the element-wise square root. | Sqrt | +| Squeeze | Removes dimensions of size 1. | Squeeze | +| StridedSlice | Slices a tensor with stride. | Slice | +| SubFusion | Computes the element-wise subtraction. | Sub | +| TileFusion | Constructs a tensor by replicating input tensor multiple times. | Tile | +| TopKFusion | Obtains the top K elements from the input tensor. | TopK | +| Transpose | Transposes a tensor. | Transpose | +| Tril | Obtains the lower triangular part of a matrix. | Trilu (upper=0) | +| Triu | Obtains the upper triangular part of a matrix. | Trilu (upper=1) | +| Unsqueeze | Inserts a new dimension into the input tensor. | Unsqueeze | +| Where | Selects elements based on specified conditions. | Where | diff --git a/en/application-dev/contacts/contacts-addcontactviaui.md b/en/application-dev/contacts/contacts-addcontactviaui.md new file mode 100644 index 00000000000..b0a70a0831d --- /dev/null +++ b/en/application-dev/contacts/contacts-addcontactviaui.md @@ -0,0 +1,94 @@ +# Using the Picker for Contact Management + +## Available APIs + +| API | Description | +| --------------------- | ------------------------------------------ | +| addContactViaUI(context: Context, contact: Contact): Promise<number> | Opens the **Add contact** page to add a contact. This API uses a promise to return the result.| +| saveToExistingContactViaUI(context: Context, contact: Contact): Promise<number> | Opens the **Save to existing** page to save a contact to an existing one. This API uses a promise to return the result.| + + +## Creating a Contact + +Call **addContactViaUI** to launch the UI for contact creation. Then, uses can complete contact information on the UI. + +```js +import { common } from '@kit.AbilityKit'; +import { contact } from '@kit.ContactsKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + + +@Entry +@Component +struct Index { + @State message: string = 'Hello World'; + + build() { + Column() { + Text(this.message) + .fontSize(50) + .fontWeight(FontWeight.Bold) + .onClick(() => { + let contactInfo: contact.Contact = { + name: { + fullName: 'xxx' + }, + phoneNumbers: [{ + phoneNumber: '138xxxxxx' + }] + } + let context = this.getUIContext().getHostContext() as common.UIAbilityContext; + let promise = contact.addContactViaUI(context, contactInfo); + promise.then((data) => { + console.info(`Succeeded in add Contact via UI.data->${JSON.stringify(data)}`); + }).catch((err: BusinessError) => { + console.error(`Failed to add Contact via UI. Code: ${err.code}, message: ${err.message}`); + }); + }) + } + } +} +``` + +## Updating Contact Information + +Call **saveToExistingContactViaUI** to launch the UI for contact information updating. Then, users can update information about a specific contact on the UI. + +```js +import { common } from '@kit.AbilityKit'; +import { contact } from '@kit.ContactsKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + + +@Entry +@Component +struct Index { + @State message: string = 'Hello World'; + + build() { + Column() { + Text(this.message) + .fontSize(50) + .fontWeight(FontWeight.Bold) + .onClick(() => { + let contactInfo: contact.Contact = { + id: 1, + name: { + fullName: 'xxx' + }, + phoneNumbers: [{ + phoneNumber: '138xxxxxx' + }] + } + let context = this.getUIContext().getHostContext() as common.UIAbilityContext; + let promise = contact.saveToExistingContactViaUI(context, contactInfo); + promise.then((data) => { + console.info(`Succeeded in save to existing Contact via UI.data->${JSON.stringify(data)}`); + }).catch((err: BusinessError) => { + console.error(`Failed to save to existing Contact via UI. Code: ${err.code}, message: ${err.message}`); + }); + }) + } + } +} +``` diff --git a/en/application-dev/device/driver/environmental-preparation.md b/en/application-dev/device/driver/environmental-preparation.md index 9c0f1bfab72..6733e8f7917 100644 --- a/en/application-dev/device/driver/environmental-preparation.md +++ b/en/application-dev/device/driver/environmental-preparation.md @@ -8,9 +8,9 @@ DevEco Studio, as the driver development tool, allows you to develop, debug, and ## SDK Version Configuration -The ArkTs APIs for peripheral management can be used only when the SDK is of API version 10 or later. For details about how to update the SDK, see [OpenHarmony SDK Upgrade Assistant](../../tools/openharmony_sdk_upgrade_assistant.md). +The ArkTs APIs for peripheral management are applicable only when the SDK is of API version 10 or later. -The SDK version must meet the following requirements when you develop dedicated peripheral drivers or enhanced peripheral drivers based on the DDK. +The following table lists the SDK versions required to develop dedicated peripheral drivers or enhanced peripheral drivers based on the DDK. | NDK API | SDK Version | |----------------|----------| @@ -36,5 +36,3 @@ HarmonyOS Device Connector (hdc) is a command-line tool for debugging. It can be - Currently, RK3568 is used as the device for development, debugging, and verification. For details about how to compile and burn the RK3568, see [Quick Start](../../../device-dev/quick-start/quickstart-pkg-3568-burn.md). - During peripheral client and driver development, you need to connect an external USB device for debugging. Currently, **only an external USB device is supported**. - The product ID and vendor ID of the USB device are required for defining drivers and implementing IPC. - - \ No newline at end of file diff --git a/en/application-dev/device/driver/hid-ddk-guidelines.md b/en/application-dev/device/driver/hid-ddk-guidelines.md index 2fec0f8ed66..fab2a40ad81 100644 --- a/en/application-dev/device/driver/hid-ddk-guidelines.md +++ b/en/application-dev/device/driver/hid-ddk-guidelines.md @@ -47,7 +47,7 @@ A non-standard peripheral application obtains the HID device ID by using the per | int32_t OH_Hid_Close(Hid_DeviceHandle **dev) | Closes a HID device.| | int32_t OH_Hid_Write(Hid_DeviceHandle *dev, uint8_t *data, uint32_t length, uint32_t *bytesWritten) | Writes a report to a HID device.| | int32_t OH_Hid_ReadTimeout(Hid_DeviceHandle *dev, uint8_t *data, uint32_t buffSize, int timeout, uint32_t *bytesRead) | Reads a report from a HID device within the specified time.| -| int32_t OH_Hid_Read(Hid_DeviceHandle *dev, uint8_t *data, uint32_t buffSize, uint32_t *bytesRead) | Reads a report from a HID device in the specified mode. The blocking mode (blocking remains active until data can be read) is used by default. You can call **OH_Hid_SetNonBlocking** to change the mode.| +| int32_t OH_Hid_Read(Hid_DeviceHandle *dev, uint8_t *data, uint32_t buffSize, uint32_t *bytesRead) | Reads a report from a HID device in the specified mode. The blocking mode (that is, blocking remains active until data can be read) is used by default. You can call **OH_Hid_SetNonBlocking** to change the mode.| | int32_t OH_Hid_SetNonBlocking(Hid_DeviceHandle *dev, int nonblock) | Sets the device read mode to non-blocking mode.| | int32_t OH_Hid_GetRawInfo(Hid_DeviceHandle *dev, Hid_RawDevInfo *rawDevInfo) | Obtains the raw information of a HID device.| | int32_t OH_Hid_GetRawName(Hid_DeviceHandle *dev, char *data, uint32_t buffSize) | Obtains the raw name of a HID device.| @@ -57,7 +57,7 @@ A non-standard peripheral application obtains the HID device ID by using the per | int32_t OH_Hid_GetReport(Hid_DeviceHandle *dev, Hid_ReportType reportType, uint8_t *data, uint32_t buffSize) | Obtains a report from a HID device.| | int32_t OH_Hid_GetReportDescriptor(Hid_DeviceHandle *dev, uint8_t *buf, uint32_t buffSize, uint32_t *bytesRead) | Obtains the report descriptor of a HID device.| -For details about the APIs, see [HID DDK](../../reference/apis-driverdevelopment-kit/_hid_ddk.md). +For details about the APIs, see [HID DDK](../../reference/apis-driverdevelopment-kit/capi-hidddk.md). ## How to Develop @@ -80,7 +80,7 @@ libhid.z.so 1. Create a HID device. - Use **OH_Hid_CreateDevice** of **hid_ddk_api.h** to create a HID device. If the operation is successful, a device ID is returned. If the operation fails, an [error code](../../reference/apis-driverdevelopment-kit/_hid_ddk.md#hid_ddkerrcode) is returned. + Use **OH_Hid_CreateDevice** of **hid_ddk_api.h** to create a HID device. If the operation is successful, a device ID is returned. If the operation fails, an [error code](../../reference/apis-driverdevelopment-kit/capi-hid-ddk-types-h.md#hid_ddkerrcode) is returned. ```c++ // Construct HID device properties. diff --git a/en/application-dev/device/input/keypressed-guidelines.md b/en/application-dev/device/input/keypressed-guidelines.md index 6a9684ac871..1ae415fd663 100644 --- a/en/application-dev/device/input/keypressed-guidelines.md +++ b/en/application-dev/device/input/keypressed-guidelines.md @@ -31,30 +31,85 @@ In e-book or news reading apps, users can navigate pages via volume buttons—ty ```js import { inputConsumer, KeyEvent } from '@kit.InputKit'; -// Start the application. -try { - let options: inputConsumer.KeyPressedConfig = { - key: 17, - action: 1, - isRepeat: false, +import { KeyCode } from '@kit.InputKit'; + +@Entry +@Component +struct TestDemo14 { + private volumeUpCallBackFunc: (event: KeyEvent) => void = () => { + } + private volumeDownCallBackFunc: (event: KeyEvent) => void = () => { + } + + aboutToAppear(): void { + try { + let options1: inputConsumer.KeyPressedConfig = { + key: KeyCode.KEYCODE_VOLUME_UP, + action: 1, // The value 1 indicates a key press. + isRepeat: false, // Key events are consumed preferentially and not reported. + } + let options2: inputConsumer.KeyPressedConfig = { + key: KeyCode.KEYCODE_VOLUME_DOWN, + action: 1, // The value 1 indicates a key press. + isRepeat: false, // Key events are consumed preferentially and not reported. + } + + // Callback invoked when the Volume Up button is pressed + this.volumeUpCallBackFunc = (event: KeyEvent) => { + this.getUIContext().getPromptAction().showToast({ message: 'The Volume Up button was pressed.' }); + // do something + } + + // Callback invoked when the Volume Down button is pressed + this.volumeDownCallBackFunc = (event: KeyEvent) => { + this.getUIContext().getPromptAction().showToast({ message: 'The Volume Down button was pressed.' }); + // do something + } + // Register an event listener. + inputConsumer.on('keyPressed', options1, this.volumeUpCallBackFunc); + inputConsumer.on('keyPressed', options2, this.volumeDownCallBackFunc); + } catch (error) { + console.error(`Subscribe execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`); + } + } + + build() { + Column() { + Row() { + Button ('Cancel listening for Volume Up button events') + .onClick(() => { + try { + // Disable listening for a single callback. + inputConsumer.off('keyPressed', this.volumeUpCallBackFunc); + this.getUIContext().getPromptAction().showToast({ message: ''Listening for Volume Up button events is canceled successfully.' }); + } catch (error) { + console.error(`Unsubscribe execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`); + } + }) + }.width('100%') + .justifyContent(FlexAlign.Center) + .margin({ top: 20, bottom: 50 }) + + Row() { + Button ('Cancel listening for Volume Down button events') + .onClick(() => { + try { + // Disable listening for a single callback. + inputConsumer.off('keyPressed', this.volumeDownCallBackFunc); + this.getUIContext().getPromptAction().showToast({ message: 'Listening for Volume Down button events is canceled successfully.' }); + } catch (error) { + console.error(`Unsubscribe execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`); + } + }) + }.width('100%') + .justifyContent(FlexAlign.Center) + .margin({ top: 20, bottom: 50 }) + Row(){ + Text ('Listening is enabled for Volume Down and Volume Down button events by default.') + } + .width('100%') + .justifyContent(FlexAlign.Center) + }.width('100%').height('100%') } - // Subscribe to key press events. - inputConsumer.on('keyPressed', options, (event: KeyEvent) => { - console.info(`Subscribe success ${JSON.stringify(event)}`); - }); - // You can define a typical scenario, such as page turning or in-app photographing via the volume button. -} catch (error) { - console.error(`Subscribe execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`); -} -// Stop the application. -try { - // Disable listening for a single callback. - inputConsumer.off('keyPressed', (event: KeyEvent) => { - console.info(`Unsubscribe success ${JSON.stringify(event)}`); - }); - // Disable listening for all callbacks. - inputConsumer.off("keyPressed"); -} catch (error) { - console.error(`Unsubscribe execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`); } ``` diff --git a/en/application-dev/device/sensor/sensor-guidelines.md b/en/application-dev/device/sensor/sensor-guidelines.md index d5f7ef19b04..9f129199e69 100644 --- a/en/application-dev/device/sensor/sensor-guidelines.md +++ b/en/application-dev/device/sensor/sensor-guidelines.md @@ -10,12 +10,15 @@ For details about the APIs, see [Sensor](../../reference/apis-sensor-service-kit ## Available APIs -| Name| Description| -| -------- | -------- | -| sensor.on(sensorId, callback:AsyncCallback<Response>): void | Subscribes to data changes of a type of sensor.| -| sensor.once(sensorId, callback:AsyncCallback<Response>): void | Subscribes to only one data change of a type of sensor.| -| sensor.off(sensorId, callback?:AsyncCallback<void>): void | Unsubscribes from sensor data changes.| -| sensor.getSensorList(callback: AsyncCallback\>): void| Obtains information about all sensors on the device. This API uses an asynchronous callback to return the result.| +| Name| Description | +| -------- |---------------------------------| +| sensor.on(sensorId, callback:AsyncCallback<Response>, options?: Options): void | Enables listening for data changes of the specified type of sensor. | +| sensor.on(type: 'sensorStatusChange', callback: Callback<SensorStatusEvent>): void | Enables listening for sensor status changes.| +| sensor.once(sensorId, callback:AsyncCallback<Response>): void | Enables one-time listening for sensor data changes. | +| sensor.off(sensorId, callback?:AsyncCallback<void>): void | Disables listening for data changes of the specified type of sensor. | +| sensor.off(sensorId, sensorInfoParam?: SensorInfoParam, callback?:AsyncCallback<void>): void | Disables listening for data changes of the specified type of sensor based on the given sensor parameters. | +| sensor.off(type: 'sensorStatusChange', callback?: Callback<SensorStatusEvent>): void | Disables listening for sensor status changes. | +| sensor.getSensorList(callback: AsyncCallback\>): void| Obtains information about all sensors on the device. | ## How to Develop @@ -34,7 +37,7 @@ The acceleration sensor is used as an example. ```ts sensor.getSensorList((error: BusinessError, data: Array) => { if (error) { - console.info('getSensorList failed'); + console.error('getSensorList failed'); } else { console.info('getSensorList success'); for (let i = 0; i < data.length; i++) { @@ -48,21 +51,58 @@ The acceleration sensor is used as an example. The minimum and the maximum sampling periods supported by the sensor are 5000000 ns and 200000000 ns, respectively. The sampling interval may vary depending on the sensor type. The specified sampling interval must be within this range. If the configured value is smaller than the minimum sampling interval of the sensor, the minimum sampling interval is used. If the configured value is larger than the maximum sampling interval of the sensor, the maximum sampling interval is used. A smaller value means a higher reporting frequency and a higher power consumption. + You can query sensors based on the given device ID. + ```ts + try { + const deviceId = 1; + // The deviceId parameter is optional. By default, it is set to the ID of the local device. + const sensorList: sensor.Sensor[] = sensor.getSensorListByDeviceSync(deviceId); + console.log(`sensorList length: ${sensorList.length}`); + console.log(`sensorList: ${JSON.stringify(sensorList)}`); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to get sensorList. Code: ${e.code}, message: ${e.message}`); + } + ``` + 3. Check whether the corresponding permission has been configured. For details, see [Declaring Permissions](../../security/AccessToken/declare-permissions.md). -4. Register a listener. You can call **on()** or **once()** to listen for sensor data changes. +4. Enable listening for sensor status changes. You can call **on()** or **once()** to listen for sensor data changes. The **on()** API is used to continuously listen for data changes of the sensor. The sensor reporting interval is set to 100000000 ns. - ```ts - sensor.on(sensor.SensorId.ACCELEROMETER, (data: sensor.AccelerometerResponse) => { - console.info("Succeeded in obtaining data. x: " + data.x + " y: " + data.y + " z: " + data.z); - }, { interval: 100000000 }); + ```ts + import { sensor } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + try { + sensor.on(sensor.SensorId.ACCELEROMETER, (data: sensor.AccelerometerResponse) => { + console.info("Succeeded in obtaining data. x: " + data.x + " y: " + data.y + " z: " + data.z); + }, { interval: 100000000 }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to get sensorList. Code: ${e.code}, message: ${e.message}`); + } + ``` + + You can also specify SensorInfoParam, which is used to pass deviceId and sensorIndex. + ```ts + import { sensor } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + try { + sensor.on(sensor.SensorId.ACCELEROMETER, (data: sensor.AccelerometerResponse) => { + console.info("Succeeded in obtaining data. x: " + data.x + " y: " + data.y + " z: " + data.z); + }, { interval: 100000000, sensorInfoParam: { deviceId: 1, sensorIndex: 3 } }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to get sensorList. Code: ${e.code}, message: ${e.message}`); + } ``` ![](figures/002.png) - The **once()** API is used to listen for only one data change of the sensor. + The **once()** API is used to perform one-time listening for sensor data changes. ```ts sensor.once(sensor.SensorId.ACCELEROMETER, (data: sensor.AccelerometerResponse) => { @@ -72,8 +112,31 @@ The acceleration sensor is used as an example. ![](figures/003.png) -5. Cancel continuous listening. +5. Disable listening for sensor status changes. + Note that disabling listening without a prior subscription is an abnormal behavior and requires exception handling. ```ts sensor.off(sensor.SensorId.ACCELEROMETER); ``` + + Disables listening for sensor status changes based on the given sensor parameters. + ```ts + sensor.off(sensor.SensorId.ACCELEROMETER, { deviceId: 1, sensorIndex: 3 }); + ``` + +6. Enable listening for sensor status changes. When receiving a device offline event, you need to call **off** to close the sensor on the device. + + In **SensorStatusEvent**, the following information is included: event timestamp, sensor ID, sensor index, online/offline status, device ID, and device name. + ```ts + sensor.on('sensorStatusChange', (data: sensor.SensorStatusEvent) => { + console.log(`timestamp: ${data.timestamp}, + deviceId: ${data.deviceId} deviceName: ${data.deviceName} + sensorId: ${data.sensorId} sensorIndex:${data.sensorIndex} isSensorOnline: ${data.isSensorOnline}`) + }); + ``` + + Disable listening for sensor status changes. + ```ts + // Before performing this operation, ensure that listening for sensor status changes has been enabled. + sensor.off('sensorStatusChange'); + ``` diff --git a/en/application-dev/device/sensor/sensorservice-kit-intro.md b/en/application-dev/device/sensor/sensorservice-kit-intro.md index 6f10e0a7bab..946eee9d349 100644 --- a/en/application-dev/device/sensor/sensorservice-kit-intro.md +++ b/en/application-dev/device/sensor/sensorservice-kit-intro.md @@ -5,8 +5,13 @@ Sensor Service Kit enables applications to obtain raw data from sensors and provides vibration control capabilities. - The sensor module provides APIs for applications to access the underlying sensor hardware. Using these APIs, you can query sensors on your device and subscribe to sensor data. Based on the sensor data obtained, you can customize algorithms and develop various sensor-based applications, such as compass, motion-controlled games, and fitness and health applications. + - Local sensors: sensors built into the device. Typical examples include accelerometers, gyroscopes, and temperature sensors. + - Dynamic sensors: external sensors. The sensor module supports refined control over dynamic sensors, and listening for status changes (such as connection and disconnection) of dynamic sensors can be enabled or disabled via the **on** or **off** API. - The vibrator module maximally unlocks the capabilities of the vibrator device. By expanding the vibrator services, it achieves an integrated design of vibration and interaction, creating a delicate and sophisticated vibration experience that takes user interaction efficiency and usability to the next level. + - Local vibrators: vibrators built into the device. Typical examples include rotor vibrators and linear vibrators. + - Dynamic vibrators: external vibrators, which support independent control and management based on information such as device connection status and vibrator status. Dynamic vibrators are widely used in peripherals, including game controllers and external vibrators. + ## Constraints @@ -18,8 +23,10 @@ Sensor Service Kit enables applications to obtain raw data from sensors and prov - The APIs for subscribing to and unsubscribing from sensor data work in pairs. If you do not need sensor data, call the unsubscription API to stop sensor data reporting. +- If a dynamic sensor is disconnected, the application needs to disable listening for sensor data changes. ### Vibrator - To use vibrator functions, ensure that the device where your application runs has the required misc components. - To use vibrators, you need to request the required permissions. +- If there are multiple devices and vibrators, the application must determine which vibrator to use. diff --git a/en/application-dev/device/sensor/vibrator-guidelines.md b/en/application-dev/device/sensor/vibrator-guidelines.md index b14c495f2c0..7cc77c74ec5 100644 --- a/en/application-dev/device/sensor/vibrator-guidelines.md +++ b/en/application-dev/device/sensor/vibrator-guidelines.md @@ -10,16 +10,21 @@ For details about the APIs, see [Vibrator](../../reference/apis-sensor-service-k ## Available APIs -| Name | Description | -| ------------------------------------------------------------ | ------------------------------------------------------------ | -| startVibration(effect: VibrateEffect, attribute: VibrateAttribute): Promise<void> | Starts vibration with the specified effect and attribute. This API uses a promise to return the result.| -| startVibration(effect: VibrateEffect, attribute: VibrateAttribute, callback: AsyncCallback<void>): void | Starts vibration with the specified effect and attribute. This API uses an asynchronous callback to return the result.| -| stopVibration(stopMode: VibratorStopMode): Promise<void> | Stops vibration in the specified mode. This API uses a promise to return the result. | -| stopVibration(stopMode: VibratorStopMode, callback: AsyncCallback<void>): void | Stops vibration in the specified mode. This API uses an asynchronous callback to return the result. | -| stopVibration(): Promise<void> | Stops vibration in all modes. This API uses a promise to return the result. | -| stopVibration(callback: AsyncCallback<void>): void | Stops vibration in all modes. This API uses an asynchronous callback to return the result. | -| isSupportEffect(effectId: string): Promise<boolean> | Checks whether an effect ID is supported. This API uses a promise to return the result. This API uses a promise to return the result. The return value **true** means that the effect ID is supported, and **false** means the opposite.| -| isSupportEffect(effectId: string, callback: AsyncCallback<boolean>): void | Checks whether an effect ID is supported. This API uses an asynchronous callback to return the result. This API uses an asynchronous callback to return the result. The return value **true** means that the effect ID is supported, and **false** means the opposite.| +| Name | Description | +| ------------------------------------------------------------ |-----------------------------------------------------------------------------| +| startVibration(effect: VibrateEffect, attribute: VibrateAttribute): Promise<void> | Starts vibration with the specified effect and attribute. This API uses a promise to return the result. | +| startVibration(effect: VibrateEffect, attribute: VibrateAttribute, callback: AsyncCallback<void>): void | Starts vibration with the specified effect and attribute. This API uses an asynchronous callback to return the result. | +| stopVibration(stopMode: VibratorStopMode): Promise<void> | Stops vibration in the specified mode. This API uses a promise to return the result. | +| stopVibration(stopMode: VibratorStopMode, callback: AsyncCallback<void>): void | Stops vibration in the specified mode. This API uses an asynchronous callback to return the result. | +| stopVibration(): Promise<void> | Stops vibration in all modes. This API uses a promise to return the result. | +| stopVibration(param?: VibratorInfoParam): Promise<void> | Stops vibration based on the specified vibrator parameters. This API uses a promise to return the result. | +| stopVibration(callback: AsyncCallback<void>): void | Stops vibration in all modes. This API uses an asynchronous callback to return the result. | +| isSupportEffect(effectId: string): Promise<boolean> | Checks whether an effect ID is supported. This API uses a promise to return the result. The return value **true** means that the effect ID is supported, and **false** means the opposite. | +| isSupportEffect(effectId: string, callback: AsyncCallback<boolean>): void | Checks whether an effect ID is supported. This API uses an asynchronous callback to return the result. The return value **true** means that the effect ID is supported, and **false** means the opposite. | +| getEffectInfoSync(effectId: string, param?: VibratorInfoParam): EffectInfo | Checks whether the effect specified by the input **effectId** is supported. The **param** parameter can be used to specify a specific vibrator. You can check the **isEffectSupported** field in the returned **EffectInfo** object to determine whether the effect is supported.| +| getVibratorInfoSync(param?: VibratorInfoParam): Array<VibratorInfo> | Queries the vibrator list of one or all devices. The returned **VibratorInfo** object includes the following information: device ID, vibrator ID, device name, support for HD vibration, and local device flag. | +| on(type: 'vibratorStateChange', callback: Callback<VibratorStatusEvent>): void | Enables listening for vibrator status changes. The **VibratorStatusEvent** parameter includes the following information: event timestamp, device ID, number of vibrators, and online/offline status. | +| off(type: 'vibratorStateChange', callback?: Callback<VibratorStatusEvent>): void | Disables listening for vibrator status changes. | ## Vibration Effect Description @@ -151,7 +156,42 @@ The following requirements must be met: 1. 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). -2. Start vibration with the specified effect and attribute. +2. Query vibrator information. + + Scenario 1: Query information about all vibrators. + + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + try { + const vibratorInfoList: vibrator.VibratorInfo[] = vibrator.getVibratorInfoSync(); + console.log(`vibratorInfoList: ${JSON.stringify(vibratorInfoList)}`); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` + + Scenario 2: Query information about one or more vibrators of the specified device. + + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + try { + const vibratorParam: vibrator.VibratorInfoParam = { + deviceId: 1 // The device ID must be the one that actually exists. + } + const vibratorInfoList: vibrator.VibratorInfo[] = vibrator.getVibratorInfoSync(vibratorParam); + console.log(`vibratorInfoList: ${JSON.stringify(vibratorInfoList)}`); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` + +3. Start vibration with the specified effect and attribute. Scenario 1: Trigger vibration with the specified duration. @@ -276,7 +316,7 @@ The following requirements must be met: } ``` -3. Stop vibration. +4. Stop vibration. Method 1: Stop vibration in the specified mode. This method is invalid for custom vibration. @@ -343,11 +383,65 @@ The following requirements must be met: } ``` + Method 3: Stop vibration of the specified device. -## Samples + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + const vibratorInfoParam: vibrator.VibratorInfoParam = { + deviceId: 1 // The device ID must be the one that actually exists. + } + try { + vibrator.stopVibration(vibratorInfoParam).then(() => { + console.info('Succeed in stopping vibration'); + }, (error: BusinessError) => { + console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`); + }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` -The following sample is provided to help you better understand how to develop vibrators: -- [Vibrator (ArkTS, API version 9)](https://gitee.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/DeviceManagement/Vibrator/BasicVibration) +5. Enable listening for vibrator status changes. -- [CustomHaptic (ArkTS, Full SDK, API version 10)](https://gitee.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/DeviceManagement/Vibrator/CustomHaptic) + Enable listening. + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + // Callback + const vibratorStateChangeCallback = (data: vibrator.VibratorStatusEvent) => { + console.log('vibrator state callback info:', JSON.stringify(data)); + } + + try { + // Subscribe to vibratorStateChange events. + vibrator.on('vibratorStateChange', vibratorStateChangeCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` + + Disable listening. The specified callback must be the same as that passed to the **on** API. + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + // Callback + const vibratorStateChangeCallback = (data: vibrator.VibratorStatusEvent) => { + console.log('vibrator state callback info:', JSON.stringify(data)); + } + try { + // Unsubscribe from specified vibratorStateChange events. + vibrator.off('vibratorStateChange', vibratorStateChangeCallback); + // Unsubscribe from all vibratorStateChange events. + // vibrator.off('vibratorStateChange'); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` diff --git a/en/application-dev/device/stationary/userStatus-guidelines.md b/en/application-dev/device/stationary/userStatus-guidelines.md new file mode 100644 index 00000000000..abbe9e308c6 --- /dev/null +++ b/en/application-dev/device/stationary/userStatus-guidelines.md @@ -0,0 +1,62 @@ +# User Status Awareness Development + +The UserStatus module, designed for user status awareness, empowers the system to perceive specific conditions of the operator, such as determining their age group. + +For details about the APIs, see the [userStatus API Reference](../../reference/apis-multimodalawareness-kit/js-apis-awareness-userStatus.md). + +## How to Develop +### When to Use +An application can invoke the UserStatus module when it needs to obtain the age group of users. This way, the application can determine, for example, whether the individual interacting with the device is a child or an adult. + +### Available APIs + +| API | Description | +| ------------------------------------------------------------ | -------------------------------------- | +| on(type:'userAgeGroupDetected',callback:Callback<UserClassification>):void; | Enables the age group detection function. This API returns the result through a callback.| +| off(type: 'userAgeGroupDetected', callback?: Callback<UserClassification>): void; | Disables the age group detection function. | + +### Constraints + + - The device must support the touchscreen and be compatible with specific chips. + +### Development Procedure + +1. Import the related modules. + + ```ts + import { userStatus } from '@kit.MultimodalAwarenessKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + import { Callback } from '@ohos.base'; + ``` + +2. Define the callback used to receive the age group detection result. + + ``` + let callback : Callback = (data : userStatus.UserClassification) => { + console.info('callback success, ageGroup:' + data.ageGroup + ", confidence:" + data.confidence); + }; + ``` + +3. Enable the age group detection function. + + ``` + try { + userStatus.on('userAgeGroupDetected', callback); + console.info("on succeeded"); + } catch (err) { + let error = err as BusinessError; + console.error("Failed on and err code is " + error.code); + } + ``` + +4. Disable the age group detection function. + + ``` + try { + userStatus.off('userAgeGroupDetected'); + console.info("off succeeded"); + } catch (err) { + let error = err as BusinessError; + console.error("Failed off and err code is " + error.code); + } + ``` diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_base_ddk.md b/en/application-dev/reference/apis-driverdevelopment-kit/_base_ddk.md deleted file mode 100644 index ceded0972f1..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_base_ddk.md +++ /dev/null @@ -1,171 +0,0 @@ -# Base DDK - - -## Overview - -Provides APIs for creating, mapping, unmapping, and destroying an **Ashmem** object. - -**System capability**: SystemCapability.Driver.DDK.Extension - -**Since** - -12 - -## Summary - - -### Files - -| Name| Description| -| -------- | -------- | -| [ddk_api.h](ddk_api.md) | Declares the HID DDK functions for accessing an input device from the host.
File to include: <base/ddk_api.h>
Library: libddk_base.z.so| -| [ddk_types.h](ddk_types.md) | Defines the enum variables and structs used in the HID DDK.
File to include:
Library: libddk_base.z.so| - - -### Structs - -| Name| Description| -| -------- | -------- | -| [DDK_Ashmem](_ddk_ashmem.md) | Shared memory. | - - -### Enums - -| Name| Description| -| -------- | -------- | -| [DDK_RetCode](#ddk_retcode) | Base DDK error code definitions. | - - -### Functions - -| Name| Description| -| -------- | -------- | -| [OH_DDK_CreateAshmem](#oh_ddk_createashmem) (const uint8_t *name, [DDK_Ashmem](_ddk_ashmem.md) \*\*ashmem) | Creates an **Ashmem** object. | -| [OH_DDK_MapAshmem](#oh_ddk_mapashmem) ([DDK_Ashmem](_ddk_ashmem.md) \*ashmem, const uint8_t ashmemMapType) | Maps an **Ashmem** object. | -| [OH_DDK_UnmapAshmem](#oh_ddk_unmapashmem) ([DDK_Ashmem](_ddk_ashmem.md) \*ashmem) | Unmaps an **Ashmem** object. | -| [OH_DDK_DestroyAshmem](#oh_ddk_destroyashmem) ([DDK_Ashmem](_ddk_ashmem.md) \*ashmem) | Destroys an **Ashmem** object. | - - -## Enum Description - - -### DDK_RetCode - - -``` -enum DDK_RetCode -``` - -**Description** - -Base DDK error code definitions. - -| Value| Description| -| -------- | -------- | -| DDK_SUCCESS | The operation is successful.| -| DDK_FAILED | Operation failed.| -| DDK_INVALID_PARAMETER | Invalid parameter.| -| DDK_INVALID_OPERATION | Invalid operation.| -| DDK_NULL_PTR | Null pointer.| - - -## Function Description - - -### OH_DDK_CreateAshmem() - - -``` -DDK_RetCode OH_DDK_CreateAshmem(const uint8_t *name, uint32_t size, DDK_Ashmem **ashmem); -``` - -**Description** - -Creates an **Ashmem** object. - -**Parameters** - -| Name| Description| -| -------- | -------- | -| name | Name of the **Ashmem** object.| -| size | Buffer size of the **Ashmem** object.| -| ashmem | Pointer to the **Ashmem** object.| - -**Returns** - -- [DK_SUCCESS](#ddk_retcode) if the API is called successfully. -- [DDK_INVALID_PARAMETER](#ddk_retcode) if the input **name** or **ashmem** is a null pointer, or **size** is **0**. -- [DDK_FAILURE] (#ddk_retcode) if the attempt to create the shared memory or the **DDK_Ashmem** structure fails. - - -### OH_DDK_MapAshmem() - - -``` -DDK_RetCode OH_DDK_MapAshmem(DDK_Ashmem *ashmem, const uint8_t ashmemMapType); -``` - -**Description** - -Maps an **Ashmem** object. - -**Parameters** - -| Name| Description| -| -------- | -------- | -| ashmem | Pointer to the **Ashmem** object.| -| ashmemMapType | Mapping type for the **Ashmem** object.| - -**Returns** - -- [DK_SUCCESS](#ddk_retcode) if the API is called successfully. -- [DDK_NULL_PTR](#ddk_retcode) if the input **ashmem** is a null pointer. -- [DDK_FAILURE] (#ddk_retcode) if the file descriptor of the shared memory is invalid. -- [DDK_INVALID_OPERATION](#ddk_retcode) if calling the **MapAshmem** API fails. - - -### OH_DDK_UnmapAshmem() - - -``` -DDK_RetCode OH_DDK_UnmapAshmem(DDK_Ashmem *ashmem); -``` - -**Description** - -Unmaps an **Ashmem** object. - -**Parameters** - -| Name| Description| -| -------- | -------- | -| ashmem | Pointer to the **Ashmem** object.| - -**Returns** - -- [DK_SUCCESS](#ddk_retcode) if the API is called successfully. -- [DDK_NULL_PTR](#ddk_retcode) if the input **ashmem** is a null pointer. -- [DDK_FAILURE] (#ddk_retcode) if the file descriptor of the shared memory is invalid. - -### OH_DDK_DestroyAshmem() - - -``` -DDK_RetCode OH_DDK_DestroyAshmem(DDK_Ashmem *ashmem); -``` - -**Description** - -Destroys the created shared memory. - -**Parameters** - -| Name| Description| -| -------- | -------- | -| ashmem | Pointer to the **Ashmem** object.| - -**Returns** - -- [DK_SUCCESS](#ddk_retcode) if the API is called successfully. -- [DDK_NULL_PTR](#ddk_retcode) if the input **ashmem** is a null pointer. -- [DDK_FAILURE] (#ddk_retcode) if the file descriptor of the shared memory is invalid. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_ddk_ashmem.md b/en/application-dev/reference/apis-driverdevelopment-kit/_ddk_ashmem.md deleted file mode 100644 index 03a313266e4..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_ddk_ashmem.md +++ /dev/null @@ -1,105 +0,0 @@ -# DDK_Ashmem - - -## Overview - -Defines the data structure of **Ashmem** objects. - -**Since** - -12 - -**Related module** - -[Base DDK](_base_ddk.md) - -**Header file**: [ddk_types.h](ddk_types.md) - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| [ashmemFd](#ashmemfd) | File descriptor of the **Ashmem** object.| -| [address](#address) | Mapping address of the **Ashmem** object.| -| [size](#size) | Length of the data array.| -| [offset](#offset) | Data offset.| -| [bufferLength](#bufferlength) | Length of the data array that is actually used.| -| [transferredLength](#transferredlength) | Length of the data to transfer.| - - -## Member Variable Description - - -### ashmemFd - - -~~~ -int32_t ashmemFd -~~~ - -**Description** - -File descriptor of the **Ashmem** object. - - -### address - - -~~~ -const uint8_t * address -~~~ - -**Description** - -Mapping address of the **Ashmem** object. - - -### size - - -~~~ -const uint32_t size -~~~ - -**Description** - -Length of the data array. - - -### offset - - -~~~ -uint32_t offset -~~~ - -**Description** - -Data offset. - - -### bufferLength - - -~~~ -uint32_t bufferLength -~~~ - -**Description** - -Length of the data array that is actually used. - - -### transferredLength - - -~~~ -uint32_t transferredLength -~~~ - -**Description** - -Length of the data to transfer. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_hid___abs_axes_array.md b/en/application-dev/reference/apis-driverdevelopment-kit/_hid___abs_axes_array.md deleted file mode 100644 index e9fb5b8ebae..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_hid___abs_axes_array.md +++ /dev/null @@ -1,52 +0,0 @@ -# Hid_AbsAxesArray - - -## Overview - -Defines an array of absolute coordinates. - -**Since** - -11 - -**Related module** - -[HID DDK](_hid_ddk.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| [hidAbsAxes](#hidabsaxes) | Array of absolute coordinates.| -| [length](#length) | Length of the array.| - - -## Member Variable Description - - -### hidAbsAxes - - -``` -Hid_AbsAxes Hid_AbsAxesArray::*hidAbsAxes -``` - -**Description** - -Array of absolute coordinates. - - -### length - - -``` -uint16_t Hid_AbsAxesArray::length -``` - -**Description** - -Length of the array. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_hid___device.md b/en/application-dev/reference/apis-driverdevelopment-kit/_hid___device.md deleted file mode 100644 index d2f5e39d32d..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_hid___device.md +++ /dev/null @@ -1,117 +0,0 @@ -# Hid_Device - - -## Overview - -Defines basic device information. - -**Since** - -11 - -**Related module** - -[HID DDK](_hid_ddk.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| [deviceName](#devicename) | Device name.| -| [vendorId](#vendorid) | Vendor ID.| -| [productId](#productid) | Product ID.| -| [version](#version) | Version number.| -| [bustype](#bustype) | Bus type.| -| [properties](#properties) | Device properties.| -| [propLength](#proplength) | Number of device properties.| - - -## Member Variable Description - - -### deviceName - - -``` -const char Hid_Device::deviceName -``` - -**Description** - -Device name. - - -### vendorId - - -``` -uint16_t Hid_Device::vendorId -``` - -**Description** - -Vendor ID. - - -### productId - - -``` -uint16_t Hid_Device::productId -``` - -**Description** - -Product ID. - - -### version - - -``` -uint16_t Hid_Device::version -``` - -**Description** - -Version number. - - -### bustype - - -``` -uint16_t Hid_Device::bustype -``` - -**Description** - -Bus type. - - -### properties - - -``` -Hid_DeviceProp Hid_Device::properties -``` - -**Description** - -Device properties. - - -### propLength - - -``` -uint16_t Hid_Device::propLength -``` - -**Description** - -Number of device properties. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_hid___emit_item.md b/en/application-dev/reference/apis-driverdevelopment-kit/_hid___emit_item.md deleted file mode 100644 index a053ecbda28..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_hid___emit_item.md +++ /dev/null @@ -1,65 +0,0 @@ -# Hid_EmitItem - - -## Overview - -Defines event information. - -**Since** - -11 - -**Related module** - -[HID DDK](_hid_ddk.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| [type](#type) | Event type.| -| [code](#code) | Event code.| -| [value](#value) | Event value.| - - -## Member Variable Description - - -### type - - -``` -uint16_t Hid_EmitItem::type -``` - -**Description** - -Event type. - - -### code - - -``` -uint16_t Hid_EmitItem::code -``` - -**Description** - -Event code. - - -### value - - -``` -uint32_t Hid_EmitItem::value -``` - -**Description** - -Event value. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_hid___event_properties.md b/en/application-dev/reference/apis-driverdevelopment-kit/_hid___event_properties.md deleted file mode 100644 index e0e737e09da..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_hid___event_properties.md +++ /dev/null @@ -1,143 +0,0 @@ -# Hid_EventProperties - - -## Overview - -Defines the event properties of a device. - -**Since** - -11 - -**Related module** - -[HID DDK](_hid_ddk.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| [hidEventTypes](#hideventtypes) | Array of event types.| -| [hidKeys](#hidkeys) | Array of key codes.| -| [hidAbs](#hidabs) | Array of absolute coordinates.| -| [hidRelBits](#hidrelbits) | Array of relative coordinates.| -| [hidMiscellaneous](#hidmiscellaneous) | Array of miscellaneous events.| -| [hidAbsMax](#hidabsmax) | Maximum values of the absolute coordinates.| -| [hidAbsMin](#hidabsmin) | Minimum values of the absolute coordinates.| -| [hidAbsFuzz](#hidabsfuzz) | Fuzzy values of the absolute coordinates.| -| [hidAbsFlat](#hidabsflat) | Fixed values of the absolute coordinates.| - - -## Member Variable Description - - -### hidEventTypes - - -``` -struct Hid_EventTypeArray Hid_EventProperties::hidEventTypes -``` - -**Description** - -Array of event types. - - -### hidKeys - - -``` -struct Hid_KeyCodeArray Hid_EventProperties::hidKeys -``` - -**Description** - -Array of key codes. - - -### hidAbs - - -``` -struct Hid_AbsAxesArray Hid_EventProperties::hidAbs -``` - -**Description** - -Array of absolute coordinates. - - -### hidRelBits - - -``` -struct Hid_RelAxesArray Hid_EventProperties::hidRelBits -``` - -**Description** - -Array of relative coordinates. - - -### hidMiscellaneous - - -``` -struct Hid_MscEventArray Hid_EventProperties::hidMiscellaneous -``` - -**Description** - -Array of miscellaneous events. - - -### hidAbsMax - - -``` -int32_t Hid_EventProperties::hidAbsMax[64] -``` - -**Description** - -Maximum values of the absolute coordinates. - - -### hidAbsMin - - -``` -int32_t Hid_EventProperties::hidAbsMin[64] -``` - -**Description** - -Minimum values of the absolute coordinates. - - -### hidAbsFuzz - - -``` -int32_t Hid_EventProperties::hidAbsFuzz[64] -``` - -**Description** - -Fuzzy values of the absolute coordinates. - - -### hidAbsFlat - - -``` -int32_t Hid_EventProperties::hidAbsFlat[64] -``` - -**Description** - -Fixed values of the absolute coordinates. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_hid___event_type_array.md b/en/application-dev/reference/apis-driverdevelopment-kit/_hid___event_type_array.md deleted file mode 100644 index 7f864636c7c..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_hid___event_type_array.md +++ /dev/null @@ -1,52 +0,0 @@ -# Hid_EventTypeArray - - -## Overview - -Defines an array of event types. - -**Since** - -11 - -**Related module** - -[HID DDK](_hid_ddk.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| [hidEventType](#hideventtype) | Array of event types.| -| [length](#length) | Length of the array.| - - -## Member Variable Description - - -### hidEventType - - -``` -Hid_EventType Hid_EventTypeArray::*hidEventType -``` - -**Description** - -Array of event types. - - -### length - - -``` -uint16_t Hid_EventTypeArray::length -``` - -**Description** - -Length of the array. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_hid___key_code_array.md b/en/application-dev/reference/apis-driverdevelopment-kit/_hid___key_code_array.md deleted file mode 100644 index 957b3055a18..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_hid___key_code_array.md +++ /dev/null @@ -1,52 +0,0 @@ -# Hid_KeyCodeArray - - -## Overview - -Defines an array of key codes. - -**Since** - -11 - -**Related module** - -[HID DDK](_hid_ddk.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| [hidKeyCode](#hidkeycode) | Array of key codes.| -| [length](#length) | Length of the array.| - - -## Member Variable Description - - -### hidKeyCode - - -``` -Hid_KeyCode Hid_KeyCodeArray::*hidKeyCode -``` - -**Description** - -Array of key codes. - - -### length - - -``` -uint16_t Hid_KeyCodeArray::length -``` - -**Description** - -Length of the array. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_hid___msc_event_array.md b/en/application-dev/reference/apis-driverdevelopment-kit/_hid___msc_event_array.md deleted file mode 100644 index 1c47513671c..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_hid___msc_event_array.md +++ /dev/null @@ -1,52 +0,0 @@ -# Hid_MscEventArray - - -## Overview - -Defines an array of miscellaneous events. - -**Since** - -11 - -**Related module** - -[HDI DDK](_hid_ddk.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| [hidMscEvent](#hidmscevent) | Array of miscellaneous events.| -| [length](#length) | Length of the array.| - - -## Member Variable Description - - -### hidMscEvent - - -``` -Hid_MscEvent Hid_MscEventArray::*hidMscEvent -``` - -**Description** - -Array of miscellaneous events. - - -### length - - -``` -uint16_t Hid_MscEventArray::length -``` - -**Description** - -Length of the array. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_hid___raw_dev_info.md b/en/application-dev/reference/apis-driverdevelopment-kit/_hid___raw_dev_info.md deleted file mode 100644 index 75b98c90793..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_hid___raw_dev_info.md +++ /dev/null @@ -1,24 +0,0 @@ -# Hid_RawDevInfo - - -## Overview - -Defines the raw device information. - -**Since**: 18 - -**Related module**: [HID DDK](_hid_ddk.md) - -**Header file**: [hid_ddk_types.h](hid__ddk__types_8h.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| uint32_t [busType](_hid_ddk.md#bustype) | Bus type.| -| uint16_t [vendor](_hid_ddk.md#vendor) | Provider ID.| -| uint16_t [product](_hid_ddk.md#product) | Product ID.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_hid___rel_axes_array.md b/en/application-dev/reference/apis-driverdevelopment-kit/_hid___rel_axes_array.md deleted file mode 100644 index 35fae979a89..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_hid___rel_axes_array.md +++ /dev/null @@ -1,52 +0,0 @@ -# Hid_RelAxesArray - - -## Overview - -Defines an array of relative coordinates. - -**Since** - -11 - -**Related module** - -[HID DDK](_hid_ddk.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| [hidRelAxes](#hidrelaxes) | Array of relative coordinates.| -| [length](#length) | Length of the array.| - - -## Member Variable Description - - -### hidrelaxes - - -``` -Hid_RelAxes Hid_RelAxesArray::*hidRelAxes -``` - -**Description** - -Array of relative coordinates. - - -### length - - -``` -uint16_t Hid_RelAxesArray::length -``` - -**Description** - -Length of the array. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_hid_ddk.md b/en/application-dev/reference/apis-driverdevelopment-kit/_hid_ddk.md deleted file mode 100644 index 5a68af5b45d..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_hid_ddk.md +++ /dev/null @@ -1,1676 +0,0 @@ -# HID DDK - - -## Overview - -Provides HID driver development kit (DDK) functions, including those for creating a device, sending events to a device, and destroying a device. - -**System capability**: SystemCapability.Driver.HID.Extension - -**Since**: 11 - - -## Summary - - -### Files - -| Name| Description| -| -------- | -------- | -| [hid_ddk_api.h](hid__ddk__api_8h.md) | Declares the HID DDK functions for accessing an input device from the host.
File to include: <hid/hid_ddk_api.h>
Library: libhid.z.so| -| [hid_ddk_types.h](hid__ddk__types_8h.md) | Defines the enum variables and structs used in the HID DDK.
File to include: <hid/hid_ddk_types.h>
Library: libhid.z.so| - - -### Structs - -| Name| Description| -| -------- | -------- | -| struct  [Hid_EmitItem](_hid___emit_item.md) | Defines event information.| -| struct  [Hid_Device](_hid___device.md) | Defines basic device information.| -| struct  [Hid_EventTypeArray](_hid___event_type_array.md) | Defines an array of event types.| -| struct  [Hid_KeyCodeArray](_hid___key_code_array.md) | Defines an array of key codes.| -| struct  [Hid_AbsAxesArray](_hid___abs_axes_array.md) | Defines an array of absolute coordinates.| -| struct  [Hid_RelAxesArray](_hid___rel_axes_array.md) | Defines an array of relative coordinates.| -| struct  [Hid_MscEventArray](_hid___msc_event_array.md) | Defines an array of miscellaneous events.| -| struct  [Hid_EventProperties](_hid___event_properties.md) | Defines the event properties of a device.| -| struct  [Hid_RawDevInfo](_hid___raw_dev_info.md) | Defines the raw device information.| - - -### Macros - -| Name| Description| -| -------- | -------- | -| [HID_MAX_REPORT_BUFFER_SIZE](#hid_max_report_buffer_size)   (16 \* 1024 - 1) | Defines the maximum size of the report buffer.| - - -### Types - -| Name| Description| -| -------- | -------- | -| typedef struct [Hid_EmitItem](_hid___emit_item.md) [Hid_EmitItem](#hid_emititem) | Defines event information.| -| typedef struct [Hid_Device](_hid___device.md) [Hid_Device](#hid_device) | Defines basic device information.| -| typedef struct [Hid_EventTypeArray](_hid___event_type_array.md) [Hid_EventTypeArray](#hid_eventtypearray) | Defines an array of event types.| -| typedef struct [Hid_KeyCodeArray](_hid___key_code_array.md) [Hid_KeyCodeArray](#hid_keycodearray) | Defines an array of key codes.| -| typedef struct [Hid_AbsAxesArray](_hid___abs_axes_array.md) [Hid_AbsAxesArray](#hid_absaxesarray) | Defines an array of absolute coordinates.| -| typedef struct [Hid_RelAxesArray](_hid___rel_axes_array.md) [Hid_RelAxesArray](#hid_relaxesarray) | Defines an array of relative coordinates.| -| typedef struct [Hid_MscEventArray](_hid___msc_event_array.md) [Hid_MscEventArray](#hid_msceventarray) | Defines an array of miscellaneous events.| -| typedef struct [Hid_EventProperties](_hid___event_properties.md) [Hid_EventProperties](#hid_eventproperties) | Defines the event properties of a device.| -| typedef struct [Hid_DeviceHandle](#hid_devicehandle) [Hid_DeviceHandle](#hid_devicehandle) | Defines the opaque USB HID device structure.| -| typedef struct [Hid_RawDevInfo](_hid___raw_dev_info.md) [Hid_RawDevInfo](#hid_rawdevinfo) | Defines the raw device information.| - - -### Enums - -| Name| Description| -| -------- | -------- | -| [Hid_DeviceProp](#hid_deviceprop) {
HID_PROP_POINTER = 0x00, HID_PROP_DIRECT = 0x01, HID_PROP_BUTTON_PAD = 0x02, HID_PROP_SEMI_MT = 0x03, HID_PROP_TOP_BUTTON_PAD = 0x04, HID_PROP_POINTING_STICK = 0x05, HID_PROP_ACCELEROMETER = 0x06
} | Enumerates the properties of input devices.| -| [Hid_EventType](#hid_eventtype) {
HID_EV_SYN = 0x00, HID_EV_KEY = 0x01, HID_EV_REL = 0x02, HID_EV_ABS = 0x03, HID_EV_MSC = 0x04
} | Enumerates the event types.| -| [Hid_SynEvent](#hid_synevent) { HID_SYN_REPORT = 0, HID_SYN_CONFIG = 1, HID_SYN_MT_REPORT = 2, HID_SYN_DROPPED = 3 } | Enumerates sync events.| -| [Hid_KeyCode](#hid_keycode) {
HID_KEY_A = 30, HID_KEY_B = 48, HID_KEY_C = 46, HID_KEY_D = 32, HID_KEY_E = 18, HID_KEY_F = 33, HID_KEY_G = 34, HID_KEY_H = 35, HID_KEY_I = 23, HID_KEY_J = 36, HID_KEY_K = 37, HID_KEY_L = 38, HID_KEY_M = 50, HID_KEY_N = 49, HID_KEY_O = 24, HID_KEY_P = 25, HID_KEY_Q = 16, HID_KEY_R = 19, HID_KEY_S = 31, HID_KEY_T = 20, HID_KEY_U = 22, HID_KEY_V = 47, HID_KEY_W = 17, HID_KEY_X = 45, HID_KEY_Y = 21, HID_KEY_Z = 44, HID_KEY_ESC = 1, HID_KEY_0 = 11, HID_KEY_1 = 2, HID_KEY_2 = 3, HID_KEY_3 = 4, HID_KEY_4 = 5, HID_KEY_5 = 6, HID_KEY_6 = 7, HID_KEY_7 = 8, HID_KEY_8 = 9, HID_KEY_9 = 10, HID_KEY_GRAVE = 41, HID_KEY_MINUS = 12, HID_KEY_EQUALS = 13, HID_KEY_BACKSPACE = 14, HID_KEY_LEFT_BRACKET = 26, HID_KEY_RIGHT_BRACKET = 27, HID_KEY_ENTER = 28, HID_KEY_LEFT_SHIFT = 42, HID_KEY_BACKSLASH = 43, HID_KEY_SEMICOLON = 39, HID_KEY_APOSTROPHE = 40, HID_KEY_SPACE = 57, HID_KEY_SLASH = 53, HID_KEY_COMMA = 51, HID_KEY_PERIOD = 52, HID_KEY_RIGHT_SHIFT = 54, HID_KEY_NUMPAD_0 = 82, HID_KEY_NUMPAD_1 = 79, HID_KEY_NUMPAD_2 = 80, HID_KEY_NUMPAD_3 = 81, HID_KEY_NUMPAD_4 = 75, HID_KEY_NUMPAD_5 = 76, HID_KEY_NUMPAD_6 = 77, HID_KEY_NUMPAD_7 = 71, HID_KEY_NUMPAD_8 = 72, HID_KEY_NUMPAD_9 = 73, HID_KEY_NUMPAD_DIVIDE = 70, HID_KEY_NUMPAD_MULTIPLY = 55, HID_KEY_NUMPAD_SUBTRACT = 74, HID_KEY_NUMPAD_ADD = 78, HID_KEY_NUMPAD_DOT = 83, HID_KEY_SYSRQ = 99, HID_KEY_DELETE = 111, HID_KEY_MUTE = 113, HID_KEY_VOLUME_DOWN = 114, HID_KEY_VOLUME_UP = 115, HID_KEY_BRIGHTNESS_DOWN = 224, HID_KEY_BRIGHTNESS_UP = 225, HID_BTN_0 = 0x100, HID_BTN_1 = 0x101, HID_BTN_2 = 0x102, HID_BTN_3 = 0x103, HID_BTN_4 = 0x104, HID_BTN_5 = 0x105, HID_BTN_6 = 0x106, HID_BTN_7 = 0x107, HID_BTN_8 = 0x108, HID_BTN_9 = 0x109, HID_BTN_LEFT = 0x110, HID_BTN_RIGHT = 0x111, HID_BTN_MIDDLE = 0x112, HID_BTN_SIDE = 0x113, HID_BTN_EXTRA = 0x114, HID_BTN_FORWARD = 0x115, HID_BTN_BACKWARD = 0x116, HID_BTN_TASK = 0x117, HID_BTN_TOOL_PEN = 0x140, HID_BTN_TOOL_RUBBER = 0x141, HID_BTN_TOOL_BRUSH = 0x142, HID_BTN_TOOL_PENCIL = 0x143, HID_BTN_TOOL_AIRBRUSH = 0x144, HID_BTN_TOOL_FINGER = 0x145, HID_BTN_TOOL_MOUSE = 0x146, HID_BTN_TOOL_LENS = 0x147, HID_BTN_TOOL_QUINT_TAP = 0x148, HID_BTN_STYLUS3 = 0x149, HID_BTN_TOUCH = 0x14a, HID_BTN_STYLUS = 0x14b, HID_BTN_STYLUS2 = 0x14c, HID_BTN_TOOL_DOUBLE_TAP = 0x14d, HID_BTN_TOOL_TRIPLE_TAP = 0x14e, HID_BTN_TOOL_QUAD_TAP = 0x14f, HID_BTN_WHEEL = 0x150
} | Enumerates the key codes.| -| [Hid_AbsAxes](#hid_absaxes) {
HID_ABS_X = 0x00, HID_ABS_Y = 0x01, HID_ABS_Z = 0x02, HID_ABS_RX = 0x03, HID_ABS_RY = 0x04, HID_ABS_RZ = 0x05, HID_ABS_THROTTLE = 0x06, HID_ABS_RUDDER = 0x07, HID_ABS_WHEEL = 0x08, HID_ABS_GAS = 0x09, HID_ABS_BRAKE = 0x0a, HID_ABS_HAT0X = 0x10, HID_ABS_HAT0Y = 0x11, HID_ABS_HAT1X = 0x12, HID_ABS_HAT1Y = 0x13, HID_ABS_HAT2X = 0x14, HID_ABS_HAT2Y = 0x15, HID_ABS_HAT3X = 0x16, HID_ABS_HAT3Y = 0x17, HID_ABS_PRESSURE = 0x18, HID_ABS_DISTANCE = 0x19, HID_ABS_TILT_X = 0x1a, HID_ABS_TILT_Y = 0x1b, HID_ABS_TOOL_WIDTH = 0x1c, HID_ABS_VOLUME = 0x20, HID_ABS_MISC = 0x28
} | Enumerates the absolute coordinates.| -| [Hid_RelAxes](#hid_relaxes) {
HID_REL_X = 0x00, HID_REL_Y = 0x01, HID_REL_Z = 0x02, HID_REL_RX = 0x03, HID_REL_RY = 0x04, HID_REL_RZ = 0x05, HID_REL_HWHEEL = 0x06, HID_REL_DIAL = 0x07, HID_REL_WHEEL = 0x08, HID_REL_MISC = 0x09, HID_REL_RESERVED = 0x0a, HID_REL_WHEEL_HI_RES = 0x0b, HID_REL_HWHEEL_HI_RES = 0x0c
} | Enumerates the relative coordinates.| -| [Hid_MscEvent](#hid_mscevent) {
HID_MSC_SERIAL = 0x00, HID_MSC_PULSE_LED = 0x01, HID_MSC_GESTURE = 0x02, HID_MSC_RAW = 0x03, HID_MSC_SCAN = 0x04, HID_MSC_TIMESTAMP = 0x05
} | Enumerates miscellaneous input events.| -| [Hid_DdkErrCode](#hid_ddkerrcode) {
HID_DDK_SUCCESS = 0, HID_DDK_NO_PERM = 201, HID_DDK_INVALID_PARAMETER = 401, HID_DDK_FAILURE = 27300001, HID_DDK_NULL_PTR = 27300002, HID_DDK_INVALID_OPERATION = 27300003, HID_DDK_TIMEOUT = 27300004, HID_DDK_INIT_ERROR = 27300005, HID_DDK_SERVICE_ERROR = 27300006, HID_DDK_MEMORY_ERROR = 27300007, HID_DDK_IO_ERROR = 27300008, HID_DDK_DEVICE_NOT_FOUND = 27300009
} | Enumerates the HID DDK error codes.| -| [Hid_ReportType](#hid_reporttype) { HID_INPUT_REPORT = 0, HID_OUTPUT_REPORT = 1, HID_FEATURE_REPORT = 2 } | Defines the report (data packets exchanged between the HID device and the host) type.| - - -### Functions - -| Name| Description| -| -------- | -------- | -| int32_t [OH_Hid_CreateDevice](#oh_hid_createdevice) ([Hid_Device](_hid___device.md) \*hidDevice, [Hid_EventProperties](_hid___event_properties.md) \*hidEventProperties) | Creates a device.| -| int32_t [OH_Hid_EmitEvent](#oh_hid_emitevent) (int32_t deviceId, const [Hid_EmitItem](_hid___emit_item.md) items[], uint16_t length) | Sends an event list to a device.| -| int32_t [OH_Hid_DestroyDevice](#oh_hid_destroydevice) (int32_t deviceId) | Destroys a device.| -| int32_t [OH_Hid_Init](#oh_hid_init) (void) | Initializes an HID DDK.| -| int32_t [OH_Hid_Release](#oh_hid_release) (void) | Releases an HID DDK.| -| int32_t [OH_Hid_Open](#oh_hid_open) (uint64_t deviceId, uint8_t interfaceIndex, [Hid_DeviceHandle](#hid_devicehandle) \*\*dev) | Opens the device specified by **deviceId** and **interfaceIndex**.| -| int32_t [OH_Hid_Close](#oh_hid_close) ([Hid_DeviceHandle](#hid_devicehandle) \*\*dev) | Closes an HID device.| -| int32_t [OH_Hid_Write](#oh_hid_write) ([Hid_DeviceHandle](#hid_devicehandle) \*dev, uint8_t \*data, uint32_t length, uint32_t \*bytesWritten) | Writes reports to an HID device.| -| int32_t [OH_Hid_ReadTimeout](#oh_hid_readtimeout) ([Hid_DeviceHandle](#hid_devicehandle) \*dev, uint8_t \*data, uint32_t bufSize, int timeout, uint32_t \*bytesRead) | Reads reports from the HID device within the specified timeout interval.| -| int32_t [OH_Hid_Read](#oh_hid_read) ([Hid_DeviceHandle](#hid_devicehandle) \*dev, uint8_t \*data, uint32_t bufSize, uint32_t \*bytesRead) | Reads reports from the HID device. The blocking mode (that is, blocking remains active until data can be read) is used by default. You can call [OH_Hid_SetNonBlocking](#oh_hid_setnonblocking) to change the mode.| -| int32_t [OH_Hid_SetNonBlocking](#oh_hid_setnonblocking) ([Hid_DeviceHandle](#hid_devicehandle) \*dev, int nonBlock) | Sets the device read mode to non-blocking mode.| -| int32_t [OH_Hid_GetRawInfo](#oh_hid_getrawinfo) ([Hid_DeviceHandle](#hid_devicehandle) \*dev, [Hid_RawDevInfo](_hid___raw_dev_info.md) \*rawDevInfo) | Obtains the original device information.| -| int32_t [OH_Hid_GetRawName](#oh_hid_getrawname) ([Hid_DeviceHandle](#hid_devicehandle) \*dev, char \*data, uint32_t bufSize) | Obtains the original device name.| -| int32_t [OH_Hid_GetPhysicalAddress](#oh_hid_getphysicaladdress) ([Hid_DeviceHandle](#hid_devicehandle) \*dev, char \*data, uint32_t bufSize) | Obtains the physical address of the HID device.| -| int32_t [OH_Hid_GetRawUniqueId](#oh_hid_getrawuniqueid) ([Hid_DeviceHandle](#hid_devicehandle) \*dev, uint8_t \*data, uint32_t bufSize) | Obtains the original unique identifier of a device.| -| int32_t [OH_Hid_SendReport](#oh_hid_sendreport) ([Hid_DeviceHandle](#hid_devicehandle) \*dev, [Hid_ReportType](#hid_reporttype) reportType, const uint8_t \*data, uint32_t length) | Sends reports to the HID device.| -| int32_t [OH_Hid_GetReport](#oh_hid_getreport) ([Hid_DeviceHandle](#hid_devicehandle) \*dev, [Hid_ReportType](#hid_reporttype) reportType, uint8_t \*data, uint32_t bufSize) | Obtains reports from the HID device.| -| int32_t [OH_Hid_GetReportDescriptor](#oh_hid_getreportdescriptor) ([Hid_DeviceHandle](#hid_devicehandle) \*dev, uint8_t \*buf, uint32_t bufSize, uint32_t \*bytesRead) | Obtains the report descriptor of the HID device.| - - -### Variables - -| Name| Description| -| -------- | -------- | -| uint16_t [Hid_EmitItem::type](#type) | Enumerates the event types.| -| uint16_t [Hid_EmitItem::code](#code) | Event code.| -| uint32_t [Hid_EmitItem::value](#value) | Event value.| -| const char \* [Hid_Device::deviceName](#devicename) | Device name.| -| uint16_t [Hid_Device::vendorId](#vendorid) | Vendor ID.| -| uint16_t [Hid_Device::productId](#productid) | Product ID.| -| uint16_t [Hid_Device::version](#version) | Version.| -| uint16_t [Hid_Device::bustype](#bustype) | Bus type.| -| [Hid_DeviceProp](#hid_deviceprop) \* [Hid_Device::properties](#properties) | Device properties.| -| uint16_t [Hid_Device::propLength](#proplength) | Number of device properties.| -| [Hid_EventType](#hid_eventtype) \* [Hid_EventTypeArray::hidEventType](#hideventtype) | Event type.| -| uint16_t [Hid_EventTypeArray::length](#length-15) | Size of the array.| -| [Hid_KeyCode](#hid_keycode) \* [Hid_KeyCodeArray::hidKeyCode](#hidkeycode) | Enumerates the key codes.| -| uint16_t [Hid_KeyCodeArray::length](#length-25) | Size of the array.| -| [Hid_AbsAxes](#hid_absaxes) \* [Hid_AbsAxesArray::hidAbsAxes](#hidabsaxes) | Array of absolute coordinates.| -| uint16_t [Hid_AbsAxesArray::length](#length-35) | Size of the array.| -| [Hid_RelAxes](#hid_relaxes) \* [Hid_RelAxesArray::hidRelAxes](#hidrelaxes) | Relative coordinate.| -| uint16_t [Hid_RelAxesArray::length](#length-45) | Size of the array.| -| [Hid_MscEvent](#hid_mscevent) \* [Hid_MscEventArray::hidMscEvent](#hidmscevent) | Miscellaneous event.| -| uint16_t [Hid_MscEventArray::length](#length-55) | Size of the array.| -| struct [Hid_EventTypeArray](_hid___event_type_array.md)[Hid_EventProperties::hidEventTypes](#hideventtypes) | Array of event types.| -| struct [Hid_KeyCodeArray](_hid___key_code_array.md)[Hid_EventProperties::hidKeys](#hidkeys) | Array of key codes.| -| struct [Hid_AbsAxesArray](_hid___abs_axes_array.md)[Hid_EventProperties::hidAbs](#hidabs) | Array of absolute coordinates.| -| struct [Hid_RelAxesArray](_hid___rel_axes_array.md)[Hid_EventProperties::hidRelBits](#hidrelbits) | Array of relative coordinates.| -| struct [Hid_MscEventArray](_hid___msc_event_array.md)[Hid_EventProperties::hidMiscellaneous](#hidmiscellaneous) | Array of miscellaneous events.| -| int32_t [Hid_EventProperties::hidAbsMax](#hidabsmax) [64] | Maximum values of the absolute coordinates.| -| int32_t [Hid_EventProperties::hidAbsMin](#hidabsmin) [64] | Minimum values of the absolute coordinates.| -| int32_t [Hid_EventProperties::hidAbsFuzz](#hidabsfuzz) [64] | Fuzzy values of the absolute coordinates.| -| int32_t [Hid_EventProperties::hidAbsFlat](#hidabsflat) [64] | Fixed values of the absolute coordinates.| -| uint32_t [Hid_RawDevInfo::busType](#bustype) | Bus type.| -| uint16_t [Hid_RawDevInfo::vendor](#vendor) | Provider ID.| -| uint16_t [Hid_RawDevInfo::product](#product) | Product ID.| - - -## Macro Description - - -### HID_MAX_REPORT_BUFFER_SIZE - -``` -#define HID_MAX_REPORT_BUFFER_SIZE (16 * 1024 - 1) -``` - -**Description** - -Defines the maximum size of the report buffer. - -**Since**: 18 - - -## Type Description - - -### Hid_AbsAxesArray - -``` -typedef struct Hid_AbsAxesArray Hid_AbsAxesArray -``` - -**Description** - -Defines a struct for an array of absolute coordinates. - -**Since**: 11 - - -### Hid_Device - -``` -typedef struct Hid_Device Hid_Device -``` - -**Description** - -Defines a struct for basic device information. - -**Since**: 11 - - -### Hid_DeviceHandle - -``` -typedef struct Hid_DeviceHandle Hid_DeviceHandle -``` - -**Description** - -Defines the opaque USB HID device structure. - -**Since**: 18 - - -### Hid_EmitItem - -``` -typedef struct Hid_EmitItem Hid_EmitItem -``` - -**Description** - -Defines a struct for event information. - -**Since**: 11 - - -### Hid_EventProperties - -``` -typedef struct Hid_EventProperties Hid_EventProperties -``` - -**Description** - -Defines a struct for the event properties of a device. - -**Since**: 11 - - -### Hid_EventTypeArray - -``` -typedef struct Hid_EventTypeArray Hid_EventTypeArray -``` - -**Description** - -Defines a struct for an array of event types. - -**Since**: 11 - - -### Hid_KeyCodeArray - -``` -typedef struct Hid_KeyCodeArray Hid_KeyCodeArray -``` - -**Description** - -Defines a struct for an array of key codes. - -**Since**: 11 - - -### Hid_MscEventArray - -``` -typedef struct Hid_MscEventArray Hid_MscEventArray -``` - -**Description** - -Defines a struct for an array of miscellaneous events. - -**Since**: 11 - - -### Hid_RawDevInfo - -``` -typedef struct Hid_RawDevInfo Hid_RawDevInfo -``` - -**Description** - -Defines the raw device information. - -**Since**: 18 - - -### Hid_RelAxesArray - -``` -typedef struct Hid_RelAxesArray Hid_RelAxesArray -``` - -**Description** - -Defines a struct for an array of relative coordinates. - -**Since**: 11 - - -## Enum Description - - -### Hid_AbsAxes - -``` -enum Hid_AbsAxes -``` - -**Description** - -Enumerates the absolute coordinates. - -**Since**: 11 - -| Value| Description| -| -------- | -------- | -| HID_ABS_X | X axis.| -| HID_ABS_Y | Y axis.| -| HID_ABS_Z | Z axis.| -| HID_ABS_RX | X axis of the right analog stick.| -| HID_ABS_RY | Y axis of the right analog stick.| -| HID_ABS_RZ | Z axis of the right analog stick.| -| HID_ABS_THROTTLE | Throttle.| -| HID_ABS_RUDDER | Rudder.| -| HID_ABS_WHEEL | Scroll wheel.| -| HID_ABS_GAS | Gas.| -| HID_ABS_BRAKE | Brake.| -| HID_ABS_HAT0X | HAT0X.| -| HID_ABS_HAT0Y | HAT0Y.| -| HID_ABS_HAT1X | HAT1X.| -| HID_ABS_HAT1Y | HAT1Y.| -| HID_ABS_HAT2X | HAT2X.| -| HID_ABS_HAT2Y | HAT2Y.| -| HID_ABS_HAT3X | HAT3X.| -| HID_ABS_HAT3Y | HAT3Y.| -| HID_ABS_PRESSURE | Pressure.| -| HID_ABS_DISTANCE | Distance.| -| HID_ABS_TILT_X | Tilt of X axis.| -| HID_ABS_TILT_Y | Tilt of Y axis.| -| HID_ABS_TOOL_WIDTH | Width of the touch tool.| -| HID_ABS_VOLUME | Volume.| -| HID_ABS_MISC | Others.| - - -### Hid_DdkErrCode - -``` -enum Hid_DdkErrCode -``` - -**Description** - -Enumerates the HID DDK error codes. - -**Since**: 11 - -| Value| Description| -| -------- | -------- | -| HID_DDK_SUCCESS | Operation succeeded.| -| HID_DDK_NO_PERM | No permission. The value is changed from **-6** to **201** since API version 16.| -| HID_DDK_INVALID_PARAMETER | Invalid parameter. The value is changed from **-2** to **401** since API version 16.| -| HID_DDK_FAILURE | Operation failed. The value is changed from **-1** to **27300001** since API version 16.| -| HID_DDK_NULL_PTR | Null pointer. The value is changed from **-4** to **27300002** since API version 16.| -| HID_DDK_INVALID_OPERATION | Invalid operation. The value is changed from **-3** to **27300003** since API version 16.| -| HID_DDK_TIMEOUT | Timeout. The value is changed from **-5** to **27300004** since API version 16.| -| HID_DDK_INIT_ERROR | DDK initialization error. This enum is supported since API version 16.| -| HID_DDK_SERVICE_ERROR | Service communication error. This enum is supported since API version 16.| -| HID_DDK_MEMORY_ERROR | Memory-related errors, such as memory data copy failure and memory allocation failure. This enum is supported since API version 16.| -| HID_DDK_IO_ERROR | I/O operation failure. This enum is supported since API version 16.| -| HID_DDK_DEVICE_NOT_FOUND | Device not found. This enum is supported since API version 16.| - - -### Hid_DeviceProp - -``` -enum Hid_DeviceProp -``` - -**Description** - -Enumerates the properties of input devices. - -**Since**: 11 - -| Value| Description| -| -------- | -------- | -| HID_PROP_POINTER | Pointer device.| -| HID_PROP_DIRECT | Direct input device.| -| HID_PROP_BUTTON_PAD | Touch device with bottom keys.| -| HID_PROP_SEMI_MT | Full multi-touch device.| -| HID_PROP_TOP_BUTTON_PAD | Touch device with top soft keys.| -| HID_PROP_POINTING_STICK | Pointing stick.| -| HID_PROP_ACCELEROMETER | Accelerometer.| - - -### Hid_EventType - -``` -enum Hid_EventType -``` - -**Description** - -Enumerates the event types. - -**Since**: 11 - -| Value| Description| -| -------- | -------- | -| HID_EV_SYN | Sync event.| -| HID_EV_KEY | Key event.| -| HID_EV_REL | Relative coordinate event.| -| HID_EV_ABS | Absolute coordinate event.| -| HID_EV_MSC | Miscellaneous event.| - - -### Hid_KeyCode - -``` -enum Hid_KeyCode -``` - -**Description** - -Enumerates the key codes. - -**Since**: 11 - -| Value| Description| -| -------- | -------- | -| HID_KEY_A | Key A| -| HID_KEY_B | Key B| -| HID_KEY_C | Key C| -| HID_KEY_D | Key D| -| HID_KEY_E | Key E| -| HID_KEY_F | Key F| -| HID_KEY_G | Key G| -| HID_KEY_H | Key H| -| HID_KEY_I | Key I| -| HID_KEY_J | Key J| -| HID_KEY_K | Key K| -| HID_KEY_L | Key L| -| HID_KEY_M | Key M| -| HID_KEY_N | Key N| -| HID_KEY_O | Key O| -| HID_KEY_P | Key P| -| HID_KEY_Q | Key Q| -| HID_KEY_R | Key R| -| HID_KEY_S | Key S| -| HID_KEY_T | Key T| -| HID_KEY_U | Key U| -| HID_KEY_V | Key V| -| HID_KEY_W | Key W| -| HID_KEY_X | Key X| -| HID_KEY_Y | Key Y| -| HID_KEY_Z | Key Z| -| HID_KEY_ESC | Key Esc| -| HID_KEY_0 | Key 0| -| HID_KEY_1 | Key 1| -| HID_KEY_2 | Key 2| -| HID_KEY_3 | Key 3| -| HID_KEY_4 | Key 4| -| HID_KEY_5 | Key 5| -| HID_KEY_6 | Key 6| -| HID_KEY_7 | Key 7| -| HID_KEY_8 | Key 8| -| HID_KEY_9 | Key 9| -| HID_KEY_GRAVE | Key `| -| HID_KEY_MINUS | Key -| -| HID_KEY_EQUALS | Key =| -| HID_KEY_BACKSPACE | key Backspace| -| HID_KEY_LEFT_BRACKET | Key [| -| HID_KEY_RIGHT_BRACKET | Key ]| -| HID_KEY_ENTER | Key Enter| -| HID_KEY_LEFT_SHIFT | Left Shift| -| HID_KEY_BACKSLASH | Key \| -| HID_KEY_SEMICOLON | Key ;| -| HID_KEY_APOSTROPHE | Key '| -| HID_KEY_SPACE | Key Space| -| HID_KEY_SLASH | Key /| -| HID_KEY_COMMA | Key ,| -| HID_KEY_PERIOD | Key .| -| HID_KEY_RIGHT_SHIFT | Right Shift| -| HID_KEY_NUMPAD_0 | Numeral 0 on the numeric keypad| -| HID_KEY_NUMPAD_1 | Numeral 1 on the numeric keypad| -| HID_KEY_NUMPAD_2 | Numeral 2 on the numeric keypad| -| HID_KEY_NUMPAD_3 | Numeral 3 on the numeric keypad| -| HID_KEY_NUMPAD_4 | Numeral 4 on the numeric keypad| -| HID_KEY_NUMPAD_5 | Numeral 5 on the numeric keypad| -| HID_KEY_NUMPAD_6 | Numeral 6 on the numeric keypad| -| HID_KEY_NUMPAD_7 | Numeral 7 on the numeric keypad| -| HID_KEY_NUMPAD_8 | Numeral 8 on the numeric keypad| -| HID_KEY_NUMPAD_9 | Numeral 9 on the numeric keypad| -| HID_KEY_NUMPAD_DIVIDE | Key / on the numeric keypad| -| HID_KEY_NUMPAD_MULTIPLY | Key * on the numeric keypad| -| HID_KEY_NUMPAD_SUBTRACT | Key - on the numeric keypad| -| HID_KEY_NUMPAD_ADD | Key + on the numeric keypad| -| HID_KEY_NUMPAD_DOT | Key . on the numeric keypad| -| HID_KEY_SYSRQ | SYSRQ key| -| HID_KEY_DELETE | Delete key| -| HID_KEY_MUTE | Mute key| -| HID_KEY_VOLUME_DOWN | Volume Down key| -| HID_KEY_VOLUME_UP | Volume Down key| -| HID_KEY_BRIGHTNESS_DOWN | Brightness Down key| -| HID_KEY_BRIGHTNESS_UP | Brightness Up key| -| HID_BTN_0 | Button 0| -| HID_BTN_1 | Button 1| -| HID_BTN_2 | Button 2| -| HID_BTN_3 | Button 3| -| HID_BTN_4 | Button 4| -| HID_BTN_5 | Button 5| -| HID_BTN_6 | Button 6| -| HID_BTN_7 | Button 7| -| HID_BTN_8 | Button 8| -| HID_BTN_9 | Button 9| -| HID_BTN_LEFT | Left mouse button| -| HID_BTN_RIGHT | Right mouse button| -| HID_BTN_MIDDLE | Middle mouse button| -| HID_BTN_SIDE | Side mouse button| -| HID_BTN_EXTRA | Extra mouse button| -| HID_BTN_FORWARD | Mouse forward button| -| HID_BTN_BACKWARD | Mouse backward button| -| HID_BTN_TASK | Mouse task button| -| HID_BTN_TOOL_PEN | Pen| -| HID_BTN_TOOL_RUBBER | Rubber| -| HID_BTN_TOOL_BRUSH | Brush| -| HID_BTN_TOOL_PENCIL | Pencil| -| HID_BTN_TOOL_AIRBRUSH | Air brush| -| HID_BTN_TOOL_FINGER | Finger| -| HID_BTN_TOOL_MOUSE | Mouse| -| HID_BTN_TOOL_LENS | Lens| -| HID_BTN_TOOL_QUINT_TAP | Five-finger touch| -| HID_BTN_STYLUS3 | Stylus 3| -| HID_BTN_TOUCH | Touch| -| HID_BTN_STYLUS | Stylus| -| HID_BTN_STYLUS2 | Stylus 2| -| HID_BTN_TOOL_DOUBLE_TAP | Two-finger touch| -| HID_BTN_TOOL_TRIPLE_TAP | Three-finger touch| -| HID_BTN_TOOL_QUAD_TAP | Four-finger touch| -| HID_BTN_WHEEL | Scroll wheel| - - -### Hid_MscEvent - -``` -enum Hid_MscEvent -``` - -**Description** - -Enumerates miscellaneous input events. - -**Since**: 11 - -| Value| Description| -| -------- | -------- | -| HID_MSC_SERIAL | Serial number| -| HID_MSC_PULSE_LED | Pulse| -| HID_MSC_GESTURE | Gesture| -| HID_MSC_RAW | Start event| -| HID_MSC_SCAN | Scan| -| HID_MSC_TIMESTAMP | Timestamp| - - -### Hid_RelAxes - -``` -enum Hid_RelAxes -``` - -**Description** - -Enumerates the relative coordinates. - -**Since**: 11 - -| Value| Description| -| -------- | -------- | -| HID_REL_X | X axis.| -| HID_REL_Y | Y axis.| -| HID_REL_Z | Z axis| -| HID_REL_RX | X axis of the right analog stick| -| HID_REL_RY | Y axis of the right analog stick| -| HID_REL_RZ | Z axis of the right analog stick| -| HID_REL_HWHEEL | Horizontal scroll wheel| -| HID_REL_DIAL | Scale| -| HID_REL_WHEEL | Scroll wheel| -| HID_REL_MISC | Others| -| HID_REL_RESERVED | Reserved| -| HID_REL_WHEEL_HI_RES | High-resolution scroll wheel| -| HID_REL_HWHEEL_HI_RES | High-resolution horizontal scroll wheel| - - -### Hid_ReportType - -``` -enum Hid_ReportType -``` - -**Description** - -Defines the report (data packets exchanged between the HID device and the host) type. - -**Since**: 18 - -| Value| Description| -| -------- | -------- | -| HID_INPUT_REPORT | Input report.| -| HID_OUTPUT_REPORT | Output report.| -| HID_FEATURE_REPORT | Feature report.| - - -### Hid_SynEvent - -``` -enum Hid_SynEvent -``` - -**Description** - -Enumerates sync events. - -**Since**: 11 - -| Value| Description| -| -------- | -------- | -| HID_SYN_REPORT | End of an event.| -| HID_SYN_CONFIG | Configuration synchronization.| -| HID_SYN_MT_REPORT | End of a multi-touch ABS data packet.| -| HID_SYN_DROPPED | Event discarded.| - - -## Function Description - - -### OH_Hid_Close() - -``` -int32_t OH_Hid_Close (Hid_DeviceHandle ** dev) -``` - -**Description** - -Closes an HID device. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device operation handle.| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_HID - -**Returns** - -- HID_DDK_SUCCESS: Operation succeeded. - -- HID_DDK_NO_PERM: Permission verification failed. - -- HID_DDK_INIT_ERROR DDK: DDK initialization error. - -- HID_DDK_SERVICE_ERROR: DDK service communication error. - -- HID_DDK_IO_ERROR: I/O operation error. - -- HID_DDK_INVALID_PARAMETER: Empty **dev**. - - -### OH_Hid_CreateDevice() - -``` -int32_t OH_Hid_CreateDevice (Hid_Device * hidDevice, Hid_EventProperties * hidEventProperties) -``` - -**Description** - -Creates a device. - -**Since**: 11 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| hidDevice | Pointer to the basic information about the device to create, including the device name, vendor ID, and product ID.| -| hidEventProperties | Pointer to the event properties related to the device to create, including the event type, key event properties, absolute coordinate event properties, and relative coordinate event properties.| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_HID - -**Returns** - -- deviceID (a non-negative number) if the API call is successful. - -- HID_DDK_NO_PERM: Permission verification failed. - -- HID_DDK_INVALID_OPERATION: hid_ddk service connection failed. - -- HID_DDK_INVALID_PARAMETER: Parameter verification failed. Possible causes: 1. The input **hidDevice** is a null pointer. 2. The input **hidEventProperties** is a null pointer. 3. The length of **properties** exceeds 7 characters. 4. The length of **hidEventTypes** exceeds 5 characters. 5. The length of **hidKeys** exceeds 100 characters. 6. The length of **hidAbs** exceeds 26 characters. 7. The length of **hidRelBits** exceeds 13 characters. 8. The length of **hidMiscellaneous** exceeds 6 characters. - -- HID_DDK_FAILURE: Number of devices exceeding the maximum value (200). - - -### OH_Hid_DestroyDevice() - -``` -int32_t OH_Hid_DestroyDevice (int32_t deviceId) -``` - -**Description** - -Destroys a device. - -**Since**: 11 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| deviceId | Device ID.| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_HID - -**Returns** - -- HID_DDK_SUCCESS: Operation succeeded. - -- HID_DDK_NO_PERM: Permission verification failed. - -- HID_DDK_INVALID_OPERATION: Invalid operation. The hid_ddk service connection fails or the caller is not the device creator. - -- HID_DDK_FAILURE: Device not exist. - - -### OH_Hid_EmitEvent() - -``` -int32_t OH_Hid_EmitEvent (int32_t deviceId, const Hid_EmitItem items[], uint16_t length) -``` - -**Description** - -Sends an event list to a device. - -**Since**: 11 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| deviceId | Device ID.| -| items | List of the events to send. The event information includes the event type (**Hid_EventType**), code (**Hid_SynEvent**, **Hid_KeyCode**, **HidBtnCode**, **Hid_AbsAxes**, **Hid_RelAxes**, or **Hid_MscEvent**), and value (depending on the actual device input).| -| length | Length of the event list (number of events to be sent at a time).| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_HID - -**Returns** - -- HID_DDK_SUCCESS: Operation succeeded. - -- HID_DDK_NO_PERM: Permission verification failed. - -- HID_DDK_INVALID_OPERATION: Invalid operation. The hid_ddk service connection fails or the caller is not the device creator. - -- HID_DDK_INVALID_PARAMETER: Parameter verification failed. Possible causes: 1. The device ID is smaller than 0. 2. The length of the input parameter exceeds 7 characters. 3. The input **items** is a null pointer. - -- HID_DDK_NULL_PTR: Null pointer. The input device is empty. - -- HID_DDK_FAILURE: Device not exist. - - -### OH_Hid_GetPhysicalAddress() - -``` -int32_t OH_Hid_GetPhysicalAddress (Hid_DeviceHandle * dev, char * data, uint32_t bufSize) -``` - -**Description** - -Obtains the physical address of the HID device. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device operation handle.| -| data | Buffer for storing the read data.| -| bufSize | Size of the buffer for storing read data. The value cannot exceed [HID_MAX_REPORT_BUFFER_SIZE](#hid_max_report_buffer_size).| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_HID - -**Returns** - -- HID_DDK_SUCCESS: Operation succeeded. - -- HID_DDK_NO_PERM: Permission verification failed. - -- HID_DDK_INVALID_PARAMETER: Parameter verification failed. Possible causes: 1. **dev** is empty. 2. **data** is empty. 3. The value of **bufSize** is **0**. 4. The value of **bufSize** exceeds [HID_MAX_REPORT_BUFFER_SIZE](#hid_max_report_buffer_size). HID_DDK_INIT_ERROR DDK: DDK initialization error. - -- HID_DDK_SERVICE_ERROR: DDK service communication error. - -- HID_DDK_MEMORY_ERROR: Memory data copy error. - -- HID_DDK_IO_ERROR: I/O operation error. - -- HID_DDK_INVALID_OPERATION: Invalid operation. - - -### OH_Hid_GetRawInfo() - -``` -int32_t OH_Hid_GetRawInfo (Hid_DeviceHandle * dev, Hid_RawDevInfo * rawDevInfo) -``` - -**Description** - -Obtains the original device information. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device operation handle.| -| rawDevInfo | Original device information, including the vendor ID, product ID, and bus type.| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_HID - -**Returns** - -- HID_DDK_SUCCESS: Operation succeeded. - -- HID_DDK_NO_PERM: Permission verification failed. - -- HID_DDK_INVALID_PARAMETER: Parameter verification failed. Possible causes: 1. **dev** is empty. 2. **rawDevInfo** is empty. - -- HID_DDK_INIT_ERROR DDK: DDK initialization error. - -- HID_DDK_SERVICE_ERROR: DDK service communication error. - -- HID_DDK_IO_ERROR: I/O operation error. - -- HID_DDK_INVALID_OPERATION: Invalid operation. - - -### OH_Hid_GetRawName() - -``` -int32_t OH_Hid_GetRawName (Hid_DeviceHandle * dev, char * data, uint32_t bufSize) -``` - -**Description** - -Obtains the original device name. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device operation handle.| -| data | Buffer for storing the read data.| -| bufSize | Size of the buffer for storing read data. The value cannot exceed [HID_MAX_REPORT_BUFFER_SIZE](#hid_max_report_buffer_size).| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_HID - -**Returns** - -- HID_DDK_SUCCESS: Operation succeeded. - -- HID_DDK_NO_PERM: Permission verification failed. - -- HID_DDK_INVALID_PARAMETER: Parameter verification failed. Possible causes: 1. **dev** is empty. 2. **data** is empty. 3. The value of **bufSize** is **0**. 4. The value of **bufSize** exceeds [HID_MAX_REPORT_BUFFER_SIZE](#hid_max_report_buffer_size). HID_DDK_INIT_ERROR DDK: DDK initialization error. - -- HID_DDK_SERVICE_ERROR: DDK service communication error. - -- HID_DDK_MEMORY_ERROR: Memory data copy error. - -- HID_DDK_IO_ERROR: I/O operation error. - -- HID_DDK_INVALID_OPERATION: Invalid operation. - - -### OH_Hid_GetRawUniqueId() - -``` -int32_t OH_Hid_GetRawUniqueId (Hid_DeviceHandle * dev, uint8_t * data, uint32_t bufSize) -``` - -**Description** - -Obtains the original unique identifier of a device. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device operation handle.| -| data | Buffer for storing the read data.| -| bufSize | Size of the buffer for storing read data. The value cannot exceed [HID_MAX_REPORT_BUFFER_SIZE](#hid_max_report_buffer_size).| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_HID - -**Returns** - -- HID_DDK_SUCCESS: Operation succeeded. - -- HID_DDK_NO_PERM: Permission verification failed. - -- HID_DDK_INVALID_PARAMETER: Parameter verification failed. Possible causes: 1. **dev** is empty. 2. **data** is empty. 3. The value of **bufSize** is **0**. 4. The value of **bufSize** exceeds [HID_MAX_REPORT_BUFFER_SIZE](#hid_max_report_buffer_size). HID_DDK_INIT_ERROR DDK: DDK initialization error. - -- HID_DDK_SERVICE_ERROR: DDK service communication error. - -- HID_DDK_MEMORY_ERROR: Memory data copy error. - -- HID_DDK_IO_ERROR: I/O operation error. - -- HID_DDK_INVALID_OPERATION: Invalid operation. - - -### OH_Hid_GetReport() - -``` -int32_t OH_Hid_GetReport (Hid_DeviceHandle * dev, Hid_ReportType reportType, uint8_t * data, uint32_t bufSize) -``` - -**Description** - -Obtains reports from the HID device. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device operation handle.| -| reportType | Report type.| -| data | Buffer for storing the read data.| -| bufSize | Size of the buffer for storing read data. The value cannot exceed [HID_MAX_REPORT_BUFFER_SIZE](#hid_max_report_buffer_size).| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_HID - -**Returns** - -- HID_DDK_SUCCESS: Operation succeeded. - -- HID_DDK_NO_PERM: Permission verification failed. - -- HID_DDK_INVALID_PARAMETER: Parameter verification failed. Possible causes: 1. **dev** is empty. 2. **data** is empty. 3. The value of **bufSize** is **0**. 4. The value of **bufSize** exceeds [HID_MAX_REPORT_BUFFER_SIZE](#hid_max_report_buffer_size). - -- HID_DDK_INIT_ERROR DDK: DDK initialization error. - -- HID_DDK_SERVICE_ERROR: DDK service communication error. - -- HID_DDK_MEMORY_ERROR: Memory data copy error. - -- HID_DDK_IO_ERROR: I/O operation error. - -- HID_DDK_INVALID_OPERATION: Invalid operation. - - -### OH_Hid_GetReportDescriptor() - -``` -int32_t OH_Hid_GetReportDescriptor (Hid_DeviceHandle * dev, uint8_t * buf, uint32_t bufSize, uint32_t * bytesRead) -``` - -**Description** - -Obtains the report descriptor of the HID device. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device operation handle.| -| buf | Buffer for storing descriptors.| -| bufSize | Size of the buffer, in bytes. The value cannot exceed [HID_MAX_REPORT_BUFFER_SIZE](#hid_max_report_buffer_size).| -| bytesRead | Number of bytes to read.| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_HID - -**Returns** - -- HID_DDK_SUCCESS: Operation succeeded. - -- HID_DDK_NO_PERM: Permission verification failed. - -- HID_DDK_INVALID_PARAMETER: Parameter verification failed. Possible causes: 1. **dev** is empty. 2. **buf** is empty. 3. The value of **bufSize** is **0**. 4. The value of **bufSize** exceeds that of **[HID_MAX_REPORT_BUFFER_SIZE](#hid_max_report_buffer_size)**. 5. **bytesRead** is empty. - -- HID_DDK_INIT_ERROR DDK: DDK initialization error. - -- HID_DDK_SERVICE_ERROR: DDK service communication error. - -- HID_DDK_MEMORY_ERROR: Memory data copy error. - -- HID_DDK_IO_ERROR: I/O operation error. - -- HID_DDK_INVALID_OPERATION: Invalid operation. - - -### OH_Hid_Init() - -``` -int32_t OH_Hid_Init (void) -``` - -**Description** - -Initializes an HID DDK. - -**Since**: 18 - -**Required Permissions** - -ohos.permission.ACCESS_DDK_HID - -**Returns** - -- HID_DDK_SUCCESS: Operation succeeded. - -- HID_DDK_NO_PERM: Permission verification failed. - -- HID_DDK_INIT_ERROR: DDK initialization error. - -- HID_DDK_SERVICE_ERROR: DDK service communication error. - - -### OH_Hid_Open() - -``` -int32_t OH_Hid_Open (uint64_t deviceId, uint8_t interfaceIndex, Hid_DeviceHandle ** dev) -``` - -**Description** - -Opens the device specified by **deviceId** and **interfaceIndex**. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| deviceId | Device ID.| -| interfaceIndex | Interface index for the API of the HID device.| -| dev | Device operation handle.| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_HID - -**Returns** - -- HID_DDK_SUCCESS: Operation succeeded. - -- HID_DDK_NO_PERM: Permission verification failed. - -- HID_DDK_INIT_ERROR DDK: DDK initialization error. - -- HID_DDK_SERVICE_ERROR: DDK service communication error. - -- HID_DDK_MEMORY_ERROR: dev memory application error. - -- HID_DDK_IO_ERROR: I/O operation error. - -- HID_DDK_INVALID_PARAMETER: Empty **dev**. - -- HID_DDK_DEVICE_NOT_FOUND: Device not found based on the specified **deviceId** and **interfaceIndex**. - - -### OH_Hid_Read() - -``` -int32_t OH_Hid_Read (Hid_DeviceHandle * dev, uint8_t * data, uint32_t bufSize, uint32_t * bytesRead) -``` - -**Description** - -Reads reports from the HID device. The blocking mode (that is, blocking remains active until data can be read) is used by default. You can call [OH_Hid_SetNonBlocking](#oh_hid_setnonblocking) to change the mode. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device operation handle.| -| data | Buffer for storing the read data.| -| bufSize | Size of the buffer for storing read data. The value cannot exceed [HID_MAX_REPORT_BUFFER_SIZE](#hid_max_report_buffer_size).| -| bytesRead | Number of bytes to read.| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_HID - -**Returns** - -- HID_DDK_SUCCESS: Operation succeeded. - -- HID_DDK_NO_PERM: Permission verification failed. - -- HID_DDK_INVALID_PARAMETER: Parameter verification failed. Possible causes: 1. **dev** is empty. 2. **data** is empty. 3. The value of **bufSize** is **0**. 4. The value of **bufSize** exceeds that of **[HID_MAX_REPORT_BUFFER_SIZE](#hid_max_report_buffer_size)**. 5. **bytesRead** is empty. - -- HID_DDK_INIT_ERROR DDK: DDK initialization error. - -- HID_DDK_SERVICE_ERROR: DDK service communication error. - -- HID_DDK_MEMORY_ERROR: Memory data copy error. - -- HID_DDK_IO_ERROR: I/O operation error. - -- HID_DDK_TIMEOUT: Reading timed out. - - -### OH_Hid_ReadTimeout() - -``` -int32_t OH_Hid_ReadTimeout (Hid_DeviceHandle * dev, uint8_t * data, uint32_t bufSize, int timeout, uint32_t * bytesRead) -``` - -**Description** - -Reads reports from the HID device within the specified timeout interval. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device operation handle.| -| data | Buffer for storing the read data.| -| bufSize | Size of the buffer for storing read data. The value cannot exceed [HID_MAX_REPORT_BUFFER_SIZE](#hid_max_report_buffer_size).| -| timeout | Timeout interval, in ms. The value **-1** indicates block waiting.| -| bytesRead | Number of bytes to read.| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_HID - -**Returns** - -- HID_DDK_SUCCESS: Operation succeeded. - -- HID_DDK_NO_PERM: Permission verification failed. - -- HID_DDK_INVALID_PARAMETER: Parameter verification failed. Possible causes: 1. **dev** is empty. 2. **data** is empty. 3. The value of **bufSize** is **0**. 4. The value of **bufSize** exceeds that of **[HID_MAX_REPORT_BUFFER_SIZE](#hid_max_report_buffer_size)**. 5. **bytesRead** is empty. - -- HID_DDK_INIT_ERROR DDK: DDK initialization error. - -- HID_DDK_SERVICE_ERROR: DDK service communication error. - -- HID_DDK_MEMORY_ERROR: Memory data copy error. - -- HID_DDK_IO_ERROR: I/O operation error. - -- HID_DDK_TIMEOUT: Reading timed out. - - -### OH_Hid_Release() - -``` -int32_t OH_Hid_Release (void) -``` - -**Description** - -Releases an HID DDK. - -**Since**: 18 - -**Required Permissions** - -ohos.permission.ACCESS_DDK_HID - -**Returns** - -- HID_DDK_SUCCESS: Operation succeeded. - -- HID_DDK_NO_PERM: Permission verification failed. - -- HID_DDK_INIT_ERROR DDK: DDK initialization error. - -- HID_DDK_SERVICE_ERROR: DDK service communication error. - - -### OH_Hid_SendReport() - -``` -int32_t OH_Hid_SendReport (Hid_DeviceHandle * dev, Hid_ReportType reportType, const uint8_t * data, uint32_t length) -``` - -**Description** - -Sends reports to the HID device. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device operation handle.| -| reportType | Report type.| -| data | Data to be sent.| -| length | Length of the data to be sent, in bytes. The value cannot exceed [HID_MAX_REPORT_BUFFER_SIZE](#hid_max_report_buffer_size).| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_HID - -**Returns** - -- HID_DDK_SUCCESS: Operation succeeded. - -- HID_DDK_NO_PERM: Permission verification failed. - -- HID_DDK_INVALID_PARAMETER: Parameter verification failed. Possible causes: 1. **dev** is empty. 2. **data** is empty. 3. The value of **length** is **0**; 4. The value of **length** exceeds [HID_MAX_REPORT_BUFFER_SIZE](#hid_max_report_buffer_size). - -- HID_DDK_INIT_ERROR DDK: DDK initialization error. - -- HID_DDK_SERVICE_ERROR: DDK service communication error. - -- HID_DDK_IO_ERROR: I/O operation error. - -- HID_DDK_INVALID_OPERATION: Invalid operation. - - -### OH_Hid_SetNonBlocking() - -``` -int32_t OH_Hid_SetNonBlocking (Hid_DeviceHandle * dev, int nonBlock) -``` - -**Description** - -Sets the device read mode to non-blocking mode. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device operation handle.| -| nonBlock | Whether to enable the non-blocking mode for reading data.
- 1: The non-blocking mode is enabled. When [OH_Hid_Read](#oh_hid_read) is called, if the device has readable data, **HID_DDK_SUCCESS** is returned; if the device has no readable data, **HID_DDK_TIMEOUT** is returned.
- 0: The non-blocking mode is disabled.| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_HID - -**Returns** - -- HID_DDK_SUCCESS: Operation succeeded. - -- HID_DDK_NO_PERM: Permission verification failed. - -- HID_DDK_INIT_ERROR DDK: DDK initialization error. - -- HID_DDK_INVALID_PARAMETER: Parameter verification failed. Possible causes: 1. **dev** is empty. 2. The value of **nonBlock** is not **1** or **0**. - -- HID_DDK_SERVICE_ERROR: DDK service communication error. - - -### OH_Hid_Write() - -``` -int32_t OH_Hid_Write (Hid_DeviceHandle * dev, uint8_t * data, uint32_t length, uint32_t * bytesWritten) -``` - -**Description** - -Writes reports to an HID device. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device operation handle.| -| data | Data to be written.| -| length | Length of the data to be written, in bytes. The value cannot exceed [HID_MAX_REPORT_BUFFER_SIZE](#hid_max_report_buffer_size).| -| bytesWritten | Number of written bytes.| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_HID - -**Returns** - -- HID_DDK_SUCCESS: Operation succeeded. - -- HID_DDK_NO_PERM: Permission verification failed. - -- HID_DDK_INVALID_PARAMETER: Parameter verification failed. Possible causes: 1. **dev** is empty. 2. **data** is empty. 3. The value of length is **0**; 4. The value of **length** exceeds [HID_MAX_REPORT_BUFFER_SIZE](#hid_max_report_buffer_size); 5. **bytesWritten** is empty. - -- HID_DDK_INIT_ERROR DDK: DDK initialization error. - -- HID_DDK_SERVICE_ERROR: DDK service communication error. - -- HID_DDK_IO_ERROR: I/O operation error. - - -## Variable Description - - -### bustype - -``` -uint16_t Hid_Device::bustype -``` - -**Description** - -Bus type. - - -### busType - -``` -uint32_t Hid_RawDevInfo::busType -``` - -**Description** - -Bus type. - - -### code - -``` -uint16_t Hid_EmitItem::code -``` - -**Description** - -Event code. - - -### deviceName - -``` -const char* Hid_Device::deviceName -``` - -**Description** - -Device name. - - -### hidAbs - -``` -struct Hid_AbsAxesArray Hid_EventProperties::hidAbs -``` - -**Description** - -Array of absolute coordinates. - - -### hidAbsAxes - -``` -Hid_AbsAxes* Hid_AbsAxesArray::hidAbsAxes -``` - -**Description** - -Array of absolute coordinates. - - -### hidAbsFlat - -``` -int32_t Hid_EventProperties::hidAbsFlat[64] -``` - -**Description** - -Fixed values of the absolute coordinates. - - -### hidAbsFuzz - -``` -int32_t Hid_EventProperties::hidAbsFuzz[64] -``` - -**Description** - -Fuzzy values of the absolute coordinates. - - -### hidAbsMax - -``` -int32_t Hid_EventProperties::hidAbsMax[64] -``` - -**Description** - -Maximum values of the absolute coordinates. - - -### hidAbsMin - -``` -int32_t Hid_EventProperties::hidAbsMin[64] -``` - -**Description** - -Minimum values of the absolute coordinates. - - -### hidEventType - -``` -Hid_EventType* Hid_EventTypeArray::hidEventType -``` - -**Description** - -Event type. - - -### hidEventTypes - -``` -struct Hid_EventTypeArray Hid_EventProperties::hidEventTypes -``` - -**Description** - -Array of event types. - - -### hidKeyCode - -``` -Hid_KeyCode* Hid_KeyCodeArray::hidKeyCode -``` - -**Description** - -Enumerates the key codes. - - -### hidKeys - -``` -struct Hid_KeyCodeArray Hid_EventProperties::hidKeys -``` - -**Description** - -Array of key codes. - - -### hidMiscellaneous - -``` -struct Hid_MscEventArray Hid_EventProperties::hidMiscellaneous -``` - -**Description** - -Array of miscellaneous events. - - -### hidMscEvent - -``` -Hid_MscEvent* Hid_MscEventArray::hidMscEvent -``` - -**Description** - -Miscellaneous event. - - -### hidRelAxes - -``` -Hid_RelAxes* Hid_RelAxesArray::hidRelAxes -``` - -**Description** - -Relative coordinate. - - -### hidRelBits - -``` -struct Hid_RelAxesArray Hid_EventProperties::hidRelBits -``` - -**Description** - -Array of relative coordinates. - - -### length [1/5] - -``` -uint16_t Hid_EventTypeArray::length -``` - -**Description** - -Size of the array. - - -### length [2/5] - -``` -uint16_t Hid_KeyCodeArray::length -``` - -**Description** - -Size of the array. - - -### length [3/5] - -``` -uint16_t Hid_AbsAxesArray::length -``` - -**Description** - -Size of the array. - - -### length [4/5] - -``` -uint16_t Hid_RelAxesArray::length -``` - -**Description** - -Size of the array. - - -### length [5/5] - -``` -uint16_t Hid_MscEventArray::length -``` - -**Description** - -Size of the array. - - -### product - -``` -uint16_t Hid_RawDevInfo::product -``` - -**Description** - -Product ID. - - -### productId - -``` -uint16_t Hid_Device::productId -``` - -**Description** - -Product ID. - - -### properties - -``` -Hid_DeviceProp* Hid_Device::properties -``` - -**Description** - -Device properties. - - -### propLength - -``` -uint16_t Hid_Device::propLength -``` - -**Description** - -Number of device properties. - - -### type - -``` -uint16_t Hid_EmitItem::type -``` - -**Description** - -Enumerates the event types. - - -### value - -``` -uint32_t Hid_EmitItem::value -``` - -**Description** - -Event value. - - -### vendor - -``` -uint16_t Hid_RawDevInfo::vendor -``` - -**Description** - -Provider ID. - - -### vendorId - -``` -uint16_t Hid_Device::vendorId -``` - -**Description** - -Vendor ID. - - -### version - -``` -uint16_t Hid_Device::version -``` - -**Description** - -Version. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_s_c_s_i.md b/en/application-dev/reference/apis-driverdevelopment-kit/_s_c_s_i.md deleted file mode 100644 index 67dadaa994a..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_s_c_s_i.md +++ /dev/null @@ -1,1016 +0,0 @@ -# SCSI Peripheral DDK - - -## Overview - -The SCSI Peripheral DDK is a suite dedicated to SCSI device driver development at the application layer. It provides APIs for initializing the DDK, releasing the DDK, enabling and disabling devices, and reading data from and writing data to devices. It also declares the macros, enum variables, and data structures required by the SCSI Peripheral DDK APIs. - -**System capability**: SystemCapability.Driver.SCSI.Extension - -**Since**: 18 - - -## Summary - - -### Files - -| Name| Description| -| -------- | -------- | -| [scsi_peripheral_api.h](scsi__peripheral__api_8h.md) | Declares the SCSI Peripheral DDK APIs used by the host to access the SCSI device.| -| [scsi_peripheral_types.h](scsi__peripheral__types_8h.md) | Provides the enum variables, structures, and macros used in the SCSI Peripheral DDK APIs.| - - -### Structs - -| Name| Description| -| -------- | -------- | -| struct  [ScsiPeripheral_DeviceMemMap](_scsi_peripheral___device_mem_map.md) | Device memory mapping created by calling **OH_ScsiPeripheral_CreateDeviceMemMap**. The buffer that uses the device memory mapping can provide better performance.| -| struct  [ScsiPeripheral_IORequest](_scsi_peripheral___i_o_request.md) | Read/write operation request.| -| struct  [ScsiPeripheral_Request](_scsi_peripheral___request.md) | Request structure.| -| struct  [ScsiPeripheral_Response](_scsi_peripheral___response.md) | Response structure.| -| struct  [ScsiPeripheral_TestUnitReadyRequest](_scsi_peripheral___test_unit_ready_request.md) | Request structure of the **test unit ready** command.| -| struct  [ScsiPeripheral_InquiryRequest](_scsi_peripheral___inquiry_request.md) | Request structure of the **inquiry** command.| -| struct  [ScsiPeripheral_InquiryInfo](_scsi_peripheral___inquiry_info.md) | SCSI inquiry data.| -| struct  [ScsiPeripheral_ReadCapacityRequest](_scsi_peripheral___read_capacity_request.md) | Request structure of the **read capacity** command.| -| struct  [ScsiPeripheral_CapacityInfo](_scsi_peripheral___capacity_info.md) | SCSI read capacity.| -| struct  [ScsiPeripheral_RequestSenseRequest](_scsi_peripheral___request_sense_request.md) | Request structure of the **request sense** command.| -| struct  [ScsiPeripheral_BasicSenseInfo](_scsi_peripheral___basic_sense_info.md) | Basic information about the sense data.| -| struct  [ScsiPeripheral_VerifyRequest](_scsi_peripheral___verify_request.md) | Request structure of the **verify** command.| - - -### Macros - -| Name| Description| -| -------- | -------- | -| [SCSIPERIPHERAL_MIN_DESCRIPTOR_FORMAT_SENSE](#scsiperipheral_min_descriptor_format_sense)   8 | Minimum length of the sense data descriptor format.| -| [SCSIPERIPHERAL_MIN_FIXED_FORMAT_SENSE](#scsiperipheral_min_fixed_format_sense)   18 | Minimum length of the fixed format of sense data.| -| [SCSIPERIPHERAL_MAX_CMD_DESC_BLOCK_LEN](#scsiperipheral_max_cmd_desc_block_len)   16 | Maximum length of a command descriptor block (CDB).| -| [SCSIPERIPHERAL_MAX_SENSE_DATA_LEN](#scsiperipheral_max_sense_data_len)   252 | Maximum length of sense data. In the SCSI protocol, the maximum length of sense data is usually 252 bytes.| -| [SCSIPERIPHERAL_VENDOR_ID_LEN](#scsiperipheral_vendor_id_len)   8 | Maximum length of the vendor ID.| -| [SCSIPERIPHERAL_PRODUCT_ID_LEN](#scsiperipheral_product_id_len)   18 | Maximum length of the product ID.| -| [SCSIPERIPHERAL_PRODUCT_REV_LEN](#scsiperipheral_product_rev_len)   4 | Maximum length of the product version.| - - -### Types - -| Name| Description| -| -------- | -------- | -| typedef struct [ScsiPeripheral_Device](#scsiperipheral_device) [ScsiPeripheral_Device](#scsiperipheral_device) | Opaque SCSI device structure.| -| typedef struct [ScsiPeripheral_DeviceMemMap](_scsi_peripheral___device_mem_map.md) [ScsiPeripheral_DeviceMemMap](#scsiperipheral_devicememmap) | Device memory mapping created by calling **OH_ScsiPeripheral_CreateDeviceMemMap**. The buffer that uses the device memory mapping can provide better performance.| -| typedef struct [ScsiPeripheral_IORequest](_scsi_peripheral___i_o_request.md) [ScsiPeripheral_IORequest](#scsiperipheral_iorequest) | Read/write operation request.| -| typedef struct [ScsiPeripheral_Request](_scsi_peripheral___request.md) [ScsiPeripheral_Request](#scsiperipheral_request) | Request structure.| -| typedef struct [ScsiPeripheral_Response](_scsi_peripheral___response.md) [ScsiPeripheral_Response](#scsiperipheral_response) | Response structure.| -| typedef struct [ScsiPeripheral_TestUnitReadyRequest](_scsi_peripheral___test_unit_ready_request.md) [ScsiPeripheral_TestUnitReadyRequest](#scsiperipheral_testunitreadyrequest) | Request structure of the **test unit ready** command.| -| typedef struct [ScsiPeripheral_InquiryRequest](_scsi_peripheral___inquiry_request.md) [ScsiPeripheral_InquiryRequest](#scsiperipheral_inquiryrequest) | Request structure of the **inquiry** command.| -| typedef struct [ScsiPeripheral_InquiryInfo](_scsi_peripheral___inquiry_info.md) [ScsiPeripheral_InquiryInfo](#scsiperipheral_inquiryinfo) | SCSI inquiry data.| -| typedef struct [ScsiPeripheral_ReadCapacityRequest](_scsi_peripheral___read_capacity_request.md) [ScsiPeripheral_ReadCapacityRequest](#scsiperipheral_readcapacityrequest) | Request structure of the **read capacity** command.| -| typedef struct [ScsiPeripheral_CapacityInfo](_scsi_peripheral___capacity_info.md) [ScsiPeripheral_CapacityInfo](#scsiperipheral_capacityinfo) | SCSI read capacity.| -| typedef struct [ScsiPeripheral_RequestSenseRequest](_scsi_peripheral___request_sense_request.md) [ScsiPeripheral_RequestSenseRequest](#scsiperipheral_requestsenserequest) | Request structure of the **request sense** command.| -| typedef struct [ScsiPeripheral_BasicSenseInfo](_scsi_peripheral___basic_sense_info.md) [ScsiPeripheral_BasicSenseInfo](#scsiperipheral_basicsenseinfo) | Basic information about the sense data.| -| typedef struct [ScsiPeripheral_VerifyRequest](_scsi_peripheral___verify_request.md) [ScsiPeripheral_VerifyRequest](#scsiperipheral_verifyrequest) | Request structure of the **verify** command.| - - -### Enums - -| Name| Description| -| -------- | -------- | -| [ScsiPeripheral_DdkErrCode](#scsiperipheral_ddkerrcode) {
SCSIPERIPHERAL_DDK_NO_PERM = 201, SCSIPERIPHERAL_DDK_INVALID_PARAMETER = 401, SCSIPERIPHERAL_DDK_SUCCESS = 31700000, SCSIPERIPHERAL_DDK_MEMORY_ERROR = 31700001, SCSIPERIPHERAL_DDK_INVALID_OPERATION = 31700002, SCSIPERIPHERAL_DDK_IO_ERROR = 31700003, SCSIPERIPHERAL_DDK_TIMEOUT = 31700004, SCSIPERIPHERAL_DDK_INIT_ERROR = 31700005, SCSIPERIPHERAL_DDK_SERVICE_ERROR = 31700006, SCSIPERIPHERAL_DDK_DEVICE_NOT_FOUND = 31700007
} | SCSI Peripheral DDK error codes.| -| [ScsiPeripheral_Status](#scsiperipheral_status) {
SCSIPERIPHERAL_STATUS_GOOD = 0x00, SCSIPERIPHERAL_STATUS_CHECK_CONDITION_NEEDED = 0x02, SCSIPERIPHERAL_STATUS_CONDITION_MET = 0x04, SCSIPERIPHERAL_STATUS_BUSY = 0x08, SCSIPERIPHERAL_STATUS_RESERVATION_CONFLICT = 0x18, SCSIPERIPHERAL_STATUS_TASK_SET_FULL = 0x28, SCSIPERIPHERAL_STATUS_ACA_ACTIVE = 0x30, SCSIPERIPHERAL_STATUS_TASK_ABORTED = 0x40
} | SCSI status used for the response.| - - -### Function - -| Name| Description| -| -------- | -------- | -| int32_t [OH_ScsiPeripheral_Init](#oh_scsiperipheral_init) (void) | Initializes the SCSI Peripheral DDK.| -| int32_t [OH_ScsiPeripheral_Release](#oh_scsiperipheral_release) (void) | Releases the SCSI Peripheral DDK.| -| int32_t [OH_ScsiPeripheral_Open](#oh_scsiperipheral_open) (uint64_t deviceId, uint8_t interfaceIndex, [ScsiPeripheral_Device](#scsiperipheral_device) \*\*dev) | Opens the SCSI device specified by **deviceId** and **interfaceIndex**.| -| int32_t [OH_ScsiPeripheral_Close](#oh_scsiperipheral_close) ([ScsiPeripheral_Device](#scsiperipheral_device) \*\*dev) | Disables the SCSI device.| -| int32_t [OH_ScsiPeripheral_TestUnitReady](#oh_scsiperipheral_testunitready) ([ScsiPeripheral_Device](#scsiperipheral_device) \*dev, [ScsiPeripheral_TestUnitReadyRequest](_scsi_peripheral___test_unit_ready_request.md) \*request, [ScsiPeripheral_Response](_scsi_peripheral___response.md) \*response) | Checks whether the logical units are ready.| -| int32_t [OH_ScsiPeripheral_Inquiry](#oh_scsiperipheral_inquiry) ([ScsiPeripheral_Device](#scsiperipheral_device) \*dev, [ScsiPeripheral_InquiryRequest](_scsi_peripheral___inquiry_request.md) \*request, [ScsiPeripheral_InquiryInfo](_scsi_peripheral___inquiry_info.md) \*inquiryInfo, [ScsiPeripheral_Response](_scsi_peripheral___response.md) \*response) | Queries basic information about the SCSI device.| -| int32_t [OH_ScsiPeripheral_ReadCapacity10](#oh_scsiperipheral_readcapacity10) ([ScsiPeripheral_Device](#scsiperipheral_device) \*dev, [ScsiPeripheral_ReadCapacityRequest](_scsi_peripheral___read_capacity_request.md) \*request, [ScsiPeripheral_CapacityInfo](_scsi_peripheral___capacity_info.md) \*capacityInfo, [ScsiPeripheral_Response](_scsi_peripheral___response.md) \*response) | Obtains the capacity information about the SCSI device.| -| int32_t [OH_ScsiPeripheral_RequestSense](#oh_scsiperipheral_requestsense) ([ScsiPeripheral_Device](#scsiperipheral_device) \*dev, [ScsiPeripheral_RequestSenseRequest](_scsi_peripheral___request_sense_request.md) \*request, [ScsiPeripheral_Response](_scsi_peripheral___response.md) \*response) | Obtains sense data, that is, information returned by the SCSI device to the host to report the device status, error information, and diagnosis information.| -| int32_t [OH_ScsiPeripheral_Read10](#oh_scsiperipheral_read10) ([ScsiPeripheral_Device](#scsiperipheral_device) \*dev, [ScsiPeripheral_IORequest](_scsi_peripheral___i_o_request.md) \*request, [ScsiPeripheral_Response](_scsi_peripheral___response.md) \*response) | Reads data from a specified logical block.| -| int32_t [OH_ScsiPeripheral_Write10](#oh_scsiperipheral_write10) ([ScsiPeripheral_Device](#scsiperipheral_device) \*dev, [ScsiPeripheral_IORequest](_scsi_peripheral___i_o_request.md) \*request, [ScsiPeripheral_Response](_scsi_peripheral___response.md) \*response) | Writes data to a specified logical block of a device.| -| int32_t [OH_ScsiPeripheral_Verify10](#oh_scsiperipheral_verify10) ([ScsiPeripheral_Device](#scsiperipheral_device) \*dev, [ScsiPeripheral_VerifyRequest](_scsi_peripheral___verify_request.md) \*request, [ScsiPeripheral_Response](_scsi_peripheral___response.md) \*response) | Verifies a specified logical block.| -| int32_t [OH_ScsiPeripheral_SendRequestByCdb](#oh_scsiperipheral_sendrequestbycdb) ([ScsiPeripheral_Device](#scsiperipheral_device) \*dev, [ScsiPeripheral_Request](_scsi_peripheral___request.md) \*request, [ScsiPeripheral_Response](_scsi_peripheral___response.md) \*response) | Sends SCSI commands in CDB mode.| -| int32_t [OH_ScsiPeripheral_CreateDeviceMemMap](#oh_scsiperipheral_createdevicememmap) ([ScsiPeripheral_Device](#scsiperipheral_device) \*dev, size_t size, [ScsiPeripheral_DeviceMemMap](_scsi_peripheral___device_mem_map.md) \*\*devMmap) | Creates a buffer. To avoid memory leakage, use [OH_ScsiPeripheral_DestroyDeviceMemMap](#oh_scsiperipheral_destroydevicememmap) to destroy a buffer after use.| -| int32_t [OH_ScsiPeripheral_DestroyDeviceMemMap](#oh_scsiperipheral_destroydevicememmap) ([ScsiPeripheral_DeviceMemMap](_scsi_peripheral___device_mem_map.md) \*devMmap) | Destroys a buffer. To avoid resource leakage, destroy a buffer in time after use.| -| int32_t [OH_ScsiPeripheral_ParseBasicSenseInfo](#oh_scsiperipheral_parsebasicsenseinfo) (uint8_t \*senseData, uint8_t senseDataLen, [ScsiPeripheral_BasicSenseInfo](_scsi_peripheral___basic_sense_info.md) \*senseInfo) | Parses basic sense data, including the **Information**, **Command specific information**, and **Sense key specific** fields.| - - -## Macro Description - - -### SCSIPERIPHERAL_MAX_CMD_DESC_BLOCK_LEN - -``` -#define SCSIPERIPHERAL_MAX_CMD_DESC_BLOCK_LEN 16 -``` - -**Description** - -Maximum length of a CDB. - -**Since**: 18 - - -### SCSIPERIPHERAL_MAX_SENSE_DATA_LEN - -``` -#define SCSIPERIPHERAL_MAX_SENSE_DATA_LEN 252 -``` - -**Description** - -Maximum length of sense data. In the SCSI protocol, the maximum length of sense data is usually 252 bytes. - -**Since**: 18 - - -### SCSIPERIPHERAL_MIN_DESCRIPTOR_FORMAT_SENSE - -``` -#define SCSIPERIPHERAL_MIN_DESCRIPTOR_FORMAT_SENSE 8 -``` - -**Description** - -Minimum length of the sense data descriptor format. - -**Since**: 18 - - -### SCSIPERIPHERAL_MIN_FIXED_FORMAT_SENSE - -``` -#define SCSIPERIPHERAL_MIN_FIXED_FORMAT_SENSE 18 -``` - -**Description** - -Minimum length of the fixed format of sense data. - -**Since**: 18 - - -### SCSIPERIPHERAL_PRODUCT_ID_LEN - -``` -#define SCSIPERIPHERAL_PRODUCT_ID_LEN 18 -``` - -**Description** - -Maximum length of the product ID. - -**Since**: 18 - - -### SCSIPERIPHERAL_PRODUCT_REV_LEN - -``` -#define SCSIPERIPHERAL_PRODUCT_REV_LEN 4 -``` - -**Description** - -Maximum length of the product version. - -**Since**: 18 - - -### SCSIPERIPHERAL_VENDOR_ID_LEN - -``` -#define SCSIPERIPHERAL_VENDOR_ID_LEN 8 -``` - -**Description** - -Maximum length of the vendor ID. - -**Since**: 18 - - -## Type Description - - -### ScsiPeripheral_BasicSenseInfo - -``` -typedef struct ScsiPeripheral_BasicSenseInfo ScsiPeripheral_BasicSenseInfo -``` - -**Description** - -Basic information about the sense data. - -**Since**: 18 - - -### ScsiPeripheral_CapacityInfo - -``` -typedef struct ScsiPeripheral_CapacityInfo ScsiPeripheral_CapacityInfo -``` - -**Description** - -SCSI read capacity. - -**Since**: 18 - - -### ScsiPeripheral_Device - -``` -typedef struct ScsiPeripheral_Device ScsiPeripheral_Device -``` - -**Description** - -Opaque SCSI device structure. - -**Since**: 18 - - -### ScsiPeripheral_DeviceMemMap - -``` -typedef struct ScsiPeripheral_DeviceMemMap ScsiPeripheral_DeviceMemMap -``` - -**Description** - -Device memory mapping created by calling **OH_ScsiPeripheral_CreateDeviceMemMap**. The buffer that uses the device memory mapping can provide better performance. - -**Since**: 18 - - -### ScsiPeripheral_InquiryInfo - -``` -typedef struct ScsiPeripheral_InquiryInfo ScsiPeripheral_InquiryInfo -``` - -**Description** - -SCSI inquiry data. - -**Since**: 18 - - -### ScsiPeripheral_InquiryRequest - -``` -typedef struct ScsiPeripheral_InquiryRequest ScsiPeripheral_InquiryRequest -``` - -**Description** - -Request structure of the **inquiry** command. - -**Since**: 18 - - -### ScsiPeripheral_IORequest - -``` -typedef struct ScsiPeripheral_IORequest ScsiPeripheral_IORequest -``` - -**Description** - -Read/write operation request. - -**Since**: 18 - - -### ScsiPeripheral_ReadCapacityRequest - -``` -typedef struct ScsiPeripheral_ReadCapacityRequest ScsiPeripheral_ReadCapacityRequest -``` - -**Description** - -Request structure of the **read capacity** command. - -**Since**: 18 - - -### ScsiPeripheral_Request - -``` -typedef struct ScsiPeripheral_Request ScsiPeripheral_Request -``` - -**Description** - -Request structure. - -**Since**: 18 - - -### ScsiPeripheral_RequestSenseRequest - -``` -typedef struct ScsiPeripheral_RequestSenseRequest ScsiPeripheral_RequestSenseRequest -``` - -**Description** - -Request structure of the **request sense** command. - -**Since**: 18 - - -### ScsiPeripheral_Response - -``` -typedef struct ScsiPeripheral_Response ScsiPeripheral_Response -``` - -**Description** - -Response structure. - -**Since**: 18 - - -### ScsiPeripheral_TestUnitReadyRequest - -``` -typedef struct ScsiPeripheral_TestUnitReadyRequest ScsiPeripheral_TestUnitReadyRequest -``` - -**Description** - -Request structure of the **test unit ready** command. - -**Since**: 18 - - -### ScsiPeripheral_VerifyRequest - -``` -typedef struct ScsiPeripheral_VerifyRequest ScsiPeripheral_VerifyRequest -``` - -**Description** - -Request structure of the **verify** command. - -**Since**: 18 - - -## Enum Description - - -### ScsiPeripheral_DdkErrCode - -``` -enum ScsiPeripheral_DdkErrCode -``` - -**Description** - -SCSI Peripheral DDK error codes. - -**Since**: 18 - -| Value| Description| -| -------- | -------- | -| SCSIPERIPHERAL_DDK_NO_PERM | Permission denied.| -| SCSIPERIPHERAL_DDK_INVALID_PARAMETER | Invalid parameter.| -| SCSIPERIPHERAL_DDK_SUCCESS | Operation succeeded.| -| SCSIPERIPHERAL_DDK_MEMORY_ERROR | Memory-related errors, such as insufficient memory, memory data replication failure, or memory request failure.| -| SCSIPERIPHERAL_DDK_INVALID_OPERATION | Invalid operation.| -| SCSIPERIPHERAL_DDK_IO_ERROR | Device input/output operation failure.| -| SCSIPERIPHERAL_DDK_TIMEOUT | Transfer timeout.| -| SCSIPERIPHERAL_DDK_INIT_ERROR | DDK initialization error, or DDK uninitialized.| -| SCSIPERIPHERAL_DDK_SERVICE_ERROR | Failed to communicate with the SCSI Peripheral DDK.| -| SCSIPERIPHERAL_DDK_DEVICE_NOT_FOUND | Device not found.| - - -### ScsiPeripheral_Status - -``` -enum ScsiPeripheral_Status -``` - -**Description** - -SCSI status used for the response. - -**Since**: 18 - -| Value| Description| -| -------- | -------- | -| SCSIPERIPHERAL_STATUS_GOOD | Normal state.| -| SCSIPERIPHERAL_STATUS_CHECK_CONDITION_NEEDED | Status check required.| -| SCSIPERIPHERAL_STATUS_CONDITION_MET | Conditions met.| -| SCSIPERIPHERAL_STATUS_BUSY | Occupying.| -| SCSIPERIPHERAL_STATUS_RESERVATION_CONFLICT | Resource reservation conflict.| -| SCSIPERIPHERAL_STATUS_TASK_SET_FULL | Task set already full.| -| SCSIPERIPHERAL_STATUS_ACA_ACTIVE | ACA activity status.| -| SCSIPERIPHERAL_STATUS_TASK_ABORTED | Task aborted.| - - -## Function Description - - -### OH_ScsiPeripheral_Close() - -``` -int32_t OH_ScsiPeripheral_Close (ScsiPeripheral_Device ** dev) -``` - -**Description** - -Disables the SCSI device. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device handle. For details, see [ScsiPeripheral_Device](#scsiperipheral_device).| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL - -**Returns** - -- SCSIPERIPHERAL_DDK_SUCCESS: Operation succeeded. - -- SCSIPERIPHERAL_DDK_NO_PERM: Permission verification failed. - -- SCSIPERIPHERAL_DDK_INIT_ERROR: DDK not initialized. - -- SCSIPERIPHERAL_DDK_INVALID_PARAMETER: empty dev. - -- SCSIPERIPHERAL_DDK_SERVICE_ERROR: DDK service communication error. - -- SCSIPERIPHERAL_DDK_IO_ERROR: DDK I/O error. - - -### OH_ScsiPeripheral_CreateDeviceMemMap() - -``` -int32_t OH_ScsiPeripheral_CreateDeviceMemMap (ScsiPeripheral_Device * dev, size_t size, ScsiPeripheral_DeviceMemMap ** devMmap ) -``` - -**Description** - -Creates a buffer. To avoid memory leakage, use [OH_ScsiPeripheral_DestroyDeviceMemMap](#oh_scsiperipheral_destroydevicememmap) to destroy a buffer after use. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device handle. For details, see [ScsiPeripheral_Device](#scsiperipheral_device).| -| size | Buffer size.| -| devMmap | Device memory mapping used to return the created buffer to the caller. For details, see [ScsiPeripheral_DeviceMemMap](_scsi_peripheral___device_mem_map.md).| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL - -**Returns** - -- SCSIPERIPHERAL_DDK_SUCCESS: Operation succeeded. - -- SCSIPERIPHERAL_DDK_INVALID_PARAMETER: Empty dev or devMmap. - -- SCSIPERIPHERAL_DDK_MEMORY_ERROR: Memory operation error. - - -### OH_ScsiPeripheral_DestroyDeviceMemMap() - -``` -int32_t OH_ScsiPeripheral_DestroyDeviceMemMap (ScsiPeripheral_DeviceMemMap * devMmap) -``` - -**Description** - -Destroys a buffer. To avoid resource leakage, destroy a buffer in time after use. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| devMmap | Buffer to be destroyed, which is created by calling **OH_ScsiPeripheral_CreateDeviceMemMa**. For details, see [ScsiPeripheral_DeviceMemMap](_scsi_peripheral___device_mem_map.md).| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL - -**Returns** - -- SCSIPERIPHERAL_DDK_SUCCESS: Operation succeeded. - -- SCSIPERIPHERAL_DDK_INVALID_PARAMETER: Empty devMmap. - -- SCSIPERIPHERAL_DDK_MEMORY_ERROR: Memory operation error. - - -### OH_ScsiPeripheral_Init() - -``` -int32_t OH_ScsiPeripheral_Init (void ) -``` - -**Description** - -Initializes the SCSI Peripheral DDK. - -**Since**: 18 - -**Required Permissions** - -ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL - -**Returns** - -- SCSIPERIPHERAL_DDK_SUCCESS: Operation succeeded. - -- SCSIPERIPHERAL_DDK_NO_PERM: Permission verification failed. - -- SCSIPERIPHERAL_DDK_INIT_ERROR: DDK initialization error. - -- SCSIPERIPHERAL_DDK_SERVICE_ERROR: DDK service communication error. - - -### OH_ScsiPeripheral_Inquiry() - -``` -int32_t OH_ScsiPeripheral_Inquiry (ScsiPeripheral_Device * dev, ScsiPeripheral_InquiryRequest * request, ScsiPeripheral_InquiryInfo * inquiryInfo, ScsiPeripheral_Response * response ) -``` - -**Description** - -Queries basic information about the SCSI device. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device handle. For details, see [ScsiPeripheral_Device](#scsiperipheral_device).| -| request | Request of the **inquiry** command. For details, see [ScsiPeripheral_InquiryRequest](_scsi_peripheral___inquiry_request.md).| -| inquiryInfo | Query result returned by the **inquiry** command. For details, see [ScsiPeripheral_InquiryInfo](_scsi_peripheral___inquiry_info.md).| -| response | Original response returned by the **inquiry** command. For details, see [ScsiPeripheral_Response](_scsi_peripheral___response.md).| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL - -**Returns** - -- SCSIPERIPHERAL_DDK_SUCCESS: Operation succeeded. - -- SCSIPERIPHERAL_DDK_NO_PERM: Permission verification failed. - -- SCSIPERIPHERAL_DDK_INIT_ERROR: DDK not initialized. - -- SCSIPERIPHERAL_DDK_INVALID_PARAMETER: Empty dev, request, inquiryInfo, inquiryInfo->data, or response. - -- SCSIPERIPHERAL_DDK_SERVICE_ERROR: DDK service communication error. - -- SCSIPERIPHERAL_DDK_MEMORY_ERROR: Memory operation error. - -- SCSIPERIPHERAL_DDK_IO_ERROR: DDK I/O error. - -- SCSIPERIPHERAL_DDK_TIMEOUT: Transfer timeout. - -- SCSIPERIPHERAL_DDK_INVALID_OPERATION: Operation not supported. - - -### OH_ScsiPeripheral_Open() - -``` -int32_t OH_ScsiPeripheral_Open (uint64_t deviceId, uint8_t interfaceIndex, ScsiPeripheral_Device ** dev ) -``` - -**Description** - -Opens the SCSI device specified by **deviceId** and **interfaceIndex**. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| deviceId | Device ID.| -| interfaceIndex | Interface index for the API of the SCSI device.| -| dev | Device handle. For details, see [ScsiPeripheral_Device](#scsiperipheral_device).| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL - -**Returns** - -- SCSIPERIPHERAL_DDK_SUCCESS: Operation succeeded. - -- SCSIPERIPHERAL_DDK_NO_PERM: Permission verification failed. - -- SCSIPERIPHERAL_DDK_INIT_ERROR: DDK not initialized. - -- SCSIPERIPHERAL_DDK_INVALID_PARAMETER: empty dev. - -- SCSIPERIPHERAL_DDK_SERVICE_ERROR: DDK service communication error. - -- SCSIPERIPHERAL_DDK_MEMORY_ERROR: Memory operation error. - -- SCSIPERIPHERAL_DDK_IO_ERROR: DDK I/O operation error. - -- SCSIPERIPHERAL_DDK_DEVICE_NOT_FOUND: Device not found based on deviceId and interfaceIndex. - -- SCSIPERIPHERAL_DDK_INVALID_OPERATION: Operation not supported. - -- SCSIPERIPHERAL_DDK_TIMEOUT: Transfer timeout. - -### OH_ScsiPeripheral_ParseBasicSenseInfo() - -``` -int32_t OH_ScsiPeripheral_ParseBasicSenseInfo (uint8_t * senseData, uint8_t senseDataLen, ScsiPeripheral_BasicSenseInfo * senseInfo ) -``` - -**Description** - -Parses basic sense data, including the **Information**, **Command specific information**, and **Sense key specific** fields. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| senseData | Sense data to be parsed.| -| senseDataLen | Length of sense data.| -| senseInfo | Stores parsed basic information. For details, see [ScsiPeripheral_BasicSenseInfo](_scsi_peripheral___basic_sense_info.md).| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL - -**Returns** - -- SCSIPERIPHERAL_DDK_SUCCESS: Operation succeeded. - -- SCSIPERIPHERAL_DDK_INVALID_PARAMETER: senseData or senseDataLen error. (senseData is not a descriptor or is not of the fixed format, or senseDataLen is smaller than SCSIPERIPHERAL_MIN_DESCRIPTOR_FORMAT_SENSE or SCSIPERIPHERAL_MIN_FIXED_FORMAT_SENSE.) - - -### OH_ScsiPeripheral_Read10() - -``` -int32_t OH_ScsiPeripheral_Read10 (ScsiPeripheral_Device * dev, ScsiPeripheral_IORequest * request, ScsiPeripheral_Response * response ) -``` - -**Description** - -Reads data from a specified logical block. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device handle. For details, see [ScsiPeripheral_Device](#scsiperipheral_device).| -| request | Request of the **read** command. For details, see [ScsiPeripheral_IORequest](_scsi_peripheral___i_o_request.md).| -| response | Response returned by the **read** command. For details, see [ScsiPeripheral_Response](_scsi_peripheral___response.md).| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL - -**Returns** - -- SCSIPERIPHERAL_DDK_SUCCESS: Operation succeeded. - -- SCSIPERIPHERAL_DDK_NO_PERM: Permission verification failed. - -- SCSIPERIPHERAL_DDK_INIT_ERROR: DDK not initialized. - -- SCSIPERIPHERAL_DDK_INVALID_PARAMETER: Empty dev, request, request->data, or response. - -- SCSIPERIPHERAL_DDK_SERVICE_ERROR: DDK service communication error. - -- SCSIPERIPHERAL_DDK_MEMORY_ERROR: Memory operation error. - -- SCSIPERIPHERAL_DDK_IO_ERROR: DDK I/O error. - -- SCSIPERIPHERAL_DDK_TIMEOUT: Transfer timeout. - -- SCSIPERIPHERAL_DDK_INVALID_OPERATION: Operation not supported. - - -### OH_ScsiPeripheral_ReadCapacity10() - -``` -int32_t OH_ScsiPeripheral_ReadCapacity10 (ScsiPeripheral_Device * dev, ScsiPeripheral_ReadCapacityRequest * request, ScsiPeripheral_CapacityInfo * capacityInfo, ScsiPeripheral_Response * response ) -``` - -**Description** - -Obtains the capacity information about the SCSI device. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device handle. For details, see [ScsiPeripheral_Device](#scsiperipheral_device).| -| request | Request of the **read capacity** command. For details, see [ScsiPeripheral_ReadCapacityRequest](_scsi_peripheral___read_capacity_request.md).| -| capacityInfo | Capacity information returned by the **read capacity** command. For details, see [ScsiPeripheral_CapacityInfo](_scsi_peripheral___capacity_info.md).| -| response | Original response returned by the **read capacity** command. For details, see [ScsiPeripheral_Response](_scsi_peripheral___response.md).| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL - -**Returns** - -- SCSIPERIPHERAL_DDK_SUCCESS: Operation succeeded. - -- SCSIPERIPHERAL_DDK_NO_PERM: Permission verification failed. - -- SCSIPERIPHERAL_DDK_INIT_ERROR: DDK not initialized. - -- SCSIPERIPHERAL_DDK_INVALID_PARAMETER: Empty dev, request, capacityInfo, or response. - -- SCSIPERIPHERAL_DDK_SERVICE_ERROR: DDK service communication error. - -- SCSIPERIPHERAL_DDK_MEMORY_ERROR: Memory operation error. - -- SCSIPERIPHERAL_DDK_IO_ERROR: DDK I/O error. - -- SCSIPERIPHERAL_DDK_TIMEOUT: Transfer timeout. - -- SCSIPERIPHERAL_DDK_INVALID_OPERATION: Operation not supported. - - -### OH_ScsiPeripheral_Release() - -``` -int32_t OH_ScsiPeripheral_Release (void ) -``` - -**Description** - -Releases the SCSI Peripheral DDK. - -**Since**: 18 - -**Required Permissions** - -ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL - -**Returns** - -- SCSIPERIPHERAL_DDK_SUCCESS: Operation succeeded. - -- SCSIPERIPHERAL_DDK_NO_PERM: Permission verification failed. - -- SCSIPERIPHERAL_DDK_INIT_ERROR: DDK not initialized. - -- SCSIPERIPHERAL_DDK_SERVICE_ERROR: DDK service communication error. - - -### OH_ScsiPeripheral_RequestSense() - -``` -int32_t OH_ScsiPeripheral_RequestSense (ScsiPeripheral_Device * dev, ScsiPeripheral_RequestSenseRequest * request, ScsiPeripheral_Response * response ) -``` - -**Description** - -Obtains sense data, that is, information returned by the SCSI device to the host to report the device status, error information, and diagnosis information. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device handle. For details, see [ScsiPeripheral_Device](#scsiperipheral_device).| -| request | Request of the **request sense** command. For details, see [ScsiPeripheral_RequestSenseRequest](_scsi_peripheral___request_sense_request.md).| -| response | Response returned by the **request sense** command. For details, see [ScsiPeripheral_Response](_scsi_peripheral___response.md).| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL - -**Returns** - -- SCSIPERIPHERAL_DDK_SUCCESS: Operation succeeded. - -- SCSIPERIPHERAL_DDK_NO_PERM: Permission verification failed. - -- SCSIPERIPHERAL_DDK_INIT_ERROR: DDK not initialized. - -- SCSIPERIPHERAL_DDK_INVALID_PARAMETER: Empty dev, request, or response. - -- SCSIPERIPHERAL_DDK_SERVICE_ERROR: DDK service communication error. - -- SCSIPERIPHERAL_DDK_MEMORY_ERROR: Memory operation error. - -- SCSIPERIPHERAL_DDK_IO_ERROR: DDK I/O error. - -- SCSIPERIPHERAL_DDK_TIMEOUT: Transfer timeout. - -- SCSIPERIPHERAL_DDK_INVALID_OPERATION: Operation not supported. - - -### OH_ScsiPeripheral_SendRequestByCdb() - -``` -int32_t OH_ScsiPeripheral_SendRequestByCdb (ScsiPeripheral_Device * dev, ScsiPeripheral_Request * request, ScsiPeripheral_Response * response ) -``` - -**Description** - -Sends SCSI commands in command descriptor block (CDB) mode. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device handle. For details, see [ScsiPeripheral_Device](#scsiperipheral_device).| -| request | Request. For details, see [ScsiPeripheral_Request](_scsi_peripheral___request.md).| -| response | Response. For details, see [ScsiPeripheral_Response](_scsi_peripheral___response.md).| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL - -**Returns** - -- SCSIPERIPHERAL_DDK_SUCCESS: Operation succeeded. - -- SCSIPERIPHERAL_DDK_NO_PERM: Permission verification failed. - -- SCSIPERIPHERAL_DDK_INIT_ERROR: DDK not initialized. - -- SCSIPERIPHERAL_DDK_INVALID_PARAMETER: Empty dev, request, request->data, or response, or invalid request->cdbLength value (0). - -- SCSIPERIPHERAL_DDK_SERVICE_ERROR: DDK service communication error. - -- SCSIPERIPHERAL_DDK_MEMORY_ERROR: Memory operation error. - -- SCSIPERIPHERAL_DDK_IO_ERROR: DDK I/O error. - -- SCSIPERIPHERAL_DDK_TIMEOUT: Transfer timeout. - -- SCSIPERIPHERAL_DDK_INVALID_OPERATION: Operation not supported. - - -### OH_ScsiPeripheral_TestUnitReady() - -``` -int32_t OH_ScsiPeripheral_TestUnitReady (ScsiPeripheral_Device * dev, ScsiPeripheral_TestUnitReadyRequest * request, ScsiPeripheral_Response * response ) -``` - -**Description** - -Checks whether the logical units are ready. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device handle. For details, see [ScsiPeripheral_Device](#scsiperipheral_device).| -| request | Request of the **test unit ready** command. For details, see [ScsiPeripheral_TestUnitReadyRequest](_scsi_peripheral___test_unit_ready_request.md).| -| response | Response returned by the **test unit ready** command. For details, see [ScsiPeripheral_Response](_scsi_peripheral___response.md).| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL - -**Returns** - -- SCSIPERIPHERAL_DDK_SUCCESS: Operation succeeded. - -- SCSIPERIPHERAL_DDK_NO_PERM: Permission verification failed. - -- SCSIPERIPHERAL_DDK_INIT_ERROR: DDK not initialized. - -- SCSIPERIPHERAL_DDK_INVALID_PARAMETER: Empty dev, request, or response. - -- SCSIPERIPHERAL_DDK_SERVICE_ERROR: DDK service communication error. - -- SCSIPERIPHERAL_DDK_MEMORY_ERROR: Memory operation error. - -- SCSIPERIPHERAL_DDK_IO_ERROR: DDK I/O error. - -- SCSIPERIPHERAL_DDK_TIMEOUT: Transfer timeout. - -- SCSIPERIPHERAL_DDK_INVALID_OPERATION: Operation not supported. - - -### OH_ScsiPeripheral_Verify10() - -``` -int32_t OH_ScsiPeripheral_Verify10 (ScsiPeripheral_Device * dev, ScsiPeripheral_VerifyRequest * request, ScsiPeripheral_Response * response ) -``` - -**Description** - -Verifies a specified logical block. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device handle. For details, see [ScsiPeripheral_Device](#scsiperipheral_device).| -| request | Request of the **verify** command. For details, see [ScsiPeripheral_VerifyRequest](_scsi_peripheral___verify_request.md).| -| response | Response returned by the **verify** command. For details, see [ScsiPeripheral_Response](_scsi_peripheral___response.md).| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL - -**Returns** - -- SCSIPERIPHERAL_DDK_SUCCESS: Operation succeeded. - -- SCSIPERIPHERAL_DDK_NO_PERM: Permission verification failed. - -- SCSIPERIPHERAL_DDK_INIT_ERROR: DDK not initialized. - -- SCSIPERIPHERAL_DDK_INVALID_PARAMETER: Empty dev, request, or response. - -- SCSIPERIPHERAL_DDK_SERVICE_ERROR: DDK service communication error. - -- SCSIPERIPHERAL_DDK_MEMORY_ERROR: Memory operation error. - -- SCSIPERIPHERAL_DDK_IO_ERROR: DDK I/O error. - -- SCSIPERIPHERAL_DDK_TIMEOUT: Transfer timeout. - -- SCSIPERIPHERAL_DDK_INVALID_OPERATION: Operation not supported. - - -### OH_ScsiPeripheral_Write10() - -``` -int32_t OH_ScsiPeripheral_Write10 (ScsiPeripheral_Device * dev, ScsiPeripheral_IORequest * request, ScsiPeripheral_Response * response ) -``` - -**Description** - -Writes data to a specified logical block of a device. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device handle. For details, see [ScsiPeripheral_Device](#scsiperipheral_device).| -| request | Request of the **write** command. For details, see [ScsiPeripheral_IORequest](_scsi_peripheral___i_o_request.md).| -| response | Response returned by the **write** command. For details, see [ScsiPeripheral_Response](_scsi_peripheral___response.md).| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL - -**Returns** - -- SCSIPERIPHERAL_DDK_SUCCESS: Operation succeeded. - -- SCSIPERIPHERAL_DDK_NO_PERM: Permission verification failed. - -- SCSIPERIPHERAL_DDK_INIT_ERROR: DDK not initialized. - -- SCSIPERIPHERAL_DDK_INVALID_PARAMETER: Empty dev, request, request->data, or response. - -- SCSIPERIPHERAL_DDK_SERVICE_ERROR: DDK service communication error. - -- SCSIPERIPHERAL_DDK_MEMORY_ERROR: Memory operation error. - -- SCSIPERIPHERAL_DDK_IO_ERROR: DDK I/O error. - -- SCSIPERIPHERAL_DDK_TIMEOUT: Transfer timeout. - -- SCSIPERIPHERAL_DDK_INVALID_OPERATION: Operation not supported. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___basic_sense_info.md b/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___basic_sense_info.md deleted file mode 100644 index 9fe4d5e6a6e..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___basic_sense_info.md +++ /dev/null @@ -1,96 +0,0 @@ -# ScsiPeripheral_BasicSenseInfo - - -## Overview - -Basic information about the sense data. - -**Since**: 18 - -**Related module**: [SCSI Peripheral DDK](_s_c_s_i.md) - -**Header file**: [scsi_peripheral_types.h](scsi__peripheral__types_8h.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| uint8_t [responseCode](#responsecode) | Response code.| -| bool [valid](#valid) | Information validity flag.| -| uint64_t [information](#information) | **Information** field.| -| uint64_t [commandSpecific](#commandspecific) | **Command-specific information** field.| -| bool [sksv](#sksv) | **Sense key specific** field flag.| -| uint32_t [senseKeySpecific](#sensekeyspecific) | **Sense key specific** field.| - - -## Member Variable Description - - -### commandSpecific - -``` -uint64_t ScsiPeripheral_BasicSenseInfo::commandSpecific -``` - -**Description** - -**Command-specific information** field. - - -### information - -``` -uint64_t ScsiPeripheral_BasicSenseInfo::information -``` - -**Description** - -**Information** field. - - -### responseCode - -``` -uint8_t ScsiPeripheral_BasicSenseInfo::responseCode -``` - -**Description** - -Response code. - - -### senseKeySpecific - -``` -uint32_t ScsiPeripheral_BasicSenseInfo::senseKeySpecific -``` - -**Description** - -**Sense key specific** field. - - -### sksv - -``` -bool ScsiPeripheral_BasicSenseInfo::sksv -``` - -**Description** - -**Sense key specific** field flag. - - -### valid - -``` -bool ScsiPeripheral_BasicSenseInfo::valid -``` - -**Description** - -Information validity flag. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___capacity_info.md b/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___capacity_info.md deleted file mode 100644 index dd7bd5981bb..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___capacity_info.md +++ /dev/null @@ -1,48 +0,0 @@ -# ScsiPeripheral_CapacityInfo - - -## Overview - -Defines the SCSI read capacity. - -**Since**: 18 - -**Related module**: [SCSI Peripheral DDK](_s_c_s_i.md) - -**Header file**: [scsi_peripheral_types.h](scsi__peripheral__types_8h.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| uint32_t [lbAddress](#lbaddress) | Address of the logical unit.| -| uint32_t [lbLength](#lblength) | Length of a single logical unit, in bytes.| - - -## Member Variable Description - - -### lbAddress - -``` -uint32_t ScsiPeripheral_CapacityInfo::lbAddress -``` - -**Description** - -Address of the logical unit. - - -### lbLength - -``` -uint32_t ScsiPeripheral_CapacityInfo::lbLength -``` - -**Description** - -Length of a single logical unit, in bytes. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___device_mem_map.md b/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___device_mem_map.md deleted file mode 100644 index 42f677db834..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___device_mem_map.md +++ /dev/null @@ -1,84 +0,0 @@ -# ScsiPeripheral_DeviceMemMap - - -## Overview - -Represents the device memory mapping created by calling **OH_ScsiPeripheral_CreateDeviceMemMap**. The buffer that uses the device memory mapping can provide better performance. - -**Since**: 18 - -**Related module**: [SCSI Peripheral DDK](_s_c_s_i.md) - -**Header file**: [scsi_peripheral_types.h](scsi__peripheral__types_8h.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| uint8_t \*const [address](#address) | Buffer address.| -| const size_t [size](#size) | Buffer size.| -| uint32_t [offset](#offset) | Offset of the used buffer. The default value is **0**, indicating that there is no offset and the buffer starts from the specified address.| -| uint32_t [bufferLength](#bufferlength) | Length of the used buffer. By default, the value is equal to the size of the buffer, indicating that the entire buffer is used.| -| uint32_t [transferredLength](#transferredlength) | Length of the data to be transferred.| - - -## Member Variable Description - - -### address - -``` -uint8_t* const ScsiPeripheral_DeviceMemMap::address -``` - -**Description** - -Buffer address. - - -### bufferLength - -``` -uint32_t ScsiPeripheral_DeviceMemMap::bufferLength -``` - -**Description** - -Length of the used buffer. By default, the value is equal to the size of the buffer, indicating that the entire buffer is used. - - -### offset - -``` -uint32_t ScsiPeripheral_DeviceMemMap::offset -``` - -**Description** - -Offset of the used buffer. The default value is **0**, indicating that there is no offset and the buffer starts from the specified address. - - -### size - -``` -const size_t ScsiPeripheral_DeviceMemMap::size -``` - -**Description** - -Buffer size. - - -### transferredLength - -``` -uint32_t ScsiPeripheral_DeviceMemMap::transferredLength -``` - -**Description** - -Length of the data to be transferred. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___i_o_request.md b/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___i_o_request.md deleted file mode 100644 index b2ce1a783b6..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___i_o_request.md +++ /dev/null @@ -1,108 +0,0 @@ -# ScsiPeripheral_IORequest - - -## Overview - -Defines the read/write operation request. - -**Since**: 18 - -**Related module**: [SCSI Peripheral DDK](_s_c_s_i.md) - -**Header file**: [scsi_peripheral_types.h](scsi__peripheral__types_8h.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| uint32_t [lbAddress](#lbaddress) | Start address of a logical block.| -| uint16_t [transferLength](#transferlength) | Number of consecutive logical blocks to be operated.| -| uint8_t [control](#control) | **Control** field used to specify control information.| -| uint8_t [byte1](#byte1) | First byte of the CDB.| -| uint8_t [byte6](#byte6) | Sixth byte of the CDB.| -| [ScsiPeripheral_DeviceMemMap](_scsi_peripheral___device_mem_map.md) \* [data](#data) | Buffer for data transmission.| -| uint32_t [timeout](#timeout) | Timeout duration, in ms.| - - -## Member Variable Description - - -### byte1 - -``` -uint8_t ScsiPeripheral_IORequest::byte1 -``` - -**Description** - -First byte of the CDB. - - -### byte6 - -``` -uint8_t ScsiPeripheral_IORequest::byte6 -``` - -**Description** - -Sixth byte of the CDB. - - -### control - -``` -uint8_t ScsiPeripheral_IORequest::control -``` - -**Description** - -**Control** field used to specify control information. - - -### data - -``` -ScsiPeripheral_DeviceMemMap* ScsiPeripheral_IORequest::data -``` - -**Description** - -Buffer for data transmission. - - -### lbAddress - -``` -uint32_t ScsiPeripheral_IORequest::lbAddress -``` - -**Description** - -Start address of a logical block. - - -### timeout - -``` -uint32_t ScsiPeripheral_IORequest::timeout -``` - -**Description** - -Timeout duration, in ms. - - -### transferLength - -``` -uint16_t ScsiPeripheral_IORequest::transferLength -``` - -**Description** - -Number of consecutive logical blocks to be operated. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___inquiry_info.md b/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___inquiry_info.md deleted file mode 100644 index 6de21d09b34..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___inquiry_info.md +++ /dev/null @@ -1,84 +0,0 @@ -# ScsiPeripheral_InquiryInfo - - -## Overview - -Defines the SCSI inquiry data. - -**Since**: 18 - -**Related module**: [SCSI Peripheral DDK](_s_c_s_i.md) - -**Header file**: [scsi_peripheral_types.h](scsi__peripheral__types_8h.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| uint8_t [deviceType](#devicetype) | Device type.| -| char [idVendor](#idvendor) [[SCSIPERIPHERAL_VENDOR_ID_LEN](_s_c_s_i.md#scsiperipheral_vendor_id_len)+1] | Vendor ID.| -| char [idProduct](#idproduct) [[SCSIPERIPHERAL_PRODUCT_ID_LEN](_s_c_s_i.md#scsiperipheral_product_id_len)+1] | Product ID.| -| char [revProduct](#revproduct) [[SCSIPERIPHERAL_PRODUCT_REV_LEN](_s_c_s_i.md#scsiperipheral_product_rev_len)+1] | Product version.| -| [ScsiPeripheral_DeviceMemMap](_scsi_peripheral___device_mem_map.md) \* [data](#data) | Inquiry data.| - - -## Member Variable Description - - -### data - -``` -ScsiPeripheral_DeviceMemMap* ScsiPeripheral_InquiryInfo::data -``` - -**Description** - -Inquiry data. - - -### deviceType - -``` -uint8_t ScsiPeripheral_InquiryInfo::deviceType -``` - -**Description** - -Device type. - - -### idProduct - -``` -char ScsiPeripheral_InquiryInfo::idProduct[SCSIPERIPHERAL_PRODUCT_ID_LEN+1] -``` - -**Description** - -Product ID. - - -### idVendor - -``` -char ScsiPeripheral_InquiryInfo::idVendor[SCSIPERIPHERAL_VENDOR_ID_LEN+1] -``` - -**Description** - -Vendor ID. - - -### revProduct - -``` -char ScsiPeripheral_InquiryInfo::revProduct[SCSIPERIPHERAL_PRODUCT_REV_LEN+1] -``` - -**Description** - -Product version. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___inquiry_request.md b/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___inquiry_request.md deleted file mode 100644 index 69df6cf754b..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___inquiry_request.md +++ /dev/null @@ -1,84 +0,0 @@ -# ScsiPeripheral_InquiryRequest - - -## Overview - -Defines the request structure of the **inquiry** command. - -**Since**: 18 - -**Related module**: [SCSI Peripheral DDK](_s_c_s_i.md) - -**Header file**: [scsi_peripheral_types.h](scsi__peripheral__types_8h.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| uint8_t [pageCode](#pagecode) | **Page code** field. Set this filed if you want to obtain certain types of device information. When an **Inquiry** command with a specific page code is run, the device returns details related to the page code. If the page code is set to **0x00**, it indicates that the standard inquiry data rather than the data of specific pages is requested.| -| uint16_t [allocationLength](#allocationlength) | **Allocation length** field used to specify the size of the buffer prepared by the request initiator (usually the host) for the response data.| -| uint8_t [control](#control) | **Control** field used to specify control information.| -| uint8_t [byte1](#byte1) | First byte of the CDB.| -| uint32_t [timeout](#timeout) | Timeout duration, in ms.| - - -## Member Variable Description - - -### allocationLength - -``` -uint16_t ScsiPeripheral_InquiryRequest::allocationLength -``` - -**Description** - -**Allocation length** field used to specify the size of the buffer prepared by the request initiator (usually the host) for the response data. - - -### byte1 - -``` -uint8_t ScsiPeripheral_InquiryRequest::byte1 -``` - -**Description** - -First byte of the CDB. - - -### control - -``` -uint8_t ScsiPeripheral_InquiryRequest::control -``` - -**Description** - -**Control** field used to specify control information. - - -### pageCode - -``` -uint8_t ScsiPeripheral_InquiryRequest::pageCode -``` - -**Description** - -**Page code** field. Set this filed if you want to obtain certain types of device information. When an **Inquiry** command with a specific page code is run, the device returns details related to the page code. If the page code is set to **0x00**, it indicates that the standard inquiry data rather than the data of specific pages is requested. - - -### timeout - -``` -uint32_t ScsiPeripheral_InquiryRequest::timeout -``` - -**Description** - -Timeout duration, in ms. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___read_capacity_request.md b/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___read_capacity_request.md deleted file mode 100644 index f4c4bde05f1..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___read_capacity_request.md +++ /dev/null @@ -1,72 +0,0 @@ -# ScsiPeripheral_ReadCapacityRequest - - -## Overview - -Request structure of the **read capacity** command. - -**Since**: 18 - -**Related module**: [SCSI Peripheral DDK](_s_c_s_i.md) - -**Header file**: [scsi_peripheral_types.h](scsi__peripheral__types_8h.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| uint32_t [lbAddress](#lbaddress) | Address of the logical unit.| -| uint8_t [control](#control) | Control field used to specify control information.| -| uint8_t [byte8](#byte8) | Eighth byte of the CDB.| -| uint32_t [timeout](#timeout) | Timeout duration, in ms.| - - -## Member Variable Description - - -### byte8 - -``` -uint8_t ScsiPeripheral_ReadCapacityRequest::byte8 -``` - -**Description** - -Eighth byte of the CDB. - - -### control - -``` -uint8_t ScsiPeripheral_ReadCapacityRequest::control -``` - -**Description** - -Control field used to specify control information. - - -### lbAddress - -``` -uint32_t ScsiPeripheral_ReadCapacityRequest::lbAddress -``` - -**Description** - -Address of the logical unit. - - -### timeout - -``` -uint32_t ScsiPeripheral_ReadCapacityRequest::timeout -``` - -**Description** - -Timeout duration, in ms. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___request.md b/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___request.md deleted file mode 100644 index bfbcd4b6738..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___request.md +++ /dev/null @@ -1,84 +0,0 @@ -# ScsiPeripheral_Request - - -## Overview - -Defines the request structure. - -**Since**: 18 - -**Related module**: [SCSI Peripheral DDK](_s_c_s_i.md) - -**Header file**: [scsi_peripheral_types.h](scsi__peripheral__types_8h.md) - - -## Summary - - -### Member Variables - -| **Name**| Description| -| -------- | -------- | -| uint8_t [commandDescriptorBlock](#commanddescriptorblock) [[SCSIPERIPHERAL_MAX_CMD_DESC_BLOCK_LEN](_s_c_s_i.md#scsiperipheral_max_cmd_desc_block_len)] | Command descriptor block.| -| uint8_t [cdbLength](#cdblength) | Length of the command descriptor block.| -| int8_t [dataTransferDirection](#datatransferdirection) | Data transmission direction.| -| [ScsiPeripheral_DeviceMemMap](_scsi_peripheral___device_mem_map.md) \* [data](#data) | Buffer for data transmission.| -| uint32_t [timeout](#timeout) | Timeout duration, in ms.| - - -## Member Variable Description - - -### cdbLength - -``` -uint8_t ScsiPeripheral_Request::cdbLength -``` - -**Description** - -Length of the command descriptor block. - - -### commandDescriptorBlock - -``` -uint8_t ScsiPeripheral_Request::commandDescriptorBlock[SCSIPERIPHERAL_MAX_CMD_DESC_BLOCK_LEN] -``` - -**Description** - -Command descriptor block. - - -### data - -``` -ScsiPeripheral_DeviceMemMap* ScsiPeripheral_Request::data -``` - -**Description** - -Buffer for data transmission. - - -### dataTransferDirection - -``` -int8_t ScsiPeripheral_Request::dataTransferDirection -``` - -**Description** - -Data transmission direction. - - -### timeout - -``` -uint32_t ScsiPeripheral_Request::timeout -``` - -**Description** - -Timeout duration, in ms. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___request_sense_request.md b/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___request_sense_request.md deleted file mode 100644 index 5628a3ba1fc..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___request_sense_request.md +++ /dev/null @@ -1,72 +0,0 @@ -# ScsiPeripheral_RequestSenseRequest - - -## Overview - -Defines the request structure of the **request sense** command. - -**Since**: 18 - -**Related module**: [SCSI Peripheral DDK](_s_c_s_i.md) - -**Header file**: [scsi_peripheral_types.h](scsi__peripheral__types_8h.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| uint8_t [allocationLength](#allocationlength) | **Allocation length** field used to specify the size of the buffer prepared by the request initiator (usually the host) for the response data.| -| uint8_t [control](#control) | **Control** field used to specify control information.| -| uint8_t [byte1](#byte1) | First byte of the CDB.| -| uint32_t [timeout](#timeout) | Timeout duration, in ms.| - - -## Member Variable Description - - -### allocationLength - -``` -uint8_t ScsiPeripheral_RequestSenseRequest::allocationLength -``` - -**Description** - -**Allocation length** field used to specify the size of the buffer prepared by the request initiator (usually the host) for the response data. - - -### byte1 - -``` -uint8_t ScsiPeripheral_RequestSenseRequest::byte1 -``` - -**Description** - -First byte of the CDB. - - -### control - -``` -uint8_t ScsiPeripheral_RequestSenseRequest::control -``` - -**Description** - -**Control** field used to specify control information. - - -### timeout - -``` -uint32_t ScsiPeripheral_RequestSenseRequest::timeout -``` - -**Description** - -Timeout duration, in ms. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___response.md b/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___response.md deleted file mode 100644 index 75ae2817aea..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___response.md +++ /dev/null @@ -1,132 +0,0 @@ -# ScsiPeripheral_Response - - -## Overview - -Defines the response structure. - -**Since**: 18 - -**Related module**: [SCSI Peripheral DDK](_s_c_s_i.md) - -**Header file**: [scsi_peripheral_types.h](scsi__peripheral__types_8h.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| uint8_t [senseData](#sensedata) [[SCSIPERIPHERAL_MAX_SENSE_DATA_LEN](_s_c_s_i.md#scsiperipheral_max_sense_data_len)] | Sense data, that is, information returned by the SCSI device to the host to report the device status, error information, and diagnosis information.| -| [ScsiPeripheral_Status](_s_c_s_i.md#scsiperipheral_status) [status](#status) | Status when the call is complete, for example, **Good** or **Busy**.| -| uint8_t [maskedStatus](#maskedstatus) | Masked status, which is used in SCSI Generic (SG) interfaces of Linux to store the processed SCSI status for easy access by applications.| -| uint8_t [msgStatus](#msgstatus) | Message status.| -| uint8_t [sbLenWr](#sblenwr) | Number of bytes that are actually written to the sense buffer.| -| uint16_t [hostStatus](#hoststatus) | Host adapter status, for example, success (0x00), connection failure (0x01), busy bus (0x02), or timeout (0x03).| -| uint16_t [driverStatus](#driverstatus) | Driver status, for example, success (0x00) or busy device or resource (0x01).| -| int32_t [resId](#resid) | Length deviation of the actually transmitted data, that is, the number of bytes that are not transmitted.| -| uint32_t [duration](#duration) | Command execution duration, in ms.| - - -## Member Variable Description - - -### driverStatus - -``` -uint16_t ScsiPeripheral_Response::driverStatus -``` - -**Description** - -Driver status, for example, success (0x00) or busy device or resource (0x01). - - -### duration - -``` -uint32_t ScsiPeripheral_Response::duration -``` - -**Description** - -Command execution duration, in ms. - - -### hostStatus - -``` -uint16_t ScsiPeripheral_Response::hostStatus -``` - -**Description** - -Host adapter status, for example, success (0x00), connection failure (0x01), busy bus (0x02), or timeout (0x03). - - -### maskedStatus - -``` -uint8_t ScsiPeripheral_Response::maskedStatus -``` - -**Description** - -Masked status, which is used in SCSI Generic (SG) interfaces of Linux to store the processed SCSI status for easy access by applications. - - -### msgStatus - -``` -uint8_t ScsiPeripheral_Response::msgStatus -``` - -**Description** - -Message status. - - -### resId - -``` -int32_t ScsiPeripheral_Response::resId -``` - -**Description** - -Length deviation of the actually transmitted data, that is, the number of bytes that are not transmitted. - - -### sbLenWr - -``` -uint8_t ScsiPeripheral_Response::sbLenWr -``` - -**Description** - -Number of bytes that are actually written to the sense buffer. - - -### senseData - -``` -uint8_t ScsiPeripheral_Response::senseData[SCSIPERIPHERAL_MAX_SENSE_DATA_LEN] -``` - -**Description** - -Sense data, that is, information returned by the SCSI device to the host to report the device status, error information, and diagnosis information. - - -### status - -``` -ScsiPeripheral_Status ScsiPeripheral_Response::status -``` - -**Description** - -Status when the call is complete, for example, **Good** or **Busy**. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___test_unit_ready_request.md b/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___test_unit_ready_request.md deleted file mode 100644 index da744c31548..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___test_unit_ready_request.md +++ /dev/null @@ -1,48 +0,0 @@ -# ScsiPeripheral_TestUnitReadyRequest - - -## Overview - -Defines the request structure of the **test unit ready** command. - -**Since**: 18 - -**Related module**: [SCSI Peripheral DDK](_s_c_s_i.md) - -**Header file**: [scsi_peripheral_types.h](scsi__peripheral__types_8h.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| uint8_t [control](#control) | **Control** field used to specify control information.| -| uint32_t [timeout](#timeout) | Timeout duration, in ms.| - - -## Member Variable Description - - -### control - -``` -uint8_t ScsiPeripheral_TestUnitReadyRequest::control -``` - -**Description** - -**Control** field used to specify control information. - - -### timeout - -``` -uint32_t ScsiPeripheral_TestUnitReadyRequest::timeout -``` - -**Description** - -Timeout duration, in ms. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___verify_request.md b/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___verify_request.md deleted file mode 100644 index 676992b1f0f..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_scsi_peripheral___verify_request.md +++ /dev/null @@ -1,96 +0,0 @@ -# ScsiPeripheral_VerifyRequest - - -## Overview - -Request structure of the **verify** command. - -**Since**: 18 - -**Related module**: [SCSI Peripheral DDK](_s_c_s_i.md) - -**Header file**: [scsi_peripheral_types.h](scsi__peripheral__types_8h.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| uint32_t [lbAddress](#lbaddress) | Start address of logical blocks.| -| uint16_t [verificationLength](#verificationlength) | Number of consecutive logical blocks.| -| uint8_t [control](#control) | **Control** field used to specify control information.| -| uint8_t [byte1](#byte1) | First byte of the CDB.| -| uint8_t [byte6](#byte6) | Sixth byte of the CDB.| -| uint32_t [timeout](#timeout) | Timeout duration, in ms.| - - -## Member Variable Description - - -### byte1 - -``` -uint8_t ScsiPeripheral_VerifyRequest::byte1 -``` - -**Description** - -First byte of the CDB. - - -### byte6 - -``` -uint8_t ScsiPeripheral_VerifyRequest::byte6 -``` - -**Description** - -Sixth byte of the CDB. - - -### control - -``` -uint8_t ScsiPeripheral_VerifyRequest::control -``` - -**Description** - -**Control** field used to specify control information. - - -### lbAddress - -``` -uint32_t ScsiPeripheral_VerifyRequest::lbAddress -``` - -**Description** - -Start address of logical blocks. - - -### timeout - -``` -uint32_t ScsiPeripheral_VerifyRequest::timeout -``` - -**Description** - -Timeout duration, in ms. - - -### verificationLength - -``` -uint16_t ScsiPeripheral_VerifyRequest::verificationLength -``` - -**Description** - -Number of consecutive logical blocks. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_serial_ddk.md b/en/application-dev/reference/apis-driverdevelopment-kit/_serial_ddk.md deleted file mode 100644 index df107b6b93a..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_serial_ddk.md +++ /dev/null @@ -1,670 +0,0 @@ -# USB Serial DDK - -## Overview - -USB Serial DDK is a development kit for USB drivers. This module provides USB Serial DDK APIs as well as the enum types and data structs used by them. - -Serial port communication is often used in industrial scenarios and some legacy devices, such as card issuers and ID card readers. By using the USB Serial DDK APIs, you can develop extended drivers for non-standard peripherals to implement extended functions for USB serial port devices. - -**System capability**: SystemCapability.Driver.SERIAL.Extension - -**Since**: 18 - - -## Summary - - -### Files - -| Name| Description| -| -------- | -------- | -| [usb_serial_ddk_api.h](usb__serial__ddk__api_8h.md) | Declares the USB Serial DDK APIs used by the host to access the serial port device.
**File to include**: <serial/usb_serial_ddk_api.h>
**Library**: libusb_serial.z.so| -| [usb_serial_types.h](usb__serial__ddk__types_8h.md) | Provides the enum variables, structures, and macros used in USB Serial DDK APIs.
**File to include**: <serial/usb_serial_types.h>
**Library**: libusb_serial.z.so| - - -### Structs - -| Name| Description| -| -------- | -------- | -| struct  [UsbSerial_Params](_usb_serial___params.md) | Defines the USB serial port parameters for the USB Serial DDK.| - - -### Types - -| Name| Description| -| -------- | -------- | -| typedef struct [UsbSerial_DeviceHandle](#usbserial_devicehandle) [UsbSerial_DeviceHandle](#usbserial_devicehandle) | Defines the data structures for the USB serial port device (opaque).| -| typedef struct [UsbSerial_Params](_usb_serial___params.md) \__attribute\__((aligned(8))) [UsbSerial_Params](_usb_serial___params.md) | Defines the USB serial port parameters used by the USB Serial DDK.| - - -### Enums - -| Name| Description| -| -------- | -------- | -| [UsbSerial_DdkRetCode](#usbserial_ddkretcode) {
USB_SERIAL_DDK_NO_PERM = 201, USB_SERIAL_DDK_INVALID_PARAMETER = 401, USB_SERIAL_DDK_SUCCESS = 31600000, USB_SERIAL_DDK_INVALID_OPERATION = 31600001, USB_SERIAL_DDK_INIT_ERROR = 31600002, USB_SERIAL_DDK_SERVICE_ERROR = 31600003, USB_SERIAL_DDK_MEMORY_ERROR = 31600004, USB_SERIAL_DDK_IO_ERROR = 31600005, USB_SERIAL_DDK_DEVICE_NOT_FOUND = 31600006
} | Defines the return codes used by the USB Serial DDK.| -| [UsbSerial_FlowControl](#usbserial_flowcontrol) { USB_SERIAL_NO_FLOW_CONTROL = 0, USB_SERIAL_SOFTWARE_FLOW_CONTROL = 1, USB_SERIAL_HARDWARE_FLOW_CONTROL = 2 } | Defines the flow control in the USB Serial DDK.| -| [UsbSerial_Parity](#usbserial_parity) { USB_SERIAL_PARITY_NONE = 0, USB_SERIAL_PARITY_ODD = 1, USB_SERIAL_PARITY_EVEN = 2 } | Defines the enums of the parity parameter used by the USB Serial DDK.| - - -### Functions - -| Name| Description| -| -------- | -------- | -| int32_t [OH_UsbSerial_Init](#oh_usbserial_init) (void) | Initializes the USB Serial DDK.| -| int32_t [OH_UsbSerial_Release](#oh_usbserial_release) (void) | Releases the USB Serial DDK.| -| int32_t [OH_UsbSerial_Open](#oh_usbserial_open) (uint64_t deviceId, uint8_t interfaceIndex, [UsbSerial_DeviceHandle](#usbserial_devicehandle) \*\*dev) | Enables the USB serial port device based on the specified **deviceId** and **interfaceIndex**.| -| int32_t [OH_UsbSerial_Close](#oh_usbserial_close) ([UsbSerial_DeviceHandle](#usbserial_devicehandle) \*dev) | Disables the USB serial port device.| -| int32_t [OH_UsbSerial_Read](#oh_usbserial_read) ([UsbSerial_DeviceHandle](#usbserial_devicehandle) \*dev, uint8_t \*buff, uint32_t bufferSize, uint32_t \*bytesRead) | Reads data from the USB serial port device to the buffer.| -| int32_t [OH_UsbSerial_Write](#oh_usbserial_write) ([UsbSerial_DeviceHandle](#usbserial_devicehandle) \*dev, uint8_t \*buff, uint32_t bufferSize, uint32_t \*bytesWritten) | Writes the data in the buffer to the USB serial port device.| -| int32_t [OH_UsbSerial_SetBaudRate](#oh_usbserial_setbaudrate) ([UsbSerial_DeviceHandle](#usbserial_devicehandle) \*dev, uint32_t [baudRate](usb__serial__ddk__types_8h.md#baudrate)) | Sets the baud rate for a USB serial port device. If the parameters of the USB serial port device are set to the default values (the data bit is **8**, the stop bit is **1**, and parity is disabled for data transfer), you only need to call this API to set the baud rate.| -| int32_t [OH_UsbSerial_SetParams](#oh_usbserial_setparams) ([UsbSerial_DeviceHandle](#usbserial_devicehandle) \*dev, [UsbSerial_Params](_usb_serial___params.md) \*params) | Sets the parameters of the USB serial port device. If the parameters of the USB serial port device are not set to the default values (the data bit is **8**, the stop bit is **1**, and parity is disabled for data transfer), you only need to call this API to set the related parameters.| -| int32_t [OH_UsbSerial_SetTimeout](#oh_usbserial_settimeout) ([UsbSerial_DeviceHandle](#usbserial_devicehandle) \*dev, int timeout) | Sets the timeout interval (ms) for reading data reported by a USB serial port device. If this function is not called, the timeout value is **0** by default, indicating that data is returned immediately regardless of whether data is read. If you need to wait for a certain period of time or data must be read, call this API to set the timeout interval.| -| int32_t [OH_UsbSerial_SetFlowControl](#oh_usbserial_setflowcontrol) ([UsbSerial_DeviceHandle](#usbserial_devicehandle) \*dev, [UsbSerial_FlowControl](#usbserial_flowcontrol) flowControl) | Sets flow control parameters. Flow control is used to manage the data transfer rate during communication with the USB serial port device to ensure that the sender does not send data that exceeds the processing capability of the receiver.
If flow control is required, call this API to set flow control parameters. If this API is not called, flow control is not performed by default.| -| int32_t [OH_UsbSerial_Flush](#oh_usbserial_flush) ([UsbSerial_DeviceHandle](#usbserial_devicehandle) \*dev) | Clears the input and output buffers after the write operation is complete. If a large amount of data is to be transmitted to the USB serial port device, the data may be buffered in the kernel for transmission. If the application closes the file descriptor or exits before the data is completely sent out, some data may be lost. You can call this API to ensure that all data is sent before subsequent operations are performed.| -| int32_t [OH_UsbSerial_FlushInput](#oh_usbserial_flushinput) ([UsbSerial_DeviceHandle](#usbserial_devicehandle) \*dev) | Refreshes the input buffer. The data in the buffer is cleared immediately. During the communication with the USB serial port device, especially in the debugging phase, disordered data packets or other exceptions may occur.
You can call this API to clear these exceptions to restore the communication.| -| int32_t [OH_UsbSerial_FlushOutput](#oh_usbserial_flushoutput) ([UsbSerial_DeviceHandle](#usbserial_devicehandle) \*dev) | Refreshes the output buffer. The data in the buffer is cleared immediately. During the communication with the USB serial port device, especially in the debugging phase, disordered data packets or other exceptions may occur.
You can call this API to clear these exceptions to restore the communication.| - - -## Type Description - - -### UsbSerial_DeviceHandle - -``` -typedef struct UsbSerial_DeviceHandle UsbSerial_DeviceHandle -``` - -**Description** - -Defines the data structures for the USB serial port device (opaque). - -**Since**: 18 - - -### UsbSerial_Params - -``` -typedef struct UsbSerial_Params \__attribute\__((aligned(8))) UsbSerial_Params -``` - -**Description** - -Defines the USB serial port parameters for the USB Serial DDK. - -**Since**: 18 - - -## Enum Description - - -### UsbSerial_DdkRetCode - -``` -enum UsbSerial_DdkRetCode -``` - -**Description** - -Defines the return codes used by the USB Serial DDK. - -**Since**: 18 - -| Value| Description| -| -------- | -------- | -| USB_SERIAL_DDK_NO_PERM | No access permission.| -| USB_SERIAL_DDK_INVALID_PARAMETER | Invalid parameter.| -| USB_SERIAL_DDK_SUCCESS | Operation succeeded.| -| USB_SERIAL_DDK_INVALID_OPERATION | Invalid operation.| -| USB_SERIAL_DDK_INIT_ERROR | Initialization error.| -| USB_SERIAL_DDK_SERVICE_ERROR | Service error.| -| USB_SERIAL_DDK_MEMORY_ERROR | Memory-related errors, such as insufficient memory, memory data replication failure, or memory application fault.| -| USB_SERIAL_DDK_IO_ERROR | I/O error.| -| USB_SERIAL_DDK_DEVICE_NOT_FOUND | Device not found.| - - -### UsbSerial_FlowControl - -``` -enum UsbSerial_FlowControl -``` - -**Description** - -Defines the flow control mode for the USB Serial DDK. - -**Since**: 18 - -| Value| Description| -| -------- | -------- | -| USB_SERIAL_NO_FLOW_CONTROL | No flow control.| -| USB_SERIAL_SOFTWARE_FLOW_CONTROL | Software flow control.| -| USB_SERIAL_HARDWARE_FLOW_CONTROL | Hardware flow control.| - - -### UsbSerial_Parity - -``` -enum UsbSerial_Parity -``` - -**Description** - -Defines the enums of the parity parameter used by the USB Serial DDK. - -**Since**: 18 - -| Value| Description| -| -------- | -------- | -| USB_SERIAL_PARITY_NONE | No parity.| -| USB_SERIAL_PARITY_ODD | Odd parity.| -| USB_SERIAL_PARITY_EVEN | Even parity.| - - -## Function Description - - -### OH_UsbSerial_Close() - -``` -int32_t OH_UsbSerial_Close (UsbSerial_DeviceHandle * dev) -``` - -**Description** - -Disables the USB serial port device. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device handle.| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_USB_SERIAL - -**Returns** - -- USB_SERIAL_DDK_SUCCESS: Operation succeeded. - -- USB_SERIAL_DDK_NO_PERM: Permission verification failed. - -- USB_SERIAL_DDK_INVALID_PARAMETER: Parameter verification failed. Possible cause: The input **dev** is a null pointer. - -- USB_SERIAL_DDK_INIT_ERROR: DDK initialization error. - -- USB_SERIAL_DDK_SERVICE_ERROR: DDK service communication error. - -- USB_SERIAL_DDK_IO_ERROR: DDK I/O error. - -- USB_SERIAL_DDK_INVALID_OPERATION: Invalid operation. - - -### OH_UsbSerial_Flush() - -``` -int32_t OH_UsbSerial_Flush (UsbSerial_DeviceHandle * dev) -``` - -**Description** - -Clears the input and output buffers after the write operation is complete. - -If a large amount of data is to be transmitted to the USB serial port device, the data may be buffered in the kernel for transmission. If the application closes the file descriptor or exits before the data is completely sent out, some data may be lost. You can call this API to ensure that all data is sent before subsequent operations are performed. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device handle.| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_USB_SERIAL - -**Returns** - -- USB_SERIAL_DDK_SUCCESS: Operation succeeded. - -- USB_SERIAL_DDK_NO_PERM: Permission verification failed. - -- USB_SERIAL_DDK_INVALID_PARAMETER: Parameter verification failed. Possible cause: The input **dev** is a null pointer. - -- USB_SERIAL_DDK_INIT_ERROR: DDK initialization error. - -- USB_SERIAL_DDK_SERVICE_ERROR: DDK service communication error. - -- USB_SERIAL_DDK_IO_ERROR: DDK I/O error. - -- USB_SERIAL_DDK_INVALID_OPERATION: Invalid operation. - - -### OH_UsbSerial_FlushInput() - -``` -int32_t OH_UsbSerial_FlushInput (UsbSerial_DeviceHandle * dev) -``` - -**Description** - -Refreshes the input buffer. The data in the buffer is cleared immediately. During the communication with the USB serial port device, especially in the debugging phase, disordered data packets or other exceptions may occur. - -You can call this API to clear these exceptions to restore the communication. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device handle.| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_USB_SERIAL - -**Returns** - -- USB_SERIAL_DDK_SUCCESS: Operation succeeded. - -- USB_SERIAL_DDK_NO_PERM: Permission verification failed. - -- USB_SERIAL_DDK_INVALID_PARAMETER: Parameter verification failed. Possible cause: The input **dev** is a null pointer. - -- USB_SERIAL_DDK_INIT_ERROR: DDK initialization error. - -- USB_SERIAL_DDK_SERVICE_ERROR: DDK service communication error. - -- USB_SERIAL_DDK_IO_ERROR: DDK I/O error. - -- USB_SERIAL_DDK_INVALID_OPERATION: Invalid operation. - - -### OH_UsbSerial_FlushOutput() - -``` -int32_t OH_UsbSerial_FlushOutput (UsbSerial_DeviceHandle * dev) -``` - -**Description** - -Refreshes the output buffer. The data in the buffer is cleared immediately. During the communication with the USB serial port device, especially in the debugging phase, disordered data packets or other exceptions may occur. - -You can call this API to clear these exceptions to restore the communication. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device handle.| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_USB_SERIAL - -**Returns** - -- USB_SERIAL_DDK_SUCCESS: Operation succeeded. - -- USB_SERIAL_DDK_NO_PERM: Permission verification failed. - -- USB_SERIAL_DDK_INVALID_PARAMETER: Parameter verification failed. Possible cause: The input **dev** is a null pointer. - -- USB_SERIAL_DDK_INIT_ERROR: DDK initialization error. - -- USB_SERIAL_DDK_SERVICE_ERROR: DDK service communication error. - -- USB_SERIAL_DDK_IO_ERROR: DDK I/O error. - -- USB_SERIAL_DDK_INVALID_OPERATION: Invalid operation. - - -### OH_UsbSerial_Init() - -``` -int32_t OH_UsbSerial_Init (void) -``` - -**Description** - -Initializes the USB Serial DDK. - -**Since**: 18 - -**Required Permissions** - -ohos.permission.ACCESS_DDK_USB_SERIAL - -**Returns** - -- USB_SERIAL_DDK_SUCCESS: Operation succeeded. - -- USB_SERIAL_DDK_NO_PERM: Permission verification failed. - -- USB_SERIAL_DDK_INIT_ERROR: DDK initialization error. - - -### OH_UsbSerial_Open() - -``` -int32_t OH_UsbSerial_Open (uint64_t deviceId, uint8_t interfaceIndex, UsbSerial_DeviceHandle ** dev) -``` - -**Description** - -Enables the USB serial port device based on the specified **deviceId** and **interfaceIndex**. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| deviceId | Device ID.| -| interfaceIndex | Interface index, which corresponds to [bInterfaceNumber](usb__ddk__types_8h.md#binterfacenumber) in the USB protocol.| -| dev | Device handle.| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_USB_SERIAL - -**Returns** - -- USB_SERIAL_DDK_SUCCESS: Operation succeeded. - -- USB_SERIAL_DDK_NO_PERM: Permission verification failed. - -- USB_SERIAL_DDK_INVALID_PARAMETER: Parameter verification failed. Possible cause: The input **dev** is a null pointer. - -- USB_SERIAL_DDK_INIT_ERROR: DDK initialization error. - -- USB_SERIAL_DDK_SERVICE_ERROR: DDK service communication error. - -- USB_SERIAL_DDK_MEMORY_ERROR: Insufficient memory. - -- USB_SERIAL_DDK_IO_ERROR: DDK I/O error. - -- USB_SERIAL_DDK_DEVICE_NOT_FOUND: Device or interface not found. - - -### OH_UsbSerial_Read() - -``` -int32_t OH_UsbSerial_Read (UsbSerial_DeviceHandle * dev, uint8_t * buff, uint32_t bufferSize, uint32_t * bytesRead) -``` - -**Description** - -Reads data from the USB serial port device to the buffer. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device handle.| -| buff | Buffer for storing the data read from the USB serial port device.| -| bufferSize | Buffer size.| -| bytesRead | Number of bytes that are actually read. If the block mode is set, the number of bytes that are actually read is returned only when it is equal to the value of **bufferSize**.
For details, see [OH_UsbSerial_SetTimeout](#oh_usbserial_settimeout).| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_USB_SERIAL - -**Returns** - -- USB_SERIAL_DDK_SUCCESS: Operation succeeded. - -- USB_SERIAL_DDK_NO_PERM: Permission verification failed. - -- USB_SERIAL_DDK_INVALID_PARAMETER: Parameter verification failed. Possible causes: 1. **dev** is a null pointer. 2. **buff** is a null pointer. 3. **bufferSize** is **0**. 4. **bytesRead** is a null pointer. - -- USB_SERIAL_DDK_INIT_ERROR: DDK initialization error. - -- USB_SERIAL_DDK_SERVICE_ERROR: DDK service communication error. - -- USB_SERIAL_DDK_MEMORY_ERROR: Invalid buffer address. - -- USB_SERIAL_DDK_IO_ERROR: DDK I/O error. - -- USB_SERIAL_DDK_INVALID_OPERATION: Invalid operation. - - -### OH_UsbSerial_Release() - -``` -int32_t OH_UsbSerial_Release (void) -``` - -**Description** - -Releases the USB Serial DDK. - -**Since**: 18 - -**Required Permissions** - -ohos.permission.ACCESS_DDK_USB_SERIAL - -**Returns** - -- USB_SERIAL_DDK_SUCCESS: Operation succeeded. - -- USB_SERIAL_DDK_NO_PERM: Permission verification failed. - -- USB_SERIAL_DDK_INIT_ERROR: DDK initialization error. - -- USB_SERIAL_DDK_SERVICE_ERROR: DDK service communication error. - - -### OH_UsbSerial_SetBaudRate() - -``` -int32_t OH_UsbSerial_SetBaudRate (UsbSerial_DeviceHandle * dev, uint32_t baudRate) -``` - -**Description** - -Sets the baud rate for a USB serial port device. If the parameters of the USB serial port device are set to the default values (the data bit is **8**, the stop bit is **1**, and parity is disabled for data transfer), you only need to call this API to set the baud rate. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device handle.| -| baudRate | Baud rate of the USB serial port device.| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_USB_SERIAL - -**Returns** - -- USB_SERIAL_DDK_SUCCESS: Operation succeeded. - -- USB_SERIAL_DDK_NO_PERM: Permission verification failed. - -- USB_SERIAL_DDK_INVALID_PARAMETER: Parameter verification failed. Possible cause: The input **dev** is a null pointer. - -- USB_SERIAL_DDK_INIT_ERROR: DDK initialization error. - -- USB_SERIAL_DDK_SERVICE_ERROR: DDK service communication error. - -- USB_SERIAL_DDK_IO_ERROR: DDK I/O error. - -- USB_SERIAL_DDK_INVALID_OPERATION: Invalid operation. - - -### OH_UsbSerial_SetFlowControl() - -``` -int32_t OH_UsbSerial_SetFlowControl (UsbSerial_DeviceHandle * dev, UsbSerial_FlowControl flowControl) -``` - -**Description** - -Sets flow control parameters. Flow control is used to manage the data transfer rate during communication with the USB serial port device to ensure that the sender does not send data that exceeds the processing capability of the receiver. - -If flow control is required, call this API to set flow control parameters. If this API is not called, flow control is not performed by default. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device handle.| -| flowControl | Flow control mode. For details, see [UsbSerial_FlowControl](#usbserial_flowcontrol).| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_USB_SERIAL - -**Returns** - -- USB_SERIAL_DDK_SUCCESS: Operation succeeded. - -- USB_SERIAL_DDK_NO_PERM: Permission verification failed. - -- USB_SERIAL_DDK_INVALID_PARAMETER: Parameter verification failed. Possible cause: The input **dev** is a null pointer. - -- USB_SERIAL_DDK_INIT_ERROR: DDK initialization error. - -- USB_SERIAL_DDK_SERVICE_ERROR: DDK service communication error. - -- USB_SERIAL_DDK_IO_ERROR: DDK I/O error. - -- USB_SERIAL_DDK_INVALID_OPERATION: Invalid operation. - - -### OH_UsbSerial_SetParams() - -``` -int32_t OH_UsbSerial_SetParams (UsbSerial_DeviceHandle * dev, UsbSerial_Params * params) -``` - -**Description** - -Sets the parameters of the USB serial port device. If the parameters of the USB serial port device are not set to the default values (the data bit is **8**, the stop bit is **1**, and parity is disabled for data transfer), you only need to call this API to set the related parameters. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device handle.| -| params | USB serial port device parameters. For details, see [UsbSerial_Params](_usb_serial___params.md).| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_USB_SERIAL - -**Returns** - -- USB_SERIAL_DDK_SUCCESS: Operation succeeded. - -- USB_SERIAL_DDK_NO_PERM: Permission verification failed. - -- USB_SERIAL_DDK_INVALID_PARAMETER: Parameter verification failed. Possible causes: 1. **dev** is a null pointer. 2. **params** is a null pointer. - -- USB_SERIAL_DDK_INIT_ERROR: DDK initialization error. - -- USB_SERIAL_DDK_SERVICE_ERROR: DDK service communication error. - -- USB_SERIAL_DDK_IO_ERROR: DDK I/O error. - -- USB_SERIAL_DDK_INVALID_OPERATION: Invalid operation. - - -### OH_UsbSerial_SetTimeout() - -``` -int32_t OH_UsbSerial_SetTimeout (UsbSerial_DeviceHandle * dev, int timeout) -``` - -**Description** - -Sets the timeout interval (ms) for reading data reported by a USB serial port device. - -If this function is not called, the timeout value is **0** by default, indicating that data is returned immediately regardless of whether data is read. If you need to wait for a certain period of time or data must be read, call this API to set the timeout interval. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device handle.| -| timeout | Timeout interval for reading data from a USB serial port device. The value range is as follows:
- (0, 25500]: time value in milliseconds. The value is rounded off to the nearest 100 milliseconds as the actual timeout interval. For example, if the value is set to **12321**, the effective timeout interval is **12300**.
- **0**: Data is returned immediately.
- **-1**: Data is read in block mode. That is, data is returned only after data of the specified length is read. For details, see [OH_UsbSerial_Read](#oh_usbserial_read).| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_USB_SERIAL - -**Returns** - -- USB_SERIAL_DDK_SUCCESS: Operation succeeded. - -- USB_SERIAL_DDK_NO_PERM: Permission verification failed. - -- USB_SERIAL_DDK_INVALID_PARAMETER: Parameter verification failed. Possible causes: 1. **dev** is a null pointer. 2. **timeout** is less than **-1** or greater than **25500**. - -- USB_SERIAL_DDK_INIT_ERROR: DDK initialization error. - -- USB_SERIAL_DDK_SERVICE_ERROR: DDK service communication error. - -- USB_SERIAL_DDK_IO_ERROR: DDK I/O error. - -- USB_SERIAL_DDK_INVALID_OPERATION: Invalid operation. - - -### OH_UsbSerial_Write() - -``` -int32_t OH_UsbSerial_Write (UsbSerial_DeviceHandle * dev, uint8_t * buff, uint32_t bufferSize, uint32_t * bytesWritten) -``` - -**Description** - -Writes the data in the buffer to the USB serial port device. - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| dev | Device handle.| -| buff | Buffer to which the data of the USB serial port device is written.| -| bufferSize | Buffer size.| -| bytesWritten | Number of bytes that are actually written.| - -**Required Permissions** - -ohos.permission.ACCESS_DDK_USB_SERIAL - -**Returns** - -- USB_SERIAL_DDK_SUCCESS: Operation succeeded. - -- USB_SERIAL_DDK_NO_PERM: Permission verification failed. - -- USB_SERIAL_DDK_INVALID_PARAMETER: Parameter verification failed. Possible causes: 1. **dev** is a null pointer. 2. **buff** is a null pointer. 3. **bufferSize** is **0**. 4. **bytesWritten** is a null pointer. - -- USB_SERIAL_DDK_INIT_ERROR: DDK initialization error. - -- USB_SERIAL_DDK_SERVICE_ERROR: DDK service communication error. - -- USB_SERIAL_DDK_IO_ERROR: DDK I/O error. - -- USB_SERIAL_DDK_INVALID_OPERATION: Invalid operation. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_usb_config_descriptor.md b/en/application-dev/reference/apis-driverdevelopment-kit/_usb_config_descriptor.md deleted file mode 100644 index 762e604605c..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_usb_config_descriptor.md +++ /dev/null @@ -1,132 +0,0 @@ -# UsbConfigDescriptor - - -## Overview - -Defines standard configuration descriptors, which correspond to **Standard Configuration Descriptor** in the USB protocol. - -**Since** - -10 - -**Related Modules** - -[USB DDK](_usb_ddk.md) - -**Header file**: [usb_ddk_types.h](usb__ddk__types_8h.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| [bLength](#blength) | Size of the descriptor, in bytes.| -| [bDescriptorType](#bdescriptortype) | Descriptor type.| -| [wTotalLength](#wtotallength) | Total length of the configuration descriptor, including the configuration, interface, endpoint, and class- or vendor-specific descriptors.| -| [bNumInterfaces](#bnuminterfaces) | Number of interfaces supported by the configuration.| -| [bConfigurationValue](#bconfigurationvalue) | Configuration index, which is used to select the configuration.| -| [iConfiguration](#iconfiguration) | Index of the string descriptor that describes the configuration.| -| [bmAttributes](#bmattributes) | Configuration attributes, including the power mode and remote wakeup.| -| [bMaxPower](#bmaxpower) | Maximum power consumption of the bus-powered USB device, in 2 mA.| - - -## Member Variable Description - - -### bConfigurationValue - - -``` -uint8_t UsbConfigDescriptor::bConfigurationValue -``` - -**Description** - -Configuration index, which is used to select the configuration. - - -### bDescriptorType - - -``` -uint8_t UsbConfigDescriptor::bDescriptorType -``` - -**Description** - -Descriptor type. - - -### bLength - - -``` -uint8_t UsbConfigDescriptor::bLength -``` - -**Description** - -Size of the descriptor, in bytes. - - -### bmAttributes - - -``` -uint8_t UsbConfigDescriptor::bmAttributes -``` - -**Description** - -Configuration attributes, including the power mode and remote wakeup. - - -### bMaxPower - - -``` -uint8_t UsbConfigDescriptor::bMaxPower -``` - -**Description** - -Maximum power consumption of the bus-powered USB device, in 2 mA. - - -### bNumInterfaces - - -``` -uint8_t UsbConfigDescriptor::bNumInterfaces -``` - -**Description** - -Number of interfaces supported by the configuration. - - -### iConfiguration - - -``` -uint8_t UsbConfigDescriptor::iConfiguration -``` - -**Description** - -Index of the string descriptor that describes the configuration. - - -### wTotalLength - - -``` -uint16_t UsbConfigDescriptor::wTotalLength -``` - -**Description** - -Total length of the configuration descriptor, including the configuration, interface, endpoint, and class- or vendor-specific descriptors. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_usb_control_request_setup.md b/en/application-dev/reference/apis-driverdevelopment-kit/_usb_control_request_setup.md deleted file mode 100644 index ca95674df2a..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_usb_control_request_setup.md +++ /dev/null @@ -1,93 +0,0 @@ -# UsbControlRequestSetup - - -## Overview - -Setup data for control transfer. It corresponds to Setup Data in the USB protocol. - -**Since** - -10 - -**Related Modules** - -[USB DDK](_usb_ddk.md) - -**Header file**: [usb_ddk_types.h](usb__ddk__types_8h.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| [bmRequestType](#bmrequesttype) | Request type.| -| [bRequest](#brequest) | Specific request.| -| [wValue](#wvalue) | Value corresponding to **wValue** in the USB protocol. Its meaning varies according to the request.| -| [wIndex](#windex) | Index corresponding to **wIndex** in the USB protocol. It is usually used to transfer the index or offset. Its meaning varies according to the request. | -| [wLength](#wlength) | Data length corresponding to **wLength** in the USB protocol. If data is transferred, this field indicates the number of transferred bytes.| - - -## Member Variable Description - - -### wIndex - - -``` -uint16_t UsbControlRequestSetup::wIndex -``` - -**Description** - -Index corresponding to **wIndex** in the USB protocol. It is usually used to transfer the index or offset. Its meaning varies according to the request. - - -### wLength - - -``` -uint16_t UsbControlRequestSetup::wLength -``` - -**Description** - -Data length, corresponding to **wLength** in the USB protocol. If data is transferred, this field indicates the number of transferred bytes. - - -### bRequest - - -``` -uint8_t UsbControlRequestSetup::bRequest -``` - -**Description** - -Specific request. - - -### bmRequestType - - -``` -uint8_t UsbControlRequestSetup::bmRequestType -``` - -**Description** - -Request type. - - -### wValue - - -``` -uint16_t UsbControlRequestSetup::wValue -``` - -**Description** - -Value corresponding to **wValue** in the USB protocol. Its meaning varies according to the request. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_usb_ddk.md b/en/application-dev/reference/apis-driverdevelopment-kit/_usb_ddk.md deleted file mode 100644 index a55783910b7..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_usb_ddk.md +++ /dev/null @@ -1,667 +0,0 @@ -# USB DDK - - -## Overview - -Provides USB DDK APIs to open and close USB interfaces, perform non-isochronous and isochronous data transfer over USB pipes, and implement control transfer and interrupt transfer, etc. - -**System capability**: SystemCapability.Driver.USB.Extension - -**Since** - -10 - -## Summary - - -### Files - -| Name| Description| -| -------- | -------- | -| [usb_ddk_api.h](usb__ddk__api_8h.md) | Declares the USB DDK APIs used by the USB host to access USB devices.
File to include: <usb/usb_ddk_api.h>
Library: libusb_ndk.z.so| -| [usb_ddk_types.h](usb__ddk__types_8h.md) | Provides the enumerated variables, structures, and macros used in USB DDK APIs.
File to include: <usb/usb_ddk_types.h>
Library: libusb_ndk.z.so| - - -### Structs - -| Name| Description| -| -------- | -------- | -| [UsbControlRequestSetup](_usb_control_request_setup.md) | Setup data for control transfer. It corresponds to **Setup Data** in the USB protocol.| -| [UsbDeviceDescriptor](_usb_device_descriptor.md) | Standard device descriptor, corresponding to **Standard Device Descriptor** in the USB protocol.| -| [UsbConfigDescriptor](_usb_config_descriptor.md) | Standard configuration descriptor, corresponding to **Standard Configuration Descriptor** in the USB protocol.| -| [UsbInterfaceDescriptor](_usb_interface_descriptor.md) | Standard interface descriptor, corresponding to **Standard Interface Descriptor** in the USB protocol.| -| [UsbEndpointDescriptor](_usb_endpoint_descriptor.md) | Standard endpoint descriptor, corresponding to **Standard Endpoint Descriptor** in the USB protocol.| -| [UsbDdkEndpointDescriptor](_usb_ddk_endpoint_descriptor.md) | Endpoint descriptor.| -| [UsbDdkInterfaceDescriptor](_usb_ddk_interface_descriptor.md) | Interface descriptor.| -| [UsbDdkInterface](_usb_ddk_interface.md) | USB DDK interface, which is a collection of alternate settings for a particular USB interface.| -| [UsbDdkConfigDescriptor](_usb_ddk_config_descriptor.md) | Configuration descriptor.| -| [UsbRequestPipe](_usb_request_pipe.md) | Request pipe.| -| [UsbDeviceMemMap](_usb_device_mem_map.md) | Device memory map created by calling [OH_Usb_CreateDeviceMemMap()](#oh_usb_createdevicememmap). A buffer using the device memory map can provide better performance.| -| [Usb_DeviceArray](_usb_device_array.md) | Defines the device ID list, which is used to store the device IDs and device quantity obtained using [OH_Usb_GetDevices()](#oh_usb_getdevices).| - -### Enums - -| Name| Description| -| -------- | -------- | -| [UsbDdkErrCode](#usbddkerrcode) {
USB_DDK_SUCCESS = 0, USB_DDK_NO_PERM = 201, USB_DDK_INVALID_PARAMETER = 401, USB_DDK_MEMORY_ERROR = 27400001,
USB_DDK_INVALID_OPERATION = 27400002, USB_DDK_IO_FAILED = 27400003, USB_DDK_TIMEOUT = 27400004
} | USB DDK error code definitions.| - - -### Functions - -| Name| Description| -| -------- | -------- | -| [OH_Usb_Init](#oh_usb_init) (void) | Initializes the DDK.| -| [OH_Usb_Release](#oh_usb_release) (void) | Releases the DDK.| -| [OH_Usb_ReleaseResource](#oh_usb_releaseresource) (void) | Releases the DDK.| -| [OH_Usb_GetDeviceDescriptor](#oh_usb_getdevicedescriptor) (uint64_t deviceId, struct [UsbDeviceDescriptor](_usb_device_descriptor.md) \*desc) | Obtains the device descriptor.| -| [OH_Usb_GetConfigDescriptor](#oh_usb_getconfigdescriptor) (uint64_t deviceId, uint8_t configIndex, struct [UsbDdkConfigDescriptor](_usb_ddk_config_descriptor.md) \*\*const config) | Obtains the configuration descriptor. To prevent memory leakage, use [OH_Usb_FreeConfigDescriptor()](#oh_usb_freeconfigdescriptor) to release a descriptor after use.| -| [OH_Usb_FreeConfigDescriptor](#oh_usb_freeconfigdescriptor) (const struct [UsbDdkConfigDescriptor](_usb_ddk_config_descriptor.md) \*const config) | Releases a configuration descriptor after use to prevent memory leakage.| -| [OH_Usb_ClaimInterface](#oh_usb_claiminterface) (uint64_t deviceId, uint8_t interfaceIndex, uint64_t \*[interfaceHandle](usb__ddk__types_8h.md#interfacehandle)) | Declares a USB interface.| -| [OH_Usb_ReleaseInterface](#oh_usb_releaseinterface) (uint64_t [interfaceHandle](usb__ddk__types_8h.md#interfacehandle)) | Releases a USB interface.| -| [OH_Usb_SelectInterfaceSetting](#oh_usb_selectinterfacesetting) (uint64_t [interfaceHandle](usb__ddk__types_8h.md#interfacehandle), uint8_t settingIndex) | Activates the alternate setting of a USB interface.| -| [OH_Usb_GetCurrentInterfaceSetting](#oh_usb_getcurrentinterfacesetting) (uint64_t [interfaceHandle](usb__ddk__types_8h.md#interfacehandle), uint8_t \*settingIndex) | Obtains the activated alternate setting of a USB interface.| -| [OH_Usb_SendControlReadRequest](#oh_usb_sendcontrolreadrequest) (uint64_t [interfaceHandle](usb__ddk__types_8h.md#interfacehandle), const struct [UsbControlRequestSetup](_usb_control_request_setup.md) \*setup, uint32_t [timeout](usb__ddk__types_8h.md#timeout), uint8_t \*data, uint32_t \*dataLen) | Sends a control read transfer request. This API works in a synchronous manner.| -| [OH_Usb_SendControlWriteRequest](#oh_usb_sendcontrolwriterequest) (uint64_t [interfaceHandle](usb__ddk__types_8h.md#interfacehandle), const struct [UsbControlRequestSetup](_usb_control_request_setup.md) \*setup, uint32_t [timeout](usb__ddk__types_8h.md#timeout), const uint8_t \*data, uint32_t dataLen) | Sends a control write transfer request. This API works in a synchronous manner.| -| [OH_Usb_SendPipeRequest](#oh_usb_sendpiperequest) (const struct [UsbRequestPipe](_usb_request_pipe.md) \*pipe, [UsbDeviceMemMap](_usb_device_mem_map.md) \*devMmap) | Sends a pipe request. This API works in a synchronous manner. It applies to interrupt transfer and bulk transfer.| -| [OH_Usb_SendPipeRequestWithAshmem](#oh_usb_sendpiperequestwithashmem) (const struct [UsbRequestPipe](_usb_request_pipe.md) \*pipe, [DDK_Ashmem](_ddk_ashmem.md) \*ashmem) | Sends a pipe request for the shared memory. This API returns the result synchronously. It applies to interrupt transfer and bulk transfer.| -| [OH_Usb_CreateDeviceMemMap](#oh_usb_createdevicememmap) (uint64_t deviceId, size_t size, [UsbDeviceMemMap](_usb_device_mem_map.md) \*\*devMmap) | Creates a buffer. To prevent memory leakage, use [OH_Usb_DestroyDeviceMemMap()](#oh_usb_destroydevicememmap) to destroy a buffer after use.| -| [OH_Usb_DestroyDeviceMemMap](#oh_usb_destroydevicememmap) ([UsbDeviceMemMap](_usb_device_mem_map.md) \*devMmap) | Destroys a buffer. To prevent resource leakage, destroy a buffer in time after use.| -| [OH_Usb_GetDevices](#oh_usb_getdevices) ([Usb_DeviceArray](_usb_device_array.md) \*devices) | Obtains the USB device ID list. Ensure that the input pointer is valid and the number of devices does not exceed 128. To prevent resource leakage, release the member memory after usage. Besides, make sure that the obtained USB device ID has been filtered by **vid** in the driver configuration information.| - -#### deviceId Description - -You can call **queryDevices()** to obtain the device ID, that is, **deviceId**. -For details, see [Peripheral Management Development](../../device/driver/externaldevice-guidelines.md). - -#### deviceId Conversion - -The **deviceId** obtained through **queryDevices()** cannot be directly used as the input parameter for functions such as [OH_Usb_GetDeviceDescriptor](#oh_usb_getdevicedescriptor). -

Specifically, you need to extract its first 32 bits as the input parameter **deviceId** for C APIs.

-

The following code is for reference only:

- - ~~~ -uint64_t JsDeviceIdToNative(uint64_t deviceId) -{ - uint32_t busNum = (uint32_t)(deviceId >> 48); - uint32_t devNum = (uint32_t)((deviceId & 0x0000FFFF00000000) >> 32); - return (((static_cast(busNum)) << 32) | devNum); -} -~~~ - -## Type Description - -### UsbDdkEndpointDescriptor - -``` -typedef struct UsbDdkEndpointDescriptor UsbDdkEndpointDescriptor -``` - -**Description** - -Endpoint descriptor. - -**Since**: 10 - -### UsbDdkInterfaceDescriptor - -``` -typedef struct UsbDdkInterfaceDescriptor UsbDdkInterfaceDescriptor -``` - -**Description** - -Interface descriptor. - -**Since**: 10 - -### UsbDdkInterface - -``` -typedef struct UsbDdkInterface UsbDdkInterface -``` - -**Description** - -USB API. - -**Since**: 10 - -### UsbDdkConfigDescriptor - -``` -typedef struct UsbDdkConfigDescriptor UsbDdkConfigDescriptor -``` - -**Description** - -Configuration descriptor. - -**Since**: 10 - -### UsbDeviceMemMap - -``` -typedef struct UsbDeviceMemMap UsbDeviceMemMap -``` - -**Description** - - Device memory map created by calling [OH_Usb_CreateDeviceMemMap()](_usb_ddk.md#oh_usb_createdevicememmap). A buffer using the device memory map can provide better performance. - -**Since**: 10 - -### Usb_DeviceArray - -``` -typedef struct Usb_DeviceArray usb_DeviceArray -``` - -**Description** - -Defines the device ID list, which is used to store the device IDs and device quantity obtained using [OH_Usb_GetDevices()](_usb_ddk.md#oh_usb_getdevices). - -**Since**: 10 - -## Enum Description - -### UsbDdkErrCode - - -``` -enum UsbDdkErrCode -``` - -**Description** - -USB DDK error code definitions. - -**Since**: 10 - -| Enum| Value| Description| -| -------- | -------- |-------- | -| USB_DDK_SUCCESS | 0 | Operation successful.| -| USB_DDK_NO_PERM | 201 | Operation failed.| -| USB_DDK_INVALID_PARAMETER | 401 | Invalid parameter.| -| USB_DDK_MEMORY_ERROR | 27400001 | Memory-related error, for example, insufficient memory, memory data copy failure, or memory application failure.| -| USB_DDK_INVALID_OPERATION | 27400002 | Invalid operation.| -| USB_DDK_IO_FAILED | 27400003 | The device I/O operation fails.| -| USB_DDK_TIMEOUT | 27400004 | Transfer timed out.| - - -## Function Description - - -### OH_Usb_ClaimInterface() - - -``` -int32_t OH_Usb_ClaimInterface (uint64_t deviceId, uint8_t interfaceIndex, uint64_t * interfaceHandle) -``` - -**Description** - -Declares a USB interface. - -**Required permissions**: ohos.permission.ACCESS_DDK_USB - -**Since**: 10 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| deviceId | Device ID.| -| interfaceIndex | Interface index, which corresponds to [bInterfaceNumber](_usb_interface_descriptor.md#binterfacenumber) in the USB protocol.| -| interfaceHandle | Interface operation handle. After the interface is claimed successfully, a value will be assigned to this parameter.| - -**Returns** - -- [USB_DDK_SUCCESS] (#usbddkerrcode): The API call is successful. -- [USB_DDK_NO_PERM](#usbddkerrcode): Permission verification fails. -- [USB_DDK_INVALID_OPERATION](#usbddkerrcode): The usb_ddk service connection fails. -- [USB_DDK_INVALID_PARAMETER](#usbddkerrcode): The input **interfaceHandle** is a null pointer. -- [USB_DDK_MEMORY_ERROR](#usbddkerrcode): The memory limit is exceeded. - -### OH_Usb_CreateDeviceMemMap() - - -``` -int32_t OH_Usb_CreateDeviceMemMap (uint64_t deviceId, size_t size, UsbDeviceMemMap ** devMmap) -``` - -**Description** - -Creates a buffer. To prevent memory leakage, use [OH_Usb_DestroyDeviceMemMap()](#oh_usb_destroydevicememmap) to destroy a buffer after use. - -**Required permissions**: ohos.permission.ACCESS_DDK_USB - -**Since**: 10 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| deviceId | Device ID.| -| size | Buffer size.| -| devMmap | Data memory map, through which the created buffer is returned to the caller.| - -**Returns** - -- [USB_DDK_SUCCESS] (#usbddkerrcode): The API call is successful. -- [USB_DDK_NO_PERM](#usbddkerrcode): Permission verification fails. -- [USB_DDK_INVALID_PARAMETER](#usbddkerrcode): The input **devMmap** is a null pointer. -- [USB_DDK_MEMORY_ERROR](#usbddkerrcode): indicates that the mmap fails or the memory space of the devMmap fails to be applied for. - - -### OH_Usb_DestroyDeviceMemMap() - - -``` -void OH_Usb_DestroyDeviceMemMap (UsbDeviceMemMap * devMmap) -``` - -**Description** - -Destroys a buffer. To prevent resource leakage, destroy a buffer in time after use. - -**Required permissions**: ohos.permission.ACCESS_DDK_USB - -**Since**: 10 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| devMmap | Destroys the buffer created by [OH_Usb_CreateDeviceMemMap()](#oh_usb_createdevicememmap).| - - -### OH_Usb_FreeConfigDescriptor() - - -``` -void OH_Usb_FreeConfigDescriptor (struct UsbDdkConfigDescriptor *const config) -``` - -**Description** - -Releases a configuration descriptor after use to prevent memory leakage. - -**Required permissions**: ohos.permission.ACCESS_DDK_USB - -**Since**: 10 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| config | Configuration descriptor obtained by calling [OH_Usb_GetConfigDescriptor()](#oh_usb_getconfigdescriptor).| - - -### OH_Usb_GetConfigDescriptor() - - -``` -int32_t OH_Usb_GetConfigDescriptor (uint64_t deviceId, uint8_t configIndex, struct UsbDdkConfigDescriptor **const config) -``` - -**Description** - -Obtains the configuration descriptor. To prevent memory leakage, use [OH_Usb_FreeConfigDescriptor()](#oh_usb_freeconfigdescriptor) to release a descriptor after use. - -**Required permissions**: ohos.permission.ACCESS_DDK_USB - -**Since**: 10 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| deviceId | Device ID.| -| configIndex | Configuration ID, which corresponds to [bConfigurationValue](_usb_config_descriptor.md#bconfigurationvalue) in the USB protocol.| -| config | Configuration descriptor, which includes the standard configuration descriptor defined in the USB protocol and the associated interface descriptor and endpoint descriptor.| - -**Returns** - -- [USB_DDK_SUCCESS] (#usbddkerrcode): The API call is successful. -- [USB_DDK_NO_PERM](#usbddkerrcode): Permission verification fails. -- [USB_DDK_INVALID_OPERATION](#usbddkerrcode): The usb_ddk service connection fails. -- [USB_DDK_INVALID_PARAMETER](#usbddkerrcode): The input **config** is a null pointer. -- [USB_DDK_IO_FAILED](#usbddkerrcode): The device I/O operation fails. -- [USB_DDK_MEMORY_ERROR](#usbddkerrcode): Memory allocation fails. - - -### OH_Usb_GetCurrentInterfaceSetting() - - -``` -int32_t OH_Usb_GetCurrentInterfaceSetting (uint64_t interfaceHandle, uint8_t * settingIndex) -``` - -**Description** - -Obtains the activated alternate setting of a USB interface. - -**Required permissions**: ohos.permission.ACCESS_DDK_USB - -**Since**: 10 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| interfaceHandle | Interface operation handle.| -| settingIndex | Index of the alternate setting, which corresponds to [bAlternateSetting](_usb_interface_descriptor.md#balternatesetting) in the USB protocol.| - -**Returns** - -- [USB_DDK_SUCCESS] (#usbddkerrcode): The API call is successful. -- [USB_DDK_NO_PERM](#usbddkerrcode): Permission verification fails. -- [USB_DDK_INVALID_OPERATION](#usbddkerrcode): The usb_ddk service connection fails. -- [USB_DDK_INVALID_PARAMETER](#usbddkerrcode): The input **settingIndex** is a null pointer. - - -### OH_Usb_GetDeviceDescriptor() - - -``` -int32_t OH_Usb_GetDeviceDescriptor (uint64_t deviceId, struct UsbDeviceDescriptor * desc) -``` - -**Description** - -Obtains the device descriptor. - -**Required permissions**: ohos.permission.ACCESS_DDK_USB - -**Since**: 10 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| deviceId | Device ID.| -| desc | Device descriptor. For details, see [UsbDeviceDescriptor](_usb_device_descriptor.md).| - -**Returns** - -- [USB_DDK_SUCCESS] (#usbddkerrcode): The API call is successful. -- [USB_DDK_NO_PERM](#usbddkerrcode): Permission verification fails. -- [USB_DDK_INVALID_OPERATION](#usbddkerrcode): The usb_ddk service connection fails. -- [USB_DDK_MEMORY_ERROR](#usbddkerrcode): Memory allocation fails. - -### OH_Usb_Init() - - -``` -int32_t OH_Usb_Init (void ) -``` - -**Description** - -Initializes the DDK. - -**Required permissions**: ohos.permission.ACCESS_DDK_USB - -**Since**: 10 - -**Returns** - -- [USB_DDK_SUCCESS] (#usbddkerrcode): The API call is successful. -- [USB_DDK_NO_PERM](#usbddkerrcode): Permission verification fails. -- [USB_DDK_INVALID_OPERATION](#usbddkerrcode): The usb_ddk service connection fails. - -### OH_Usb_Release() - - -``` -void OH_Usb_Release (void) -``` - -**Description** - -Releases the DDK. - -**Required permissions**: ohos.permission.ACCESS_DDK_USB - -**Since**: 10 - -### OH_Usb_ReleaseResource() - -``` -int32_t OH_Usb_ReleaseResource (void) -``` - -**Description** - -Releases the DDK. - -**Required permissions**: ohos.permission.ACCESS_DDK_USB - -**Since**: 18 - -**Returns** - -- [USB_DDK_SUCCESS] (#usbddkerrcode): The API call is successful. -- [USB_DDK_NO_PERM](#usbddkerrcode): Permission verification fails. -- [USB_DDK_INVALID_OPERATION](#usbddkerrcode): The usb_ddk service connection fails. - -### OH_Usb_ReleaseInterface() - -``` -int32_t OH_Usb_ReleaseInterface (uint64_t interfaceHandle) -``` - -**Description** - -Releases a USB interface. - -**Required permissions**: ohos.permission.ACCESS_DDK_USB - -**Since**: 10 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| interfaceHandle | Interface operation handle.| - -**Returns** - -- [USB_DDK_SUCCESS] (#usbddkerrcode): The API call is successful. -- [USB_DDK_NO_PERM](#usbddkerrcode): Permission verification fails. -- [USB_DDK_INVALID_OPERATION](#usbddkerrcode): The usb_ddk service connection fails. -- [USB_DDK_INVALID_PARAMETER](#usbddkerrcode): An invalid parameter is specified. - - -### OH_Usb_SelectInterfaceSetting() - - -``` -int32_t OH_Usb_SelectInterfaceSetting (uint64_t interfaceHandle, uint8_t settingIndex) -``` - -**Description** - -Activates the alternate setting of a USB interface. - -**Required permissions**: ohos.permission.ACCESS_DDK_USB - -**Since**: 10 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| interfaceHandle | Interface operation handle.| -| settingIndex | Index of the alternate setting, which corresponds to [bAlternateSetting](_usb_interface_descriptor.md#balternatesetting) in the USB protocol.| - -**Returns** - -- [USB_DDK_SUCCESS] (#usbddkerrcode): The API call is successful. -- [USB_DDK_NO_PERM](#usbddkerrcode): Permission verification fails. -- [USB_DDK_INVALID_OPERATION](#usbddkerrcode): The usb_ddk service connection fails. -- [USB_DDK_INVALID_PARAMETER](#usbddkerrcode): An invalid parameter is specified. - -### OH_Usb_SendControlReadRequest() - - -``` -int32_t OH_Usb_SendControlReadRequest (uint64_t interfaceHandle, const struct UsbControlRequestSetup * setup, uint32_t timeout, uint8_t * data, uint32_t * dataLen) -``` - -**Description** - -Sends a control read transfer request. This API works in a synchronous manner. - -**Required permissions**: ohos.permission.ACCESS_DDK_USB - -**Since**: 10 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| interfaceHandle | Interface operation handle.| -| setup | Request parameters. For details, see [UsbControlRequestSetup](_usb_control_request_setup.md).| -| timeout | Timeout duration, in milliseconds.| -| data | Data to be transferred.| -| dataLen | Data length. The return value indicates the length of the actually read data.| - -**Returns** - -- [USB_DDK_SUCCESS] (#usbddkerrcode): The API call is successful. -- [USB_DDK_NO_PERM](#usbddkerrcode): Permission verification fails. -- [USB_DDK_INVALID_OPERATION](#usbddkerrcode): The usb_ddk service connection fails. -- [USB_DDK_INVALID_PARAMETER](#usbddkerrcode): The input **setup**, **data**, or **dataLen** is a null pointer, or the value of **datalen** is less than the length of the read data. -- [USB_DDK_MEMORY_ERROR](#usbddkerrcode): The attempt to copy the memory that stores the read data fails. -- [USB_DDK_IO_FAILED](#usbddkerrcode): The device I/O operation fails. -- [USB_DDK_TIMEOUT] (#usbddkerrcode): The request times out. - - -### OH_Usb_SendControlWriteRequest() - - -``` -int32_t OH_Usb_SendControlWriteRequest (uint64_t interfaceHandle, const struct UsbControlRequestSetup * setup, uint32_t timeout, const uint8_t * data, uint32_t dataLen) -``` - -**Description** - -Sends a control write transfer request. This API works in a synchronous manner. - -**Required permissions**: ohos.permission.ACCESS_DDK_USB - -**Since**: 10 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| interfaceHandle | Interface operation handle.| -| setup | Request parameters. For details, see [UsbControlRequestSetup](_usb_control_request_setup.md).| -| timeout | Timeout duration, in milliseconds.| -| data | Data to be transferred.| -| dataLen | Data length.| - -**Returns** - -- [USB_DDK_SUCCESS] (#usbddkerrcode): The API call is successful. -- [USB_DDK_NO_PERM](#usbddkerrcode): Permission verification fails. -- [USB_DDK_INVALID_OPERATION](#usbddkerrcode): The usb_ddk service connection fails. -- [USB_DDK_INVALID_PARAMETER](#usbddkerrcode): The input **setup** or **data** is a null pointer. -- [USB_DDK_MEMORY_ERROR](#usbddkerrcode): The attempt to copy the memory that stores the read data fails. -- [USB_DDK_IO_FAILED](#usbddkerrcode): The device I/O operation fails. -- [USB_DDK_TIMEOUT] (#usbddkerrcode): The request times out. - - -### OH_Usb_SendPipeRequest() - - -``` -int32_t OH_Usb_SendPipeRequest (const struct UsbRequestPipe * pipe, UsbDeviceMemMap * devMmap) -``` - -**Description** - -Sends a pipe request. This API works in a synchronous manner. It applies to interrupt transfer and bulk transfer. - -**Required permissions**: ohos.permission.ACCESS_DDK_USB - -**Since**: 10 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| pipe | Pipe used to transfer data.| -| devMmap | Device memory map, which can be obtained by calling [OH_Usb_CreateDeviceMemMap()](#oh_usb_createdevicememmap).| - -**Returns** - -- [USB_DDK_SUCCESS] (#usbddkerrcode): The API call is successful. -- [USB_DDK_NO_PERM](#usbddkerrcode): Permission verification fails. -- [USB_DDK_INVALID_OPERATION](#usbddkerrcode): The usb_ddk service connection fails. -- [USB_DDK_INVALID_PARAMETER](#usbddkerrcode): The input **pipe**, **devMmap**, or **devMmap** address is a null pointer. -- [USB_DDK_MEMORY_ERROR](#usbddkerrcode): The attempt to copy the memory that stores the read data fails. -- [USB_DDK_IO_FAILED](#usbddkerrcode): The device I/O operation fails. -- [USB_DDK_TIMEOUT] (#usbddkerrcode): The request times out. - -### OH_Usb_SendPipeRequestWithAshmem() - - -``` -int32_t OH_Usb_SendPipeRequestWithAshmem(const struct UsbRequestPipe *pipe, DDK_Ashmem *ashmem) -``` - -**Description** - -Sends a pipe request for the shared memory. This API returns the result synchronously. It applies to interrupt transfer and bulk transfer. - -**Required permissions**: ohos.permission.ACCESS_DDK_USB - -**Since**: 12 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| pipe | Pipe used to transfer data.| -| ashmem | Shared memory, which can be obtained through [OH_DDK_CreateAshmem()](_base_ddk.md#oh_ddk_createashmem).| - -**Returns** - -- [USB_DDK_SUCCESS] (#usbddkerrcode): The API call is successful. -- [USB_DDK_NO_PERM](#usbddkerrcode): Permission verification fails. -- [USB_DDK_INVALID_OPERATION](#usbddkerrcode): The usb_ddk service connection fails. -- [USB_DDK_INVALID_PARAMETER](#usbddkerrcode): The input **pipe**, **ashmem**, or **ashmem** address is a null pointer. -- [USB_DDK_MEMORY_ERROR](#usbddkerrcode): The attempt to copy the memory that stores the read data fails. -- [USB_DDK_IO_FAILED](#usbddkerrcode): The device I/O operation fails. -- [USB_DDK_TIMEOUT] (#usbddkerrcode): The request times out. - -### OH_Usb_GetDevices() - - -``` -int32_t OH_Usb_GetDevices(struct Usb_DeviceArray *devices) -``` - -**Description** - -Obtains the USB device ID list. Ensure that the input pointer is valid and the number of devices does not exceed 128. To prevent resource leakage, release the member memory after usage. Besides, make sure that the obtained USB device ID has been filtered by **vid** in the driver configuration information. - -**Required permissions**: ohos.permission.ACCESS_DDK_USB - -**Since**: 18 - -**Parameters** - -| Name| Description| -| -------- | -------- | -| devices | Device memory address, which is used to store the obtained device ID list and quantity.| - -**Returns** - -- [USB_DDK_SUCCESS] (#usbddkerrcode): The API call is successful. -- [USB_DDK_NO_PERM](#usbddkerrcode): Permission verification fails. -- [USB_DDK_INVALID_OPERATION](#usbddkerrcode): The usb_ddk service connection fails. -- [USB_DDK_INVALID_PARAMETER](#usbddkerrcode): The address of **devices** is a null pointer. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_usb_ddk_config_descriptor.md b/en/application-dev/reference/apis-driverdevelopment-kit/_usb_ddk_config_descriptor.md deleted file mode 100644 index dcb812e20eb..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_usb_ddk_config_descriptor.md +++ /dev/null @@ -1,80 +0,0 @@ -# UsbDdkConfigDescriptor - - -## Overview - -Defines configuration descriptors. - -**Since** - -10 - -**Related Modules** - -[USB DDK](_usb_ddk.md) - -**Header file**: [usb_ddk_types.h](usb__ddk__types_8h.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| [configDescriptor](#configdescriptor) | Standard configuration descriptor.| -| [interface](#interface) | Interfaces contained in the configuration.| -| [extra](#extra) | Unresolved descriptor, including class- or vendor-specific descriptors.| -| [extraLength](#extralength) | Length of the unresolved descriptor.| - - -## Member Variable Description - - -### configDescriptor - - -``` -struct UsbConfigDescriptor UsbDdkConfigDescriptor::configDescriptor -``` - -**Description** - -Standard configuration descriptor. - - -### extra - - -``` -const uint8_t* UsbDdkConfigDescriptor::extra -``` - -**Description** - -Unresolved descriptor, including class- or vendor-specific descriptors. - - -### extraLength - - -``` -uint32_t UsbDdkConfigDescriptor::extraLength -``` - -**Description** - -Length of the unresolved descriptor. - - -### interface - - -``` -struct UsbDdkInterface* UsbDdkConfigDescriptor::interface -``` - -**Description** - -Interfaces contained in the configuration. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_usb_ddk_endpoint_descriptor.md b/en/application-dev/reference/apis-driverdevelopment-kit/_usb_ddk_endpoint_descriptor.md deleted file mode 100644 index 9817c139be4..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_usb_ddk_endpoint_descriptor.md +++ /dev/null @@ -1,67 +0,0 @@ -# UsbDdkEndpointDescriptor - - -## Overview - -Defines endpoint descriptors. - -**Since** - -10 - -**Related Modules** - -[USB DDK](_usb_ddk.md) - -**Header file**: [usb_ddk_types.h](usb__ddk__types_8h.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| [endpointDescriptor](#endpointdescriptor) | Standard endpoint descriptor.| -| [extra](#extra) | Unresolved descriptor, including class- or vendor-specific descriptors.| -| [extraLength](#extralength) | Length of the unresolved descriptor.| - - -## Member Variable Description - - -### endpointDescriptor - - -``` -struct UsbEndpointDescriptor UsbDdkEndpointDescriptor::endpointDescriptor -``` - -**Description** - -Standard endpoint descriptor. - - -### extra - - -``` -const uint8_t* UsbDdkEndpointDescriptor::extra -``` - -**Description** - -Unresolved descriptor, including class- or vendor-specific descriptors. - - -### extraLength - - -``` -uint32_t UsbDdkEndpointDescriptor::extraLength -``` - -**Description** - -Length of the unresolved descriptor. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_usb_ddk_interface.md b/en/application-dev/reference/apis-driverdevelopment-kit/_usb_ddk_interface.md deleted file mode 100644 index 7ad428bd9b7..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_usb_ddk_interface.md +++ /dev/null @@ -1,54 +0,0 @@ -# UsbDdkInterface - - -## Overview - -Defines a USB DDK interface, which is a collection of alternate settings for a particular USB interface. - -**Since** - -10 - -**Related Modules** - -[USB DDK](_usb_ddk.md) - -**Header file**: [usb_ddk_types.h](usb__ddk__types_8h.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| [numAltsetting](#numaltsetting) | Number of alternate settings of the interface.| -| [altsetting](#altsetting) | Alternate setting of the interface.| - - -## Member Variable Description - - -### altsetting - - -``` -struct UsbDdkInterfaceDescriptor* UsbDdkInterface::altsetting -``` - -**Description** - -Alternate setting of the interface. - - -### numAltsetting - - -``` -uint8_t UsbDdkInterface::numAltsetting -``` - -**Description** - -Number of alternate settings of the interface. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_usb_ddk_interface_descriptor.md b/en/application-dev/reference/apis-driverdevelopment-kit/_usb_ddk_interface_descriptor.md deleted file mode 100644 index 1b63e7da69a..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_usb_ddk_interface_descriptor.md +++ /dev/null @@ -1,80 +0,0 @@ -# UsbDdkInterfaceDescriptor - - -## Overview - -Defines interface descriptors. - -**Since** - -10 - -**Related Modules** - -[USB DDK](_usb_ddk.md) - -**Header file**: [usb_ddk_types.h](usb__ddk__types_8h.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| [interfaceDescriptor](#interfacedescriptor) | Standard interface descriptor.| -| [endPoint](#endpoint) | Endpoint descriptor contained in the interface.| -| [extra](#extra) | Unresolved descriptor, including class- or vendor-specific descriptors.| -| [extraLength](#extralength) | Length of the unresolved descriptor.| - - -## Member Variable Description - - -### endPoint - - -``` -struct UsbDdkEndpointDescriptor* UsbDdkInterfaceDescriptor::endPoint -``` - -**Description** - -Endpoint descriptor contained in the interface. - - -### extra - - -``` -const uint8_t* UsbDdkInterfaceDescriptor::extra -``` - -**Description** - -Unresolved descriptor, including class- or vendor-specific descriptors. - - -### extraLength - - -``` -uint32_t UsbDdkInterfaceDescriptor::extraLength -``` - -**Description** - -Length of the unresolved descriptor. - - -### interfaceDescriptor - - -``` -struct UsbInterfaceDescriptor UsbDdkInterfaceDescriptor::interfaceDescriptor -``` - -**Description** - -Standard interface descriptor. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_usb_device_array.md b/en/application-dev/reference/apis-driverdevelopment-kit/_usb_device_array.md deleted file mode 100644 index 46a3eb706e7..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_usb_device_array.md +++ /dev/null @@ -1,51 +0,0 @@ -# Usb_DeviceArray - - -## Overview - -Defines the device ID list, which is used to store the device IDs and device quantity obtained using [OH_Usb_GetDevices()](_usb_ddk.md#oh_usb_getdevices). - -**Since** - -18 - -**Related Modules** - -[USB DDK](_usb_ddk.md) - -**Header file**: [usb_ddk_types.h](usb__ddk__types_8h.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| [deviceIds](#deviceids) | Start address of the device ID array.| -| [num](#num) | Device quantity.| - -## Member Variable Description - - -### deviceIds - - -``` -uint64_t* Usb_DeviceArray::deviceIds -``` - -**Description** - -Defines the start address of the device ID array. The number of device IDs cannot exceed 128. -### num - - -``` -uint32_t Usb_DeviceArray::num -``` - -**Description** - -Defines the device quantity. Device IDs are obtained by traversing **deviceIds** based on the value of this parameter. If the value is **0**, there is no USB device. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_usb_device_descriptor.md b/en/application-dev/reference/apis-driverdevelopment-kit/_usb_device_descriptor.md deleted file mode 100644 index f7acdcff5b3..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_usb_device_descriptor.md +++ /dev/null @@ -1,210 +0,0 @@ -# UsbDeviceDescriptor - - -## Overview - -Defines standard device descriptors, which correspond to **Standard Device Descriptor** in the USB protocol. - -**Since** - -10 - -**Related Modules** - -[USB DDK](_usb_ddk.md) - -**Header file**: [usb_ddk_types.h](usb__ddk__types_8h.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| [bLength](#blength) | Size of the descriptor, in bytes.| -| [bDescriptorType](#bdescriptortype) | Descriptor type.| -| [bcdUSB](#bcdusb) | USB protocol release number.| -| [bDeviceClass](#bdeviceclass) | Interface class code allocated by the USB-IF.| -| [bDeviceSubClass](#bdevicesubclass) | Device subclass code allocated by USB-IF. The value is limited by that of bDeviceClass.| -| [bDeviceProtocol](#bdeviceprotocol) | Protocol code allocated by USB-IF. The value is limited by that of [bDeviceClass](#bdeviceclass) and [bDeviceSubClass](#bdevicesubclass).| -| [bMaxPacketSize0](#bmaxpacketsize0) | Maximum packet size of endpoint 0. Only values 8, 16, 32, and 64 are valid.| -| [idVendor](#idvendor) | Vendor ID allocated by USB-IF.| -| [idProduct](#idproduct) | Product ID allocated by the vendor.| -| [bcdDevice](#bcddevice) | Device release number.| -| [iManufacturer](#imanufacturer) | Index of the string descriptor that describes the vendor.| -| [iProduct](#iproduct) | Index of the string descriptor that describes the product.| -| [iSerialNumber](#iserialnumber) | Index of the string descriptor that describes the device SN.| -| [bNumConfigurations](#bnumconfigurations) | Configuration quantity.| - - -## Member Variable Description - - -### bcdDevice - - -``` -uint16_t UsbDeviceDescriptor::bcdDevice -``` - -**Description** - -Device release number. - - -### bcdUSB - - -``` -uint16_t UsbDeviceDescriptor::bcdUSB -``` - -**Description** - -USB protocol release number. - - -### bDescriptorType - - -``` -uint8_t UsbDeviceDescriptor::bDescriptorType -``` - -**Description** - -Descriptor type. - - -### bDeviceClass - - -``` -uint8_t UsbDeviceDescriptor::bDeviceClass -``` - -**Description** - -Interface class code allocated by the USB-IF. - - -### bDeviceProtocol - - -``` -uint8_t UsbDeviceDescriptor::bDeviceProtocol -``` - -**Description** - -Protocol code allocated by USB-IF. The value is limited by that of [bDeviceClass](#bdeviceclass) and [bDeviceSubClass](#bdevicesubclass). - - -### bDeviceSubClass - - -``` -uint8_t UsbDeviceDescriptor::bDeviceSubClass -``` - -**Description** - -Device subclass code allocated by USB-IF. The value is limited by that of bDeviceClass. - - -### bLength - - -``` -uint8_t UsbDeviceDescriptor::bLength -``` - -**Description** - -Size of the descriptor, in bytes. - - -### bMaxPacketSize0 - - -``` -uint8_t UsbDeviceDescriptor::bMaxPacketSize0 -``` - -**Description** - -Maximum packet size of endpoint 0. Only values 8, 16, 32, and 64 are valid. - - -### bNumConfigurations - - -``` -uint8_t UsbDeviceDescriptor::bNumConfigurations -``` - -**Description** - -Configuration quantity. - - -### idProduct - - -``` -uint16_t UsbDeviceDescriptor::idProduct -``` - -**Description** - -Product ID allocated by the vendor. - - -### idVendor - - -``` -uint16_t UsbDeviceDescriptor::idVendor -``` - -**Description** - -Vendor ID allocated by USB-IF. - - -### iManufacturer - - -``` -uint8_t UsbDeviceDescriptor::iManufacturer -``` - -**Description** - -Index of the string descriptor that describes the vendor. - - -### iProduct - - -``` -uint8_t UsbDeviceDescriptor::iProduct -``` - -**Description** - -Index of the string descriptor that describes the product. - - -### iSerialNumber - - -``` -uint8_t UsbDeviceDescriptor::iSerialNumber -``` - -**Description** - -Index of the string descriptor that describes the device SN. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_usb_device_mem_map.md b/en/application-dev/reference/apis-driverdevelopment-kit/_usb_device_mem_map.md deleted file mode 100644 index 0a6ca17ec58..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_usb_device_mem_map.md +++ /dev/null @@ -1,93 +0,0 @@ -# UsbDeviceMemMap - - -## Overview - -Device memory map created by calling [OH_Usb_CreateDeviceMemMap()](_usb_ddk.md#oh_usb_createdevicememmap). A buffer using the device memory map can provide better performance. - -**Since** - -10 - -**Related Modules** - -[USB DDK](_usb_ddk.md) - -**Header file**: [usb_ddk_types.h](usb__ddk__types_8h.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| [address](#address) | Buffer address.| -| [size](#size) | Buffer size.| -| [offset](#offset) | Offset of the used buffer. The default value is 0, indicating that there is no offset and the buffer starts from the specified address.| -| [bufferLength](#bufferlength) | Length of the used buffer. By default, the value is equal to the size, indicating that the entire buffer is used.| -| [transferedLength](#transferedlength) | Length of the transferred data.| - - -## Member Variable Description - - -### address - - -``` -uint8_t* const UsbDeviceMemMap::address -``` - -**Description** - - Buffer address. - - -### bufferLength - - -``` -uint32_t UsbDeviceMemMap::bufferLength -``` - -**Description** - -Length of the used buffer. By default, the value is equal to the size, indicating that the entire buffer is used. - - -### offset - - -``` -uint32_t UsbDeviceMemMap::offset -``` - -**Description** - -Offset of the used buffer. The default value is 0, indicating that there is no offset and the buffer starts from the specified address. - - -### size - - -``` -const size_t UsbDeviceMemMap::size -``` - -**Description** - -Buffer size. - - -### transferedLength - - -``` -uint32_t UsbDeviceMemMap::transferedLength -``` - -**Description** - -Length of the transferred data. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_usb_endpoint_descriptor.md b/en/application-dev/reference/apis-driverdevelopment-kit/_usb_endpoint_descriptor.md deleted file mode 100644 index d03b063eb8f..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_usb_endpoint_descriptor.md +++ /dev/null @@ -1,132 +0,0 @@ -# UsbEndpointDescriptor - - -## Overview - -Defines standard endpoint descriptors, which correspond to **Standard Endpoint Descriptor** in the USB protocol. - -**Since** - -10 - -**Related Modules** - -[USB DDK](_usb_ddk.md) - -**Header file**: [usb_ddk_types.h](usb__ddk__types_8h.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| [bLength](#blength) | Size of the descriptor, in bytes.| -| [bDescriptorType](#bdescriptortype) | Descriptor type.| -| [bEndpointAddress](#bendpointaddress) | Endpoint address, including the endpoint number and endpoint direction.| -| [bmAttributes](#bmattributes) | Endpoint attributes, including the transfer type, synchronization type, and usage type.| -| [wMaxPacketSize](#wmaxpacketsize) | Maximum packet size supported by an endpoint.| -| [bInterval](#binterval) | Interval for polling endpoints for data transfer.| -| [bRefresh](#brefresh) | Refresh rate for audio devices.| -| [bSynchAddress](#bsynchaddress) | Endpoint synchronization address for audio devices.| - - -## Member Variable Description - - -### bDescriptorType - - -``` -uint8_t UsbEndpointDescriptor::bDescriptorType -``` - -**Description** - -Descriptor type. - - -### bEndpointAddress - - -``` -uint8_t UsbEndpointDescriptor::bEndpointAddress -``` - -**Description** - -Endpoint address, including the endpoint number and endpoint direction. - - -### bInterval - - -``` -uint8_t UsbEndpointDescriptor::bInterval -``` - -**Description** - -Interval for polling endpoints for data transfer. - - -### bLength - - -``` -uint8_t UsbEndpointDescriptor::bLength -``` - -**Description** - -Size of the descriptor, in bytes. - - -### bmAttributes - - -``` -uint8_t UsbEndpointDescriptor::bmAttributes -``` - -**Description** - -Endpoint attributes, including the transfer type, synchronization type, and usage type. - - -### bRefresh - - -``` -uint8_t UsbEndpointDescriptor::bRefresh -``` - -**Description** - -Refresh rate for audio devices. - - -### bSynchAddress - - -``` -uint8_t UsbEndpointDescriptor::bSynchAddress -``` - -**Description** - -Endpoint synchronization address for audio devices. - - -### wMaxPacketSize - - -``` -uint16_t UsbEndpointDescriptor::wMaxPacketSize -``` - -**Description** - -Maximum packet size supported by an endpoint. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_usb_interface_descriptor.md b/en/application-dev/reference/apis-driverdevelopment-kit/_usb_interface_descriptor.md deleted file mode 100644 index e88de60faa7..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_usb_interface_descriptor.md +++ /dev/null @@ -1,145 +0,0 @@ -# UsbInterfaceDescriptor - - -## Overview - -Defines standard interface descriptors, which correspond to **Standard Interface Descriptor** in the USB protocol. - -**Since** - -10 - -**Related Modules** - -[USB DDK](_usb_ddk.md) - -**Header file**: [usb_ddk_types.h](usb__ddk__types_8h.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| [bLength](#blength) | Size of the descriptor, in bytes.| -| [bDescriptorType](#bdescriptortype) | Descriptor type.| -| [bInterfaceNumber](#binterfacenumber) | Interface ID.| -| [bAlternateSetting](#balternatesetting) | Value used to select the alternate setting of the interface.| -| [bNumEndpoints](#bnumendpoints) | Number of endpoints (excluding endpoint 0) used by the interface.| -| [bInterfaceClass](#binterfaceclass) | Interface class code allocated by the USB-IF.| -| [bInterfaceSubClass](#binterfacesubclass) | Device subclass code allocated by USB-IF. The value is limited by that of [bInterfaceClass](#binterfaceclass).| -| [bInterfaceProtocol](#binterfaceprotocol) | Protocol code allocated by USB-IF. The value is limited by that of [bInterfaceClass](#binterfaceclass) and [bInterfaceSubClass](#binterfacesubclass).| -| [iInterface](#iinterface) | Index of the string descriptor that describes the interface.| - - -## Member Variable Description - - -### bAlternateSetting - - -``` -uint8_t UsbInterfaceDescriptor::bAlternateSetting -``` - -**Description** - -Value used to select the alternate setting of the interface. - - -### bDescriptorType - - -``` -uint8_t UsbInterfaceDescriptor::bDescriptorType -``` - -**Description** - -Descriptor type. - - -### bInterfaceClass - - -``` -uint8_t UsbInterfaceDescriptor::bInterfaceClass -``` - -**Description** - -Interface class code allocated by the USB-IF. - - -### bInterfaceNumber - - -``` -uint8_t UsbInterfaceDescriptor::bInterfaceNumber -``` - -**Description** - -Interface ID. - - -### bInterfaceProtocol - - -``` -uint8_t UsbInterfaceDescriptor::bInterfaceProtocol -``` - -**Description** - -Protocol code allocated by USB-IF. The value is limited by that of [bInterfaceClass](#binterfaceclass) and [bInterfaceSubClass](#binterfacesubclass). - - -### bInterfaceSubClass - - -``` -uint8_t UsbInterfaceDescriptor::bInterfaceSubClass -``` - -**Description** - -Device subclass code allocated by USB-IF. The value is limited by that of [bInterfaceClass](#binterfaceclass). - - -### bLength - - -``` -uint8_t UsbInterfaceDescriptor::bLength -``` - -**Description** - -Size of the descriptor, in bytes. - - -### bNumEndpoints - - -``` -uint8_t UsbInterfaceDescriptor::bNumEndpoints -``` - -**Description** - -Number of endpoints (excluding endpoint 0) used by the interface. - - -### iInterface - - -``` -uint8_t UsbInterfaceDescriptor::iInterface -``` - -**Description** - -Index of the string descriptor that describes the interface. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_usb_request_pipe.md b/en/application-dev/reference/apis-driverdevelopment-kit/_usb_request_pipe.md deleted file mode 100644 index 36270885fc9..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_usb_request_pipe.md +++ /dev/null @@ -1,67 +0,0 @@ -# UsbRequestPipe - - -## Overview - -Defines a USB request pipe. - -**Since** - -10 - -**Related Modules** - -[USB DDK](_usb_ddk.md) - -**Header file**: [usb_ddk_types.h](usb__ddk__types_8h.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| [interfaceHandle](#interfacehandle) | Interface operation handle.| -| [endpoint](#endpoint) | Endpoint address.| -| [timeout](#timeout) | Timeout duration, in milliseconds.| - - -## Member Variable Description - - -### endpoint - - -``` -uint8_t UsbRequestPipe::endpoint -``` - -**Description** - -Endpoint address. - - -### interfaceHandle - - -``` -uint64_t UsbRequestPipe::interfaceHandle -``` - -**Description** - -Interface operation handle. - - -### timeout - - -``` -uint32_t UsbRequestPipe::timeout -``` - -**Description** - -Timeout duration, in milliseconds. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/_usb_serial___params.md b/en/application-dev/reference/apis-driverdevelopment-kit/_usb_serial___params.md deleted file mode 100644 index ad797559522..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/_usb_serial___params.md +++ /dev/null @@ -1,72 +0,0 @@ -# UsbSerial_Params - - -## Overview - -Defines the USB serial port parameters for the USB Serial DDK. - -**Since**: 18 - -**Related module**: [USB Serial DDK](_serial_ddk.md) - -**Header file**: [usb_serial_ddk_types.h](usb__serial__ddk__types_8h.md) - - -## Summary - - -### Member Variables - -| Name| Description| -| -------- | -------- | -| uint32_t [baudRate](#baudrate) | Baud rate.| -| uint8_t [nDataBits](#ndatabits) | Number of data transfer bits.| -| uint8_t [nStopBits](#nstopbits) | Number of data stop bits.| -| uint8_t [parity](#parity) | Parity check settings.| - - -## Member Variable Description - - -### baudRate - -``` -uint32_t UsbSerial_Params::baudRate -``` - -**Description** - -Baud rate. - - -### nDataBits - -``` -uint8_t UsbSerial_Params::nDataBits -``` - -**Description** - -Number of data transfer bits. - - -### nStopBits - -``` -uint8_t UsbSerial_Params::nStopBits -``` - -**Description** - -Number of data stop bits. - - -### parity - -``` -uint8_t UsbSerial_Params::parity -``` - -**Description** - -Parity check settings. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-baseddk-ddk-ashmem.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-baseddk-ddk-ashmem.md new file mode 100644 index 00000000000..583777e853e --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-baseddk-ddk-ashmem.md @@ -0,0 +1,24 @@ +# DDK_Ashmem + +## Overview + +Device memory map created by calling **OH_DDK_CreateAshmem**. A buffer using the device memory map can provide better performance. + +**Since**: 12 + +**Related module**: [BaseDdk](capi-baseddk.md) + +**Header file:** [ddk_types.h](capi-ddk-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| int32_t ashmemFd | File descriptor of the **Ashmem** object.| +| const uint8_t* address | Buffer address.| +| const uint32_t size | Buffer size.| +| uint32_t offset | Offset of the used buffer. The default value is **0**, indicating that there is no offset and the buffer starts from the specified address.| +| uint32_t bufferLength | Length of the buffer. By default, the value is equal to that of **size**, indicating that the entire buffer is used.| +| uint32_t transferredLength | Length of the data to be transferred.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-baseddk.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-baseddk.md new file mode 100644 index 00000000000..77d234bc59c --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-baseddk.md @@ -0,0 +1,13 @@ +# BaseDdk + +## Overview + +Provides BASE DDK APIs for creating, mapping, unmapping, and destroying an **Ashmem** object. + +**Since**: 12 +## Files + +| Name| Description| +| -- | -- | +| [ddk_api.h](capi-ddk-api-h.md) | Declares the BASE DDK APIs used by the USB host to access USB devices.| +| [ddk_types.h](capi-ddk-types-h.md) | Provides BASE DDK types and declares the macros, enums, and data structures required by the BASE DDK APIs.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-ddk-api-h.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-ddk-api-h.md new file mode 100644 index 00000000000..168a8ff6821 --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-ddk-api-h.md @@ -0,0 +1,131 @@ +# ddk_api.h + +## Overview + +Declares the BASE DDK APIs used by the USB host to access USB devices. + +**File to include**: + +**Library**: libddk_base.z.so + +**System capability**: SystemCapability.Driver.DDK.Extension + +**Since**: 12 + +**Related module**: [BaseDdk](capi-baseddk.md) + +## Summary + +### Function + +| Name| Description| +| -- | -- | +| [DDK_RetCode OH_DDK_CreateAshmem(const uint8_t *name, uint32_t size, DDK_Ashmem **ashmem)](#oh_ddk_createashmem) | Creates an **Ashmem** object. To prevent resource leakage, call **OH_DDK_DestroyAshmem** to destroy the **Ashmem** object when it is no longer needed.| +| [DDK_RetCode OH_DDK_MapAshmem(DDK_Ashmem *ashmem, const uint8_t ashmemMapType)](#oh_ddk_mapashmem) | Maps the created **Ashmem** object to the user space. Call **OH_DDK_UnmapAshmem** to unmap the **Ashmem** object when it is no longer needed.| +| [DDK_RetCode OH_DDK_UnmapAshmem(DDK_Ashmem *ashmem)](#oh_ddk_unmapashmem) | Unmaps an **Ashmem** object.| +| [DDK_RetCode OH_DDK_DestroyAshmem(DDK_Ashmem *ashmem)](#oh_ddk_destroyashmem) | Destroys an **Ashmem** object.| + +## Function Description + +### OH_DDK_CreateAshmem() + +``` +DDK_RetCode OH_DDK_CreateAshmem(const uint8_t *name, uint32_t size, DDK_Ashmem **ashmem) +``` + +**Description** + +Creates an **Ashmem** object. To prevent resource leakage, call **OH_DDK_DestroyAshmem** to destroy the **Ashmem** object when it is no longer needed. + +**Since**: 12 + + +**Parameters** + +| Name | Description| +|---------------------------------------------------| -- | +| const uint8_t *name | Pointer to the name of the **Ashmem** object.| +| uint32_t size | Buffer size of the **Ashmem** object.| +| [DDK_Ashmem](capi-baseddk-ddk-ashmem.md) **ashmem | Pointer to the **Ashmem** object.| + +**Returns** + +| Type| Description| +| -- | -- | +| [DDK_RetCode](capi-ddk-types-h.md#ddk_retcode) | [DDK_SUCCESS](capi-ddk-types-h.md#ddk_retcode): The API call is successful.
[DDK_INVALID_PARAMETER](capi-ddk-types-h.md#ddk_retcode): The input **name** is a null pointer, the value of **size** is 0, or the input **ashmem** is a null pointer.
[DDK_FAILURE](capi-ddk-types-h.md#ddk_retcode): The attempt to create an **Ashmem** object or the DDK_Ashmem structure fails.| + +### OH_DDK_MapAshmem() + +``` +DDK_RetCode OH_DDK_MapAshmem(DDK_Ashmem *ashmem, const uint8_t ashmemMapType) +``` + +**Description** + +Maps the created **Ashmem** object to the user space. Call **OH_DDK_UnmapAshmem** to unmap the **Ashmem** object when it is no longer needed. + +**Since**: 12 + + +**Parameters** + +| Name | Description| +|--------------------------------------------------| -- | +| [DDK_Ashmem](capi-baseddk-ddk-ashmem.md) *ashmem | Pointer to the **Ashmem** object.| +| const uint8_t ashmemMapType | Mapping type for the **Ashmem** object.| + +**Returns** + +| Type| Description| +| -- | -- | +| [DDK_RetCode](capi-ddk-types-h.md#ddk_retcode) | [DDK_SUCCESS](capi-ddk-types-h.md#ddk_retcode): The API call is successful.
[DDK_NULL_PTR](capi-ddk-types-h.md#ddk_retcode): The input **ashmem** is a null pointer.
[DDK_FAILURE](capi-ddk-types-h.md#ddk_retcode): The file descriptor of the **Ashmem** object is invalid.
[DDK_INVALID_OPERATION] (capi-ddk-types-h.md#ddk_retcode): The attempt to call MapAshmem fails.| + +### OH_DDK_UnmapAshmem() + +``` +DDK_RetCode OH_DDK_UnmapAshmem(DDK_Ashmem *ashmem) +``` + +**Description** + +Unmaps an **Ashmem** object. + +**Since**: 12 + + +**Parameters** + +| Name | Description| +|--------------------------------------------------| -- | +| [DDK_Ashmem](capi-baseddk-ddk-ashmem.md) *ashmem | Pointer to the **Ashmem** object.| + +**Returns** + +| Type| Description| +| -- | -- | +| [DDK_RetCode](capi-ddk-types-h.md#ddk_retcode) | [DDK_SUCCESS](capi-ddk-types-h.md#ddk_retcode): The API call is successful.
[DDK_NULL_PTR](capi-ddk-types-h.md#ddk_retcode): The input **ashmem** is a null pointer.
[DDK_FAILURE](capi-ddk-types-h.md#ddk_retcode): The file descriptor of the **Ashmem** object is invalid.| + +### OH_DDK_DestroyAshmem() + +``` +DDK_RetCode OH_DDK_DestroyAshmem(DDK_Ashmem *ashmem) +``` + +**Description** + +Destroys an **Ashmem** object. + +**Since**: 12 + + +**Parameters** + +| Name | Description| +|--------------------------------------------------| -- | +| [DDK_Ashmem](capi-baseddk-ddk-ashmem.md) *ashmem | Pointer to the **Ashmem** object.| + +**Returns** + +| Type| Description| +| -- | -- | +| [DDK_RetCode](capi-ddk-types-h.md#ddk_retcode) | [DDK_SUCCESS](capi-ddk-types-h.md#ddk_retcode): The API call is successful.
[DDK_NULL_PTR](capi-ddk-types-h.md#ddk_retcode): The input **ashmem** is a null pointer.
[DDK_FAILURE](capi-ddk-types-h.md#ddk_retcode): The file descriptor of the **Ashmem** object is invalid.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-ddk-types-h.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-ddk-types-h.md new file mode 100644 index 00000000000..6ccbf49a3cf --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-ddk-types-h.md @@ -0,0 +1,51 @@ +# ddk_types.h + +## Overview + +Provides BASE DDK types and declares the macros, enums, and data structures required by the BASE DDK APIs. + +**Header file:** + +**Library**: libddk_base.z.so + +**System capability**: SystemCapability.Driver.DDK.Extension + +**Since**: 12 + +**Related module**: [BaseDdk](capi-baseddk.md) + +## Summary + +### Structs + +| Name | typedef Keyword| Description| +|------------------------------------------| -- | -- | +| [DDK_Ashmem](capi-baseddk-ddk-ashmem.md) | DDK_Ashmem | Device memory map created by calling **OH_DDK_CreateAshmem**. A buffer using the device memory map can provide better performance.| + +### Enums + +| Name| typedef Keyword| Description| +| -- | -- | -- | +| [DDK_RetCode](#ddk_retcode) | DDK_RetCode | Enumerates error codes used in the BASE DDK.| + +## Enum Description + +### DDK_RetCode + +``` +enum DDK_RetCode +``` + +**Description** + +Enumerates the error codes used in the basic DDK. + +**Since**: 12 + +| Enum| Description| +| -- | -- | +| DDK_SUCCESS = 0 | Operation success.| +| DDK_FAILURE = 28600001 | Operation failed.| +| DDK_INVALID_PARAMETER = 28600002 | Invalid parameter.| +| DDK_INVALID_OPERATION = 28600003 | Invalid operation.| +| DDK_NULL_PTR = 28600004 | Null pointer.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-hid-ddk-api-h.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-hid-ddk-api-h.md new file mode 100644 index 00000000000..5a5c801e9ff --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-hid-ddk-api-h.md @@ -0,0 +1,546 @@ +# hid_ddk_api.h + +## Overview + +Declares the HID DDK functions for accessing an input device from the host. + +**File to include**: + +**Library**: libhid.z.so + +**System capability**: SystemCapability.Driver.HID.Extension + +**Since**: 11 + +**Related module**: [HidDdk](capi-hidddk.md) + +## Summary + +### Functions + +| Name| Description| +| -- | -- | +| [int32_t OH_Hid_CreateDevice(Hid_Device *hidDevice, Hid_EventProperties *hidEventProperties)](#oh_hid_createdevice) | Creates a device.| +| [int32_t OH_Hid_EmitEvent(int32_t deviceId, const Hid_EmitItem items[], uint16_t length)](#oh_hid_emitevent) | Sends an event list to a device.| +| [int32_t OH_Hid_DestroyDevice(int32_t deviceId)](#oh_hid_destroydevice) | Destroys a device.| +| [int32_t OH_Hid_Init(void)](#oh_hid_init) | Initializes an HID DDK.| +| [int32_t OH_Hid_Release(void)](#oh_hid_release) | Releases an HID DDK.| +| [int32_t OH_Hid_Open(uint64_t deviceId, uint8_t interfaceIndex, Hid_DeviceHandle **dev)](#oh_hid_open) | Opens the device specified by **deviceId** and **interfaceIndex**.| +| [int32_t OH_Hid_Close(Hid_DeviceHandle **dev)](#oh_hid_close) | Closes an HID device.| +| [int32_t OH_Hid_Write(Hid_DeviceHandle *dev, uint8_t *data, uint32_t length, uint32_t *bytesWritten)](#oh_hid_write) | Writes reports to an HID device.| +| [int32_t OH_Hid_ReadTimeout(Hid_DeviceHandle *dev, uint8_t *data, uint32_t bufSize, int timeout, uint32_t *bytesRead)](#oh_hid_readtimeout) | Reads reports from the HID device within the specified timeout interval.| +| [int32_t OH_Hid_Read(Hid_DeviceHandle *dev, uint8_t *data, uint32_t bufSize, uint32_t *bytesRead)](#oh_hid_read) | Reads reports from the HID device. The blocking mode (that is, blocking remains active until data can be read) is used by default. You can call [OH_Hid_SetNonBlocking](capi-hid-ddk-api-h.md#oh_hid_setnonblocking) to change the mode.| +| [int32_t OH_Hid_SetNonBlocking(Hid_DeviceHandle *dev, int nonBlock)](#oh_hid_setnonblocking) | Sets the device read mode to non-blocking mode.| +| [int32_t OH_Hid_GetRawInfo(Hid_DeviceHandle *dev, Hid_RawDevInfo *rawDevInfo)](#oh_hid_getrawinfo) | Obtains the original device information.| +| [int32_t OH_Hid_GetRawName(Hid_DeviceHandle *dev, char *data, uint32_t bufSize)](#oh_hid_getrawname) | Obtains the original device name.| +| [int32_t OH_Hid_GetPhysicalAddress(Hid_DeviceHandle *dev, char *data, uint32_t bufSize)](#oh_hid_getphysicaladdress) | Obtains the physical address of the HID device.| +| [int32_t OH_Hid_GetRawUniqueId(Hid_DeviceHandle *dev, uint8_t *data, uint32_t bufSize)](#oh_hid_getrawuniqueid) | Obtains the original unique identifier of a device.| +| [int32_t OH_Hid_SendReport(Hid_DeviceHandle *dev, Hid_ReportType reportType, const uint8_t *data, uint32_t length)](#oh_hid_sendreport) | Sends reports to the HID device.| +| [int32_t OH_Hid_GetReport(Hid_DeviceHandle *dev, Hid_ReportType reportType, uint8_t *data, uint32_t bufSize)](#oh_hid_getreport) | Obtains reports from the HID device.| +| [int32_t OH_Hid_GetReportDescriptor(Hid_DeviceHandle *dev, uint8_t *buf, uint32_t bufSize, uint32_t *bytesRead)](#oh_hid_getreportdescriptor) | Obtains the report descriptor of the HID device.| + +## Function Description + +### OH_Hid_CreateDevice() + +``` +int32_t OH_Hid_CreateDevice(Hid_Device *hidDevice, Hid_EventProperties *hidEventProperties) +``` + +**Description** + +Creates a device. + +**Required permissions**: ohos.permission.ACCESS_DDK_HID + +**Since**: 11 + + +**Parameters** + +| Name | Description| +|-------------------------------------------------------------------------------| -- | +| [Hid_Device](capi-hidddk-hid-device.md) *hidDevice | Pointer to the basic information about the device to create, including the device name, vendor ID, and product ID.| +| [Hid_EventProperties](capi-hidddk-hid-eventproperties.md) *hidEventProperties | Pointer to the event properties related to the device to create, including the event type, key event properties, absolute coordinate event properties, and relative coordinate event properties.| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | deviceID (a non-negative number) if the API call is successful.
[HID_DDK_NO_PERM](capi-hid-ddk-types-h.md#hid_ddkerrcode): The permission verification fails.
[HID_DDK_INVALID_OPERATION](capi-hid-ddk-types-h.md#hid_ddkerrcode): The hid_ddk service connection fails.
[HID_DDK_INVALID_PARAMETER](capi-hid-ddk-types-h.md#hid_ddkerrcode): The parameter check fails. Possible causes: 1. The input **hidDevice** is a null pointer.
2. The input **hidEventProperties** is a null pointer. 3. The length of **properties** exceeds 7 characters. 4. The length of **hidEventTypes** exceeds 5 characters.
5. The length of **hidKeys** exceeds 100 characters. 6. The length of **hidAbs** exceeds 26 characters. 7. The length of **hidRelBits** exceeds 13 characters.
8. The length of **hidMiscellaneous** exceeds 6 characters.
[HID_DDK_FAILURE](capi-hid-ddk-types-h.md#hid_ddkerrcode): The number of devices reaches the maximum value 200.| + +### OH_Hid_EmitEvent() + +``` +int32_t OH_Hid_EmitEvent(int32_t deviceId, const Hid_EmitItem items[], uint16_t length) +``` + +**Description** + +Sends an event list to a device. + +**Required permissions**: ohos.permission.ACCESS_DDK_HID + +**Since**: 11 + + +**Parameters** + +| Name| Description| +| -- | -- | +| int32_t deviceId | Device ID.| +| items | List of the events to send. The event information includes the event type (**Hid_EventType**), code (**Hid_SynEvent**, **Hid_KeyCode**, **HidBtnCode**, **Hid_AbsAxes**, **Hid_RelAxes**, or **Hid_MscEvent**), and value (depending on the actual device input).| +| uint16_t length | Length of the event list (number of events to be sent at a time).| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [HID_DDK_SUCCESS](capi-hid-ddk-types-h.md#hid_ddkerrcode): The API call is successful.
[HID_DDK_NO_PERM](capi-hid-ddk-types-h.md#hid_ddkerrcode): The permission verification fails.
[HID_DDK_INVALID_OPERATION](capi-hid-ddk-types-h.md#hid_ddkerrcode): The hid_ddk service connection fails or the caller is not the device creator.
[HID_DDK_INVALID_PARAMETER](capi-hid-ddk-types-h.md#hid_ddkerrcode): The parameter check fails. Possible causes: 1. The device ID is less than 0.
2. The length of the input parameter length exceeds 7 characters. 3. The input parameter items is a null pointer.
[HID_DDK_NULL_PTR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The input device is a null pointer.
[HID_DDK_FAILURE](capi-hid-ddk-types-h.md#hid_ddkerrcode): The corresponding device does not exist.| + +### OH_Hid_DestroyDevice() + +``` +int32_t OH_Hid_DestroyDevice(int32_t deviceId) +``` + +**Description** + +Destroys a device. + +**Required permissions**: ohos.permission.ACCESS_DDK_HID + +**Since**: 11 + + +**Parameters** + +| Name| Description| +| -- | -- | +| int32_t deviceId | Device ID.| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [HID_DDK_SUCCESS](capi-hid-ddk-types-h.md#hid_ddkerrcode): The API call is successful.
[HID_DDK_NO_PERM](capi-hid-ddk-types-h.md#hid_ddkerrcode): The permission verification fails.
[HID_DDK_INVALID_OPERATION](capi-hid-ddk-types-h.md#hid_ddkerrcode): The hid_ddk service connection fails or the caller is not the device creator.
[HID_DDK_FAILURE](capi-hid-ddk-types-h.md#hid_ddkerrcode): The corresponding device does not exist.| + +### OH_Hid_Init() + +``` +int32_t OH_Hid_Init(void) +``` + +**Description** + +Initializes an HID DDK. + +**Required permissions**: ohos.permission.ACCESS_DDK_HID + +**Since**: 18 + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [HID_DDK_SUCCESS](capi-hid-ddk-types-h.md#hid_ddkerrcode): The operation is successful.
[HID_DDK_NO_PERM](capi-hid-ddk-types-h.md#hid_ddkerrcode): The permission verification fails.
[HID_DDK_INIT_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The DDK initialization fails.
[HID_DDK_SERVICE_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): Communication with the DDK server fails.| + +### OH_Hid_Release() + +``` +int32_t OH_Hid_Release(void) +``` + +**Description** + +Releases an HID DDK. + +**Required permissions**: ohos.permission.ACCESS_DDK_HID + +**Since**: 18 + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [HID_DDK_SUCCESS](capi-hid-ddk-types-h.md#hid_ddkerrcode): The operation is successful.
[HID_DDK_NO_PERM](capi-hid-ddk-types-h.md#hid_ddkerrcode): The permission verification fails.
[HID_DDK_INIT_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The DDK initialization fails.
[HID_DDK_SERVICE_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): Communication with the DDK server fails.| + +### OH_Hid_Open() + +``` +int32_t OH_Hid_Open(uint64_t deviceId, uint8_t interfaceIndex, Hid_DeviceHandle **dev) +``` + +**Description** + +Opens the device specified by **deviceId** and **interfaceIndex**. + +**Required permissions**: ohos.permission.ACCESS_DDK_HID + +**Since**: 18 + + +**Parameters** + +| Name | Description| +|----------------------------| -- | +| uint64_t deviceId | Device ID.| +| uint8_t interfaceIndex | Interface index for the API of the HID device.| +| [Hid_DeviceHandle](capi-hidddk-hid-devicehandle.md) **dev | Device operation handle.| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [HID_DDK_SUCCESS](capi-hid-ddk-types-h.md#hid_ddkerrcode): The operation is successful.
[HID_DDK_NO_PERM](capi-hid-ddk-types-h.md#hid_ddkerrcode): The permission verification fails.
[HID_DDK_INIT_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The DDK initialization fails.
[HID_DDK_SERVICE_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): Communication with the DDK server fails.
[HID_DDK_MEMORY_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): Memory allocation for the device fails.
[HID_DDK_IO_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The I/O operation fails.
[HID_DDK_INVALID_PARAMETER](capi-hid-ddk-types-h.md#hid_ddkerrcode): The input **dev** is empty.
[HID_DDK_DEVICE_NOT_FOUND](capi-hid-ddk-types-h.md#hid_ddkerrcode): No device is found based on **deviceId** and **interfaceIndex**.| + +### OH_Hid_Close() + +``` +int32_t OH_Hid_Close(Hid_DeviceHandle **dev) +``` + +**Description** + +Closes an HID device. + +**Required permissions**: ohos.permission.ACCESS_DDK_HID + +**Since**: 18 + + +**Parameters** + +| Name| Description| +| -- | -- | +| [Hid_DeviceHandle](capi-hidddk-hid-devicehandle.md) **dev | Device operation handle.| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [HID_DDK_SUCCESS](capi-hid-ddk-types-h.md#hid_ddkerrcode): The operation is successful.
[HID_DDK_NO_PERM](capi-hid-ddk-types-h.md#hid_ddkerrcode): The permission verification fails.
[HID_DDK_INIT_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The DDK initialization fails.
[HID_DDK_SERVICE_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): Communication with the DDK server fails.
[HID_DDK_IO_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The I/O operation fails.
[HID_DDK_INVALID_PARAMETER](capi-hid-ddk-types-h.md#hid_ddkerrcode): The dev parameter is empty.| + +### OH_Hid_Write() + +``` +int32_t OH_Hid_Write(Hid_DeviceHandle *dev, uint8_t *data, uint32_t length, uint32_t *bytesWritten) +``` + +**Description** + +Writes reports to an HID device. + +**Required permissions**: ohos.permission.ACCESS_DDK_HID + +**Since**: 18 + + +**Parameters** + +| Name| Description| +| -- | -- | +| [Hid_DeviceHandle](capi-hidddk-hid-devicehandle.md) *dev | Device operation handle.| +| uint8_t *data | Data to be written.| +| uint32_t length | Length of the data to be written, in bytes. The value cannot exceed [HID_MAX_REPORT_BUFFER_SIZE](capi-hid-ddk-types-h.md#hid_max_report_buffer_size).| +| uint32_t *bytesWritten | Number of written bytes.| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [HID_DDK_SUCCESS](capi-hid-ddk-types-h.md#hid_ddkerrcode): The operation is successful.
[HID_DDK_NO_PERM](capi-hid-ddk-types-h.md#hid_ddkerrcode): The permission verification fails.
[HID_DDK_INVALID_PARAMETER](capi-hid-ddk-types-h.md#hid_ddkerrcode): The parameter check fails. Possible causes: 1. **dev** is empty.
2. **data** is empty. 3. The value of **length** is **0**; 4. The value of **length** exceeds [HID_MAX_REPORT_BUFFER_SIZE](capi-hid-ddk-types-h.md#hid_max_report_buffer_size).
5. **bytesWritten** is empty.
[HID_DDK_INIT_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The DDK initialization fails.
[HID_DDK_SERVICE_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): Communication with the DDK server fails.
[HID_DDK_IO_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The I/O operation fails.| + +### OH_Hid_ReadTimeout() + +``` +int32_t OH_Hid_ReadTimeout(Hid_DeviceHandle *dev, uint8_t *data, uint32_t bufSize, int timeout, uint32_t *bytesRead) +``` + +**Description** + +Reads reports from the HID device within the specified timeout interval. + +**Required permissions**: ohos.permission.ACCESS_DDK_HID + +**Since**: 18 + + +**Parameters** + +| Name| Description| +| -- | -- | +| [Hid_DeviceHandle](capi-hidddk-hid-devicehandle.md) *dev | Device operation handle.| +| uint8_t *data | Buffer for storing the read data.| +| uint32_t bufSize | Size of the buffer for storing read data. The value cannot exceed [HID_MAX_REPORT_BUFFER_SIZE](capi-hid-ddk-types-h.md#hid_max_report_buffer_size).| +| int timeout | Timeout interval, in ms. The value **-1** indicates block waiting.| +| uint32_t *bytesRead | Number of bytes to read.| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [HID_DDK_SUCCESS](capi-hid-ddk-types-h.md#hid_ddkerrcode): The operation is successful.
[HID_DDK_NO_PERM](capi-hid-ddk-types-h.md#hid_ddkerrcode): The permission verification fails.
[HID_DDK_INVALID_PARAMETER](capi-hid-ddk-types-h.md#hid_ddkerrcode): The parameter check fails. Possible causes: 1. **dev** is empty.
2. **data** is empty. 3. The value of **bufSize** is **0**. 4. The value of **bufSize** exceeds [HID_MAX_REPORT_BUFFER_SIZE](capi-hid-ddk-types-h.md#hid_max_report_buffer_size).
5. **bytesRead** is empty.
[HID_DDK_INIT_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The DDK initialization fails.
[HID_DDK_SERVICE_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): Communication with the DDK server fails.
[HID_DDK_MEMORY_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The memory data copy fails.
[HID_DDK_IO_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The I/O operation fails.
[HID_DDK_TIMEOUT](capi-hid-ddk-types-h.md#hid_ddkerrcode): The read operation times out.| + +### OH_Hid_Read() + +``` +int32_t OH_Hid_Read(Hid_DeviceHandle *dev, uint8_t *data, uint32_t bufSize, uint32_t *bytesRead) +``` + +**Description** + +Reads reports from the HID device. The blocking mode (that is, blocking remains active until data can be read) is used by default. You can call [OH_Hid_SetNonBlocking](capi-hid-ddk-api-h.md#oh_hid_setnonblocking) to change the mode. + +**Required permissions**: ohos.permission.ACCESS_DDK_HID + +**Since**: 18 + + +**Parameters** + +| Name| Description| +| -- | -- | +| [Hid_DeviceHandle](capi-hidddk-hid-devicehandle.md) *dev | Device operation handle.| +| uint8_t *data | Buffer for storing the read data.| +| uint32_t bufSize | Size of the buffer for storing read data. The value cannot exceed [HID_MAX_REPORT_BUFFER_SIZE](capi-hid-ddk-types-h.md#hid_max_report_buffer_size).| +| uint32_t *bytesRead | Number of bytes to read.| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [HID_DDK_SUCCESS](capi-hid-ddk-types-h.md#hid_ddkerrcode): The operation is successful.
[HID_DDK_NO_PERM](capi-hid-ddk-types-h.md#hid_ddkerrcode): The permission verification fails.
[HID_DDK_INVALID_PARAMETER](capi-hid-ddk-types-h.md#hid_ddkerrcode): The parameter check fails. Possible causes: 1. **dev** is empty.
2. **data** is empty. 3. The value of **bufSize** is **0**. 4. The value of **bufSize** exceeds [HID_MAX_REPORT_BUFFER_SIZE](capi-hid-ddk-types-h.md#hid_max_report_buffer_size).
5. **bytesRead** is empty.
[HID_DDK_INIT_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The DDK initialization fails.
[HID_DDK_SERVICE_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): Communication with the DDK server fails.
[HID_DDK_MEMORY_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The memory data copy fails.
[HID_DDK_IO_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The I/O operation fails.
[HID_DDK_TIMEOUT](capi-hid-ddk-types-h.md#hid_ddkerrcode): The read operation times out.| + +### OH_Hid_SetNonBlocking() + +``` +int32_t OH_Hid_SetNonBlocking(Hid_DeviceHandle *dev, int nonBlock) +``` + +**Description** + +Sets the device read mode to non-blocking mode. + +**Required permissions**: ohos.permission.ACCESS_DDK_HID + +**Since**: 18 + + +**Parameters** + +| Name| Description| +| -- | -- | +| [Hid_DeviceHandle](capi-hidddk-hid-devicehandle.md) *dev | Device operation handle.| +| int nonBlock | Whether to enable the non-blocking mode for reading data. - **1**: The non-blocking mode is enabled. When [OH_Hid_Read](capi-hid-ddk-api-h.md#oh_hid_read) is called, if the device has readable data, [HID_DDK_SUCCESS](capi-hid-ddk-types-h.md#hid_ddkerrcode) is returned;
if the device has no readable data, [HID_DDK_TIMEOUT](capi-hid-ddk-types-h.md#hid_ddkerrcode) is returned. - **0**: The non-blocking mode is disabled.| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [HID_DDK_SUCCESS](capi-hid-ddk-types-h.md#hid_ddkerrcode): The operation is successful.
[HID_DDK_NO_PERM](capi-hid-ddk-types-h.md#hid_ddkerrcode): The permission verification fails.
[HID_DDK_INIT_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The DDK initialization fails.
[HID_DDK_INVALID_PARAMETER](capi-hid-ddk-types-h.md#hid_ddkerrcode): The parameter check fails. Possible causes: 1. **dev** is empty.
2. The value of **nonBlock** is not **1** or **0**.
[HID_DDK_SERVICE_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): Communication with the DDK server fails.| + +### OH_Hid_GetRawInfo() + +``` +int32_t OH_Hid_GetRawInfo(Hid_DeviceHandle *dev, Hid_RawDevInfo *rawDevInfo) +``` + +**Description** + +Obtains the original device information. + +**Required permissions**: ohos.permission.ACCESS_DDK_HID + +**Since**: 18 + + +**Parameters** + +| Name | Description| +|-------------------------------------------------------------| -- | +| [Hid_DeviceHandle](capi-hidddk-hid-devicehandle.md) *dev | Device operation handle.| +| [Hid_RawDevInfo](capi-hidddk-hid-rawdevinfo.md) *rawDevInfo | Original device information, including the vendor ID, product ID, and bus type.| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [HID_DDK_SUCCESS](capi-hid-ddk-types-h.md#hid_ddkerrcode): The operation is successful.
[HID_DDK_NO_PERM](capi-hid-ddk-types-h.md#hid_ddkerrcode): The permission verification fails.
[HID_DDK_INVALID_PARAMETER](capi-hid-ddk-types-h.md#hid_ddkerrcode): The parameter check fails. Possible causes: 1. **dev** is empty.
2. **rawDevInfo** is empty.
[HID_DDK_INIT_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The DDK initialization fails.
[HID_DDK_SERVICE_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): Communication with the DDK server fails.
[HID_DDK_IO_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The I/O operation fails.
[HID_DDK_INVALID_OPERATION](capi-hid-ddk-types-h.md#hid_ddkerrcode): This operation is not supported.| + +### OH_Hid_GetRawName() + +``` +int32_t OH_Hid_GetRawName(Hid_DeviceHandle *dev, char *data, uint32_t bufSize) +``` + +**Description** + +Obtains the original device name. + +**Required permissions**: ohos.permission.ACCESS_DDK_HID + +**Since**: 18 + + +**Parameters** + +| Name| Description| +| -- | -- | +| [Hid_DeviceHandle](capi-hidddk-hid-devicehandle.md) *dev | Device operation handle.| +| char *data | Buffer for storing the read data.| +| uint32_t bufSize | Size of the buffer for storing read data. The value cannot exceed [HID_MAX_REPORT_BUFFER_SIZE](capi-hid-ddk-types-h.md#hid_max_report_buffer_size).| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [HID_DDK_SUCCESS](capi-hid-ddk-types-h.md#hid_ddkerrcode): The operation is successful.
[HID_DDK_NO_PERM](capi-hid-ddk-types-h.md#hid_ddkerrcode): The permission verification fails.
[HID_DDK_INVALID_PARAMETER](capi-hid-ddk-types-h.md#hid_ddkerrcode): The parameter check fails. Possible causes: 1. **dev** is empty.
2. **data** is empty. 3. The value of **bufSize** is **0**. 4. The value of **bufSize** exceeds [HID_MAX_REPORT_BUFFER_SIZE](capi-hid-ddk-types-h.md#hid_max_report_buffer_size).
[HID_DDK_INIT_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The DDK initialization fails.
[HID_DDK_SERVICE_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): Communication with the DDK server fails.
[HID_DDK_MEMORY_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The memory data copy fails.
[HID_DDK_IO_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The I/O operation fails.
[HID_DDK_INVALID_OPERATION](capi-hid-ddk-types-h.md#hid_ddkerrcode): This operation is not supported.| + +### OH_Hid_GetPhysicalAddress() + +``` +int32_t OH_Hid_GetPhysicalAddress(Hid_DeviceHandle *dev, char *data, uint32_t bufSize) +``` + +**Description** + +Obtains the physical address of the HID device. + +**Required permissions**: ohos.permission.ACCESS_DDK_HID + +**Since**: 18 + + +**Parameters** + +| Name| Description| +| -- | -- | +| [Hid_DeviceHandle](capi-hidddk-hid-devicehandle.md) *dev | Device operation handle.| +| char *data | Buffer for storing the read data.| +| uint32_t bufSize | Size of the buffer for storing read data. The value cannot exceed [HID_MAX_REPORT_BUFFER_SIZE](capi-hid-ddk-types-h.md#hid_max_report_buffer_size).| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [HID_DDK_SUCCESS](capi-hid-ddk-types-h.md#hid_ddkerrcode): The operation is successful.
[HID_DDK_NO_PERM](capi-hid-ddk-types-h.md#hid_ddkerrcode): The permission verification fails.
[HID_DDK_INVALID_PARAMETER](capi-hid-ddk-types-h.md#hid_ddkerrcode): The parameter check fails. Possible causes: 1. **dev** is empty.
2. **data** is empty. 3. The value of **bufSize** is **0**. 4. The value of **bufSize** exceeds [HID_MAX_REPORT_BUFFER_SIZE](capi-hid-ddk-types-h.md#hid_max_report_buffer_size).
[HID_DDK_INIT_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The DDK initialization fails.
[HID_DDK_SERVICE_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): Communication with the DDK server fails.
[HID_DDK_MEMORY_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The memory data copy fails.
[HID_DDK_IO_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The I/O operation fails.
[HID_DDK_INVALID_OPERATION](capi-hid-ddk-types-h.md#hid_ddkerrcode): This operation is not supported.| + +### OH_Hid_GetRawUniqueId() + +``` +int32_t OH_Hid_GetRawUniqueId(Hid_DeviceHandle *dev, uint8_t *data, uint32_t bufSize) +``` + +**Description** + +Obtains the original unique identifier of a device. + +**Required permissions**: ohos.permission.ACCESS_DDK_HID + +**Since**: 18 + + +**Parameters** + +| Name| Description| +| -- | -- | +| [Hid_DeviceHandle](capi-hidddk-hid-devicehandle.md) *dev | Device operation handle.| +| uint8_t *data | Buffer for storing the read data.| +| uint32_t bufSize | Size of the buffer for storing read data. The value cannot exceed [HID_MAX_REPORT_BUFFER_SIZE](capi-hid-ddk-types-h.md#hid_max_report_buffer_size).| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [HID_DDK_SUCCESS](capi-hid-ddk-types-h.md#hid_ddkerrcode): The operation is successful.
[HID_DDK_NO_PERM](capi-hid-ddk-types-h.md#hid_ddkerrcode): The permission verification fails.
[HID_DDK_INVALID_PARAMETER](capi-hid-ddk-types-h.md#hid_ddkerrcode): The parameter check fails. Possible causes: 1. **dev** is empty.
2. **data** is empty. 3. The value of **bufSize** is **0**. 4. The value of **bufSize** exceeds [HID_MAX_REPORT_BUFFER_SIZE](capi-hid-ddk-types-h.md#hid_max_report_buffer_size).
[HID_DDK_INIT_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The DDK initialization fails.
[HID_DDK_SERVICE_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): Communication with the DDK server fails.
[HID_DDK_MEMORY_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The memory data copy fails.
[HID_DDK_IO_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The I/O operation fails.
[HID_DDK_INVALID_OPERATION](capi-hid-ddk-types-h.md#hid_ddkerrcode): This operation is not supported.| + +### OH_Hid_SendReport() + +``` +int32_t OH_Hid_SendReport(Hid_DeviceHandle *dev, Hid_ReportType reportType, const uint8_t *data, uint32_t length) +``` + +**Description** + +Sends reports to the HID device. + +**Required permissions**: ohos.permission.ACCESS_DDK_HID + +**Since**: 18 + + +**Parameters** + +| Name| Description | +| -- |---------------------------------------------------------------------------------------------------| +| [Hid_DeviceHandle](capi-hidddk-hid-devicehandle.md) *dev | Device operation handle. | +| [Hid_ReportType](capi-hid-ddk-types-h.md#hid_reporttype) reportType | Report type. | +| const uint8_t *data | Data to be sent. | +| uint32_t length | Length of the data to be sent, in bytes. The value cannot exceed [HID_MAX_REPORT_BUFFER_SIZE](capi-hid-ddk-types-h.md#hid_max_report_buffer_size).| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [HID_DDK_SUCCESS](capi-hid-ddk-types-h.md#hid_ddkerrcode): The operation is successful.
[HID_DDK_NO_PERM](capi-hid-ddk-types-h.md#hid_ddkerrcode): The permission verification fails.
[HID_DDK_INVALID_PARAMETER](capi-hid-ddk-types-h.md#hid_ddkerrcode): The parameter check fails. Possible causes: 1. **dev** is empty.
2. **data** is empty. 3. The value of **length** is **0**; 4. The value of **length** exceeds [HID_MAX_REPORT_BUFFER_SIZE](capi-hid-ddk-types-h.md#hid_max_report_buffer_size).
[HID_DDK_INIT_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The DDK initialization fails.
[HID_DDK_SERVICE_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): Communication with the DDK server fails.
[HID_DDK_IO_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The I/O operation fails.
[HID_DDK_INVALID_OPERATION](capi-hid-ddk-types-h.md#hid_ddkerrcode): This operation is not supported.| + +### OH_Hid_GetReport() + +``` +int32_t OH_Hid_GetReport(Hid_DeviceHandle *dev, Hid_ReportType reportType, uint8_t *data, uint32_t bufSize) +``` + +**Description** + +Obtains reports from the HID device. + +**Required permissions**: ohos.permission.ACCESS_DDK_HID + +**Since**: 18 + + +**Parameters** + +| Name| Description| +| -- | -- | +| [Hid_DeviceHandle](capi-hidddk-hid-devicehandle.md) *dev | Device operation handle.| +| [Hid_ReportType](capi-hid-ddk-types-h.md#hid_reporttype) reportType | Report type.| +| uint8_t *data | Buffer for storing the read data.| +| uint32_t bufSize | Size of the buffer for storing read data. The value cannot exceed [HID_MAX_REPORT_BUFFER_SIZE](capi-hid-ddk-types-h.md#hid_max_report_buffer_size).| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [HID_DDK_SUCCESS](capi-hid-ddk-types-h.md#hid_ddkerrcode): The operation is successful.
[HID_DDK_NO_PERM](capi-hid-ddk-types-h.md#hid_ddkerrcode): The permission verification fails.
[HID_DDK_INVALID_PARAMETER](capi-hid-ddk-types-h.md#hid_ddkerrcode): The parameter check fails. Possible causes: 1. **dev** is empty.
2. **data** is empty. 3. The value of **bufSize** is **0**. 4. The value of **bufSize** exceeds [HID_MAX_REPORT_BUFFER_SIZE](capi-hid-ddk-types-h.md#hid_max_report_buffer_size).
[HID_DDK_INIT_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The DDK initialization fails.
[HID_DDK_SERVICE_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): Communication with the DDK server fails.
[HID_DDK_MEMORY_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The memory data copy fails.
[HID_DDK_IO_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The I/O operation fails.
[HID_DDK_INVALID_OPERATION](capi-hid-ddk-types-h.md#hid_ddkerrcode): This operation is not supported.| + +### OH_Hid_GetReportDescriptor() + +``` +int32_t OH_Hid_GetReportDescriptor(Hid_DeviceHandle *dev, uint8_t *buf, uint32_t bufSize, uint32_t *bytesRead) +``` + +**Description** + +Obtains the report descriptor of the HID device. + +**Required permissions**: ohos.permission.ACCESS_DDK_HID + +**Since**: 18 + + +**Parameters** + +| Name| Description| +| -- | -- | +| [Hid_DeviceHandle](capi-hidddk-hid-devicehandle.md) *dev | Device operation handle.| +| uint8_t *buf | Buffer for storing descriptors.| +| uint32_t bufSize | Buffer size, in bytes. The value cannot exceed [HID_MAX_REPORT_BUFFER_SIZE](capi-hid-ddk-types-h.md#hid_max_report_buffer_size).| +| uint32_t *bytesRead | Number of bytes to read.| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [HID_DDK_SUCCESS](capi-hid-ddk-types-h.md#hid_ddkerrcode): The operation is successful.
[HID_DDK_NO_PERM](capi-hid-ddk-types-h.md#hid_ddkerrcode): The permission verification fails.
[HID_DDK_INVALID_PARAMETER](capi-hid-ddk-types-h.md#hid_ddkerrcode): The parameter check fails. Possible causes: 1. **dev** is empty.
2. **buf** is empty. 3. The value of **bufSize** is **0**. 4. The value of **bufSize** exceeds [HID_MAX_REPORT_BUFFER_SIZE](capi-hid-ddk-types-h.md#hid_max_report_buffer_size).
5. **bytesRead** is empty.
[HID_DDK_INIT_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The DDK initialization fails.
[HID_DDK_SERVICE_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): Communication with the DDK server fails.
[HID_DDK_MEMORY_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The memory data copy fails.
[HID_DDK_IO_ERROR](capi-hid-ddk-types-h.md#hid_ddkerrcode): The I/O operation fails.
[HID_DDK_INVALID_OPERATION](capi-hid-ddk-types-h.md#hid_ddkerrcode): This operation is not supported.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-hid-ddk-types-h.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-hid-ddk-types-h.md new file mode 100644 index 00000000000..1b912cb4627 --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-hid-ddk-types-h.md @@ -0,0 +1,388 @@ +# hid_ddk_types.h + +## Overview + +Defines the enum variables and structs used in the HID DDK. + +**File to include**: + +**Library**: libhid.z.so + +**System capability**: SystemCapability.Driver.HID.Extension + +**Since**: 11 + +**Related module**: [HidDdk](capi-hidddk.md) + +## Summary + +### Structs + +| Name | typedef Keyword| Description| +|-----------------------------------------------------------| -- | -- | +| [Hid_EmitItem](capi-hidddk-hid-emititem.md) | Hid_EmitItem | Defines event information.| +| [Hid_Device](capi-hidddk-hid-device.md) | Hid_Device | Defines basic device information.| +| [Hid_EventTypeArray](capi-hidddk-hid-eventtypearray.md) | Hid_EventTypeArray | Defines an array of event types.| +| [Hid_KeyCodeArray](capi-hidddk-hid-keycodearray.md) | Hid_KeyCodeArray | Defines an array of key codes.| +| [Hid_AbsAxesArray](capi-hidddk-hid-absaxesarray.md) | Hid_AbsAxesArray | Defines an array of absolute coordinates.| +| [Hid_RelAxesArray](capi-hidddk-hid-relaxesarray.md) | Hid_RelAxesArray | Defines an array of relative coordinates.| +| [Hid_MscEventArray](capi-hidddk-hid-msceventarray.md) | Hid_MscEventArray | Defines an array of miscellaneous events.| +| [Hid_EventProperties](capi-hidddk-hid-eventproperties.md) | Hid_EventProperties | Defines the event properties of a device.| +| [Hid_RawDevInfo](capi-hidddk-hid-rawdevinfo.md) | Hid_RawDevInfo | Defines the raw device information.| +| [Hid_DeviceHandle](capi-hidddk-hid-devicehandle.md) | Hid_DeviceHandle | Defines the opaque USB HID device structure.| + +### Enums + +| Name| typedef Keyword| Description| +| -- | -- | -- | +| [Hid_DeviceProp](#hid_deviceprop) | Hid_DeviceProp | Enumerates the properties of input devices.| +| [Hid_EventType](#hid_eventtype) | Hid_EventType | Enumerates the event types.| +| [Hid_SynEvent](#hid_synevent) | Hid_SynEvent | Enumerates sync events.| +| [Hid_KeyCode](#hid_keycode) | Hid_KeyCode | Enumerates the key codes.| +| [Hid_AbsAxes](#hid_absaxes) | Hid_AbsAxes | Enumerates the absolute coordinates.| +| [Hid_RelAxes](#hid_relaxes) | Hid_RelAxes | Enumerates the relative coordinates.| +| [Hid_MscEvent](#hid_mscevent) | Hid_MscEvent | Enumerates miscellaneous input events.| +| [Hid_DdkErrCode](#hid_ddkerrcode) | Hid_DdkErrCode | Enumerates the HID DDK error codes.| +| [Hid_ReportType](#hid_reporttype) | Hid_ReportType | Defines the report (data packets exchanged between the HID device and the host) type.| + +### Macros + +| Name| Description| +| -- | -- | +| HID_MAX_REPORT_BUFFER_SIZE (16 * 1024 - 1) | Defines the maximum size of the report buffer.| + +## Enum Description + +### Hid_DeviceProp + +``` +enum Hid_DeviceProp +``` + +**Description** + +Enumerates the properties of input devices. + +**Since**: 11 + +| Enum| Description| +| -- | -- | +| HID_PROP_POINTER = 0x00 | Pointer device.| +| HID_PROP_DIRECT = 0x01 | Direct input device.| +| HID_PROP_BUTTON_PAD = 0x02 | Touch device with bottom keys.| +| HID_PROP_SEMI_MT = 0x03 | Full multi-touch device.| +| HID_PROP_TOP_BUTTON_PAD = 0x04 | Touch device with top soft keys.| +| HID_PROP_POINTING_STICK = 0x05 | Pointing stick.| +| HID_PROP_ACCELEROMETER = 0x06 | Accelerometer.| + +### Hid_EventType + +``` +enum Hid_EventType +``` + +**Description** + +Enumerates the event types. + +**Since**: 11 + +| Enum| Description| +| -- | -- | +| HID_EV_SYN = 0x00 | Sync event.| +| HID_EV_KEY = 0x01 | Key event.| +| HID_EV_REL = 0x02 | Relative coordinate event.| +| HID_EV_ABS = 0x03 | Absolute coordinate event.| +| HID_EV_MSC = 0x04 | Miscellaneous event.| + +### Hid_SynEvent + +``` +enum Hid_SynEvent +``` + +**Description** + +Enumerates sync events. + +**Since**: 11 + +| Enum| Description| +| -- | -- | +| HID_SYN_REPORT = 0 | End of an event.| +| HID_SYN_CONFIG = 1 | Configuration synchronization.| +| HID_SYN_MT_REPORT = 2 | End of a multi-touch ABS data packet.| +| HID_SYN_DROPPED = 3 | Event discarded.| + +### Hid_KeyCode + +``` +enum Hid_KeyCode +``` + +**Description** + +Enumerates the key codes. + +**Since**: 11 + +| Enum| Description| +| -- | -- | +| HID_KEY_A = 30 | Key A| +| HID_KEY_B = 48 | Key B| +| HID_KEY_C = 46 | Key C| +| HID_KEY_D = 32 | Key D| +| HID_KEY_E = 18 | Key E| +| HID_KEY_F = 33 | Key F| +| HID_KEY_G = 34 | Key G| +| HID_KEY_H = 35 | Key H| +| HID_KEY_I = 23 | Key I| +| HID_KEY_J = 36 | Key J| +| HID_KEY_K = 37 | Key K| +| HID_KEY_L = 38 | Key L| +| HID_KEY_M = 50 | Key M| +| HID_KEY_N = 49 | Key N| +| HID_KEY_O = 24 | Key O| +| HID_KEY_P = 25 | Key P| +| HID_KEY_Q = 16 | Key Q| +| HID_KEY_R = 19 | Key R| +| HID_KEY_S = 31 | Key S| +| HID_KEY_T = 20 | Key T| +| HID_KEY_U = 22 | Key U| +| HID_KEY_V = 47 | Key V| +| HID_KEY_W = 17 | Key W| +| HID_KEY_X = 45 | Key X| +| HID_KEY_Y = 21 | Key Y| +| HID_KEY_Z = 44 | Key Z| +| HID_KEY_ESC = 1 | Key Esc| +| HID_KEY_0 = 11 | Key 0| +| HID_KEY_1 = 2 | Key 1| +| HID_KEY_2 = 3 | Key 2| +| HID_KEY_3 = 4 | Key 3| +| HID_KEY_4 = 5 | Key 4| +| HID_KEY_5 = 6 | Key 5| +| HID_KEY_6 = 7 | Key 6| +| HID_KEY_7 = 8 | Key 7| +| HID_KEY_8 = 9 | Key 8| +| HID_KEY_9 = 10 | Key 9| +| HID_KEY_GRAVE = 41 | Key grave (`)| +| HID_KEY_MINUS = 12 | Key -| +| HID_KEY_EQUALS = 13 | Key =| +| HID_KEY_BACKSPACE = 14 | Key Backspace| +| HID_KEY_LEFT_BRACKET = 26 | Key [| +| HID_KEY_RIGHT_BRACKET = 27 | Key ]| +| HID_KEY_ENTER = 28 | Key Enter| +| HID_KEY_LEFT_SHIFT = 42 | Left Shift| +| HID_KEY_BACKSLASH = 43 | Key \| +| HID_KEY_SEMICOLON = 39 | Key ;| +| HID_KEY_APOSTROPHE = 40 | Key '| +| HID_KEY_SPACE = 57 | Key Space| +| HID_KEY_SLASH = 53 | Key /| +| HID_KEY_COMMA = 51 | Key comma (,)| +| HID_KEY_PERIOD = 52 | Key period (.)| +| HID_KEY_RIGHT_SHIFT = 54 | Right Shift| +| HID_KEY_NUMPAD_0 = 82 | Numeral 0 on the numeric keypad| +| HID_KEY_NUMPAD_1 = 79 | Numeral 1 on the numeric keypad| +| HID_KEY_NUMPAD_2 = 80 | Numeral 2 on the numeric keypad| +| HID_KEY_NUMPAD_3 = 81 | Numeral 3 on the numeric keypad| +| HID_KEY_NUMPAD_4 = 75 | Numeral 4 on the numeric keypad| +| HID_KEY_NUMPAD_5 = 76 | Numeral 5 on the numeric keypad| +| HID_KEY_NUMPAD_6 = 77 | Numeral 6 on the numeric keypad| +| HID_KEY_NUMPAD_7 = 71 | Numeral 7 on the numeric keypad| +| HID_KEY_NUMPAD_8 = 72 | Numeral 8 on the numeric keypad| +| HID_KEY_NUMPAD_9 = 73 | Numeral 9 on the numeric keypad| +| HID_KEY_NUMPAD_DIVIDE = 70 | Slash key (/) on the numeric keypad| +| HID_KEY_NUMPAD_MULTIPLY = 55 | Asterisk key (*) on the numeric keypad| +| HID_KEY_NUMPAD_SUBTRACT = 74 | Minus key (-) on the numeric keypad| +| HID_KEY_NUMPAD_ADD = 78 | Plus key (+) on the numeric keypad| +| HID_KEY_NUMPAD_DOT = 83 | Decimal point (.) on the numeric keypad| +| HID_KEY_SYSRQ = 99 | SYSRQ key| +| HID_KEY_DELETE = 111 | Delete key| +| HID_KEY_MUTE = 113 | Mute key| +| HID_KEY_VOLUME_DOWN = 114 | Volume Down key| +| HID_KEY_VOLUME_UP = 115 | Volume Up key| +| HID_KEY_BRIGHTNESS_DOWN = 224 | Brightness Down key| +| HID_KEY_BRIGHTNESS_UP = 225 | Brightness Up key| +| HID_BTN_0 = 0x100 | Button 0| +| HID_BTN_1 = 0x101 | Button 1| +| HID_BTN_2 = 0x102 | Button 2| +| HID_BTN_3 = 0x103 | Button 3| +| HID_BTN_4 = 0x104 | Button 4| +| HID_BTN_5 = 0x105 | Button 5| +| HID_BTN_6 = 0x106 | Button 6| +| HID_BTN_7 = 0x107 | Button 7| +| HID_BTN_8 = 0x108 | Button 8| +| HID_BTN_9 = 0x109 | Button 9| +| HID_BTN_LEFT = 0x110 | Left mouse button| +| HID_BTN_RIGHT = 0x111 | Right mouse button| +| HID_BTN_MIDDLE = 0x112 | Middle mouse button| +| HID_BTN_SIDE = 0x113 | Side mouse button| +| HID_BTN_EXTRA = 0x114 | Extra mouse button| +| HID_BTN_FORWARD = 0x115 | Mouse forward button| +| HID_BTN_BACKWARD = 0x116 | Mouse backward button| +| HID_BTN_TASK = 0x117 | Mouse task button| +| HID_BTN_TOOL_PEN = 0x140 | Pen| +| HID_BTN_TOOL_RUBBER = 0x141 | Eraser| +| HID_BTN_TOOL_BRUSH = 0x142 | Brush| +| HID_BTN_TOOL_PENCIL = 0x143 | Pencil| +| HID_BTN_TOOL_AIRBRUSH = 0x144 | Air brush| +| HID_BTN_TOOL_FINGER = 0x145 | Finger| +| HID_BTN_TOOL_MOUSE = 0x146 | Mouse| +| HID_BTN_TOOL_LENS = 0x147 | Lens| +| HID_BTN_TOOL_QUINT_TAP = 0x148 | Five-finger touch| +| HID_BTN_STYLUS3 = 0x149 | Stylus 3| +| HID_BTN_TOUCH = 0x14a | Touch| +| HID_BTN_STYLUS = 0x14b | Stylus| +| HID_BTN_STYLUS2 = 0x14c | Stylus 2| +| HID_BTN_TOOL_DOUBLE_TAP = 0x14d | Two-finger touch| +| HID_BTN_TOOL_TRIPLE_TAP = 0x14e | Three-finger touch| +| HID_BTN_TOOL_QUAD_TAP = 0x14f | Four-finger touch| +| HID_BTN_WHEEL = 0x150 | Scroll wheel| + +### Hid_AbsAxes + +``` +enum Hid_AbsAxes +``` + +**Description** + +Enumerates the absolute coordinates. + +**Since**: 11 + +| Enum| Description| +| -- | -- | +| HID_ABS_X = 0x00 | X axis| +| HID_ABS_Y = 0x01 | Y axis| +| HID_ABS_Z = 0x02 | Z axis| +| HID_ABS_RX = 0x03 | X axis of the right analog stick| +| HID_ABS_RY = 0x04 | Y axis of the right analog stick| +| HID_ABS_RZ = 0x05 | Z axis of the right analog stick| +| HID_ABS_THROTTLE = 0x06 | Throttle| +| HID_ABS_RUDDER = 0x07 | Rudder| +| HID_ABS_WHEEL = 0x08 | Scroll wheel| +| HID_ABS_GAS = 0x09 | Gas| +| HID_ABS_BRAKE = 0x0a | Brake| +| HID_ABS_HAT0X = 0x10 | HAT0X | +| HID_ABS_HAT0Y = 0x11 | HAT0Y | +| HID_ABS_HAT1X = 0x12 | HAT1X | +| HID_ABS_HAT1Y = 0x13 | HAT1Y | +| HID_ABS_HAT2X = 0x14 | HAT2X | +| HID_ABS_HAT2Y = 0x15 | HAT2Y | +| HID_ABS_HAT3X = 0x16 | HAT3X | +| HID_ABS_HAT3Y = 0x17 | HAT3Y | +| HID_ABS_PRESSURE = 0x18 | Pressure| +| HID_ABS_DISTANCE = 0x19 | Distance| +| HID_ABS_TILT_X = 0x1a | Tilt of X axis| +| HID_ABS_TILT_Y = 0x1b | Tilt of Y axis| +| HID_ABS_TOOL_WIDTH = 0x1c | Width of the touch tool| +| HID_ABS_VOLUME = 0x20 | Volume| +| HID_ABS_MISC = 0x28 | Others| + +### Hid_RelAxes + +``` +enum Hid_RelAxes +``` + +**Description** + +Enumerates the relative coordinates. + +**Since**: 11 + +| Enum| Description| +| -- | -- | +| HID_REL_X = 0x00 | X axis| +| HID_REL_Y = 0x01 | Y axis| +| HID_REL_Z = 0x02 | Z axis| +| HID_REL_RX = 0x03 | X axis of the right analog stick| +| HID_REL_RY = 0x04 | Y axis of the right analog stick| +| HID_REL_RZ = 0x05 | Z axis of the right analog stick| +| HID_REL_HWHEEL = 0x06 | Horizontal scroll wheel| +| HID_REL_DIAL = 0x07 | Scale| +| HID_REL_WHEEL = 0x08 | Scroll wheel| +| HID_REL_MISC = 0x09 | Others| +| HID_REL_RESERVED = 0x0a | Reserved| +| HID_REL_WHEEL_HI_RES = 0x0b | High-resolution scroll wheel| +| HID_REL_HWHEEL_HI_RES = 0x0c | High-resolution horizontal scroll wheel| + +### Hid_MscEvent + +``` +enum Hid_MscEvent +``` + +**Description** + +Enumerates miscellaneous input events. + +**Since**: 11 + +| Enum| Description| +| -- | -- | +| HID_MSC_SERIAL = 0x00 | Serial number| +| HID_MSC_PULSE_LED = 0x01 | Pulse| +| HID_MSC_GESTURE = 0x02 | Gesture| +| HID_MSC_RAW = 0x03 | Start event| +| HID_MSC_SCAN = 0x04 | Scan| +| HID_MSC_TIMESTAMP = 0x05 | Timestamp| + +### Hid_DdkErrCode + +``` +enum Hid_DdkErrCode +``` + +**Description** + +Enumerates the HID DDK error codes. + +**Since**: 11 + +| Enum| Description| +| -- | -- | +| HID_DDK_SUCCESS = 0 | Operation success.| +| HID_DDK_NO_PERM = 201 | No permission. The value is changed from **-6** to **201** since API version 16.| +| HID_DDK_INVALID_PARAMETER = 401 | Invalid parameter. The value is changed from **-2** to **401** since API version 16.| +| HID_DDK_FAILURE = 27300001 | Operation failed. The value is changed from **-1** to **27300001** since API version 16.| +| HID_DDK_NULL_PTR = 27300002 | Null pointer. The value is changed from **-4** to **27300002** since API version 16.| +| HID_DDK_INVALID_OPERATION = 27300003 | Invalid operation. The value is changed from **-3** to **27300003** since API version 16.| +| HID_DDK_TIMEOUT = 27300004 | Timeout. The value is changed from **-5** to **27300004** since API version 16.| +| HID_DDK_INIT_ERROR = 27300005 | DDK initialization error. This enum is supported since API version 16.| +| HID_DDK_SERVICE_ERROR = 27300006 | Service communication error. This enum is supported since API version 16.| +| HID_DDK_MEMORY_ERROR = 27300007 | Memory-related errors, such as memory data copy failure and memory allocation failure. This enum is supported since API version 16.| +| HID_DDK_IO_ERROR = 27300008 | I/O operation failure. This enum is supported since API version 16.| +| HID_DDK_DEVICE_NOT_FOUND = 27300009 | Device not found. This enum is supported since API version 16.| + +### Hid_ReportType + +``` +enum Hid_ReportType +``` + +**Description** + +Defines the report (data packets exchanged between the HID device and the host) type. + +**Since**: 18 + +| Enum| Description| +| -- | -- | +| HID_INPUT_REPORT = 0 | Input report.| +| HID_OUTPUT_REPORT = 1 | Output report.| +| HID_FEATURE_REPORT = 2 | Feature report.| + + +### HID_MAX_REPORT_BUFFER_SIZE + +``` +HID_MAX_REPORT_BUFFER_SIZE (16 * 1024 - 1) +``` + +**Description** + +Defines the maximum size of the report buffer. + +**Since**: 18 diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-absaxesarray.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-absaxesarray.md new file mode 100644 index 00000000000..63b403aeb6e --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-absaxesarray.md @@ -0,0 +1,20 @@ +# Hid_AbsAxesArray + +## Overview + +Defines an array of absolute coordinates. + +**Since**: 11 + +**Related module**: [HidDdk](capi-hidddk.md) + +**Header file:** [hid_ddk_types.h](capi-hid-ddk-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| Hid_AbsAxes* hidAbsAxes | Array of absolute coordinates.| +| uint16_t length | Length of the array.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-device.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-device.md new file mode 100644 index 00000000000..7d4f7a9c4d7 --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-device.md @@ -0,0 +1,25 @@ +# Hid_Device + +## Overview + +Defines a struct for basic device information. + +**Since**: 11 + +**Related module**: [HidDdk](capi-hidddk.md) + +**Header file:** [hid_ddk_types.h](capi-hid-ddk-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| const char* deviceName | Device name.| +| uint16_t vendorId | Vendor ID.| +| uint16_t productId | Product ID.| +| uint16_t version | Version number.| +| uint16_t bustype | Bus type.| +| Hid_DeviceProp* properties | Device properties.| +| uint16_t propLength | Number of device properties.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-devicehandle.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-devicehandle.md new file mode 100644 index 00000000000..95897463a3c --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-devicehandle.md @@ -0,0 +1,11 @@ +# Hid_DeviceHandle + +## Overview + +Defines the opaque USB HID device structure. + +**Since**: 18 + +**Related module**: [HidDdk](capi-hidddk.md) + +**Header file:** [hid_ddk_types.h](capi-hid-ddk-types-h.md) diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-emititem.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-emititem.md new file mode 100644 index 00000000000..4fc3b5a60a4 --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-emititem.md @@ -0,0 +1,21 @@ +# Hid_EmitItem + +## Overview + +Represents the event information. + +**Since**: 11 + +**Related module**: [HidDdk](capi-hidddk.md) + +**Header file:** [hid_ddk_types.h](capi-hid-ddk-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| uint16_t type | Event type.| +| uint16_t code | Event code.| +| uint32_t value | Event value.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-eventproperties.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-eventproperties.md new file mode 100644 index 00000000000..803dfc0aea0 --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-eventproperties.md @@ -0,0 +1,27 @@ +# Hid_EventProperties + +## Overview + +Defines a struct for the event properties of a device. + +**Since**: 11 + +**Related module**: [HidDdk](capi-hidddk.md) + +**Header file:** [hid_ddk_types.h](capi-hid-ddk-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| struct Hid_EventTypeArray hidEventTypes | Array of event types.| +| struct Hid_KeyCodeArray hidKeys | Array of key codes.| +| struct Hid_AbsAxesArray hidAbs | Array of absolute coordinate properties.| +| struct Hid_RelAxesArray hidRelBits | Array of relative coordinate properties.| +| struct Hid_MscEventArray hidMiscellaneous | Array of miscellaneous events.| +| int32_t hidAbsMax[64] | Maximum values of the absolute coordinates.| +| int32_t hidAbsMin[64] | Minimum values of the absolute coordinates.| +| int32_t hidAbsFuzz[64] | Fuzzy values of the absolute coordinates.| +| int32_t hidAbsFlat[64] | Fixed values of the absolute coordinates.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-eventtypearray.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-eventtypearray.md new file mode 100644 index 00000000000..0bdb1f7956f --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-eventtypearray.md @@ -0,0 +1,20 @@ +# Hid_EventTypeArray + +## Overview + +Defines a struct for an array of event types. + +**Since**: 11 + +**Related module**: [HidDdk](capi-hidddk.md) + +**Header file:** [hid_ddk_types.h](capi-hid-ddk-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| Hid_EventType* hidEventType | Array of event types.| +| uint16_t length | Length of the array.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-keycodearray.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-keycodearray.md new file mode 100644 index 00000000000..871377a036a --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-keycodearray.md @@ -0,0 +1,20 @@ +# Hid_KeyCodeArray + +## Overview + +Defines a struct for the key code array. + +**Since**: 11 + +**Related module**: [HidDdk](capi-hidddk.md) + +**Header file:** [hid_ddk_types.h](capi-hid-ddk-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| Hid_KeyCode* hidKeyCode | Key code array.| +| uint16_t length | Length of the array.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-msceventarray.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-msceventarray.md new file mode 100644 index 00000000000..a9ddb874e4a --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-msceventarray.md @@ -0,0 +1,20 @@ +# Hid_MscEventArray + +## Overview + +Defines an array of miscellaneous events. + +**Since**: 11 + +**Related module**: [HidDdk](capi-hidddk.md) + +**Header file:** [hid_ddk_types.h](capi-hid-ddk-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| Hid_MscEvent* hidMscEvent | Array of miscellaneous events.| +| uint16_t length | Length of the array.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-rawdevinfo.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-rawdevinfo.md new file mode 100644 index 00000000000..295e94ad7ef --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-rawdevinfo.md @@ -0,0 +1,21 @@ +# Hid_RawDevInfo + +## Overview + +Defines the raw device information. + +**Since**: 18 + +**Related module**: [HidDdk](capi-hidddk.md) + +**Header file:** [hid_ddk_types.h](capi-hid-ddk-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| uint32_t busType | Bus type.| +| uint16_t vendor | Provider ID.| +| uint16_t product | Product ID.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-relaxesarray.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-relaxesarray.md new file mode 100644 index 00000000000..9b1a5bf6115 --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk-hid-relaxesarray.md @@ -0,0 +1,20 @@ +# Hid_RelAxesArray + +## Overview + +Defines an array of relative coordinates. + +**Since**: 11 + +**Related module**: [HidDdk](capi-hidddk.md) + +**Header file:** [hid_ddk_types.h](capi-hid-ddk-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| Hid_RelAxes* hidRelAxes | Array of relative coordinates.| +| uint16_t length | Length of the array.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk.md new file mode 100644 index 00000000000..093c964ebac --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-hidddk.md @@ -0,0 +1,15 @@ +# HidDdk + +## Overview + +Provides HID driver development kit (DDK) functions, including those for creating a device, sending events to a device, and destroying a device. + +**System capability**: SystemCapability.Driver.HID.Extension + +**Since**: 11 +## Files + +| Name| Description| +| -- | -- | +| [hid_ddk_api.h](capi-hid-ddk-api-h.md) | Declares the HID DDK functions for accessing an input device from the host.| +| [hid_ddk_types.h](capi-hid-ddk-types-h.md) | Defines the enum variables and structs used in the HID DDK.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsi-peripheral-api-h.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsi-peripheral-api-h.md new file mode 100644 index 00000000000..e6499580962 --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsi-peripheral-api-h.md @@ -0,0 +1,452 @@ +# scsi_peripheral_api.h + +## Overview + +Declares the SCSI Peripheral DDK APIs used by the host to access the SCSI device. + +**File to include**: + +**System capability**: SystemCapability.Driver.SCSI.Extension + +**Since**: 18 + +**Related module**: [SCSIPeripheralDDK](capi-scsiperipheralddk.md) + +## Summary + +### Function + +| Name| Description| +| -- | -- | +| [int32_t OH_ScsiPeripheral_Init(void)](#oh_scsiperipheral_init) | Initializes the SCSI Peripheral DDK.| +| [int32_t OH_ScsiPeripheral_Release(void)](#oh_scsiperipheral_release) | Releases the SCSI Peripheral DDK.| +| [int32_t OH_ScsiPeripheral_Open(uint64_t deviceId, uint8_t interfaceIndex, ScsiPeripheral_Device **dev)](#oh_scsiperipheral_open) | Opens the SCSI device specified by **deviceId** and **interfaceIndex**.| +| [int32_t OH_ScsiPeripheral_Close(ScsiPeripheral_Device **dev)](#oh_scsiperipheral_close) | Disables the SCSI device.| +| [int32_t OH_ScsiPeripheral_TestUnitReady(ScsiPeripheral_Device *dev, ScsiPeripheral_TestUnitReadyRequest *request,ScsiPeripheral_Response *response)](#oh_scsiperipheral_testunitready) | Checks whether the logical units are ready.| +| [int32_t OH_ScsiPeripheral_Inquiry(ScsiPeripheral_Device *dev, ScsiPeripheral_InquiryRequest *request,ScsiPeripheral_InquiryInfo *inquiryInfo, ScsiPeripheral_Response *response)](#oh_scsiperipheral_inquiry) | Queries basic information about the SCSI device.| +| [int32_t OH_ScsiPeripheral_ReadCapacity10(ScsiPeripheral_Device *dev, ScsiPeripheral_ReadCapacityRequest *request,ScsiPeripheral_CapacityInfo *capacityInfo, ScsiPeripheral_Response *response)](#oh_scsiperipheral_readcapacity10) | Obtains the capacity information about the SCSI device.| +| [int32_t OH_ScsiPeripheral_RequestSense(ScsiPeripheral_Device *dev, ScsiPeripheral_RequestSenseRequest *request,ScsiPeripheral_Response *response)](#oh_scsiperipheral_requestsense) | Obtains sense data, that is, information returned by the SCSI device to the host to report the device status, error information, and diagnosis information.| +| [int32_t OH_ScsiPeripheral_Read10(ScsiPeripheral_Device *dev, ScsiPeripheral_IORequest *request,ScsiPeripheral_Response *response)](#oh_scsiperipheral_read10) | Reads data from a specified logical block.| +| [int32_t OH_ScsiPeripheral_Write10(ScsiPeripheral_Device *dev, ScsiPeripheral_IORequest *request,ScsiPeripheral_Response *response)](#oh_scsiperipheral_write10) | Writes data to a specified logical block of a device.| +| [int32_t OH_ScsiPeripheral_Verify10(ScsiPeripheral_Device *dev, ScsiPeripheral_VerifyRequest *request,ScsiPeripheral_Response *response)](#oh_scsiperipheral_verify10) | Verifies a specified logical block.| +| [int32_t OH_ScsiPeripheral_SendRequestByCdb(ScsiPeripheral_Device *dev, ScsiPeripheral_Request *request,ScsiPeripheral_Response *response)](#oh_scsiperipheral_sendrequestbycdb) | Sends SCSI commands in CDB mode.| +| [int32_t OH_ScsiPeripheral_CreateDeviceMemMap(ScsiPeripheral_Device *dev, size_t size,ScsiPeripheral_DeviceMemMap **devMmap)](#oh_scsiperipheral_createdevicememmap) | Creates a buffer. To avoid resource leakage, use [OH_ScsiPeripheral_DestroyDeviceMemMap](capi-scsi-peripheral-api-h.md#oh_scsiperipheral_destroydevicememmap) to destroy a buffer after use.| +| [int32_t OH_ScsiPeripheral_DestroyDeviceMemMap(ScsiPeripheral_DeviceMemMap *devMmap)](#oh_scsiperipheral_destroydevicememmap) | Destroys a buffer. To avoid resource leakage, destroy a buffer in time after use.| +| [int32_t OH_ScsiPeripheral_ParseBasicSenseInfo(uint8_t *senseData, uint8_t senseDataLen,ScsiPeripheral_BasicSenseInfo *senseInfo)](#oh_scsiperipheral_parsebasicsenseinfo) | Parses basic sense data, including the **Information**, **Command specific information**, and **Sense key specific** fields.| + +## Function Description + +### OH_ScsiPeripheral_Init() + +``` +int32_t OH_ScsiPeripheral_Init(void) +``` + +**Description** + +Initializes the SCSI Peripheral DDK. + +**Required permissions**: ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL + +**Since**: 18 + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [SCSIPERIPHERAL_DDK_SUCCESS](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The API call is successful.
[SCSIPERIPHERAL_DDK_NO_PERM](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The permission verification fails.
[SCSIPERIPHERAL_DDK_INIT_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The DDK initialization fails.
[SCSIPERIPHERAL_DDK_SERVICE_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The communication with the DDK service fails.| + +### OH_ScsiPeripheral_Release() + +``` +int32_t OH_ScsiPeripheral_Release(void) +``` + +**Description** + +Releases the SCSI Peripheral DDK. + +**Required permissions**: ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL + +**Since**: 18 + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [SCSIPERIPHERAL_DDK_SUCCESS](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The API call is successful.
[SCSIPERIPHERAL_DDK_NO_PERM](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The permission verification fails.
[SCSIPERIPHERAL_DDK_INIT_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The DDK is not initialized.
[SCSIPERIPHERAL_DDK_SERVICE_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The communication with the DDK service fails.| + +### OH_ScsiPeripheral_Open() + +``` +int32_t OH_ScsiPeripheral_Open(uint64_t deviceId, uint8_t interfaceIndex, ScsiPeripheral_Device **dev) +``` + +**Description** + +Opens the SCSI device specified by **deviceId** and **interfaceIndex**. + +**Required permissions**: ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL + +**Since**: 18 + + +**Parameters** + +| Name | Description| +|---------------------------------| -- | +| uint64_t deviceId | Device ID.| +| uint8_t interfaceIndex | Interface index for the API of the SCSI device.| +| [ScsiPeripheral_Device](capi-scsiperipheralddk-scsiperipheral-device.md) **dev | Device handle. For details, see [ScsiPeripheral_Device](capi-scsiperipheralddk-scsiperipheral-device.md).| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [SCSIPERIPHERAL_DDK_SUCCESS](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The API call is successful.
[SCSIPERIPHERAL_DDK_NO_PERM](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The permission verification fails.
[SCSIPERIPHERAL_DDK_INIT_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The DDK is not initialized.
[SCSIPERIPHERAL_DDK_INVALID_PARAMETER](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The input **dev** is empty.
[SCSIPERIPHERAL_DDK_SERVICE_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The communication with the DDK service fails.
[SCSIPERIPHERAL_DDK_MEMORY_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The memory operation fails.
[SCSIPERIPHERAL_DDK_IO_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): An I/O error occurs.
[SCSIPERIPHERAL_DDK_DEVICE_NOT_FOUND](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): No device is found based on the specified **deviceId** and **interfaceIndex**.
[SCSIPERIPHERAL_DDK_INVALID_OPERATION](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The operation is not supported.| + +### OH_ScsiPeripheral_Close() + +``` +int32_t OH_ScsiPeripheral_Close(ScsiPeripheral_Device **dev) +``` + +**Description** + +Disables the SCSI device. + +**Required permissions**: ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL + +**Since**: 18 + + +**Parameters** + +| Name| Description| +| -- | -- | +| [ScsiPeripheral_Device](capi-scsiperipheralddk-scsiperipheral-device.md) **dev | Device handle. For details, see [ScsiPeripheral_Device](capi-scsiperipheralddk-scsiperipheral-device.md).| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [SCSIPERIPHERAL_DDK_SUCCESS](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The API call is successful.
[SCSIPERIPHERAL_DDK_NO_PERM](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The permission verification fails.
[SCSIPERIPHERAL_DDK_INIT_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The DDK is not initialized.
[SCSIPERIPHERAL_DDK_INVALID_PARAMETER](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The input **dev** is empty.
[SCSIPERIPHERAL_DDK_SERVICE_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The communication with the DDK service fails.
[SCSIPERIPHERAL_DDK_IO_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): An I/O error occurs.| + +### OH_ScsiPeripheral_TestUnitReady() + +``` +int32_t OH_ScsiPeripheral_TestUnitReady(ScsiPeripheral_Device *dev, ScsiPeripheral_TestUnitReadyRequest *request,ScsiPeripheral_Response *response) +``` + +**Description** + +Checks whether the logical units are ready. + +**Required permissions**: ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL + +**Since**: 18 + + +**Parameters** + +| Name | Description | +|---------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------| +| [ScsiPeripheral_Device](capi-scsiperipheralddk-scsiperipheral-device.md) *dev | Device handle. For details, see [ScsiPeripheral_Device](capi-scsiperipheralddk-scsiperipheral-device.md). | +| [ScsiPeripheral_TestUnitReadyRequest](capi-scsiperipheralddk-scsiperipheral-testunitreadyrequest.md) *request | Request of the **test unit ready** command. For details, see [ScsiPeripheral_TestUnitReadyRequest](capi-scsiperipheralddk-scsiperipheral-testunitreadyrequest.md).| +| [ScsiPeripheral_Response](capi-scsiperipheralddk-scsiperipheral-response.md) *response | Response returned by the **test unit ready** command. For details, see [ScsiPeripheral_Response](capi-scsiperipheralddk-scsiperipheral-response.md). | + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [SCSIPERIPHERAL_DDK_SUCCESS](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The API call is successful.
[SCSIPERIPHERAL_DDK_NO_PERM](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The permission verification fails.
[SCSIPERIPHERAL_DDK_INIT_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The DDK is not initialized.
[SCSIPERIPHERAL_DDK_INVALID_PARAMETER](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The input **dev**, **request**, or **response** is empty.
[SCSIPERIPHERAL_DDK_SERVICE_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The communication with the DDK service fails.
[SCSIPERIPHERAL_DDK_MEMORY_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The memory operation fails.
[SCSIPERIPHERAL_DDK_IO_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): An I/O error occurs.
[SCSIPERIPHERAL_DDK_TIMEOUT](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The transmission times out.
[SCSIPERIPHERAL_DDK_INVALID_OPERATION](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The operation is not supported.| + +### OH_ScsiPeripheral_Inquiry() + +``` +int32_t OH_ScsiPeripheral_Inquiry(ScsiPeripheral_Device *dev, ScsiPeripheral_InquiryRequest *request,ScsiPeripheral_InquiryInfo *inquiryInfo, ScsiPeripheral_Response *response) +``` + +**Description** + +Queries basic information about the SCSI device. + +**Required permissions**: ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL + +**Since**: 18 + + +**Parameters** + +| Name | Description | +|----------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------| +| [ScsiPeripheral_Device](capi-scsiperipheralddk-scsiperipheral-device.md) *dev | Device handle. For details, see [ScsiPeripheral_Device](capi-scsiperipheralddk-scsiperipheral-device.md). | +| [ScsiPeripheral_InquiryRequest](capi-scsiperipheralddk-scsiperipheral-inquiryrequest.md) *request | Request of the **inquiry** command. For details, see [ScsiPeripheral_InquiryRequest](capi-scsiperipheralddk-scsiperipheral-inquiryrequest.md). | +| [ScsiPeripheral_InquiryInfo](capi-scsiperipheralddk-scsiperipheral-inquiryinfo.md) *inquiryInfo | Query result returned by the **inquiry** command. For details, see [ScsiPeripheral_InquiryInfo](capi-scsiperipheralddk-scsiperipheral-inquiryinfo.md). | +| [ScsiPeripheral_Response](capi-scsiperipheralddk-scsiperipheral-response.md) *response | Raw response returned by the inquiry command. For details, see [ScsiPeripheral_Response](capi-scsiperipheralddk-scsiperipheral-response.md).| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [SCSIPERIPHERAL_DDK_SUCCESS](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The API call is successful.
[SCSIPERIPHERAL_DDK_NO_PERM](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The permission verification fails.
[SCSIPERIPHERAL_DDK_INIT_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The DDK is not initialized.
[SCSIPERIPHERAL_DDK_INVALID_PARAMETER](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The input **dev**, **request**, **inquiryInfo**, **inquiryInfo > data**, or **response** is empty.
[SCSIPERIPHERAL_DDK_SERVICE_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The communication with the DDK service fails.
[SCSIPERIPHERAL_DDK_MEMORY_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The memory operation fails.
[SCSIPERIPHERAL_DDK_IO_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): An I/O error occurs.
[SCSIPERIPHERAL_DDK_TIMEOUT](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The transmission times out.
[SCSIPERIPHERAL_DDK_INVALID_OPERATION](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The operation is not supported.| + +### OH_ScsiPeripheral_ReadCapacity10() + +``` +int32_t OH_ScsiPeripheral_ReadCapacity10(ScsiPeripheral_Device *dev, ScsiPeripheral_ReadCapacityRequest *request,ScsiPeripheral_CapacityInfo *capacityInfo, ScsiPeripheral_Response *response) +``` + +**Description** + +Obtains the capacity information about the SCSI device. + +**Required permissions**: ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL + +**Since**: 18 + + +**Parameters** + +| Name | Description | +|-------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------| +| [ScsiPeripheral_Device](capi-scsiperipheralddk-scsiperipheral-device.md) *dev | Device handle. For details, see [ScsiPeripheral_Device](capi-scsiperipheralddk-scsiperipheral-device.md). | +| [ScsiPeripheral_ReadCapacityRequest](capi-scsiperipheralddk-scsiperipheral-readcapacityrequest.md) *request | Request of the **read capacity** command. For details, see [ScsiPeripheral_ReadCapacityRequest](capi-scsiperipheralddk-scsiperipheral-readcapacityrequest.md).| +| [ScsiPeripheral_CapacityInfo](capi-scsiperipheralddk-scsiperipheral-capacityinfo.md) *capacityInfo | Capacity information returned by the **read capacity** command. For details, see [ScsiPeripheral_CapacityInfo](capi-scsiperipheralddk-scsiperipheral-capacityinfo.md). | +| [ScsiPeripheral_Response](capi-scsiperipheralddk-scsiperipheral-response.md) *response | Original response returned by the **read capacity** command. For details, see [ScsiPeripheral_Response](capi-scsiperipheralddk-scsiperipheral-response.md).| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [SCSIPERIPHERAL_DDK_SUCCESS](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The API call is successful.
[SCSIPERIPHERAL_DDK_NO_PERM](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The permission verification fails.
[SCSIPERIPHERAL_DDK_INIT_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The DDK is not initialized.
[SCSIPERIPHERAL_DDK_INVALID_PARAMETER](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The input **dev**, **request**, **capacityInfo**, or **response** is empty.
[SCSIPERIPHERAL_DDK_SERVICE_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The communication with the DDK service fails.
[SCSIPERIPHERAL_DDK_MEMORY_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The memory operation fails.
[SCSIPERIPHERAL_DDK_IO_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): An I/O error occurs.
[SCSIPERIPHERAL_DDK_TIMEOUT](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The transmission times out.
[SCSIPERIPHERAL_DDK_INVALID_OPERATION](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The operation is not supported.| + +### OH_ScsiPeripheral_RequestSense() + +``` +int32_t OH_ScsiPeripheral_RequestSense(ScsiPeripheral_Device *dev, ScsiPeripheral_RequestSenseRequest *request,ScsiPeripheral_Response *response) +``` + +**Description** + +Obtains sense data, that is, information returned by the SCSI device to the host to report the device status, error information, and diagnosis information. + +**Required permissions**: ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL + +**Since**: 18 + + +**Parameters** + +| Name | Description | +|-------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------| +| [ScsiPeripheral_Device](capi-scsiperipheralddk-scsiperipheral-device.md) *dev | Device handle. For details, see [ScsiPeripheral_Device](capi-scsiperipheralddk-scsiperipheral-device.md). | +| [ScsiPeripheral_RequestSenseRequest](capi-scsiperipheralddk-scsiperipheral-requestsenserequest.md) *request | Request of the **request sense** command. For details, see [ScsiPeripheral_RequestSenseRequest](capi-scsiperipheralddk-scsiperipheral-requestsenserequest.md).| +| [ScsiPeripheral_Response](capi-scsiperipheralddk-scsiperipheral-response.md) *response | Response returned by the **request sense** command. For details, see [ScsiPeripheral_Response](capi-scsiperipheralddk-scsiperipheral-response.md). | + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [SCSIPERIPHERAL_DDK_SUCCESS](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The API call is successful.
[SCSIPERIPHERAL_DDK_NO_PERM](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The permission verification fails.
[SCSIPERIPHERAL_DDK_INIT_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The DDK is not initialized.
[SCSIPERIPHERAL_DDK_INVALID_PARAMETER](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The input **dev**, **request**, or **response** is empty.
[SCSIPERIPHERAL_DDK_SERVICE_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The communication with the DDK service fails.
[SCSIPERIPHERAL_DDK_MEMORY_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The memory operation fails.
[SCSIPERIPHERAL_DDK_IO_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): An I/O error occurs.
[SCSIPERIPHERAL_DDK_TIMEOUT](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The transmission times out.
[SCSIPERIPHERAL_DDK_INVALID_OPERATION](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The operation is not supported.| + +### OH_ScsiPeripheral_Read10() + +``` +int32_t OH_ScsiPeripheral_Read10(ScsiPeripheral_Device *dev, ScsiPeripheral_IORequest *request,ScsiPeripheral_Response *response) +``` + +**Description** + +Reads data from a specified logical block. + +**Required permissions**: ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL + +**Since**: 18 + + +**Parameters** + +| Name | Description | +|-----------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------| +| [ScsiPeripheral_Device](capi-scsiperipheralddk-scsiperipheral-device.md) *dev | Device handle. For details, see [ScsiPeripheral_Device](capi-scsiperipheralddk-scsiperipheral-device.md). | +| [ScsiPeripheral_IORequest](capi-scsiperipheralddk-scsiperipheral-iorequest.md) *request | Request of the **read** command. For details, see [ScsiPeripheral_IORequest](capi-scsiperipheralddk-scsiperipheral-iorequest.md).| +| [ScsiPeripheral_Response](capi-scsiperipheralddk-scsiperipheral-response.md) *response | Response returned by the **read** command. For details, see [ScsiPeripheral_Response](capi-scsiperipheralddk-scsiperipheral-response.md).| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [SCSIPERIPHERAL_DDK_SUCCESS](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The API call is successful.
[SCSIPERIPHERAL_DDK_NO_PERM](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The permission verification fails.
[SCSIPERIPHERAL_DDK_INIT_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The DDK is not initialized.
[SCSIPERIPHERAL_DDK_INVALID_PARAMETER](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The input **dev**, **request**, **request > data**, or **response** is empty.
[SCSIPERIPHERAL_DDK_SERVICE_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The communication with the DDK service fails.
[SCSIPERIPHERAL_DDK_MEMORY_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The memory operation fails.
[SCSIPERIPHERAL_DDK_IO_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): An I/O error occurs.
[SCSIPERIPHERAL_DDK_TIMEOUT](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The transmission times out.
[SCSIPERIPHERAL_DDK_INVALID_OPERATION](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The operation is not supported.| + +### OH_ScsiPeripheral_Write10() + +``` +int32_t OH_ScsiPeripheral_Write10(ScsiPeripheral_Device *dev, ScsiPeripheral_IORequest *request,ScsiPeripheral_Response *response) +``` + +**Description** + +Writes data to a specified logical block of a device. + +**Required permissions**: ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL + +**Since**: 18 + + +**Parameters** + +| Name | Description | +|-----------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------| +| [ScsiPeripheral_Device](capi-scsiperipheralddk-scsiperipheral-device.md) *dev | Device handle. For details, see [ScsiPeripheral_Device](capi-scsiperipheralddk-scsiperipheral-device.md). | +| [ScsiPeripheral_IORequest](capi-scsiperipheralddk-scsiperipheral-iorequest.md) *request | Request of the **write** command. For details, see [ScsiPeripheral_IORequest](capi-scsiperipheralddk-scsiperipheral-iorequest.md).| +| [ScsiPeripheral_Response](capi-scsiperipheralddk-scsiperipheral-response.md) *response | Response returned by the **write** command. For details, see [ScsiPeripheral_Response](capi-scsiperipheralddk-scsiperipheral-response.md).| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [SCSIPERIPHERAL_DDK_SUCCESS](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The API call is successful.
[SCSIPERIPHERAL_DDK_NO_PERM](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The permission verification fails.
[SCSIPERIPHERAL_DDK_INIT_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The DDK is not initialized.
[SCSIPERIPHERAL_DDK_INVALID_PARAMETER](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The input **dev**, **request**, **request > data**, or **response** is empty.
[SCSIPERIPHERAL_DDK_SERVICE_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The communication with the DDK service fails.
[SCSIPERIPHERAL_DDK_MEMORY_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The memory operation fails.
[SCSIPERIPHERAL_DDK_IO_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): An I/O error occurs.
[SCSIPERIPHERAL_DDK_TIMEOUT](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The transmission times out.
[SCSIPERIPHERAL_DDK_INVALID_OPERATION](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The operation is not supported.| + +### OH_ScsiPeripheral_Verify10() + +``` +int32_t OH_ScsiPeripheral_Verify10(ScsiPeripheral_Device *dev, ScsiPeripheral_VerifyRequest *request,ScsiPeripheral_Response *response) +``` + +**Description** + +Verifies a specified logical block. + +**Required permissions**: ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL + +**Since**: 18 + + +**Parameters** + +| Name | Description | +|----------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------| +| [ScsiPeripheral_Device](capi-scsiperipheralddk-scsiperipheral-device.md) *dev | Device handle. For details, see [ScsiPeripheral_Device](capi-scsiperipheralddk-scsiperipheral-device.md). | +| [ScsiPeripheral_VerifyRequest](capi-scsiperipheralddk-scsiperipheral-verifyrequest.md) *request | Request of the **verify** command. For details, see [ScsiPeripheral_VerifyRequest](capi-scsiperipheralddk-scsiperipheral-verifyrequest.md). | +| [ScsiPeripheral_Response](capi-scsiperipheralddk-scsiperipheral-response.md) *response | Response returned by the **verify** command. For details, see [ScsiPeripheral_Response](capi-scsiperipheralddk-scsiperipheral-response.md).| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [SCSIPERIPHERAL_DDK_SUCCESS](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The API call is successful.
[SCSIPERIPHERAL_DDK_NO_PERM](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The permission verification fails.
[SCSIPERIPHERAL_DDK_INIT_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The DDK is not initialized.
[SCSIPERIPHERAL_DDK_INVALID_PARAMETER](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The input **dev**, **request**, or **response** is empty.
[SCSIPERIPHERAL_DDK_SERVICE_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The communication with the DDK service fails.
[SCSIPERIPHERAL_DDK_MEMORY_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The memory operation fails.
[SCSIPERIPHERAL_DDK_IO_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): An I/O error occurs.
[SCSIPERIPHERAL_DDK_TIMEOUT](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The transmission times out.
[SCSIPERIPHERAL_DDK_INVALID_OPERATION](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The operation is not supported.| + +### OH_ScsiPeripheral_SendRequestByCdb() + +``` +int32_t OH_ScsiPeripheral_SendRequestByCdb(ScsiPeripheral_Device *dev, ScsiPeripheral_Request *request,ScsiPeripheral_Response *response) +``` + +**Description** + +Sends SCSI commands in CDB mode. + +**Required permissions**: ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL + +**Since**: 18 + + +**Parameters** + +| Name | Description | +|----------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------| +| [ScsiPeripheral_Device](capi-scsiperipheralddk-scsiperipheral-device.md) *dev | Device handle. For details, see [ScsiPeripheral_Device](capi-scsiperipheralddk-scsiperipheral-device.md). | +| [ScsiPeripheral_Request](capi-scsiperipheralddk-scsiperipheral-request.md) *request | Request. For details, see [ScsiPeripheral_Request](capi-scsiperipheralddk-scsiperipheral-request.md). | +| [ScsiPeripheral_Response](capi-scsiperipheralddk-scsiperipheral-response.md) *response | Response. For details, see [ScsiPeripheral_Response](capi-scsiperipheralddk-scsiperipheral-response.md).| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [SCSIPERIPHERAL_DDK_SUCCESS](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The API call is successful.
[SCSIPERIPHERAL_DDK_NO_PERM](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The permission verification fails.
[SCSIPERIPHERAL_DDK_INIT_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The DDK is not initialized.
[SCSIPERIPHERAL_DDK_INVALID_PARAMETER](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The input **dev**, **request**, **request > data**, or **response**
is empty, or **request > cdbLength** is 0.
[SCSIPERIPHERAL_DDK_SERVICE_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The communication with the DDK service fails.
[SCSIPERIPHERAL_DDK_MEMORY_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The memory operation fails.
[SCSIPERIPHERAL_DDK_IO_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): An I/O error occurs.
[SCSIPERIPHERAL_DDK_TIMEOUT](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The transmission times out.
[SCSIPERIPHERAL_DDK_INVALID_OPERATION](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The operation is not supported.| + +### OH_ScsiPeripheral_CreateDeviceMemMap() + +``` +int32_t OH_ScsiPeripheral_CreateDeviceMemMap(ScsiPeripheral_Device *dev, size_t size,ScsiPeripheral_DeviceMemMap **devMmap) +``` + +**Description** + +Creates a buffer. To avoid resource leakage, use [OH_ScsiPeripheral_DestroyDeviceMemMap](capi-scsi-peripheral-api-h.md#oh_scsiperipheral_destroydevicememmap) to destroy a buffer after use. + +**Required permissions**: ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL + +**Since**: 18 + + +**Parameters** + +| Name | Description | +|------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------| +| [ScsiPeripheral_Device](capi-scsiperipheralddk-scsiperipheral-device.md) *dev | Device handle. For details, see [ScsiPeripheral_Device](capi-scsiperipheralddk-scsiperipheral-device.md). | +| size_t size | Buffer size. | +| [ScsiPeripheral_DeviceMemMap](capi-scsiperipheralddk-scsiperipheral-devicememmap.md) **devMmap | Device memory mapping used to return the created buffer to the caller. For details, see [ScsiPeripheral_DeviceMemMap](capi-scsiperipheralddk-scsiperipheral-devicememmap.md).| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [SCSIPERIPHERAL_DDK_SUCCESS](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The API call is successful.
[SCSIPERIPHERAL_DDK_INVALID_PARAMETER](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The input **dev** or **devMmap** is empty.
[SCSIPERIPHERAL_DDK_MEMORY_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The memory operation fails.| + +### OH_ScsiPeripheral_DestroyDeviceMemMap() + +``` +int32_t OH_ScsiPeripheral_DestroyDeviceMemMap(ScsiPeripheral_DeviceMemMap *devMmap) +``` + +**Description** + +Destroys a buffer. To avoid resource leakage, destroy a buffer in time after use. + +**Required permissions**: ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL + +**Since**: 18 + + +**Parameters** + +| Name | Description | +|-----------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [ScsiPeripheral_DeviceMemMap](capi-scsiperipheralddk-scsiperipheral-devicememmap.md) *devMmap | Buffer to be destroyed, which is created by calling [OH_ScsiPeripheral_CreateDeviceMemMap](#oh_scsiperipheral_createdevicememmap). For details, see [ScsiPeripheral_DeviceMemMap](capi-scsiperipheralddk-scsiperipheral-devicememmap.md).| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [SCSIPERIPHERAL_DDK_SUCCESS](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The API call is successful.
[SCSIPERIPHERAL_DDK_INVALID_PARAMETER](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The input **devMmap** is empty.
[SCSIPERIPHERAL_DDK_MEMORY_ERROR](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The memory operation fails.| + +### OH_ScsiPeripheral_ParseBasicSenseInfo() + +``` +int32_t OH_ScsiPeripheral_ParseBasicSenseInfo(uint8_t *senseData, uint8_t senseDataLen,ScsiPeripheral_BasicSenseInfo *senseInfo) +``` + +**Description** + +Parses basic sense data, including the **Information**, **Command specific information**, and **Sense key specific** fields. + +**Required permissions**: ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL + +**Since**: 18 + + +**Parameters** + +| Name| Description| +| -- | -- | +| uint8_t *senseData | Sense data to be parsed.| +| uint8_t senseDataLen | Length of sense data.| +| [ScsiPeripheral_BasicSenseInfo](capi-scsiperipheralddk-scsiperipheral-basicsenseinfo.md) *senseInfo | Basic sense data after parsing. For details, see [ScsiPeripheral_BasicSenseInfo](capi-scsiperipheralddk-scsiperipheral-basicsenseinfo.md).| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [SCSIPERIPHERAL_DDK_SUCCESS](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The API call is successful.
[SCSIPERIPHERAL_DDK_INVALID_PARAMETER](capi-scsi-peripheral-types-h.md#scsiperipheral_ddkerrcode): The input **senseData** is not a descriptor or is not of the fixed format, or **senseDataLen** is smaller than
**SCSIPERIPHERAL_MIN_DESCRIPTOR_FORMAT_SENSE** or **SCSIPERIPHERAL_MIN_FIXED_FORMAT_SENSE**.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsi-peripheral-types-h.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsi-peripheral-types-h.md new file mode 100644 index 00000000000..25a8e1e911a --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsi-peripheral-types-h.md @@ -0,0 +1,92 @@ +# scsi_peripheral_types.h + +## Overview + +Provides the enum variables, structures, and macros used in the SCSI Peripheral DDK APIs. + +**File to include**: <scsi_peripheral/scsi_peripheral_types.h> + +**Library**: libscsi.z.so + +**System capability**: SystemCapability.Driver.SCSI.Extension + +**Since**: 18 + +**Related module**: [SCSIPeripheralDDK](capi-scsiperipheralddk.md) + +## Summary + +### Structs + +| Name | typedef Keyword| Description| +|--------------------------------------------------------------------------------------| -- | -- | +| [ScsiPeripheral_DeviceMemMap](capi-scsiperipheralddk-scsiperipheral-devicememmap.md) | ScsiPeripheral_DeviceMemMap | Represents the device memory mapping created by calling **OH_ScsiPeripheral_CreateDeviceMemMap**. The buffer that uses the device memory mapping can provide better performance.| +| [ScsiPeripheral_IORequest](capi-scsiperipheralddk-scsiperipheral-iorequest.md) | ScsiPeripheral_IORequest | Read/write operation request.| +| [ScsiPeripheral_Request](capi-scsiperipheralddk-scsiperipheral-request.md) | ScsiPeripheral_Request | Request structure.| +| [ScsiPeripheral_Response](capi-scsiperipheralddk-scsiperipheral-response.md) | ScsiPeripheral_Response | Response structure.| +| [ScsiPeripheral_TestUnitReadyRequest](capi-scsiperipheralddk-scsiperipheral-testunitreadyrequest.md) | ScsiPeripheral_TestUnitReadyRequest | Request structure of the **test unit ready** command.| +| [ScsiPeripheral_InquiryRequest](capi-scsiperipheralddk-scsiperipheral-inquiryrequest.md) | ScsiPeripheral_InquiryRequest | Request structure of the **inquiry** command.| +| [ScsiPeripheral_InquiryInfo](capi-scsiperipheralddk-scsiperipheral-inquiryinfo.md) | ScsiPeripheral_InquiryInfo | SCSI inquiry data.| +| [ScsiPeripheral_ReadCapacityRequest](capi-scsiperipheralddk-scsiperipheral-readcapacityrequest.md) | ScsiPeripheral_ReadCapacityRequest | Request structure of the **read capacity** command.| +| [ScsiPeripheral_CapacityInfo](capi-scsiperipheralddk-scsiperipheral-capacityinfo.md) | ScsiPeripheral_CapacityInfo | SCSI read capacity.| +| [ScsiPeripheral_RequestSenseRequest](capi-scsiperipheralddk-scsiperipheral-requestsenserequest.md) | ScsiPeripheral_RequestSenseRequest | Request structure of the **request sense** command.| +| [ScsiPeripheral_BasicSenseInfo](capi-scsiperipheralddk-scsiperipheral-basicsenseinfo.md) | ScsiPeripheral_BasicSenseInfo | Basic information about the sense data.| +| [ScsiPeripheral_VerifyRequest](capi-scsiperipheralddk-scsiperipheral-verifyrequest.md) | ScsiPeripheral_VerifyRequest | Request structure of the **verify** command.| +| [ScsiPeripheral_Device](capi-scsiperipheralddk-scsiperipheral-device.md) | ScsiPeripheral_Device | Opaque SCSI device structure.| + +### Enums + +| Name| typedef Keyword| Description| +| -- | -- | -- | +| [ScsiPeripheral_DdkErrCode](#scsiperipheral_ddkerrcode) | ScsiPeripheral_DdkErrCode | SCSI Peripheral DDK error codes.| +| [ScsiPeripheral_Status](#scsiperipheral_status) | ScsiPeripheral_Status | SCSI status used for the response.| + +## Enum Description + +### ScsiPeripheral_DdkErrCode + +``` +enum ScsiPeripheral_DdkErrCode +``` + +**Description** + +SCSI Peripheral DDK error codes. + +**Since**: 18 + +| Enum| Description| +| -- | -- | +| SCSIPERIPHERAL_DDK_NO_PERM = 201 | Permission denied.| +| SCSIPERIPHERAL_DDK_INVALID_PARAMETER = 401 | Invalid parameter.| +| SCSIPERIPHERAL_DDK_SUCCESS = 31700000 | Operation success.| +| SCSIPERIPHERAL_DDK_MEMORY_ERROR = 31700001 | Memory-related errors, such as insufficient memory, memory data replication failure, or memory request failure.| +| SCSIPERIPHERAL_DDK_INVALID_OPERATION = 31700002 | Invalid operation.| +| SCSIPERIPHERAL_DDK_IO_ERROR = 31700003 | Device input/output operation failed.| +| SCSIPERIPHERAL_DDK_TIMEOUT = 31700004 | Transfer timeout.| +| SCSIPERIPHERAL_DDK_INIT_ERROR = 31700005 | DDK initialization error, or DDK uninitialized.| +| SCSIPERIPHERAL_DDK_SERVICE_ERROR = 31700006 | Communication with the SCSI Peripheral DDK failed.| +| SCSIPERIPHERAL_DDK_DEVICE_NOT_FOUND = 31700007 | Device not found.| + +### ScsiPeripheral_Status + +``` +enum ScsiPeripheral_Status +``` + +**Description** + +Enumerates the SCSI status codes used for the response. + +**Since**: 18 + +| Enum| Description| +| -- | -- | +| SCSIPERIPHERAL_STATUS_GOOD = 0x00 | Normal state.| +| SCSIPERIPHERAL_STATUS_CHECK_CONDITION_NEEDED = 0x02 | Status check required.| +| SCSIPERIPHERAL_STATUS_CONDITION_MET = 0x04 | Conditions met.| +| SCSIPERIPHERAL_STATUS_BUSY = 0x08 | Occupying.| +| SCSIPERIPHERAL_STATUS_RESERVATION_CONFLICT = 0x18 | Resource reservation conflict.| +| SCSIPERIPHERAL_STATUS_TASK_SET_FULL = 0x28 | Task set already full.| +| SCSIPERIPHERAL_STATUS_ACA_ACTIVE = 0x30 | ACA activity status.| +| SCSIPERIPHERAL_STATUS_TASK_ABORTED = 0x40 | Task aborted.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-basicsenseinfo.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-basicsenseinfo.md new file mode 100644 index 00000000000..85ac1eba38a --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-basicsenseinfo.md @@ -0,0 +1,24 @@ +# ScsiPeripheral_BasicSenseInfo + +## Overview + +Defines the basic information about the sense data. + +**Since**: 18 + +**Related module**: [SCSIPeripheralDDK](capi-scsiperipheralddk.md) + +**Header file**: [scsi_peripheral_types.h](capi-scsi-peripheral-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| uint8_t responseCode | Response code.| +| bool valid | Information validity flag.| +| uint64_t information | **Information** field.| +| uint64_t commandSpecific | **Command-specific information** field.| +| bool sksv | Flag of the **Sense key specific** field.| +| uint32_t senseKeySpecific | **Sense key specific** field.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-capacityinfo.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-capacityinfo.md new file mode 100644 index 00000000000..4b50bf5199f --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-capacityinfo.md @@ -0,0 +1,20 @@ +# ScsiPeripheral_CapacityInfo + +## Overview + +Defines the SCSI read capacity. + +**Since**: 18 + +**Related module**: [SCSIPeripheralDDK](capi-scsiperipheralddk.md) + +**Header file**: [scsi_peripheral_types.h](capi-scsi-peripheral-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| uint32_t lbAddress | Address of the logical unit.| +| uint32_t lbLength | Length of a single logical unit, in bytes.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-device.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-device.md new file mode 100644 index 00000000000..dd0ba7cfc45 --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-device.md @@ -0,0 +1,11 @@ +# ScsiPeripheral_Device + +## Overview + +Opaque SCSI device structure. + +**Since**: 18 + +**Related module**: [SCSIPeripheralDDK](capi-scsiperipheralddk.md) + +**Header file**: [scsi_peripheral_types.h](capi-scsi-peripheral-types-h.md) diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-devicememmap.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-devicememmap.md new file mode 100644 index 00000000000..a8422615f58 --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-devicememmap.md @@ -0,0 +1,23 @@ +# ScsiPeripheral_DeviceMemMap + +## Overview + +Represents the device memory mapping created by calling **OH_ScsiPeripheral_CreateDeviceMemMap**. The buffer that uses the device memory mapping can provide better performance. + +**Since**: 18 + +**Related module**: [SCSIPeripheralDDK](capi-scsiperipheralddk.md) + +**Header file**: [scsi_peripheral_types.h](capi-scsi-peripheral-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| uint8_t* const address | Buffer address.| +| const size_t size | Buffer size.| +| uint32_t offset | Offset of the used buffer. The default value is **0**, indicating that there is no offset and the buffer starts from the specified address.| +| uint32_t bufferLength | Length of the used buffer. By default, the value is equal to the size of the buffer, indicating that the entire buffer is used.| +| uint32_t transferredLength | Length of the data to be transferred.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-inquiryinfo.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-inquiryinfo.md new file mode 100644 index 00000000000..8edd8b50e6c --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-inquiryinfo.md @@ -0,0 +1,23 @@ +# ScsiPeripheral_InquiryInfo + +## Overview + +Defines the SCSI inquiry data. + +**Since**: 18 + +**Related module**: [SCSIPeripheralDDK](capi-scsiperipheralddk.md) + +**Header file**: [scsi_peripheral_types.h](capi-scsi-peripheral-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| uint8_t deviceType | Device type.| +| char idVendor | Vendor ID.| +| char idProduct | Product ID.| +| char revProduct | Product version.| +| ScsiPeripheral_DeviceMemMap* data | Inquiry data.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-inquiryrequest.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-inquiryrequest.md new file mode 100644 index 00000000000..4fde6fb4618 --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-inquiryrequest.md @@ -0,0 +1,23 @@ +# ScsiPeripheral_InquiryRequest + +## Overview + +Defines the request structure of the **inquiry** command. + +**Since**: 18 + +**Related module**: [SCSIPeripheralDDK](capi-scsiperipheralddk.md) + +**Header file**: [scsi_peripheral_types.h](capi-scsi-peripheral-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| uint8_t pageCode | **Page code** field. Set this field if you want to obtain certain types of device information. When an **Inquiry** command with a specific page code is run, the device returns details related to the page code. If the page code is set to **0x00**, it indicates that the standard inquiry data rather than the data of specific pages is requested.| +| uint16_t allocationLength | **Allocation length** field used to specify the size of the buffer prepared by the request initiator (usually the host) for the response data.| +| uint8_t control | **Control** field used to specify control information.| +| uint8_t byte1 | First byte of the CDB.| +| uint32_t timeout | Timeout duration, in ms.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-iorequest.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-iorequest.md new file mode 100644 index 00000000000..1099898c110 --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-iorequest.md @@ -0,0 +1,25 @@ +# ScsiPeripheral_IORequest + +## Overview + +Defines the read/write operation request. + +**Since**: 18 + +**Related module**: [SCSIPeripheralDDK](capi-scsiperipheralddk.md) + +**Header file**: [scsi_peripheral_types.h](capi-scsi-peripheral-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| uint32_t lbAddress | Start address of a logical block.| +| uint16_t transferLength | Number of consecutive logical blocks to be operated.| +| uint8_t control | **Control** field used to specify control information.| +| uint8_t byte1 | First byte of the CDB.| +| uint8_t byte6 | Sixth byte of the CDB.| +| ScsiPeripheral_DeviceMemMap* data | Buffer for data transmission.| +| uint32_t timeout | Timeout duration, in ms.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-readcapacityrequest.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-readcapacityrequest.md new file mode 100644 index 00000000000..050db621727 --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-readcapacityrequest.md @@ -0,0 +1,22 @@ +# ScsiPeripheral_ReadCapacityRequest + +## Overview + +Request structure of the **read capacity** command. + +**Since**: 18 + +**Related module**: [SCSIPeripheralDDK](capi-scsiperipheralddk.md) + +**Header file**: [scsi_peripheral_types.h](capi-scsi-peripheral-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| uint32_t lbAddress | Address of the logical unit.| +| uint8_t control | **Control** field used to specify control information.| +| uint8_t byte8 | Eighth byte of the CDB.| +| uint32_t timeout | Timeout duration, in ms.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-request.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-request.md new file mode 100644 index 00000000000..3e18a8d634e --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-request.md @@ -0,0 +1,23 @@ +# ScsiPeripheral_Request + +## Overview + +Defines the request structure. + +**Since**: 18 + +**Related module**: [SCSIPeripheralDDK](capi-scsiperipheralddk.md) + +**Header file**: [scsi_peripheral_types.h](capi-scsi-peripheral-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| uint8_t commandDescriptorBlock[SCSIPERIPHERAL_MAX_CMD_DESC_BLOCK_LEN] | Command descriptor block.| +| uint8_t cdbLength | Length of the command descriptor block.| +| int8_t dataTransferDirection | Data transmission direction.| +| ScsiPeripheral_DeviceMemMap* data | Buffer for data transmission.| +| uint32_t timeout | Timeout duration, in ms.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-requestsenserequest.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-requestsenserequest.md new file mode 100644 index 00000000000..7a4fcbd5bb9 --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-requestsenserequest.md @@ -0,0 +1,22 @@ +# ScsiPeripheral_RequestSenseRequest + +## Overview + +Defines the request structure of the **request sense** command. + +**Since**: 18 + +**Related module**: [SCSIPeripheralDDK](capi-scsiperipheralddk.md) + +**Header file**: [scsi_peripheral_types.h](capi-scsi-peripheral-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| uint8_t allocationLength | **Allocation length** field used to specify the size of the buffer prepared by the request initiator (usually the host) for the response data.| +| uint8_t control | **Control** field used to specify control information.| +| uint8_t byte1 | First byte of the CDB.| +| uint32_t timeout | Timeout duration, in ms.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-response.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-response.md new file mode 100644 index 00000000000..ef28be54ca4 --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-response.md @@ -0,0 +1,27 @@ +# ScsiPeripheral_Response + +## Overview + +Defines the response structure. + +**Since**: 18 + +**Related module**: [SCSIPeripheralDDK](capi-scsiperipheralddk.md) + +**Header file**: [scsi_peripheral_types.h](capi-scsi-peripheral-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| uint8_t senseData[SCSIPERIPHERAL_MAX_SENSE_DATA_LEN] | Sense data, that is, information returned by the SCSI device to the host to report the device status, error information, and diagnosis information.| +| ScsiPeripheral_Status status | Status when the call is complete, for example, **Good** or **Busy**.| +| uint8_t maskedStatus | Masked status, which is used in SCSI Generic (SG) interfaces of Linux to store the processed SCSI status for easy access by applications.| +| uint8_t msgStatus | Message status.| +| uint8_t sbLenWr | Number of bytes that are actually written to the sense buffer.| +| uint16_t hostStatus | Host adapter status, for example, success (0x00), connection failure (0x01), busy bus (0x02), or timeout (0x03).| +| uint16_t driverStatus | Driver status, for example, success (0x00) or busy device or resource (0x01).| +| int32_t resId | Length deviation of the actually transmitted data, that is, the number of bytes that are not transmitted.| +| uint32_t duration | Command execution duration, in ms.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-testunitreadyrequest.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-testunitreadyrequest.md new file mode 100644 index 00000000000..8970300d82b --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-testunitreadyrequest.md @@ -0,0 +1,20 @@ +# ScsiPeripheral_TestUnitReadyRequest + +## Overview + +Defines the request structure of the **test unit ready** command. + +**Since**: 18 + +**Related module**: [SCSIPeripheralDDK](capi-scsiperipheralddk.md) + +**Header file**: [scsi_peripheral_types.h](capi-scsi-peripheral-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| uint8_t control | **Control** field used to specify control information.| +| uint32_t timeout | Timeout duration, in ms.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-verifyrequest.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-verifyrequest.md new file mode 100644 index 00000000000..0b3e0232117 --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk-scsiperipheral-verifyrequest.md @@ -0,0 +1,24 @@ +# ScsiPeripheral_VerifyRequest + +## Overview + +Defines the request structure of the **verify** command. + +**Since**: 18 + +**Related module**: [SCSIPeripheralDDK](capi-scsiperipheralddk.md) + +**Header file**: [scsi_peripheral_types.h](capi-scsi-peripheral-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| uint32_t lbAddress | Start address of logical blocks.| +| uint16_t verificationLength | Number of consecutive logical blocks.| +| uint8_t control | **Control** field used to specify control information.| +| uint8_t byte1 | First byte of the CDB.| +| uint8_t byte6 | Sixth byte of the CDB.| +| uint32_t timeout | Timeout duration, in ms.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk.md new file mode 100644 index 00000000000..96c351f2a0b --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-scsiperipheralddk.md @@ -0,0 +1,13 @@ +# SCSIPeripheralDDK + +## Overview + +The SCSI Peripheral DDK is a suite dedicated to SCSI device driver development at the application layer. It provides APIs for initializing the DDK, releasing the DDK, enabling and disabling devices, and reading data from and writing data to devices. It also declares the macros, enum variables, and data structures required by the SCSI Peripheral DDK APIs. + +**Since**: 18 +## Files + +| Name| Description| +| -- | -- | +| [scsi_peripheral_api.h](capi-scsi-peripheral-api-h.md) | Declares the SCSI Peripheral DDK APIs used by the host to access the SCSI device.| +| [scsi_peripheral_types.h](capi-scsi-peripheral-types-h.md) | Provides the enum variables, structures, and macros used in the SCSI Peripheral DDK APIs.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-serialddk-usbserial-devicehandle.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-serialddk-usbserial-devicehandle.md new file mode 100644 index 00000000000..2957ab32be1 --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-serialddk-usbserial-devicehandle.md @@ -0,0 +1,11 @@ +# UsbSerial_DeviceHandle + +## Overview + +Defines the data structures (opaque) for the USB serial port device. + +**Since**: 18 + +**Related module**: [SerialDdk](capi-serialddk.md) + +**Header file:** [usb_serial_types.h](capi-usb-serial-types-h.md) diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-serialddk-usbserial-params.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-serialddk-usbserial-params.md new file mode 100644 index 00000000000..a10e98eb82c --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-serialddk-usbserial-params.md @@ -0,0 +1,22 @@ +# UsbSerial_Params + +## Overview + +Defines the USB serial port parameters for the USB SERIAL DDK. + +**Since**: 18 + +**Related module**: [SerialDdk](capi-serialddk.md) + +**Header file:** [usb_serial_types.h](capi-usb-serial-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| uint32_t baudRate | Baud rate.| +| uint8_t nDataBits | Number of data transfer bits.| +| uint8_t nStopBits | Number of data stop bits.| +| uint8_t parity | Parity settings.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-serialddk.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-serialddk.md new file mode 100644 index 00000000000..52d8b829738 --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-serialddk.md @@ -0,0 +1,15 @@ +# SerialDdk + +## Overview + +Provides USB SERIAL DDK APIs as well as the enum types and data structs used by them. Serial port communication is often used in industrial scenarios and some legacy devices, such as card issuers and ID card readers. The open APIs of USB SERIAL DDK can be used to develop drivers for non-standard USB peripherals that use USB serial ports. + +**System capability**: SystemCapability.Driver.UsbSerial.Extension + +**Since**: 18 +## Files + +| Name| Description| +| -- | -- | +| [usb_serial_api.h](capi-usb-serial-api-h.md) | Declares the USB SERIAL DDK APIs used by the host to access the serial port device.| +| [usb_serial_types.h](capi-usb-serial-types-h.md) | Provides the enumerated variables, structures, and macros used in USB SERIAL DDK APIs.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-usb-ddk-api-h.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usb-ddk-api-h.md new file mode 100644 index 00000000000..e2197698d66 --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usb-ddk-api-h.md @@ -0,0 +1,480 @@ +# usb_ddk_api.h + +## Overview + +Declares the USB DDK APIs used by the USB host to access USB devices. + +**File to include**: + +**Library**: libusb_ndk.z.so + +**System capability**: SystemCapability.Driver.USB.Extension + +**Since**: 10 + +**Related module**: [UsbDDK](capi-usbddk.md) + +## Summary + +### Functions + +| Name| Description| +| -- | -- | +| [int32_t OH_Usb_Init(void)](#oh_usb_init) | Initializes the DDK.| +| [void OH_Usb_Release(void)](#oh_usb_release) | Releases the USB DDK.| +| [int32_t OH_Usb_ReleaseResource(void)](#oh_usb_releaseresource) | Releases the USB DDK.| +| [int32_t OH_Usb_GetDeviceDescriptor(uint64_t deviceId, struct UsbDeviceDescriptor *desc)](#oh_usb_getdevicedescriptor) | Obtains the device descriptor.| +| [int32_t OH_Usb_GetConfigDescriptor(uint64_t deviceId, uint8_t configIndex, struct UsbDdkConfigDescriptor ** const config)](#oh_usb_getconfigdescriptor) | Obtains the configuration descriptor. To avoid memory leakage, use [OH_Usb_FreeConfigDescriptor](capi-usb-ddk-api-h.md#oh_usb_freeconfigdescriptor) to release a descriptor after use.| +| [void OH_Usb_FreeConfigDescriptor(const struct UsbDdkConfigDescriptor * const config)](#oh_usb_freeconfigdescriptor) | Releases the configuration descriptor. To avoid memory leakage, release a descriptor after use.| +| [int32_t OH_Usb_ClaimInterface(uint64_t deviceId, uint8_t interfaceIndex, uint64_t *interfaceHandle)](#oh_usb_claiminterface) | Declares a USB interface.| +| [int32_t OH_Usb_ReleaseInterface(uint64_t interfaceHandle)](#oh_usb_releaseinterface) | Releases a USB interface.| +| [int32_t OH_Usb_SelectInterfaceSetting(uint64_t interfaceHandle, uint8_t settingIndex)](#oh_usb_selectinterfacesetting) | Activates the alternate setting of a USB interface.| +| [int32_t OH_Usb_GetCurrentInterfaceSetting(uint64_t interfaceHandle, uint8_t *settingIndex)](#oh_usb_getcurrentinterfacesetting) | Obtains the activated alternate setting of a USB interface.| +| [int32_t OH_Usb_SendControlReadRequest(uint64_t interfaceHandle, const struct UsbControlRequestSetup *setup,uint32_t timeout, uint8_t *data, uint32_t *dataLen)](#oh_usb_sendcontrolreadrequest) | Sends a control read transfer request. This API works in a synchronous manner.| +| [int32_t OH_Usb_SendControlWriteRequest(uint64_t interfaceHandle, const struct UsbControlRequestSetup *setup,uint32_t timeout, const uint8_t *data, uint32_t dataLen)](#oh_usb_sendcontrolwriterequest) | Sends a control write transfer request. This API works in a synchronous manner.| +| [int32_t OH_Usb_SendPipeRequest(const struct UsbRequestPipe *pipe, UsbDeviceMemMap *devMmap)](#oh_usb_sendpiperequest) | Sends a pipe request. This API works in a synchronous manner. It applies to interrupt transfer and bulk transfer.| +| [int32_t OH_Usb_SendPipeRequestWithAshmem(const struct UsbRequestPipe *pipe, DDK_Ashmem *ashmem)](#oh_usb_sendpiperequestwithashmem) | Sends a pipe request. This API works in a synchronous manner. It applies to interrupt transfer and bulk transfer.| +| [int32_t OH_Usb_CreateDeviceMemMap(uint64_t deviceId, size_t size, UsbDeviceMemMap **devMmap)](#oh_usb_createdevicememmap) | Creates a buffer. To avoid resource leakage, use [OH_Usb_DestroyDeviceMemMap](capi-usb-ddk-api-h.md#oh_usb_destroydevicememmap) to destroy a buffer after use.| +| [void OH_Usb_DestroyDeviceMemMap(UsbDeviceMemMap *devMmap)](#oh_usb_destroydevicememmap) | Destroys a buffer. To avoid resource leakage, destroy a buffer in time after use.| +| [int32_t OH_Usb_GetDevices(struct Usb_DeviceArray *devices)](#oh_usb_getdevices) | Obtains the USB device ID list. Ensure that the input pointer is valid and the number of devices does not exceed 128. To prevent resource leakage, release the member memory after usage. Besides, make sure that the obtained USB device ID has been filtered by **vid** in the driver configuration information.| + +## Function Description + +### OH_Usb_Init() + +``` +int32_t OH_Usb_Init(void) +``` + +**Description** + +Initializes the DDK. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB + +**Since**: 10 + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [USB_DDK_SUCCESS](capi-usb-ddk-types-h.md#usbddkerrcode): The operation is successful.
[USB_DDK_INVALID_OPERATION](capi-usb-ddk-types-h.md#usbddkerrcode): The USB DDK service connection fails, or an internal error occurs.
USB_DDK_NO_PERM: The permission check fails.
[USB_DDK_MEMORY_ERROR](capi-usb-ddk-types-h.md#usbddkerrcode): The memory allocation fails.| + +### OH_Usb_Release() + +``` +void OH_Usb_Release(void) +``` + +**Description** + +Releases the USB DDK. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB + +**Since**: 10 + +### OH_Usb_ReleaseResource() + +``` +int32_t OH_Usb_ReleaseResource(void) +``` + +**Description** + +Releases the USB DDK. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB + +**Since**: 18 + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [USB_DDK_SUCCESS](capi-usb-ddk-types-h.md#usbddkerrcode): The operation is successful.
USB_DDK_NO_PERM: The permission check fails.
[USB_DDK_INVALID_OPERATION](capi-usb-ddk-types-h.md#usbddkerrcode): The USB DDK service connection fails, or an internal error occurs.| + +### OH_Usb_GetDeviceDescriptor() + +``` +int32_t OH_Usb_GetDeviceDescriptor(uint64_t deviceId, struct UsbDeviceDescriptor *desc) +``` + +**Description** + +Obtains the device descriptor. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB + +**Since**: 10 + + +**Parameters** + +| Name| Description| +| -- | -- | +| uint64_t deviceId | Device ID.| +| [struct UsbDeviceDescriptor](capi-usbddk-usbdevicedescriptor.md) *desc | Device descriptor. For details, see [UsbDeviceDescriptor](capi-usbddk-usbdevicedescriptor.md).| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [USB_DDK_SUCCESS](capi-usb-ddk-types-h.md#usbddkerrcode): The operation is successful.
USB_DDK_NO_PERM: The permission check fails.
[USB_DDK_INVALID_OPERATION](capi-usb-ddk-types-h.md#usbddkerrcode): The USB DDK service connection fails, or an internal error occurs.
[USB_DDK_INVALID_PARAMETER](capi-usb-ddk-types-h.md#usbddkerrcode): The input **desc** is a null pointer.| + +### OH_Usb_GetConfigDescriptor() + +``` +int32_t OH_Usb_GetConfigDescriptor(uint64_t deviceId, uint8_t configIndex, struct UsbDdkConfigDescriptor ** const config) +``` + +**Description** + +Obtains the configuration descriptor. To avoid memory leakage, use [OH_Usb_FreeConfigDescriptor](capi-usb-ddk-api-h.md#oh_usb_freeconfigdescriptor) to release a descriptor after use. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB + +**Since**: 10 + + +**Parameters** + +| Name | Description| +|---------------------------------------------------| -- | +| uint64_t deviceId | Device ID.| +| uint8_t configIndex | Configuration index, which corresponds to {@link bConfigurationValue} in the USB protocol.| +| struct [UsbDdkConfigDescriptor](capi-usbddk-usbddkconfigdescriptor.md) ** const config | Configuration descriptor, which includes the standard configuration descriptor defined in the USB protocol and the associated interface descriptor and endpoint descriptor.| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [USB_DDK_SUCCESS](capi-usb-ddk-types-h.md#usbddkerrcode): The operation is successful.
USB_DDK_NO_PERM: The permission check fails.
[USB_DDK_INVALID_OPERATION](capi-usb-ddk-types-h.md#usbddkerrcode): The USB DDK service connection fails, or an internal error occurs.
[USB_DDK_INVALID_PARAMETER](capi-usb-ddk-types-h.md#usbddkerrcode): The input **config** is a null pointer.
{@link USB_DDK_IO_FAILED}: An I/O exception occurs.
[USB_DDK_MEMORY_ERROR](capi-usb-ddk-types-h.md#usbddkerrcode): The memory allocation fails.| + +### OH_Usb_FreeConfigDescriptor() + +``` +void OH_Usb_FreeConfigDescriptor(const struct UsbDdkConfigDescriptor * const config) +``` + +**Description** + +Releases the configuration descriptor. To avoid memory leakage, release a descriptor after use. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB + +**Since**: 10 + + +**Parameters** + +| Name| Description| +| -- | -- | +| const struct [UsbDdkConfigDescriptor](capi-usbddk-usbddkconfigdescriptor.md) * const config | Configuration descriptor, which is obtained by calling [OH_Usb_GetConfigDescriptor](capi-usb-ddk-api-h.md#oh_usb_getconfigdescriptor).| + +### OH_Usb_ClaimInterface() + +``` +int32_t OH_Usb_ClaimInterface(uint64_t deviceId, uint8_t interfaceIndex, uint64_t *interfaceHandle) +``` + +**Description** + +Declares a USB interface. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB + +**Since**: 10 + + +**Parameters** + +| Name| Description| +| -- | -- | +| uint64_t deviceId | Device ID.| +| uint8_t interfaceIndex | Interface index, which corresponds to [bInterfaceNumber](capi-usbddk-usbinterfacedescriptor.md) in the USB protocol.| +| uint64_t *interfaceHandle | Interface operation handle. After the interface is claimed successfully, a value will be assigned to this parameter.| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [USB_DDK_SUCCESS](capi-usb-ddk-types-h.md#usbddkerrcode): The operation is successful.
USB_DDK_NO_PERM: The permission check fails.
[USB_DDK_INVALID_OPERATION](capi-usb-ddk-types-h.md#usbddkerrcode): The USB DDK service connection fails, or an internal error occurs.
[USB_DDK_INVALID_PARAMETER](capi-usb-ddk-types-h.md#usbddkerrcode): The input **interfaceHandle** is a null pointer.
[USB_DDK_MEMORY_ERROR](capi-usb-ddk-types-h.md#usbddkerrcode): The memory to be allocated exceeds the limit.| + +### OH_Usb_ReleaseInterface() + +``` +int32_t OH_Usb_ReleaseInterface(uint64_t interfaceHandle) +``` + +**Description** + +Releases a USB interface. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB + +**Since**: 10 + + +**Parameters** + +| Name| Description| +| -- | -- | +| uint64_t interfaceHandle | Interface operation handle.| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [USB_DDK_SUCCESS](capi-usb-ddk-types-h.md#usbddkerrcode): The operation is successful.
USB_DDK_NO_PERM: The permission check fails.
[USB_DDK_INVALID_OPERATION](capi-usb-ddk-types-h.md#usbddkerrcode): The USB DDK service connection fails, or an internal error occurs.
[USB_DDK_INVALID_PARAMETER](capi-usb-ddk-types-h.md#usbddkerrcode): One or more parameters are invalid.| + +### OH_Usb_SelectInterfaceSetting() + +``` +int32_t OH_Usb_SelectInterfaceSetting(uint64_t interfaceHandle, uint8_t settingIndex) +``` + +**Description** + +Activates the alternate setting of a USB interface. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB + +**Since**: 10 + + +**Parameters** + +| Name| Description| +| -- | -- | +| uint64_t interfaceHandle | Interface operation handle.| +| uint8_t settingIndex | Index of the alternate setting, which corresponds to {@link bAlternateSetting} in the USB protocol.| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [USB_DDK_SUCCESS](capi-usb-ddk-types-h.md#usbddkerrcode): The operation is successful.
USB_DDK_NO_PERM: The permission check fails.
[USB_DDK_INVALID_OPERATION](capi-usb-ddk-types-h.md#usbddkerrcode): The USB DDK service connection fails, or an internal error occurs.
[USB_DDK_INVALID_PARAMETER](capi-usb-ddk-types-h.md#usbddkerrcode) Incorrect parameter.| + +### OH_Usb_GetCurrentInterfaceSetting() + +``` +int32_t OH_Usb_GetCurrentInterfaceSetting(uint64_t interfaceHandle, uint8_t *settingIndex) +``` + +**Description** + +Obtains the activated alternate setting of a USB interface. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB + +**Since**: 10 + + +**Parameters** + +| Name| Description| +| -- | -- | +| uint64_t interfaceHandle | Interface operation handle.| +| uint8_t *settingIndex | Index of the alternate setting, which corresponds to {@link bAlternateSetting} in the USB protocol.| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [USB_DDK_SUCCESS](capi-usb-ddk-types-h.md#usbddkerrcode): The operation is successful.
USB_DDK_NO_PERM: The permission check fails.
[USB_DDK_INVALID_OPERATION](capi-usb-ddk-types-h.md#usbddkerrcode): The USB DDK service connection fails, or an internal error occurs.
[USB_DDK_INVALID_PARAMETER](capi-usb-ddk-types-h.md#usbddkerrcode): The input **settingIndex** is a null pointer.| + +### OH_Usb_SendControlReadRequest() + +``` +int32_t OH_Usb_SendControlReadRequest(uint64_t interfaceHandle, const struct UsbControlRequestSetup *setup,uint32_t timeout, uint8_t *data, uint32_t *dataLen) +``` + +**Description** + +Sends a control read transfer request. This API works in a synchronous manner. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB + +**Since**: 10 + + +**Parameters** + +| Name| Description| +| -- | -- | +| uint64_t interfaceHandle | Interface operation handle.| +| [const struct UsbControlRequestSetup](capi-usbddk-usbcontrolrequestsetup.md) *setup | Request parameters. For details, see [UsbControlRequestSetup](capi-usbddk-usbcontrolrequestsetup.md).| +| uint32_t timeout | Timeout duration, in ms.| +| uint8_t *data | Data to transfer.| +| uint32_t *dataLen | Data length. The return value indicates the length of the actually read data.| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [USB_DDK_SUCCESS](capi-usb-ddk-types-h.md#usbddkerrcode): The operation is successful.
[USB_DDK_FAILED](capi-usb-ddk-types-h.md#usbddkerrcode): The permission check fails.
[USB_DDK_INVALID_OPERATION](capi-usb-ddk-types-h.md#usbddkerrcode): The USB DDK service connection fails, or an internal error occurs.
[USB_DDK_INVALID_PARAMETER](capi-usb-ddk-types-h.md#usbddkerrcode): The input **setup**, **data**, or **dataLen** is a null pointer, or the value of **datalen** is less than the length of the read data.
[USB_DDK_MEMORY_ERROR](capi-usb-ddk-types-h.md#usbddkerrcode): The attempt to copy the memory that stores the read data fails.
USB_DDK_IO_FAILED: An I/O exception occurs.
[USB_DDK_TIMEOUT](capi-usb-ddk-types-h.md#usbddkerrcode): The operation times out.| + +### OH_Usb_SendControlWriteRequest() + +``` +int32_t OH_Usb_SendControlWriteRequest(uint64_t interfaceHandle, const struct UsbControlRequestSetup *setup,uint32_t timeout, const uint8_t *data, uint32_t dataLen) +``` + +**Description** + +Sends a control write transfer request. This API works in a synchronous manner. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB + +**Since**: 10 + + +**Parameters** + +| Name| Description| +| -- | -- | +| uint64_t interfaceHandle | Interface operation handle.| +| [const struct UsbControlRequestSetup](capi-usbddk-usbcontrolrequestsetup.md) *setup | Request parameters. For details, see [UsbControlRequestSetup](capi-usbddk-usbcontrolrequestsetup.md).| +| uint32_t timeout | Timeout duration, in ms.| +| const uint8_t *data | Data to transfer.| +| uint32_t dataLen | Data length.| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [USB_DDK_SUCCESS](capi-usb-ddk-types-h.md#usbddkerrcode): The operation is successful.
[USB_DDK_FAILED](capi-usb-ddk-types-h.md#usbddkerrcode): The permission check fails.
[USB_DDK_INVALID_OPERATION](capi-usb-ddk-types-h.md#usbddkerrcode): The USB DDK service connection fails, or an internal error occurs.
[USB_DDK_INVALID_PARAMETER](capi-usb-ddk-types-h.md#usbddkerrcode): The input **setup** or **data** is a null pointer.
[USB_DDK_MEMORY_ERROR](capi-usb-ddk-types-h.md#usbddkerrcode): The attempt to copy the memory that stores the read data fails.
USB_DDK_IO_FAILED: An I/O exception occurs.
[USB_DDK_TIMEOUT](capi-usb-ddk-types-h.md#usbddkerrcode): The operation times out.| + +### OH_Usb_SendPipeRequest() + +``` +int32_t OH_Usb_SendPipeRequest(const struct UsbRequestPipe *pipe, UsbDeviceMemMap *devMmap) +``` + +**Description** + +Sends a pipe request. This API works in a synchronous manner. It applies to interrupt transfer and bulk transfer. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB + +**Since**: 10 + + +**Parameters** + +| Name| Description| +| -- | -- | +| [const struct UsbRequestPipe](capi-usbddk-usbrequestpipe.md) *pipe | Pipe used to transfer data.| +| [UsbDeviceMemMap](capi-usbddk-usbdevicememmap.md) *devMmap | Data buffer, which can be obtained by calling [OH_Usb_CreateDeviceMemMap](capi-usb-ddk-api-h.md#oh_usb_createdevicememmap).| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [USB_DDK_SUCCESS](capi-usb-ddk-types-h.md#usbddkerrcode): The operation is successful.
USB_DDK_NO_PERM: The permission check fails.
[USB_DDK_INVALID_OPERATION](capi-usb-ddk-types-h.md#usbddkerrcode): The USB DDK service connection fails, or an internal error occurs.
[USB_DDK_INVALID_PARAMETER](capi-usb-ddk-types-h.md#usbddkerrcode): The input **pipe** or **devMmap** is a null pointer, or the **devMmap** address is null.
[USB_DDK_MEMORY_ERROR](capi-usb-ddk-types-h.md#usbddkerrcode): The attempt to copy the memory that stores the read data fails.
USB_DDK_IO_FAILED: An I/O exception occurs.
[USB_DDK_TIMEOUT](capi-usb-ddk-types-h.md#usbddkerrcode): The operation times out.| + +### OH_Usb_SendPipeRequestWithAshmem() + +``` +int32_t OH_Usb_SendPipeRequestWithAshmem(const struct UsbRequestPipe *pipe, DDK_Ashmem *ashmem) +``` + +**Description** + +Sends a pipe request. This API works in a synchronous manner. It applies to interrupt transfer and bulk transfer. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB + +**Since**: 12 + + +**Parameters** + +| Name | Description| +|-------------------------------------------------------------| -- | +| [const struct UsbRequestPipe](capi-usbddk-usbrequestpipe.md) *pipe | Pipe used to transfer data.| +| [DDK_Ashmem](capi-baseddk-ddk-ashmem.md) *ashmem | Shared memory, which can be obtained by calling {@link OH_DDK_CreateAshmem}.| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [USB_DDK_SUCCESS](capi-usb-ddk-types-h.md#usbddkerrcode): The operation is successful.
USB_DDK_NO_PERM: The permission check fails.
[USB_DDK_INVALID_OPERATION](capi-usb-ddk-types-h.md#usbddkerrcode): The USB DDK service connection fails, or an internal error occurs.
[USB_DDK_INVALID_PARAMETER](capi-usb-ddk-types-h.md#usbddkerrcode): The input **pipe** or **ashmem** is a null pointer, or the **ashmem** address is null.
[USB_DDK_MEMORY_ERROR](capi-usb-ddk-types-h.md#usbddkerrcode): The attempt to copy the memory that stores the read data fails.
USB_DDK_IO_FAILED: An I/O exception occurs.
[USB_DDK_TIMEOUT](capi-usb-ddk-types-h.md#usbddkerrcode): The operation times out.| + +### OH_Usb_CreateDeviceMemMap() + +``` +int32_t OH_Usb_CreateDeviceMemMap(uint64_t deviceId, size_t size, UsbDeviceMemMap **devMmap) +``` + +**Description** + +Creates a buffer. To avoid resource leakage, use [OH_Usb_DestroyDeviceMemMap](capi-usb-ddk-api-h.md#oh_usb_destroydevicememmap) to destroy a buffer after use. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB + +**Since**: 10 + + +**Parameters** + +| Name| Description| +| -- | -- | +| uint64_t deviceId | Device ID.| +| size_t size | Buffer size.| +| [UsbDeviceMemMap](capi-usbddk-usbdevicememmap.md) **devMmap | Data memory map, through which the created buffer is returned to the caller.| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [USB_DDK_SUCCESS](capi-usb-ddk-types-h.md#usbddkerrcode): The operation is successful.
USB_DDK_NO_PERM: The permission check fails.
[USB_DDK_INVALID_PARAMETER](capi-usb-ddk-types-h.md#usbddkerrcode): The input **devMmap** is a null pointer.
[USB_DDK_MEMORY_ERROR](capi-usb-ddk-types-h.md#usbddkerrcode): The memory mapping fails, or the memory allocation of **devMmap** fails.| + +### OH_Usb_DestroyDeviceMemMap() + +``` +void OH_Usb_DestroyDeviceMemMap(UsbDeviceMemMap *devMmap) +``` + +**Description** + +Destroys a buffer. To avoid resource leakage, destroy a buffer in time after use. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB + +**Since**: 10 + + +**Parameters** + +| Name| Description| +| -- | -- | +| [UsbDeviceMemMap](capi-usbddk-usbdevicememmap.md) *devMmap | Destroys the buffer created by calling [OH_Usb_CreateDeviceMemMap](capi-usb-ddk-api-h.md#oh_usb_createdevicememmap).| + +### OH_Usb_GetDevices() + +``` +int32_t OH_Usb_GetDevices(struct Usb_DeviceArray *devices) +``` + +**Description** + +Obtains the USB device ID list. Ensure that the input pointer is valid and the number of devices does not exceed 128. To prevent resource leakage, release the member memory after usage. Besides, make sure that the obtained USB device ID has been filtered by **vid** in the driver configuration information. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB + +**Since**: 18 + + +**Parameters** + +| Name| Description| +| -- | -- | +| [struct Usb_DeviceArray](capi-usbddk-usb-devicearray.md) *devices | Device memory address, which is used to store the obtained device ID list and quantity.| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [USB_DDK_SUCCESS](capi-usb-ddk-types-h.md#usbddkerrcode): The operation is successful.
USB_DDK_NO_PERM: The permission check fails.
[USB_DDK_INVALID_OPERATION](capi-usb-ddk-types-h.md#usbddkerrcode): The USB DDK service connection fails, or an internal error occurs.
[USB_DDK_INVALID_PARAMETER](capi-usb-ddk-types-h.md#usbddkerrcode): The input **devices** is a null pointer.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-usb-ddk-types-h.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usb-ddk-types-h.md new file mode 100644 index 00000000000..01953be2973 --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usb-ddk-types-h.md @@ -0,0 +1,65 @@ +# usb_ddk_types.h + +## Overview + +Provides the enumerated variables, structures, and macros used in USB DDK APIs. + +**File to include**: + +**Library**: libusb_ndk.z.so + +**System capability**: SystemCapability.Driver.USB.Extension + +**Since**: 10 + +**Related module**: [UsbDDK](capi-usbddk.md) + +## Summary + +### Structs + +| Name| typedef Keyword| Description| +| -- | -- | -- | +| [UsbControlRequestSetup](capi-usbddk-usbcontrolrequestsetup.md) | __attribute__((aligned(8))) UsbControlRequestSetup | Control transfer setup data, which corresponds to **Setup Data** in the USB protocol.| +| [UsbDeviceDescriptor](capi-usbddk-usbdevicedescriptor.md) | __attribute__((aligned(8))) UsbDeviceDescriptor | Standard device descriptor, which corresponds to **Standard Device Descriptor** in the USB protocol.| +| [UsbConfigDescriptor](capi-usbddk-usbconfigdescriptor.md) | __attribute__((packed)) UsbConfigDescriptor | Standard configuration descriptor, which corresponds to **Standard Configuration Descriptor** in the USB protocol.| +| [UsbInterfaceDescriptor](capi-usbddk-usbinterfacedescriptor.md) | __attribute__((packed)) UsbInterfaceDescriptor | Standard interface descriptor, which corresponds to **Standard Interface Descriptor** in the USB protocol.| +| [UsbEndpointDescriptor](capi-usbddk-usbendpointdescriptor.md) | __attribute__((packed)) UsbEndpointDescriptor | Standard endpoint descriptor, which corresponds to **Standard Endpoint Descriptor** in the USB protocol.| +| [UsbDdkEndpointDescriptor](capi-usbddk-usbddkendpointdescriptor.md) | UsbDdkEndpointDescriptor | Endpoint descriptor.| +| [UsbDdkInterfaceDescriptor](capi-usbddk-usbddkinterfacedescriptor.md) | UsbDdkInterfaceDescriptor | Interface descriptor.| +| [UsbDdkInterface](capi-usbddk-usbddkinterface.md) | UsbDdkInterface | USB DDK interface, which is a collection of alternate settings for a particular USB interface.| +| [UsbDdkConfigDescriptor](capi-usbddk-usbddkconfigdescriptor.md) | UsbDdkConfigDescriptor | Configuration descriptor.| +| [UsbRequestPipe](capi-usbddk-usbrequestpipe.md) | __attribute__((aligned(8))) UsbRequestPipe | Defines a USB request pipe.| +| [UsbDeviceMemMap](capi-usbddk-usbdevicememmap.md) | UsbDeviceMemMap | Device memory map created by calling **OH_Usb_CreateDeviceMemMap**. A buffer using the device memory map can provide better performance.| +| [Usb_DeviceArray](capi-usbddk-usb-devicearray.md) | Usb_DeviceArray | Defines the device ID list, which is used to store the device IDs and device quantity obtained using **OH_Usb_GetDevices**.| + +### Enums + +| Name| typedef Keyword| Description| +| -- | -- | -- | +| [UsbDdkErrCode](#usbddkerrcode) | UsbDdkErrCode | USB DDK error code definitions.| + +## Enum Description + +### UsbDdkErrCode + +``` +enum UsbDdkErrCode +``` + +**Description** + +USB DDK error code definitions. + +**Since**: 10 + +| Enum| Description| +| -- | -- | +| USB_DDK_SUCCESS = 0 | Operation succeeded.| +| USB_DDK_FAILED = -1 | Operation failed.| +| USB_DDK_INVALID_PARAMETER = -2 | Invalid parameter.| +| USB_DDK_MEMORY_ERROR = -3 | Memory-related error, for example, insufficient memory, memory data copy failure, or memory application failure.| +| USB_DDK_INVALID_OPERATION = -4 | Invalid operation.| +| USB_DDK_NULL_PTR = -5 | Null pointer.| +| USB_DDK_DEVICE_BUSY = -6 | Device busy.| +| USB_DDK_TIMEOUT = -7 | Transfer timeout.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-usb-serial-api-h.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usb-serial-api-h.md new file mode 100644 index 00000000000..a23f40d849d --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usb-serial-api-h.md @@ -0,0 +1,386 @@ +# usb_serial_api.h + +## Overview + +Declares the USB Serial DDK APIs used by the host to access the serial port device. + +**File to include**: + +**Library**: libusb_serial.z.so + +**System capability**: SystemCapability.Driver.UsbSerial.Extension + +**Since**: 18 + +**Related module**: [SerialDdk](capi-serialddk.md) + +## Summary + +### Functions + +| Name| Description| +| -- | -- | +| [int32_t OH_UsbSerial_Init(void)](#oh_usbserial_init) | Initializes the USB Serial DDK.| +| [int32_t OH_UsbSerial_Release(void)](#oh_usbserial_release) | Releases the USB Serial DDK.| +| [int32_t OH_UsbSerial_Open(uint64_t deviceId, uint8_t interfaceIndex, UsbSerial_DeviceHandle **dev)](#oh_usbserial_open) | Enables the USB serial port device based on the specified **deviceId** and **interfaceIndex**.| +| [int32_t OH_UsbSerial_Close(UsbSerial_DeviceHandle *dev)](#oh_usbserial_close) | Disables the USB serial port device.| +| [int32_t OH_UsbSerial_Read(UsbSerial_DeviceHandle *dev, uint8_t *buff, uint32_t bufferSize, uint32_t *bytesRead)](#oh_usbserial_read) | Reads data from the USB serial port device to the buffer.| +| [int32_t OH_UsbSerial_Write(UsbSerial_DeviceHandle *dev, uint8_t *buff, uint32_t bufferSize, uint32_t *bytesWritten)](#oh_usbserial_write) | Writes the data in the buffer to the USB serial port device.| +| [int32_t OH_UsbSerial_SetBaudRate(UsbSerial_DeviceHandle *dev, uint32_t baudRate)](#oh_usbserial_setbaudrate) | Sets the baud rate for a USB serial port device. If the parameters of the USB serial port device are set to the default values (the data bit is **8**, the stop bit is **1**, and parity is disabled for data transfer), you only need to call this API to set the baud rate.| +| [int32_t OH_UsbSerial_SetParams(UsbSerial_DeviceHandle *dev, UsbSerial_Params *params)](#oh_usbserial_setparams) | Sets the parameters of the USB serial port device. If the parameters of the USB serial port device are not set to the default values (the data bit is **8**, the stop bit is **1**, and parity is disabled for data transfer), you only need to call this API to set the related parameters.| +| [int32_t OH_UsbSerial_SetTimeout(UsbSerial_DeviceHandle *dev, int timeout)](#oh_usbserial_settimeout) | Sets the timeout interval (ms) for reading data reported by a USB serial port device. If this function is not called, the timeout value is **0** by default, indicating that data is returned immediately regardless of whether data is read. If you need to wait for a certain period of time or data must be read, call this API to set the timeout interval.| +| [int32_t OH_UsbSerial_SetFlowControl(UsbSerial_DeviceHandle *dev, UsbSerial_FlowControl flowControl)](#oh_usbserial_setflowcontrol) | Sets flow control parameters. Flow control is used to manage the data transfer rate during communication with the USB serial port device to ensure that the sender does not send data that exceeds the processing capability of the receiver.
If flow control is required, call this API to set flow control parameters. If this API is not called, flow control is not performed by default.| +| [int32_t OH_UsbSerial_Flush(UsbSerial_DeviceHandle *dev)](#oh_usbserial_flush) | Clears the input and output buffers after the write operation is complete. If a large amount of data is to be transmitted to the USB serial port device, the data may be buffered in the kernel for transmission. If the application closes the file descriptor or exits before the data is completely sent out, some data may be lost.
If the data is not sent out, some data may be lost. You can call this API to ensure that all data is sent before subsequent operations are performed.| +| [int32_t OH_UsbSerial_FlushInput(UsbSerial_DeviceHandle *dev)](#oh_usbserial_flushinput) | Refreshes the input buffer. The data in the buffer is cleared immediately. During the communication with the USB serial port device, especially in the debugging phase, disordered data packets or other exceptions may occur.
You can call this API to clear these exceptions to restore the communication.| +| [int32_t OH_UsbSerial_FlushOutput(UsbSerial_DeviceHandle *dev)](#oh_usbserial_flushoutput) | Refreshes the output buffer. The data in the buffer is cleared immediately. During the communication with the USB serial port device, especially in the debugging phase, disordered data packets or other exceptions may occur.
You can call this API to clear these exceptions to restore the communication.| + +## Function Description + +### OH_UsbSerial_Init() + +``` +int32_t OH_UsbSerial_Init(void) +``` + +**Description** + +Initializes the USB Serial DDK. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB_SERIAL + +**Since**: 18 + +**Returns** + +| Type| Description | +| -- |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| int32_t | [USB_SERIAL_DDK_SUCCESS](capi-usb-serial-types-h.md#usbserial_ddkretcode): The operation is successful.
[USB_SERIAL_DDK_NO_PERM](capi-usb-serial-types-h.md#usbserial_ddkretcode): The permission verification fails.
[USB_SERIAL_DDK_INIT_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): The DDK initialization fails.| + +### OH_UsbSerial_Release() + +``` +int32_t OH_UsbSerial_Release(void) +``` + +**Description** + +Releases the USB Serial DDK. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB_SERIAL + +**Since**: 18 + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [USB_SERIAL_DDK_SUCCESS](capi-usb-serial-types-h.md#usbserial_ddkretcode): The operation is successful.
[USB_SERIAL_DDK_NO_PERM](capi-usb-serial-types-h.md#usbserial_ddkretcode): The permission verification fails.
[USB_SERIAL_DDK_INIT_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): The DDK initialization fails.
[USB_SERIAL_DDK_SERVICE_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): The DDK service communication fails.| + +### OH_UsbSerial_Open() + +``` +int32_t OH_UsbSerial_Open(uint64_t deviceId, uint8_t interfaceIndex, UsbSerial_DeviceHandle **dev) +``` + +**Description** + +Enables the USB serial port device based on the specified **deviceId** and **interfaceIndex**. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB_SERIAL + +**Since**: 18 + + +**Parameters** + +| Name | Description | +|----------------------------------|--------------------------------------------| +| uint64_t deviceId | Device ID. | +| uint8_t interfaceIndex | Interface index, which corresponds to [bInterfaceNumber](capi-usbddk-usbinterfacedescriptor.md) in the USB protocol.| +| [UsbSerial_DeviceHandle](capi-serialddk-usbserial-devicehandle.md) **dev | Device handle. | + +**Returns** + +| Type| Description | +| -- |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| int32_t | [USB_SERIAL_DDK_SUCCESS](capi-usb-serial-types-h.md#usbserial_ddkretcode): The operation is successful.
[USB_SERIAL_DDK_NO_PERM](capi-usb-serial-types-h.md#usbserial_ddkretcode): The permission verification fails.
[USB_SERIAL_DDK_INVALID_PARAMETER](capi-usb-serial-types-h.md#usbserial_ddkretcode): The parameter verification fails. Possible cause: The input **dev** is a null pointer.
[USB_SERIAL_DDK_INIT_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): The DDK initialization fails.
[USB_SERIAL_DDK_SERVICE_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): The DDK service communication fails.
[USB_SERIAL_DDK_MEMORY_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): The memory is insufficient.
[USB_SERIAL_DDK_IO_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): An I/O exception occurs.
[USB_SERIAL_DDK_DEVICE_NOT_FOUND](capi-usb-serial-types-h.md#usbserial_ddkretcode): The device or interface is not found.| + +### OH_UsbSerial_Close() + +``` +int32_t OH_UsbSerial_Close(UsbSerial_DeviceHandle *dev) +``` + +**Description** + +Disables the USB serial port device. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB_SERIAL + +**Since**: 18 + + +**Parameters** + +| Name| Description| +| -- | -- | +| [UsbSerial_DeviceHandle](capi-serialddk-usbserial-devicehandle.md) *dev | Device handle.| + +**Returns** + +| Type| Description | +| -- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| int32_t | [USB_SERIAL_DDK_SUCCESS](capi-usb-serial-types-h.md#usbserial_ddkretcode): The operation is successful.
[USB_SERIAL_DDK_NO_PERM](capi-usb-serial-types-h.md#usbserial_ddkretcode): The permission verification fails.
[USB_SERIAL_DDK_INVALID_PARAMETER](capi-usb-serial-types-h.md#usbserial_ddkretcode): The parameter verification fails. Possible cause: The input **dev** is a null pointer.
[USB_SERIAL_DDK_INIT_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): The DDK initialization fails.
[USB_SERIAL_DDK_SERVICE_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): The DDK service communication fails.
[USB_SERIAL_DDK_IO_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): An I/O exception occurs.
[USB_SERIAL_DDK_INVALID_OPERATION](capi-usb-serial-types-h.md#usbserial_ddkretcode): The operation is invalid.| + +### OH_UsbSerial_Read() + +``` +int32_t OH_UsbSerial_Read(UsbSerial_DeviceHandle *dev, uint8_t *buff, uint32_t bufferSize, uint32_t *bytesRead) +``` + +**Description** + +Reads data from the USB serial port device to the buffer. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB_SERIAL + +**Since**: 18 + + +**Parameters** + +| Name| Description| +| -- | -- | +| [UsbSerial_DeviceHandle](capi-serialddk-usbserial-devicehandle.md) *dev | Device handle.| +| uint8_t *buff | Buffer for storing the data read from the USB serial port device.| +| uint32_t bufferSize | Buffer size.| +| uint32_t *bytesRead | Number of bytes that are actually read. If the block mode is set, the number of bytes that are actually read is returned only when it is equal to the value of **bufferSize**.
For details, see [OH_UsbSerial_SetTimeout](capi-usb-serial-api-h.md#oh_usbserial_settimeout).| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [USB_SERIAL_DDK_SUCCESS](capi-usb-serial-types-h.md#usbserial_ddkretcode): The operation is successful.
[USB_SERIAL_DDK_NO_PERM](capi-usb-serial-types-h.md#usbserial_ddkretcode): The permission verification fails.
[USB_SERIAL_DDK_INVALID_PARAMETER](capi-usb-serial-types-h.md#usbserial_ddkretcode): The parameter verification fails. Possible causes: 1. **dev** is a null pointer.
2. **buff** is a null pointer. 3. **bufferSize** is **0**. 4. **bytesRead** is a null pointer.
[USB_SERIAL_DDK_INIT_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): The DDK initialization fails.
[USB_SERIAL_DDK_SERVICE_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): The DDK service communication fails.
[USB_SERIAL_DDK_MEMORY_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): The buffer address is invalid.
[USB_SERIAL_DDK_IO_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): An I/O exception occurs.
[USB_SERIAL_DDK_INVALID_OPERATION](capi-usb-serial-types-h.md#usbserial_ddkretcode): The operation is invalid.| + +### OH_UsbSerial_Write() + +``` +int32_t OH_UsbSerial_Write(UsbSerial_DeviceHandle *dev, uint8_t *buff, uint32_t bufferSize, uint32_t *bytesWritten) +``` + +**Description** + +Writes the data in the buffer to the USB serial port device. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB_SERIAL + +**Since**: 18 + + +**Parameters** + +| Name| Description| +| -- | -- | +| [UsbSerial_DeviceHandle](capi-serialddk-usbserial-devicehandle.md) *dev | Device handle.| +| uint8_t *buff | Buffer to which the data of the USB serial port device is written.| +| uint32_t bufferSize | Buffer size.| +| uint32_t *bytesWritten | Number of bytes that are actually written.| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [USB_SERIAL_DDK_SUCCESS](capi-usb-serial-types-h.md#usbserial_ddkretcode): The operation is successful.
[USB_SERIAL_DDK_NO_PERM](capi-usb-serial-types-h.md#usbserial_ddkretcode): The permission verification fails.
[USB_SERIAL_DDK_INVALID_PARAMETER](capi-usb-serial-types-h.md#usbserial_ddkretcode): The parameter verification fails. Possible causes: 1. **dev** is a null pointer.
2. **buff** is a null pointer. 3. **bufferSize** is **0**. 4. **bytesWritten** is a null pointer.
[USB_SERIAL_DDK_INIT_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): The DDK initialization fails.
[USB_SERIAL_DDK_SERVICE_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): The DDK service communication fails.
[USB_SERIAL_DDK_MEMORY_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): The buffer address is invalid.
[USB_SERIAL_DDK_IO_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): An I/O exception occurs.
[USB_SERIAL_DDK_INVALID_OPERATION](capi-usb-serial-types-h.md#usbserial_ddkretcode): The operation is invalid.| + +### OH_UsbSerial_SetBaudRate() + +``` +int32_t OH_UsbSerial_SetBaudRate(UsbSerial_DeviceHandle *dev, uint32_t baudRate) +``` + +**Description** + +Sets the baud rate for a USB serial port device. If the parameters of the USB serial port device are set to the default values (the data bit is **8**, the stop bit is **1**, and parity is disabled for data transfer), you only need to call this API to set the baud rate. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB_SERIAL + +**Since**: 18 + + +**Parameters** + +| Name| Description| +| -- | -- | +| [UsbSerial_DeviceHandle](capi-serialddk-usbserial-devicehandle.md) *dev | Device handle.| +| uint32_t baudRate | Baud rate of the USB serial port device.| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [USB_SERIAL_DDK_SUCCESS](capi-usb-serial-types-h.md#usbserial_ddkretcode): The operation is successful.
[USB_SERIAL_DDK_NO_PERM](capi-usb-serial-types-h.md#usbserial_ddkretcode): The permission verification fails.
[USB_SERIAL_DDK_INVALID_PARAMETER](capi-usb-serial-types-h.md#usbserial_ddkretcode): The parameter verification fails. Possible cause: The input **dev** is a null pointer.
[USB_SERIAL_DDK_INIT_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): The DDK initialization fails.
[USB_SERIAL_DDK_SERVICE_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): The DDK service communication fails.
[USB_SERIAL_DDK_IO_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): An I/O exception occurs.
[USB_SERIAL_DDK_INVALID_OPERATION](capi-usb-serial-types-h.md#usbserial_ddkretcode): The operation is invalid.| + +### OH_UsbSerial_SetParams() + +``` +int32_t OH_UsbSerial_SetParams(UsbSerial_DeviceHandle *dev, UsbSerial_Params *params) +``` + +**Description** + +Sets the parameters of the USB serial port device. If the parameters of the USB serial port device are not set to the default values (the data bit is **8**, the stop bit is **1**, and parity is disabled for data transfer), you only need to call this API to set the related parameters. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB_SERIAL + +**Since**: 18 + + +**Parameters** + +| Name | Description| +|-------------------------------------------------------------------------| -- | +| [UsbSerial_DeviceHandle](capi-serialddk-usbserial-devicehandle.md) *dev | Device handle.| +| [UsbSerial_Params](capi-serialddk-usbserial-params.md) *params | USB serial port device parameters. For details, see [UsbSerial_Params](capi-serialddk-usbserial-params.md).| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [USB_SERIAL_DDK_SUCCESS](capi-usb-serial-types-h.md#usbserial_ddkretcode): The operation is successful.
[USB_SERIAL_DDK_NO_PERM](capi-usb-serial-types-h.md#usbserial_ddkretcode): The permission verification fails.
[USB_SERIAL_DDK_INVALID_PARAMETER](capi-usb-serial-types-h.md#usbserial_ddkretcode): The parameter verification fails. Possible causes: 1. **dev** is a null pointer.
2. **params** is a null pointer.
[USB_SERIAL_DDK_INIT_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): The DDK initialization fails.
[USB_SERIAL_DDK_SERVICE_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): The DDK service communication fails.
[USB_SERIAL_DDK_IO_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): An I/O exception occurs.
[USB_SERIAL_DDK_INVALID_OPERATION](capi-usb-serial-types-h.md#usbserial_ddkretcode): The operation is invalid.| + +### OH_UsbSerial_SetTimeout() + +``` +int32_t OH_UsbSerial_SetTimeout(UsbSerial_DeviceHandle *dev, int timeout) +``` + +**Description** + +Sets the timeout interval (ms) for reading data reported by a USB serial port device. If this function is not called, the timeout value is **0** by default, indicating that data is returned immediately regardless of whether data is read. If you need to wait for a certain period of time or data must be read, call this API to set the timeout interval. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB_SERIAL + +**Since**: 18 + + +**Parameters** + +| Name| Description| +| -- | -- | +| [UsbSerial_DeviceHandle](capi-serialddk-usbserial-devicehandle.md) *dev | Device handle.| +| int timeout | Timeout interval for reading data from a USB serial port device, in milliseconds. The value range is - (0, 25500]. The value is rounded off to the nearest 100 milliseconds as the actual timeout interval. For example, if the value is set to **12321**, the effective timeout interval is **12300**. - **0**: Data is returned immediately. - **-1**: Data is read in block mode. That is, data is returned only after data of the specified length is read. For details, see [OH_UsbSerial_Read](capi-usb-serial-api-h.md#oh_usbserial_read).| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [USB_SERIAL_DDK_SUCCESS](capi-usb-serial-types-h.md#usbserial_ddkretcode): The operation is successful.
[USB_SERIAL_DDK_NO_PERM](capi-usb-serial-types-h.md#usbserial_ddkretcode): The permission verification fails.
[USB_SERIAL_DDK_INVALID_PARAMETER](capi-usb-serial-types-h.md#usbserial_ddkretcode): The parameter verification fails. Possible causes: 1. **dev** is a null pointer.
2. timeout < -1 or timeout > 25500.
[USB_SERIAL_DDK_INIT_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): The DDK initialization fails.
[USB_SERIAL_DDK_SERVICE_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): The DDK service communication fails.
[USB_SERIAL_DDK_IO_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): An I/O exception occurs.
[USB_SERIAL_DDK_INVALID_OPERATION](capi-usb-serial-types-h.md#usbserial_ddkretcode): The operation is invalid.| + +### OH_UsbSerial_SetFlowControl() + +``` +int32_t OH_UsbSerial_SetFlowControl(UsbSerial_DeviceHandle *dev, UsbSerial_FlowControl flowControl) +``` + +**Description** + +Sets flow control parameters. Flow control is used to manage the data transfer rate during communication with the USB serial port device to ensure that the sender does not send data that exceeds the processing capability of the receiver.
If flow control is required, call this API to set flow control parameters. If this API is not called, flow control is not performed by default. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB_SERIAL + +**Since**: 18 + + +**Parameters** + +| Name | Description| +|---------------------------------------------------------------------------------------| -- | +| [UsbSerial_DeviceHandle](capi-serialddk-usbserial-devicehandle.md) *dev | Device handle.| +| [UsbSerial_FlowControl](capi-usb-serial-types-h.md#usbserial_flowcontrol) flowControl | Flow control mode. For details, see [UsbSerial_FlowControl](capi-usb-serial-types-h.md#usbserial_flowcontrol).| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [USB_SERIAL_DDK_SUCCESS](capi-usb-serial-types-h.md#usbserial_ddkretcode): The operation is successful.
[USB_SERIAL_DDK_NO_PERM](capi-usb-serial-types-h.md#usbserial_ddkretcode): The permission verification fails.
[USB_SERIAL_DDK_INVALID_PARAMETER](capi-usb-serial-types-h.md#usbserial_ddkretcode): The parameter verification fails. Possible cause: The input **dev** is a null pointer.
[USB_SERIAL_DDK_INIT_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): The DDK initialization fails.
[USB_SERIAL_DDK_SERVICE_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): The DDK service communication fails.
[USB_SERIAL_DDK_IO_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): An I/O exception occurs.
[USB_SERIAL_DDK_INVALID_OPERATION](capi-usb-serial-types-h.md#usbserial_ddkretcode): The operation is invalid.| + +### OH_UsbSerial_Flush() + +``` +int32_t OH_UsbSerial_Flush(UsbSerial_DeviceHandle *dev) +``` + +**Description** + +Clears the input and output buffers after the write operation is complete. If a large amount of data is to be transmitted to the USB serial port device, the data may be buffered in the kernel for transmission. If the application closes the file descriptor or exits before the data is completely sent out, some data may be lost.
If the data is not sent out, some data may be lost. You can call this API to ensure that all data is sent before subsequent operations are performed. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB_SERIAL + +**Since**: 18 + + +**Parameters** + +| Name| Description| +| -- | -- | +| [UsbSerial_DeviceHandle](capi-serialddk-usbserial-devicehandle.md) *dev | Device handle.| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [USB_SERIAL_DDK_SUCCESS](capi-usb-serial-types-h.md#usbserial_ddkretcode): The operation is successful.
[USB_SERIAL_DDK_NO_PERM](capi-usb-serial-types-h.md#usbserial_ddkretcode): The permission verification fails.
[USB_SERIAL_DDK_INVALID_PARAMETER](capi-usb-serial-types-h.md#usbserial_ddkretcode): The parameter verification fails. Possible cause: The input **dev** is a null pointer.
[USB_SERIAL_DDK_INIT_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): The DDK initialization fails.
[USB_SERIAL_DDK_SERVICE_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): The DDK service communication fails.
[USB_SERIAL_DDK_IO_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): An I/O exception occurs.
[USB_SERIAL_DDK_INVALID_OPERATION](capi-usb-serial-types-h.md#usbserial_ddkretcode): The operation is invalid.| + +### OH_UsbSerial_FlushInput() + +``` +int32_t OH_UsbSerial_FlushInput(UsbSerial_DeviceHandle *dev) +``` + +**Description** + +Refreshes the input buffer. The data in the buffer is cleared immediately. During the communication with the USB serial port device, especially in the debugging phase, disordered data packets or other exceptions may occur.
You can call this API to clear these exceptions to restore the communication. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB_SERIAL + +**Since**: 18 + + +**Parameters** + +| Name| Description| +| -- | -- | +| [UsbSerial_DeviceHandle](capi-serialddk-usbserial-devicehandle.md) *dev | Device handle.| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [USB_SERIAL_DDK_SUCCESS](capi-usb-serial-types-h.md#usbserial_ddkretcode): The operation is successful.
[USB_SERIAL_DDK_NO_PERM](capi-usb-serial-types-h.md#usbserial_ddkretcode): The permission verification fails.
[USB_SERIAL_DDK_INVALID_PARAMETER](capi-usb-serial-types-h.md#usbserial_ddkretcode): The parameter verification fails. Possible cause: The input **dev** is a null pointer.
[USB_SERIAL_DDK_INIT_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): The DDK initialization fails.
[USB_SERIAL_DDK_SERVICE_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): The DDK service communication fails.
[USB_SERIAL_DDK_IO_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): An I/O exception occurs.
[USB_SERIAL_DDK_INVALID_OPERATION](capi-usb-serial-types-h.md#usbserial_ddkretcode): The operation is invalid.| + +### OH_UsbSerial_FlushOutput() + +``` +int32_t OH_UsbSerial_FlushOutput(UsbSerial_DeviceHandle *dev) +``` + +**Description** + +Refreshes the output buffer. The data in the buffer is cleared immediately. During the communication with the USB serial port device, especially in the debugging phase, disordered data packets or other exceptions may occur.
You can call this API to clear these exceptions to restore the communication. + +**Required permissions**: ohos.permission.ACCESS_DDK_USB_SERIAL + +**Since**: 18 + + +**Parameters** + +| Name| Description| +| -- | -- | +| [UsbSerial_DeviceHandle](capi-serialddk-usbserial-devicehandle.md) *dev | Device handle.| + +**Returns** + +| Type| Description| +| -- | -- | +| int32_t | [USB_SERIAL_DDK_SUCCESS](capi-usb-serial-types-h.md#usbserial_ddkretcode): The operation is successful.
[USB_SERIAL_DDK_NO_PERM](capi-usb-serial-types-h.md#usbserial_ddkretcode): The permission verification fails.
[USB_SERIAL_DDK_INVALID_PARAMETER](capi-usb-serial-types-h.md#usbserial_ddkretcode): The parameter verification fails. Possible cause: The input **dev** is a null pointer.
[USB_SERIAL_DDK_INIT_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): The DDK initialization fails.
[USB_SERIAL_DDK_SERVICE_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): The DDK service communication fails.
[USB_SERIAL_DDK_IO_ERROR](capi-usb-serial-types-h.md#usbserial_ddkretcode): An I/O exception occurs.
[USB_SERIAL_DDK_INVALID_OPERATION](capi-usb-serial-types-h.md#usbserial_ddkretcode): The operation is invalid.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-usb-serial-types-h.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usb-serial-types-h.md new file mode 100644 index 00000000000..cd2b3aaa359 --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usb-serial-types-h.md @@ -0,0 +1,94 @@ +# usb_serial_types.h + +## Overview + +Provides the enumerated variables, structures, and macros used in USB SERIAL DDK APIs. + +**File to include**: + +**Library**: libusb_serial.z.so + +**System capability**: SystemCapability.Driver.UsbSerial.Extension + +**Since**: 18 + +**Related module**: [SerialDdk](capi-serialddk.md) + +## Summary + +### Structs + +| Name| typedef Keyword| Description| +| -- | -- | -- | +| [UsbSerial_Params](capi-serialddk-usbserial-params.md) | __attribute__((aligned(8))) UsbSerial_Params | Defines the USB serial port parameters for the USB SERIAL DDK.| +| [UsbSerial_DeviceHandle](capi-serialddk-usbserial-devicehandle.md) | UsbSerial_DeviceHandle | Defines the data structures for the USB serial port device (opaque).| + +### Enums + +| Name| typedef Keyword| Description| +| -- | -- | -- | +| [UsbSerial_DdkRetCode](#usbserial_ddkretcode) | UsbSerial_DdkRetCode | Defines the return codes used by the USB SERIAL DDK.| +| [UsbSerial_FlowControl](#usbserial_flowcontrol) | UsbSerial_FlowControl | Defines the flow control mode for the USB SERIAL DDK.| +| [UsbSerial_Parity](#usbserial_parity) | UsbSerial_Parity | Defines the enums of the parity parameter used by the USB SERIAL DDK.| + +## Enum Description + +### UsbSerial_DdkRetCode + +``` +enum UsbSerial_DdkRetCode +``` + +**Description** + +Defines the return codes used by the USB SERIAL DDK. + +**Since**: 18 + +| Enum| Description| +| -- | -- | +| USB_SERIAL_DDK_NO_PERM = 201 | No access permission.| +| USB_SERIAL_DDK_INVALID_PARAMETER = 401 | Invalid parameter.| +| USB_SERIAL_DDK_SUCCESS = 31600000 | Operation success.| +| USB_SERIAL_DDK_INVALID_OPERATION = 31600001 | Invalid operation.| +| USB_SERIAL_DDK_INIT_ERROR = 31600002 | Initialization error.| +| USB_SERIAL_DDK_SERVICE_ERROR = 31600003 | Service error.| +| USB_SERIAL_DDK_MEMORY_ERROR = 31600004 | Memory-related errors, such as insufficient memory, memory data replication failure, or memory application fault.| +| USB_SERIAL_DDK_IO_ERROR = 31600005 | I/O error.| +| USB_SERIAL_DDK_DEVICE_NOT_FOUND = 31600006 | Device not found.| + +### UsbSerial_FlowControl + +``` +enum UsbSerial_FlowControl +``` + +**Description** + +Defines the flow control mode for the USB SERIAL DDK. + +**Since**: 18 + +| Enum| Description| +| -- | -- | +| USB_SERIAL_NO_FLOW_CONTROL = 0 | No flow control.| +| USB_SERIAL_SOFTWARE_FLOW_CONTROL = 1 | Software flow control.| +| USB_SERIAL_HARDWARE_FLOW_CONTROL = 2 | Hardware flow control.| + +### UsbSerial_Parity + +``` +enum UsbSerial_Parity +``` + +**Description** + +Defines the enums of the parity parameter used by the USB SERIAL DDK. + +**Since**: 18 + +| Enum| Description| +| -- | -- | +| USB_SERIAL_PARITY_NONE = 0 | No parity.| +| USB_SERIAL_PARITY_ODD = 1 | Odd parity.| +| USB_SERIAL_PARITY_EVEN = 2 | Even parity.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usb-devicearray.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usb-devicearray.md new file mode 100644 index 00000000000..be0cd3a6e0b --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usb-devicearray.md @@ -0,0 +1,20 @@ +# Usb_DeviceArray + +## Overview + +Defines the device ID list, which is used to store the device IDs and device quantity obtained using **OH_Usb_GetDevices**. + +**Since**: 16 + +**Related module**: [UsbDDK](capi-usbddk.md) + +**Header file:** [usb_ddk_types.h](capi-usb-ddk-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| uint64_t* deviceIds | Defines the start address of the device ID array. The number of device IDs cannot exceed 128.| +| uint32_t num | Defines the device quantity. Device IDs are obtained by traversing **deviceIds** based on the value of this parameter. If the value is **0**, there is no USB device.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbconfigdescriptor.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbconfigdescriptor.md new file mode 100644 index 00000000000..69fe4a7448f --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbconfigdescriptor.md @@ -0,0 +1,26 @@ +# UsbConfigDescriptor + +## Overview + +Defines standard configuration descriptors, which correspond to **Standard Configuration Descriptor** in the USB protocol. + +**Since**: 10 + +**Related module**: [UsbDDK](capi-usbddk.md) + +**Header file:** [usb_ddk_types.h](capi-usb-ddk-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| uint8_t bLength | Size of the descriptor, in bytes.| +| uint8_t bDescriptorType | Descriptor type.| +| uint16_t wTotalLength | Total length of the configuration descriptor, including the configuration, interface, endpoint, and class- or vendor-specific descriptors.| +| uint8_t bNumInterfaces | Number of interfaces supported by the configuration.| +| uint8_t bConfigurationValue | Configuration index, which is used to select the configuration.| +| uint8_t iConfiguration | Index of the string descriptor that describes the configuration.| +| uint8_t bmAttributes | Configuration attributes, including the power mode and remote wakeup.| +| uint8_t bMaxPower | Maximum power consumption of the bus-powered USB device, in 2 mA.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbcontrolrequestsetup.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbcontrolrequestsetup.md new file mode 100644 index 00000000000..403aa9ebcc3 --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbcontrolrequestsetup.md @@ -0,0 +1,23 @@ +# UsbControlRequestSetup + +## Overview + +Setup data for control transfer. It corresponds to Setup Data in the USB protocol. + +**Since**: 10 + +**Related module**: [UsbDDK](capi-usbddk.md) + +**Header file:** [usb_ddk_types.h](capi-usb-ddk-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| uint8_t bmRequestType | Request type.| +| uint8_t bRequest | Specific request.| +| uint16_t wValue | Value corresponding to **wValue** in the USB protocol. Its meaning varies according to the request.| +| uint16_t wIndex | Index corresponding to **wIndex** in the USB protocol. It is usually used to pass the index or offset. Its meaning varies according to the request. | +| uint16_t wLength | Data length corresponding to **wLength** in the USB protocol. If data is transferred, this field indicates the number of transferred bytes.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbddkconfigdescriptor.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbddkconfigdescriptor.md new file mode 100644 index 00000000000..99c73eee9f0 --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbddkconfigdescriptor.md @@ -0,0 +1,22 @@ +# UsbDdkConfigDescriptor + +## Overview + +Defines configuration descriptors. + +**Since**: 10 + +**Related module**: [UsbDDK](capi-usbddk.md) + +**Header file:** [usb_ddk_types.h](capi-usb-ddk-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| struct UsbConfigDescriptor configDescriptor | Standard configuration descriptor.| +| struct UsbDdkInterface* interface | Interfaces contained in the configuration.| +| uint8_t* extra | Unresolved descriptor, including class- or vendor-specific descriptors.| +| uint32_t extraLength | Length of the unresolved descriptor.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbddkendpointdescriptor.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbddkendpointdescriptor.md new file mode 100644 index 00000000000..fbaa6abd0ce --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbddkendpointdescriptor.md @@ -0,0 +1,21 @@ +# UsbDdkEndpointDescriptor + +## Overview + +Defines endpoint descriptors. + +**Since**: 10 + +**Related module**: [UsbDDK](capi-usbddk.md) + +**Header file:** [usb_ddk_types.h](capi-usb-ddk-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| struct UsbEndpointDescriptor endpointDescriptor | Standard endpoint descriptor.| +| uint8_t* extra | Unresolved descriptor, including class- or vendor-specific descriptors.| +| uint32_t extraLength | Length of the unresolved descriptor.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbddkinterface.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbddkinterface.md new file mode 100644 index 00000000000..398a57f73c8 --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbddkinterface.md @@ -0,0 +1,20 @@ +# UsbDdkInterface + +## Overview + +Defines a USB DDK API, which is a collection of alternate settings for a particular USB interface. + +**Since**: 10 + +**Related module**: [UsbDDK](capi-usbddk.md) + +**Header file:** [usb_ddk_types.h](capi-usb-ddk-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| uint8_t numAltsetting | Number of alternate settings of the USB interface.| +| struct UsbDdkInterfaceDescriptor* altsetting | Alternate setting of the USB interface.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbddkinterfacedescriptor.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbddkinterfacedescriptor.md new file mode 100644 index 00000000000..8b7eb88d5ac --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbddkinterfacedescriptor.md @@ -0,0 +1,22 @@ +# UsbDdkInterfaceDescriptor + +## Overview + +Defines USB interface descriptors. + +**Since**: 10 + +**Related module**: [UsbDDK](capi-usbddk.md) + +**Header file:** [usb_ddk_types.h](capi-usb-ddk-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| struct UsbInterfaceDescriptor interfaceDescriptor | Standard USB interface descriptor.| +| struct UsbDdkEndpointDescriptor* endPoint | Endpoint descriptor contained in the interface.| +| uint8_t* extra | Unresolved descriptor, including class- or vendor-specific descriptors.| +| uint32_t extraLength | Length of the unresolved descriptor.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbdevicedescriptor.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbdevicedescriptor.md new file mode 100644 index 00000000000..80d9379a706 --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbdevicedescriptor.md @@ -0,0 +1,32 @@ +# UsbDeviceDescriptor + +## Overview + +Defines standard device descriptors, which correspond to **Standard Device Descriptor** in the USB protocol. + +**Since**: 10 + +**Related module**: [UsbDDK](capi-usbddk.md) + +**Header file:** [usb_ddk_types.h](capi-usb-ddk-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| uint8_t bLength | Size of the descriptor, in bytes.| +| uint8_t bDescriptorType | Descriptor type.| +| uint16_t bcdUSB | USB protocol release number.| +| uint8_t bDeviceClass | Interface class code allocated by the USB-IF.| +| uint8_t bDeviceSubClass | Device subclass code allocated by USB-IF. The value is limited by that of {@link bDeviceClass}.| +| uint8_t bDeviceProtocol | Protocol code allocated by USB-IF. The value is limited by that of {@link bDeviceClass} and {@link bDeviceSubClass}.| +| uint8_t bMaxPacketSize0 | Maximum packet size of endpoint 0. Only values 8, 16, 32, and 64 are valid.| +| uint16_t idVendor | Vendor ID allocated by USB-IF.| +| uint16_t idProduct | Product ID allocated by the vendor.| +| uint16_t bcdDevice | Device SN.| +| uint8_t iManufacturer | Index of the string descriptor that describes the vendor.| +| uint8_t iProduct | Index of the string descriptor that describes the product.| +| uint8_t iSerialNumber | Index of the string descriptor that describes the device SN.| +| uint8_t bNumConfigurations | Configuration quantity.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbdevicememmap.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbdevicememmap.md new file mode 100644 index 00000000000..537b75d169e --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbdevicememmap.md @@ -0,0 +1,23 @@ +# UsbDeviceMemMap + +## Overview + +Device memory map created by calling OH_Usb_CreateDeviceMemMap. A buffer using the device memory map can provide better performance. + +**Since**: 10 + +**Related module**: [UsbDDK](capi-usbddk.md) + +**Header file:** [usb_ddk_types.h](capi-usb-ddk-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| uint8_t* const address | Buffer address.| +| const size_t size | Pointer to the buffer size.| +| uint32_t offset | Offset of the used buffer. The default value is **0**, indicating that there is no offset and the buffer starts from the specified {@link address}.| +| uint32_t bufferLength | Length of the used buffer. By default, the value is equal to the {@link size}, indicating that the entire buffer is used.| +| uint32_t transferedLength | Length of the transferred data.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbendpointdescriptor.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbendpointdescriptor.md new file mode 100644 index 00000000000..222f4373c90 --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbendpointdescriptor.md @@ -0,0 +1,26 @@ +# UsbEndpointDescriptor + +## Overview + +Defines standard endpoint descriptors, which correspond to **Standard Endpoint Descriptor** in the USB protocol. + +**Since**: 10 + +**Related module**: [UsbDDK](capi-usbddk.md) + +**Header file:** [usb_ddk_types.h](capi-usb-ddk-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| uint8_t bLength | Size of the descriptor, in bytes.| +| uint8_t bDescriptorType | Descriptor type.| +| uint8_t bEndpointAddress | Endpoint address, including the endpoint number and endpoint direction.| +| uint8_t bmAttributes | Endpoint attributes, including the transfer type, synchronization type, and usage type.| +| uint16_t wMaxPacketSize | Maximum packet size supported by an endpoint.| +| uint8_t bInterval | Interval for polling endpoints for data transfer.| +| uint8_t bRefresh | Refresh rate for audio devices.| +| uint8_t bSynchAddress | Endpoint synchronization address for audio devices.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbinterfacedescriptor.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbinterfacedescriptor.md new file mode 100644 index 00000000000..db0a64765c4 --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbinterfacedescriptor.md @@ -0,0 +1,27 @@ +# UsbInterfaceDescriptor + +## Overview + +Defines standard interface descriptors, which correspond to **Standard Interface Descriptor** in the USB protocol. + +**Since**: 10 + +**Related module**: [UsbDDK](capi-usbddk.md) + +**Header file:** [usb_ddk_types.h](capi-usb-ddk-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| uint8_t bLength | Size of the descriptor, in bytes.| +| uint8_t bDescriptorType | Descriptor type.| +| uint8_t bInterfaceNumber | Interface ID.| +| uint8_t bAlternateSetting | Value used to select the alternate setting of the interface.| +| uint8_t bNumEndpoints | Number of endpoints (excluding endpoint 0) used by the interface.| +| uint8_t bInterfaceClass | Interface class code allocated by the USB-IF.| +| uint8_t bInterfaceSubClass | Device subclass code allocated by USB-IF. The value is limited by that of {@link bInterfaceClass}.| +| uint8_t bInterfaceProtocol | Protocol code allocated by USB-IF. The value is limited by that of {@link bInterfaceClass} and {@link bInterfaceSubClass}.| +| uint8_t iInterface | Index of the string descriptor that describes the interface.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbrequestpipe.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbrequestpipe.md new file mode 100644 index 00000000000..6589409bfa9 --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk-usbrequestpipe.md @@ -0,0 +1,21 @@ +# UsbRequestPipe + +## Overview + +Defines a USB request pipe. + +**Since**: 10 + +**Related module**: [UsbDDK](capi-usbddk.md) + +**Header file:** [usb_ddk_types.h](capi-usb-ddk-types-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| uint64_t interfaceHandle | Interface operation handle.| +| uint8_t endpoint | Endpoint address.| +| uint32_t timeout | Timeout duration, in milliseconds.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk.md b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk.md new file mode 100644 index 00000000000..29884756096 --- /dev/null +++ b/en/application-dev/reference/apis-driverdevelopment-kit/capi-usbddk.md @@ -0,0 +1,15 @@ +# UsbDDK + +## Overview + +Provides USB DDK APIs to open and close USB interfaces, perform non-isochronous and isochronous data transfer over USB pipes, and implement control transfer and interrupt transfer, etc. + +**System capability**: SystemCapability.Driver.USB.Extension + +**Since**: 10 +## Files + +| Name| Description| +| -- | -- | +| [usb_ddk_api.h](capi-usb-ddk-api-h.md) | Declares the USB DDK APIs used by the USB host to access USB devices.| +| [usb_ddk_types.h](capi-usb-ddk-types-h.md) | Provides the enumerated variables, structures, and macros used in USB DDK APIs.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/ddk_api.md b/en/application-dev/reference/apis-driverdevelopment-kit/ddk_api.md deleted file mode 100644 index 2cec82b988a..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/ddk_api.md +++ /dev/null @@ -1,25 +0,0 @@ -# ddk_api.h - - -## Overview - -Declares the BASE DDK APIs used by the host to access the device. - -**System capability**: SystemCapability.Driver.DDK.Extension - -**Since**: 12 - -**Related module**: [Base DDK](_base_ddk.md) - - -## Summary - - -### Functions - -| Name| Description| -| -------- | -------- | -| [OH_DDK_CreateAshmem](_base_ddk.md#oh_ddk_createashmem) (const uint8_t *name, [DDK_Ashmem](_ddk_ashmem.md) \*\*ashmem) | Creates an **Ashmem** object. | -| [OH_DDK_MapAshmem](_base_ddk.md#oh_ddk_mapashmem) ([DDK_Ashmem](_ddk_ashmem.md) \*ashmem), const uint8_t ashmemMapType| Maps an **Ashmem** object. | -| [OH_DDK_UnmapAshmem](_base_ddk.md#oh_ddk_unmapashmem) ([DDK_Ashmem](_ddk_ashmem.md) \*ashmem) | Unmaps an **Ashmem** object. | -| [OH_DDK_DestroyAshmem](_base_ddk.md#oh_ddk_destroyashmem) ([DDK_Ashmem](_ddk_ashmem.md) \*ashmem) | Destroys an **Ashmem** object. | diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/ddk_types.md b/en/application-dev/reference/apis-driverdevelopment-kit/ddk_types.md deleted file mode 100644 index c9cb42c87fe..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/ddk_types.md +++ /dev/null @@ -1,52 +0,0 @@ -# ddk_types.h - - -## Overview - -Defines the enum variables and structs used in the Base DDK. - -**System capability**: SystemCapability.Driver.DDK.Extension - -**Since**: 12 - -**Related module**: [Base DDK](_base_ddk.md) - - -## Summary - - -### Structs - -| Name| Description| -| -------- | -------- | -| [DDK_Ashmem](_ddk_ashmem.md) | **Ashmem** object. | - - -### Enums - -| Name| Description| -| -------- | -------- | -| [DDK_RetCode](#ddk_retcode)  {
DDK_SUCCESS = 0,
DDK_FAILED = 28600001,
DDK_INVALID_PARAMETER = 28600002,
DDK_INVALID_OPERATION = 28600003,
DDK_NULL_PTR = 28600004
} | Base DDK error code definitions. | - - -## Enum Description - - -### DDK_RetCode - - -``` -enum DDK_RetCode -``` - -**Description** - -Base DDK error code definitions. - -| Value| Description| -| -------- | -------- | -| DDK_SUCCESS | Operation succeeded.| -| DDK_FAILED | Operation failed.| -| DDK_INVALID_PARAMETER | Invalid parameter.| -| DDK_INVALID_OPERATION | Invalid operation.| -| DDK_NULL_PTR | Null pointer.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/hid__ddk__api_8h.md b/en/application-dev/reference/apis-driverdevelopment-kit/hid__ddk__api_8h.md deleted file mode 100644 index 380d0aa9722..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/hid__ddk__api_8h.md +++ /dev/null @@ -1,24 +0,0 @@ -# hid_ddk_api.h - - -## Overview - -Declares the HID DDK functions for accessing an input device from the host. - -File to include: <hid/hid_ddk_api.h> - -**Since**: 11 - -**Related module**: [HID DDK](_hid_ddk.md) - - -## Summary - - -### Functions - -| Name| Description| -| -------- | -------- | -| [OH_Hid_CreateDevice](_hid_ddk.md#oh_hid_createdevice) ([Hid_Device](_hid___device.md) \*hidDevice, [Hid_EventProperties](_hid___event_properties.md) \*hidEventProperties) | Creates a device. | -| [OH_Hid_EmitEvent](_hid_ddk.md#oh_hid_emitevent) (int32_t deviceId, const [Hid_EmitItem](_hid___emit_item.md) items[], uint16_t length) | Sends an event list to a device. | -| [OH_Hid_DestroyDevice](_hid_ddk.md#oh_hid_destroydevice) (int32_t deviceId) | Destroys a device. | diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/hid__ddk__types_8h.md b/en/application-dev/reference/apis-driverdevelopment-kit/hid__ddk__types_8h.md deleted file mode 100644 index 3be8ba96c73..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/hid__ddk__types_8h.md +++ /dev/null @@ -1,57 +0,0 @@ -# hid_ddk_types.h - - -## Overview - -Defines the enums and structs used in the HID DDK. - -File to include: <hid/hid_ddk_types.h> - -**Since**: 11 - -**Related module**: [HidDdk](_hid_ddk.md) - - -## Summary - - -### Structs - -| Name| Description| -| -------- | -------- | -| [Hid_EmitItem](_hid___emit_item.md) | Defines event information. | -| [Hid_Device](_hid___device.md) | Defines basic device information. | -| [Hid_EventTypeArray](_hid___event_type_array.md) | Defines an array of event types. | -| [Hid_KeyCodeArray](_hid___key_code_array.md) | Defines an array of key codes. | -| [Hid_AbsAxesArray](_hid___abs_axes_array.md) | Defines an array of absolute coordinates. | -| [Hid_RelAxesArray](_hid___rel_axes_array.md) | Defines an array of relative coordinates. | -| [Hid_MscEventArray](_hid___msc_event_array.md) | Defines an array of miscellaneous events. | -| [Hid_EventProperties](_hid___event_properties.md) | Defines the event properties of a device. | - - -### Types - -| Name| Description| -| -------- | -------- | -| [Hid_EmitItem](_hid_ddk.md#hid_emititem) | Defines a struct for event information. | -| [Hid_Device](_hid_ddk.md#hid_device) | Defines a struct for basic device information. | -| [Hid_EventTypeArray](_hid_ddk.md#hid_eventtypearray) | Defines a struct for an array of event types. | -| [Hid_KeyCodeArray](_hid_ddk.md#hid_keycodearray) | Defines a struct for an array of key codes. | -| [Hid_AbsAxesArray](_hid_ddk.md#hid_absaxesarray) | Defines a struct for an array of absolute coordinates. | -| [Hid_RelAxesArray](_hid_ddk.md#hid_relaxesarray) | Defines a struct for an array of relative coordinates. | -| [Hid_MscEventArray](_hid_ddk.md#hid_msceventarray) | Defines a struct for an array of miscellaneous events. | -| [Hid_EventProperties](_hid_ddk.md#hid_eventproperties) | Defines a struct for the event properties of a device. | - - -### Enums - -| Name| Description| -| -------- | -------- | -| [Hid_DeviceProp](_hid_ddk.md#hid_deviceprop) {
[HID_PROP_POINTER](_hid_ddk.md) = 0x00, [HID_PROP_DIRECT](_hid_ddk.md) = 0x01, [HID_PROP_BUTTON_PAD](_hid_ddk.md) = 0x02, [HID_PROP_SEMI_MT](_hid_ddk.md) = 0x03,
[HID_PROP_TOP_BUTTON_PAD](_hid_ddk.md) = 0x04, [HID_PROP_POINTING_STICK](_hid_ddk.md) = 0x05, [HID_PROP_ACCELEROMETER](_hid_ddk.md) = 0x06
} | Enumerates the properties of input devices. | -| [Hid_EventType](_hid_ddk.md#hid_eventtype) {
[HID_EV_SYN](_hid_ddk.md) = 0x00, [HID_EV_KEY](_hid_ddk.md) = 0x01, [HID_EV_REL](_hid_ddk.md) = 0x02, [HID_EV_ABS](_hid_ddk.md) = 0x03,
[HID_EV_MSC](_hid_ddk.md) = 0x04
} | Enumerates the event types. | -| [Hid_SynEvent](_hid_ddk.md#hid_synevent) { [HID_SYN_REPORT](_hid_ddk.md) = 0, [HID_SYN_CONFIG](_hid_ddk.md) = 1, [HID_SYN_MT_REPORT](_hid_ddk.md) = 2, [HID_SYN_DROPPED](_hid_ddk.md) = 3 } | Enumerates sync events. | -| [Hid_KeyCode](_hid_ddk.md#hid_keycode) {
[HID_KEY_A](_hid_ddk.md) = 30, [HID_KEY_B](_hid_ddk.md) = 48, [HID_KEY_C](_hid_ddk.md) = 46, [HID_KEY_D](_hid_ddk.md) = 32,
[HID_KEY_E](_hid_ddk.md) = 18, [HID_KEY_F](_hid_ddk.md) = 33, [HID_KEY_G](_hid_ddk.md) = 34, [HID_KEY_H](_hid_ddk.md) = 35,
[HID_KEY_I](_hid_ddk.md) = 23, [HID_KEY_J](_hid_ddk.md) = 36, [HID_KEY_K](_hid_ddk.md) = 37, [HID_KEY_L](_hid_ddk.md) = 38,
[HID_KEY_M](_hid_ddk.md) = 50, [HID_KEY_N](_hid_ddk.md) = 49, [HID_KEY_O](_hid_ddk.md) = 24, [HID_KEY_P](_hid_ddk.md) = 25,
[HID_KEY_Q](_hid_ddk.md) = 16, [HID_KEY_R](_hid_ddk.md) = 19, [HID_KEY_S](_hid_ddk.md) = 31, [HID_KEY_T](_hid_ddk.md) = 20,
[HID_KEY_U](_hid_ddk.md) = 22, [HID_KEY_V](_hid_ddk.md) = 47, [HID_KEY_W](_hid_ddk.md) = 17, [HID_KEY_X](_hid_ddk.md) = 45,
[HID_KEY_Y](_hid_ddk.md) = 21, [HID_KEY_Z](_hid_ddk.md) = 44, [HID_KEY_ESC](_hid_ddk.md) = 1, [HID_KEY_0](_hid_ddk.md) = 11,
[HID_KEY_1](_hid_ddk.md) = 2, [HID_KEY_2](_hid_ddk.md) = 3, [HID_KEY_3](_hid_ddk.md) = 4, [HID_KEY_4](_hid_ddk.md) = 5,
[HID_KEY_5](_hid_ddk.md) = 6, [HID_KEY_6](_hid_ddk.md) = 7, [HID_KEY_7](_hid_ddk.md) = 8, [HID_KEY_8](_hid_ddk.md) = 9,
[HID_KEY_9](_hid_ddk.md) = 10, [HID_KEY_GRAVE](_hid_ddk.md) = 41, [HID_KEY_MINUS](_hid_ddk.md) = 12, [HID_KEY_EQUALS](_hid_ddk.md) = 13,
[HID_KEY_BACKSPACE](_hid_ddk.md) = 14, [HID_KEY_LEFT_BRACKET](_hid_ddk.md) = 26, [HID_KEY_RIGHT_BRACKET](_hid_ddk.md) = 27, [HID_KEY_ENTER](_hid_ddk.md) = 28,
[HID_KEY_LEFT_SHIFT](_hid_ddk.md) = 42, [HID_KEY_BACKSLASH](_hid_ddk.md) = 43, [HID_KEY_SEMICOLON](_hid_ddk.md) = 39, [HID_KEY_APOSTROPHE](_hid_ddk.md) = 40,
[HID_KEY_SPACE](_hid_ddk.md) = 57, [HID_KEY_SLASH](_hid_ddk.md) = 53, [HID_KEY_COMMA](_hid_ddk.md) = 51, [HID_KEY_PERIOD](_hid_ddk.md) = 52,
[HID_KEY_RIGHT_SHIFT](_hid_ddk.md) = 54, [HID_KEY_NUMPAD_0](_hid_ddk.md) = 82, [HID_KEY_NUMPAD_1](_hid_ddk.md) = 79, [HID_KEY_NUMPAD_2](_hid_ddk.md) = 80,
[HID_KEY_NUMPAD_3](_hid_ddk.md) = 81, [HID_KEY_NUMPAD_4](_hid_ddk.md) = 75, [HID_KEY_NUMPAD_5](_hid_ddk.md) = 76, [HID_KEY_NUMPAD_6](_hid_ddk.md) = 77,
[HID_KEY_NUMPAD_7](_hid_ddk.md) = 71, [HID_KEY_NUMPAD_8](_hid_ddk.md) = 72, [HID_KEY_NUMPAD_9](_hid_ddk.md) = 73, [HID_KEY_NUMPAD_DIVIDE](_hid_ddk.md) = 70,
[HID_KEY_NUMPAD_MULTIPLY](_hid_ddk.md) = 55, [HID_KEY_NUMPAD_SUBTRACT](_hid_ddk.md) = 74, [HID_KEY_NUMPAD_ADD](_hid_ddk.md) = 78, [HID_KEY_NUMPAD_DOT](_hid_ddk.md) = 83,
[HID_KEY_SYSRQ](_hid_ddk.md) = 99, [HID_KEY_MUTE](_hid_ddk.md) = 113, [HID_KEY_VOLUME_DOWN](_hid_ddk.md) = 114, [HID_KEY_VOLUME_UP](_hid_ddk.md) = 115,
[HID_KEY_BRIGHTNESS_DOWN](_hid_ddk.md) = 224, [HID_KEY_BRIGHTNESS_UP](_hid_ddk.md) = 225, [HID_BTN_0](_hid_ddk.md) = 0x100, [HID_BTN_1](_hid_ddk.md) = 0x101,
[HID_BTN_2](_hid_ddk.md) = 0x102, [HID_BTN_3](_hid_ddk.md) = 0x103, [HID_BTN_4](_hid_ddk.md) = 0x104, [HID_BTN_5](_hid_ddk.md) = 0x105,
[HID_BTN_6](_hid_ddk.md) = 0x106, [HID_BTN_7](_hid_ddk.md) = 0x107, [HID_BTN_8](_hid_ddk.md) = 0x108, [HID_BTN_9](_hid_ddk.md) = 0x109,
[HID_BTN_LEFT](_hid_ddk.md) = 0x110, [HID_BTN_RIGHT](_hid_ddk.md) = 0x111, [HID_BTN_MIDDLE](_hid_ddk.md) = 0x112, [HID_BTN_SIDE](_hid_ddk.md) = 0x113,
[HID_BTN_EXTRA](_hid_ddk.md) = 0x114, [HID_BTN_FORWARD](_hid_ddk.md) = 0x115, [HID_BTN_BACKWARD](_hid_ddk.md) = 0x116, [HID_BTN_TASK](_hid_ddk.md) = 0x117,
[HID_BTN_TOOL_PEN](_hid_ddk.md) = 0x140, [HID_BTN_TOOL_RUBBER](_hid_ddk.md) = 0x141, [HID_BTN_TOOL_BRUSH](_hid_ddk.md) = 0x142, [HID_BTN_TOOL_PENCIL](_hid_ddk.md) = 0x143,
[HID_BTN_TOOL_AIRBRUSH](_hid_ddk.md) = 0x144, [HID_BTN_TOOL_FINGER](_hid_ddk.md) = 0x145, [HID_BTN_TOOL_MOUSE](_hid_ddk.md) = 0x146, [HID_BTN_TOOL_LENS](_hid_ddk.md) = 0x147,
[HID_BTN_TOOL_QUINT_TAP](_hid_ddk.md) = 0x148, [HID_BTN_STYLUS3](_hid_ddk.md) = 0x149, [HID_BTN_TOUCH](_hid_ddk.md) = 0x14a, [HID_BTN_STYLUS](_hid_ddk.md) = 0x14b,
[HID_BTN_STYLUS2](_hid_ddk.md) = 0x14c, [HID_BTN_TOOL_DOUBLE_TAP](_hid_ddk.md) = 0x14d, [HID_BTN_TOOL_TRIPLE_TAP](_hid_ddk.md) = 0x14e, [HID_BTN_TOOL_QUAD_TAP](_hid_ddk.md) = 0x14f,
[HID_BTN_WHEEL](_hid_ddk.md) = 0x150
} | Enumerates the key codes. | -| [Hid_AbsAxes](_hid_ddk.md#hid_absaxes) {
[HID_ABS_X](_hid_ddk.md) = 0x00, [HID_ABS_Y](_hid_ddk.md) = 0x01, [HID_ABS_Z](_hid_ddk.md) = 0x02, [HID_ABS_RX](_hid_ddk.md) = 0x03,
[HID_ABS_RY](_hid_ddk.md) = 0x04, [HID_ABS_RZ](_hid_ddk.md) = 0x05, [HID_ABS_THROTTLE](_hid_ddk.md) = 0x06, [HID_ABS_RUDDER](_hid_ddk.md) = 0x07,
[HID_ABS_WHEEL](_hid_ddk.md) = 0x08, [HID_ABS_GAS](_hid_ddk.md) = 0x09, [HID_ABS_BRAKE](_hid_ddk.md) = 0x0a, [HID_ABS_HAT0X](_hid_ddk.md) = 0x10,
[HID_ABS_HAT0Y](_hid_ddk.md) = 0x11, [HID_ABS_HAT1X](_hid_ddk.md) = 0x12, [HID_ABS_HAT1Y](_hid_ddk.md) = 0x13, [HID_ABS_HAT2X](_hid_ddk.md) = 0x14,
[HID_ABS_HAT2Y](_hid_ddk.md) = 0x15, [HID_ABS_HAT3X](_hid_ddk.md) = 0x16, [HID_ABS_HAT3Y](_hid_ddk.md) = 0x17, [HID_ABS_PRESSURE](_hid_ddk.md) = 0x18,
[HID_ABS_DISTANCE](_hid_ddk.md) = 0x19, [HID_ABS_TILT_X](_hid_ddk.md) = 0x1a, [HID_ABS_TILT_Y](_hid_ddk.md) = 0x1b, [HID_ABS_TOOL_WIDTH](_hid_ddk.md) = 0x1c,
[HID_ABS_VOLUME](_hid_ddk.md) = 0x20, [HID_ABS_MISC](_hid_ddk.md) = 0x28
} | Enumerates the absolute coordinates. | -| [Hid_RelAxes](_hid_ddk.md#hid_relaxes) {
[HID_REL_X](_hid_ddk.md) = 0x00, [HID_REL_Y](_hid_ddk.md) = 0x01, [HID_REL_Z](_hid_ddk.md) = 0x02, [HID_REL_RX](_hid_ddk.md) = 0x03,
[HID_REL_RY](_hid_ddk.md) = 0x04, [HID_REL_RZ](_hid_ddk.md) = 0x05, [HID_REL_HWHEEL](_hid_ddk.md) = 0x06, [HID_REL_DIAL](_hid_ddk.md) = 0x07,
[HID_REL_WHEEL](_hid_ddk.md) = 0x08, [HID_REL_MISC](_hid_ddk.md) = 0x09, [HID_REL_RESERVED](_hid_ddk.md) = 0x0a, [HID_REL_WHEEL_HI_RES](_hid_ddk.md) = 0x0b,
[HID_REL_HWHEEL_HI_RES](_hid_ddk.md) = 0x0c
} | Enumerates the relative coordinates. | -| [Hid_MscEvent](_hid_ddk.md#hid_mscevent) {
[HID_MSC_SERIAL](_hid_ddk.md) = 0x00, [HID_MSC_PULSE_LED](_hid_ddk.md) = 0x01, [HID_MSC_GESTURE](_hid_ddk.md) = 0x02, [HID_MSC_RAW](_hid_ddk.md) = 0x03,
[HID_MSC_SCAN](_hid_ddk.md) = 0x04, [HID_MSC_TIMESTAMP](_hid_ddk.md) = 0x05
} | Enumerates miscellaneous input events. | -| [Hid_DdkErrCode](_hid_ddk.md#hid_ddkerrcode) {
[HID_DDK_SUCCESS](_hid_ddk.md) = 0, [HID_DDK_FAILURE](_hid_ddk.md) = -1, [HID_DDK_INVALID_PARAMETER](_hid_ddk.md) = -2, [HID_DDK_INVALID_OPERATION](_hid_ddk.md) = -3,
[HID_DDK_NULL_PTR](_hid_ddk.md) = -4, [HID_DDK_TIMEOUT](_hid_ddk.md) = -5, [HID_DDK_NO_PERM](_hid_ddk.md) = -6
} | Enumerates the HID DDK error codes. | diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/scsi__peripheral__api_8h.md b/en/application-dev/reference/apis-driverdevelopment-kit/scsi__peripheral__api_8h.md deleted file mode 100644 index 6c3af4acfda..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/scsi__peripheral__api_8h.md +++ /dev/null @@ -1,40 +0,0 @@ -# scsi_peripheral_api.h - - -## Overview - -Declares the SCSI Peripheral DDK APIs used by the host to access the SCSI device. - -**File to include**: <scsi_peripheral/scsi_peripheral_api.h> - -**Library**: libscsi.z.so - -**System capability**: SystemCapability.Driver.SCSI.Extension - -**Since**: 18 - -**Related module**: [SCSI Peripheral DDK](_s_c_s_i.md) - - -## Summary - - -### Function - -| Name| Description| -| -------- | -------- | -| int32_t [OH_ScsiPeripheral_Init](_s_c_s_i.md#oh_scsiperipheral_init) (void) | Initializes the SCSI Peripheral DDK.| -| int32_t [OH_ScsiPeripheral_Release](_s_c_s_i.md#oh_scsiperipheral_release) (void) | Releases the SCSI Peripheral DDK.| -| int32_t [OH_ScsiPeripheral_Open](_s_c_s_i.md#oh_scsiperipheral_open) (uint64_t deviceId, uint8_t interfaceIndex, [ScsiPeripheral_Device](_s_c_s_i.md#scsiperipheral_device) \*\*dev) | Opens the SCSI device specified by **deviceId** and **interfaceIndex**.| -| int32_t [OH_ScsiPeripheral_Close](_s_c_s_i.md#oh_scsiperipheral_close) ([ScsiPeripheral_Device](_s_c_s_i.md#scsiperipheral_device) \*\*dev) | Disables the SCSI device.| -| int32_t [OH_ScsiPeripheral_TestUnitReady](_s_c_s_i.md#oh_scsiperipheral_testunitready) ([ScsiPeripheral_Device](_s_c_s_i.md#scsiperipheral_device) \*dev, [ScsiPeripheral_TestUnitReadyRequest](_scsi_peripheral___test_unit_ready_request.md) \*request, [ScsiPeripheral_Response](_scsi_peripheral___response.md) \*response) | Checks whether the logical units are ready.| -| int32_t [OH_ScsiPeripheral_Inquiry](_s_c_s_i.md#oh_scsiperipheral_inquiry) ([ScsiPeripheral_Device](_s_c_s_i.md#scsiperipheral_device) \*dev, [ScsiPeripheral_InquiryRequest](_scsi_peripheral___inquiry_request.md) \*request, [ScsiPeripheral_InquiryInfo](_scsi_peripheral___inquiry_info.md) \*inquiryInfo, [ScsiPeripheral_Response](_scsi_peripheral___response.md) \*response) | Queries basic information about the SCSI device.| -| int32_t [OH_ScsiPeripheral_ReadCapacity10](_s_c_s_i.md#oh_scsiperipheral_readcapacity10) ([ScsiPeripheral_Device](_s_c_s_i.md#scsiperipheral_device) \*dev, [ScsiPeripheral_ReadCapacityRequest](_scsi_peripheral___read_capacity_request.md) \*request, [ScsiPeripheral_CapacityInfo](_scsi_peripheral___capacity_info.md) \*capacityInfo, [ScsiPeripheral_Response](_scsi_peripheral___response.md) \*response) | Obtains the capacity information about the SCSI device.| -| int32_t [OH_ScsiPeripheral_RequestSense](_s_c_s_i.md#oh_scsiperipheral_requestsense) ([ScsiPeripheral_Device](_s_c_s_i.md#scsiperipheral_device) \*dev, [ScsiPeripheral_RequestSenseRequest](_scsi_peripheral___request_sense_request.md) \*request, [ScsiPeripheral_Response](_scsi_peripheral___response.md) \*response) | Obtains sense data, that is, information returned by the SCSI device to the host to report the device status, error information, and diagnosis information.| -| int32_t [OH_ScsiPeripheral_Read10](_s_c_s_i.md#oh_scsiperipheral_read10) ([ScsiPeripheral_Device](_s_c_s_i.md#scsiperipheral_device) \*dev, [ScsiPeripheral_IORequest](_scsi_peripheral___i_o_request.md) \*request, [ScsiPeripheral_Response](_scsi_peripheral___response.md) \*response) | Reads data from a specified logical block.| -| int32_t [OH_ScsiPeripheral_Write10](_s_c_s_i.md#oh_scsiperipheral_write10) ([ScsiPeripheral_Device](_s_c_s_i.md#scsiperipheral_device) \*dev, [ScsiPeripheral_IORequest](_scsi_peripheral___i_o_request.md) \*request, [ScsiPeripheral_Response](_scsi_peripheral___response.md) \*response) | Writes data to a specified logical block of a device.| -| int32_t [OH_ScsiPeripheral_Verify10](_s_c_s_i.md#oh_scsiperipheral_verify10) ([ScsiPeripheral_Device](_s_c_s_i.md#scsiperipheral_device) \*dev, [ScsiPeripheral_VerifyRequest](_scsi_peripheral___verify_request.md) \*request, [ScsiPeripheral_Response](_scsi_peripheral___response.md) \*response) | Verifies a specified logical block.| -| int32_t [OH_ScsiPeripheral_SendRequestByCdb](_s_c_s_i.md#oh_scsiperipheral_sendrequestbycdb) ([ScsiPeripheral_Device](_s_c_s_i.md#scsiperipheral_device) \*dev, [ScsiPeripheral_Request](_scsi_peripheral___request.md) \*request, [ScsiPeripheral_Response](_scsi_peripheral___response.md) \*response) | Sends SCSI commands in CDB mode.| -| int32_t [OH_ScsiPeripheral_CreateDeviceMemMap](_s_c_s_i.md#oh_scsiperipheral_createdevicememmap) ([ScsiPeripheral_Device](_s_c_s_i.md#scsiperipheral_device) \*dev, size_t size, [ScsiPeripheral_DeviceMemMap](_scsi_peripheral___device_mem_map.md) \*\*devMmap) | Creates a buffer. To avoid memory leakage, use [OH_ScsiPeripheral_DestroyDeviceMemMap](_s_c_s_i.md#oh_scsiperipheral_destroydevicememmap) to destroy a buffer after use.| -| int32_t [OH_ScsiPeripheral_DestroyDeviceMemMap](_s_c_s_i.md#oh_scsiperipheral_destroydevicememmap) ([ScsiPeripheral_DeviceMemMap](_scsi_peripheral___device_mem_map.md) \*devMmap) | Destroys a buffer. To avoid resource leakage, destroy a buffer in time after use.| -| int32_t [OH_ScsiPeripheral_ParseBasicSenseInfo](_s_c_s_i.md#oh_scsiperipheral_parsebasicsenseinfo) (uint8_t \*senseData, uint8_t senseDataLen, [ScsiPeripheral_BasicSenseInfo](_scsi_peripheral___basic_sense_info.md) \*senseInfo) | Parses basic sense data, including the **Information**, **Command specific information**, and **Sense key specific** fields.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/scsi__peripheral__types_8h.md b/en/application-dev/reference/apis-driverdevelopment-kit/scsi__peripheral__types_8h.md deleted file mode 100644 index 2bd88697ac3..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/scsi__peripheral__types_8h.md +++ /dev/null @@ -1,77 +0,0 @@ -# scsi_peripheral_types.h - - -## Overview - -Provides the enum variables, structures, and macros used in the SCSI Peripheral DDK APIs. - -**File to include**: <scsi_peripheral/scsi_peripheral_types.h> - -**Library**: libscsi.z.so - -**System capability**: SystemCapability.Driver.SCSI.Extension - -**Since**: 18 - -**Related module**: [SCSI Peripheral DDK](_s_c_s_i.md) - - -## Summary - - -### Structs - -| Name| Description| -| -------- | -------- | -| struct  [ScsiPeripheral_DeviceMemMap](_scsi_peripheral___device_mem_map.md) | Device memory mapping created by calling [OH_ScsiPeripheral_CreateDeviceMemMap](_s_c_s_i.md#oh_scsiperipheral_createdevicememmap). The buffer that uses the device memory mapping can provide better performance.| -| struct  [ScsiPeripheral_IORequest](_scsi_peripheral___i_o_request.md) | Read/write operation request.| -| struct  [ScsiPeripheral_Request](_scsi_peripheral___request.md) | Request structure.| -| struct  [ScsiPeripheral_Response](_scsi_peripheral___response.md) | Response structure.| -| struct  [ScsiPeripheral_TestUnitReadyRequest](_scsi_peripheral___test_unit_ready_request.md) | Request structure of the **test unit ready** command.| -| struct  [ScsiPeripheral_InquiryRequest](_scsi_peripheral___inquiry_request.md) | Request structure of the **inquiry** command.| -| struct  [ScsiPeripheral_InquiryInfo](_scsi_peripheral___inquiry_info.md) | SCSI inquiry data.| -| struct  [ScsiPeripheral_ReadCapacityRequest](_scsi_peripheral___read_capacity_request.md) | Request structure of the **read capacity** command.| -| struct  [ScsiPeripheral_CapacityInfo](_scsi_peripheral___capacity_info.md) | SCSI read capacity.| -| struct  [ScsiPeripheral_RequestSenseRequest](_scsi_peripheral___request_sense_request.md) | Request structure of the **request sense** command.| -| struct  [ScsiPeripheral_BasicSenseInfo](_scsi_peripheral___basic_sense_info.md) | Basic information about the sense data.| -| struct  [ScsiPeripheral_VerifyRequest](_scsi_peripheral___verify_request.md) | Request structure of the **verify** command.| - - -### Macros - -| Name| Description| -| -------- | -------- | -| [SCSIPERIPHERAL_MIN_DESCRIPTOR_FORMAT_SENSE](_s_c_s_i.md#scsiperipheral_min_descriptor_format_sense)   8 | Minimum length of the sense data descriptor format.| -| [SCSIPERIPHERAL_MIN_FIXED_FORMAT_SENSE](_s_c_s_i.md#scsiperipheral_min_fixed_format_sense)   18 | Minimum length of the fixed format of sense data.| -| [SCSIPERIPHERAL_MAX_CMD_DESC_BLOCK_LEN](_s_c_s_i.md#scsiperipheral_max_cmd_desc_block_len)   16 | Maximum length of a command descriptor block (CDB).| -| [SCSIPERIPHERAL_MAX_SENSE_DATA_LEN](_s_c_s_i.md#scsiperipheral_max_sense_data_len)   252 | Maximum length of sense data. In the SCSI protocol, the maximum length of sense data is usually 252 bytes.| -| [SCSIPERIPHERAL_VENDOR_ID_LEN](_s_c_s_i.md#scsiperipheral_vendor_id_len)   8 | Maximum length of the vendor ID.| -| [SCSIPERIPHERAL_PRODUCT_ID_LEN](_s_c_s_i.md#scsiperipheral_product_id_len)   18 | Maximum length of the product ID.| -| [SCSIPERIPHERAL_PRODUCT_REV_LEN](_s_c_s_i.md#scsiperipheral_product_rev_len)   4 | Maximum length of the product version.| - - -### Types - -| Name| Description| -| -------- | -------- | -| typedef struct [ScsiPeripheral_Device](_s_c_s_i.md#scsiperipheral_device) [ScsiPeripheral_Device](_s_c_s_i.md#scsiperipheral_device) | Opaque SCSI device structure.| -| typedef struct [ScsiPeripheral_DeviceMemMap](_scsi_peripheral___device_mem_map.md) [ScsiPeripheral_DeviceMemMap](_s_c_s_i.md#scsiperipheral_devicememmap) | Device memory mapping created by calling [OH_ScsiPeripheral_CreateDeviceMemMap](_s_c_s_i.md#oh_scsiperipheral_createdevicememmap). The buffer that uses the device memory mapping can provide better performance.| -| typedef struct [ScsiPeripheral_IORequest](_scsi_peripheral___i_o_request.md) [ScsiPeripheral_IORequest](_s_c_s_i.md#scsiperipheral_iorequest) | Read/write operation request.| -| typedef struct [ScsiPeripheral_Request](_scsi_peripheral___request.md) [ScsiPeripheral_Request](_s_c_s_i.md#scsiperipheral_request) | Request structure.| -| typedef struct [ScsiPeripheral_Response](_scsi_peripheral___response.md) [ScsiPeripheral_Response](_s_c_s_i.md#scsiperipheral_response) | Response structure.| -| typedef struct [ScsiPeripheral_TestUnitReadyRequest](_scsi_peripheral___test_unit_ready_request.md) [ScsiPeripheral_TestUnitReadyRequest](_s_c_s_i.md#scsiperipheral_testunitreadyrequest) | Request structure of the **test unit ready** command.| -| typedef struct [ScsiPeripheral_InquiryRequest](_scsi_peripheral___inquiry_request.md) [ScsiPeripheral_InquiryRequest](_s_c_s_i.md#scsiperipheral_inquiryrequest) | Request structure of the **inquiry** command.| -| typedef struct [ScsiPeripheral_InquiryInfo](_scsi_peripheral___inquiry_info.md) [ScsiPeripheral_InquiryInfo](_s_c_s_i.md#scsiperipheral_inquiryinfo) | SCSI inquiry data.| -| typedef struct [ScsiPeripheral_ReadCapacityRequest](_scsi_peripheral___read_capacity_request.md) [ScsiPeripheral_ReadCapacityRequest](_s_c_s_i.md#scsiperipheral_readcapacityrequest) | Request structure of the **read capacity** command.| -| typedef struct [ScsiPeripheral_CapacityInfo](_scsi_peripheral___capacity_info.md) [ScsiPeripheral_CapacityInfo](_s_c_s_i.md#scsiperipheral_capacityinfo) | SCSI read capacity.| -| typedef struct [ScsiPeripheral_RequestSenseRequest](_scsi_peripheral___request_sense_request.md) [ScsiPeripheral_RequestSenseRequest](_s_c_s_i.md#scsiperipheral_requestsenserequest) | Request structure of the **request sense** command.| -| typedef struct [ScsiPeripheral_BasicSenseInfo](_scsi_peripheral___basic_sense_info.md) [ScsiPeripheral_BasicSenseInfo](_s_c_s_i.md#scsiperipheral_basicsenseinfo) | Basic information about the sense data.| -| typedef struct [ScsiPeripheral_VerifyRequest](_scsi_peripheral___verify_request.md) [ScsiPeripheral_VerifyRequest](_s_c_s_i.md#scsiperipheral_verifyrequest) | Request structure of the **verify** command.| - - -### Enums - -| Name| Description| -| -------- | -------- | -| [ScsiPeripheral_DdkErrCode](_s_c_s_i.md#scsiperipheral_ddkerrcode) {
SCSIPERIPHERAL_DDK_NO_PERM = 201, SCSIPERIPHERAL_DDK_INVALID_PARAMETER = 401, SCSIPERIPHERAL_DDK_SUCCESS = 31700000, SCSIPERIPHERAL_DDK_MEMORY_ERROR = 31700001, SCSIPERIPHERAL_DDK_INVALID_OPERATION = 31700002, SCSIPERIPHERAL_DDK_IO_ERROR = 31700003, SCSIPERIPHERAL_DDK_TIMEOUT = 31700004, SCSIPERIPHERAL_DDK_INIT_ERROR = 31700005, SCSIPERIPHERAL_DDK_SERVICE_ERROR = 31700006, SCSIPERIPHERAL_DDK_DEVICE_NOT_FOUND = 31700007
} | SCSI Peripheral DDK error codes.| -| [ScsiPeripheral_Status](_s_c_s_i.md#scsiperipheral_status) {
SCSIPERIPHERAL_STATUS_GOOD = 0x00, SCSIPERIPHERAL_STATUS_CHECK_CONDITION_NEEDED = 0x02, SCSIPERIPHERAL_STATUS_CONDITION_MET = 0x04, SCSIPERIPHERAL_STATUS_BUSY = 0x08, SCSIPERIPHERAL_STATUS_RESERVATION_CONFLICT = 0x18, SCSIPERIPHERAL_STATUS_TASK_SET_FULL = 0x28, SCSIPERIPHERAL_STATUS_ACA_ACTIVE = 0x30, SCSIPERIPHERAL_STATUS_TASK_ABORTED = 0x40
} | SCSI status used for the response.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/usb__ddk__api_8h.md b/en/application-dev/reference/apis-driverdevelopment-kit/usb__ddk__api_8h.md deleted file mode 100644 index 9cf35e46454..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/usb__ddk__api_8h.md +++ /dev/null @@ -1,42 +0,0 @@ -# usb_ddk_api.h - - -## Overview - -Declares the USB DDK APIs used by the USB host to access USB devices. - -**File to include**: - -**Library**: libusb_ndk.z.so - -**System capability**: SystemCapability.Driver.USB.Extension - -**Since**: 10 - -**Related module**: [USB DDK](_usb_ddk.md) - - -## Summary - - -### Functions - -| Name| Description| -| -------- | -------- | -| [OH_Usb_Init](_usb_ddk.md#oh_usb_init) (void) | Initializes the DDK.| -| [OH_Usb_Release](_usb_ddk.md#oh_usb_release) (void) | Releases the USB DDK.| -| [OH_Usb_ReleaseResource](_usb_ddk.md#oh_usb_releaseresource) (void) | Releases the USB DDK.| -| [OH_Usb_GetDeviceDescriptor](_usb_ddk.md#oh_usb_getdevicedescriptor) (uint64_t deviceId, struct [UsbDeviceDescriptor](_usb_device_descriptor.md) \*desc) | Obtains the device descriptor.| -| [OH_Usb_GetConfigDescriptor](_usb_ddk.md#oh_usb_getconfigdescriptor) (uint64_t deviceId, uint8_t configIndex, struct [UsbDdkConfigDescriptor](_usb_ddk_config_descriptor.md) \*\*const config) | Obtains the configuration descriptor. To avoid memory leakage, use [OH_Usb_FreeConfigDescriptor()](_usb_ddk.md#oh_usb_freeconfigdescriptor) to release a descriptor after use.| -| [OH_Usb_FreeConfigDescriptor](_usb_ddk.md#oh_usb_freeconfigdescriptor) (const struct [UsbDdkConfigDescriptor](_usb_ddk_config_descriptor.md) \*const config) | Releases the configuration descriptor. To avoid memory leakage, release a descriptor after use.| -| [OH_Usb_ClaimInterface](_usb_ddk.md#oh_usb_claiminterface) (uint64_t deviceId, uint8_t interfaceIndex, uint64_t \*[interfaceHandle](usb__ddk__types_8h.md#interfacehandle)) | Declares a USB interface.| -| [OH_Usb_ReleaseInterface](_usb_ddk.md#oh_usb_releaseinterface) (uint64_t [interfaceHandle](usb__ddk__types_8h.md#interfacehandle)) | Releases a USB interface.| -| [OH_Usb_SelectInterfaceSetting](_usb_ddk.md#oh_usb_selectinterfacesetting) (uint64_t [interfaceHandle](usb__ddk__types_8h.md#interfacehandle), uint8_t settingIndex) | Activates the alternate setting of a USB interface.| -| [OH_Usb_GetCurrentInterfaceSetting](_usb_ddk.md#oh_usb_getcurrentinterfacesetting) (uint64_t [interfaceHandle](usb__ddk__types_8h.md#interfacehandle), uint8_t \*settingIndex) | Obtains the activated alternate setting of a USB interface.| -| [OH_Usb_SendControlReadRequest](_usb_ddk.md#oh_usb_sendcontrolreadrequest) (uint64_t [interfaceHandle](usb__ddk__types_8h.md#interfacehandle), const struct [UsbControlRequestSetup](_usb_control_request_setup.md) \*setup, uint32_t [timeout](usb__ddk__types_8h.md#timeout), uint8_t \*data, uint32_t \*dataLen) | Sends a control read transfer request. This API works in a synchronous manner.| -| [OH_Usb_SendControlWriteRequest](_usb_ddk.md#oh_usb_sendcontrolwriterequest) (uint64_t [interfaceHandle](usb__ddk__types_8h.md#interfacehandle), const struct [UsbControlRequestSetup](_usb_control_request_setup.md) \*setup, uint32_t [timeout](usb__ddk__types_8h.md#timeout), const uint8_t \*data, uint32_t dataLen) | Sends a control write transfer request. This API works in a synchronous manner.| -| [OH_Usb_SendPipeRequest](_usb_ddk.md#oh_usb_sendpiperequest) (const struct [UsbRequestPipe](_usb_request_pipe.md) \*pipe, [UsbDeviceMemMap](_usb_device_mem_map.md) \*devMmap) | Sends a pipe request. This API works in a synchronous manner. It applies to interrupt transfer and bulk transfer.| -| [OH_Usb_SendPipeRequestWithAshmem](_usb_ddk.md#oh_usb_sendpiperequestwithashmem) (const struct [UsbRequestPipe](_usb_request_pipe.md) \*pipe, [DDK_Ashmem](_ddk_ashmem.md) \*ashmem) | Sends a pipe request for the shared memory. This API returns the result synchronously. It applies to interrupt transfer and bulk transfer.| -| [OH_Usb_CreateDeviceMemMap](_usb_ddk.md#oh_usb_createdevicememmap) (uint64_t deviceId, size_t size, [UsbDeviceMemMap](_usb_device_mem_map.md) \*\*devMmap) | Creates a buffer. To avoid memory leakage, use [OH_Usb_DestroyDeviceMemMap()](_usb_ddk.md#oh_usb_destroydevicememmap) to destroy a buffer after use.| -| [OH_Usb_DestroyDeviceMemMap](_usb_ddk.md#oh_usb_destroydevicememmap) ([UsbDeviceMemMap](_usb_device_mem_map.md) \*devMmap) | Destroys a buffer. To avoid resource leakage, destroy a buffer in time after use.| -| [OH_Usb_GetDevices](_usb_ddk.md#oh_usb_getdevices) ([Usb_DeviceArray](_usb_device_array.md) \*devices) | Obtains the USB device ID list. Ensure that the input pointer is valid and the number of devices does not exceed 128. To prevent resource leakage, release the member memory after usage. Besides, make sure that the obtained USB device ID has been filtered by **vid** in the driver configuration information.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/usb__ddk__types_8h.md b/en/application-dev/reference/apis-driverdevelopment-kit/usb__ddk__types_8h.md deleted file mode 100644 index d43b7ba77a3..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/usb__ddk__types_8h.md +++ /dev/null @@ -1,620 +0,0 @@ -# usb_ddk_types.h - - -## Overview - -Provides the enumerated variables, structures, and macros used in USB DDK APIs. - -**File to include**: - -**Library**: libusb_ndk.z.so - -**System capability**: SystemCapability.Driver.USB.Extension - -**Since**: 10 - -**Related module**: [USB DDK](_usb_ddk.md) - - -## Summary - - -### Structs - -| Name| Description| -| -------- | -------- | -| [UsbControlRequestSetup](_usb_control_request_setup.md) | Setup data for control transfer, corresponding to **Setup Data** in the USB protocol.| -| [UsbDeviceDescriptor](_usb_device_descriptor.md) | Standard device descriptor, corresponding to **Standard Device Descriptor** in the USB protocol.| -| [UsbConfigDescriptor](_usb_config_descriptor.md) | Standard configuration descriptor, corresponding to **Standard Configuration Descriptor** in the USB protocol.| -| [UsbInterfaceDescriptor](_usb_interface_descriptor.md) | Standard interface descriptor, corresponding to **Standard Interface Descriptor** in the USB protocol.| -| [UsbEndpointDescriptor](_usb_endpoint_descriptor.md) | Standard endpoint descriptor, corresponding to **Standard Endpoint Descriptor** in the USB protocol.| -| [UsbDdkEndpointDescriptor](_usb_ddk_endpoint_descriptor.md) | Endpoint descriptor.| -| [UsbDdkInterfaceDescriptor](_usb_ddk_interface_descriptor.md) | Interface descriptor.| -| [UsbDdkInterface](_usb_ddk_interface.md) | USB DDK interface, which is a collection of alternate settings for a particular USB interface.| -| [UsbDdkConfigDescriptor](_usb_ddk_config_descriptor.md) | Configuration descriptor.| -| [UsbRequestPipe](_usb_request_pipe.md) | Request pipe.| -| [UsbDeviceMemMap](_usb_device_mem_map.md) | Device memory map created by calling [OH_Usb_CreateDeviceMemMap()](_usb_ddk.md#oh_usb_createdevicememmap). A buffer using the device memory map can provide better performance.| -| [Usb_DeviceArray](_usb_device_array.md) | Defines the device ID list, which is used to store the device IDs and device quantity obtained using [OH_Usb_GetDevices()](_usb_ddk.md#oh_usb_getdevices).| - - -### Types - -| Name| Description| -| -------- | -------- | -| typedef struct [UsbDdkEndpointDescriptor](_usb_ddk_endpoint_descriptor.md) [UsbDdkEndpointDescriptor](_usb_ddk.md#usbddkendpointdescriptor) | Endpoint descriptor.| -| typedef struct [UsbDdkInterfaceDescriptor](_usb_ddk_interface_descriptor.md) [UsbDdkInterfaceDescriptor](_usb_ddk.md#usbddkinterfacedescriptor) | Interface descriptor.| -| typedef struct [UsbDdkInterface](_usb_ddk_interface.md) [UsbDdkInterface](_usb_ddk.md#usbddkinterface) | USB interface.| -| typedef struct [UsbDdkConfigDescriptor](_usb_ddk_config_descriptor.md) [UsbDdkConfigDescriptor](_usb_ddk.md#usbddkconfigdescriptor) | Configuration descriptor.| -| typedef struct [UsbDeviceMemMap](_usb_device_mem_map.md) [UsbDeviceMemMap](_usb_ddk.md#usbdevicememmap) | Device memory map created by calling [OH_Usb_CreateDeviceMemMap()](_usb_ddk.md#oh_usb_createdevicememmap). A buffer using the device memory map can provide better performance.| -| typedef struct [Usb_DeviceArray](_usb_device_array.md) [Usb_DeviceArray](_usb_ddk.md#usb_devicearray) | Defines the device ID list, which is used to store the device IDs and device quantity obtained using [OH_Usb_GetDevices()](_usb_ddk.md#oh_usb_getdevices).| - -### Enums - -| Name| Description| -| -------- | -------- | -| [UsbDdkErrCode](_usb_ddk.md#usbddkerrcode) {
USB_DDK_SUCCESS = 0, USB_DDK_FAILED = -1, USB_DDK_INVALID_PARAMETER = -2, USB_DDK_MEMORY_ERROR = -3,
USB_DDK_INVALID_OPERATION = -4, USB_DDK_NULL_PTR = -5, USB_DDK_DEVICE_BUSY = -6, USB_DDK_TIMEOUT = -7
} | USB DDK error code definition.| - - -### Variables - -| Name| Description| -| -------- | -------- | -| [bmRequestType](#bmrequesttype) | Request type.| -| [bRequest](#brequest) | Specific request.| -| [wValue](#wvalue) | Value corresponding to **wValue** in the USB protocol. Its meaning varies according to the request.| -| [wIndex](#windex) | Index corresponding to **wIndex** in the USB protocol. It is usually used to transfer the index or offset. Its meaning varies according to the request. | -| [wLength](#wlength) | Data length corresponding to **wLength** in the USB protocol. If data is transferred, this field indicates the number of transferred bytes.| -| [bLength](#blength) | Size of the descriptor, in bytes.| -| [bDescriptorType](#bdescriptortype) | Descriptor type.| -| [bcdUSB](#bcdusb) | USB protocol release number.| -| [bDeviceClass](#bdeviceclass) | Interface class code allocated by the USB-IF.| -| [bDeviceSubClass](#bdevicesubclass) | Device subclass code allocated by USB-IF. The value is limited by that of bDeviceClass.| -| [bDeviceProtocol](#bdeviceprotocol) | Protocol code allocated by USB-IF. The value is limited by that of [bDeviceClass](#bdeviceclass) and [bDeviceSubClass](#bdevicesubclass).| -| [bMaxPacketSize0](#bmaxpacketsize0) | Maximum packet size of endpoint 0. Only values 8, 16, 32, and 64 are valid.| -| [idVendor](#idvendor) | Vendor ID allocated by USB-IF.| -| [idProduct](#idproduct) | Product ID allocated by the vendor.| -| [bcdDevice](#bcddevice) | Device release number.| -| [iManufacturer](#imanufacturer) | Index of the string descriptor that describes the vendor.| -| [iProduct](#iproduct) | Index of the string descriptor that describes the product.| -| [iSerialNumber](#iserialnumber) | Index of the string descriptor that describes the device SN.| -| [bNumConfigurations](#bnumconfigurations) | Configuration quantity.| -| [wTotalLength](#wtotallength) | Total length of the configuration descriptor, including the configuration, interface, endpoint, and class- or vendor-specific descriptors.| -| [bNumInterfaces](#bnuminterfaces) | Number of interfaces supported by the configuration.| -| [bConfigurationValue](#bconfigurationvalue) | Configuration index, which is used to select the configuration.| -| [iConfiguration](#iconfiguration) | Index of the string descriptor that describes the configuration.| -| [bmAttributes](#bmattributes) | Configuration attributes, including the power mode and remote wakeup.| -| [bMaxPower](#bmaxpower) | Maximum power consumption of the bus-powered USB device, in 2 mA.| -| [bInterfaceNumber](#binterfacenumber) | Interface ID.| -| [bAlternateSetting](#balternatesetting) | Value used to select the alternate setting of the interface.| -| [bNumEndpoints](#bnumendpoints) | Number of endpoints (excluding endpoint 0) used by the interface.| -| [bInterfaceClass](#binterfaceclass) | Interface class code allocated by the USB-IF.| -| [bInterfaceSubClass](#binterfacesubclass) | Device subclass code allocated by USB-IF. The value is limited by that of [bInterfaceClass](#binterfaceclass).| -| [bInterfaceProtocol](#binterfaceprotocol) | Protocol code allocated by USB-IF. The value is limited by that of [bInterfaceClass](#binterfaceclass) and [bInterfaceSubClass](#binterfacesubclass).| -| [iInterface](#iinterface) | Index of the string descriptor that describes the interface.| -| [bEndpointAddress](#bendpointaddress) | Endpoint address, including the endpoint number and endpoint direction.| -| [bmAttributes](#bmattributes) | Endpoint attributes, including the transfer type, synchronization type, and usage type.| -| [wMaxPacketSize](#wmaxpacketsize) | Maximum packet size supported by an endpoint.| -| [bInterval](#binterval) | Interval for polling endpoints for data transfer.| -| [bRefresh](#brefresh) | Refresh rate for audio devices.| -| [bSynchAddress](#bsynchaddress) | Endpoint synchronization address for audio devices.| -| [interfaceHandle](#interfacehandle) | Interface operation handle.| -| [endpoint](#endpoint) | Endpoint address.| -| [timeout](#timeout) | Timeout duration, in milliseconds.| -| [deviceIds](#deviceids) | Start address of the device ID array.| -| [num](#num) | Device quantity.| - - -## Variable Description - - -### bAlternateSetting - - -``` -uint8_t bAlternateSetting -``` - -**Description** - -Value used to select the alternate setting of the interface. - - -### bcdDevice - - -``` -uint16_t bcdDevice -``` - -**Description** - -Device release number. - - -### bcdUSB - - -``` -uint16_t bcdUSB -``` - -**Description** - -USB protocol release number. - - -### bConfigurationValue - - -``` -uint8_t bConfigurationValue -``` - -**Description** - -Configuration index, which is used to select the configuration. - - -### bDescriptorType - - -``` -uint8_t bDescriptorType -``` - -**Description** - -Descriptor type. - - -### bDeviceClass - - -``` -uint8_t bDeviceClass -``` - -**Description** - -Interface class code allocated by the USB-IF. - - -### bDeviceProtocol - - -``` -uint8_t bDeviceProtocol -``` - -**Description** - -Protocol code allocated by USB-IF. The value is limited by that of [bDeviceClass](#bdeviceclass) and [bDeviceSubClass](#bdevicesubclass). - - -### bDeviceSubClass - - -``` -uint8_t bDeviceSubClass -``` - -**Description** - -Device subclass code allocated by USB-IF. The value is limited by that of bDeviceClass. - - -### bEndpointAddress - - -``` -uint8_t bEndpointAddress -``` - -**Description** - -Endpoint address, including the endpoint number and endpoint direction. - - -### bmAttributes - - -``` -uint8_t bmAttributes -``` - -**Description** - -Endpoint attributes, including the transfer type, synchronization type, and usage type. - - -### bInterfaceClass - - -``` -uint8_t bInterfaceClass -``` - -**Description** - -Interface class code allocated by the USB-IF. - - -### bInterfaceNumber - - -``` -uint8_t bInterfaceNumber -``` - -**Description** - -Interface ID. - - -### bInterfaceProtocol - - -``` -uint8_t bInterfaceProtocol -``` - -**Description** - -Protocol code allocated by USB-IF. The value is limited by that of [bInterfaceClass](#binterfaceclass) and [bInterfaceSubClass](#binterfacesubclass). - - -### bInterfaceSubClass - - -``` -uint8_t bInterfaceSubClass -``` - -**Description** - -Device subclass code allocated by USB-IF. The value is limited by that of [bInterfaceClass](#binterfaceclass). - - -### bInterval - - -``` -uint8_t bInterval -``` - -**Description** - -Interval for polling endpoints for data transfer. - - -### bLength - - -``` -uint8_t bLength -``` - -**Description** - -Size of the descriptor, in bytes. - - -### bmAttributes - - -``` -uint8_t bmAttributes -``` - -**Description** - -Configuration attributes, including the power mode and remote wakeup. - - -### bMaxPacketSize0 - - -``` -uint8_t bMaxPacketSize0 -``` - -**Description** - -Maximum packet size of endpoint 0. Only values 8, 16, 32, and 64 are valid. - - -### bMaxPower - - -``` -uint8_t bMaxPower -``` - -**Description** - -Maximum power consumption of the bus-powered USB device, in 2 mA. - - -### bNumConfigurations - - -``` -uint8_t bNumConfigurations -``` - -**Description** - -Configuration quantity. - - -### bNumEndpoints - - -``` -uint8_t bNumEndpoints -``` - -**Description** - -Number of endpoints (excluding endpoint 0) used by the interface. - - -### bNumInterfaces - - -``` -uint8_t bNumInterfaces -``` - -**Description** - -Number of interfaces supported by the configuration. - - -### bRefresh - - -``` -uint8_t bRefresh -``` - -**Description** - -Refresh rate for audio devices. - - -### bSynchAddress - - -``` -uint8_t bSynchAddress -``` - -**Description** - -Endpoint synchronization address for audio devices. - - -### endpoint - - -``` -uint8_t endpoint -``` - -**Description** - -Endpoint address. - - -### iConfiguration - - -``` -uint8_t iConfiguration -``` - -**Description** - -Index of the string descriptor that describes the configuration. - - -### idProduct - - -``` -uint16_t idProduct -``` - -**Description** - -Product ID allocated by the vendor. - - -### idVendor - - -``` -uint16_t idVendor -``` - -**Description** - -Vendor ID allocated by USB-IF. - - -### iInterface - - -``` -uint8_t iInterface -``` - -**Description** - -Index of the string descriptor that describes the interface. - - -### iManufacturer - - -``` -uint8_t iManufacturer -``` - -**Description** - -Index of the string descriptor that describes the vendor. - - -### wIndex - - -``` -uint16_t wIndex -``` - -**Description** - -Index corresponding to **wIndex** in the USB protocol. It is usually used to transfer the index or offset. Its meaning varies according to the request. - - -### interfaceHandle - - -``` -uint64_t interfaceHandle -``` - -**Description** - -Interface operation handle. - - -### iProduct - - -``` -uint8_t iProduct -``` - -**Description** - -Index of the string descriptor that describes the product. - - -### iSerialNumber - - -``` -uint8_t iSerialNumber -``` - -**Description** - -Index of the string descriptor that describes the device SN. - - -### wLength - - -``` -uint16_t wLength -``` - -**Description** - -Data length corresponding to **wLength** in the USB protocol. If data is transferred, this field indicates the number of transferred bytes. - - -### bRequest - - -``` -uint8_t bRequest -``` - -**Description** - -Specific request. - - -### bmRequestType - - -``` -uint8_t bmRequestType -``` - -**Description** - -Request type. - - -### timeout - - -``` -uint32_t timeout -``` - -**Description** - -Timeout duration, in milliseconds. - - -### wValue - - -``` -uint16_t wValue -``` - -**Description** - -Value corresponding to **wValue** in the USB protocol. Its meaning varies according to the request. - - -### wMaxPacketSize - - -``` -uint16_t wMaxPacketSize -``` - -**Description** - -Maximum packet size supported by an endpoint. - - -### wTotalLength - - -``` -uint16_t wTotalLength -``` - -**Description** - -Total length of the configuration descriptor, including the configuration, interface, endpoint, and class- or vendor-specific descriptors. - - -### deviceIds - -``` -uint64_t* deviceIds -``` - -**Description** - -Defines the start address of the device ID array. The number of device IDs cannot exceed 128. -### num - - -``` -uint32_t num -``` - -**Description** - -Defines the device quantity. Device IDs are obtained by traversing **deviceIds** based on the value of this parameter. If the value is **0**, there is no USB device. diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/usb__serial__ddk__api_8h.md b/en/application-dev/reference/apis-driverdevelopment-kit/usb__serial__ddk__api_8h.md deleted file mode 100644 index 7310fea2eb4..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/usb__serial__ddk__api_8h.md +++ /dev/null @@ -1,38 +0,0 @@ -# usb_serial_ddk_api.h - - -## Overview - -Declares the USB Serial DDK APIs used by the host to access the serial port device. - -**Library**: libusb_serial.z.so - -**File to include**: <serial/usb_serial_ddk_api.h> - -**System capability**: SystemCapability.Driver.SERIAL.Extension - -**Since**: 18 - -**Related module**: [USB Serial DDK](_serial_ddk.md) - - -## Summary - - -### Function - -| Name| Description| -| -------- | -------- | -| int32_t [OH_UsbSerial_Init](_serial_ddk.md#oh_usbserial_init) (void) | Initializes the USB Serial DDK.| -| int32_t [OH_UsbSerial_Release](_serial_ddk.md#oh_usbserial_release) (void) | Releases the USB Serial DDK.| -| int32_t [OH_UsbSerial_Open](_serial_ddk.md#oh_usbserial_open) (uint64_t deviceId, uint8_t interfaceIndex, [UsbSerial_DeviceHandle](_serial_ddk.md#usbserial_devicehandle) \*\*dev) | Enables the USB serial port device based on the specified **deviceId** and **interfaceIndex**.| -| int32_t [OH_UsbSerial_Close](_serial_ddk.md#oh_usbserial_close) ([UsbSerial_DeviceHandle](_serial_ddk.md#usbserial_devicehandle) \*dev) | Disables the USB serial port device.| -| int32_t [OH_UsbSerial_Read](_serial_ddk.md#oh_usbserial_read) ([UsbSerial_DeviceHandle](_serial_ddk.md#usbserial_devicehandle) \*dev, uint8_t \*buff, uint32_t bufferSize, uint32_t \*bytesRead) | Reads data from the USB serial port device to the buffer.| -| int32_t [OH_UsbSerial_Write](_serial_ddk.md#oh_usbserial_write) ([UsbSerial_DeviceHandle](_serial_ddk.md#usbserial_devicehandle) \*dev, uint8_t \*buff, uint32_t bufferSize, uint32_t \*bytesWritten) | Writes the data in the buffer to the USB serial port device.| -| int32_t [OH_UsbSerial_SetBaudRate](_serial_ddk.md#oh_usbserial_setbaudrate) ([UsbSerial_DeviceHandle](_serial_ddk.md#usbserial_devicehandle) \*dev, uint32_t [baudRate](usb__serial__ddk__types_8h.md#baudrate)) | Sets the baud rate for a USB serial port device. If the parameters of the USB serial port device are set to the default values (the data bit is **8**, the stop bit is **1**, and parity is disabled for data transfer), you only need to call this API to set the baud rate.| -| int32_t [OH_UsbSerial_SetParams](_serial_ddk.md#oh_usbserial_setparams) ([UsbSerial_DeviceHandle](_serial_ddk.md#usbserial_devicehandle) \*dev, [UsbSerial_Params](_usb_serial___params.md) \*params) | Sets the parameters of the USB serial port device. If the parameters of the USB serial port device are not set to the default values (the data bit is **8**, the stop bit is **1**, and parity is disabled for data transfer), you only need to call this API to set the related parameters.| -| int32_t [OH_UsbSerial_SetTimeout](_serial_ddk.md#oh_usbserial_settimeout) ([UsbSerial_DeviceHandle](_serial_ddk.md#usbserial_devicehandle) \*dev, int timeout) | Sets the timeout interval (ms) for reading data reported by a USB serial port device. If this function is not called, the timeout value is **0** by default, indicating that data is returned immediately regardless of whether data is read. If you need to wait for a certain period of time or data must be read, call this API to set the timeout interval.| -| int32_t [OH_UsbSerial_SetFlowControl](_serial_ddk.md#oh_usbserial_setflowcontrol) ([UsbSerial_DeviceHandle](_serial_ddk.md#usbserial_devicehandle) \*dev, [UsbSerial_FlowControl](_serial_ddk.md#usbserial_flowcontrol) flowControl) | Sets flow control parameters. Flow control is used to manage the data transfer rate during communication with the USB serial port device to ensure that the sender does not send data that exceeds the processing capability of the receiver.
If flow control is required, call this API to set flow control parameters. If this API is not called, flow control is not performed by default.| -| int32_t [OH_UsbSerial_Flush](_serial_ddk.md#oh_usbserial_flush) ([UsbSerial_DeviceHandle](_serial_ddk.md#usbserial_devicehandle) \*dev) | Clears the input and output buffers after the write operation is complete. If a large amount of data is to be transmitted to the USB serial port device, the data may be buffered in the kernel for transmission. If the application closes the file descriptor or exits before the data is completely sent out, some data may be lost. You can call this API to ensure that all data is sent before subsequent operations are performed.| -| int32_t [OH_UsbSerial_FlushInput](_serial_ddk.md#oh_usbserial_flushinput) ([UsbSerial_DeviceHandle](_serial_ddk.md#usbserial_devicehandle) \*dev) | Refreshes the input buffer. The data in the buffer is cleared immediately. During the communication with the USB serial port device, especially in the debugging phase, disordered data packets or other exceptions may occur.
You can call this API to clear these exceptions to restore the communication.| -| int32_t [OH_UsbSerial_FlushOutput](_serial_ddk.md#oh_usbserial_flushoutput) ([UsbSerial_DeviceHandle](_serial_ddk.md#usbserial_devicehandle) \*dev) | Refreshes the output buffer. The data in the buffer is cleared immediately. During the communication with the USB serial port device, especially in the debugging phase, disordered data packets or other exceptions may occur.
You can call this API to clear these exceptions to restore the communication.| diff --git a/en/application-dev/reference/apis-driverdevelopment-kit/usb__serial__ddk__types_8h.md b/en/application-dev/reference/apis-driverdevelopment-kit/usb__serial__ddk__types_8h.md deleted file mode 100644 index 538b60dad96..00000000000 --- a/en/application-dev/reference/apis-driverdevelopment-kit/usb__serial__ddk__types_8h.md +++ /dev/null @@ -1,100 +0,0 @@ -# usb_serial_types.h - - -## Overview - -Provides the enum variables, structures, and macros used in USB Serial DDK APIs. - -**Library**: libusb_serial.z.so - -**File to include**: <serial/usb_serial_types.h> - -**System capability**: SystemCapability.Driver.SERIAL.Extension - -**Since**: 18 - -**Related module**: [USB Serial DDK](_serial_ddk.md) - - -## Summary - - -### Structs - -| Name| Description| -| -------- | -------- | -| struct  [UsbSerial_Params](_usb_serial___params.md) | Defines the USB serial port parameters for the USB Serial DDK.| - - -### Types - -| Name| Description| -| -------- | -------- | -| typedef struct [UsbSerial_DeviceHandle](_serial_ddk.md#usbserial_devicehandle) [UsbSerial_DeviceHandle](_serial_ddk.md#usbserial_devicehandle) | Data structure of the USB serial port device (opaque).| -| typedef struct [UsbSerial_Params](_usb_serial___params.md) \__attribute\__((aligned(8))) [UsbSerial_Params](_usb_serial___params.md) | USB serial port parameters used by the USB Serial DDK.| - - -### Enums - -| Name| Description| -| -------- | -------- | -| [UsbSerial_DdkRetCode](_serial_ddk.md#usbserial_ddkretcode) {
USB_SERIAL_DDK_NO_PERM = 201, USB_SERIAL_DDK_INVALID_PARAMETER = 401, USB_SERIAL_DDK_SUCCESS = 31600000, USB_SERIAL_DDK_INVALID_OPERATION = 31600001, USB_SERIAL_DDK_INIT_ERROR = 31600002, USB_SERIAL_DDK_SERVICE_ERROR = 31600003, USB_SERIAL_DDK_MEMORY_ERROR = 31600004, USB_SERIAL_DDK_IO_ERROR = 31600005, USB_SERIAL_DDK_DEVICE_NOT_FOUND = 31600006
} | Defines the return codes used by the USB Serial DDK.| -| [UsbSerial_FlowControl](_serial_ddk.md#usbserial_flowcontrol) { USB_SERIAL_NO_FLOW_CONTROL = 0, USB_SERIAL_SOFTWARE_FLOW_CONTROL = 1, USB_SERIAL_HARDWARE_FLOW_CONTROL = 2 } | Defines the flow control mode for the USB Serial DDK.| -| [UsbSerial_Parity](_serial_ddk.md#usbserial_parity) { USB_SERIAL_PARITY_NONE = 0, USB_SERIAL_PARITY_ODD = 1, USB_SERIAL_PARITY_EVEN = 2 } | Defines the enums of the parity parameter used by the USB Serial DDK.| - - -### Variables - -| Name| Description| -| -------- | -------- | -| uint32_t [baudRate](#baudrate) | Baud rate.| -| uint8_t [nDataBits](#ndatabits) | Number of data transfer bits.| -| uint8_t [nStopBits](#nstopbits) | Number of data stop bits.| -| uint8_t [parity](#parity) | Parity settings.| - - -## Variable Description - - -### baudRate - -``` -uint32_t baudRate -``` - -**Description** - -Baud rate. - - -### nDataBits - -``` -uint8_t nDataBits -``` - -**Description** - -Number of data transfer bits. - - -### nStopBits - -``` -uint8_t nStopBits -``` - -**Description** - -Number of data stop bits. - - -### parity - -``` -uint8_t parity -``` - -**Description** - -Parity settings. diff --git a/en/application-dev/reference/apis-input-kit/capi-input-input-axisevent.md b/en/application-dev/reference/apis-input-kit/capi-input-input-axisevent.md new file mode 100644 index 00000000000..af5e5a738ef --- /dev/null +++ b/en/application-dev/reference/apis-input-kit/capi-input-input-axisevent.md @@ -0,0 +1,11 @@ +# Input_AxisEvent + +## Overview + +Defines an axis event. + +**Since**: 12 + +**Related module**: [input](capi-input.md) + +**Header file**: [oh_input_manager.h](capi-oh-input-manager-h.md) diff --git a/en/application-dev/reference/apis-input-kit/capi-input-input-deviceinfo.md b/en/application-dev/reference/apis-input-kit/capi-input-input-deviceinfo.md new file mode 100644 index 00000000000..0e28f530890 --- /dev/null +++ b/en/application-dev/reference/apis-input-kit/capi-input-input-deviceinfo.md @@ -0,0 +1,11 @@ +# Input_DeviceInfo + +## Overview + +Defines the input device information. + +**Since**: 13 + +**Related module**: [input](capi-input.md) + +**Header file**: [oh_input_manager.h](capi-oh-input-manager-h.md) diff --git a/en/application-dev/reference/apis-input-kit/capi-input-input-devicelistener.md b/en/application-dev/reference/apis-input-kit/capi-input-input-devicelistener.md new file mode 100644 index 00000000000..1dc429b0720 --- /dev/null +++ b/en/application-dev/reference/apis-input-kit/capi-input-input-devicelistener.md @@ -0,0 +1,20 @@ +# Input_DeviceListener + +## Overview + +Defines a listener for device hot swap events. + +**Since**: 13 + +**Related module**: [input](capi-input.md) + +**Header file**: [oh_input_manager.h](capi-oh-input-manager-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| Input_DeviceAddedCallback deviceAddedCallback | Defines a callback used to receive device insertion events.| +| Input_DeviceRemovedCallback deviceRemovedCallback | Defines a callback used to receive device removal events.| diff --git a/en/application-dev/reference/apis-input-kit/capi-input-input-hotkey.md b/en/application-dev/reference/apis-input-kit/capi-input-input-hotkey.md new file mode 100644 index 00000000000..fb05ba8b387 --- /dev/null +++ b/en/application-dev/reference/apis-input-kit/capi-input-input-hotkey.md @@ -0,0 +1,11 @@ +# Input_Hotkey + +## Overview + +Defines the shortcut key structure. + +**Since**: 14 + +**Related module**: [input](capi-input.md) + +**Header file**: [oh_input_manager.h](capi-oh-input-manager-h.md) diff --git a/en/application-dev/reference/apis-input-kit/capi-input-input-interceptoreventcallback.md b/en/application-dev/reference/apis-input-kit/capi-input-input-interceptoreventcallback.md new file mode 100644 index 00000000000..f46b1c619e2 --- /dev/null +++ b/en/application-dev/reference/apis-input-kit/capi-input-input-interceptoreventcallback.md @@ -0,0 +1,143 @@ +# Input_InterceptorEventCallback + +## Overview + +Defines the structure of the interceptor for callback events, including mouse events, touch events, and axis events. + +**Since**: 12 + +**Related module**: [input](capi-input.md) + +**Header file**: [oh_input_manager.h](capi-oh-input-manager-h.md) + +## Summary + +### Member Variables + +| Name| Description| +| -- | -- | +| Input_MouseEventCallback mouseCallback | Callback for mouse events.
**Since**: 12| +| Input_TouchEventCallback touchCallback | Callback for touch events.
**Since**: 12| +| Input_AxisEventCallback axisCallback | Callback for axis events.
**Since**: 12| + + +### Member functions + +| Name| typedef Keyword| Description| +| -- | -- | -- | +| [typedef void (\*Input_KeyEventCallback)(const Input_KeyEvent* keyEvent)](#input_keyeventcallback) | Input_KeyEventCallback() | Defines a lifecycle callback for **keyEvent**. If the callback is triggered, **keyEvent** will be destroyed.
**Since**: 12| +| [typedef void (\*Input_MouseEventCallback)(const Input_MouseEvent* mouseEvent)](#input_mouseeventcallback) | Input_MouseEventCallback() | Defines a lifecycle callback for **mouseEvent**. If the callback is triggered, **mouseEvent** will be destroyed.
**Since**: 12| +| [typedef void (\*Input_TouchEventCallback)(const Input_TouchEvent* touchEvent)](#input_toucheventcallback) | Input_TouchEventCallback() | Defines a lifecycle callback for **touchEvent**. If the callback is triggered, **touchEvent** will be destroyed.
**Since**: 12| +| [typedef void (\*Input_AxisEventCallback)(const Input_AxisEvent* axisEvent)](#input_axiseventcallback) | Input_AxisEventCallback() | Defines a lifecycle callback for **axisEvent**. If the callback is triggered, **axisEvent** will be destroyed.
**Since**: 12| +| [typedef void (\*Input_DeviceAddedCallback)(int32_t deviceId)](#input_deviceaddedcallback) | Input_DeviceAddedCallback() | Defines the callback used to receive device insertion events.
**Since**: 13| +| [typedef void (\*Input_DeviceRemovedCallback)(int32_t deviceId)](#input_deviceremovedcallback) | Input_DeviceRemovedCallback() | Defines the callback used to receive device removal events.
**Since**: 13| + +## Member Function Description + +### Input_KeyEventCallback() + +``` +typedef void (*Input_KeyEventCallback)(const Input_KeyEvent* keyEvent) +``` + +**Description** + +Defines a lifecycle callback for **keyEvent**. If the callback is triggered, **keyEvent** will be destroyed. + +**Since**: 12 + +**Parameters** + +| Name| Description| +| -- | -- | +| const [Input_KeyEvent](capi-input-input-keyevent.md)* keyEvent | Key event object.| + +### Input_MouseEventCallback() + +``` +typedef void (*Input_MouseEventCallback)(const Input_MouseEvent* mouseEvent) +``` + +**Description** + +Defines a lifecycle callback for **mouseEvent**. If the callback is triggered, **mouseEvent** will be destroyed. + +**Since**: 12 + +**Parameters** + +| Name| Description| +| -- | -- | +| const [Input_MouseEvent](capi-input-input-mouseevent.md)* mouseEvent | Mouse event object.| + +### Input_TouchEventCallback() + +``` +typedef void (*Input_TouchEventCallback)(const Input_TouchEvent* touchEvent) +``` + +**Description** + +Defines a lifecycle callback for **touchEvent**. If the callback is triggered, **touchEvent** will be destroyed. + +**Since**: 12 + +**Parameters** + +| Name| Description| +| -- | -- | +| const [Input_TouchEvent](capi-input-input-touchevent.md)* touchEvent | Touch event object.| + +### Input_AxisEventCallback() + +``` +typedef void (*Input_AxisEventCallback)(const Input_AxisEvent* axisEvent) +``` + +**Description** + +Defines a lifecycle callback for **axisEvent**. If the callback is triggered, **axisEvent** will be destroyed. + +**Since**: 12 + +**Parameters** + +| Name| Description| +| -- | -- | +| const [Input_AxisEvent](capi-input-input-axisevent.md)* axisEvent | Axis event object.| + +### Input_DeviceAddedCallback() + +``` +typedef void (*Input_DeviceAddedCallback)(int32_t deviceId) +``` + +**Description** + +Defines the callback used to receive device insertion events. + +**Since**: 13 + +**Parameters** + +| Name| Description| +| -- | -- | +| int32_t deviceId | Device ID.| + +### Input_DeviceRemovedCallback() + +``` +typedef void (*Input_DeviceRemovedCallback)(int32_t deviceId) +``` + +**Description** + +Defines the callback used to receive device removal events. + +**Since**: 13 + +**Parameters** + +| Name| Description| +| -- | -- | +| int32_t deviceId | Device ID.| diff --git a/en/application-dev/reference/apis-input-kit/capi-input-input-interceptoroptions.md b/en/application-dev/reference/apis-input-kit/capi-input-input-interceptoroptions.md new file mode 100644 index 00000000000..4a73c86f0b8 --- /dev/null +++ b/en/application-dev/reference/apis-input-kit/capi-input-input-interceptoroptions.md @@ -0,0 +1,11 @@ +# Input_InterceptorOptions + +## **Overview** + +Defines event interception options. + +**Since**: 12 + +**Related module**: [input](capi-input.md) + +**Header file**: [oh_input_manager.h](capi-oh-input-manager-h.md) diff --git a/en/application-dev/reference/apis-input-kit/capi-input-input-keyevent.md b/en/application-dev/reference/apis-input-kit/capi-input-input-keyevent.md new file mode 100644 index 00000000000..84690fd2499 --- /dev/null +++ b/en/application-dev/reference/apis-input-kit/capi-input-input-keyevent.md @@ -0,0 +1,11 @@ +# Input_KeyEvent + +## **Overview** + +Defines the key event to be injected. + +**Since**: 12 + +**Related module**: [input](capi-input.md) + +**Header file**: [oh_input_manager.h](capi-oh-input-manager-h.md) diff --git a/en/application-dev/reference/apis-input-kit/capi-input-input-keystate.md b/en/application-dev/reference/apis-input-kit/capi-input-input-keystate.md new file mode 100644 index 00000000000..ced334b2b6d --- /dev/null +++ b/en/application-dev/reference/apis-input-kit/capi-input-input-keystate.md @@ -0,0 +1,11 @@ +# Input_KeyState + +## **Overview** + +Defines key information, which identifies a key pressing behavior. For example, the Ctrl key information contains the key value and key type. + +**Since**: 12 + +**Related module**: [input](capi-input.md) + +**Header file**: [oh_input_manager.h](capi-oh-input-manager-h.md) diff --git a/en/application-dev/reference/apis-input-kit/capi-input-input-mouseevent.md b/en/application-dev/reference/apis-input-kit/capi-input-input-mouseevent.md new file mode 100644 index 00000000000..92cecfb6083 --- /dev/null +++ b/en/application-dev/reference/apis-input-kit/capi-input-input-mouseevent.md @@ -0,0 +1,11 @@ +# Input_MouseEvent + +## Overview + +Defines the mouse event to be injected. + +**Since**: 12 + +**Related module**: [input](capi-input.md) + +**Header file**: [oh_input_manager.h](capi-oh-input-manager-h.md) diff --git a/en/application-dev/reference/apis-input-kit/capi-input-input-touchevent.md b/en/application-dev/reference/apis-input-kit/capi-input-input-touchevent.md new file mode 100644 index 00000000000..f6d87483d68 --- /dev/null +++ b/en/application-dev/reference/apis-input-kit/capi-input-input-touchevent.md @@ -0,0 +1,11 @@ +# Input_TouchEvent + +## Overview + +Defines the touch event to be injected. + +**Since**: 12 + +**Related module**: [input](capi-input.md) + +**Header file**: [oh_input_manager.h](capi-oh-input-manager-h.md) diff --git a/en/application-dev/reference/apis-multimodalawareness-kit/errorcode-userStatus.md b/en/application-dev/reference/apis-multimodalawareness-kit/errorcode-userStatus.md new file mode 100644 index 00000000000..73d961951dd --- /dev/null +++ b/en/application-dev/reference/apis-multimodalawareness-kit/errorcode-userStatus.md @@ -0,0 +1,75 @@ +# User Awareness Error Code + +> **NOTE** +> +> This topic describes only module-specific error codes. For details about universal error codes, see [Universal Error Codes](../errorcode-universal.md). + +## 33900001 Service Exception + +**Error Message** + +Service exception. Possible causes: +
 1. System error, such as a null pointer and container-related exception. +
 2. Node-API invocation exception, such as invalid Node-API status. + +**Description** + +This error code is reported if a service exception occurs when the **on** or **off** API of the userStatus module is called. + +**Possible Causes** + +The service status is abnormal. + +**Solution** + +1. Retry the operation at a specified interval (for example, 1s) or at an exponential increase interval. +2. If the operation fails for three consecutive times, stop the retry. During this period, you can preferentially obtain the device list to check for device availability. + + + +## 33900002 Subscription Failed + +**Error Message** + +Subscription failed. Possible causes: +
 1. Callback registration failed. +
 2. Failed to bind the native object to the JS wrapper. +
 3. Node-API invocation exception, such as invalid Node-API status. +
 4. IPC request exception. + +**Description** + +This error code is reported if subscription fails when the **on** API of the userStatus module is called. + +**Possible Causes** + +Subscription to status change events has failed. + +**Solution** + +1. Retry the operation at a specified interval (for example, 1s) or at an exponential increase interval. +2. If the operation fails for three consecutive times, stop the retry. + + + +## 33500003 Unsubscription Failed + +**Error Message** + +Unsubscription failed. Possible causes: +
 1. Callback failure. +
 2. Node-API invocation exception, such as invalid Node-API status. +
 3. IPC request exception. + +**Description** + +This error code is reported if unsubscription fails when the **off** API of the userStatus module is called. + +**Possible Causes** + +Unsubscription from status change events has failed. + +**Solution** + +1. Retry the operation at a specified interval (for example, 1s) or at an exponential increase interval. +2. If the operation fails for three consecutive times, stop the retry. diff --git a/en/application-dev/reference/apis-multimodalawareness-kit/js-apis-awareness-userStatus.md b/en/application-dev/reference/apis-multimodalawareness-kit/js-apis-awareness-userStatus.md new file mode 100644 index 00000000000..111c4a9404b --- /dev/null +++ b/en/application-dev/reference/apis-multimodalawareness-kit/js-apis-awareness-userStatus.md @@ -0,0 +1,121 @@ +# @ohos.multimodalawareness.userStatus (User Status Awareness) + +The UserStatus module, designed for user state awareness, empowers the system to perceive specific conditions of users, such as determining their age group. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 20. Newly added APIs will be marked with a superscript to indicate their earliest API version. + + +## Modules to Import + +```ts +import { userStatus } from '@kit.MultimodalAwarenessKit'; +``` + +## UserAgeGroup + +Enumerates the user age groups, for example, child or adult. + +**System capability**: SystemCapability.MultimodalAwareness.UserStatus + +| Name | Value | Description | +| ------------------- | ---- | ---------------------- | +| OTHERS | 0 | Adult.| +| CHILD | 1 | Child.| + +## UserClassification + +Defines the user age group detection result. + +**System capability**: SystemCapability.MultimodalAwareness.UserStatus + +| Name | Type | Description | +| ------------------- | ---- | ---------------------- | +| ageGroup | [UserAgeGroup](#useragegroup) | User age group, for example, child or adult.| +| confidence | float | Confidence of the detection result. The value is a floating point number ranging from 0 to 1. A larger value indicates a higher confidence.| + + +## userStatus.on('userAgeGroupDetected') + + on(type: 'userAgeGroupDetected', callback: Callback<userclassification>): void; + +Enables the age group detection function. + +When the function is enabled, the application can recommend content based on the age group detection result. + +**System capability**: SystemCapability.MultimodalAwareness.UserStatus + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------------------- | ---- |------------------------------------------------------------ | +| type | string | Yes | Event type. The value **userAgeGroupDetected** indicates the event of enabling age group detection.| +| callback | Callback<[UserClassification](#userclassification)> | Yes | Callback used to return the detection result.| + +**Error codes** + +For details about the error codes, see [User Status Awareness Error Codes](errorcode-userStatus.md) and [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message | +| -------- | ------------------------------------------------------------ | +| 801 | Capability not supported. Function can not work correctly due to limited device capabilities. | +| 33900001 | Service exception. Possible causes:
1. System error, such as a null pointer and container-related exception.
2. Node-API invocation exception, such as invalid Node-API status.| +| 33900002 | Subscription failed. Possible causes:
1. Callback registration failure.
2. Failed to bind native object to js wrapper.
3. N-API invocation exception, invalid N-API status.
4. IPC request exception. | + +**Example** + +```ts +import { BusinessError } from '@kit.BasicServicesKit'; + +try { + userStatus.on('userAgeGroupDetected', (data: userStatus.UserClassification) => { + console.info('callback success, ageGroup:' + data.ageGroup + ", confidence:" + data.confidence); + }); + console.info("on succeeded"); +} catch (err) { + let error = err as BusinessError; + console.error("Failed on and err code is " + error.code); +} +``` + + + +## userStatus.off('userAgeGroupDetected') + +off(type: 'userAgeGroupDetected', callback?: Callback<UserClassification>): void; + +Disables the age group detection function. + +**System capability**: SystemCapability.MultimodalAwareness.UserStatus + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------------------- | ---- | ------------------------------------------------------------ | +| type | string | Yes | Event type. The value **userAgeGroupDetected** indicates the event of enabling age group detection.| +| callback | Callback<[UserClassification](#userclassification)> | No | Callback used to return the detection result.| + +**Error codes** + +For details about the error codes, see [User Status Awareness Error Codes](errorcode-userStatus.md) and [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message | +| -------- | ------------------------------------------------------------ | +| 801 | Capability not supported. Function can not work correctly due to limited device capabilities. | +| 33900001 | Service exception. Possible causes:
1. System error, such as a null pointer and container-related exception.
2. Node-API invocation exception, such as invalid Node-API status. | +| 33900003 | Unsubscription failed. Possible causes:
1. Callback failure.
2. Node-API invocation exception, such as invalid Node-API status.
3. IPC request exception.| + +**Example** + +```ts +import { BusinessError } from '@kit.BasicServicesKit'; + +try { + userStatus.off('userAgeGroupDetected'); + console.info("off succeeded"); +} catch (err) { + let error = err as BusinessError; + console.error("Failed off and err code is " + error.code); +} +``` diff --git a/en/application-dev/reference/apis-network-kit/errorcode-kernel.md b/en/application-dev/reference/apis-network-kit/errorcode-kernel.md new file mode 100644 index 00000000000..227097d14f9 --- /dev/null +++ b/en/application-dev/reference/apis-network-kit/errorcode-kernel.md @@ -0,0 +1,69 @@ +# Kernel Error Codes + +> **NOTE** +> +> The following lists only the kernel error codes and descriptions. + +| Error Code| Name| Description| +|-------|------|-----| +| 1 | EPERM | Operation not permitted | +| 2 | ENOENT | No such file or directory | +| 3 | ESRCH | No such process | +| 4 | EINTR | Interrupted system call | +| 5 | EIO | Input/output error | +| 6 | ENXIO | No such device or address | +| 7 | E2BIG | Argument list too long | +| 8 | ENOEXEC | Exec format error | +| 9 | EBADF | Bad file descriptor | +| 10 | ECHILD | No child processes | +| 11 | EAGAIN | Try again | +| 12 | ENOMEM | Out of memory | +| 13 | EACCES | Permission denied | +| 14 | EFAULT | Bad address | +| 16 | EBUSY | Device or resource busy | +| 17 | EEXIST | File exists | +| 18 | EXDEV | Cross-device link | +| 19 | ENODEV | No such device | +| 20 | ENOTDIR | Not a directory | +| 21 | EISDIR | Is a directory | +| 22 | EINVAL | Invalid argument | +| 23 | ENFILE | File table overflow | +| 24 | EMFILE | Too many open files | +| 25 | ENOTTY | Inappropriate ioctl for device | +| 26 | ETXTBSY | Text file busy | +| 96 | EPFNOSUPPORT | Protocol family not supported | +| 97 | EAFNOSUPPORT | Address family not supported by protocol | +| 98 | EADDRINUSE | Address already in use | +| 99 | EADDRNOTAVAIL | Cannot assign requested address | +| 100 | ENETDOWN | Network is down | +| 101 | ENETUNREACH | Network is unreachable | +| 102 | ENETRESET | Network dropped connection because of reset | +| 103 | ECONNABORTED | Software caused connection abort | +| 104 | ECONNRESET | Connection reset by peer | +| 105 | ENOBUFS | No buffer space available | +| 106 | EISCONN | Socket is already connected | +| 107 | ENOTCONN | Socket is not connected | +| 110 | ETIMEDOUT | Connection timed out | +| 111 | ECONNREFUSED | Connection refused | +| 112 | EHOSTDOWN | Host is down | +| 113 | EHOSTUNREACH | No route to host | +| 114 | EALREADY | Operation already in progress | +| 115 | EINPROGRESS | Operation now in progress | +| 116 | ESTALE | Stale file handle | +| 117 | EUCLEAN | Structure needs cleaning | +| 118 | ENOTNAM | Not a XENIX named type file | +| 119 | ENAVAIL | No XENIX semaphores available | +| 120 | EREMOTEIO | Is a named type file | +| 121 | EREMOTEIO | Remote I/O error | +| 122 | EDQUOT | Quota exceeded | +| 123 | ENOMEDIUM | No medium found | +| 124 | EMEDIUMTYPE | Wrong medium type | +| 125 | ECANCELED | Operation Canceled | +| 126 | ENOKEY | Required key not available | +| 127 | EKEYEXPIRED | Key has expired | +| 128 | EKEYREVOKED | Key has been revoked | +| 129 | EKEYREJECTED | Key was rejected by service | +| 130 | EOWNERDEAD | Owner died | +| 131 | ENOTRECOVERABLE | State not recoverable | +| 132 | ERFKILL | Operation not possible due to RF-kill | +| 133 | EHWPOISON | Memory page has hardware error | diff --git a/en/application-dev/reference/apis-sensor-service-kit/_sensor.md b/en/application-dev/reference/apis-sensor-service-kit/_sensor.md index 6a965a19b1c..78bcdb2cc1e 100644 --- a/en/application-dev/reference/apis-sensor-service-kit/_sensor.md +++ b/en/application-dev/reference/apis-sensor-service-kit/_sensor.md @@ -25,8 +25,8 @@ It also provides APIs to define common sensor attributes. | Name| Description| | -------- | -------- | -| [Sensor_Type](#sensor_type) | Defines an enum for sensor types. | -| [Sensor_Result](#sensor_result) | Defines an enum for sensor result codes. | +| [Sensor_Type](#sensor_type) | Enumerates the sensor types. | +| [Sensor_Result](#sensor_result) | Enumerates the sensor result codes. | | [Sensor_Accuracy](#sensor_accuracy) | Defines an enum for accuracy levels of data reported by a sensor.| | [Sensor_Info](#sensor_info) | Defines a struct for the sensor information. | | [Sensor_Event](#sensor_event) | Defines a struct for the sensor data information. | @@ -298,6 +298,38 @@ Creates a [Sensor_Subscriber](#sensor_subscriber) instance. Returns the pointer to the [Sensor_Subscriber](#sensor_subscriber) instances if the operation is successful; returns **NULL** otherwise. +**Example** + +For details about the development procedure, see [Sensor Development](../../device/sensor/sensor-guidelines-capi.md). + + ```c + #include "sensors/oh_sensor.h" + #include "napi/native_api.h" + #include "hilog/log.h" + + const int SENSOR_LOG_DOMAIN = 0xD002700; + const char *TAG = "[Sensor]"; + + static napi_value CreateSubscriber(napi_env env, napi_callback_info info) { + Sensor_Result ret; + // Create a Sensor_Subscriber instance. + Sensor_Subscriber *subscriberTemp = OH_Sensor_CreateSubscriber(); + if (subscriberTemp == nullptr) { + OH_LOG_Print(LOG_APP, LOG_ERROR, SENSOR_LOG_DOMAIN, TAG, "OH_Sensor_CreateSubscriber failed"); + ret = SENSOR_SERVICE_EXCEPTION; + } else { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_Sensor_CreateSubscriber successful"); + ret = SENSOR_SUCCESS; + } + // Destroy the Sensor_Subscriber instance when it is no longer needed. + if (subscriberTemp != nullptr) { + OH_Sensor_DestroySubscriber(subscriberTemp); + } + napi_value result; + napi_create_int32(env, ret, &result); + return result; + } + ``` ### OH_Sensor_CreateSubscriptionAttribute() @@ -314,6 +346,38 @@ Creates a [Sensor_SubscriptionAttribute](#sensor_subscriptionattribute) instance Returns the pointer to the [Sensor_SubscriptionAttribute](#sensor_subscriptionattribute) instances if the operation is successful; returns **NULL** otherwise. +**Example** + +For details about the development procedure, see [Sensor Development](../../device/sensor/sensor-guidelines-capi.md). + + ```c + #include "sensors/oh_sensor.h" + #include "napi/native_api.h" + #include "hilog/log.h" + + const int SENSOR_LOG_DOMAIN = 0xD002700; + const char *TAG = "[Sensor]"; + + static napi_value CreateSubscriptionAttribute(napi_env env, napi_callback_info info) { + Sensor_Result ret; + // Create a Sensor_SubscriptionAttribute instance. + Sensor_SubscriptionAttribute *attr = OH_Sensor_CreateSubscriptionAttribute(); + if (attr == nullptr) { + OH_LOG_Print(LOG_APP, LOG_ERROR, SENSOR_LOG_DOMAIN, TAG, "OH_Sensor_CreateSubscriptionAttribute failed"); + ret = SENSOR_SERVICE_EXCEPTION; + } else { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_Sensor_CreateSubscriptionAttribute successful"); + ret = SENSOR_SUCCESS; + } + // Destroy the Sensor_SubscriptionAttribute instance when it is no longer needed. + if (attr != nullptr) { + OH_Sensor_DestroySubscriptionAttribute(attr); + } + napi_value result; + napi_create_int32(env, ret, &result); + return result; + } + ``` ### OH_Sensor_CreateSubscriptionId() @@ -330,6 +394,38 @@ Creates a [Sensor_SubscriptionId](#sensor_subscriptionid) instance. Returns the pointer to the [Sensor_SubscriptionId](#sensor_subscriptionid) instances if the operation is successful; returns **NULL** otherwise. +**Example** + +For details about the development procedure, see [Sensor Development](../../device/sensor/sensor-guidelines-capi.md). + + ```c + #include "sensors/oh_sensor.h" + #include "napi/native_api.h" + #include "hilog/log.h" + + const int SENSOR_LOG_DOMAIN = 0xD002700; + const char *TAG = "[Sensor]"; + + static napi_value CreateSubscriptionId(napi_env env, napi_callback_info info) { + Sensor_Result ret; + // Create a Sensor_SubscriptionId instance. + Sensor_SubscriptionId *id = OH_Sensor_CreateSubscriptionId(); + if (id == nullptr) { + OH_LOG_Print(LOG_APP, LOG_ERROR, SENSOR_LOG_DOMAIN, TAG, "OH_Sensor_CreateSubscriptionId failed"); + ret = SENSOR_SERVICE_EXCEPTION; + } else { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_Sensor_CreateSubscriptionId successful"); + ret = SENSOR_SUCCESS; + } + // Destroy the Sensor_SubscriptionId instance when it is no longer needed. + if (id != nullptr) { + OH_Sensor_DestroySubscriptionId(id); + } + napi_value result; + napi_create_int32(env, ret, &result); + return result; + } + ``` ### OH_Sensor_DestroyInfos() @@ -375,6 +471,33 @@ Destroys a [Sensor_Subscriber](#sensor_subscriber) instance and reclaims memory. Returns **SENSOR_SUCCESS** if the operation is successful; returns an error code defined in [Sensor_Result](#sensor_result) otherwise. +**Example** + +For details about the development procedure, see [Sensor Development](../../device/sensor/sensor-guidelines-capi.md). + + ```c + #include "sensors/oh_sensor.h" + #include "napi/native_api.h" + #include "hilog/log.h" + + const int SENSOR_LOG_DOMAIN = 0xD002700; + const char *TAG = "[Sensor]"; + + static napi_value DestroySubscriber(napi_env env, napi_callback_info info) { + // Create a Sensor_Subscriber instance. + Sensor_Subscriber *subscriberTemp = OH_Sensor_CreateSubscriber(); + // Destroy the Sensor_Subscriber instance when it is no longer needed. + int32_t ret = OH_Sensor_DestroySubscriber(subscriberTemp); + if (ret != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_ERROR, SENSOR_LOG_DOMAIN, TAG, "OH_Sensor_DestroySubscriber failed"); + } else { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_Sensor_DestroySubscriber successful"); + } + napi_value result; + napi_create_int32(env, ret, &result); + return result; + } + ``` ### OH_Sensor_DestroySubscriptionAttribute() @@ -397,6 +520,33 @@ Destroys a [Sensor_SubscriptionAttribute](#sensor_subscriptionattribute) instanc Returns **SENSOR_SUCCESS** if the operation is successful; returns an error code defined in [Sensor_Result](#sensor_result) otherwise. +**Example** + +For details about the development procedure, see [Sensor Development](../../device/sensor/sensor-guidelines-capi.md). + + ```c + #include "sensors/oh_sensor.h" + #include "napi/native_api.h" + #include "hilog/log.h" + + const int SENSOR_LOG_DOMAIN = 0xD002700; + const char *TAG = "[Sensor]"; + + static napi_value DestroySubscriptionAttribute(napi_env env, napi_callback_info info) { + // Create a Sensor_SubscriptionAttribute instance. + Sensor_SubscriptionAttribute *attr = OH_Sensor_CreateSubscriptionAttribute(); + // Destroy the Sensor_SubscriptionAttribute instance when it is no longer needed. + int32_t ret = OH_Sensor_DestroySubscriptionAttribute(attr); + if (ret != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_ERROR, SENSOR_LOG_DOMAIN, TAG, "OH_Sensor_DestroySubscriptionAttribute failed"); + } else { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_Sensor_DestroySubscriptionAttribute successful"); + } + napi_value result; + napi_create_int32(env, ret, &result); + return result; + } + ``` ### OH_Sensor_DestroySubscriptionId() @@ -419,6 +569,33 @@ Destroys a [Sensor_SubscriptionId](#sensor_subscriptionid) instance and reclaims Returns **SENSOR_SUCCESS** if the operation is successful; returns an error code defined in [Sensor_Result](#sensor_result) otherwise. +**Example** + +For details about the development procedure, see [Sensor Development](../../device/sensor/sensor-guidelines-capi.md). + + ```c + #include "sensors/oh_sensor.h" + #include "napi/native_api.h" + #include "hilog/log.h" + + const int SENSOR_LOG_DOMAIN = 0xD002700; + const char *TAG = "[Sensor]"; + + static napi_value DestroySubscriptionId(napi_env env, napi_callback_info info) { + // Create a Sensor_SubscriptionId instance. + Sensor_SubscriptionId *id = OH_Sensor_CreateSubscriptionId(); + // Destroy the Sensor_SubscriptionId instance when it is no longer needed. + int32_t ret = OH_Sensor_DestroySubscriptionId(id); + if (ret != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_ERROR, SENSOR_LOG_DOMAIN, TAG, "OH_Sensor_DestroySubscriptionId failed"); + } else { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_Sensor_DestroySubscriptionId successful"); + } + napi_value result; + napi_create_int32(env, ret, &result); + return result; + } + ``` ### OH_Sensor_GetInfos() @@ -470,6 +647,120 @@ Returns **SENSOR_SUCCESS** if the operation is successful; returns an error code ohos.permission.ACCELEROMETER, ohos.permission.GYROSCOPE, ohos.permission.ACTIVITY_MOTION, or ohos.permission.READ_HEALTH_DATA +**Example** + +For details about the development procedure, see [Sensor Development](../../device/sensor/sensor-guidelines-capi.md). + + ```c + #include "sensors/oh_sensor.h" + #include "napi/native_api.h" + #include "hilog/log.h" + #include + + const int SENSOR_LOG_DOMAIN = 0xD002700; + const char *TAG = "[Sensor]"; + constexpr Sensor_Type SENSOR_ID { SENSOR_TYPE_ACCELEROMETER }; + constexpr uint32_t SENSOR_NAME_LENGTH_MAX = 64; + constexpr int64_t SENSOR_SAMPLE_PERIOD = 200000000; + constexpr int32_t SLEEP_TIME_MS = 1000; + constexpr int64_t INVALID_VALUE = -1; + constexpr float INVALID_RESOLUTION = -1.0F; + Sensor_Subscriber *g_user = nullptr; + + // Define the callback. + void SensorDataCallbackImpl(Sensor_Event *event) { + if (event == nullptr) { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "event is null"); + return; + } + int64_t timestamp = INVALID_VALUE; + // Obtain the timestamp of sensor data. + int32_t ret = OH_SensorEvent_GetTimestamp(event, ×tamp); + if (ret != SENSOR_SUCCESS) { + return; + } + Sensor_Type sensorType; + // Obtain the sensor type. + ret = OH_SensorEvent_GetType(event, &sensorType); + if (ret != SENSOR_SUCCESS) { + return; + } + Sensor_Accuracy accuracy = SENSOR_ACCURACY_UNRELIABLE; + // Obtain the accuracy of sensor data. + ret = OH_SensorEvent_GetAccuracy(event, &accuracy); + if (ret != SENSOR_SUCCESS) { + return; + } + float *data = nullptr; + uint32_t length = 0; + // Obtain sensor data. + ret = OH_SensorEvent_GetData(event, &data, &length); + if (ret != SENSOR_SUCCESS) { + return; + } + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "sensorType:%{public}d, dataLen:%{public}d, accuracy:%{public}d", sensorType, length, accuracy); + for (uint32_t i = 0; i < length; ++i) { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "accData[%{public}d]:%{public}f", i, data[i]); + } + } + + static napi_value Subscribe(napi_env env, napi_callback_info info) { + // Create a Sensor_Subscriber instance. + g_user = OH_Sensor_CreateSubscriber(); + // Set the callback used to return sensor data. + int32_t ret = OH_SensorSubscriber_SetCallback(g_user, SensorDataCallbackImpl); + if (ret != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_SensorSubscriber_SetCallback failed"); + return nullptr; + } + // Create a Sensor_SubscriptionId instance. + Sensor_SubscriptionId *id = OH_Sensor_CreateSubscriptionId(); + // Set the sensor type. For example, if you use SENSOR_TYPE_ACCELEROMETER, you need to request the ohos.permission.ACCELEROMETER permission. + // Configure the required permission as instructed in step 2 in the Sensor Development. + ret = OH_SensorSubscriptionId_SetType(id, SENSOR_ID); + if (ret != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_SensorSubscriptionId_SetType failed"); + return nullptr; + } + // Create a **Sensor_SubscriptionAttribute** instance. + Sensor_SubscriptionAttribute *attr = OH_Sensor_CreateSubscriptionAttribute(); + // Set the sensor data reporting interval. + ret = OH_SensorSubscriptionAttribute_SetSamplingInterval(attr, SENSOR_SAMPLE_PERIOD); + if (ret != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_SensorSubscriptionAttribute_SetSamplingInterval failed"); + return nullptr; + } + // Subscribe to sensor data. + ret = OH_Sensor_Subscribe(id, attr, g_user); + if (ret != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_Sensor_Subscribe failed"); + return nullptr; + } + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_Sensor_Subscribe successful"); + std::this_thread::sleep_for(std::chrono::milliseconds(SLEEP_TIME_MS)); + // Unsubscribe from sensor data. + ret = OH_Sensor_Unsubscribe(id, g_user); + if (ret != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_Sensor_Unsubscribe failed"); + return nullptr; + } + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_Sensor_Unsubscribe successful"); + if (id != nullptr) { + // Destroy the Sensor_SubscriptionId instance. + OH_Sensor_DestroySubscriptionId(id); + } + if (attr != nullptr) { + // Destroy the Sensor_SubscriptionAttribute instance. + OH_Sensor_DestroySubscriptionAttribute(attr); + } + if (g_user != nullptr) { + // Destroy the Sensor_Subscriber instance and reclaim memory. + OH_Sensor_DestroySubscriber(g_user); + g_user = nullptr; + } + return nullptr; + } + ``` ### OH_Sensor_Unsubscribe() @@ -497,6 +788,120 @@ Returns **SENSOR_SUCCESS** if the operation is successful; returns an error code ohos.permission.ACCELEROMETER, ohos.permission.GYROSCOPE, ohos.permission.ACTIVITY_MOTION, or ohos.permission.READ_HEALTH_DATA +**Example** + +For details about the development procedure, see [Sensor Development](../../device/sensor/sensor-guidelines-capi.md). + + ```c + #include "sensors/oh_sensor.h" + #include "napi/native_api.h" + #include "hilog/log.h" + #include + + const int SENSOR_LOG_DOMAIN = 0xD002700; + const char *TAG = "[Sensor]"; + constexpr Sensor_Type SENSOR_ID { SENSOR_TYPE_ACCELEROMETER }; + constexpr uint32_t SENSOR_NAME_LENGTH_MAX = 64; + constexpr int64_t SENSOR_SAMPLE_PERIOD = 200000000; + constexpr int32_t SLEEP_TIME_MS = 1000; + constexpr int64_t INVALID_VALUE = -1; + constexpr float INVALID_RESOLUTION = -1.0F; + Sensor_Subscriber *g_user = nullptr; + + // Define the callback. + void SensorDataCallbackImpl(Sensor_Event *event) { + if (event == nullptr) { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "event is null"); + return; + } + int64_t timestamp = INVALID_VALUE; + // Obtain the timestamp of sensor data. + int32_t ret = OH_SensorEvent_GetTimestamp(event, ×tamp); + if (ret != SENSOR_SUCCESS) { + return; + } + Sensor_Type sensorType; + // Obtain the sensor type. + ret = OH_SensorEvent_GetType(event, &sensorType); + if (ret != SENSOR_SUCCESS) { + return; + } + Sensor_Accuracy accuracy = SENSOR_ACCURACY_UNRELIABLE; + // Obtain the accuracy of sensor data. + ret = OH_SensorEvent_GetAccuracy(event, &accuracy); + if (ret != SENSOR_SUCCESS) { + return; + } + float *data = nullptr; + uint32_t length = 0; + // Obtain sensor data. + ret = OH_SensorEvent_GetData(event, &data, &length); + if (ret != SENSOR_SUCCESS) { + return; + } + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "sensorType:%{public}d, dataLen:%{public}d, accuracy:%{public}d", sensorType, length, accuracy); + for (uint32_t i = 0; i < length; ++i) { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "accData[%{public}d]:%{public}f", i, data[i]); + } + } + + static napi_value Unsubscribe(napi_env env, napi_callback_info info) { + // Create a Sensor_Subscriber instance. + g_user = OH_Sensor_CreateSubscriber(); + // Set the callback used to return sensor data. + int32_t ret = OH_SensorSubscriber_SetCallback(g_user, SensorDataCallbackImpl); + if (ret != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_SensorSubscriber_SetCallback failed"); + return nullptr; + } + // Create a Sensor_SubscriptionId instance. + Sensor_SubscriptionId *id = OH_Sensor_CreateSubscriptionId(); + // Set the sensor type. For example, if you use SENSOR_TYPE_ACCELEROMETER, you need to request the ohos.permission.ACCELEROMETER permission. + // Configure the required permission as instructed in step 2 in the Sensor Development. + ret = OH_SensorSubscriptionId_SetType(id, SENSOR_ID); + if (ret != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_SensorSubscriptionId_SetType failed"); + return nullptr; + } + // Create a **Sensor_SubscriptionAttribute** instance. + Sensor_SubscriptionAttribute *attr = OH_Sensor_CreateSubscriptionAttribute(); + // Set the sensor data reporting interval. + ret = OH_SensorSubscriptionAttribute_SetSamplingInterval(attr, SENSOR_SAMPLE_PERIOD); + if (ret != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_SensorSubscriptionAttribute_SetSamplingInterval failed"); + return nullptr; + } + // Subscribe to sensor data. + ret = OH_Sensor_Subscribe(id, attr, g_user); + if (ret != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_Sensor_Subscribe failed"); + return nullptr; + } + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_Sensor_Subscribe successful"); + std::this_thread::sleep_for(std::chrono::milliseconds(SLEEP_TIME_MS)); + // Unsubscribe from sensor data. + ret = OH_Sensor_Unsubscribe(id, g_user); + if (ret != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_Sensor_Unsubscribe failed"); + return nullptr; + } + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_Sensor_Unsubscribe successful"); + if (id != nullptr) { + // Destroy the Sensor_SubscriptionId instance. + OH_Sensor_DestroySubscriptionId(id); + } + if (attr != nullptr) { + // Destroy the Sensor_SubscriptionAttribute instance. + OH_Sensor_DestroySubscriptionAttribute(attr); + } + if (g_user != nullptr) { + // Destroy the Sensor_Subscriber instance and reclaim memory. + OH_Sensor_DestroySubscriber(g_user); + g_user = nullptr; + } + return nullptr; + } + ``` ### OH_SensorEvent_GetAccuracy() @@ -574,6 +979,121 @@ Obtains sensor data. The data length and content depend on the sensor type. The Returns **SENSOR_SUCCESS** if the operation is successful; returns an error code defined in [Sensor_Result](#sensor_result) otherwise. +**Example** + +For details about the development procedure, see [Sensor Development](../../device/sensor/sensor-guidelines-capi.md). + + ```c + #include "sensors/oh_sensor.h" + #include "napi/native_api.h" + #include "hilog/log.h" + #include + + const int SENSOR_LOG_DOMAIN = 0xD002700; + const char *TAG = "[Sensor]"; + constexpr Sensor_Type SENSOR_ID { SENSOR_TYPE_ACCELEROMETER }; + constexpr uint32_t SENSOR_NAME_LENGTH_MAX = 64; + constexpr int64_t SENSOR_SAMPLE_PERIOD = 200000000; + constexpr int32_t SLEEP_TIME_MS = 1000; + constexpr int64_t INVALID_VALUE = -1; + constexpr float INVALID_RESOLUTION = -1.0F; + Sensor_Subscriber *g_user = nullptr; + + // Define the callback. + void SensorDataCallbackImpl(Sensor_Event *event) { + if (event == nullptr) { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "event is null"); + return; + } + int64_t timestamp = INVALID_VALUE; + // Obtain the timestamp of sensor data. + int32_t ret = OH_SensorEvent_GetTimestamp(event, ×tamp); + if (ret != SENSOR_SUCCESS) { + return; + } + Sensor_Type sensorType; + // Obtain the sensor type. + ret = OH_SensorEvent_GetType(event, &sensorType); + if (ret != SENSOR_SUCCESS) { + return; + } + Sensor_Accuracy accuracy = SENSOR_ACCURACY_UNRELIABLE; + // Obtain the accuracy of sensor data. + ret = OH_SensorEvent_GetAccuracy(event, &accuracy); + if (ret != SENSOR_SUCCESS) { + return; + } + float *data = nullptr; + uint32_t length = 0; + // Obtain sensor data. + ret = OH_SensorEvent_GetData(event, &data, &length); + if (ret != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_SensorEvent_GetData failed"); + return; + } + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_SensorEvent_GetData successful"); + for (uint32_t i = 0; i < length; ++i) { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "accData[%{public}d]:%{public}f", i, data[i]); + } + } + + static napi_value SensorEventGetData(napi_env env, napi_callback_info info) { + // Create a Sensor_Subscriber instance. + g_user = OH_Sensor_CreateSubscriber(); + // Set the callback used to return sensor data. + int32_t ret = OH_SensorSubscriber_SetCallback(g_user, SensorDataCallbackImpl); + if (ret != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_SensorSubscriber_SetCallback failed"); + return nullptr; + } + // Create a Sensor_SubscriptionId instance. + Sensor_SubscriptionId *id = OH_Sensor_CreateSubscriptionId(); + // Set the sensor type. For example, if you use SENSOR_TYPE_ACCELEROMETER, you need to request the ohos.permission.ACCELEROMETER permission. + // Configure the required permission as instructed in step 2 in the Sensor Development. + ret = OH_SensorSubscriptionId_SetType(id, SENSOR_ID); + if (ret != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_SensorSubscriptionId_SetType failed"); + return nullptr; + } + // Create a **Sensor_SubscriptionAttribute** instance. + Sensor_SubscriptionAttribute *attr = OH_Sensor_CreateSubscriptionAttribute(); + // Set the sensor data reporting interval. + ret = OH_SensorSubscriptionAttribute_SetSamplingInterval(attr, SENSOR_SAMPLE_PERIOD); + if (ret != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_SensorSubscriptionAttribute_SetSamplingInterval failed"); + return nullptr; + } + // Subscribe to sensor data. + ret = OH_Sensor_Subscribe(id, attr, g_user); + if (ret != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_Sensor_Subscribe failed"); + return nullptr; + } + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_Sensor_Subscribe successful"); + std::this_thread::sleep_for(std::chrono::milliseconds(SLEEP_TIME_MS)); + // Unsubscribe from sensor data. + ret = OH_Sensor_Unsubscribe(id, g_user); + if (ret != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_Sensor_Unsubscribe failed"); + return nullptr; + } + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_Sensor_Unsubscribe successful"); + if (id != nullptr) { + // Destroy the Sensor_SubscriptionId instance. + OH_Sensor_DestroySubscriptionId(id); + } + if (attr != nullptr) { + // Destroy the Sensor_SubscriptionAttribute instance. + OH_Sensor_DestroySubscriptionAttribute(attr); + } + if (g_user != nullptr) { + // Destroy the Sensor_Subscriber instance and reclaim memory. + OH_Sensor_DestroySubscriber(g_user); + g_user = nullptr; + } + return nullptr; + } + ``` ### OH_SensorEvent_GetTimestamp() @@ -806,6 +1326,73 @@ Sets a callback function to report sensor data. Returns **SENSOR_SUCCESS** if the operation is successful; returns an error code defined in [Sensor_Result](#sensor_result) otherwise. +**Example** + +For details about the development procedure, see [Sensor Development](../../device/sensor/sensor-guidelines-capi.md). + + ```c + #include "sensors/oh_sensor.h" + #include "napi/native_api.h" + #include "hilog/log.h" + + const int SENSOR_LOG_DOMAIN = 0xD002700; + const char *TAG = "[Sensor]"; + constexpr int64_t INVALID_VALUE = -1; + + void SensorDataCallbackImpl(Sensor_Event *event) { + if (event == nullptr) { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "event is null"); + return; + } + int64_t timestamp = INVALID_VALUE; + // Obtain the timestamp of sensor data. + int32_t ret = OH_SensorEvent_GetTimestamp(event, ×tamp); + if (ret != SENSOR_SUCCESS) { + return; + } + Sensor_Type sensorType; + // Obtain the sensor type. + ret = OH_SensorEvent_GetType(event, &sensorType); + if (ret != SENSOR_SUCCESS) { + return; + } + Sensor_Accuracy accuracy = SENSOR_ACCURACY_UNRELIABLE; + // Obtain the accuracy of sensor data. + ret = OH_SensorEvent_GetAccuracy(event, &accuracy); + if (ret != SENSOR_SUCCESS) { + return; + } + float *data = nullptr; + uint32_t length = 0; + // Obtain sensor data. + ret = OH_SensorEvent_GetData(event, &data, &length); + if (ret != SENSOR_SUCCESS) { + return; + } + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "sensorType:%{public}d, dataLen:%{public}d, accuracy:%{public}d", sensorType, length, accuracy); + for (uint32_t i = 0; i < length; ++i) { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "data[%{public}d]:%{public}f", i, data[i]); + } + } + + static napi_value SensorSubscriberSetCallback(napi_env env, napi_callback_info info) { + // Create a Sensor_Subscriber instance. + Sensor_Subscriber *subscriberTemp = OH_Sensor_CreateSubscriber(); + int32_t ret = OH_SensorSubscriber_SetCallback(subscriberTemp, SensorDataCallbackImpl); + if (ret != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_ERROR, SENSOR_LOG_DOMAIN, TAG, "OH_SensorSubscriber_SetCallback failed"); + } else { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_SensorSubscriber_SetCallback successful"); + } + // Destroy the Sensor_Subscriber instance when it is no longer needed. + if (subscriberTemp != nullptr) { + OH_Sensor_DestroySubscriber(subscriberTemp); + } + napi_value result; + napi_create_int32(env, ret, &result); + return result; + } + ``` ### OH_SensorSubscriptionAttribute_GetSamplingInterval() @@ -852,6 +1439,37 @@ Sets the interval for reporting sensor data. Returns **SENSOR_SUCCESS** if the operation is successful; returns an error code defined in [Sensor_Result](#sensor_result) otherwise. +**Example** + +For details about the development procedure, see [Sensor Development](../../device/sensor/sensor-guidelines-capi.md). + + ```c + #include "sensors/oh_sensor.h" + #include "napi/native_api.h" + #include "hilog/log.h" + + const int SENSOR_LOG_DOMAIN = 0xD002700; + const char *TAG = "[Sensor]"; + + static napi_value SensorSubscriptionAttributeSetSamplingInterval(napi_env env, napi_callback_info info) { + // Create a **Sensor_SubscriptionAttribute** instance. + Sensor_SubscriptionAttribute *attr = OH_Sensor_CreateSubscriptionAttribute(); + int64_t sensorSamplePeriod = 200000000; + int32_t ret = OH_SensorSubscriptionAttribute_SetSamplingInterval(attr, sensorSamplePeriod); + if (ret != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_ERROR, SENSOR_LOG_DOMAIN, TAG, "OH_SensorSubscriptionAttribute_SetSamplingInterval failed"); + } else { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_SensorSubscriptionAttribute_SetSamplingInterval successful"); + } + // Destroy the Sensor_SubscriptionAttribute instance when it is no longer needed. + if (attr != nullptr) { + OH_Sensor_DestroySubscriptionAttribute(attr); + } + napi_value result; + napi_create_int32(env, ret, &result); + return result; + } + ``` ### OH_SensorSubscriptionId_GetType() @@ -897,3 +1515,35 @@ Sets the sensor type. **Returns** Returns **SENSOR_SUCCESS** if the operation is successful; returns an error code defined in [Sensor_Result](#sensor_result) otherwise. + +**Example** + +For details about the development procedure, see [Sensor Development](../../device/sensor/sensor-guidelines-capi.md). + + ```c + #include "sensors/oh_sensor.h" + #include "napi/native_api.h" + #include "hilog/log.h" + + const int SENSOR_LOG_DOMAIN = 0xD002700; + const char *TAG = "[Sensor]"; + + static napi_value SensorSubscriptionIdSetType(napi_env env, napi_callback_info info) { + // Create a Sensor_SubscriptionId instance. + Sensor_SubscriptionId *id = OH_Sensor_CreateSubscriptionId(); + Sensor_Type sensorId { SENSOR_TYPE_ACCELEROMETER }; + int32_t ret = OH_SensorSubscriptionId_SetType(id, sensorId); + if (ret != SENSOR_SUCCESS) { + OH_LOG_Print(LOG_APP, LOG_ERROR, SENSOR_LOG_DOMAIN, TAG, "OH_SensorSubscriptionId_SetType failed"); + } else { + OH_LOG_Print(LOG_APP, LOG_INFO, SENSOR_LOG_DOMAIN, TAG, "OH_SensorSubscriptionId_SetType successful"); + } + // Destroy the Sensor_SubscriptionId instance when it is no longer needed. + if (id != nullptr) { + OH_Sensor_DestroySubscriptionId(id); + } + napi_value result; + napi_create_int32(env, ret, &result); + return result; + } + ``` diff --git a/en/application-dev/reference/apis-sensor-service-kit/errorcode-sensor.md b/en/application-dev/reference/apis-sensor-service-kit/errorcode-sensor.md index 4612ba8e5b4..6c68751359c 100644 --- a/en/application-dev/reference/apis-sensor-service-kit/errorcode-sensor.md +++ b/en/application-dev/reference/apis-sensor-service-kit/errorcode-sensor.md @@ -8,7 +8,7 @@ **Error Message** -Service exception. +Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. **Description** diff --git a/en/application-dev/reference/apis-sensor-service-kit/js-apis-sensor-sys.md b/en/application-dev/reference/apis-sensor-service-kit/js-apis-sensor-sys.md index df5a162b15f..44cef114919 100644 --- a/en/application-dev/reference/apis-sensor-service-kit/js-apis-sensor-sys.md +++ b/en/application-dev/reference/apis-sensor-service-kit/js-apis-sensor-sys.md @@ -43,7 +43,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | -------- | ------------------------------------------------------------ | | 202 | Permission check failed. A non-system application uses the system API. | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -91,7 +91,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | -------- | ------------------------------------------------------------ | | 202 | Permission check failed. A non-system application uses the system API. | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -126,10 +126,10 @@ Unsubscribes from data of the color sensor. **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ | -| type | [SensorId](#sensorid9).COLOR | Yes | Sensor type. The value is fixed at **SensorId.COLOR**. | -| callback | Callback<[ColorResponse](#colorresponse10)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| +| Name | Type | Mandatory| Description | +| -------- |--------------------------------------------------------| ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).COLOR | Yes | Sensor type. The value is fixed at **SensorId.COLOR**. | +| callback | Callback<[ColorResponse](#colorresponse10)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| **Error codes** @@ -167,6 +167,84 @@ try { } ``` +### COLOR19+ + +off(type: SensorId.COLOR, sensorInfoParam?: SensorInfoParam, callback?: Callback<ColorResponse>): void + +Unsubscribes from data of the color sensor. + +**System capability**: SystemCapability.Sensors.Sensor + +**System API**: This is a system API. + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- |--------------------------------------------------------| ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).COLOR | Yes | Sensor type. The value is fixed at **SensorId.COLOR**. | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | No| Sensor parameters, including **deviceId** and **sensorIndex**.| +| callback | Callback<[ColorResponse](#colorresponse10)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message | +| -------- | ------------------------------------------------------------ | +| 202 | Permission check failed. A non-system application uses the system API. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**Example** + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// Sensor callback +const sensorCallback = (response: sensor.ColorResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// Sensor type +const sensorType = sensor.SensorId.COLOR; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // Query all sensors. + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // Obtain the target sensor based on the actual service logic. + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // Subscribe to sensor events. + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + ### SAR10+ off(type: SensorId.SAR, callback?: Callback<SarResponse>): void @@ -220,6 +298,84 @@ try { } ``` +### SAR19+ + +off(type: SensorId.SAR, sensorInfoParam?: SensorInfoParam, callback?: Callback<SarResponse>): void + +Unsubscribes from data of the SAR sensor. + +**System capability**: SystemCapability.Sensors.Sensor + +**System API**: This is a system API. + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).SAR | Yes | Sensor type. The value is fixed at **SensorId.SAR**. | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | No| Sensor parameters, including **deviceId** and **sensorIndex**.| +| callback | Callback<[SarResponse](#sarresponse10)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message | +| -------- |-----------------------------------------------------------------------------------------------------------------------------------------| +| 202 | Permission check failed. A non-system application uses the system API. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**Example** + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// Sensor callback +const sensorCallback = (response: sensor.SarResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// Sensor type +const sensorType = sensor.SensorId.SAR; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // Query all sensors. + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // Obtain the target sensor based on the actual service logic. + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // Subscribe to sensor events. + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + ## SensorId9+ Enumerates the sensor types. @@ -240,7 +396,7 @@ Describes the color sensor data. It extends from [Response](js-apis-sensor.md#re **System API**: This is a system API. -| Name | Type | Readable| Writable| Description | +| Name | Type | Read-Only| Optional| Description | | ---------------- | ------ | ---- | ---- | ----------------------------- | | lightIntensity | number | Yes | Yes | Intensity of light, in lux.| | colorTemperature | number | Yes | Yes | Color temperature, in Kelvin. | @@ -254,6 +410,19 @@ Describes the SAR sensor data. It extends from [Response](js-apis-sensor.md#resp **System API**: This is a system API. -| Name | Type | Readable| Writable| Description | +| Name | Type | Read-Only| Optional| Description | | --------------- | ------ | ---- | ---- | ------------------------------- | | absorptionRatio | number | Yes | Yes | Absorption ratio, in W/kg.| + + +## SensorInfoParam19+ + +Defines sensor parameters. + +**System capability**: SystemCapability.Sensors.Sensor + + +| Name| Type | Mandatory| Description | +| ------ | ---------------------- | ---- |-------------------------| +| deviceId | number | No | Device ID. The default value is **-1**, which indicates the local device. | +| sensorIndex | number | No | Sensor index. The default value is **0**, which indicates the default sensor on the device.| diff --git a/en/application-dev/reference/apis-sensor-service-kit/js-apis-sensor.md b/en/application-dev/reference/apis-sensor-service-kit/js-apis-sensor.md index b2d6d6fe099..bfdfbd3f1ab 100644 --- a/en/application-dev/reference/apis-sensor-service-kit/js-apis-sensor.md +++ b/en/application-dev/reference/apis-sensor-service-kit/js-apis-sensor.md @@ -42,7 +42,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | -------- | ------------------------------------------------------------ | | 201 | Permission denied. | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -91,7 +91,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | -------- | ------------------------------------------------------------ | | 201 | Permission denied. | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -140,7 +140,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -184,7 +184,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -228,7 +228,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -272,7 +272,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -323,7 +323,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | -------- | ------------------------------------------------------------ | | 201 | Permission denied. | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -373,7 +373,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | -------- | ------------------------------------------------------------ | | 201 | Permission denied. | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -423,7 +423,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -471,7 +471,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | -------- | ------------------------------------------------------------ | | 201 | Permission denied. | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -515,7 +515,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -563,7 +563,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | -------- | ------------------------------------------------------------ | | 201 | Permission denied. | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -609,7 +609,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -655,7 +655,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -687,6 +687,10 @@ on(type: SensorId.ORIENTATION, callback: Callback<OrientationResponse>, op Subscribes to data of the orientation sensor. +> **NOTE** +> +> Applications or services invoking this API can prompt users to use figure-8 calibration to improve the accuracy of the direction sensor. The sensor has a theoretical error of ±5 degrees, but the specific precision may vary depending on different driver implementations and algorithmic designs. + **Atomic service API**: This API can be used in atomic services since API version 11. **System capability**: SystemCapability.Sensors.Sensor @@ -698,7 +702,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Parameters** @@ -747,7 +751,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | -------- | ------------------------------------------------------------ | | 201 | Permission denied. | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Parameters** @@ -803,7 +807,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | -------- | ------------------------------------------------------------ | | 201 | Permission denied. | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -847,7 +851,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3.Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -892,7 +896,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3.Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -940,7 +944,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3.Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -985,7 +989,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3.Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -1006,6 +1010,49 @@ try { } ``` +### sensorStatusChange19+ + +on(type: 'sensorStatusChange', callback: Callback<SensorStatusEvent>): void + +Enables listening for sensor status changes. This API asynchronously returns the result through a callback. + +**System capability**: SystemCapability.Sensors.Sensor + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------------- | +| sensorStatusChange | sensorStatusChange | Yes | Event type. The value **sensorStatusChange** indicates a sensor status change event. | +| callback | Callback<[SensorStatusEvent](#sensorstatusevent19)> | Yes | Callback used to return the sensor status change event.| + +**Error codes** + +For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) and [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message | +| -------- | ------------------------------------------------------------ | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**Example** + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +try { + sensor.on('sensorStatusChange', (data: sensor.SensorStatusEvent) => { + console.info('sensorStatusChange : ' + JSON.stringify(data)); + }); + setTimeout(() => { + sensor.off('sensorStatusChange'); + }, 5000); +} catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke on. Code: ${e.code}, message: ${e.message}`); +} +``` + + ## sensor.once9+ ### ACCELEROMETER9+ @@ -1033,7 +1080,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | -------- | ------------------------------------------------------------ | | 201 | Permission denied. | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -1078,7 +1125,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | -------- | ------------------------------------------------------------ | | 201 | Permission denied. | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -1123,7 +1170,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -1163,7 +1210,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -1203,7 +1250,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -1243,7 +1290,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -1288,7 +1335,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | -------- | ------------------------------------------------------------ | | 201 | Permission denied. | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -1333,7 +1380,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | -------- | ------------------------------------------------------------ | | 201 | Permission denied. | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -1378,7 +1425,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -1421,7 +1468,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | -------- | ------------------------------------------------------------ | | 201 | Permission denied. | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -1461,7 +1508,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -1504,7 +1551,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | -------- | ------------------------------------------------------------ | | 201 | Permission denied. | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -1546,7 +1593,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -1588,7 +1635,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -1633,7 +1680,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -1678,7 +1725,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | -------- | ------------------------------------------------------------ | | 201 | Permission denied. | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -1721,7 +1768,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | -------- | ------------------------------------------------------------ | | 201 | Permission denied. | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -1761,7 +1808,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -1801,7 +1848,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -1844,7 +1891,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -1884,7 +1931,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -1918,10 +1965,10 @@ Unsubscribes from data of the acceleration sensor. **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| type | [SensorId](#sensorid9).ACCELEROMETER | Yes | Sensor type. The value is fixed at **SensorId.ACCELEROMETER**. | -| callback | Callback<[AccelerometerResponse](#accelerometerresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| +| Name | Type | Mandatory| Description | +|-------------------------------| ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).ACCELEROMETER | Yes | Sensor type. The value is fixed at **SensorId.ACCELEROMETER**. | +| callback | Callback<[AccelerometerResponse](#accelerometerresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| **Error codes** @@ -1959,6 +2006,86 @@ try { } ``` +### ACCELEROMETER19+ + +off(type: SensorId.ACCELEROMETER, sensorInfoParam?: SensorInfoParam, callback?: Callback<AccelerometerResponse>): void + +Unsubscribes from data of the acceleration sensor. + +**Required permissions**: ohos.permission.ACCELEROMETER + +**Atomic service API**: This API can be used in atomic services since API version 19. + +**System capability**: SystemCapability.Sensors.Sensor + +**Parameters** + +| Name | Type | Mandatory| Description | +|--------------------| ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).ACCELEROMETER | Yes | Sensor type. The value is fixed at **SensorId.ACCELEROMETER**. | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | No| Sensor parameters, including **deviceId** and **sensorIndex**.| +| callback | Callback<[AccelerometerResponse](#accelerometerresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message | +| -------- | ------------------------------------------------------------ | +| 201 | Permission denied. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**Example** + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// Sensor callback +const sensorCallback = (response: sensor.AccelerometerResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// Sensor type +const sensorType = sensor.SensorId.ACCELEROMETER; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // Query all sensors. + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // Obtain the target sensor based on the actual service logic. + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // Subscribe to sensor events. + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + ### ACCELEROMETER_UNCALIBRATED9+ off(type: SensorId.ACCELEROMETER_UNCALIBRATED, callback?: Callback<AccelerometerUncalibratedResponse>): void @@ -2012,6 +2139,84 @@ try { } ``` +### ACCELEROMETER_UNCALIBRATED19+ + +off(type: SensorId.ACCELEROMETER_UNCALIBRATED, sensorInfoParam?: SensorInfoParam, callback?: Callback<AccelerometerUncalibratedResponse>): void + +Unsubscribes from data of the uncalibrated acceleration sensor. + +**Required permissions**: ohos.permission.ACCELEROMETER + +**System capability**: SystemCapability.Sensors.Sensor + +**Parameters** + +| Name | Type | Mandatory| Description | +|------------------| ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).ACCELEROMETER_UNCALIBRATED | Yes | Sensor type. The value is fixed at **SensorId.ACCELEROMETER_UNCALIBRATED**. | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | No| Sensor parameters, including **deviceId** and **sensorIndex**.| +| callback | Callback<[AccelerometerUncalibratedResponse](#accelerometeruncalibratedresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message | +| -------- | ------------------------------------------------------------ | +| 201 | Permission denied. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**Example** + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// Sensor callback +const sensorCallback = (response: sensor.AccelerometerUncalibratedResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// Sensor type +const sensorType = sensor.SensorId.ACCELEROMETER_UNCALIBRATED; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // Query all sensors. + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // Obtain the target sensor based on the actual service logic. + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // Subscribe to sensor events. + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + ### AMBIENT_LIGHT9+ off(type: SensorId.AMBIENT_LIGHT, callback?: Callback<LightResponse>): void @@ -2062,6 +2267,81 @@ try { } ``` +### AMBIENT_LIGHT19+ + +off(type: SensorId.AMBIENT_LIGHT, sensorInfoParam?: SensorInfoParam, callback?: Callback<LightResponse>): void + +Unsubscribes from data of the ambient light sensor. + +**System capability**: SystemCapability.Sensors.Sensor + +**Parameters** + +| Name | Type | Mandatory| Description | +|------------------| ----------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).AMBIENT_LIGHT | Yes | Sensor type. The value is fixed at **SensorId.AMBIENT_LIGHT**. | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | No| Sensor parameters, including **deviceId** and **sensorIndex**.| +| callback | Callback<[LightResponse](#lightresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message | +| -------- | ------------------------------------------------------------ | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**Example** + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// Sensor callback +const sensorCallback = (response: sensor.LightResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// Sensor type +const sensorType = sensor.SensorId.AMBIENT_LIGHT; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // Query all sensors. + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // Obtain the target sensor based on the actual service logic. + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // Subscribe to sensor events. + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + ### AMBIENT_TEMPERATURE9+ off(type: SensorId.AMBIENT_TEMPERATURE, callback?: Callback<AmbientTemperatureResponse>): void @@ -2112,6 +2392,82 @@ try { } ``` +### AMBIENT_TEMPERATURE19+ + +off(type: SensorId.AMBIENT_TEMPERATURE, sensorInfoParam?: SensorInfoParam, callback?: Callback<AmbientTemperatureResponse>): void + +Unsubscribes from data of the ambient temperature sensor. + +**System capability**: SystemCapability.Sensors.Sensor + +**Parameters** + +| Name | Type | Mandatory| Description | +|------------------| ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).AMBIENT_TEMPERATURE | Yes | Sensor type. The value is fixed at **SensorId.AMBIENT_TEMPERATURE**. | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | No| Sensor parameters, including **deviceId** and **sensorIndex**.| +| callback | Callback<[AmbientTemperatureResponse](#ambienttemperatureresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message | +| -------- | ------------------------------------------------------------ | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**Example** + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// Sensor callback +const sensorCallback = (response: sensor.AmbientTemperatureResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// Sensor type +const sensorType = sensor.SensorId.AMBIENT_TEMPERATURE; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // Query all sensors. + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // Obtain the target sensor based on the actual service logic. + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // Subscribe to sensor events. + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + + ### BAROMETER9+ off(type: SensorId.BAROMETER, callback?: Callback<BarometerResponse>): void @@ -2162,6 +2518,81 @@ try { } ``` +### BAROMETER19+ + +off(type: SensorId.BAROMETER, sensorInfoParam?: SensorInfoParam, callback?: Callback<BarometerResponse>): void + +Unsubscribes from data of the barometer sensor. + +**System capability**: SystemCapability.Sensors.Sensor + +**Parameters** + +| Name | Type | Mandatory| Description | +|------------------| ------------------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).BAROMETER | Yes | Sensor type. The value is fixed at **SensorId.BAROMETER**. | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | No| Sensor parameters, including **deviceId** and **sensorIndex**.| +| callback | Callback<[BarometerResponse](#barometerresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message | +| -------- | ------------------------------------------------------------ | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**Example** + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// Sensor callback +const sensorCallback = (response: sensor.BarometerResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// Sensor type +const sensorType = sensor.SensorId.BAROMETER; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // Query all sensors. + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // Obtain the target sensor based on the actual service logic. + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // Subscribe to sensor events. + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + ### GRAVITY9+ off(type: SensorId.GRAVITY, callback?: Callback<GravityResponse>): void @@ -2213,6 +2644,81 @@ try { ``` +### GRAVITY19+ + +off(type: SensorId.GRAVITY, sensorInfoParam?: SensorInfoParam, callback?: Callback<GravityResponse>): void + +Unsubscribes from data of the gravity sensor. + +**System capability**: SystemCapability.Sensors.Sensor + +**Parameters** + +| Name | Type | Mandatory| Description | +|------------------| --------------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).GRAVITY | Yes | Sensor type. The value is fixed at **SensorId.GRAVITY**. | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | No| Sensor parameters, including **deviceId** and **sensorIndex**.| +| callback | Callback<[GravityResponse](#gravityresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message | +| -------- | ------------------------------------------------------------ | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**Example** + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// Sensor callback +const sensorCallback = (response: sensor.GravityResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// Sensor type +const sensorType = sensor.SensorId.GRAVITY; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // Query all sensors. + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // Obtain the target sensor based on the actual service logic. + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // Subscribe to sensor events. + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + ### GYROSCOPE9+ off(type: SensorId.GYROSCOPE, callback?: Callback<GyroscopeResponse>): void @@ -2268,6 +2774,86 @@ try { } ``` +### GYROSCOPE19+ + +off(type: SensorId.GYROSCOPE, sensorInfoParam?: SensorInfoParam, callback?: Callback<GyroscopeResponse>): void + +Unsubscribes from data of the gyroscope sensor. + +**Required permissions**: ohos.permission.GYROSCOPE + +**Atomic service API**: This API can be used in atomic services since API version 19. + +**System capability**: SystemCapability.Sensors.Sensor + +**Parameters** + +| Name | Type | Mandatory| Description | +|------------------| ------------------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).GYROSCOPE | Yes | Sensor type. The value is fixed at **SensorId.GYROSCOPE**. | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | No| Sensor parameters, including **deviceId** and **sensorIndex**.| +| callback | Callback<[GyroscopeResponse](#gyroscoperesponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message | +| -------- | ------------------------------------------------------------ | +| 201 | Permission denied. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**Example** + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// Sensor callback +const sensorCallback = (response: sensor.GyroscopeResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// Sensor type +const sensorType = sensor.SensorId.GYROSCOPE; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // Query all sensors. + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // Obtain the target sensor based on the actual service logic. + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // Subscribe to sensor events. + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + ### GYROSCOPE_UNCALIBRATED9+ off(type: SensorId.GYROSCOPE_UNCALIBRATED, callback?: Callback<GyroscopeUncalibratedResponse>): void @@ -2321,6 +2907,84 @@ try { } ``` +### GYROSCOPE_UNCALIBRATED19+ + +off(type: SensorId.GYROSCOPE_UNCALIBRATED, sensorInfoParam?: SensorInfoParam, callback?: Callback<GyroscopeUncalibratedResponse>): void + +Unsubscribes from data of the uncalibrated gyroscope sensor. + +**Required permissions**: ohos.permission.GYROSCOPE + +**System capability**: SystemCapability.Sensors.Sensor + +**Parameters** + +| Name | Type | Mandatory| Description | +|------------------| ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).GYROSCOPE_UNCALIBRATED | Yes | Sensor type. The value is fixed at **SensorId.GYROSCOPE_UNCALIBRATED**. | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | No| Sensor parameters, including **deviceId** and **sensorIndex**.| +| callback | Callback<[GyroscopeUncalibratedResponse](#gyroscopeuncalibratedresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message | +| -------- | ------------------------------------------------------------ | +| 201 | Permission denied. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**Example** + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// Sensor callback +const sensorCallback = (response: sensor.GyroscopeUncalibratedResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// Sensor type +const sensorType = sensor.SensorId.GYROSCOPE_UNCALIBRATED; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // Query all sensors. + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // Obtain the target sensor based on the actual service logic. + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // Subscribe to sensor events. + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + ### HALL9+ off(type: SensorId.HALL, callback?: Callback<HallResponse>): void @@ -2371,6 +3035,81 @@ try { } ``` +### HALL19+ + +off(type: SensorId.HALL, sensorInfoParam?: SensorInfoParam, callback?: Callback<HallResponse>): void + +Unsubscribes from data of the Hall effect sensor. + +**System capability**: SystemCapability.Sensors.Sensor + +**Parameters** + +| Name | Type | Mandatory| Description | +|------------------| --------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).HALL | Yes | Sensor type. The value is fixed at **SensorId.HALL**. | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | No| Sensor parameters, including **deviceId** and **sensorIndex**.| +| callback | Callback<[HallResponse](#hallresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message | +| -------- | ------------------------------------------------------------ | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**Example** + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// Sensor callback +const sensorCallback = (response: sensor.HallResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// Sensor type +const sensorType = sensor.SensorId.HALL; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // Query all sensors. + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // Obtain the target sensor based on the actual service logic. + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // Subscribe to sensor events. + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + ### HEART_RATE9+ off(type: SensorId.HEART_RATE, callback?: Callback<HeartRateResponse>): void @@ -2424,6 +3163,84 @@ try { } ``` +### HEART_RATE19+ + +off(type: SensorId.HEART_RATE, sensorInfoParam?: SensorInfoParam, callback?: Callback<HeartRateResponse>): void + +Unsubscribes from data of the heart rate sensor. + +**Required permissions**: ohos.permission.READ_HEALTH_DATA + +**System capability**: SystemCapability.Sensors.Sensor + +**Parameters** + +| Name | Type | Mandatory| Description | +|------------------| ------------------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).HEART_RATE | Yes | Sensor type. The value is fixed at **SensorId.HEART_RATE**. | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | No| Sensor parameters, including **deviceId** and **sensorIndex**.| +| callback | Callback<[HeartRateResponse](#heartrateresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message | +| -------- | ------------------------------------------------------------ | +| 201 | Permission denied. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**Example** + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// Sensor callback +const sensorCallback = (response: sensor.HeartRateResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// Sensor type +const sensorType = sensor.SensorId.HEART_RATE; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // Query all sensors. + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // Obtain the target sensor based on the actual service logic. + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // Subscribe to sensor events. + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + ### HUMIDITY9+ off(type: SensorId.HUMIDITY, callback?: Callback<HumidityResponse>): void @@ -2474,6 +3291,81 @@ try { } ``` +### HUMIDITY19+ + +off(type: SensorId.HUMIDITY, sensorInfoParam?: SensorInfoParam, callback?: Callback<HumidityResponse>): void + +Unsubscribes from data of the humidity sensor. + +**System capability**: SystemCapability.Sensors.Sensor + +**Parameters** + +| Name | Type | Mandatory| Description | +|------------------| ----------------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).HUMIDITY | Yes | Sensor type. The value is fixed at **SensorId.HUMIDITY**. | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | No| Sensor parameters, including **deviceId** and **sensorIndex**.| +| callback | Callback<[HumidityResponse](#humidityresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message | +| -------- | ------------------------------------------------------------ | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**Example** + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// Sensor callback +const sensorCallback = (response: sensor.HumidityResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// Sensor type +const sensorType = sensor.SensorId.HUMIDITY; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // Query all sensors. + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // Obtain the target sensor based on the actual service logic. + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // Subscribe to sensor events. + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + ### LINEAR_ACCELEROMETER9+ off(type: SensorId.LINEAR_ACCELEROMETER, callback?: Callback<LinearAccelerometerResponse>): void @@ -2527,6 +3419,84 @@ try { } ``` +### LINEAR_ACCELEROMETER19+ + +off(type: SensorId.LINEAR_ACCELEROMETER, sensorInfoParam?: SensorInfoParam, callback?: Callback<LinearAccelerometerResponse>): void + +Unsubscribes from data of the linear acceleration sensor. + +**Required permissions**: ohos.permission.ACCELEROMETER + +**System capability**: SystemCapability.Sensors.Sensor + +**Parameters** + +| Name | Type | Mandatory| Description | +|------------------| ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).LINEAR_ACCELEROMETER | Yes | Sensor type. The value is fixed at **SensorId.LINEAR_ACCELERATION**. | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | No| Sensor parameters, including **deviceId** and **sensorIndex**.| +| callback | Callback<[LinearAccelerometerResponse](#linearaccelerometerresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message | +| -------- | ------------------------------------------------------------ | +| 201 | Permission denied. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**Example** + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// Sensor callback +const sensorCallback = (response: sensor.LinearAccelerometerResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// Sensor type +const sensorType = sensor.SensorId.LINEAR_ACCELEROMETER; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // Query all sensors. + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // Obtain the target sensor based on the actual service logic. + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // Subscribe to sensor events. + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + ### MAGNETIC_FIELD9+ off(type: SensorId.MAGNETIC_FIELD, callback?: Callback<MagneticFieldResponse>): void @@ -2577,20 +3547,736 @@ try { } ``` -### MAGNETIC_FIELD_UNCALIBRATED9+ +### MAGNETIC_FIELD19+ -off(type: SensorId.MAGNETIC_FIELD_UNCALIBRATED, callback?: Callback<MagneticFieldUncalibratedResponse>): void +off(type: SensorId.MAGNETIC_FIELD, sensorInfoParam?: SensorInfoParam, callback?: Callback<MagneticFieldResponse>): void -Unsubscribes from data of the uncalibrated magnetic field sensor. +Unsubscribes from data of the magnetic field sensor. **System capability**: SystemCapability.Sensors.Sensor **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| type | [SensorId](#sensorid9).MAGNETIC_FIELD_UNCALIBRATED | Yes | Sensor type. The value is fixed at **SensorId.MAGNETIC_FIELD_UNCALIBRATED**.| -| callback | Callback<[MagneticFieldUncalibratedResponse](#magneticfielduncalibratedresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| +| Name | Type | Mandatory| Description | +|------------------| ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).MAGNETIC_FIELD | Yes | Sensor type. The value is fixed at **SensorId.MAGNETIC_FIELD**. | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | No| Sensor parameters, including **deviceId** and **sensorIndex**.| +| callback | Callback<[MagneticFieldResponse](#magneticfieldresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message | +| -------- | ------------------------------------------------------------ | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**Example** + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// Sensor callback +const sensorCallback = (response: sensor.MagneticFieldResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// Sensor type +const sensorType = sensor.SensorId.MAGNETIC_FIELD; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // Query all sensors. + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // Obtain the target sensor based on the actual service logic. + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // Subscribe to sensor events. + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + +### MAGNETIC_FIELD_UNCALIBRATED9+ + +off(type: SensorId.MAGNETIC_FIELD_UNCALIBRATED, callback?: Callback<MagneticFieldUncalibratedResponse>): void + +Unsubscribes from data of the uncalibrated magnetic field sensor. + +**System capability**: SystemCapability.Sensors.Sensor + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).MAGNETIC_FIELD_UNCALIBRATED | Yes | Sensor type. The value is fixed at **SensorId.MAGNETIC_FIELD_UNCALIBRATED**.| +| callback | Callback<[MagneticFieldUncalibratedResponse](#magneticfielduncalibratedresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message | +| -------- | ------------------------------------------------------------ | +| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | + +**Example** + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +function callback1(data: object) { + console.info('Succeeded in getting callback1 data: ' + JSON.stringify(data)); +} + +function callback2(data: object) { + console.info('Succeeded in getting callback2 data: ' + JSON.stringify(data)); +} + +try { + sensor.on(sensor.SensorId.MAGNETIC_FIELD_UNCALIBRATED, callback1); + sensor.on(sensor.SensorId.MAGNETIC_FIELD_UNCALIBRATED, callback2); + // Unsubscribe from callback1. + sensor.off(sensor.SensorId.MAGNETIC_FIELD_UNCALIBRATED, callback1); + // Unsubscribe from all callbacks of the SensorId.MAGNETIC_FIELD_UNCALIBRATED type. + sensor.off(sensor.SensorId.MAGNETIC_FIELD_UNCALIBRATED); +} catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); +} +``` + +### MAGNETIC_FIELD_UNCALIBRATED19+ + +off(type: SensorId.MAGNETIC_FIELD_UNCALIBRATED, sensorInfoParam?: SensorInfoParam, callback?: Callback<MagneticFieldUncalibratedResponse>): void + +Unsubscribes from data of the uncalibrated magnetic field sensor. + +**System capability**: SystemCapability.Sensors.Sensor + +**Parameters** + +| Name | Type | Mandatory| Description | +|------------------| ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).MAGNETIC_FIELD_UNCALIBRATED | Yes | Sensor type. The value is fixed at **SensorId.MAGNETIC_FIELD_UNCALIBRATED**.| +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | No| Sensor parameters, including **deviceId** and **sensorIndex**.| +| callback | Callback<[MagneticFieldUncalibratedResponse](#magneticfielduncalibratedresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message | +| -------- | ------------------------------------------------------------ | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**Example** + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// Sensor callback +const sensorCallback = (response: sensor.MagneticFieldUncalibratedResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// Sensor type +const sensorType = sensor.SensorId.MAGNETIC_FIELD_UNCALIBRATED; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // Query all sensors. + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // Obtain the target sensor based on the actual service logic. + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // Subscribe to sensor events. + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + +### ORIENTATION9+ + +off(type: SensorId.ORIENTATION, callback?: Callback<OrientationResponse>): void + +Unsubscribes from data of the orientation sensor. + +**Atomic service API**: This API can be used in atomic services since API version 11. + +**System capability**: SystemCapability.Sensors.Sensor + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).ORIENTATION | Yes | Sensor type. The value is fixed at **SensorId.ORIENTATION**. | +| callback | Callback<[OrientationResponse](#orientationresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message | +| -------- | ------------------------------------------------------------ | +| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | + +**Example** + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +function callback1(data: object) { + console.info('Succeeded in getting callback1 data: ' + JSON.stringify(data)); +} + +function callback2(data: object) { + console.info('Succeeded in getting callback2 data: ' + JSON.stringify(data)); +} + +try { + sensor.on(sensor.SensorId.ORIENTATION, callback1); + sensor.on(sensor.SensorId.ORIENTATION, callback2); + // Unsubscribe from callback1. + sensor.off(sensor.SensorId.ORIENTATION, callback1); + // Unsubscribe from all callbacks of the SensorId.ORIENTATION type. + sensor.off(sensor.SensorId.ORIENTATION); +} catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); +} +``` + +### ORIENTATION19+ + +off(type: SensorId.ORIENTATION, sensorInfoParam?: SensorInfoParam, callback?: Callback<OrientationResponse>): void + +Unsubscribes from data of the orientation sensor. + +**Atomic service API**: This API can be used in atomic services since API version 19. + +**System capability**: SystemCapability.Sensors.Sensor + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).ORIENTATION | Yes | Sensor type. The value is fixed at **SensorId.ORIENTATION**. | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | No| Sensor parameters, including **deviceId** and **sensorIndex**.| +| callback | Callback<[OrientationResponse](#orientationresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message | +| -------- | ------------------------------------------------------------ | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**Example** + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// Sensor callback +const sensorCallback = (response: sensor.OrientationResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// Sensor type +const sensorType = sensor.SensorId.ORIENTATION; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // Query all sensors. + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // Obtain the target sensor based on the actual service logic. + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // Subscribe to sensor events. + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + +### PEDOMETER9+ + +off(type: SensorId.PEDOMETER, callback?: Callback<PedometerResponse>): void + +Unsubscribes from data of the pedometer sensor. + +**Required permissions**: ohos.permission.ACTIVITY_MOTION + +**System capability**: SystemCapability.Sensors.Sensor + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).PEDOMETER | Yes | Sensor type. The value is fixed at **SensorId.PEDOMETER**. | +| callback | Callback<[PedometerResponse](#pedometerresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message | +| -------- | ------------------------------------------------------------ | +| 201 | Permission denied. | +| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | + +**Example** + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +function callback1(data: object) { + console.info('Succeeded in getting callback1 data: ' + JSON.stringify(data)); +} + +function callback2(data: object) { + console.info('Succeeded in getting callback2 data: ' + JSON.stringify(data)); +} + +try { + sensor.on(sensor.SensorId.PEDOMETER, callback1); + sensor.on(sensor.SensorId.PEDOMETER, callback2); + // Unsubscribe from callback1. + sensor.off(sensor.SensorId.PEDOMETER, callback1); + // Unsubscribe from all callbacks of the SensorId.ORIENTATION type. + sensor.off(sensor.SensorId.PEDOMETER); +} catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); +} +``` + +### PEDOMETER19+ + +off(type: SensorId.PEDOMETER, sensorInfoParam?: SensorInfoParam, callback?: Callback<PedometerResponse>): void + +Unsubscribes from data of the pedometer sensor. + +**Required permissions**: ohos.permission.ACTIVITY_MOTION + +**System capability**: SystemCapability.Sensors.Sensor + +**Parameters** + +| Name | Type | Mandatory| Description | +|------------------| ------------------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).PEDOMETER | Yes | Sensor type. The value is fixed at **SensorId.PEDOMETER**. | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | No| Sensor parameters, including **deviceId** and **sensorIndex**.| +| callback | Callback<[PedometerResponse](#pedometerresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message | +| -------- | ------------------------------------------------------------ | +| 201 | Permission denied. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**Example** + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// Sensor callback +const sensorCallback = (response: sensor.PedometerResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// Sensor type +const sensorType = sensor.SensorId.PEDOMETER; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // Query all sensors. + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // Obtain the target sensor based on the actual service logic. + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // Subscribe to sensor events. + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + +### PEDOMETER_DETECTION9+ + +off(type: SensorId.PEDOMETER_DETECTION, callback?: Callback<PedometerDetectionResponse>): void + +Unsubscribes from data of the pedometer detection sensor. + +**Required permissions**: ohos.permission.ACTIVITY_MOTION + +**System capability**: SystemCapability.Sensors.Sensor + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).PEDOMETER_DETECTION | Yes | Sensor type. The value is fixed at **SensorId.PEDOMETER_DETECTION**. | +| callback | Callback<[PedometerDetectionResponse](#pedometerdetectionresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message | +| -------- | ------------------------------------------------------------ | +| 201 | Permission denied. | +| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | + +**Example** + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +function callback1(data: object) { + console.info('Succeeded in getting callback1 data: ' + JSON.stringify(data)); +} + +function callback2(data: object) { + console.info('Succeeded in getting callback2 data: ' + JSON.stringify(data)); +} + +try { + sensor.on(sensor.SensorId.PEDOMETER_DETECTION, callback1); + sensor.on(sensor.SensorId.PEDOMETER_DETECTION, callback2); + // Unsubscribe from callback1. + sensor.off(sensor.SensorId.PEDOMETER_DETECTION, callback1); + // Unsubscribe from all callbacks of the SensorId.PEDOMETER_DETECTION type. + sensor.off(sensor.SensorId.PEDOMETER_DETECTION); +} catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); +} +``` + +### PEDOMETER_DETECTION19+ + +off(type: SensorId.PEDOMETER_DETECTION, sensorInfoParam?: SensorInfoParam, callback?: Callback<PedometerDetectionResponse>): void + +Unsubscribes from data of the pedometer detection sensor. + +**Required permissions**: ohos.permission.ACTIVITY_MOTION + +**System capability**: SystemCapability.Sensors.Sensor + +**Parameters** + +| Name | Type | Mandatory| Description | +|------------------| ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).PEDOMETER_DETECTION | Yes | Sensor type. The value is fixed at **SensorId.PEDOMETER_DETECTION**. | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | No| Sensor parameters, including **deviceId** and **sensorIndex**.| +| callback | Callback<[PedometerDetectionResponse](#pedometerdetectionresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message | +| -------- | ------------------------------------------------------------ | +| 201 | Permission denied. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**Example** + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// Sensor callback +const sensorCallback = (response: sensor.PedometerDetectionResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// Sensor type +const sensorType = sensor.SensorId.PEDOMETER_DETECTION; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // Query all sensors. + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // Obtain the target sensor based on the actual service logic. + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // Subscribe to sensor events. + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + +### PROXIMITY9+ + +off(type: SensorId.PROXIMITY, callback?: Callback<ProximityResponse>): void + +Unsubscribes from data of the proximity sensor. + +**System capability**: SystemCapability.Sensors.Sensor + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).PROXIMITY | Yes | Sensor type. The value is fixed at **SensorId.PROXIMITY**. | +| callback | Callback<[ProximityResponse](#proximityresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message | +| -------- | ------------------------------------------------------------ | +| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | + +**Example** + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +function callback1(data: object) { + console.info('Succeeded in getting callback1 data: ' + JSON.stringify(data)); +} + +function callback2(data: object) { + console.info('Succeeded in getting callback2 data: ' + JSON.stringify(data)); +} + +try { + sensor.on(sensor.SensorId.PROXIMITY, callback1); + sensor.on(sensor.SensorId.PROXIMITY, callback2); + // Unsubscribe from callback1. + sensor.off(sensor.SensorId.PROXIMITY, callback1); + // Unsubscribe from all callbacks of the SensorId.PROXIMITY type. + sensor.off(sensor.SensorId.PROXIMITY); +} catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); +} +``` + +### PROXIMITY19+ + +off(type: SensorId.PROXIMITY, sensorInfoParam?: SensorInfoParam, callback?: Callback<ProximityResponse>): void + +Unsubscribes from data of the proximity sensor. + +**System capability**: SystemCapability.Sensors.Sensor + +**Parameters** + +| Name | Type | Mandatory| Description | +|-----------------| ------------------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).PROXIMITY | Yes | Sensor type. The value is fixed at **SensorId.PROXIMITY**. | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | No| Sensor parameters, including **deviceId** and **sensorIndex**.| +| callback | Callback<[ProximityResponse](#proximityresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message | +| -------- | ------------------------------------------------------------ | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**Example** + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// Sensor callback +const sensorCallback = (response: sensor.ProximityResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// Sensor type +const sensorType = sensor.SensorId.PROXIMITY; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // Query all sensors. + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // Obtain the target sensor based on the actual service logic. + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // Subscribe to sensor events. + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + +### ROTATION_VECTOR9+ + +off(type: SensorId.ROTATION_VECTOR, callback?: Callback<RotationVectorResponse>): void + +Unsubscribes from data of the rotation vector sensor. + +**System capability**: SystemCapability.Sensors.Sensor + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).ROTATION_VECTOR | Yes | Sensor type. The value is fixed at **SensorId.ROTATION_VECTOR**. | +| callback | Callback<[RotationVectorResponse](#rotationvectorresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| **Error codes** @@ -2615,34 +4301,33 @@ function callback2(data: object) { } try { - sensor.on(sensor.SensorId.MAGNETIC_FIELD_UNCALIBRATED, callback1); - sensor.on(sensor.SensorId.MAGNETIC_FIELD_UNCALIBRATED, callback2); + sensor.on(sensor.SensorId.ROTATION_VECTOR, callback1); + sensor.on(sensor.SensorId.ROTATION_VECTOR, callback2); // Unsubscribe from callback1. - sensor.off(sensor.SensorId.MAGNETIC_FIELD_UNCALIBRATED, callback1); - // Unsubscribe from all callbacks of the SensorId.MAGNETIC_FIELD_UNCALIBRATED type. - sensor.off(sensor.SensorId.MAGNETIC_FIELD_UNCALIBRATED); + sensor.off(sensor.SensorId.ROTATION_VECTOR, callback1); + // Unsubscribe from all callbacks of the SensorId.ROTATION_VECTOR type. + sensor.off(sensor.SensorId.ROTATION_VECTOR); } catch (error) { let e: BusinessError = error as BusinessError; console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); } ``` -### ORIENTATION9+ - -off(type: SensorId.ORIENTATION, callback?: Callback<OrientationResponse>): void +### ROTATION_VECTOR19+ -Unsubscribes from data of the orientation sensor. +off(type: SensorId.ROTATION_VECTOR, sensorInfoParam?: SensorInfoParam, callback?: Callback<RotationVectorResponse>): void -**Atomic service API**: This API can be used in atomic services since API version 11. +Unsubscribes from data of the rotation vector sensor. **System capability**: SystemCapability.Sensors.Sensor **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | -| type | [SensorId](#sensorid9).ORIENTATION | Yes | Sensor type. The value is fixed at **SensorId.ORIENTATION**. | -| callback | Callback<[OrientationResponse](#orientationresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| +| Name | Type | Mandatory| Description | +|------------------| ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).ROTATION_VECTOR | Yes | Sensor type. The value is fixed at **SensorId.ROTATION_VECTOR**. | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | No| Sensor parameters, including **deviceId** and **sensorIndex**.| +| callback | Callback<[RotationVectorResponse](#rotationvectorresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| **Error codes** @@ -2650,7 +4335,7 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | ID| Error Message | | -------- | ------------------------------------------------------------ | -| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -2658,43 +4343,65 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ import { sensor } from '@kit.SensorServiceKit'; import { BusinessError } from '@kit.BasicServicesKit'; -function callback1(data: object) { - console.info('Succeeded in getting callback1 data: ' + JSON.stringify(data)); +enum Ret { OK, Failed = -1 } + +// Sensor callback +const sensorCallback = (response: sensor.RotationVectorResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); } +// Sensor type +const sensorType = sensor.SensorId.ROTATION_VECTOR; +const sensorInfoParam: sensor.SensorInfoParam = {}; -function callback2(data: object) { - console.info('Succeeded in getting callback2 data: ' + JSON.stringify(data)); +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // Query all sensors. + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // Obtain the target sensor based on the actual service logic. + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // Subscribe to sensor events. + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; } -try { - sensor.on(sensor.SensorId.ORIENTATION, callback1); - sensor.on(sensor.SensorId.ORIENTATION, callback2); - // Unsubscribe from callback1. - sensor.off(sensor.SensorId.ORIENTATION, callback1); - // Unsubscribe from all callbacks of the SensorId.ORIENTATION type. - sensor.off(sensor.SensorId.ORIENTATION); -} catch (error) { - let e: BusinessError = error as BusinessError; - console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; } ``` -### PEDOMETER9+ - -off(type: SensorId.PEDOMETER, callback?: Callback<PedometerResponse>): void +### SIGNIFICANT_MOTION9+ -Unsubscribes from data of the pedometer sensor. +off(type: SensorId.SIGNIFICANT_MOTION, callback?: Callback<SignificantMotionResponse>): void -**Required permissions**: ohos.permission.ACTIVITY_MOTION +Unsubscribes from valid motion sensor data. **System capability**: SystemCapability.Sensors.Sensor **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | -| type | [SensorId](#sensorid9).PEDOMETER | Yes | Sensor type. The value is fixed at **SensorId.PEDOMETER**. | -| callback | Callback<[PedometerResponse](#pedometerresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).SIGNIFICANT_MOTION | Yes | Sensor type. The value is fixed at **SensorId.SIGNIFICANT_MOTION**. | +| callback | Callback<[SignificantMotionResponse](#significantmotionresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| **Error codes** @@ -2702,7 +4409,6 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | ID| Error Message | | -------- | ------------------------------------------------------------ | -| 201 | Permission denied. | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | **Example** @@ -2720,34 +4426,33 @@ function callback2(data: object) { } try { - sensor.on(sensor.SensorId.PEDOMETER, callback1); - sensor.on(sensor.SensorId.PEDOMETER, callback2); + sensor.on(sensor.SensorId.SIGNIFICANT_MOTION, callback1); + sensor.on(sensor.SensorId.SIGNIFICANT_MOTION, callback2); // Unsubscribe from callback1. - sensor.off(sensor.SensorId.PEDOMETER, callback1); - // Unsubscribe from all callbacks of the SensorId.ORIENTATION type. - sensor.off(sensor.SensorId.PEDOMETER); + sensor.off(sensor.SensorId.SIGNIFICANT_MOTION, callback1); + // Unsubscribe from all callbacks of the SensorId.SIGNIFICANT_MOTION type. + sensor.off(sensor.SensorId.SIGNIFICANT_MOTION); } catch (error) { let e: BusinessError = error as BusinessError; console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); } ``` -### PEDOMETER_DETECTION9+ - -off(type: SensorId.PEDOMETER_DETECTION, callback?: Callback<PedometerDetectionResponse>): void +### SIGNIFICANT_MOTION19+ -Unsubscribes from data of the pedometer detection sensor. +off(type: SensorId.SIGNIFICANT_MOTION, sensorInfoParam?: SensorInfoParam, callback?: Callback<SignificantMotionResponse>): void -**Required permissions**: ohos.permission.ACTIVITY_MOTION +Unsubscribes from valid motion sensor data. **System capability**: SystemCapability.Sensors.Sensor **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| type | [SensorId](#sensorid9).PEDOMETER_DETECTION | Yes | Sensor type. The value is fixed at **SensorId.PEDOMETER_DETECTION**. | -| callback | Callback<[PedometerDetectionResponse](#pedometerdetectionresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| +| Name | Type | Mandatory| Description | +|------------------| ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).SIGNIFICANT_MOTION | Yes | Sensor type. The value is fixed at **SensorId.SIGNIFICANT_MOTION**. | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | No| Sensor parameters, including **deviceId** and **sensorIndex**.| +| callback | Callback<[SignificantMotionResponse](#significantmotionresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| **Error codes** @@ -2755,8 +4460,7 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | ID| Error Message | | -------- | ------------------------------------------------------------ | -| 201 | Permission denied. | -| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -2764,41 +4468,65 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ import { sensor } from '@kit.SensorServiceKit'; import { BusinessError } from '@kit.BasicServicesKit'; -function callback1(data: object) { - console.info('Succeeded in getting callback1 data: ' + JSON.stringify(data)); +enum Ret { OK, Failed = -1 } + +// Sensor callback +const sensorCallback = (response: sensor.SignificantMotionResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); } +// Sensor type +const sensorType = sensor.SensorId.SIGNIFICANT_MOTION; +const sensorInfoParam: sensor.SensorInfoParam = {}; -function callback2(data: object) { - console.info('Succeeded in getting callback2 data: ' + JSON.stringify(data)); +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // Query all sensors. + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // Obtain the target sensor based on the actual service logic. + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // Subscribe to sensor events. + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; } -try { - sensor.on(sensor.SensorId.PEDOMETER_DETECTION, callback1); - sensor.on(sensor.SensorId.PEDOMETER_DETECTION, callback2); - // Unsubscribe from callback1. - sensor.off(sensor.SensorId.PEDOMETER_DETECTION, callback1); - // Unsubscribe from all callbacks of the SensorId.PEDOMETER_DETECTION type. - sensor.off(sensor.SensorId.PEDOMETER_DETECTION); -} catch (error) { - let e: BusinessError = error as BusinessError; - console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; } ``` -### PROXIMITY9+ +### WEAR_DETECTION9+ -off(type: SensorId.PROXIMITY, callback?: Callback<ProximityResponse>): void +off(type: SensorId.WEAR_DETECTION, callback?: Callback<WearDetectionResponse>): void -Unsubscribes from data of the proximity sensor. +Unsubscribes from data of the wear detection sensor. **System capability**: SystemCapability.Sensors.Sensor **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | -| type | [SensorId](#sensorid9).PROXIMITY | Yes | Sensor type. The value is fixed at **SensorId.PROXIMITY**. | -| callback | Callback<[ProximityResponse](#proximityresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).WEAR_DETECTION | Yes | Sensor type. The value is fixed at **SensorId.WEAR_DETECTION**. | +| callback | Callback<[WearDetectionResponse](#weardetectionresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| **Error codes** @@ -2823,32 +4551,33 @@ function callback2(data: object) { } try { - sensor.on(sensor.SensorId.PROXIMITY, callback1); - sensor.on(sensor.SensorId.PROXIMITY, callback2); + sensor.on(sensor.SensorId.WEAR_DETECTION, callback1); + sensor.on(sensor.SensorId.WEAR_DETECTION, callback2); // Unsubscribe from callback1. - sensor.off(sensor.SensorId.PROXIMITY, callback1); - // Unsubscribe from all callbacks of the SensorId.PROXIMITY type. - sensor.off(sensor.SensorId.PROXIMITY); + sensor.off(sensor.SensorId.WEAR_DETECTION, callback1); + // Unsubscribe from all callbacks of the SensorId.WEAR_DETECTION type. + sensor.off(sensor.SensorId.WEAR_DETECTION); } catch (error) { let e: BusinessError = error as BusinessError; console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); } ``` -### ROTATION_VECTOR9+ +### WEAR_DETECTION19+ -off(type: SensorId.ROTATION_VECTOR, callback?: Callback<RotationVectorResponse>): void +off(type: SensorId.WEAR_DETECTION, sensorInfoParam?: SensorInfoParam, callback?: Callback<WearDetectionResponse>): void -Unsubscribes from data of the rotation vector sensor. +Unsubscribes from data of the wear detection sensor. **System capability**: SystemCapability.Sensors.Sensor **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| type | [SensorId](#sensorid9).ROTATION_VECTOR | Yes | Sensor type. The value is fixed at **SensorId.ROTATION_VECTOR**. | -| callback | Callback<[RotationVectorResponse](#rotationvectorresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| +| Name | Type | Mandatory| Description | +|------------------| ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).WEAR_DETECTION | Yes | Sensor type. The value is fixed at **SensorId.WEAR_DETECTION**. | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | No| Sensor parameters, including **deviceId** and **sensorIndex**.| +| callback | Callback<[WearDetectionResponse](#weardetectionresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| **Error codes** @@ -2856,7 +4585,7 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | ID| Error Message | | -------- | ------------------------------------------------------------ | -| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -2864,49 +4593,73 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ import { sensor } from '@kit.SensorServiceKit'; import { BusinessError } from '@kit.BasicServicesKit'; -function callback1(data: object) { - console.info('Succeeded in getting callback1 data: ' + JSON.stringify(data)); +enum Ret { OK, Failed = -1 } + +// Sensor callback +const sensorCallback = (response: sensor.WearDetectionResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); } +// Sensor type +const sensorType = sensor.SensorId.WEAR_DETECTION; +const sensorInfoParam: sensor.SensorInfoParam = {}; -function callback2(data: object) { - console.info('Succeeded in getting callback2 data: ' + JSON.stringify(data)); +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // Query all sensors. + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // Obtain the target sensor based on the actual service logic. + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // Subscribe to sensor events. + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; } -try { - sensor.on(sensor.SensorId.ROTATION_VECTOR, callback1); - sensor.on(sensor.SensorId.ROTATION_VECTOR, callback2); - // Unsubscribe from callback1. - sensor.off(sensor.SensorId.ROTATION_VECTOR, callback1); - // Unsubscribe from all callbacks of the SensorId.ROTATION_VECTOR type. - sensor.off(sensor.SensorId.ROTATION_VECTOR); -} catch (error) { - let e: BusinessError = error as BusinessError; - console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; } ``` -### SIGNIFICANT_MOTION9+ +### sensorStatusChange19+ -off(type: SensorId.SIGNIFICANT_MOTION, callback?: Callback<SignificantMotionResponse>): void +off(type: 'sensorStatusChange', callback?: Callback<SensorStatusEvent>): void -Unsubscribes from valid motion sensor data. +Disables listening for sensor status changes. **System capability**: SystemCapability.Sensors.Sensor **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| type | [SensorId](#sensorid9).SIGNIFICANT_MOTION | Yes | Sensor type. The value is fixed at **SensorId.SIGNIFICANT_MOTION**. | -| callback | Callback<[SignificantMotionResponse](#significantmotionresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------------- | +| sensorStatusChange | sensorStatusChange | Yes | Event type. The value **sensorStatusChange** indicates a sensor status change event. | +| callback | Callback<[SensorStatusEvent](#sensorstatusevent19)> | No | Callback passed to **sensor.on**. If this parameter is left unspecified, listening will be disabled for all callbacks.| **Error codes** -For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). +For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) and [Universal Error Codes](../errorcode-universal.md). | ID| Error Message | | -------- | ------------------------------------------------------------ | -| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -2914,49 +4667,53 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ import { sensor } from '@kit.SensorServiceKit'; import { BusinessError } from '@kit.BasicServicesKit'; -function callback1(data: object) { - console.info('Succeeded in getting callback1 data: ' + JSON.stringify(data)); -} - -function callback2(data: object) { - console.info('Succeeded in getting callback2 data: ' + JSON.stringify(data)); -} - try { - sensor.on(sensor.SensorId.SIGNIFICANT_MOTION, callback1); - sensor.on(sensor.SensorId.SIGNIFICANT_MOTION, callback2); - // Unsubscribe from callback1. - sensor.off(sensor.SensorId.SIGNIFICANT_MOTION, callback1); - // Unsubscribe from all callbacks of the SensorId.SIGNIFICANT_MOTION type. - sensor.off(sensor.SensorId.SIGNIFICANT_MOTION); + const statusChangeCallback = (data: sensor.SensorStatusEvent) => { + console.info('sensorStatusChange : ' + JSON.stringify(data)); + } + const statusChangeCallback2 = (data: sensor.SensorStatusEvent) => { + console.info('sensorStatusChange2 : ' + JSON.stringify(data)); + } + // Register two callback listeners for device online events. + sensor.on('sensorStatusChange', statusChangeCallback); + sensor.on('sensorStatusChange', statusChangeCallback2); + + // Unregister the first listener after 3 seconds. + setTimeout(() => { + sensor.off('sensorStatusChange', statusChangeCallback); + }, 3000); + // Unregister the other listener after 5 seconds. + setTimeout(() => { + sensor.off('sensorStatusChange'); + }, 5000); } catch (error) { let e: BusinessError = error as BusinessError; - console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); + console.error(`Failed to invoke on. Code: ${e.code}, message: ${e.message}`); } ``` -### WEAR_DETECTION9+ -off(type: SensorId.WEAR_DETECTION, callback?: Callback<WearDetectionResponse>): void +## sensor.getSensorListByDeviceSync19+ -Unsubscribes from data of the wear detection sensor. +getSensorListByDeviceSync(deviceId?: number): Array<Sensor> + +Obtains the information about all sensors on the device. **System capability**: SystemCapability.Sensors.Sensor **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| type | [SensorId](#sensorid9).WEAR_DETECTION | Yes | Sensor type. The value is fixed at **SensorId.WEAR_DETECTION**. | -| callback | Callback<[WearDetectionResponse](#weardetectionresponse)> | No | Callback used for unsubscription. If this parameter is not specified, all callbacks of the specified sensor type are unsubscribed from.| +| Name | Type | Mandatory| Description | +| --------------- | ------------------------------------------------------------ | ---- |--------| +| deviceId | number | No | Device ID. The default value is the ID of the local device.| -**Error codes** -For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). +**Return value** + +| Type | Description | +| ---------------------------------------------------------- | -------------- | +| Array<[Sensor](#sensor9)> | Sensor attribute list. | -| ID| Error Message | -| -------- | ------------------------------------------------------------ | -| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | **Example** @@ -2964,27 +4721,61 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ import { sensor } from '@kit.SensorServiceKit'; import { BusinessError } from '@kit.BasicServicesKit'; -function callback1(data: object) { - console.info('Succeeded in getting callback1 data: ' + JSON.stringify(data)); +try { + const deviceId = 1; + // The first deviceId is optional. By default, it is set to the ID of the local device. + const sensorList: sensor.Sensor[] = sensor.getSensorListByDeviceSync(deviceId); + console.log(`sensorList length: ${sensorList.length}`); + console.log(`sensorList: ${JSON.stringify(sensorList)}`); +} catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to get sensorList. Code: ${e.code}, message: ${e.message}`); } +``` -function callback2(data: object) { - console.info('Succeeded in getting callback2 data: ' + JSON.stringify(data)); -} + +## sensor.getSingleSensorByDeviceSync19+ + +getSingleSensorByDeviceSync(type: SensorId, deviceId?: number): Array<Sensor> + +Obtains information about the sensor of a specific type. + +**System capability**: SystemCapability.Sensors.Sensor + +**Parameters** + +| Name | Type | Mandatory| Description | +| --------------- | ------------------------------------------------------------ | ---- |----------| +| type | [SensorId](#sensorid9) | Yes | Sensor type.| +| deviceId | number | No | Device ID. The default value is the ID of the local device. | + + +**Return value** + +| Type | Description | +| ---------------------------------------------------------- | -------------- | +| Array<[Sensor](#sensor9)> | Sensor attribute list. | + + +**Example** + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; try { - sensor.on(sensor.SensorId.WEAR_DETECTION, callback1); - sensor.on(sensor.SensorId.WEAR_DETECTION, callback2); - // Unsubscribe from callback1. - sensor.off(sensor.SensorId.WEAR_DETECTION, callback1); - // Unsubscribe from all callbacks of the SensorId.WEAR_DETECTION type. - sensor.off(sensor.SensorId.WEAR_DETECTION); + const deviceId = 1; + // The second deviceId is optional. + const sensorList: sensor.Sensor[] = sensor.getSingleSensorByDeviceSync(sensor.SensorId.ACCELEROMETER, deviceId); + console.log(`sensorList length: ${sensorList.length}`); + console.log(`sensorList Json: ${JSON.stringify(sensorList)}`); } catch (error) { let e: BusinessError = error as BusinessError; - console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); + console.error(`Failed to get sensorList. Code: ${e.code}, message: ${e.message}`); } ``` + ## sensor.getGeomagneticInfo9+ getGeomagneticInfo(locationOptions: LocationOptions, timeMillis: number, callback: AsyncCallback<GeomagneticResponse>): void @@ -3008,7 +4799,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -3065,7 +4856,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -3115,7 +4906,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -3167,7 +4958,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -3212,7 +5003,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -3267,7 +5058,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -3318,7 +5109,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -3384,7 +5175,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -3443,7 +5234,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -3495,7 +5286,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -3543,7 +5334,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -3600,7 +5391,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -3650,7 +5441,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -3702,7 +5493,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -3748,7 +5539,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -3807,7 +5598,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -3858,7 +5649,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -3910,7 +5701,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -3954,7 +5745,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -3999,7 +5790,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -4041,7 +5832,7 @@ For details about the following error codes, see [Sensor Error Codes](errorcode- | ID| Error Message | | -------- | ------------------ | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **Example** @@ -4082,7 +5873,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | | 14500102 | The sensor is not supported by the device. | **Example** @@ -4132,7 +5923,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | | 14500102 | The sensor is not supported by the device. | **Example** @@ -4180,7 +5971,7 @@ For details about the error codes, see [Sensor Error Codes](errorcode-sensor.md) | ID| Error Message | | -------- | ------------------------------------------------------------ | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | -| 14500101 | Service exception. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | | 14500102 | The sensor is not supported by the device. | **Example** @@ -4228,6 +6019,36 @@ Enumerates the sensor types. | WEAR_DETECTION | 280 | Wear detection sensor. | | ACCELEROMETER_UNCALIBRATED | 281 | Uncalibrated acceleration sensor. | + +## SensorInfoParam19+ + +Defines sensor parameters, including **deviceId** and **sensorIndex**. + +**System capability**: SystemCapability.Sensors.Sensor + + +| Name| Type | Mandatory| Description | +| ------ | ---------------------- | ---- |-------------------------| +| deviceId | number | No | Device ID. The default value is **-1**, which indicates the local device. You can use [getSensorListByDeviceSync](#sensorgetsensorlistbydevicesync19) to query other device IDs. | +| sensorIndex | number | No | Sensor index. The default value is **0**, which indicates the default sensor on the device. You can use [getSensorListByDeviceSync](#sensorgetsensorlistbydevicesync19) to query other sensor IDs.| + + +## SensorStatusEvent19+ + +Defines a device status change event. + +**System capability**: SystemCapability.Sensors.Sensor + + +| Name| Type | Description | +| ------ | ---------------------- | ------------ | +| timestamp | number | Timestamp when an event occurs.| +| sensorId | number | Sensor ID.| +| sensorIndex | number | Sensor index.| +| isSensorOnline | boolean | Sensor status. The value **true** indicates that the sensor is online, and the value **false** indicates the opposite.| +| deviceId | number | Device ID.| +| deviceName | string | Device name.| + ## SensorType(deprecated) Enumerates the sensor types. @@ -4282,7 +6103,7 @@ Describes the timestamp of the sensor data. **System capability**: SystemCapability.Sensors.Sensor -| Name | Type | Readable| Writable| Description | +| Name | Type | Read-Only| Optional| Description | | --------- | ------ | ---- | ---- | ------------------------ | | timestamp | number | Yes | Yes | Timestamp when the sensor reports data.| | accuracy11+ | [SensorAccuracy](#sensoraccuracy11)11+ | Yes | No | Accuracy of the sensor data.| @@ -4293,18 +6114,22 @@ Describes the sensor information. **System capability**: SystemCapability.Sensors.Sensor -| Name | Type| Readable| Writable| Description | -| --------------- | -------- | ---------------------- | ---------------------- | ---------------------- | -| sensorName | string | Yes | No | Sensor name. | -| vendorName | string | Yes | No | Vendor of the sensor. | -| firmwareVersion | string | Yes | No | Firmware version of the sensor. | -| hardwareVersion | string | Yes | No | Hardware version of the sensor. | -| sensorId | number | Yes | No | Sensor type ID. | -| maxRange | number | Yes | No | Maximum measurement range of the sensor.| -| minSamplePeriod | number | Yes | No | Minimum sampling period. | -| maxSamplePeriod | number | Yes | No | Maximum sampling period. | -| precision | number | Yes | No | Precision of the sensor. | -| power | number | Yes | No | Estimated sensor power, in mA. | +| Name | Type | Read-Only| Optional| Description | +|-----------------------------|---------|----|----|------------------| +| sensorName | string | Yes | No | Sensor name. | +| vendorName | string | Yes | No | Vendor of the sensor. | +| firmwareVersion | string | Yes | No | Firmware version of the sensor. | +| hardwareVersion | string | Yes | No | Hardware version of the sensor. | +| sensorId | number | Yes | No | Sensor type ID. | +| maxRange | number | Yes | No | Maximum measurement range of the sensor. | +| minSamplePeriod | number | Yes | No | Minimum sampling period. | +| maxSamplePeriod | number | Yes | No | Maximum sampling period. | +| precision | number | Yes | No | Precision of the sensor. | +| power | number | Yes | No | Estimated sensor power, in mA.| +| sensorIndex19+ | number | Yes | Yes | Sensor index. | +| deviceId19+ | number | Yes | Yes | Device ID. | +| deviceName19+ | string | Yes | Yes | Device name. | +| isLocalSensor19+ | boolean | Yes | Yes | Whether the sensor is a local sensor. | ## AccelerometerResponse @@ -4315,7 +6140,7 @@ Describes the acceleration sensor data. It extends from [Response](#response). **System capability**: SystemCapability.Sensors.Sensor -| Name| Type | Readable| Writable| Description | +| Name| Type | Read-Only| Optional| Description | | ---- | ------ | ---- | ---- | ---------------------------------------------------------- | | x | number | Yes | Yes | Acceleration along the x-axis of the device, in m/s². The value is equal to the reported physical quantity.| | y | number | Yes | Yes | Acceleration along the y-axis of the device, in m/s². The value is equal to the reported physical quantity.| @@ -4329,7 +6154,7 @@ Describes the linear acceleration sensor data. It extends from [Response](#respo **System capability**: SystemCapability.Sensors.Sensor -| Name| Type | Readable| Writable| Description | +| Name| Type | Read-Only| Optional| Description | | ---- | ------ | ---- | ---- | ---------------------------------------- | | x | number | Yes | Yes | Linear acceleration along the x-axis of the device, in m/s².| | y | number | Yes | Yes | Linear acceleration along the y-axis of the device, in m/s².| @@ -4343,7 +6168,7 @@ Describes the uncalibrated acceleration sensor data. It extends from [Response]( **System capability**: SystemCapability.Sensors.Sensor -| Name | Type | Readable| Writable| Description | +| Name | Type | Read-Only| Optional| Description | | ----- | ------ | ---- | ---- | ---------------------------------------------- | | x | number | Yes | Yes | Uncalibrated acceleration along the x-axis of the device, in m/s². | | y | number | Yes | Yes | Uncalibrated acceleration along the y-axis of the device, in m/s². | @@ -4360,7 +6185,7 @@ Describes the gravity sensor data. It extends from [Response](#response). **System capability**: SystemCapability.Sensors.Sensor -| Name| Type | Readable| Writable| Description | +| Name| Type | Read-Only| Optional| Description | | ---- | ------ | ---- | ---- | ---------------------------------------- | | x | number | Yes | Yes | Gravitational acceleration along the x-axis of the device, in m/s².| | y | number | Yes | Yes | Gravitational acceleration along the y-axis of the device, in m/s².| @@ -4376,7 +6201,7 @@ Describes the orientation sensor data. It extends from [Response](#response). **System capability**: SystemCapability.Sensors.Sensor -| Name | Type | Readable| Writable| Description | +| Name | Type | Read-Only| Optional| Description | | ----- | ------ | ---- | ---- | ----------------------------------------------------- | | alpha | number | Yes | Yes | Rotation angle of the device around the z-axis, in degrees. The value ranges from 0 to 360. | | beta | number | Yes | Yes | Rotation angle of the device around the x-axis, in degrees. The value ranges from 0 to ±180.| @@ -4390,12 +6215,12 @@ Describes the rotation vector sensor data. It extends from [Response](#response) **System capability**: SystemCapability.Sensors.Sensor -| Name| Type | Readable| Writable| Description | +| Name| Type | Read-Only| Optional| Description | | ---- | ------ | ---- | ---- | ----------------- | | x | number | Yes | Yes | X-component of the rotation vector.| | y | number | Yes | Yes | Y-component of the rotation vector.| | z | number | Yes | Yes | Z-component of the rotation vector.| -| w | number | Yes | Yes | Scalar. | +| w | number | Yes | Yes | Scalar, which describes the rotation status of the device relative to a reference direction, in radians | ## GyroscopeResponse @@ -4407,7 +6232,7 @@ Describes the gyroscope sensor data. It extends from [Response](#response). **System capability**: SystemCapability.Sensors.Sensor -| Name| Type | Readable| Writable| Description | +| Name| Type | Read-Only| Optional| Description | | ---- | ------ | ---- | ---- | ------------------------------------------------------ | | x | number | Yes | Yes | Angular velocity of rotation around the x-axis of the device, in rad/s. The value is equal to the reported physical quantity.| | y | number | Yes | Yes | Angular velocity of rotation around the y-axis of the device, in rad/s. The value is equal to the reported physical quantity.| @@ -4421,7 +6246,7 @@ Describes the uncalibrated gyroscope sensor data. It extends from [Response](#re **System capability**: SystemCapability.Sensors.Sensor -| Name | Type | Readable| Writable| Description | +| Name | Type | Read-Only| Optional| Description | | ----- | ------ | ---- | ---- | ------------------------------------------ | | x | number | Yes | Yes | Uncalibrated angular velocity of rotation around the x-axis of the device, in rad/s. | | y | number | Yes | Yes | Uncalibrated angular velocity of rotation around the y-axis of the device, in rad/s. | @@ -4438,7 +6263,7 @@ Describes the significant motion sensor data. It extends from [Response](#respon **System capability**: SystemCapability.Sensors.Sensor -| Name | Type | Readable| Writable| Description | +| Name | Type | Read-Only| Optional| Description | | ------ | ------ | ---- | ---- | ------------------------------------------------------------ | | scalar | number | Yes | Yes | Intensity of a motion. This parameter specifies whether a device has a significant motion on three physical axes (X, Y, and Z). The value **1** is reported when the device has a significant motion.| @@ -4450,7 +6275,7 @@ Describes the proximity sensor data. It extends from [Response](#response). **System capability**: SystemCapability.Sensors.Sensor -| Name | Type | Readable| Writable| Description | +| Name | Type | Read-Only| Optional| Description | | -------- | ------ | ---- | ---- | ---------------------------------------------------------- | | distance | number | Yes | Yes | Proximity between the visible object and the device monitor. The value **0** means the two are close to each other, and a value greater than 0 means that they are far away from each other.| @@ -4462,7 +6287,7 @@ Describes the ambient light sensor data. It extends from [Response](#response). **System capability**: SystemCapability.Sensors.Sensor -| Name | Type | Readable| Writable| Description | +| Name | Type | Read-Only| Optional| Description | | ------------------------------- | ------ | ---- | ---- | ------------------------------------------------------------ | | intensity | number | Yes | Yes | Illumination, in lux. | | colorTemperature12+ | number | Yes | Yes | Color temperature, in Kelvin. This parameter is optional. If this parameter is not supported, **undefined** is returned. If this parameter is supported, a normal value is returned.| @@ -4476,7 +6301,7 @@ Describes the Hall effect sensor data. It extends from [Response](#response). **System capability**: SystemCapability.Sensors.Sensor -| Name | Type | Readable| Writable| Description | +| Name | Type | Read-Only| Optional| Description | | ------ | ------ | ---- | ---- | ------------------------------------------------------------ | | status | number | Yes | Yes | Hall effect sensor status. This parameter specifies whether a magnetic field exists around a device. The value **0** means that a magnetic field does not exist, and a value greater than **0** means the opposite.| @@ -4488,7 +6313,7 @@ Describes the magnetic field sensor data. It extends from [Response](#response). **System capability**: SystemCapability.Sensors.Sensor -| Name| Type | Readable| Writable| Description | +| Name| Type | Read-Only| Optional| Description | | ---- | ------ | ---- | ---- | ---------------------------- | | x | number | Yes | Yes | Magnetic field strength on the x-axis, in ÎĽT.| | y | number | Yes | Yes | Magnetic field strength on the y-axis, in ÎĽT.| @@ -4502,7 +6327,7 @@ Describes the uncalibrated magnetic field sensor data. It extends from [Response **System capability**: SystemCapability.Sensors.Sensor -| Name | Type | Readable| Writable| Description | +| Name | Type | Read-Only| Optional| Description | | ----- | ------ | ---- | ---- | -------------------------------------- | | x | number | Yes | Yes | Uncalibrated magnetic field strength on the x-axis, in ÎĽT. | | y | number | Yes | Yes | Uncalibrated magnetic field strength on the y-axis, in ÎĽT. | @@ -4519,7 +6344,7 @@ Describes the pedometer sensor data. It extends from [Response](#response). **System capability**: SystemCapability.Sensors.Sensor -| Name | Type | Readable| Writable| Description | +| Name | Type | Read-Only| Optional| Description | | ----- | ------ | ---- | ---- | ---------------- | | steps | number | Yes | Yes | Number of steps a user has walked.| @@ -4531,7 +6356,7 @@ Describes the humidity sensor data. It extends from [Response](#response). **System capability**: SystemCapability.Sensors.Sensor -| Name | Type | Readable| Writable| Description | +| Name | Type | Read-Only| Optional| Description | | -------- | ------ | ---- | ---- | --------------------------------------------------------- | | humidity | number | Yes | Yes | Ambient relative humidity, in a percentage (%).| @@ -4543,7 +6368,7 @@ Describes the pedometer detection sensor data. It extends from [Response](#respo **System capability**: SystemCapability.Sensors.Sensor -| Name | Type | Readable| Writable| Description | +| Name | Type | Read-Only| Optional| Description | | ------ | ------ | ---- | ---- | ------------------------------------------------------------ | | scalar | number | Yes | Yes | Pedometer detection. This parameter specifies whether a user takes a step. The value **0** means that the user does not take a step, and **1** means that the user takes a step.| @@ -4555,7 +6380,7 @@ Describes the ambient temperature sensor data. It extends from [Response](#respo **System capability**: SystemCapability.Sensors.Sensor -| Name | Type | Readable| Writable| Description | +| Name | Type | Read-Only| Optional| Description | | ----------- | ------ | ---- | ---- | -------------------------- | | temperature | number | Yes | Yes | Ambient temperature, in degree Celsius.| @@ -4567,7 +6392,7 @@ Describes the barometer sensor data. It extends from [Response](#response). **System capability**: SystemCapability.Sensors.Sensor -| Name | Type | Readable| Writable| Description | +| Name | Type | Read-Only| Optional| Description | | -------- | ------ | ---- | ---- | ---------------------- | | pressure | number | Yes | Yes | Atmospheric pressure, in units of hPa.| @@ -4579,7 +6404,7 @@ Describes the heart rate sensor data. It extends from [Response](#response). **System capability**: SystemCapability.Sensors.Sensor -| Name | Type | Readable| Writable| Description | +| Name | Type | Read-Only| Optional| Description | | --------- | ------ | ---- | ---- | --------------------------------------- | | heartRate | number | Yes | Yes | Heart rate, in beats per minute (bpm).| @@ -4591,7 +6416,7 @@ Describes the wear detection sensor data. It extends from [Response](#response). **System capability**: SystemCapability.Sensors.Sensor -| Name | Type | Readable| Writable| Description | +| Name | Type | Read-Only| Optional| Description | | ----- | ------ | ---- | ---- | ------------------------------------------------ | | value | number | Yes | Yes | Whether the device is being worn. The value **1** means that the device is being worn, and **0** means the opposite.| @@ -4604,9 +6429,10 @@ Describes the sensor data reporting frequency. **System capability**: SystemCapability.Sensors.Sensor -| Name | Type | Readable| Writable| Description | +| Name | Type | Read-Only| Optional| Description | | -------- | ----------------------------------------------------------- | ---- | ---- | ------------------------------------------------------------ | | interval | number\|[SensorFrequency](#sensorfrequency11)11+ | Yes | Yes | Frequency at which a sensor reports data. The default value is 200,000,000 ns. The maximum and minimum values of this parameter are determined by the reporting frequency supported by the hardware. If the configured frequency is greater than the maximum value, the maximum value is used for data reporting. If the configured frequency is less than the minimum value, the minimum value is used for data reporting.| +| sensorInfoParam19+ | [SensorInfoParam](#sensorinfoparam19) | Yes| Yes| Sensor parameters, including **deviceId** and **sensorIndex**.| ## SensorFrequency11+ @@ -4630,7 +6456,7 @@ Describes the response for setting the rotation matrix. **System capability**: SystemCapability.Sensors.Sensor -| Name | Type | Readable| Writable| Description | +| Name | Type | Read-Only| Optional| Description | | ----------- | ------------------- | ---- | ---- | ---------- | | rotation | Array<number> | Yes | Yes | Rotation matrix.| | inclination | Array<number> | Yes | Yes | Inclination matrix.| @@ -4642,7 +6468,7 @@ Describes the coordinate options. **System capability**: SystemCapability.Sensors.Sensor -| Name| Type | Readable| Writable| Description | +| Name| Type | Read-Only| Optional| Description | | ---- | ------ | ---- | ---- | ----------- | | x | number | Yes | Yes | X coordinate direction.| | y | number | Yes | Yes | Y coordinate direction.| @@ -4654,7 +6480,7 @@ Describes a geomagnetic response object. **System capability**: SystemCapability.Sensors.Sensor -| Name | Type | Readable| Writable| Description | +| Name | Type | Read-Only| Optional| Description | | --------------- | ------ | ---- | ---- | -------------------------------------------------- | | x | number | Yes | Yes | North component of the geomagnetic field. | | y | number | Yes | Yes | East component of the geomagnetic field. | @@ -4670,7 +6496,7 @@ Describes the geographical location. **System capability**: SystemCapability.Sensors.Sensor -| Name | Type | Readable| Writable| Description | +| Name | Type | Read-Only| Optional| Description | | --------- | ------ | ---- | ---- | ---------- | | latitude | number | Yes | Yes | Latitude. | | longitude | number | Yes | Yes | Longitude. | diff --git a/en/application-dev/reference/apis-sensor-service-kit/js-apis-system-sensor.md b/en/application-dev/reference/apis-sensor-service-kit/js-apis-system-sensor.md index 8abb67ec08b..a7f38c169ea 100644 --- a/en/application-dev/reference/apis-sensor-service-kit/js-apis-system-sensor.md +++ b/en/application-dev/reference/apis-sensor-service-kit/js-apis-system-sensor.md @@ -371,7 +371,7 @@ Sensor.unsubscribeHeartRate(); subscribeOnBodyState(options: SubscribeOnBodyStateOptions): void -Subscribes to changes of the wearing state of a wearable device. If this API is called multiple times for the same application, the last call takes effect. +Subscribes to wearing status changes of a wearable device. If this API is called multiple times for the same application, the last call takes effect. **System capability**: SystemCapability.Sensors.Sensor.Lite @@ -404,7 +404,7 @@ Sensor.subscribeOnBodyState(subscribeOnBodyStateOptions); unsubscribeOnBodyState(): void -Unsubscribes from changes of the wearing state of a wearable device. +Unsubscribes from wearing status changes of a wearable device. **System capability**: SystemCapability.Sensors.Sensor.Lite @@ -426,7 +426,7 @@ Obtains the wearing state of a wearable device. | Name | Type | Mandatory| Description | | ------- | ----------------------------------------------- | ---- | -------------------------- | -| options | [GetOnBodyStateOptions](#getonbodystateoptions) | Yes | Type of data to return.| +| options | [GetOnBodyStateOptions](#getonbodystateoptions) | Yes | Callback invoked when obtaining the wearing state of the device that accommodates the sensor.| **Example** @@ -554,7 +554,7 @@ Sensor.unsubscribeGyroscope(); ## subscribeAccelerometerOptions -Defines the type of data to return for a subscription to the acceleration sensor data. +Defines the type of data to return for a subscription to data changes of the acceleration sensor. **Required permissions**: ohos.permission.ACCELEROMETER @@ -563,12 +563,12 @@ Defines the type of data to return for a subscription to the acceleration sensor | Name | Type | Mandatory| Description | | -------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | | interval | string | Yes | Execution frequency of the callback for returning the acceleration sensor data.
The default value is **normal**. The options are as follows:
- **game**: called at an interval of 20 ms, which is applicable to gaming scenarios.
- **ui**: called at an interval of 60 ms, which is applicable to UI updating scenarios.
- **normal**: called at an interval of 200 ms, which is applicable to power-saving scenarios.| -| success | [AccelerometerResponse](#accelerometerresponse) | Yes | Called when the acceleration sensor data changes. | -| fail | Function | No | Callback upon an API call failure. | +| success | [AccelerometerResponse](#accelerometerresponse) | Yes | Callback invoked when the acceleration sensor data changes. | +| fail | Function | No | Callback invoked when an API call fails. | ## AccelerometerResponse -Defines the type of data to include in an **AccelerometerResponse** object. +Defines the callback invoked when the acceleration sensor data changes. **Required permissions**: ohos.permission.ACCELEROMETER @@ -582,18 +582,18 @@ Defines the type of data to include in an **AccelerometerResponse** object. ## SubscribeCompassOptions -Defines the type of data to return for a subscription to the compass sensor data. +Defines the type of data to return for a subscription to data changes of the compass sensor. **System capability**: SystemCapability.Sensors.Sensor.Lite | Name | Type | Mandatory| Description | | ------- | ----------------------------------- | ---- | ------------------------------ | -| success | [CompassResponse](#compassresponse) | Yes | Called when the compass sensor data changes.| -| fail | Function | No | Callback upon an API call failure. | +| success | [CompassResponse](#compassresponse) | Yes | Callback invoked when the compass sensor data changes.| +| fail | Function | No | Callback invoked when an API call fails. | ## CompassResponse -Defines the type of data to include in a **CompassResponse** object. +Defines a **CompassResponse** object. **System capability**: SystemCapability.Sensors.Sensor.Lite @@ -603,18 +603,18 @@ Defines the type of data to include in a **CompassResponse** object. ## SubscribeProximityOptions -Defines the type of data to return for a subscription to the proximity sensor data. +Defines the type of data to return for a subscription to data changes of the proximity sensor. **System capability**: SystemCapability.Sensors.Sensor.Lite | Name | Type | Mandatory| Description | | ------- | --------------------------------------- | ---- | ---------------------------------- | -| success | [ProximityResponse](#proximityresponse) | Yes | Defines the type of data to include in a **ProximityResponse** object.| -| fail | Function | No | Callback upon an API call failure. | +| success | [ProximityResponse](#proximityresponse) | Yes | Defines a **ProximityResponse** object.| +| fail | Function | No | Callback invoked when an API call fails. | ## ProximityResponse -Called when the proximity sensor data changes. +Callback invoked when the proximity sensor data changes. **System capability**: SystemCapability.Sensors.Sensor.Lite @@ -624,18 +624,18 @@ Called when the proximity sensor data changes. ## SubscribeLightOptions -Defines the type of data to return for a subscription to the ambient light sensor data. +Defines the type of data to return for a subscription to data changes of the ambient light sensor. **System capability**: SystemCapability.Sensors.Sensor.Lite | Name | Type | Mandatory| Description | | ------- | ------------------------------- | ---- | ------------------------------ | -| success | [LightResponse](#lightresponse) | Yes | Called when the ambient light sensor data changes.| -| fail | Function | No | Callback upon an API call failure. | +| success | [LightResponse](#lightresponse) | Yes | Callback invoked when the ambient light sensor data changes.| +| fail | Function | No | Callback invoked when an API call fails. | ## LightResponse -Defines the type of data to include in a **LightResponse** object. +Defines a **LightResponse** object. **System capability**: SystemCapability.Sensors.Sensor.Lite @@ -645,7 +645,7 @@ Defines the type of data to include in a **LightResponse** object. ## SubscribeStepCounterOptions -Defines the type of data to return for a subscription to the step counter sensor data. +Defines the type of data to return for a subscription to data changes of the step counter sensor. **Required permissions**: ohos.permission.ACTIVITY_MOTION @@ -653,12 +653,12 @@ Defines the type of data to return for a subscription to the step counter sensor | Name | Type | Mandatory| Description | | ------- | ------------------------------------------- | ---- | -------------------------------- | -| success | [StepCounterResponse](#stepcounterresponse) | Yes | Defines the type of data to include in a **StepCounterResponse** object.| -| fail | Function | No | Callback upon an API call failure. | +| success | [StepCounterResponse](#stepcounterresponse) | Yes | Defines a **StepCounterResponse** object.| +| fail | Function | No | Callback invoked when an API call fails. | ## StepCounterResponse -Called when the step counter sensor data changes. +Callback invoked when the step counter sensor data changes. **Required permissions**: ohos.permission.ACTIVITY_MOTION @@ -670,18 +670,18 @@ Called when the step counter sensor data changes. ## SubscribeBarometerOptions -Defines the type of data to return for a subscription to the barometer sensor data. +Defines the type of data to return for a subscription to data changes of the barometer sensor. **System capability**: SystemCapability.Sensors.Sensor.Lite | Name | Type | Mandatory| Description | | ------- | --------------------------------------- | ---- | -------------------------------- | -| success | [BarometerResponse](#barometerresponse) | Yes | Called when the barometer sensor data changes.| -| fail | Function | No | Callback upon an API call failure. | +| success | [BarometerResponse](#barometerresponse) | Yes | Callback invoked when the barometer sensor data changes.| +| fail | Function | No | Callback invoked when an API call fails. | ## BarometerResponse -Defines the type of data to include in a **BarometerResponse** object. +Defines a **BarometerResponse** object. **System capability**: SystemCapability.Sensors.Sensor.Lite @@ -691,7 +691,7 @@ Defines the type of data to include in a **BarometerResponse** object. ## SubscribeHeartRateOptions -Defines the type of data to return for a subscription to the heart rate sensor data. +Defines the type of data to return for a subscription to data changes of the heart rate sensor. **Required permissions**: ohos.permission.READ_HEALTH_DATA @@ -699,12 +699,12 @@ Defines the type of data to return for a subscription to the heart rate sensor d | Name | Type | Mandatory| Description | | ------- | --------------------------------------- | ---- | ----------------------------------------------- | -| success | [HeartRateResponse](#heartrateresponse) | Yes | Called when the heart rate sensor data changes. This callback is invoked every five seconds.| -| fail | Function | No | Callback upon an API call failure. | +| success | [HeartRateResponse](#heartrateresponse) | Yes | Callback invoked when the heart rate sensor data changes. This callback is invoked every five seconds.| +| fail | Function | No | Callback invoked when an API call fails. | ## HeartRateResponse -Defines the type of data to include in a **HeartRateResponse** object. +Defines a **HeartRateResponse** object. **Required permissions**: ohos.permission.READ_HEALTH_DATA @@ -716,18 +716,18 @@ Defines the type of data to include in a **HeartRateResponse** object. ## SubscribeOnBodyStateOptions -Defines the type of data to return for a subscription to the wearing state changes. +Defines the callback invoked upon change in the wearing state of the device that accommodates the sensor. **System capability**: SystemCapability.Sensors.Sensor.Lite | Name | Type | Mandatory| Description | | ------- | ------------------------------------------- | ---- | -------------------------- | -| success | [OnBodyStateResponse](#onbodystateresponse) | Yes | Called when the wearing state changes.| -| fail | Function | No | Callback upon an API call failure. | +| success | [OnBodyStateResponse](#onbodystateresponse) | Yes | Callback invoked when obtaining the wearing state change of the device that accommodates the sensor.| +| fail | Function | No | Callback invoked when an API call fails. | ## OnBodyStateResponse -Defines the wearing state. +Whether the device where the sensor is located is worn. **System capability**: SystemCapability.Sensors.Sensor.Lite @@ -737,31 +737,31 @@ Defines the wearing state. ## GetOnBodyStateOptions - Defines the type of data to return for obtaining the wearing state. + Defines the callback for obtaining the wearing state of the device that accommodates the sensor. **System capability**: SystemCapability.Sensors.Sensor.Lite | Name | Type | Mandatory| Description | | -------- | ------------------------------------------- | ---- | ------------------------ | | success | [OnBodyStateResponse](#onbodystateresponse) | Yes | Callback upon a successful API call.| -| fail | Function | No | Callback upon an API call failure.| -| complete | Function | No | Called when the API call is complete.| +| fail | Function | No | Callback invoked when an API call fails.| +| complete | Function | No | Callback invoked when the API call is complete.| ## SubscribeDeviceOrientationOptions6+ -Defines the type of data to return for a subscription to the device orientation sensor data. +Defines the type of data to return for a subscription to data changes of the device orientation sensor. **System capability**: SystemCapability.Sensors.Sensor.Lite | Name | Type | Mandatory| Description | | -------- | -------------------------------------------------------- | ---- | ------------------------------------------------------------ | | interval | string | Yes | Interval at which the callback is invoked to return the device orientation sensor data.
The default value is **normal**. The options are as follows:
- **game**: called at an interval of 20 ms, which is applicable to gaming scenarios.
- **ui**: called at an interval of 60 ms, which is applicable to UI updating scenarios.
- **normal**: called at an interval of 200 ms, which is applicable to power-saving scenarios.| -| success | [DeviceOrientationResponse](#deviceorientationresponse6) | Yes | Called when the device orientation sensor data changes. | -| fail | Function | No | Callback upon an API call failure. | +| success | [DeviceOrientationResponse](#deviceorientationresponse6) | Yes | Callback invoked when the device orientation sensor data changes. | +| fail | Function | No | Callback invoked when an API call fails. | ## DeviceOrientationResponse6+ -Defines the type of data to include in a **DeviceOrientationResponse** object. +Defines a **DeviceOrientationResponse** object. **System capability**: SystemCapability.Sensors.Sensor.Lite @@ -773,7 +773,7 @@ Defines the type of data to include in a **DeviceOrientationResponse** object. ## SubscribeGyroscopeOptions6+ -Defines the type of data to return for a subscription to the gyroscope sensor data. +Defines the type of data to return for a subscription to data changes of the gyroscope sensor. **Required permissions**: ohos.permission.GYROSCOPE @@ -782,12 +782,12 @@ Defines the type of data to return for a subscription to the gyroscope sensor da | Name | Type | Mandatory| Description | | -------- | ---------------------------------------- | ---- | ------------------------------------------------------------ | | interval | string | Yes | Interval at which the callback is invoked to return the gyroscope sensor data.
The default value is **normal**. The options are as follows:
- **game**: called at an interval of 20 ms, which is applicable to gaming scenarios.
- **ui**: called at an interval of 60 ms, which is applicable to UI updating scenarios.
- **normal**: called at an interval of 200 ms, which is applicable to power-saving scenarios.| -| success | [GyroscopeResponse](#gyroscoperesponse6) | Yes | Called when the gyroscope sensor data changes. | -| fail | Function | No | Callback upon an API call failure. | +| success | [GyroscopeResponse](#gyroscoperesponse6) | Yes | Callback invoked when the gyroscope sensor data changes. | +| fail | Function | No | Callback invoked when an API call fails. | ## GyroscopeResponse6+ -Defines the type of data to include in a **GyroscopeResponse** object. +Defines a **GyroscopeResponse** object. **Required permissions**: ohos.permission.GYROSCOPE diff --git a/en/application-dev/reference/apis-sensor-service-kit/js-apis-vibrator.md b/en/application-dev/reference/apis-sensor-service-kit/js-apis-vibrator.md index e1887eb27ac..6fa3015d7bc 100644 --- a/en/application-dev/reference/apis-sensor-service-kit/js-apis-vibrator.md +++ b/en/application-dev/reference/apis-sensor-service-kit/js-apis-vibrator.md @@ -29,7 +29,7 @@ Starts vibration with the specified effect and attribute. This API uses an async | Name | Type | Mandatory| Description | | --------- | -------------------------------------- | ---- | :----------------------------------------------------------- | -| effect | [VibrateEffect](#vibrateeffect9) | Yes | Vibration effect. The following options are supported:
- [VibrateTime](#vibratetime9): starts vibration of the specified duration. This mode is not recommended because there is no start or stop.
- [VibratePreset](#vibratepreset9): starts vibration based on the preset effect. This mode is applicable to short vibration scenarios.
- [VibrateFromFile](#vibratefromfile10): starts the vibration according to a custom vibration configuration file. This mode is applicable to short vibration scenarios.
- [VibrateFromPattern18+](#vibratefrompattern18): starts vibration according to a custom vibration pattern.| +| effect | [VibrateEffect](#vibrateeffect9) | Yes | Vibration effect. The following options are supported:
1. [VibratePreset](#vibratepreset9): triggers vibration according to preset vibration effects. This mode is suitable for short vibration scenarios in interactive feedback (such as tapping, long-pressing, sliding, dragging, etc.). This API is recommended to maintain consistency with the system's overall vibration feedback experience.
2. [VibrateFromFile](#vibratefromfile10): triggers vibration according to custom vibration configuration file. This mode is suitable for interactive feedback in complex scenarios requiring precise vibration patterns (such as realistic effects triggered by emoji packs, or feedback for in-game actions/mechanics).
3. [VibrateTime](#vibratetime9): triggers vibration of the specified duration, providing basic control over the start and stop of vibration. This mode does not support customization of vibration intensity, frequency, or other parameters. As a result, the vibration adjustment is relatively coarse and not suitable for delivering a refined experience.
- [VibrateFromPattern18+](#vibratefrompattern18): starts vibration according to a custom vibration pattern. The usage scenario is the same as **VibrateFromFile**. **VibrateFromFile** utilizes predefined effects in a custom configuration file, passing specific vibration events to the API via file descriptors. By contrast, **VibrateFromPattern** enables more flexible vibration event combinations, delivering them to the API as a vibration event array.
| | attribute | [VibrateAttribute](#vibrateattribute9) | Yes | Vibration attribute. | | callback | AsyncCallback<void> | Yes | Callback used to return the operation result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object, which contains the error code and error information.| @@ -48,121 +48,121 @@ For details about the error codes, see [Vibrator Error Codes](errorcode-vibrator 1. Start vibration based on the preset effect. -```ts -import { vibrator } from '@kit.SensorServiceKit'; -import { BusinessError } from '@kit.BasicServicesKit'; - -try { - // Check whether 'haptic.clock.timer' is supported. - vibrator.isSupportEffect('haptic.clock.timer', (err: BusinessError, state: boolean) => { - if (err) { - console.error(`Failed to query effect. Code: ${err.code}, message: ${err.message}`); - return; - } - console.info('Succeed in querying effect'); - if (state) { - try { - vibrator.startVibration({ - type: 'preset', - effectId: 'haptic.clock.timer', - count: 1, - }, { - usage: 'alarm' // The switch control is subject to the selected type. - }, (error: BusinessError) => { - if (error) { - console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`); - return; - } - console.info('Succeed in starting vibration'); + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + try { + // Check whether 'haptic.notice.success' is supported. + vibrator.isSupportEffect('haptic.notice.success', (err: BusinessError, state: boolean) => { + if (err) { + console.error(`Failed to query effect. Code: ${err.code}, message: ${err.message}`); + return; + } + console.info('Succeed in querying effect'); + if (state) { + try { + vibrator.startVibration({ + type: 'preset', + effectId: 'haptic.notice.success', + count: 1, + }, { + usage: 'notification' // The switch control is subject to the selected type. + }, (error: BusinessError) => { + if (error) { + console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`); + return; + } + console.info('Succeed in starting vibration'); - }); - } catch (err) { - let e: BusinessError = err as BusinessError; - console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); - } - } - }) -} catch (error) { - let e: BusinessError = error as BusinessError; - console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); -} -``` + }); + } catch (err) { + let e: BusinessError = err as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + } + }) + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` 2. Start vibration according to the custom vibration configuration file. -```ts -import { vibrator } from '@kit.SensorServiceKit'; -import { resourceManager } from '@kit.LocalizationKit'; -import { BusinessError } from '@kit.BasicServicesKit'; - -const fileName: string = 'xxx.json'; - -@Entry -@Component -struct Index { - uiContext = this.getUIContext(); - - build() { - Row() { - Column() { - Button('alarm-file') - .onClick(() => { - let rawFd: resourceManager.RawFileDescriptor | undefined = this.uiContext.getHostContext()?.resourceManager.getRawFdSync(fileName); - if (rawFd != undefined) { - try { - vibrator.startVibration({ - type: "file", - hapticFd: { fd: rawFd.fd, offset: rawFd.offset, length: rawFd.length } - }, { - id: 0, - usage: 'alarm' // The switch control is subject to the selected type. - }, (error: BusinessError) => { - if (error) { - console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`); - return; - } - console.info('Succeed in starting vibration'); - }); - } catch (err) { - let e: BusinessError = err as BusinessError; - console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); - } - } - this.uiContext.getHostContext()?.resourceManager.closeRawFdSync(fileName); - }) - } - .width('100%') - } - .height('100%') - } -} -``` + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { resourceManager } from '@kit.LocalizationKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + const fileName: string = 'xxx.json'; + + @Entry + @Component + struct Index { + uiContext = this.getUIContext(); + + build() { + Row() { + Column() { + Button('alarm-file') + .onClick(() => { + let rawFd: resourceManager.RawFileDescriptor | undefined = this.uiContext.getHostContext()?.resourceManager.getRawFdSync(fileName); + if (rawFd != undefined) { + try { + vibrator.startVibration({ + type: "file", + hapticFd: { fd: rawFd.fd, offset: rawFd.offset, length: rawFd.length } + }, { + id: 0, + usage: 'alarm' // The switch control is subject to the selected type. + }, (error: BusinessError) => { + if (error) { + console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`); + return; + } + console.info('Succeed in starting vibration'); + }); + } catch (err) { + let e: BusinessError = err as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + } + this.uiContext.getHostContext()?.resourceManager.closeRawFdSync(fileName); + }) + } + .width('100%') + } + .height('100%') + } + } + ``` 3. Start vibration of the specified duration. -```ts -import { vibrator } from '@kit.SensorServiceKit'; -import { BusinessError } from '@kit.BasicServicesKit'; - -try { - vibrator.startVibration({ - type: 'time', - duration: 1000, - }, { - id: 0, - usage: 'alarm' // The switch control is subject to the selected type. - }, (error: BusinessError) => { - if (error) { - console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`); - return; - } - console.info('Succeed in starting vibration'); - }); -} catch (err) { - let e: BusinessError = err as BusinessError; - console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); -} -``` + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + try { + vibrator.startVibration({ + type: 'time', + duration: 1000, + }, { + id: 0, + usage: 'alarm' // The switch control is subject to the selected type. + }, (error: BusinessError) => { + if (error) { + console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`); + return; + } + console.info('Succeed in starting vibration'); + }); + } catch (err) { + let e: BusinessError = err as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` ## vibrator.startVibration9+ @@ -180,7 +180,7 @@ Starts vibration with the specified effect and attribute. This API uses a promis | Name | Type | Mandatory| Description | | --------- | -------------------------------------- | ---- | ------------------------------------------------------------ | -| effect | [VibrateEffect](#vibrateeffect9) | Yes | Vibration effect. The following options are supported:
- [VibrateTime](#vibratetime9): starts vibration of the specified duration. This mode is not recommended because there is no start or stop.
- [VibratePreset](#vibratepreset9): starts vibration based on the preset effect. This mode is applicable to short vibration scenarios.
- [VibrateFromFile](#vibratefromfile10): starts vibration according to a custom vibration configuration file.
- [VibrateFromPattern18+](#vibratefrompattern18): starts vibration according to a custom vibration pattern.| +| effect | [VibrateEffect](#vibrateeffect9) | Yes | Vibration effect. The following options are supported:
- [VibratePreset](#vibratepreset9): triggers vibration according to preset vibration effects. This mode is suitable for short vibration scenarios in interactive feedback (such as tapping, long-pressing, sliding, dragging, etc.). This API is recommended to maintain consistency with the system's overall vibration feedback experience.
- [VibrateFromFile](#vibratefromfile10): triggers vibration according to custom vibration configuration file. This mode is suitable for interactive feedback in complex scenarios requiring precise vibration patterns (such as realistic effects triggered by emoji packs, or feedback for in-game actions/mechanics).
- [VibrateTime](#vibratetime9): triggers vibration of the specified duration, providing basic control over the start and stop of vibration. This mode does not support customization of vibration intensity, frequency, or other parameters. As a result, the vibration adjustment is relatively coarse and not suitable for delivering a refined experience.
- [VibrateFromPattern18+](#vibratefrompattern18): starts vibration according to a custom vibration pattern. The usage scenario is the same as **VibrateFromFile**. **VibrateFromFile** utilizes predefined effects in a custom configuration file, passing specific vibration events to the API via file descriptors. By contrast, **VibrateFromPattern** enables more flexible vibration event combinations, delivering them to the API as a vibration event array.| | attribute | [VibrateAttribute](#vibrateattribute9) | Yes | Vibration attribute. | **Return value** @@ -204,119 +204,119 @@ For details about the error codes, see [Vibrator Error Codes](errorcode-vibrator 1. Start vibration based on the preset effect. -```ts -import { vibrator } from '@kit.SensorServiceKit'; -import { BusinessError } from '@kit.BasicServicesKit'; - -try { - // Check whether 'haptic.clock.timer' is supported. - vibrator.isSupportEffect('haptic.clock.timer', (err: BusinessError, state: boolean) => { - if (err) { - console.error(`Failed to query effect. Code: ${err.code}, message: ${err.message}`); - return; - } - console.info('Succeed in querying effect'); - if (state) { - try { - vibrator.startVibration({ - type: 'preset', - effectId: 'haptic.clock.timer', - count: 1, - }, { - usage: 'alarm' // The switch control is subject to the selected type. - }, (error: BusinessError) => { - if (error) { - console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`); - return; - } - console.info('Succeed in starting vibration'); + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + try { + // Check whether 'haptic.notice.success' is supported. + vibrator.isSupportEffect('haptic.notice.success', (err: BusinessError, state: boolean) => { + if (err) { + console.error(`Failed to query effect. Code: ${err.code}, message: ${err.message}`); + return; + } + console.info('Succeed in querying effect'); + if (state) { + try { + vibrator.startVibration({ + type: 'preset', + effectId: 'haptic.notice.success', + count: 1, + }, { + usage: 'notification' // The switch control is subject to the selected type. + }, (error: BusinessError) => { + if (error) { + console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`); + return; + } + console.info('Succeed in starting vibration'); - }); - } catch (err) { - let e: BusinessError = err as BusinessError; - console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); - } - } - }) -} catch (error) { - let e: BusinessError = error as BusinessError; - console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); -} -``` + }); + } catch (err) { + let e: BusinessError = err as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + } + }) + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` 2. Start vibration according to the custom vibration configuration file. -```ts -import { vibrator } from '@kit.SensorServiceKit'; -import { resourceManager } from '@kit.LocalizationKit'; -import { BusinessError } from '@kit.BasicServicesKit'; - -const fileName: string = 'xxx.json'; - -@Entry -@Component -struct Index { - uiContext = this.getUIContext(); - - build() { - Row() { - Column() { - Button('alarm-file') - .onClick(() => { - let rawFd: resourceManager.RawFileDescriptor | undefined = this.uiContext.getHostContext()?.resourceManager.getRawFdSync(fileName); - if (rawFd != undefined) { - try { - vibrator.startVibration({ - type: "file", - hapticFd: { fd: rawFd.fd, offset: rawFd.offset, length: rawFd.length } - }, { - id: 0, - usage: 'alarm' // The switch control is subject to the selected type. - }, (error: BusinessError) => { - if (error) { - console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`); - return; - } - console.info('Succeed in starting vibration'); - }); - } catch (err) { - let e: BusinessError = err as BusinessError; - console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); - } - } - this.uiContext.getHostContext()?.resourceManager.closeRawFdSync(fileName); - }) - } - .width('100%') - } - .height('100%') - } -} -``` + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { resourceManager } from '@kit.LocalizationKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + const fileName: string = 'xxx.json'; + + @Entry + @Component + struct Index { + uiContext = this.getUIContext(); + + build() { + Row() { + Column() { + Button('alarm-file') + .onClick(() => { + let rawFd: resourceManager.RawFileDescriptor | undefined = this.uiContext.getHostContext()?.resourceManager.getRawFdSync(fileName); + if (rawFd != undefined) { + try { + vibrator.startVibration({ + type: "file", + hapticFd: { fd: rawFd.fd, offset: rawFd.offset, length: rawFd.length } + }, { + id: 0, + usage: 'alarm' // The switch control is subject to the selected type. + }, (error: BusinessError) => { + if (error) { + console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`); + return; + } + console.info('Succeed in starting vibration'); + }); + } catch (err) { + let e: BusinessError = err as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + } + this.uiContext.getHostContext()?.resourceManager.closeRawFdSync(fileName); + }) + } + .width('100%') + } + .height('100%') + } + } + ``` 3. Start vibration of the specified duration. -```ts -import { vibrator } from '@kit.SensorServiceKit'; -import { BusinessError } from '@kit.BasicServicesKit'; - -try { - vibrator.startVibration({ - type: 'time', - duration: 1000 - }, { - id: 0, - usage: 'alarm' // The switch control is subject to the selected type. - }).then(() => { - console.info('Succeed in starting vibration'); - }, (error: BusinessError) => { - console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`); - }); -} catch (err) { - let e: BusinessError = err as BusinessError; - console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); -} -``` + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + try { + vibrator.startVibration({ + type: 'time', + duration: 1000 + }, { + id: 0, + usage: 'alarm' // The switch control is subject to the selected type. + }).then(() => { + console.info('Succeed in starting vibration'); + }, (error: BusinessError) => { + console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`); + }); + } catch (err) { + let e: BusinessError = err as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` ## vibrator.stopVibration9+ @@ -346,88 +346,88 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ **Example** -Stop vibration of the specified duration. - -```ts -import { vibrator } from '@kit.SensorServiceKit'; -import { BusinessError } from '@kit.BasicServicesKit'; - -try { - // Start vibration of the specified duration. - vibrator.startVibration({ - type: 'time', - duration: 1000, - }, { - id: 0, - usage: 'alarm' // The switch control is subject to the selected type. - }, (error: BusinessError) => { - if (error) { - console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`); - return; - } - console.info('Succeed in starting vibration'); - }); -} catch (err) { - let e: BusinessError = err as BusinessError; - console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); -} - -try { - // Stop vibration in VIBRATOR_STOP_MODE_TIME mode. - vibrator.stopVibration(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_TIME, (error: BusinessError) => { - if (error) { - console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`); - return; - } - console.info('Succeed in stopping vibration'); - }) -} catch (err) { - let e: BusinessError = err as BusinessError; - console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); -} -``` - -Stop preset vibration. - -```ts -import { vibrator } from '@kit.SensorServiceKit'; -import { BusinessError } from '@kit.BasicServicesKit'; - -try { - // Start vibration with a preset effect. - vibrator.startVibration({ - type: 'preset', - effectId: 'haptic.clock.timer', - count: 1, - }, { - id: 0, - usage: 'alarm' // The switch control is subject to the selected type. - }, (error: BusinessError) => { - if (error) { - console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`); - return; - } - console.info('Succeed in starting vibration'); - }); -} catch (err) { - let e: BusinessError = err as BusinessError; - console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); -} - -try { - // Stop vibration in VIBRATOR_STOP_MODE_PRESET mode. - vibrator.stopVibration(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_PRESET, (error: BusinessError) => { - if (error) { - console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`); - return; - } - console.info('Succeed in stopping vibration'); - }) -} catch (err) { - let e: BusinessError = err as BusinessError; - console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); -} -``` +1. Stop vibration of the specified duration. + + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + try { + // Start vibration of the specified duration. + vibrator.startVibration({ + type: 'time', + duration: 1000, + }, { + id: 0, + usage: 'alarm' // The switch control is subject to the selected type. + }, (error: BusinessError) => { + if (error) { + console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`); + return; + } + console.info('Succeed in starting vibration'); + }); + } catch (err) { + let e: BusinessError = err as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + + try { + // Stop vibration in VIBRATOR_STOP_MODE_TIME mode. + vibrator.stopVibration(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_TIME, (error: BusinessError) => { + if (error) { + console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`); + return; + } + console.info('Succeed in stopping vibration'); + }) + } catch (err) { + let e: BusinessError = err as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` + +2. Stop vibration with the preset effect. + + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + try { + // Start vibration with a preset effect. + vibrator.startVibration({ + type: 'preset', + effectId: 'haptic.notice.success', + count: 1, + }, { + id: 0, + usage: 'notification' // The switch control is subject to the selected type. + }, (error: BusinessError) => { + if (error) { + console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`); + return; + } + console.info('Succeed in starting vibration'); + }); + } catch (err) { + let e: BusinessError = err as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + + try { + // Stop vibration in VIBRATOR_STOP_MODE_PRESET mode. + vibrator.stopVibration(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_PRESET, (error: BusinessError) => { + if (error) { + console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`); + return; + } + console.info('Succeed in stopping vibration'); + }) + } catch (err) { + let e: BusinessError = err as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` ## vibrator.stopVibration9+ @@ -462,80 +462,80 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ **Example** -Stop vibration of the specified duration. - -```ts -import { vibrator } from '@kit.SensorServiceKit'; -import { BusinessError } from '@kit.BasicServicesKit'; - -try { - // Start vibration of the specified duration. - vibrator.startVibration({ - type: 'time', - duration: 1000, - }, { - id: 0, - usage: 'alarm' // The switch control is subject to the selected type. - }).then(() => { - console.info('Succeed in starting vibration'); - }, (error: BusinessError) => { - console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`); - }); -} catch (err) { - let e: BusinessError = err as BusinessError; - console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); -} - -try { - // Stop vibration in VIBRATOR_STOP_MODE_TIME mode. - vibrator.stopVibration(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_TIME).then(() => { - console.info('Succeed in stopping vibration'); - }, (error: BusinessError) => { - console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`); - }); -} catch (err) { - let e: BusinessError = err as BusinessError; - console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); -} -``` - -Stop preset vibration. - -```ts -import { vibrator } from '@kit.SensorServiceKit'; -import { BusinessError } from '@kit.BasicServicesKit'; - -try { - // Start vibration with a preset effect. - vibrator.startVibration({ - type: 'preset', - effectId: 'haptic.clock.timer', - count: 1, - }, { - id: 0, - usage: 'alarm' // The switch control is subject to the selected type. - }).then(() => { - console.info('Succeed in starting vibration'); - }, (error: BusinessError) => { - console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`); - }); -} catch (err) { - let e: BusinessError = err as BusinessError; - console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); -} - -try { - // Stop vibration in VIBRATOR_STOP_MODE_PRESET mode. - vibrator.stopVibration(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_PRESET).then(() => { - console.info('Succeed in stopping vibration'); - }, (error: BusinessError) => { - console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`); - }); -} catch (err) { - let e: BusinessError = err as BusinessError; - console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); -} -``` +1. Stop vibration of the specified duration. + + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + try { + // Start vibration of the specified duration. + vibrator.startVibration({ + type: 'time', + duration: 1000, + }, { + id: 0, + usage: 'alarm' // The switch control is subject to the selected type. + }).then(() => { + console.info('Succeed in starting vibration'); + }, (error: BusinessError) => { + console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`); + }); + } catch (err) { + let e: BusinessError = err as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + + try { + // Stop vibration in VIBRATOR_STOP_MODE_TIME mode. + vibrator.stopVibration(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_TIME).then(() => { + console.info('Succeed in stopping vibration'); + }, (error: BusinessError) => { + console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`); + }); + } catch (err) { + let e: BusinessError = err as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` + +2. Stop vibration with the preset effect. + + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + try { + // Start vibration with a preset effect. + vibrator.startVibration({ + type: 'preset', + effectId: 'haptic.notice.success', + count: 1, + }, { + id: 0, + usage: 'notification' // The switch control is subject to the selected type. + }).then(() => { + console.info('Succeed in starting vibration'); + }, (error: BusinessError) => { + console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`); + }); + } catch (err) { + let e: BusinessError = err as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + + try { + // Stop vibration in VIBRATOR_STOP_MODE_PRESET mode. + vibrator.stopVibration(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_PRESET).then(() => { + console.info('Succeed in stopping vibration'); + }, (error: BusinessError) => { + console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`); + }); + } catch (err) { + let e: BusinessError = err as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` ## vibrator.stopVibration10+ @@ -565,24 +565,24 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ **Example** -```ts -import { vibrator } from '@kit.SensorServiceKit'; -import { BusinessError } from '@kit.BasicServicesKit'; - -try { - // Stop vibration in all modes. - vibrator.stopVibration((error: BusinessError) => { - if (error) { - console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`); - return; - } - console.info('Succeed in stopping vibration'); - }) -} catch (error) { - let e: BusinessError = error as BusinessError; - console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); -} -``` + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + try { + // Stop vibration in all modes. + vibrator.stopVibration((error: BusinessError) => { + if (error) { + console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`); + return; + } + console.info('Succeed in stopping vibration'); + }) + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` ## vibrator.stopVibration10+ @@ -612,22 +612,71 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ **Example** -```ts -import { vibrator } from '@kit.SensorServiceKit'; -import { BusinessError } from '@kit.BasicServicesKit'; - -try { - // Stop vibration in all modes. - vibrator.stopVibration().then(() => { - console.info('Succeed in stopping vibration'); - }, (error: BusinessError) => { - console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`); - }); -} catch (error) { - let e: BusinessError = error as BusinessError; - console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); -} -``` + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + try { + // Stop vibration in all modes. + vibrator.stopVibration().then(() => { + console.info('Succeed in stopping vibration'); + }, (error: BusinessError) => { + console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`); + }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` + +## vibrator.stopVibration19+ + +stopVibration(param?: VibratorInfoParam): Promise<void> + +Stops vibration based on the specified vibrator parameters. If no parameters are passed, this API stops all vibrators of the local device by default. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.VIBRATE + +**System capability**: SystemCapability.Sensors.MiscDevice + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------------ | ---- |-----------------------------------| +| param | [VibratorInfoParam](#vibratorinfoparam19) | No | Vibrator parameters, such as the specified device and vibrator. If this parameter is left unspecified, this API applies to all vibrators of the local device by default.| + +**Return value** + +| Type | Description | +| ------------------- | ------------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). + +| ID| Error Message | +| -------- | ------------------ | +| 201 | Permission denied. | +| 14600101 | Device operation failed. | + +**Example** + + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + try { + vibrator.stopVibration({ deviceId: 1, vibratorId: 3 }).then(() => { + console.info('Succeed in stopping vibration'); + }, (error: BusinessError) => { + console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`); + }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` ## vibrator.stopVibrationSync12+ @@ -652,19 +701,19 @@ For details about the error codes, see [Vibrator Error Codes](errorcode-vibrator **Example** -```ts -import { vibrator } from '@kit.SensorServiceKit'; -import { BusinessError } from '@kit.BasicServicesKit'; - -try { - // Stop any form of motor vibration. - vibrator.stopVibrationSync() - console.info('Succeed in stopping vibration'); -} catch (error) { - let e: BusinessError = error as BusinessError; - console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); -} -``` + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + try { + // Stop any form of motor vibration. + vibrator.stopVibrationSync() + console.info('Succeed in stopping vibration'); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` ## vibrator.isSupportEffect10+ @@ -678,7 +727,7 @@ Checks whether an effect ID is supported. This API uses an asynchronous callback | Name | Type | Mandatory| Description | | -------- | ---------------------------- | ---- | ----------------------------------------------------------- | -| effectId | string | Yes | Vibration effect ID. | +| effectId | string | Yes | ID of the preset vibration effect. | | callback | AsyncCallback<boolean> | Yes | Callback used to return the result. The value **true** means that the effect ID is supported, and the value **false** means the opposite.| **Error codes** @@ -692,45 +741,45 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ **Example** -```ts -import { vibrator } from '@kit.SensorServiceKit'; -import { BusinessError } from '@kit.BasicServicesKit'; - -try { - // Check whether 'haptic.clock.timer' is supported. - vibrator.isSupportEffect('haptic.clock.timer', (err: BusinessError, state: boolean) => { - if (err) { - console.error(`Failed to query effect. Code: ${err.code}, message: ${err.message}`); - return; - } - console.info('Succeed in querying effect'); - if (state) { - try { - // To use startVibration, you must configure the ohos.permission.VIBRATE permission. - vibrator.startVibration({ - type: 'preset', - effectId: 'haptic.clock.timer', - count: 1, - }, { - usage: 'unknown' // The switch control is subject to the selected type. - }, (error: BusinessError) => { - if (error) { - console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`); - } else { - console.info('Succeed in starting vibration'); - } - }); - } catch (error) { - let e: BusinessError = error as BusinessError; - console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); - } - } - }) -} catch (error) { - let e: BusinessError = error as BusinessError; - console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); -} -``` + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + try { + // Check whether 'haptic.notice.success' is supported. + vibrator.isSupportEffect('haptic.notice.success', (err: BusinessError, state: boolean) => { + if (err) { + console.error(`Failed to query effect. Code: ${err.code}, message: ${err.message}`); + return; + } + console.info('Succeed in querying effect'); + if (state) { + try { + // To use startVibration, you must configure the ohos.permission.VIBRATE permission. + vibrator.startVibration({ + type: 'preset', + effectId: 'haptic.notice.success', + count: 1, + }, { + usage: 'unknown' // The switch control is subject to the selected type. + }, (error: BusinessError) => { + if (error) { + console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`); + } else { + console.info('Succeed in starting vibration'); + } + }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + } + }) + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` ## vibrator.isSupportEffect10+ @@ -742,9 +791,9 @@ Checks whether an effect ID is supported. This API uses a promise to return the **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------ | ---- | ---------------- | -| effectId | string | Yes | Vibration effect ID.| +| Name | Type | Mandatory| Description | +| -------- | ------ | ---- | ---------------------- | +| effectId | string | Yes | ID of the preset vibration effect.| **Return value** @@ -763,40 +812,40 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ **Example** -```ts -import { vibrator } from '@kit.SensorServiceKit'; -import { BusinessError } from '@kit.BasicServicesKit'; - -try { - // Check whether 'haptic.clock.timer' is supported. - vibrator.isSupportEffect('haptic.clock.timer').then((state: boolean) => { - console.info(`The query result is ${state}`); - if (state) { - try { - vibrator.startVibration({ - type: 'preset', - effectId: 'haptic.clock.timer', - count: 1, - }, { - usage: 'unknown' // The switch control is subject to the selected type. - }).then(() => { - console.info('Succeed in starting vibration'); - }).catch((error: BusinessError) => { - console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`); - }); - } catch (error) { - let e: BusinessError = error as BusinessError; - console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); - } - } - }, (error: BusinessError) => { - console.error(`Failed to query effect. Code: ${error.code}, message: ${error.message}`); - }) -} catch (error) { - let e: BusinessError = error as BusinessError; - console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); -} -``` + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + try { + // Check whether 'haptic.notice.success' is supported. + vibrator.isSupportEffect('haptic.notice.success').then((state: boolean) => { + console.info(`The query result is ${state}`); + if (state) { + try { + vibrator.startVibration({ + type: 'preset', + effectId: 'haptic.notice.success', + count: 1, + }, { + usage: 'unknown' // The switch control is subject to the selected type. + }).then(() => { + console.info('Succeed in starting vibration'); + }).catch((error: BusinessError) => { + console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`); + }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + } + }, (error: BusinessError) => { + console.error(`Failed to query effect. Code: ${error.code}, message: ${error.message}`); + }) + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` ## vibrator.isSupportEffectSync12+ @@ -808,8 +857,8 @@ Checks whether the preset vibration effect is supported. **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------ | ---- | -------------------- | +| Name | Type | Mandatory| Description | +| -------- | ------ | ---- | ---------------------- | | effectId | string | Yes | ID of the preset vibration effect.| **Return value** @@ -829,19 +878,247 @@ For details about the error codes, see [Vibrator Error Codes](errorcode-vibrator **Example** -```ts -import { vibrator } from '@kit.SensorServiceKit'; -import { BusinessError } from '@kit.BasicServicesKit'; - -try { - // Check whether the preset 'haptic.clock.timer' is supported. - let ret = vibrator.isSupportEffectSync('haptic.clock.timer'); - console.info(`The query result is ${ret}`); -} catch (error) { - let e: BusinessError = error as BusinessError; - console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); -} -``` + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + try { + // Check whether the preset 'haptic.notice.success' is supported. + let ret = vibrator.isSupportEffectSync('haptic.notice.success'); + console.info(`The query result is ${ret}`); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` + +## vibrator.getEffectInfoSync19+ + +getEffectInfoSync(effectId: string, param?: VibratorInfoParam): EffectInfo; + +Obtains the preset vibration effect based on the device ID and vibrator ID to determine whether the preset vibration effect is supported. + +**System capability**: SystemCapability.Sensors.MiscDevice + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------------ | ---- |-----------------------------| +| effectId | string | Yes | ID of the preset vibration effect. | +| param | [VibratorInfoParam](#vibratorinfoparam19) | No | Device ID and vibrator ID. If this parameter is left unspecified, this API applies to the local device by default.| + +**Error codes** + +For details about the error codes, see [Vibrator Error Codes](errorcode-vibrator.md). + +| ID| Error Message | +| -------- | ------------------------ | +| 14600101 | Device operation failed. | + +**Return value** + +| Type | Description | +| ------- | --------------------------------------------------------- | +| [EffectInfo](#effectinfo19) | Whether the preset vibration effect is supported.| + + +**Example** + + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + try { + const effectInfo: vibrator.EffectInfo = vibrator.getEffectInfoSync('haptic.clock.timer', { deviceId: 1, vibratorId: 3}); + console.log(`isEffectSupported: ${effectInfo.isEffectSupported}`); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` + + +## vibrator.getVibratorInfoSync19+ + +getVibratorInfoSync(param?: VibratorInfoParam): Array<VibratorInfo>; + +Queries the vibrator list of one or all devices. + +**System capability**: SystemCapability.Sensors.MiscDevice + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- |-----------------------------------------| ---- |-----------------------------------| +| param | [VibratorInfoParam](#vibratorinfoparam19) | No | Vibrator parameters, such as the specified device and vibrator. If this parameter is left unspecified, this API applies to all vibrators of the local device by default.| + +**Return value** + +| Type | Description | +|-------------------------------| --------------------------------------------------------- | +| [VibratorInfo](#vibratorinfo19) | Vibrator information.| + + +**Example** + + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + try { + const vibratorInfoList: vibrator.VibratorInfo[] = vibrator.getVibratorInfoSync({ deviceId: 1, vibratorId: 3 }); + console.log(`vibratorInfoList: ${JSON.stringify(vibratorInfoList)}`); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` + + +## vibrator.on19+ + +on(type: 'vibratorStateChange', callback: Callback<VibratorStatusEvent>): void + +Enables listening for vibrator status changes. + +**System capability**: SystemCapability.Sensors.MiscDevice + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------------- | +| type | 'vibratorStateChange' | Yes | Event type. The value **vibratorStateChange** indicates a vibrator online/offline event. | +| callback | Callback<[VibratorStatusEvent](#vibratorstatusevent19)> | Yes | Callback used to return the vibrator status change event.| + +**Error codes** + +For details about the error codes, see [Vibrator Error Codes](errorcode-vibrator.md). + +| ID| Error Message | +| -------- | ------------------------ | +| 14600101 | Device operation failed. | + + +**Example** + + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + // Callback + const vibratorStateChangeCallback = (data: vibrator.VibratorStatusEvent) => { + console.log('vibrator state callback info:', JSON.stringify(data)); + } + + try { + // Subscribe to vibratorStateChange events. + vibrator.on('vibratorStateChange', vibratorStateChangeCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` + + +## vibrator.off19+ + +off(type: 'vibratorStateChange', callback?: Callback<VibratorStatusEvent>): void + +Disables listening for vibrator status changes. + +**System capability**: SystemCapability.Sensors.MiscDevice + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------------- | +| type | 'vibratorStateChange' | Yes | Event type. The value **vibratorStateChange** indicates a vibrator online/offline event. | +| callback | Callback<[VibratorStatusEvent](#vibratorstatusevent19)> | No | Callback used to return the vibrator status change event. If this parameter is not specified, all callbacks of vibrator status change events will be unregistered.| + +**Error codes** + +For details about the error codes, see [Vibrator Error Codes](errorcode-vibrator.md). + +| ID| Error Message | +| -------- | ------------------------ | +| 14600101 | Device operation failed. | + + +**Example** + + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + // Callback + const vibratorStateChangeCallback = (data: vibrator.VibratorStatusEvent) => { + console.log('vibrator state callback info:', JSON.stringify(data)); + } + try { + // Unsubscribe from specified vibratorStateChange events. + vibrator.off('vibratorStateChange', vibratorStateChangeCallback); + // Unsubscribe from all vibratorStateChange events. + // vibrator.off('vibratorStateChange'); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` + + +## VibratorStatusEvent19+ + +Defines the vibrator status change event. + +**System capability**: SystemCapability.Sensors.MiscDevice + + +| Name| Type | Description | +| ---- | ------ |----------------------------------| +| timestamp | number | Event timestamp. | +| deviceId | number | Device ID. | +| vibratorCount | number | Number of vibrators on the device. | +| isVibratorOnline | boolean | Vibrator status. The value **true** indicates that the device is online, and the value **false** indicates the opposite.| + + +## VibratorInfoParam19+ + +Defines the vibrator parameters. If **VibratorInfoParam** is left unspecified, an API applies to all vibrators of the local device by default. + +**System capability**: SystemCapability.Sensors.MiscDevice + + +| Name| Type | Read-Only| Optional| Description | +| ---- | ------ | ---- | ---- |------------------------------------------------------------| +| deviceId | number | No | Yes | Device ID. The default value is **-1**, which indicates the local device. You can use [getEffectInfoSync](#vibratorgeteffectinfosync19) to query other device IDs.| +| vibratorId | number | No | Yes | Vibrator ID. The default value is **-1**, which indicates all vibrator of the local device. You can use [getEffectInfoSync](#vibratorgeteffectinfosync19) to query other vibrator IDs. | + + + +## EffectInfo19+ + +Defines the preset effect. + +**System capability**: SystemCapability.Sensors.MiscDevice + + +| Name| Type | Description | +| ---- | ------ |------------| +| isEffectSupported | boolean | Whether the preset effect is supported. The value **true** indicates that the preset effect is supported, and the value **false** indicates the opposite.| + + +## VibratorInfo19+ + +Defines the vibrator information. + +| Name| Type | Description | +| ---- | ------ |-----------| +| deviceId | number | Device ID. | +| vibratorId | number | Vibrator ID. | +| deviceName | string | Device name. | +| isHdHapticSupported | boolean | Whether HD vibration is supported.| +| isLocalVibrator | boolean | Whether the device is a local device. | + ## vibrator.isHdHapticSupported12+ @@ -867,19 +1144,19 @@ For details about the error codes, see [Vibrator Error Codes](errorcode-vibrator **Example** -```ts -import { vibrator } from '@kit.SensorServiceKit'; -import { BusinessError } from '@kit.BasicServicesKit'; - -try { - // Check whether HD vibration is supported. - let ret = vibrator.isHdHapticSupported(); - console.info(`The query result is ${ret}`); -} catch (error) { - let e: BusinessError = error as BusinessError; - console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); -} -``` + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + try { + // Check whether HD vibration is supported. + let ret = vibrator.isHdHapticSupported(); + console.info(`The query result is ${ret}`); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` ## VibratorPatternBuilder18+ @@ -893,11 +1170,11 @@ Adds a long vibration event as a **VibratorPattern** object. **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------------------------------------- | ---- | ------------------------ | -| time | number | Yes | Start time of the long vibration. | -| duration | number | Yes | Duration of the long vibration. | -| options | [ContinuousParam](#continuousparam18) | No | Optional parameters.| +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ | +| time | number | Yes | Start time of the long vibration, in ms. The value range is (0,1800000).| +| duration | number | Yes | Duration of the long vibration, in ms. The value range is (0,5000].| +| options | [ContinuousParam](#continuousparam18) | No | Optional parameters. | **Return value** @@ -911,42 +1188,42 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | ID| Error Message | | -------- | ---------------- | -| 401 | Parameter error. | +| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | **Example** -```ts -import { vibrator } from '@kit.SensorServiceKit'; -import { BusinessError } from '@kit.BasicServicesKit'; - -let builder = new vibrator.VibratorPatternBuilder(); -try { - let pointsMe: vibrator.VibratorCurvePoint[] = [ - { time: 0, intensity: 0, frequency: -7 }, - { time: 42, intensity: 1, frequency: -6 }, - { time: 128, intensity: 0.94, frequency: -4 }, - { time: 217, intensity: 0.63, frequency: -14 }, - { time: 763, intensity: 0.48, frequency: -14 }, - { time: 1125, intensity: 0.53, frequency: -10 }, - { time: 1503, intensity: 0.42, frequency: -14 }, - { time: 1858, intensity: 0.39, frequency: -14 }, - { time: 2295, intensity: 0.34, frequency: -17 }, - { time: 2448, intensity: 0.21, frequency: -14 }, - { time: 2468, intensity: 0, frequency: -21 } - ] // No less than four VibratorCurvePoint objects must be set. The maximum value is 16. - let param: vibrator.ContinuousParam = { - intensity: 97, - frequency: 34, - points:pointsMe, - index: 0 - } - builder.addContinuousEvent(0, 2468, param); - console.info(`addContinuousEvent builder is ${builder.build()}`); -} catch(error) { - let e: BusinessError = error as BusinessError; - console.error(`Exception. Code ${e.code}`); -} -``` + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + let builder = new vibrator.VibratorPatternBuilder(); + try { + let pointsMe: vibrator.VibratorCurvePoint[] = [ + { time: 0, intensity: 0, frequency: -7 }, + { time: 42, intensity: 1, frequency: -6 }, + { time: 128, intensity: 0.94, frequency: -4 }, + { time: 217, intensity: 0.63, frequency: -14 }, + { time: 763, intensity: 0.48, frequency: -14 }, + { time: 1125, intensity: 0.53, frequency: -10 }, + { time: 1503, intensity: 0.42, frequency: -14 }, + { time: 1858, intensity: 0.39, frequency: -14 }, + { time: 2295, intensity: 0.34, frequency: -17 }, + { time: 2448, intensity: 0.21, frequency: -14 }, + { time: 2468, intensity: 0, frequency: -21 } + ] // No less than four VibratorCurvePoint objects must be set. The maximum value is 16. + let param: vibrator.ContinuousParam = { + intensity: 97, + frequency: 34, + points:pointsMe, + index: 0 + } + builder.addContinuousEvent(0, 2468, param); + console.info(`addContinuousEvent builder is ${builder.build()}`); + } catch(error) { + let e: BusinessError = error as BusinessError; + console.error(`Exception. Code ${e.code}`); + } + ``` ### vibrator('addTransientEvent')18+ @@ -958,10 +1235,10 @@ Adds a short vibration event as a **VibratorPattern** object. **Parameters** -| Name | Type | Mandatory| Description | -| ------- | ----------------------------------- | ---- | ------------------------ | -| time | number | Yes | Start time of long vibration. | -| options | [TransientParam](#transientparam18) | No | Optional parameters.| +| Name | Type | Mandatory| Description | +| ------- | ----------------------------------- | ---- | ------------------------------------------------------------ | +| time | number | Yes | Start time of the long vibration, in ms. The value range is (0,1800000).| +| options | [TransientParam](#transientparam18) | No | Optional parameters. | **Return value** @@ -975,28 +1252,28 @@ For details about the error codes, see [Universal Error Codes](../errorcode-univ | ID| Error Message | | -------- | ---------------- | -| 401 | Parameter error. | +| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | **Example** -```ts -import { vibrator } from '@kit.SensorServiceKit'; -import { BusinessError } from '@kit.BasicServicesKit'; - -let builder = new vibrator.VibratorPatternBuilder(); -try { - let param: vibrator.TransientParam = { - intensity: 80, - frequency: 70, - index: 0 - } - builder.addTransientEvent(0, param); - console.log(`addTransientEvent builder is ${builder.build()}`); -} catch(error) { - let e: BusinessError = error as BusinessError; - console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); -} -``` + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + let builder = new vibrator.VibratorPatternBuilder(); + try { + let param: vibrator.TransientParam = { + intensity: 80, + frequency: 70, + index: 0 + } + builder.addTransientEvent(0, param); + console.log(`addTransientEvent builder is ${builder.build()}`); + } catch(error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` ### vibrator('build')18+ @@ -1014,58 +1291,60 @@ Constructor used to create a **VibratorPattern** object, which determines the vi **Example** -```ts -import { vibrator } from '@kit.SensorServiceKit'; -import { BusinessError } from '@kit.BasicServicesKit'; - -let builder = new vibrator.VibratorPatternBuilder(); -try { - let param: vibrator.TransientParam = { - intensity: 80, - frequency: 70, - index: 0 - } - builder.addTransientEvent(0, param); - console.log(`addTransientEvent builder is ${builder.build()}`); -} catch(error) { - let e: BusinessError = error as BusinessError; - console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); -} -try { - vibrator.startVibration({ - type: "pattern", - pattern: builder.build() - }, { - usage: "alarm", // The switch control is subject to the selected type. - }, (error) => { - if (error) { - let e: BusinessError = error as BusinessError; - console.error(`Vibrate fail. Code: ${e.code}, message: ${e.message}`); - } else { - console.info(`vibrate success`); - } - }); -} catch(error) { - let e: BusinessError = error as BusinessError; - console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); -} -``` + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + let builder = new vibrator.VibratorPatternBuilder(); + try { + let param: vibrator.TransientParam = { + intensity: 80, + frequency: 70, + index: 0 + } + builder.addTransientEvent(0, param); + console.log(`addTransientEvent builder is ${builder.build()}`); + } catch(error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + try { + vibrator.startVibration({ + type: "pattern", + pattern: builder.build() + }, { + usage: "alarm", // The switch control is subject to the selected type. + }, (error) => { + if (error) { + let e: BusinessError = error as BusinessError; + console.error(`Vibrate fail. Code: ${e.code}, message: ${e.message}`); + } else { + console.info(`vibrate success`); + } + }); + } catch(error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` ## EffectId -Enumerates the preset vibration effect IDs. This parameter is needed when you call [vibrator.startVibration9+](#vibratorstartvibration9) or [vibrator.stopVibration9+](#vibratorstopvibration9-1) to deliver the vibration effect specified by [VibratePreset](#vibratepreset9). This parameter supports a variety of values, such as **haptic.clock.timer**. +Enumerates the preset vibration effect IDs. This parameter is needed when you call [vibrator.startVibration9+](#vibratorstartvibration9) or [vibrator.stopVibration9+](#vibratorstopvibration9-1) to deliver the vibration effect specified by [VibratePreset](#vibratepreset9). This parameter supports a variety of values, such as **haptic.clock.timer**. [HapticFeedback12+](#hapticfeedback12) provides several frequently used **EffectId** values. -Note: Preset effects vary according to devices. You are advised to call [vibrator.isSupportEffect](#vibratorissupporteffect10-1)10+ to check whether the device supports the preset effect before use. +> **NOTE** +> +> Preset effects vary according to devices. You are advised to call [vibrator.isSupportEffect](#vibratorissupporteffect10-1)10+ to check whether the device supports the preset effect before use. **System capability**: SystemCapability.Sensors.MiscDevice -| Name | Value | Description | -| ------------------ | -------------------- | -------------------------------- | +| Name | Value | Description | +| ----------- | -------------------- | ---------------------------- | | EFFECT_CLOCK_TIMER | 'haptic.clock.timer' | Vibration effect when a user adjusts the timer.| ## HapticFeedback12+ -Defines the vibration effect. The frequency of the same vibration effect may vary depending on the vibrator, but the frequency trend remains consistent. +Defines the vibration effect. The frequency of the same vibration effect may vary depending on the vibrator, but the frequency trend remains consistent. These vibration effects correspond to the specific **EffectId** values. For details, see the sample code that demonstrates how to use [vibrator.startVibration9+](#vibratorstartvibration9) or [vibrator.stopVibration9+](#vibratorstopvibration9-1) to deliver the vibration effect defined by [VibratePreset](#vibratepreset9). **System capability**: SystemCapability.Sensors.MiscDevice @@ -1110,10 +1389,10 @@ Represents vibration of the specified duration. **System capability**: SystemCapability.Sensors.MiscDevice -| Name | Type | Mandatory| Description | -| -------- | ------ | ---- | -------------------------------------- | -| type | 'time' | Yes | The value is **time**, indicating vibration of the specified duration.| -| duration | number | Yes | Vibration duration, in ms. | +| Name | Type | Mandatory| Description | +| -------- | ------ | ---- | ----------------------------------------------------------- | +| type | 'time' | Yes | The value is **time**, indicating vibration of the specified duration. | +| duration | number | Yes | Vibration duration, in ms. The value range is (0,1800000].| ## VibratePreset9+ @@ -1141,7 +1420,7 @@ Represents a custom vibration pattern. It is supported only by certain devices. ## HapticFileDescriptor10+ -Describes the FD of a custom vibration configuration file. Ensure that the file is available, and the parameters in it can be obtained from the sandbox path through the [file management API](../apis-core-file-kit/js-apis-file-fs.md#fsopen) or from the HAP resource through the [resource management API](../apis-localization-kit/js-apis-resource-manager.md#getrawfd9). The use case is as follows: The system triggers vibration according to the sequence set in a configuration file, based on the specified offset and length. For details about the storage format of the vibration sequence, see [Custom Vibration](../../device/sensor/vibrator-guidelines.md#custom-vibration). +Describes the FD of a custom vibration configuration file. Ensure that the file is available, and the parameters in it can be obtained from the sandbox path through the [file management API](../apis-core-file-kit/js-apis-file-fs.md#fsopen) or from the HAP resource through the [resource management API](../apis-localization-kit/js-apis-resource-manager.md#getrawfd9). The use case is as follows: The system triggers vibration according to the sequence set in a configuration file, based on the specified offset and length. For details about the storage format of the vibration sequence, see [Custom Vibration](../../device/sensor/vibrator-guidelines.md). **System capability**: SystemCapability.Sensors.MiscDevice @@ -1171,8 +1450,8 @@ Defines the gain relative to the vibration intensity. | Name | Type | Mandatory| Description | | --------- | ------ | ---- | ------------------------------------------------------------ | | time | number | Yes | Start time offset. | -| intensity | number | No | Gain relative to the vibration intensity. This parameter is optional. The value range is [0, 1]. If this parameter is left empty, the default value is **1**.| -| frequency | number | No | Change relative to the vibration frequency. This parameter is optional. The value range is [-100, 100]. If this parameter is left empty, the default value is 0.| +| intensity | number | No | Gain relative to the vibration intensity. This parameter is optional. The value range is [0,100%]. If this parameter is left empty, the default value is **1**.| +| frequency | number | No | Change relative to the vibration frequency. This parameter is optional. The value range is [-100,100]. If this parameter is left empty, the default value is **0**.| ## VibratorEvent18+ @@ -1183,12 +1462,12 @@ Vibration event. | Name | Type | Mandatory| Description | | --------- | ------------------------------- | ---- | ------------------------------------------------------------ | | eventType | VibratorEventType | Yes | Vibration event type. | -| time | number | Yes | Vibration start time. | -| duration | number | No | Vibration duration. This parameter is optional. The value range is [0, 5000]. The default value is **48** for short vibration and **1000** for long vibration.| -| intensity | number | No | Vibration intensity. This parameter is optional. The value range is [0, 100]. If this parameter is left empty, the default value is **100**.| -| frequency | number | No | Vibration frequency. This parameter is optional.The value range is [0, 100]. If this parameter is left empty, the default value is **50**. | -| index | number | No | Channel number. This parameter is optional. If this parameter is left empty, the default value is **0**. | -| points | Array<VibratorCurvePoint> | No | Adjustment points of the vibration curve. | +| time | number | Yes | Vibration start time, in ms. The value range is [0,1800000]. | +| duration | number | No | Vibration duration. This parameter is optional. The value range is (0,5000]. The default value is **48** for short vibration and **1000** for long vibration.| +| intensity | number | No | Vibration intensity. This parameter is optional. The value range is [0,100]. If this parameter is left empty, the default value is **100**.| +| frequency | number | No | Vibration frequency. This parameter is optional. The value range is [0,100]. If this parameter is left empty, the default value is **50**.| +| index | number | No | Channel number. This parameter is optional. The value range is [0,2]. If this parameter is left empty, the default value is **0**. | +| points | Array<[VibratorCurvePoint](#vibratorcurvepoint18)> | No | Adjustment points of the vibration curve. | ## VibratorPattern18+ @@ -1199,7 +1478,7 @@ Defines the vibration sequence. | Name | Type | Mandatory| Description | | ------ | -------------------------- | ---- | ---------------------------------------------------- | | time | number | Yes | Absolute vibration start time. | -| events | Array<VibratorEvent> | Yes | Vibration event array, which is the **VibratorPattern** object returned by **build() **.| +| events | Array<[VibratorEvent](#vibratorevent18)> | Yes | Vibration event array, which is the **VibratorPattern** object returned by **build() **.| ## ContinuousParam18+ @@ -1209,10 +1488,10 @@ Defines the parameters for continuous vibration. | Name | Type | Mandatory| Description | | --------- | -------------------- | ---- | ------------------------------------------------------------ | -| intensity | number | No | Vibration intensity. This parameter is optional. The value range is [0, 100]. If this parameter is left empty, the default value is **100**.| -| frequency | number | No | Vibration frequency. This parameter is optional.The value range is [0, 100]. If this parameter is left empty, the default value is **50**. | -| points | VibratorCurvePoint[] | No | Adjustment points of the vibration curve. | -| index | number | No | Channel number. This parameter is optional. If this parameter is left empty, the default value is **0**. | +| intensity | number | No | Vibration intensity. This parameter is optional. The value range is [0,100]. If this parameter is left empty, the default value is **100**.| +| frequency | number | No | Vibration frequency. This parameter is optional. The value range is [0,100]. If this parameter is left empty, the default value is **50**.| +| points | [VibratorCurvePoint](#vibratorcurvepoint18)[] | No | Adjustment points of the vibration curve. | +| index | number | No | Channel number. This parameter is optional. The value range is [0,2]. If this parameter is left empty, the default value is **0**. | ## TransientParam18+ @@ -1220,11 +1499,11 @@ Defines the parameters for transient vibration. **System capability**: SystemCapability.Sensors.MiscDevice -| Name | Type | Mandatory| Description | -| --------- | ------ | ---- | ------------------------------------------- | -| intensity | number | No | Vibration intensity. This parameter is optional. If this parameter is left empty, the default value is **100**.| -| frequency | number | No | Vibration frequency. This parameter is optional. If this parameter is left empty, the default value is **50**. | -| index | number | No | Channel number. This parameter is optional. If this parameter is left empty, the default value is **0**. | +| Name | Type | Mandatory| Description | +| --------- | ------ | ---- | ------------------------------------------------------------ | +| intensity | number | No | Vibration intensity. This parameter is optional. The value range is [0,100]. If this parameter is left empty, the default value is **100**.| +| frequency | number | No | Vibration frequency. This parameter is optional. The value range is [0,100]. If this parameter is left empty, the default value is **50**.| +| index | number | No | Channel number. This parameter is optional. The value range is [0,2]. If this parameter is left empty, the default value is **0**. | ## VibrateFromPattern18+ @@ -1245,10 +1524,11 @@ Describes the vibration attribute. **System capability**: SystemCapability.Sensors.MiscDevice -| Name | Type | Mandatory| Description | -| ----- | ---------------- | ---- | ---------------------- | -| id | number | No | Vibrator ID. The default value is **0**.| -| usage | [Usage](#usage9) | Yes | Vibration scenario. | +| Name | Type | Mandatory| Description | +|------------------------| ---------------- | ---- | ------------------------------------------------------------ | +| id | number | No | Vibrator ID. The default value is **0**. | +| deviceId19+ | number | No | Device ID. | +| usage | [Usage](#usage9) | Yes | Vibration scenario. The default value is **unknown**. The value must be an enum defined in [Usage](#usage9).| ## Usage9+ @@ -1289,9 +1569,9 @@ This API is deprecated since API version 9. You are advised to use [vibrator.sta **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------ | ---- | ---------------------- | -| duration | number | Yes | Vibration duration, in ms.| +| Name | Type | Mandatory| Description | +| -------- | ------ | ---- | ------------------------------------------------------------ | +| duration | number | Yes | Vibration duration, in ms. The value range is (0,1800000].| **Return value** @@ -1301,16 +1581,16 @@ This API is deprecated since API version 9. You are advised to use [vibrator.sta **Example** -```ts -import { vibrator } from '@kit.SensorServiceKit'; -import { BusinessError } from '@kit.BasicServicesKit'; + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; -vibrator.vibrate(1000).then(() => { - console.info('Succeed in vibrating'); -}, (error: BusinessError) => { - console.error(`Failed to vibrate. Code: ${error.code}, message: ${error.message}`); -}); -``` + vibrator.vibrate(1000).then(() => { + console.info('Succeed in vibrating'); + }, (error: BusinessError) => { + console.error(`Failed to vibrate. Code: ${error.code}, message: ${error.message}`); + }); + ``` ## vibrator.vibrate(deprecated) @@ -1326,25 +1606,25 @@ This API is deprecated since API version 9. You are advised to use [vibrator.sta **Parameters** -| Name | Type | Mandatory| Description | -| -------- | ------------------------- | ---- | ---------------------------------------------------------- | -| duration | number | Yes | Vibration duration, in ms. | -| callback | AsyncCallback<void> | No | Callback used to return the result. If the vibration starts, **err** is **undefined**; otherwise, **err** is an error object.| +| Name | Type | Mandatory| Description | +| -------- | ------------------------- | ---- | ------------------------------------------------------------ | +| duration | number | Yes | Vibration duration, in ms. The value range is (0,1800000].| +| callback | AsyncCallback<void> | No | Callback used to return the result. If the vibration starts, **err** is **undefined**; otherwise, **err** is an error object. | **Example** -```ts -import { vibrator } from '@kit.SensorServiceKit'; -import { BusinessError } from '@kit.BasicServicesKit'; - -vibrator.vibrate(1000, (error: BusinessError) => { - if (error) { - console.error(`Failed to vibrate. Code: ${error.code}, message: ${error.message}`); - } else { - console.info('Succeed in vibrating'); - } -}) -``` + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + vibrator.vibrate(1000, (error: BusinessError) => { + if (error) { + console.error(`Failed to vibrate. Code: ${error.code}, message: ${error.message}`); + } else { + console.info('Succeed in vibrating'); + } + }) + ``` ## vibrator.vibrate(deprecated) @@ -1373,16 +1653,16 @@ This API is deprecated since API version 9. You are advised to use [vibrator.sta **Example** -```ts -import { vibrator } from '@kit.SensorServiceKit'; -import { BusinessError } from '@kit.BasicServicesKit'; + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; -vibrator.vibrate(vibrator.EffectId.EFFECT_CLOCK_TIMER).then(() => { - console.info('Succeed in vibrating'); -}, (error: BusinessError) => { - console.error(`Failed to vibrate. Code: ${error.code}, message: ${error.message}`); -}); -``` + vibrator.vibrate(vibrator.EffectId.EFFECT_CLOCK_TIMER).then(() => { + console.info('Succeed in vibrating'); + }, (error: BusinessError) => { + console.error(`Failed to vibrate. Code: ${error.code}, message: ${error.message}`); + }); + ``` ## vibrator.vibrate(deprecated) @@ -1406,18 +1686,18 @@ This API is deprecated since API version 9. You are advised to use [vibrator.sta **Example** -```ts -import { vibrator } from '@kit.SensorServiceKit'; -import { BusinessError } from '@kit.BasicServicesKit'; - -vibrator.vibrate(vibrator.EffectId.EFFECT_CLOCK_TIMER, (error: BusinessError) => { - if (error) { - console.error(`Failed to vibrate. Code: ${error.code}, message: ${error.message}`); - } else { - console.info('Succeed in vibrating'); - } -}) -``` + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + vibrator.vibrate(vibrator.EffectId.EFFECT_CLOCK_TIMER, (error: BusinessError) => { + if (error) { + console.error(`Failed to vibrate. Code: ${error.code}, message: ${error.message}`); + } else { + console.info('Succeed in vibrating'); + } + }) + ``` ## vibrator.stop(deprecated) @@ -1445,25 +1725,25 @@ This API is deprecated since API version 9. You are advised to use [vibrator.sto **Example** -```ts -import { vibrator } from '@kit.SensorServiceKit'; -import { BusinessError } from '@kit.BasicServicesKit'; - -// Start vibration based on the specified effect ID. -vibrator.vibrate(vibrator.EffectId.EFFECT_CLOCK_TIMER, (error: BusinessError) => { - if (error) { - console.error(`Failed to vibrate. Code: ${error.code}, message: ${error.message}`); - } else { - console.info('Succeed in vibrating'); - } -}) -// Stop vibration in VIBRATOR_STOP_MODE_PRESET mode. -vibrator.stop(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_PRESET).then(() => { - console.info('Succeed in stopping'); -}, (error: BusinessError) => { - console.error(`Failed to stop. Code: ${error.code}, message: ${error.message}`); -}); -``` + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + // Start vibration based on the specified effect ID. + vibrator.vibrate(vibrator.EffectId.EFFECT_CLOCK_TIMER, (error: BusinessError) => { + if (error) { + console.error(`Failed to vibrate. Code: ${error.code}, message: ${error.message}`); + } else { + console.info('Succeed in vibrating'); + } + }) + // Stop vibration in VIBRATOR_STOP_MODE_PRESET mode. + vibrator.stop(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_PRESET).then(() => { + console.info('Succeed in stopping'); + }, (error: BusinessError) => { + console.error(`Failed to stop. Code: ${error.code}, message: ${error.message}`); + }); + ``` ## vibrator.stop(deprecated) @@ -1487,24 +1767,24 @@ This API is deprecated since API version 9. You are advised to use [vibrator.sto **Example** -```ts -import { vibrator } from '@kit.SensorServiceKit'; -import { BusinessError } from '@kit.BasicServicesKit'; - -// Start vibration based on the specified effect ID. -vibrator.vibrate(vibrator.EffectId.EFFECT_CLOCK_TIMER, (error: BusinessError) => { - if (error) { - console.error(`Failed to vibrate. Code: ${error.code}, message: ${error.message}`); - } else { - console.info('Succeed in vibrating'); - } -}) -// Stop vibration in VIBRATOR_STOP_MODE_PRESET mode. -vibrator.stop(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_PRESET, (error: BusinessError) => { - if (error) { - console.error(`Failed to stop. Code: ${error.code}, message: ${error.message}`); - } else { - console.info('Succeed in stopping'); - } -}) -``` + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + // Start vibration based on the specified effect ID. + vibrator.vibrate(vibrator.EffectId.EFFECT_CLOCK_TIMER, (error: BusinessError) => { + if (error) { + console.error(`Failed to vibrate. Code: ${error.code}, message: ${error.message}`); + } else { + console.info('Succeed in vibrating'); + } + }) + // Stop vibration in VIBRATOR_STOP_MODE_PRESET mode. + vibrator.stop(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_PRESET, (error: BusinessError) => { + if (error) { + console.error(`Failed to stop. Code: ${error.code}, message: ${error.message}`); + } else { + console.info('Succeed in stopping'); + } + }) + ``` -- Gitee