程序包 com.tencent.map.geolocation

## 类 TencentLocationManager

- java.lang.Object
- - com.tencent.map.geolocation.TencentLocationManager

-     public final class TencentLocationManager
      extends java.lang.Object

  用于访问腾讯定位服务的类, 腾讯定位服务可周期性向客户端提供位置更新.

  注意, 使用腾讯定位服务前, 应确保:

  - manifest中配置正确的key, 立即申请key
  - manifest中配置正确的权限, 详情请参考开发指南

- - ### 字段概要

    字段
    修饰符和类型 | 字段 | 说明
    --- | --- | ---
    `static int` | `COORDINATE_TYPE_GCJ02` | 坐标系标识, 国测局坐标(火星坐标).
    `static int` | `COORDINATE_TYPE_WGS84` | 坐标系标识, WGS84坐标(GPS坐标, 地球坐标).
    `static int` | `DR_TYPE_BIKE` |
    `static int` | `DR_TYPE_WALK` |
    `static int` | `SIGN_IN_SCENE` | 签到场景，单次定位，第一次会优先返回精度较高的结果，定位速度可能会延迟1～3S
    `static int` | `SPORT_SCENE` | 运动场景，高精度连续定位，适用于步行或骑行定位，第一次会优先返回精度较高的结果
    `static int` | `TRANSPORT_SCENE` | 出行场景，高精度连续定位，适用于室外出行场景，优先使用卫星定位结果，卫星定位成功之后网络定位不再返回，卫星信号断开之后一段时间才会返回网络结果

  - ### 方法概要

    所有方法 静态方法 实例方法 具体方法 已过时的方法
    修饰符和类型 | 方法 | 说明
    --- | --- | ---
    `void` | `addLocationListener​(TencentLocationListener listener)` | 添加定位监听
    `void` | `changeCallbackInterval​(long callbackInterval)` | 修改 sdk 内部的 gps 回调频率, 会影响 app 请求手机位置信息的次数
    `void` | `disableForegroundLocation​(boolean removeNotification)` | 关闭前台定位服务
    `void` | `enableForegroundLocation​(int notificationId, android.app.Notification notification)` | 开启前台定位服务
    `java.lang.String` | `getBuild()` |
    `int` | `getCoordinateType()` | 获取当前使用的坐标系.
    `TencentLocation` | `getDrPosition()` | 传出计算出的实时位置，调用`startDrEngine(int)`成功后才可能有值
    `static TencentLocationManager` | `getInstance​(android.content.Context context)` | 获取腾讯定位服务实例，该方法需要在带有looper的线程调用，SDK会保证无耗时操作并立即返回。
    `TencentLocation` | `getLastKnownLocation()` | 返回最近一次的位置, 可能为 null.
    `java.lang.String` | `getOaid()` | 获取设备oaid
    `static boolean` | `getUserAgreePrivacy()` | 获取用户是否同意隐私政策协议
    `java.lang.String` | `getVersion()` |
    `boolean` | `isDrSupport()` | 是否支持DR引擎
    `void` | `removeLocationListener​(TencentLocationListener listener)` | 移除定位监听
    `void` | `removeUpdates​(TencentLocationListener listener)` | 移除位置监听器并停止定位.
    `int` | `requestLocationUpdates​(TencentLocationRequest request, TencentLocationListener listener)` | 请求定位, 位置更新将通过 listener 回调通知.
    `int` | `requestLocationUpdates​(TencentLocationRequest request, TencentLocationListener listener, android.os.Looper looper)` | 请求(在与 looper 关联的线程中)定位, 位置更新将通过 listener 回调通知.
    `int` | `requestLocationWithScene​(int scene, TencentLocationListener listener)` | 根据场景请求定位，简化定位相关配置
    `int` | `requestSingleFreshLocation​(TencentLocationRequest request, TencentLocationListener listener, android.os.Looper looper)` | 获取当前单次定位，才方法可在未启动周期性回调时获取一次最新位置 也可以在启动周期性回调时，强制刷新得到一次最新的位置信息 该接口在单次定位时，获取位置结果为1号定位接口，在启动周期性回调时， 结果跟随TencentLocationRequest中设置的定位接口号码。
    `void` | `setCoordinateType​(int coordinateType)` | 设置坐标系.
    `void` | `setDebuggable​(boolean debuggable)` | 已过时。 该方法已废弃，由`setSDKLogListener(TencentLocationLogListener)`代替 设置是否允许内部进入Debug模式[默认为false]。
    `void` | `setDeviceID​(android.content.Context context, java.lang.String deviceID)` | Android Q开始，无法正常读取设备唯一标识，此接口用于配置设备唯一标识 deviceID长度限制为1～63，超过63将选择前63位
    `void` | `setExtraData​(java.lang.String key, java.lang.String value)` |
    `void` | `setMockEnable​(boolean switcher)` | 是否允许mockGps数据 设置为true后将不对mockGps进行过滤
    `void` | `setSDKLogListener​(TencentLocationLogListener logListener)` | 设置接收SDK内部运行时的日志接口 如未设置用或未同意隐私政策，该方法不生效.
    `void` | `setSystemCacheEnable​(boolean switcher)` | 是否允许在定位失败情况下返回系统缓存位置
    `static void` | `setUserAgreePrivacy​(boolean isAgree)` | 设置用户是否同意隐私协议政策
    `int` | `startDrEngine​(int type)` | 启动DR引擎。
    `boolean` | `startIndoorLocation()` | 已过时。
    `boolean` | `stopIndoorLocation()` | 已过时。
    `void` | `stopLocationWithScene​(int scene, TencentLocationListener listener)` | 根据场景停止定位, 与requestLocationWithScene对应
    `void` | `terminateDrEngine()` | 停止DR引擎。
    `void` | `triggerCodeGuarder​(boolean trigger)` |

    - ### 从类继承的方法 java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### 字段详细资料

    - #### DR_TYPE_WALK

          public static int DR_TYPE_WALK

    - #### DR_TYPE_BIKE

          public static int DR_TYPE_BIKE

    - #### COORDINATE_TYPE_GCJ02

          public static final int COORDINATE_TYPE_GCJ02

      坐标系标识, 国测局坐标(火星坐标).
      另请参阅:
        常量字段值

    - #### COORDINATE_TYPE_WGS84

          public static final int COORDINATE_TYPE_WGS84

      坐标系标识, WGS84坐标(GPS坐标, 地球坐标).
      另请参阅:
        常量字段值

    - #### SIGN_IN_SCENE

          public static final int SIGN_IN_SCENE

      签到场景，单次定位，第一次会优先返回精度较高的结果，定位速度可能会延迟1～3S
      另请参阅:
        常量字段值

    - #### SPORT_SCENE

          public static final int SPORT_SCENE

      运动场景，高精度连续定位，适用于步行或骑行定位，第一次会优先返回精度较高的结果
      另请参阅:
        常量字段值

    - #### TRANSPORT_SCENE

          public static final int TRANSPORT_SCENE

      出行场景，高精度连续定位，适用于室外出行场景，优先使用卫星定位结果，卫星定位成功之后网络定位不再返回，卫星信号断开之后一段时间才会返回网络结果

      首次定位或卫星定位丢失后，默认等待超时时间8s，超时无卫星定位将返回网络定位结果

      另请参阅:
        常量字段值

  - ### 方法详细资料

    - #### setUserAgreePrivacy

          public static void setUserAgreePrivacy​(boolean isAgree)

      设置用户是否同意隐私协议政策

      调用其他接口前必须首先调用此接口进行用户是否同意隐私政策的设置，传入true后才能正常使用定位功能

      参数:
        `isAgree` - 是否同意隐私政策

    - #### getUserAgreePrivacy

          public static boolean getUserAgreePrivacy()

      获取用户是否同意隐私政策协议

      设置用户隐私后，可通过该接口判断用户隐私状态

      返回:
        isAgreePrivacy 是否同意隐私政策

    - #### getInstance

          public static TencentLocationManager getInstance​(android.content.Context context)
                                                    throws java.lang.NullPointerException,
                                                           java.lang.IllegalArgumentException

      获取腾讯定位服务实例，该方法需要在带有looper的线程调用，SDK会保证无耗时操作并立即返回。
      参数:
        `context` - Activity, Service, ApplicationContext 等各种 Context
      抛出:
        `java.lang.NullPointerException` - context 为 null
        `java.lang.IllegalArgumentException` - 没有在带有线程调用该方法

    - #### enableForegroundLocation

          public void enableForegroundLocation​(int notificationId,
                                               android.app.Notification notification)
                                        throws java.lang.IllegalArgumentException

      开启前台定位服务

      如未设置用或未同意隐私政策，该方法不生效.

      参数:
        `notificationId` - notifation设置唯一id
        `notification` - 自定义的通知
      抛出:
        `java.lang.IllegalArgumentException` - 非法的的坐标类型，notificationId必须大于0，且notification不为null，否则抛出该异常

    - #### disableForegroundLocation

          public void disableForegroundLocation​(boolean removeNotification)

      关闭前台定位服务

      如未设置用或未同意隐私政策，该方法不生效.

      参数:
        `removeNotification` - 是否移除通知栏通知

    - #### setDebuggable

          public void setDebuggable​(boolean debuggable)

      已过时。
      该方法已废弃，由`setSDKLogListener(TencentLocationLogListener)`代替 设置是否允许内部进入Debug模式[默认为false]。 如果开发者遇到问题，在请求定位前设置为true，内部会将运行日志上传到腾讯服务器，将手机IMEI和当前时间提供给我们，可以分析出现问题的原因。

      如未设置用或未同意隐私政策，该方法不生效.

      参数:
        `debuggable` - 是否允许内部进入Debug模式[默认为false]

    - #### setSDKLogListener

          public void setSDKLogListener​(TencentLocationLogListener logListener)

      设置接收SDK内部运行时的日志接口 如未设置用或未同意隐私政策，该方法不生效.
      参数:
        `logListener` - 日志接口，当设为null时内部将重置

    - #### setCoordinateType

          public void setCoordinateType​(int coordinateType)

      设置坐标系. 缺省的坐标为 GCJ02, 通常*不应*调整.

      如未设置用或未同意隐私政策，该方法不生效.

      参数:
        `coordinateType` - 合法的坐标系只包括 `COORDINATE_TYPE_GCJ02` 和 `COORDINATE_TYPE_WGS84`
      抛出:
        `java.lang.IllegalArgumentException` - 非法的坐标类型
        `java.lang.IllegalStateException` - 未取消位置监听器(定位仍在进行)的情况下调用本方法

    - #### getCoordinateType

          public int getCoordinateType()

      获取当前使用的坐标系.
      返回:
        0-GCJ02坐标系, 1-WGS84坐标系, -1-未设置或未同意用户隐私

    - #### changeCallbackInterval

          public void changeCallbackInterval​(long callbackInterval)

      修改 sdk 内部的 gps 回调频率, 会影响 app 请求手机位置信息的次数

      会同时修改 `TencentLocationRequest.setInterval(long)` 设置的频率, 并保持一致

      如未设置用或未同意隐私政策，该方法不生效.

      目前, 仅在开启连续定位后, 调用此方法才生效

      参数:
        `callbackInterval` - 修改 sdk 内部的 gps 回调频率, 需大于 0, 推荐大于 1000, 单位: 毫秒

    - #### setExtraData

          public void setExtraData​(java.lang.String key,
                                   java.lang.String value)

    - #### requestLocationWithScene

          public int requestLocationWithScene​(int scene,
                                              TencentLocationListener listener)

      根据场景请求定位，简化定位相关配置

      如未设置用或未同意隐私政策，该方法不生效.

      参数:
        `scene` - 目标场景 包括 `SIGN_IN_SCENE`、`SPORT_SCENE` 和 `TRANSPORT_SCENE`
      返回:
        - SIGN_IN_SCENE 和 TRANSPORT_SCENE 参数参照 `requestLocationUpdates(TencentLocationRequest, TencentLocationListener)` 返回值
        - SPORT_SCENE 参照 `startDrEngine(int)` 返回值
      抛出:
        `java.lang.IllegalArgumentException` - 非法的使用场景

    - #### stopLocationWithScene

          public void stopLocationWithScene​(int scene,
                                            TencentLocationListener listener)

      根据场景停止定位, 与requestLocationWithScene对应

      目标场景为`SPORT_SCENE`或`TRANSPORT_SCENE`时需要调用停止定位; `SIGN_IN_SCENE`为单次定位，无需调用此接口

      如未设置用或未同意隐私政策，该方法不生效.

      参数:
        `scene` - 目标场景 包括 `SPORT_SCENE` 和 `TRANSPORT_SCENE`
      抛出:
        `java.lang.IllegalArgumentException` - 非法的使用场景

    - #### requestLocationUpdates

          public int requestLocationUpdates​(TencentLocationRequest request,
                                            TencentLocationListener listener)

      请求定位, 位置更新将通过 listener 回调通知.

      强烈建议在主线程中调用本方法, 定位完成后(无论定位成功或失败)都应尽快移除 listener, 否则可能不必要地消耗较多电量.

      参数:
        `request` - 定位请求
        `listener` - 位置监听器
      返回:
        0-成功注册监听器, 1-设备缺少使用腾讯定位服务需要的基本条件, 2-manifest 中配置的 key 不正确, 3-自动加载libtencentloc.so失败, 4-未设置或未同意用户隐私
      抛出:
        `java.lang.NullPointerException` - request 或 listener 为 null

    - #### requestLocationUpdates

          public int requestLocationUpdates​(TencentLocationRequest request,
                                            TencentLocationListener listener,
                                            android.os.Looper looper)

      请求(在与 looper 关联的线程中)定位, 位置更新将通过 listener 回调通知.

      强烈建议在主线程中调用本方法, 定位完成后(无论定位成功或失败)都应尽快移除 listener, 否则可能不必要地消耗较多电量.

      注意: 由于回调方法在新线程中调用, 回调方法中*不应*执行某些必须在主线程中完成的操作, 比如更新UI.

      参数:
        `request` - 定位请求
        `listener` - 位置监听器
        `looper` - looper
      返回:
        0-成功注册监听器, 1-设备缺少使用腾讯定位服务需要的基本条件, 2-manifest 中配置的 key 不正确, 3-自动加载libtencentloc.so失败， 4-未设置或未同意用户隐私
      抛出:
        `java.lang.NullPointerException` - request, listener 或者 looper 为 null

    - #### requestSingleFreshLocation

          public int requestSingleFreshLocation​(TencentLocationRequest request,
                                                TencentLocationListener listener,
                                                android.os.Looper looper)

      获取当前单次定位，才方法可在未启动周期性回调时获取一次最新位置 也可以在启动周期性回调时，强制刷新得到一次最新的位置信息 该接口在单次定位时，获取位置结果为1号定位接口，在启动周期性回调时， 结果跟随TencentLocationRequest中设置的定位接口号码。
      参数:
        `listener` - ，回调完成后，sdk中会置null释放指向，防止内存泄漏
      返回:
        0-成功注册监听器, 1-设备缺少使用腾讯定位服务需要的基本条件, 2-manifest 中配置的 key 不正确, 3-自动加载libtencentloc.so失败， 4-未设置或未同意用户隐私

    - #### startIndoorLocation

          @Deprecated
          public boolean startIndoorLocation()

      已过时。
      废弃该接口，请在TencentLocationRequest中启动室内定位 立即启动高精度室内定位. 启动后，当所在的楼宇支持腾讯的高精度室内定位时，会默认切换到室内定位，离开时自动切换回原定位方式

    - #### stopIndoorLocation

          @Deprecated
          public boolean stopIndoorLocation()

      已过时。
      废弃该接口，默认远离商场后自动停止 立即中断室内定位组件运行，相当于interrupt the indoor thread。 中断后，室内定位组件停止运行，但不影响正常定位逻辑。

    - #### getLastKnownLocation

          public TencentLocation getLastKnownLocation()

      返回最近一次的位置, 可能为 null.

      如未设置用或未同意隐私政策，直接返回null.

    - #### removeUpdates

          public void removeUpdates​(TencentLocationListener listener)

      移除位置监听器并停止定位.

      定位完成后应尽快通过本方法移除 listener 否则可能消耗较多电量.

      如未设置用或未同意隐私政策，直接返回null.

      参数:
        `listener` - 位置监听器。注意：传入null时，会强制停止定位引擎并移除所有监听。

    - #### addLocationListener

          public void addLocationListener​(TencentLocationListener listener)

      添加定位监听

      添加定位监听前请先请求连续定位，request与Looper配置与连续定位一致

      参数:
        `listener` - 位置监听器
      另请参阅:
        `requestLocationUpdates(TencentLocationRequest, TencentLocationListener, Looper)`

    - #### removeLocationListener

          public void removeLocationListener​(TencentLocationListener listener)

      移除定位监听

      移除通过addLocationListener增加的监听器 requestLocationUpdates的监听请使用removeUpdates移除

      参数:
        `listener` - 位置监听器

    - #### getBuild

          public java.lang.String getBuild()

    - #### getVersion

          public java.lang.String getVersion()

    - #### getOaid

          public java.lang.String getOaid()

      获取设备oaid
      返回:
        设备oaid

    - #### triggerCodeGuarder

          public void triggerCodeGuarder​(boolean trigger)

    - #### setDeviceID

          public void setDeviceID​(android.content.Context context,
                                  java.lang.String deviceID)

      Android Q开始，无法正常读取设备唯一标识，此接口用于配置设备唯一标识 deviceID长度限制为1～63，超过63将选择前63位

      如未设置用或未同意隐私政策，该方法不生效.

      参数:
        `context` -
        `deviceID` - 设备ID

    - #### setMockEnable

          public void setMockEnable​(boolean switcher)

      是否允许mockGps数据 设置为true后将不对mockGps进行过滤

      如未设置用或未同意隐私政策，该方法不生效.

      参数:
        `switcher` -

    - #### setSystemCacheEnable

          public void setSystemCacheEnable​(boolean switcher)

      是否允许在定位失败情况下返回系统缓存位置

      如未设置用或未同意隐私政策，该方法不生效.

      参数:
        `switcher` -

    - #### getDrPosition

          public TencentLocation getDrPosition()

      传出计算出的实时位置，调用`startDrEngine(int)`成功后才可能有值

      如未设置用或未同意隐私政策，直接返回null.

      返回:
        DR融合后的定位结果

    - #### startDrEngine

          public int startDrEngine​(int type)

      启动DR引擎。引擎会自动获取传感器和GPS数据，并进行位置计算。 启动后DR引擎会向TencentLocationManager注册监听。 如需停止定位引擎，请确保DR引擎先停止，或调用`removeUpdates(TencentLocationListener)`时传入null} 注意：请确保调用之前已获取位置权限 `Manifest.permission.ACCESS_COARSE_LOCATION` `Manifest.permission.ACCESS_FINE_LOCATION`
      参数:
        `type` - 运动类型 目前支持`DR_TYPE_BIKE`和`DR_TYPE_WALK`
      返回:
        返回码 RT_CODE_NOT_SUPPORT = -1; 传感器有缺失或没有GPS芯片 RT_CODE_HAS_STARTED = -2; 已经启动 RT_CODE_SENSOR_FAILED = -3; 传感器启动失败 RT_CODE_GPS_FAILED = -4; GPS启动失败 RT_CODE_PERMISSION_FAILED = -5; 没有位置权限 RT_CODE_PRIVACY_FAILED = -6; 未设置用或未同意隐私 RT_CODE_LOAD_LIBRARY_FAILED = -7; lib加载失败 RT_CODE_SUCCESS = 0; 成功

    - #### terminateDrEngine

          public void terminateDrEngine()

      停止DR引擎。内部有极短时间延迟，若在此期间调用`startDrEngine(int)`可能导致启动不成功。

      如未设置用或未同意隐私政策，该方法不生效.

    - #### isDrSupport

          public boolean isDrSupport()

      是否支持DR引擎
      返回: