Qualcomm Enhanced SDK (QESDK）API参考 （12）

---

6.3 通用位置 API、回调、枚举和结构体

6.3.1 通用位置函数

requestPreciseLocationUpdates
启动米级精度的精确定位跟踪会话。

requestPreciseLocationUpdates( )

Note
当 minIntervalMillis 设置为 0 时，只要数据准备就绪，就会调用回调，即引擎支持的最短间隔。
目前 minIntervalMillis 设为任何其他值都会在内部默认为 1 秒，精确定位会话以 1 秒的间隔运行。

removePreciseLocationUpdates
停止正在进行的精确位置会话。

removePreciseLocationUpdates()

registerLocationCapabilitiesCallback
注册以接收在 LocationCapabilities 枚举中定义的位置模块功能。
Previous

registerLocationCapabilitiesCallback( )

6.3.2 原生 NTRIP 客户端 API

这些 API 配置并使用原生 NTRIP 客户端向精确定位引擎 (eDGNSS/RTK) 提供校正数据

Note
仅允许 OEM 应用程序运行这些 API。缺少 OEM 权限将返回 EDGNSS_LOCATION_STATUS_FAILURE_UNSUPPORTED。OEM 应用程序需要在 Android manifest 文件中声明 com.qualcomm.qti.permission.ACCESS_PRECISE_LOCATION_API 用户权限，以调用原生 NTRIP 配置 API。

updateNTRIPGGAConsent
为原生 NTRIP 客户端授予权限，使其可以与 NTRIP 服务器共享 GGA NMEA。如果 NTRIP 服务器不需要 GGA NMEA 数据，则用户无需接受 GGA NMEE 许可。如果 NTRIP 服务器需要 GGA NMEA 数据，用户应接受获取校正数据的许可。仅允许 OEM 应用程序运行此 API。

updateNTRIPGGAConsent( )

enablePPENtripStream
在定位模块中启用原生 NTRIP 客户端。一次只需要一个 OEM 应用程序配置 NTRIP 原生客户端。

enablePPENtripStream( )

disablePPENtripStream
禁用原生 NTRIP 服务器。仅允许 OEM 应用程序运行此 API。

disablePPENtripStream( )

6.3.3 应用程序校正数据 API

这些 API 用于将应用程序注册为校正数据源，并在请求时注入校正后的数据。

registerAsCorrectionDataSource
将应用程序注册为精确定位引擎的校正数据提供程序。这是应用程序请求精确位置更新时必须调用的 API。

deRegisterAsCorrectionDataSource
删除作为校正数据提供程序的应用程序。一旦作为校正数据提供程序的应用程序被删除，就无法再请求精确的位置更新。

injectCorrectionData
注入校正数据以供精确定位引擎使用。

6.3.4 位置回调

ILocationReportCallback
此回调接收位置字段作为参数。

ILocationCapabilitiesCallback
此回调接收功能掩码作为参数。

ICorrectionStreamingControlCallback
此回调接收启动或停止向精确定位引擎传输校正数据的请求作为参数。收到此回调时，应用程序必须根据参数值来选择开始或停止校正数据注入。

6.3.5 位置枚举

6.3.5.1 位置状态

Note
RTK 子系统用 RTK 替换 EDGNSS。

值	说明
EDGNSS_LOCATION_STATUS_SUCCESS	操作成功
EDGNSS_LOCATION_STATUS_FAILURE	无法预见的内部错误。
EDGNSS_LOCATION_STATUS_FAILURE_UNSUPPORTED	操作不受支持。
EDGNSS_LOCATION_STATUS_FAILURE_INVALID_ARGS	指定的参数值无效。
EDGNSS_LOCATION_STATUS_FAILURE_MISSING_CBA	回调缺失。
EDGNSS_LOCATION_STATUS_FAILURE_NO_CORRECTION_DATA	应用程序尚未注册为校正数据源（通过 registerAsCorrectionDataSource）。
EDGNSS_LOCATION_STATUS_FAILURE_MISSING_PERMISSION	应用程序缺少一项或多项强制性权限。

6.3.5.2 LocationQuality

Note
RTK 系统用 RTK 替换 EDGNSS 时使用。

枚举值	说明
EDGNSS_LOCATION_QUALITY_STANDALONE	仅使用卫星信号计算的位置。
EDGNSS_LOCATION_QUALITY_DGNSS	使用卫星信号和 eDGNSS 技术计算的位置。
EDGNSS_LOCATION_QUALITY_FLOAT	使用卫星信号和 RTK 技术计算的位置；浮点型。
Note	不适用于 EDGNSS 子系统
EDGNSS_LOCATION_QUALITY_FIXED	不适用。

6.3.5.3 CorrectionDataType

枚举值
CORRECTION_DATA_TYPE_EDGNSS
CORRECTION_DATA_TYPE_RTK

6.3.5.4 LocationCapabilities

枚举值	整数值
PP_LOCATION_CAPABILITIES_EDGNSS_BIT	1
PP_LOCATION_CAPABILITIES_RTK_BIT	2

6.3.5.5 LocationFlagsBits

枚举值	整数值
PP_LOCATION_HAS_LAT_LONG_BIT	1
PP_LOCATION_HAS_ALTITUDE_BIT	2
PP_LOCATION_HAS_SPEED_BIT	4
PP_LOCATION_HAS_BEARING_BIT	8
PP_LOCATION_HAS_ACCURACY_BIT	16
PP_LOCATION_HAS_VERTICAL_ACCURACY_BIT	32
PP_LOCATION_HAS_SPEED_ACCURACY_BIT	64
PP_LOCATION_HAS_BEARING_ACCURACY_BIT	128
PP_LOCATION_HAS_ELAPSED_REAL_TIME_BIT	256
PP_LOCATION_HAS_ELAPSED_REAL_TIME_UNC_BIT	512

6.3.6 支持类和结构体

位置报告

位置类 (Java) / pp_rtk_Location 结构体（原生）

Note
精度字段指示 +/- 对应的值。

6.4 代码示例

Java
需要导入

import com.qualcomm.qti.qesdkIntf.IQesdk;
import com.qualcomm.qti.qesdk.QesdkStatusException;
import com.qualcomm.qti.qesdk.Location.PP_eDGNSSUDT;
import com.qualcomm.qti.qesdk.Location.PP_RTKUDT;
import com.qualcomm.qti.qesdk.Location.IPP_RTKCBs;
import com.qualcomm.qti.qesdk.Location.IPP_eDGNSSCBs;
import com.qualcomm.qti.qesdk.Location.PP_RTKEnums;
import com.qualcomm.qti.qesdk.Location.PP_RTKManager;
import com.qualcomm.qti.qesdk.Location.PP_eDGNSSEnums;
import com.qualcomm.qti.qesdk.Location.PP_eDGNSSManager;

声明需要对象

private IQesdk mQesdkManager;
private PP_eDGNSSManager mPpeEdgnssManager;
private PP_RTKManager mPpeRtkManager;

创建 QESDK 管理器实例并进行初始化

mQesdkManager = IQesdk.createInstance(this);
int statusId = qesdkManager.init(eventCallbackHandler);

根据需要创建 eDGNSS 或 RTK 管理器实例

mPpeEdgnssManager = new PP_eDGNSSManager(mQesdkManager);
mPpeRtkManager = new PP_RTKManager(mQesdkManager);

设置回调

IQesdkEventCallBack eventCallbackHandler = new IQesdkEventCallBack() {
      @Override
      public void onEvent(int opcode, int[] subsys) {
      // Handle QESDK event
      }
      };
      
      // For Checking eDGNSS/ RTK precise positioning Capabilities 
      private IPP_eDGNSSCBs.ILocationCapabilitiesCallback locationCapabilitiesCallback = new IPP_eDGNSSCBs.ILocationCapabilitiesCallback() {
      @Override
      public void onValues(long l) {
      // Check precise positioning Capabilities
      }
      };
      
      
      // For controlling correction data streaming to Precise Positioning engine
      private IPP_eDGNSSCBs.ICorrectionStreamingControlCallback streamingControlCallback = new IPP_eDGNSSCBs.ICorrectionStreamingControlCallback() {
      @Override
      public void onValues(PP_eDGNSSEnums.CorrectionStreamingState correctionStreamingState) {
      // Start or Stop correction data streaming as requested
      }
      };
      
      // For handling location reports
      private IPP_eDGNSSCBs.ILocationReportCallback eDgnssLocationReportCallback = new IPP_eDGNSSCBs.ILocationReportCallback() {
      @Override
      public void onValues(PP_eDGNSSUDT.Location location) {
      // Handle eDGNSS location report callback
      }
      };
      
      private IPP_RTKCBs.ILocationReportCallback rtkLocationReportCallback = new IPP_RTKCBs.ILocationReportCallback() {
      @Override
      public void onValues(PP_RTKUDT.Location location) {
      // Handle RTK location report callback        
      }
      };

获取位置功能

registerLocationCapabilitiesCallback(locationCapabilitiesCallback)

更新原生 NTRIP 客户端的 NTRIP GGA 许可（仅限 OEM 应用程序）

mPpeEdgnssManager.updateNTRIPGGAConsent(ntripGgaConsent);

如有需要，配置原生 NTRIP 客户端（仅限 OEM 应用程序）

// enable Native NTRIP client
mPpeEdgnssManager.enablePPENtripStream(
      hostNameOrIp, mountPoint,
      username, password, port,
      requiresNmeaLocation, useSSL,
      enableRTKEngine);
      
// Disable Native NTRIP client
mPpeEdgnssManager.disablePPENtripStream();

注册为校正数据提供程序

mPpeEdgnssManager.registerAsCorrectionDataSource(
correctionDataType, streamingControlCallback);

取消作为校正数据提供程序的注册

mPpeEdgnssManager.deRegisterAsCorrectionDataSource();

发送精确位置更新请求

mPpeEdgnssManager.requestPreciseLocationUpdates(
            minIntervalMillis, eDgnssLocationReportCallback);

或

mPpeRtkManager.requestPreciseLocationUpdates(
      minIntervalMillis, rtkLocationReportCallback);

删除精确位置更新请求

mPpeEdgnssManager.removePreciseLocationUpdates(eDgnssLocationReportCallback)

或

mPpeRtkManager.removePreciseLocationUpdates(rtkLocationReportCallback)

收到 StreamingControlCallback 以开始校正数据注入时，从应用程序 NTRIP 客户端下载校正数据然后注入。

mPpeEdgnssManager.injectCorrectionData(correctionData);

接收注册的 ILocationReportCallback 中的精确位置报告。

原生
需要包括的内容

#include "qesdk_ndk.h"
#include "qesdk_Location_PP_eDGNSS.h"
#include "qesdk_Location_PP_RTK.h"

初始化

qesdk_handle_t qesdk_handle = qesdk_init(nativeLicense, len, event_callback_handler);
PP_RTKManager *rtkManager = new PP_RTKManager();
PP_eDGNSSManager *edgnssManager = new PP_eDGNSSManager();
int ret = rtkManager->init(nativeLicense, len, event_callback_handler);
ret = edgnssManager->init(nativeLicense, len, event_callback_handler);

设置回调

void event_callback_handler(uint32_t opcode, uint32_t subsys[]) {
      // Callback to handle QESDK events
      }
      
      
void location_capabilities_callback(uint64_t capabilitiesMask){
      // Check precise positioning Capabilities
      }
      
void edgnss_CorrectionStreamingControlCallback(pp_edgnss_CorrectionStreamingState streamingState){
      // Start or Stop correction data streaming as requested
      }
      
void edgnss_LocationReportCallback(pp_edgnss_Location location){
      // Handle eDGNSS location report callback
      }
      
void rtk_LocationReportCallback(pp_rtk_Location location){
      // Handle RTK location report callback
      }

获取位置功能

ret = edgnssManager->registerLocationCapabilitiesCallback(location_capabilities_callback);

更新原生 NTRIP 客户端的 NTRIP GGA 许可（仅限 OEM 应用程序）

ret = edgnssManager->updateNTRIPGGAConsent(ntrip_gga_consent);

如有需要，配置原生 NTRIP 客户端（仅限 OEM 应用程序）

// enable Native NTRIP client
ret = edgnssManager->enablePPENtripStream(hostNameIP, mountPoint, userName, pass, server_port, require_nmealocation, use_ssl, enable_rtkengine);
// Disable Native NTRIP client
ret = edgnssManager->disablePPENtripStream();

注册为校正数据提供程序

ret = edgnssManager->registerAsCorrectionDataSource((pp_edgnss_CorrectionDataType)correction_data_type, edgnss_CorrectionStreamingControlCallback);

取消作为校正数据提供程序的注册

ret = edgnssManager->deRegisterAsCorrectionDataSource();

发送精确位置更新请求

ret = edgnssManager->requestPreciseLocationUpdates(min_interval_ms, edgnss_LocationReportCallback); 

或

ret = rtkManager->requestPreciseLocationUpdates(min_interval_ms, rtk_LocationReportCallback);

删除精确位置更新请求

ret = edgnssManager->removePreciseLocationUpdates(edgnss_LocationReportCallback);

或

ret = rtkManager->removePreciseLocationUpdates(rtk_LocationReportCallback);

收到 StreamingControlCallback 以开始校正数据注入时，从应用程序 NTRIP 客户端下载校正数据然后注入。

ret = edgnssManager->injectCorrectionData(corr_data);

接收注册的 ILocationReportCallback 中的精确位置报告。