From a822629eab5c62b4298405ee8ef43557646c985b Mon Sep 17 00:00:00 2001 From: Annie_wang Date: Sat, 16 Apr 2022 18:01:14 +0800 Subject: [PATCH] update docs Signed-off-by: Annie_wang --- .../apis/js-apis-system-bluetooth.md | 169 +++++++++ .../reference/apis/js-apis-system-storage.md | 61 +-- .../driver/driver-hdf-development.md | 6 +- .../driver/driver-hdf-message-management.md | 355 ++++++++---------- .../driver/driver-hdf-servicemanage.md | 265 ++++++------- 5 files changed, 492 insertions(+), 364 deletions(-) create mode 100644 en/application-dev/reference/apis/js-apis-system-bluetooth.md diff --git a/en/application-dev/reference/apis/js-apis-system-bluetooth.md b/en/application-dev/reference/apis/js-apis-system-bluetooth.md new file mode 100644 index 0000000000..b529772989 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-system-bluetooth.md @@ -0,0 +1,169 @@ +# Bluetooth + + +> ![icon-note.gif](../public_sys-resources/icon-note.gif) **NOTE**
+> +> - The APIs of this module are no longer maintained since API version 7. You are advised to use [`@ohos.bluetooth`](js-apis-bluetooth.md). +> +> - The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. + + +## Modules to Import + + +``` +import bluetooth from '@system.bluetooth'; +``` + + +## bluetooth.startBLEScan(OBJECT) + +Scans for Bluetooth Low Energy (BLE) devices nearby. This operation consumes system resources. Call [bluetooth.stopBLEScan](#bluetoothstopblescanobject) to stop the scan after BLE devices are detected and connected. + +**Required permissions**: ohos.permission.DISCOVER_BLUETOOTH and ohos.permission.LOCATION + +**System capability**: SystemCapability.Communication.Bluetooth.Lite + +**Parameters** +**Table 1** StartBLEScanOptions + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| interval | number | No| Interval for reporting device information, in milliseconds. The default value is **0**, which means to report detected devices immediately and report other information at the given interval.| +| success | Function | No| Called when the operation is successful.| +| fail | Function | No| Called when the operation fails.| +| complete | Function | No| Called when the API call is complete.| + +**Example** + + ``` + bluetooth.startBLEScan({ + success() { + console.log('call bluetooth.startBLEScan success.'); + }, + fail(code, data) { + console.log('call bluetooth.startBLEScan failed, code: ${code}, data: ${data}.'); + }, + complete() { + console.log('call bluetooth.startBLEScan complete.'); + } + }); + ``` + + +## bluetooth.stopBLEScan(OBJECT) + +Stops scanning for BLE devices nearby. This API is used with [bluetooth.startBLEScan(OBJECT)](#bluetoothstartblescanobject) in pairs. + +**Required permissions**: ohos.permission.DISCOVER_BLUETOOTH and ohos.permission.LOCATION + +**System capability**: SystemCapability.Communication.Bluetooth.Lite + +**Parameters** +**Table 2** StopBLEScanOptions + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| success | Function | No| Called when the operation is successful.| +| fail | Function | No| Called when the operation fails.| +| complete | Function | No| Called when the API call is complete.| + +**Example** + + ``` + bluetooth.stopBLEScan({ + success() { + console.log('call bluetooth.stopBLEScan success.'); + }, + fail(data, code) { + console.log('call bluethooth.stopBLEScan fail, code: ${code}, data: ${data}.'); + }, + complete() { + console.log('call bluethooth.stopBLEScan complete.'); + } + }); + ``` + + +## bluetooth.subscribeBLEFound(OBJECT) + +Subscribes to the newly detected BLE devices. If this API is called multiple times, the last call takes effect. + +**Required permissions**: ohos.permission.DISCOVER_BLUETOOTH and ohos.permission.LOCATION + +**System capability**: SystemCapability.Communication.Bluetooth.Lite + +**Parameters** +**Table 3** SubscribeBLEFoundOptions + +| Parameters| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| success | Function | Yes| Called to report newly detected devices.| +| fail | Function | No| Called when the operation fails.| + +**Table 4** Return value in success + +| Name| Type| Description| +| -------- | -------- | -------- | +| devices | Array<BluetoothDevice> | List of the newly detected BLE devices.| + +**Table 5** BluethoothDevice + +| Name| Type| Description| +| -------- | -------- | -------- | +| addrType | string | Device address type, which can be:
- **public**: a public address
- **random**: a random address| +| addr | string | MAC address of the device.| +| rssi | number | Received signal strength indicator (RSSl) of the device.| +| txpower | string | **txpower** field in the Bluetooth advertising data.| +| data | hex string | Bluetooth advertising data (including advertising data and scan response data), in a hexadecimal string.| + +**Example** + + ``` + bluetooth.startaBLEScan({ + success() { + bluetooth.subscribeBLEFound({ + success(data) { + const [device] = data.devices; + if (!!device) { + bluetooth.stopBLEScan(); + } + } + }); + }, + fail(code, data) { + console.log('Failed to start BLE device scan, code: ${code}, data: ${data}'); + } + }); + ``` + + +## bluetooth.unsubscribeBLEFound() + +Unsubscribes from the newly detected devices. + +**Required permissions**: ohos.permission.DISCOVER_BLUETOOTH and ohos.permission.LOCATION + +**System capability**: SystemCapability.Communication.Bluetooth.Lite + +**Example** + + ``` + bluetooth.unsubscribeBLEFound(); + ``` + + +## Common Error Codes + +| Error Code| Description| +| -------- | -------- | +| 1100 | The Bluetooth adapter is not initialized.| +| 1101 | The Bluetooth adapter is unavailable.| +| 1102 | The specified device is not found.| +| 1103 | Connection failed.| +| 1104 | The specified service is not found.| +| 1105 | The specified characteristics value is not found.| +| 1106 | The Bluetooth device is disconnected.| +| 1107 | The characteristic value does not support this operation.| +| 1108 | Other exceptions reported by the system.| +| 1109 | The system version does not support BLE.| diff --git a/en/application-dev/reference/apis/js-apis-system-storage.md b/en/application-dev/reference/apis/js-apis-system-storage.md index 2440183d41..ed45d5b22e 100644 --- a/en/application-dev/reference/apis/js-apis-system-storage.md +++ b/en/application-dev/reference/apis/js-apis-system-storage.md @@ -1,8 +1,9 @@ -# Data Storage +# Data storage -> ![icon-note.gif](public_sys-resources/icon-note.gif) **Noteļ¼š** -> - The APIs of this module are no longer maintained since API version 6. It is recommended that you use [`@ohos.data.storage`](js-apis-data-storage.md) instead. -> +> ![icon-note.gif](../public_sys-resources/icon-note.gif) **NOTE**
+> +> - The APIs of this module are no longer maintained since API Version 6. You are advised to use [`@ohos.data.storage`](js-apis-data-storage.md). From API Version 9, you are advised to use [`@ohos.data.preferences`](js-apis-data-preferences.md). +> > - The initial APIs of this module are supported since API version 3. Newly added APIs will be marked with a superscript to indicate their earliest API version. @@ -18,19 +19,19 @@ import storage from '@system.storage'; get(Object): void -Reads the stored content. +Obtains the stored data. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| key | string | Yes | Content index. | -| default | string | No | Default value returned when the **key** does not exist. | -| success | Function | No | Called when the stored content is successfully read. | -| fail | Function | No | Called when the stored content fails to be read. | -| complete | Function | No | Called when the execution is complete. | +| key | string | Yes| Index of the data to obtain.| +| default | string | No| Default value returned when the **key** does not exist.| +| success | Function | No| Called when the stored data is successfully obtained.| +| fail | Function | No| Called when the stored data failed to be obtained.| +| complete | Function | No| Called when the execution is complete.| **Example** @@ -58,19 +59,19 @@ export default { set(Object): void -Modifies the stored content. +Modifies the stored data. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| key | string | Yes | Index of the stored content to be modified. | -| value | string | No | Target storage content. The maximum number of characters allowed is 128. | -| success | Function | No | Called when the stored content is modified successfully. | -| fail | Function | No | Called when the stored content fails to be modified. | -| complete | Function | No | Called when the execution is complete. | +| key | string | Yes| Index of the data to modify.| +| value | string | No| New value to set. The maximum length is 128 bytes.| +| success | Function | No| Called when the data is successfully modified.| +| fail | Function | No| Called when the data failed to be modified.| +| complete | Function | No| Called when the execution is complete.| **Example** @@ -96,17 +97,17 @@ export default { clear(Object): void -Clears the stored content. +Clears the stored data. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| success | Function | No | Called when the stored content is cleared successfully | -| fail | Function | No | Called when the stored content fails to be cleared | -| complete | Function | No | Called when the execution is complete | +| success | Function | No| Called when the data is successfully cleared.| +| fail | Function | No| Called when the data failed to be cleared.| +| complete | Function | No| Called when the execution is complete.| **Example** @@ -130,18 +131,18 @@ export default { delete(Object): void -Deletes the stored content. +Deletes the stored data. **System capability**: SystemCapability.DistributedDataManager.Preferences.Core **Parameters** -| Name | Type | Mandatory | Description | +| Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| key | string | Yes | Content index. | -| success | Function | No | Called when the stored content is deleted successfully. | -| fail | Function | No | Called when the stored content fails to be deleted. | -| complete | Function | No | Called when the execution is complete. | +| key | string | Yes| Index of the data to delete.| +| success | Function | No| Called when the data is deleted.| +| fail | Function | No| Called when the data failed to be deleted.| +| complete | Function | No| Called when the execution is complete.| **Example** @@ -159,4 +160,4 @@ export default { }); } } -``` \ No newline at end of file +``` diff --git a/en/device-dev/driver/driver-hdf-development.md b/en/device-dev/driver/driver-hdf-development.md index 4716637357..089bc53480 100644 --- a/en/device-dev/driver/driver-hdf-development.md +++ b/en/device-dev/driver/driver-hdf-development.md @@ -185,12 +185,12 @@ The HDF-based driver development involves driver implementation and configuratio caps = ["DAC_OVERRIDE", "DAC_READ_SEARCH"]; // Linux capabilities of the user-mode process. device_sample :: device { // Sample device node. device0 :: deviceNode { // DeviceNode of the sample driver. - policy = 1; // Policy for publishing the driver service. For details, see Driver Service Management. + policy = 1; // Policy for providing the driver service. For details, see Driver Service Management. priority = 100; // Driver startup priority (0-200). A smaller value indicates a higher priority. The default value 100 is recommended. The drivers with the same priority start based on the time when the priority was configured. The driver configured first starts first. preload = 0; // The loading mode of the driver is on-demand loading. For details, see "NOTE" at the end of this document. permission = 0664; // Permission for the driver to create a device node. moduleName = "sample_driver"; // Driver name. The value must be the same as that of moduleName in the HdfDriverEntry structure. - serviceName = "sample_service"; // Name of the service published by the driver. The service name must be unique. + serviceName = "sample_service"; // Name of the service provided by the driver. The service name must be unique. deviceMatchAttr = "sample_config"; // Keyword for matching the private data of the driver. The value must be the same as that of match_attr in the private data configuration table of the driver. } } @@ -253,7 +253,7 @@ The HDF-based driver development involves driver implementation and configuratio > > If **preload** is set to **1 (DEVICE_PRELOAD_ENABLE_STEP2)**, the driver is loaded after a quick start is complete. If the system does not support quick start, the value **1** has the same meaning as **DEVICE_PRELOAD_ENABLE**. > -> If **preload** is set to **2 (DEVICE_PRELOAD_DISABLE)** , the driver is dynamically loaded instead of being loaded during the system boot process. When a user-mode process requests the driver service, the HDF attempts to dynamically load the driver if the driver service does not exist. For more details, see [Driver Message Mechanism Management](driver-hdf-message-management.md). +> If **preload** is set to **2 (DEVICE_PRELOAD_DISABLE)** , the driver is dynamically loaded instead of being loaded during the system boot process. When a user-mode process requests the driver service, the HDF attempts to dynamically load the driver if the driver service does not exist. For more details, see [Driver Messaging Mechanism](driver-hdf-message-management.md). > > - Sequential loading (**preload** set to **0 (DEVICE_PRELOAD_ENABLE)**)
> In the configuration file, the **priority** fields (value range: 0 to 200) determines the loading sequence of a host and a driver. For drivers in different hosts, a smaller host priority value indicates a higher driver loading priority; for drivers in the same host, a smaller driver priority value indicates a higher driver loading priority. diff --git a/en/device-dev/driver/driver-hdf-message-management.md b/en/device-dev/driver/driver-hdf-message-management.md index 14faab8e40..65ae4d200d 100644 --- a/en/device-dev/driver/driver-hdf-message-management.md +++ b/en/device-dev/driver/driver-hdf-message-management.md @@ -1,189 +1,166 @@ -# Driver Message Mechanism Management - -## When to Use - -When user-level applications need to interact with kernel-level drivers, the driver message mechanism of the HDF can be used. - -## Available APIs - -The message mechanism provides the following features: - -1. User-level applications send messages to drivers. -2. User-level applications receive events sent by the drivers. - -**Table 1** APIs for the driver message mechanism - - - - - - - - - - - - - - - - - - - -

Function

-

Description

-

struct HdfIoService *HdfIoServiceBind(const char *serviceName)

-

Obtains a specified driver service. After the service is obtained, the Dispatch function of the service is used to send messages to the driver.

-

void HdfIoServiceRecycle(struct HdfIoService *service);

-

Releases a specified driver service.

-

int HdfDeviceRegisterEventListener(struct HdfIoService *target, struct HdfDevEventlistener *listener);

-

Receives events sent by the drivers.

-

int HdfDeviceSendEvent(struct HdfDeviceObject *deviceObject, uint32_t id, struct HdfSBuf *data);

-

Sends events.

-
- -## How to Develop - -1. Set the value of the **policy** field in the driver configuration information to **2** \(SERVICE\_POLICY\_CAPACITY, see [Driver Service Management](driver-hdf-servicemanage.md)\). - - ``` - device_sample :: Device { - policy = 2; - ... - } - ``` - -2. The **permission** field in the driver configuration information indicates the permission provided for the driver to create device nodes. The default value is **0666**. You can configure the value of this field based on the actual application scenario of the driver. -3. Implement the **Dispatch** function of the service base member **IDeviceIoService** during service implementation. - - ``` - // Process messages delivered by user-level applications. - int32_t SampleDriverDispatch(struct HdfDeviceObject *device, int cmdCode, struct HdfSBuf *data, struct HdfSBuf *reply) - { - HDF_LOGE("sample driver lite A dispatch"); - return 0; - } - int32_t SampleDriverBind(struct HdfDeviceObject *device) - { - HDF_LOGE("test for lite os sample driver A Open!"); - if (device == NULL) { - HDF_LOGE("test for lite os sample driver A Open failed!"); - return -1; - } - static struct ISampleDriverService sampleDriverA = { - .ioService.Dispatch = SampleDriverDispatch, - .ServiceA = SampleDriverServiceA, - .ServiceB = SampleDriverServiceB, - }; - device->service = (struct IDeviceIoService *)(&sampleDriverA); - return 0; - } - ``` - -4. Define the CMD type in the message processing function. - - ``` - #define SAMPLE_WRITE_READ 1 // Read and write operation 1 - ``` - -5. Enable the user-level application to obtain the service interface and send messages to the driver. - - ``` - int SendMsg(const char *testMsg) - { - if (testMsg == NULL) { - HDF_LOGE("test msg is null"); - return -1; - } - struct HdfIoService *serv = HdfIoServiceBind("sample_driver"); - if (serv == NULL) { - HDF_LOGE("fail to get service"); - return -1; - } - struct HdfSBuf *data = HdfSBufObtainDefaultSize(); - if (data == NULL) { - HDF_LOGE("fail to obtain sbuf data"); - return -1; - } - struct HdfSBuf *reply = HdfSBufObtainDefaultSize(); - if (reply == NULL) { - HDF_LOGE("fail to obtain sbuf reply"); - ret = HDF_DEV_ERR_NO_MEMORY; - goto out; - } - if (!HdfSbufWriteString(data, testMsg)) { - HDF_LOGE("fail to write sbuf"); - ret = HDF_FAILURE; - goto out; - } - int ret = serv->dispatcher->Dispatch(&serv->object, SAMPLE_WRITE_READ, data, reply); - if (ret != HDF_SUCCESS) { - HDF_LOGE("fail to send service call"); - goto out; - } - out: - HdfSBufRecycle(data); - HdfSBufRecycle(reply); - HdfIoServiceRecycle(serv); - return ret; - } - ``` - -6. Enable the user-level application to receive messages reported by the driver. - 1. Enable the user-level application to compile the function for processing messages reported by the driver. - - ``` - static int OnDevEventReceived(void *priv, uint32_t id, struct HdfSBuf *data) - { - OsalTimespec time; - OsalGetTime(&time); - HDF_LOGE("%s received event at %llu.%llu", (char *)priv, time.sec, time.usec); - - const char *string = HdfSbufReadString(data); - if (string == NULL) { - HDF_LOGE("fail to read string in event data"); - return -1; - } - HDF_LOGE("%s: dev event received: %d %s", (char *)priv, id, string); - return 0; - } - ``` - - 2. Enable the user-level application to register the function for receiving messages reported by the driver. - - ``` - int RegisterListen() - { - struct HdfIoService *serv = HdfIoServiceBind("sample_driver"); - if (serv == NULL) { - HDF_LOGE("fail to get service"); - return -1; - } - static struct HdfDevEventlistener listener = { - .callBack = OnDevEventReceived, - .priv ="Service0" - }; - if (HdfDeviceRegisterEventListener(serv, &listener) != 0) { - HDF_LOGE("fail to register event listener"); - return -1; - } - ...... - HdfDeviceUnregisterEventListener(serv, &listener); - HdfIoServiceRecycle(serv); - return 0; - } - ``` - - 3. Enable the driver to report events. - - ``` - int32_t SampleDriverDispatch(struct HdfDeviceObject *device, int cmdCode, struct HdfSBuf *data, struct HdfSBuf *reply) - { - ... // process api call here - return HdfDeviceSendEvent(deviceObject, cmdCode, data); - } - ``` - - - +# Driver Messaging Mechanism + + +## When to Use + +The HDF messaging mechanism implements the interaction between the user-mode applications and kernel-mode drivers. + + +## Available APIs + +The messaging mechanism allows: + +1. User-mode applications to send messages to drivers. + +2. User-mode applications to receive events from drivers. + + **Table 1** APIs for the driver messaging mechanism + +| API| Description| +| -------- | -------- | +| struct HdfIoService \*HdfIoServiceBind(const char \*serviceName); | Obtains a driver service. The **Dispatch()** method in the driver service obtained sends messages to the driver.| +| void HdfIoServiceRecycle(struct HdfIoService \*service); | Releases a driver service.| +| int HdfDeviceRegisterEventListener(struct HdfIoService \*target, struct HdfDevEventlistener \*listener); | Registers the method for receiving events reported by the driver.| +| int HdfDeviceSendEvent(struct HdfDeviceObject \*deviceObject, uint32_t id, struct HdfSBuf \*data); | Sends events. | + + +## How to Develop + +1. In the driver configuration, set **policy** to **2**. For more details, see [policy](../driver/driver-hdf-servicemanage.md). + + ``` + device_sample :: Device { + policy = 2; + ... + } + ``` + +2. Set the driver permission. By default, the **permission** field is set to **0666**, which allows the driver to create device nodes. You can set this field based on service requirements. + +3. Implement the **Dispatch()** method of **IDeviceIoService**. + + ``` + // Dispatch messages sent from the user-mode application. + int32_t SampleDriverDispatch(struct HdfDeviceObject *device, int cmdCode, struct HdfSBuf *data, struct HdfSBuf *reply) + { + HDF_LOGE("sample driver lite A dispatch"); + return 0; + } + int32_t SampleDriverBind(struct HdfDeviceObject *device) + { + HDF_LOGE("test for lite os sample driver A Open!"); + if (device == NULL) { + HDF_LOGE("test for lite os sample driver A Open failed!"); + return -1; + } + static struct ISampleDriverService sampleDriverA = { + .ioService.Dispatch = SampleDriverDispatch, + .ServiceA = SampleDriverServiceA, + .ServiceB = SampleDriverServiceB, + }; + device->service = (struct IDeviceIoService *)(&sampleDriverA); + return 0; + } + ``` + +4. Define the cmd type in the message processing function. + + ``` + #define SAMPLE_WRITE_READ 1 // Read and write operation 1 + ``` + +5. Bind the driver service and the user-mode application to enable messages to be sent to the driver. + + ``` + int SendMsg(const char *testMsg) + { + if (testMsg == NULL) { + HDF_LOGE("test msg is null"); + return -1; + } + struct HdfIoService *serv = HdfIoServiceBind("sample_driver"); + if (serv == NULL) { + HDF_LOGE("fail to get service"); + return -1; + } + struct HdfSBuf *data = HdfSBufObtainDefaultSize(); + if (data == NULL) { + HDF_LOGE("fail to obtain sbuf data"); + return -1; + } + struct HdfSBuf *reply = HdfSBufObtainDefaultSize(); + if (reply == NULL) { + HDF_LOGE("fail to obtain sbuf reply"); + ret = HDF_DEV_ERR_NO_MEMORY; + goto out; + } + if (!HdfSbufWriteString(data, testMsg)) { + HDF_LOGE("fail to write sbuf"); + ret = HDF_FAILURE; + goto out; + } + int ret = serv->dispatcher->Dispatch(&serv->object, SAMPLE_WRITE_READ, data, reply); + if (ret != HDF_SUCCESS) { + HDF_LOGE("fail to send service call"); + goto out; + } + out: + HdfSBufRecycle(data); + HdfSBufRecycle(reply); + HdfIoServiceRecycle(serv); + return ret; + } + ``` + +6. Enable the user-mode application to receive messages from the driver. + 1. Enable the driver to report events to the user-mode application. + + ``` + static int OnDevEventReceived(void *priv, uint32_t id, struct HdfSBuf *data) + { + OsalTimespec time; + OsalGetTime(&time); + HDF_LOGE("%s received event at %llu.%llu", (char *)priv, time.sec, time.usec); + + const char *string = HdfSbufReadString(data); + if (string == NULL) { + HDF_LOGE("fail to read string in event data"); + return -1; + } + HDF_LOGE("%s: dev event received: %d %s", (char *)priv, id, string); + return 0; + } + ``` + 2. Register the method for receiving the messages from the driver. + + ``` + int RegisterListen() + { + struct HdfIoService *serv = HdfIoServiceBind("sample_driver"); + if (serv == NULL) { + HDF_LOGE("fail to get service"); + return -1; + } + static struct HdfDevEventlistener listener = { + .callBack = OnDevEventReceived, + .priv ="Service0" + }; + if (HdfDeviceRegisterEventListener(serv, &listener) != 0) { + HDF_LOGE("fail to register event listener"); + return -1; + } + ...... + HdfDeviceUnregisterEventListener(serv, &listener); + HdfIoServiceRecycle(serv); + return 0; + } + ``` + 3. Enable the driver to report events. + + ``` + int32_t SampleDriverDispatch(struct HdfDeviceObject *device, int cmdCode, struct HdfSBuf *data, struct HdfSBuf *reply) + { + ... // Process the API call. + return HdfDeviceSendEvent(deviceObject, cmdCode, data); + } + ``` diff --git a/en/device-dev/driver/driver-hdf-servicemanage.md b/en/device-dev/driver/driver-hdf-servicemanage.md index 0e5485bfb8..f9445db98f 100644 --- a/en/device-dev/driver/driver-hdf-servicemanage.md +++ b/en/device-dev/driver/driver-hdf-servicemanage.md @@ -1,162 +1,143 @@ -# Driver Service Management +# Driver Service Management -Driver services are objects of open capabilities provided by the HDF and are managed by the HDF in a unified manner. Using driver service management, you can release and obtain driver services. +Driver services are objects of capabilities provided by HDF driver devices to external systems and are managed by the HDF in a unified manner. Driver service management involves providing and obtaining driver services. -The HDF uses the **policy** field in the configuration file to define policies for drivers to release services externally. The values and meanings of this field are as follows: +The HDF uses the **policy** field in the configuration file to define policies for drivers to provide services externally. The values this field are as follows: + + + ``` typedef enum { /* The driver does not provide services. */ SERVICE_POLICY_NONE = 0, - /* The driver provides services for kernel-space applications. */ + /* The driver provides services only for kernel-mode applications. */ SERVICE_POLICY_PUBLIC = 1, - /* The driver provides services for both kernel- and user-space applications. */ + /* The driver provides services for both kernel- and user-mode applications. */ SERVICE_POLICY_CAPACITY = 2, - /* The driver services are not released externally but can be subscribed to. */ + /** The driver services are not provided externally but can be subscribed to. */ SERVICE_POLICY_FRIENDLY = 3, - /* The driver services are private. They are neither released nor subscribed to. */ + /* The driver private services cannot be provided externally or subscribed to. */ SERVICE_POLICY_PRIVATE = 4, - /* The service policy is incorrect. */ + /** Invalid service policy. */ SERVICE_POLICY_INVALID } ServicePolicy; ``` -## When to Use -The driver service management capability can be used if the driver provides capabilities using APIs. - -## Available APIs - -The table below describes the APIs used for driver service management. - -**Table 1** APIs for driver service management - - - - - - - - - - - - - - - - -

Function

-

Description

-

int32_t (*Bind)(struct HdfDeviceObject *deviceObject);

-

Binds a service interface to the HDF. You need to implement the Bind function.

-

const struct HdfObject *DevSvcManagerClntGetService(const char *svcName);

-

Obtains a specified driver service.

-

int HdfDeviceSubscribeService(

-

struct HdfDeviceObject *deviceObject, const char *serviceName, struct SubscriberCallback callback);

-

Subscribes to a specified driver service.

-
- -## How to Develop - -The development of driver service management includes compiling, binding, obtaining, and subscribing to driver services. The details are as follows: - -1. Release a driver service. - - ``` - Define the driver service structure. - struct ISampleDriverService { - struct IDeviceIoService ioService; // The first member of the service structure must be a member of the IDeviceIoService type. - int32_t (*ServiceA)(void); // The first service interface of the driver. - int32_t (*ServiceB)(uint32_t inputCode); // The second service interface of the driver. The rest can be deduced by analogy. - }; - - Implementation of the driver service interface - int32_t SampleDriverServiceA(void) - { - // You need to implement the service logic. - return 0; - } - - int32_t SampleDriverServiceB(uint32_t inputCode) - { - // You need to implement the service logic. - return 0; - } - ``` - -2. Bind the driver service to the HDF and implement the **Bind** function in the **HdfDriverEntry** structure. - - ``` - int32_t SampleDriverBind(struct HdfDeviceObject *deviceObject) - { - // deviceObject indicates the pointer to the device object created by the HDF for each driver. It is used to store device-related private data and service interfaces. - if (deviceObject == NULL) { - HDF_LOGE("Sample device object is null!"); - return -1; - } - static struct ISampleDriverService sampleDriverA = { - .ServiceA = SampleDriverServiceA, - .ServiceB = SampleDriverServiceB, - }; - deviceObject->service = &sampleDriverA.ioService; - return 0; - } - ``` - -3. Obtain the driver service. - - You can either use the API or subscription mechanism provided by the HDF to obtain the driver service. - - - Using the API - - After the driver is loaded, you can obtain the driver service using the API provided by the HDF, as shown in the following: - - ``` - const struct ISampleDriverService *sampleService = - (const struct ISampleDriverService *)DevSvcManagerClntGetService("sample_driver"); - if (sampleService == NULL) { - return -1; - } - sampleService->ServiceA(); - sampleService->ServiceB(5); - ``` - - - Using the subscription mechanism - - If the kernel mode is unaware of the time for loading drivers \(on the same host\), use the subscription mechanism provided by the HDF to subscribe to the drivers. After the drivers are loaded, the HDF releases the driver services to you. The implementation is as follows: - - ``` - // Subscription callback function. After the subscribed drivers are loaded, the HDF releases the driver services to you using this function. - // object indicates the pointer to the private data of the subscriber, and service indicates the pointer to the subscribed service. - int32_t TestDriverSubCallBack(struct HdfDeviceObject *deviceObject, const struct HdfObject *service) - { - const struct ISampleDriverService *sampleService = - (const struct ISampleDriverService *)service; - if (sampleService == NULL) { - return -1; - } - sampleService->ServiceA(); - sampleService->ServiceB(5); - } - // Implement the subscription process. - int32_t TestDriverInit(struct HdfDeviceObject *deviceObject) - { - if (deviceObject == NULL) { - HDF_LOGE("Test driver init failed, deviceObject is null!"); - return -1; - } - struct SubscriberCallback callBack; - callBack.deviceObject = deviceObject; - callBack.OnServiceConnected = TestDriverSubCallBack; - int32_t ret = HdfDeviceSubscribeService(deviceObject, "sample_driver", callBack); - if (ret != 0) { - HDF_LOGE("Test driver subscribe sample driver failed!"); - } - return ret; - } - ``` +## When to Use +The driver service management capability can be used if the driver provides capabilities using APIs. +## Available APIs + +The table below describes the APIs for driver service management. + + **Table 1** APIs for driver service management + +| API| Description| +| -------- | -------- | +| int32_t (\*Bind)(struct HdfDeviceObject \*deviceObject); | Binds a service API to the HDF. You need to implement the **Bind()** function.| +| const struct HdfObject \*DevSvcManagerClntGetService(const char \*svcName); | Obtains a driver service.| +| int HdfDeviceSubscribeService(
struct HdfDeviceObject \*deviceObject, const char \*serviceName, struct SubscriberCallback callback); | Subscribes to a driver service.| + + +## How to Develop + +The development procedure is as follows: + +1. Define the services to be provided by the driver. + + ``` + Define the driver service structure. + struct ISampleDriverService { + struct IDeviceIoService ioService; // The first member must be of the IDeviceIoService type. + int32_t (*ServiceA)(void); // API of the first driver service. + int32_t (*ServiceB)(uint32_t inputCode); // API of the second driver service. You can add more as required. + }; + + Implement the driver service APIs. + int32_t SampleDriverServiceA(void) + { + // You need to implement the service logic. + return 0; + } + + int32_t SampleDriverServiceB(uint32_t inputCode) + { + // You need to implement the service logic. + return 0; + } + ``` + +2. Bind the driver service to the HDF and implement the **Bind()** function in the **HdfDriverEntry** structure. + + ``` + int32_t SampleDriverBind(struct HdfDeviceObject *deviceObject) + { + // deviceObject is a pointer to the device object created by the HDF for each driver. The device object holds private device data and service APIs. + if (deviceObject == NULL) { + HDF_LOGE("Sample device object is null!"); + return -1; + } + static struct ISampleDriverService sampleDriverA = { + .ServiceA = SampleDriverServiceA, + .ServiceB = SampleDriverServiceB, + }; + deviceObject->service = &sampleDriverA.ioService; + return 0; + } + ``` + +3. Obtain the driver service. + The driver service can be obtained by using the API or subscription mechanism provided by the HDF. + + - Using the API + Use the API provided by the HDF to obtain the driver service if the driver has been loaded. + + + ``` + const struct ISampleDriverService *sampleService = + (const struct ISampleDriverService *)DevSvcManagerClntGetService("sample_driver"); + if (sampleService == NULL) { + return -1; + } + sampleService->ServiceA(); + sampleService->ServiceB(5); + ``` + - Using the subscription mechanism + If the kernel mode is unaware of the time for loading drivers on the same host, use the subscription mechanism provided by the HDF to subscribe to the drivers. After the drivers are loaded, the HDF sends the driver services to the subscriber. The implementation is as follows: + + + ``` + // Callback invoked to return the driver services after the subscribed driver is loaded. + // object is the pointer to the private data of the subscriber, and service is the pointer to the subscribed service object. + int32_t TestDriverSubCallBack(struct HdfDeviceObject *deviceObject, const struct HdfObject *service) + { + const struct ISampleDriverService *sampleService = + (const struct ISampleDriverService *)service; + if (sampleService == NULL) { + return -1; + } + sampleService->ServiceA(); + sampleService->ServiceB(5); + } + // Implement the subscription process. + int32_t TestDriverInit(struct HdfDeviceObject *deviceObject) + { + if (deviceObject == NULL) { + HDF_LOGE("Test driver init failed, deviceObject is null!"); + return -1; + } + struct SubscriberCallback callBack; + callBack.deviceObject = deviceObject; + callBack.OnServiceConnected = TestDriverSubCallBack; + int32_t ret = HdfDeviceSubscribeService(deviceObject, "sample_driver", callBack); + if (ret != 0) { + HDF_LOGE("Test driver subscribe sample driver failed!"); + } + return ret; + } + ``` -- GitLab