创建位置监听器

TencentLocationListener 接口代表位置监听器,您的APP 通过位置监听器接收定位SDK的位置变化通知。创建位置监听器非常简单,通常您只需实现 TencentLocationListener 接口。如下所示:

位置监听器的回调方法分为两类:一类是位置更新时的回调,一类是GPS和Wi-Fi的状态变化回调。

位置回调接口如下:

参数 含义
location 新的位置
error 错误码
reason 错误描述

状态回调接口如下:

参数 含义
name GPS,Wi-Fi等
status 新的状态, 启用或禁用
desc 状态描述

在Android 6.0 及以上的系统版本中,当位置开关关闭时,onStatusUpdate接口会返回name=wifi,status=5,该状态码说明位置开关关闭,此时无法进行Wi-Fi扫描。收到该状态码后,请及时提醒用户打开位置开关。

Name status
状态 状态码 说明
cell STATUS_DISABLED 0 模块关闭
STATUS_EABLED 1 模块开启
STATUS_DENIED 2 定位权限被禁止,位置权限被拒绝通常发生在禁用当前应用的 ACCESS_COARSE_LOCATION 等定位权限
wifi STATUS_DISABLED 0 Wi-Fi开关关闭
STATUS_EABLED 1 Wi-Fi开关打开
STATUS_DENIED 2 权限被禁止,禁用当前应用的 ACCESS_COARSE_LOCATION 等定位权限
STATUS_LOCATION_SWITCH_OFF 5 位置信息开关关闭,在android M系统中,此时禁止进行Wi-Fi扫描
GPS STATUS_DISABLED 0 GPS开关关闭
STATUS_EABLED 1 GPS开关打开
STATUS_GPS_AVAILABEL 3 GPS可用,代表GPS开关打开,且搜星定位成功
STATUS_GPS_UNAVAILABLE 4 GPS不可用,不可用有多种可能,比如:
GPS开关被关闭,GPS开关开着但是没办法搜星或者在室内等定位不成功的情况

创建定位请求

TencentLocationRequest 类代表定位请求, 您的APP通过向定位SDK发送定位请求来启动定位。通常您只需获取 TencentLocationRequest 实例即可,如下所示:

以上得到的是一个缺省的定位请求,缺省的定位请求各参数如下:

  • 定位周期(位置监听器回调周期): 10秒
  • Request Level: REQUEST_LEVEL_NAME
  • 缓存: 允许使用缓存
  • QQ: 空字符串

可调用如下方法来对定位请求进行自定义配置:

方法名 功能
setInterval 设置定位周期(位置监听器回调周期), 单位为 ms (毫秒)
setRequestLevel 设置定位的 request level
setAllowCache 设置是否允许使用缓存, 连续多次定位时建议允许缓存
setQQ 设置 QQ 号

Request level 决定定位结果中包含哪些信息,分为以下几类:

Request Level 含义
REQ_LEVEL_GEO 0 包含经纬度
REQ_LEVEL_NAME 1 包含经纬度, 位置名称, 位置地址
REQ_LEVEL_ADMIN_AREA 3 包含经纬度,位置所处的中国大陆行政区划
REQ_LEVEL_POI 4 包含经纬度,位置所处的中国大陆行政区划及周边POI列表

注册位置监听器

TencentLocationManager 类代表腾讯定位服务。注册位置监听器前需要获取 TencentLocationManager 实例,示例如下:

返回值为0时表示位置监听器注册成功。注册成功之后,在位置发生变化时,位置监听器的位置回调接口或状态回调接口将会被调用,用以接收最新的位置或状态。

返回值非0时表示位置监听器注册失败。注册监听器失败时,将无法接收到位置更新,继续使用腾讯地图定位SDK前您应先排查注册失败的问题。常见的返回值如下:

返回值 含义
0 注册位置监听器成功
1 设备缺少使用腾讯定位SDK需要的基本条件
2 配置的 Key 不正确
3 自动加载libtencentloc.so失败,可能由以下原因造成:
1、这往往是由工程中的so与设备不兼容造成的,应该添加相应版本so文件;
2、如果您使用AndroidStudio,可能是gradle没有正确指向so文件加载位置,可以按照这里配置您的gradle;

获取定位结果

通过位置监听器的位置回调接口获取定位结果。使用定位结果前应当先检查错误码:

错误码说明

错误码来自 TencentLocation 的 ERROR_XXX 常量,分如下几种情形:

错误码 含义
ERROR_OK 0 定位成功
ERROR_NETWORK 1 网络问题引起的定位失败
ERROR_BAD_JSON 2 GPS, Wi-Fi 或基站错误引起的定位失败:
1、用户的手机确实采集不到定位凭据,比如偏远地区比如地下车库电梯内等;
2、开关跟权限问题,比如用户关闭了位置信息,关闭了Wi-Fi,未授予app定位权限等。
ERROR_WGS84 4 无法将WGS84坐标转换成GCJ-02坐标时的定位失败
ERROR_UNKNOWN 404 未知原因引起的定位失败

request level 说明

request level 来自 TencentLocationRequestREQUEST_LEVEL_XXX 常量,分如下几种情形:

Request Level 含义
REQ_LEVEL_GEO 0 包含经纬度
REQ_LEVEL_NAME 1 包含经纬度, 位置名称, 位置地址
REQ_LEVEL_ADMIN_AREA 3 包含经纬度,位置所处的中国大陆行政区划
REQ_LEVEL_POI 4 包含经纬度,位置所处的中国大陆行政区划及周边POI列表
  • 当定位请求的 request level 为 REQ_LEVEL_GEO 时,以下字段有效:
字段 含义
latitude 纬度
longitude 经度
altitude 海拔
accuracy 精度
  • 当定位请求的 request level 为 REQ_LEVEL_NAME 时,以下字段有效:
字段 含义
latitude 纬度
longitude 经度
altitude 海拔
accuracy 精度
name 名称
address 地址
  • 当定位请求的 request level 为 REQ_LEVEL_ADMIN_AREA 时,以下字段有效:
字段 含义
latitude 纬度
longitude 经度
altitude 海拔
accuracy 精度
nation 国家
province
city
district
town
village
street 街道
streetNo 门号
  • 当定位请求的 request level 为 REQ_LEVEL_POI 时,以下字段有效:
字段 含义
latitude 纬度
longitude 经度
altitude 海拔
accuracy 精度
nation 国家
province
city
district
town
village
street 街道
streetNo 门号
poiList POI 列表

删除位置监听器

定位完成后,无论成功或失败,都应当尽快删除之前注册的位置监听器。代码如下:

Android 6.0说明

Android 6.0系统在原有的AndroidManifest.xml声明权限的基础上新增了运行时权限动态检测,定位等权限也包含在其中。如果您的应用程序设置了 targetSdkVersion ≥ 23,则需要在调用定位功能前进行权限检查,权限检查的示例代码如下:

用户选择允许或拒绝后,会回调onRequestPermissionsResult方法: