深入浅出高通QMI(5)：QMI核心服务进阶接口速查表

本文为《深入浅出高通QMI》系列的配套速查表，汇总了CTL、DMS、NAS、WDS四大核心服务的高级接口、关键参数与典型调用示例，方便开发者快速查阅与调用。

一、CTL（Control Service）—— 控制服务

1. 服务状态查询

用途：实时获取指定服务的运行状态（启用/禁用/异常）。

请求消息：
CTL_GET_SERVICE_STATUS_REQ_V01

关键字段：

uint32_tservice_id;// 目标服务ID，如NAS=0x02

响应消息：
CTL_GET_SERVICE_STATUS_RESP_V01

关键字段：

uint32_tservice_status;// 状态：1=启用，2=禁用，3=异常

调用示例：

ctl_get_service_status_req_msg_v01 req={0};ctl_get_service_status_resp_msg_v01 resp={0};req.service_id=0x02;// NAS服务qmi_client_send_msg_sync(ctl_handle,CTL_GET_SERVICE_STATUS_REQ_V01,&req,sizeof(req),&resp,sizeof(resp),3000);

2. 客户端权限设置

用途：限制客户端对特定服务的访问权限。

请求消息：
CTL_SET_CLIENT_PERMISSIONS_REQ_V01

关键字段：

uint32_tclient_id;uint32_tpermission_mask;// 权限掩码

常用权限掩码：

CTL_PERMISSION_DMS_READ// 允许读DMSCTL_PERMISSION_DMS_WRITE// 允许写DMSCTL_PERMISSION_NAS_READ// 允许读NASCTL_PERMISSION_WDS_WRITE// 允许写WDS

调用示例：

ctl_set_client_permissions_req_msg_v01 req={0};req.client_id=client_id;req.permission_mask_valid=1;req.permission_mask=CTL_PERMISSION_DMS_READ|CTL_PERMISSION_WDS_WRITE;

3. 服务重启

用途：重启指定的异常服务。

请求消息：
CTL_RESTART_SERVICE_REQ_V01

关键字段：

uint32_tservice_id;// 需重启的服务ID

调用示例：

ctl_restart_service_req_msg_v01 req={0};req.service_id=0x02;// 重启NAS服务qmi_client_send_msg_sync(ctl_handle,CTL_RESTART_SERVICE_REQ_V01,&req,sizeof(req),&resp,sizeof(resp),5000);

二、DMS（Device Management Service）—— 设备管理服务

1. 射频频段设置

用途：配置Modem支持的通信频段。

请求消息：
DMS_SET_RF_BAND_PREF_REQ_V01

关键字段：

uint64_tlte_bands;// LTE频段掩码uint64_tnr5g_bands;// 5G NR频段掩码

常用频段掩码：

LTE_BAND_1=1<<0LTE_BAND_3=1<<2LTE_BAND_7=1<<6NR5G_BAND_78=1<<77

调用示例：

dms_set_rf_band_pref_req_msg_v01 req={0};req.rf_band_pref_valid=1;req.rf_band_pref.lte_bands=LTE_BAND_1|LTE_BAND_3;req.rf_band_pref.nr5g_bands=NR5G_BAND_78;

2. 固件信息查询

用途：获取Modem固件版本、编译时间等。

请求消息：
DMS_GET_FIRMWARE_INFO_REQ_V01

响应关键字段：

charfirmware_version[QMI_DMS_FIRMWARE_VERSION_LENGTH_V01];charbuild_date[QMI_DMS_BUILD_DATE_LENGTH_V01];

调用示例：

dms_get_firmware_info_req_msg_v01 req={0};dms_get_firmware_info_resp_msg_v01 resp={0};qmi_client_send_msg_sync(dms_handle,DMS_GET_FIRMWARE_INFO_REQ_V01,&req,sizeof(req),&resp,sizeof(resp),3000);

三、NAS（Network Access Service）—— 网络接入服务

1. 网络模式锁定

用途：强制Modem工作在指定网络模式。

请求消息：
NAS_SET_SYSTEM_SELECTION_PREFERENCE_REQ_V01

关键字段：

uint32_tsystem_preference;// 网络模式偏好

常用模式枚举：

NAS_SYSTEM_PREF_LTE_ONLY_V01// 仅4GNAS_SYSTEM_PREF_5G_SA_ONLY_V01// 仅5G SANAS_SYSTEM_PREF_5G_NSA_ONLY_V01// 仅5G NSANAS_SYSTEM_PREF_AUTOMATIC_V01// 自动选择

调用示例：

nas_set_system_selection_preference_req_msg_v01 req={0};req.system_preference_valid=1;req.system_preference=NAS_SYSTEM_PREF_5G_SA_ONLY_V01;

2. 信号强度详细查询

用途：获取RSRP、RSRQ、SINR等5G关键指标。

请求消息：
NAS_GET_SIGNAL_STRENGTH_DETAILED_REQ_V01

响应关键字段：

floatrsrp;// 参考信号接收功率（dBm）floatrsrq;// 参考信号接收质量（dB）floatsinr;// 信号干扰噪声比（dB）

调用示例：

nas_get_signal_strength_detailed_req_msg_v01 req={0};nas_get_signal_strength_detailed_resp_msg_v01 resp={0};qmi_client_send_msg_sync(nas_handle,NAS_GET_SIGNAL_STRENGTH_DETAILED_REQ_V01,&req,sizeof(req),&resp,sizeof(resp),3000);

四、WDS（Wireless Data Service）—— 无线数据服务

1. 多APN并发连接

用途：同时建立多个不同APN的数据连接。

请求消息：
WDS_START_NETWORK_INTERFACE_REQ_V01

关键字段：

charapn_name[WDS_APN_NAME_MAX_LENGTH_V01];uint8_tip_family;// IP类型：4=IPv4，6=IPv6，10=IPv4v6

调用示例：

wds_start_network_interface_req_msg_v01 req={0};strncpy(req.apn_name,"crmnet",sizeof(req.apn_name)-1);req.ip_family_valid=1;req.ip_family=10;// IPv4v6

2. 数据连接统计

用途：获取当前连接的丢包率、延迟、吞吐量。

请求消息：
WDS_GET_PACKET_STATISTICS_REQ_V01

响应关键字段：

uint64_ttx_packets;// 发送包数uint64_trx_packets;// 接收包数uint64_ttx_bytes;// 发送字节数uint64_trx_bytes;// 接收字节数uint32_ttx_packet_errors;// 发送错误数

调用示例：

wds_get_packet_statistics_req_msg_v01 req={0};wds_get_packet_statistics_resp_msg_v01 resp={0};qmi_client_send_msg_sync(wds_handle,WDS_GET_PACKET_STATISTICS_REQ_V01,&req,sizeof(req),&resp,sizeof(resp),3000);

五、错误码速查

六、服务ID速查

七、调用模板（同步/异步）

同步调用模板：

qmi_client_error_type err;err=qmi_client_send_msg_sync(handle,// 服务句柄msg_id,// 消息IDreq,sizeof(req),// 请求结构体resp,sizeof(resp),// 响应结构体timeout_ms// 超时时间);

异步调用模板：

qmi_client_error_type err;void*txn_handle;err=qmi_client_send_msg_async(handle,msg_id,req,sizeof(req),resp,sizeof(resp),callback,// 回调函数context,// 用户上下文&txn_handle// 事务句柄);

八、注意事项

1. 初始化顺序：CTL → UIM → NAS → WDS（遵循依赖关系）。
2. Client ID：必须先通过CTL注册获取，否则无法调用其他服务。
3. 资源释放：按初始化逆序释放，先业务服务后CTL。
4. 线程安全：多客户端并发时使用互斥锁保护共享资源。
5. 日志脱敏：IMEI、ICCID等敏感信息在日志中需掩码处理。