diff --git a/en/device-dev/subsystems/subsys-tel-guide.md b/en/device-dev/subsystems/subsys-tel-guide.md index b617c07e4b2ffce46ae5d8c53e18269bad5e7d49..889f2b8c452ef67da653750c2806c71f4ecfc2dd 100644 --- a/en/device-dev/subsystems/subsys-tel-guide.md +++ b/en/device-dev/subsystems/subsys-tel-guide.md @@ -4,7 +4,7 @@ ### When to Use -Initializing a modem vendor library means to implement **const HRilOps \*RilInitOps\(const struct HRilReport \*reportOps\)** function in the vendor library. This function is mainly used to: +Initializing a modem vendor library means to implement **const HRilOps \*RilInitOps\(const struct HRilReport \*reportOps\)** function in the vendor library. This function is mainly used to: - Receive function pointers to event callbacks of RIL Adapter. When a service event needs to be reported, the target pointer will be called to report the event to RIL Adapter. - Create a thread for reading modem nodes. In this thread, the data reported by the modem is read cyclically and parsed as a specific service event for reporting. @@ -14,29 +14,15 @@ Initializing a modem vendor library means to implement **const HRilOps \*RilIni The following table describes the API for initializing a modem vendor library. -**Table 1** API for initializing a modem vendor library - - - - - - - - - - -

API

-

Description

-

const HRilOps *RilInitOps(const struct HRilReport * reportOps)

-

Function: Provides an entry for running a modem vendor library.

-

Input parameter:

-

reportOps: Specifies the pointer to the event callback function, which is passed by RIL Adapter.

-

Return result: function pointer of the service request API.

-
+**Table 1** API for initializing a modem vendor library + +| API | Description | +| -------- | -------- | +| const HRilOps \*RilInitOps(const struct HRilReport \* reportOps) | Provides an entry for running a modem vendor library.
Input parameter:
**reportOps**: Specifies the pointer to the event callback function, which is passed by RIL Adapter.
Return result: function pointer of the service request API. | ### How to Develop -1. Set the event callback function pointers passed by RIL Adapter through **RilInitOps**. +1. Set the event callback function pointers passed by RIL Adapter through **RilInitOps**. ``` // Define the callback function pointers of the modem vendor library. @@ -51,7 +37,7 @@ The following table describes the API for initializing a modem vendor library. ``` -1. Create the **g\_reader** main thread to enable message looping. +1. Create the **g\_reader** main thread to enable message looping. ``` pthread_attr_t t; @@ -61,7 +47,7 @@ The following table describes the API for initializing a modem vendor library. ``` -1. In the **g\_eventListeners** thread, use **open\(\)** to open a modem node and then create the **g\_reader** thread to read and process messages reported by the modem. +1. In the **g\_eventListeners** thread, use **open\(\)** to open a modem node and then create the **g\_reader** thread to read and process messages reported by the modem. ``` g_fd = open(g_devicePath, O_RDWR); // Open the device node specified by g_devicePath. @@ -121,7 +107,7 @@ The following table describes the API for initializing a modem vendor library. ### Debugging and Verification -1. Use the [hdc\_std](https://gitee.com/openharmony/docs/blob/master/en/device-dev/subsystems/subsys-toolchain-hdc-guide.md#preparations) tool to connect to a debugging device. Then, run the following command to send the generated **libril\_vendor.z.so** library file to the **/system/lib/** directory of the device. For details about how to integrate a library file, see [Integrating Modem Vendor Libraries](#section590mcpsimp). +1. Use the [hdc\_std](https://gitee.com/openharmony/docs/blob/master/en/device-dev/subsystems/subsys-toolchain-hdc-guide.md#preparations) tool to connect to a debugging device. Then, run the following command to send the generated **libril\_vendor.z.so** library file to the **/system/lib/** directory of the device. For details about how to integrate a library file, see [Integrating Modem Vendor Libraries](#section590mcpsimp). ``` hdc_std file send libril_vendor.z.so /system/lib/ @@ -134,7 +120,7 @@ The following table describes the API for initializing a modem vendor library. hdc_std shell reboot ``` -3. Run the **hdc\_std shell hilog** command to view the debug log, and check whether the **RilInitOps\(\)** function is successfully executed. The following debug log is for reference: +3. Run the **hdc\_std shell hilog** command to view the debug log, and check whether the **RilInitOps\(\)** function is successfully executed. The following debug log is for reference: ``` 01-01 05:13:23.071 136 2319 D 00000/RilAdapterInit: [RilAdapterDispatch-(hril_hdf.c:55)] sbuf IPC obtain test success! @@ -153,41 +139,16 @@ After receiving a specific telephony service request, RIL Adapter calls the targ The following table describes the APIs for responding to modem service requests, with the dial module as an example. -**Table 2** APIs for responding to modem service requests - - - - - - - - - - - - - -

API

-

Description

-

void ReqDial(ReqDataInfo *requestInfo, const void *data, size_t dataLen);

-

Function: Processes number dial requests.

-

Input parameters:

-
  • requestInfo: request type
-
  • data: called number
-
  • dataLen: data length
-

Return value: none

-

void (*OnCallReport)(struct ReportInfo reportInfo, const void *data, size_t dataLen);

-

Function: Reports the execution result of a service request to RIL Adapter.

-

Input parameters:

-
  • reportInfo: request type
-
  • data: called number
-
  • dataLen: data length
-

Return value: none

-
+**Table 2** APIs for responding to modem service requests + +| API | Description | +| -------- | -------- | +| void ReqDial(ReqDataInfo \*requestInfo, const void \*data, size_t dataLen); | Processes number dial requests.
Input parameters:
**requestInfo**: request type
**data**: called number
**dataLen**: data length
Return value: none | +| void (\*OnCallReport)(struct ReportInfo reportInfo, const void \*data, size_t dataLen); | Reports the execution result of a service request to RIL Adapter.
Input parameters:
**reportInfo**: request type
**data**: called number
**dataLen**: data length
Return value: none | ### How to Develop -1. Implement processing of dial requests in the **ReqDial\(\)** API. +1. Implement processing of dial requests in the **ReqDial\(\)** API. ``` // Implement the API for processing dial requests. @@ -226,7 +187,7 @@ The following table describes the APIs for responding to modem service requests, } ``` -2. After the modem executes the dial command, report the execution result to RIL Adapter via **OnCallReport\(\)**. +2. After the modem executes the dial command, report the execution result to RIL Adapter via **OnCallReport\(\)**. ``` ret = SendCommandLock(cmd, NULL, 0, &pResponse); @@ -241,7 +202,7 @@ The following table describes the APIs for responding to modem service requests, ### Debugging and Verification -1. Use the [hdc\_std](https://gitee.com/openharmony/docs/blob/master/en/device-dev/subsystems/subsys-toolchain-hdc-guide.md#preparations) tool to connect to a debugging device. Then, run the following command to send the generated **libril\_vendor.z.so** library file to the **/system/lib/** directory of the device. +1. Use the [hdc\_std](https://gitee.com/openharmony/docs/blob/master/en/device-dev/subsystems/subsys-toolchain-hdc-guide.md#preparations) tool to connect to a debugging device. Then, run the following command to send the generated **libril\_vendor.z.so** library file to the **/system/lib/** directory of the device. ``` hdc_std file send libril_vendor.z.so /system/lib/ @@ -254,7 +215,7 @@ The following table describes the APIs for responding to modem service requests, hdc_std shell reboot ``` -3. Run the **hdc\_std shell** command. Then, run the **./system/bin/ril\_adapter\_test** command, type **1**, and enter the phone number as prompted to test the call function. +3. Run the **hdc\_std shell** command. Then, run the **./system/bin/ril\_adapter\_test** command, type **1**, and enter the phone number as prompted to test the call function. ``` hdc_std shell @@ -270,7 +231,7 @@ The following table describes the APIs for responding to modem service requests, 1 ``` -4. Open another terminal window, and run the **hdc\_std shell hilog** command. Then, view the log to check whether **ReqDial\(\)** is successfully executed. The following debug log is for reference: +4. Open another terminal window, and run the **hdc\_std shell hilog** command. Then, view the log to check whether **ReqDial\(\)** is successfully executed. The following debug log is for reference: ``` 01-01 05:27:27.419 136 408 D 02b01/Rilvendor: [SendCommandLock-(at_support.c:210)] SendCommandLock enter, cmd: ATD17620373527 @@ -299,30 +260,15 @@ A modem node thread reads the messages reported by the modem cyclically, parses The following table describes the API for reporting modem events. -**Table 3** API for reporting modem events - - - - - - - - - - -

API

-

Description

-

void OnNotifyOps(const char *s, const char *smsPdu)

-

Function: Distributes the events reported by the modem.

-

Input parameters:

-
  • s: AT command prefix
-
  • smsPdu: PDU of the SMS message
-

Return value: none

-
+**Table 3** API for reporting modem events + +| API | Description | +| -------- | -------- | +| void OnNotifyOps(const char \*s, const char \*smsPdu) | Distributes the events reported by the modem.
Input parameters:
**s**: AT command prefix
**smsPdu**: PDU of the SMS message
Return value: none | ### How to Develop -1. Call **OnNotifyOps\(\)** in the g\_reader thread of the modem device node to parse reported modem events. On determining the command type, call **OnXxxReport\(\)** to report the parsed module events to the hril layer. +1. Call **OnNotifyOps\(\)** in the g\_reader thread of the modem device node to parse reported modem events. On determining the command type, call **OnXxxReport\(\)** to report the parsed module events to the hril layer. ``` // Parse the data reported by the modem as events proactively reported by the corresponding module. @@ -352,7 +298,7 @@ The following table describes the API for reporting modem events. ``` -1. Distribute the reported events from the **hril** layer to the Telephony Service layer. +1. Distribute the reported events from the **hril** layer to the Telephony Service layer. ``` // Report the call status proactively. @@ -380,7 +326,7 @@ The following table describes the API for reporting modem events. ### Debugging and Verification -1. Use the [hdc\_std](https://gitee.com/openharmony/docs/blob/master/en/device-dev/subsystems/subsys-toolchain-hdc-guide.md#preparations) tool to connect to a debugging device. Then, run the following command to send the generated **libril\_vendor.z.so** library file to the **/system/lib/** directory of the device. +1. Use the [hdc\_std](https://gitee.com/openharmony/docs/blob/master/en/device-dev/subsystems/subsys-toolchain-hdc-guide.md#preparations) tool to connect to a debugging device. Then, run the following command to send the generated **libril\_vendor.z.so** library file to the **/system/lib/** directory of the device. ``` hdc_std file send libril_vendor.z.so /system/lib/ @@ -393,7 +339,7 @@ The following table describes the API for reporting modem events. hdc_std shell reboot ``` -3. Run the **hdc\_std shell** command. Then, run the **./system/bin/ril\_adapter\_test** command, type **1**, and enter the phone number as prompted to test the call function. +3. Run the **hdc\_std shell** command. Then, run the **./system/bin/ril\_adapter\_test** command, type **1**, and enter the phone number as prompted to test the call function. ``` hdc_std shell @@ -409,7 +355,7 @@ The following table describes the API for reporting modem events. 1 ``` -4. Open another terminal window, and run the **hdc\_std shell hilog** command. Then, view the log to check whether **OnNotifyOps\(\)** is successfully executed. The following debug log is for reference: +4. Open another terminal window, and run the **hdc\_std shell hilog** command. Then, view the log to check whether **OnNotifyOps\(\)** is successfully executed. The following debug log is for reference: ``` 01-01 00:08:01.334 546 551 D 02b01/TelRilTest: [DialResponse-(tel_ril_call.cpp:280)] DialResponse --> radioResponseInfo->serial:2, radioResponseInfo->error:0 @@ -434,16 +380,16 @@ The following table describes the API for reporting modem events. ### Development Examples -- **Outgoing Call** +- **Outgoing Call** The following figure shows the API calling for an outgoing call. - **Figure 1** Time sequence of API calling for an outgoing call + **Figure 1** Time sequence of API calling for an outgoing call ![](figure/en-us_image_0000001171507146.png) - When an application initiates an outgoing call, RIL Adapter receives a call request, and the **hril** layer invokes the **ReqDial\(\)** function. In **ReqDial\(\)**, the data passed by the Telephony Service is encapsulated as an AT command and sent to the modem. After executing the dial command, the modem reports the execution result to RIL Adapter through **OnCallReport\(\)**. + When an application initiates an outgoing call, RIL Adapter receives a call request, and the **hril** layer invokes the **ReqDial\(\)** function. In **ReqDial\(\)**, the data passed by the Telephony Service is encapsulated as an AT command and sent to the modem. After executing the dial command, the modem reports the execution result to RIL Adapter through **OnCallReport\(\)**. ``` // Callback function pointer of the call module @@ -513,18 +459,18 @@ The following table describes the API for reporting modem events. ``` -- **Incoming Call** +- **Incoming Call** The following figure shows the API calling of an incoming call. - **Figure 2** Time sequence of API calling for an incoming call + **Figure 2** Time sequence of API calling for an incoming call ![](figure/en-us_image_0000001214727595.png) - The **g\_reader** thread cyclically reads the messages reported by the modem. When the modem receives an incoming call event, it actively reports the information about the incoming call. + The **g\_reader** thread cyclically reads the messages reported by the modem. When the modem receives an incoming call event, it actively reports the information about the incoming call. - The **g\_reader** thread calls **OnNotifyOps\(\)** to parse the reported information. If the parsed data reported by the modem starts with characters such as **+CRING** or **RING**, it indicates that an incoming call event exists. In this case, the event is reported to RIL Adapter through **OnCallReport\(reportInfo, NULL, 0\)**. + The **g\_reader** thread calls **OnNotifyOps\(\)** to parse the reported information. If the parsed data reported by the modem starts with characters such as **+CRING** or **RING**, it indicates that an incoming call event exists. In this case, the event is reported to RIL Adapter through **OnCallReport\(reportInfo, NULL, 0\)**. ``` // Parse the data reported by the modem as events proactively reported by the corresponding module. @@ -558,7 +504,7 @@ The following table describes the API for reporting modem events. ### Configuring Compilation Information -Compile the modem vendor library into a dynamic library by using **BUILD.gn**. Upon startup, RIL Adapter loads the dynamic library to the system in dlopen mode and then initializes the library. For details about how to implement vendor library initialization, see [Initializing a Modem Vendor Library](#section211mcpsimp). The following is an example of **BUILD.gn**: +Compile the modem vendor library into a dynamic library by using **BUILD.gn**. Upon startup, RIL Adapter loads the dynamic library to the system in dlopen mode and then initializes the library. For details about how to implement vendor library initialization, see [Initializing a Modem Vendor Library](#section211mcpsimp). The following is an example of **BUILD.gn**: ``` import("//build/ohos.gni") @@ -588,5 +534,5 @@ ohos_shared_library("ril_vendor") { // Modem vendor library ### Debugging and Verification 1. Compile the code. -2. Check whether **libril\_vendor.z.so** exists in the **/out/{device_name}/telephony/ril\_adapter** directory. If yes, the integration is successful. Otherwise, correct the error and perform debugging and verification again. +2. Check whether **libril\_vendor.z.so** exists in the **/out/{device_name}/telephony/ril\_adapter** directory. If yes, the integration is successful. Otherwise, correct the error and perform debugging and verification again.