文档中心

interface info

public interface CaptureClient

情景感知快照API的主要入口，能够通过该接口获取耳机状态、活动状态、时间状态、地理位置、信标状态、光照度、天气状态、车载蓝牙状态和各能力支持状态的响应。

Public Method Summary

Return type	Method name
Task<BeaconStatusResponse>	getBeaconStatus(BeaconStatus.Filter… filters)
Task<BeaconStatusResponse>	getBeaconStatus(Collection<BeaconStatus.Filter> filters)
Task<BehaviorResponse>	getBehavior()
Task<HeadsetStatusResponse>	getHeadsetStatus()
Task<LocationResponse>	getLocation()
Task<LocationResponse>	getCurrentLocation()
Task<TimeCategoriesResponse>	getTimeCategories()
Task<TimeCategoriesResponse>	getTimeCategoriesByUser(double latitude, double longitude)
Task<TimeCategoriesResponse>	getTimeCategoriesByCountryCode(String countryCode)
Task<TimeCategoriesResponse>	getTimeCategoriesByIP()
Task<TimeCategoriesResponse>	getTimeCategoriesForFuture(long futureTimestamp)
Task<AmbientLightResponse>	getLightIntensity()
Task<WeatherStatusResponse>	getWeatherByDevice()
Task<WeatherStatusResponse>	getWeatherByIP()
Task<WeatherStatusResponse>	getWeatherByPosition(WeatherPosition position)
Task<BluetoothStatusResponse>	getBluetoothStatus(int deviceType)
Task<CapabilityResponse>	querySupportingCapabilities()
void	enableUpdateWindow(boolean isEnable)

Public Methods

Method

public abstract Task<BeaconStatusResponse> getBeaconStatus(BeaconStatus.Filter… filters)

使用可变数量的filters参数，获取相关信标的信息。

请注意，信标快照仅在API级别24或更高版本上可用。要使用此方法，您的应用必须在AndroidManifest.xml中声明android.permission.BLUETOOTH 和android.permission.ACCESS_FINE_LOCATION权限，并且用户必须在运行时选择同意。

Parameters

Parameter name	Parameter desc
filters	信标过滤器，可以通过以下任一方式构造过滤器：1．按照在信标下注册的附件信息的命名空间和类型进行过滤。2．按照在信标下注册的附件信息的命名空间、类型和内容进行过滤。

Return

Type	desc
Task<BeaconStatusResponse>	返回BeaconStatusResponse的Task泛型。可以使用Task中的isSuccessful()判断是否成功。如果成功，可继续通过BeaconStatusResponse获取信标数据；否则表示获取信标信息失败。

Method

public abstract Task<BeaconStatusResponse> getBeaconStatus(Collection<beaconstatus.filter> filters)

传入一组filters的集合作为参数，获取相关信标的信息。

请注意，信标快照仅在运行API级别24或更高版本的设备上可用。要使用此方法，您的应用必须在AndroidManifest.xml中声明android.permission.BLUETOOTH 和android.permission.ACCESS_FINE_LOCATION权限，并且用户必须在运行时提供同意。

Parameters

Parameter name	Parameter desc
filters	信标过滤器，可以通过以下任一方式构造过滤器：1．按照在信标下注册的附件信息的命名空间和类型进行过滤。2．按照在信标下注册的附件信息的命名空间、类型和内容进行过滤。

Return

Type	desc
Task<BeaconStatusResponse>	返回BeaconStatusResponse的Task泛型。可以使用Task中的isSuccessful()判断是否成功。如果成功，可继续通过BeaconStatusResponse获取信标数据；否则表示获取信标信息失败。

Method

public abstract Task<BehaviorResponse> getBehavior()

获取用户的当前活动状态，例如跑步、步行、骑自行车、开车等。

要调用此函数，需要不同的权限，具体取决于您的Android API级别，对于Android 10（API级别29）及更高版本：android.permission.ACTIVITY_RECOGNITION权限。

对于Android 9（API级别28）：com.huawei.hms.permission.ACTIVITY_RECOGNITION权限。

Return

Type	desc
Task<BehaviorResponse>	返回BehaviorResponse的Task泛型。可以使用Task中的isSuccessful()判断是否成功。如果成功，可继续通过BehaviorResponse获取当前用户活动信息；否则表示获取活动信息失败。

Method

public abstract Task<HeadsetStatusResponse> getHeadsetStatus()

获取耳机连接状态。

请注意，耳机快照仅在运行API级别24或更高版本的设备上可用。

Return

Type	desc
Task<HeadsetStatusResponse>	返回 HeadsetStatusResponse的Task泛型。可以使用Task中的isSuccessful()判断是否成功。如果成功，可继续通过 HeadsetStatusResponse获取当前的耳机连接状态；否则表示获取耳机连接状态失败。

Method

public abstract Task<LocationResponse> getLocation()

获取设备的位置信息（纬度/经度）。使用该方法获取的位置信息，是设备中缓存的值，该值是设备最后一次查询到的位置信息。

请注意，地理位置快照仅在运行API级别24或更高版本的设备上可用。要使用此方法，您的应用必须在AndroidManifest.xml中声明android.permission.ACCESS_FINE_LOCATION权限，并且用户必须在运行时提供同意。

Return

Type	desc
Task<LocationResponse>	返回LocationResponse的Task泛型。可以使用Task中的isSuccessful()判断是否成功。如果成功，可继续通过LocationResponse获取设备当前位置；否则表示获取位置信息失败。

public abstract Task<LocationResponse> getLocation()Method

public abstract Task<LocationResponse> getCurrentLocation()

重新获取设备最新的位置信息（纬度/经度）。使用该方法获取位置信息时，系统会基于设备当前位置，重新获取位置信息返回，并刷新设备中缓存的位置信息。

请注意，地理位置快照仅在运行API级别24或更高版本的设备上可用。要使用此方法，您的应用必须在AndroidManifest.xml中声明android.permission.ACCESS_FINE_LOCATION权限，并且用户必须在运行时同意。

Return

Type	desc
Task<LocationResponse>	返回LocationResponse的Task泛型。可以使用Task中的isSuccessful()判断是否成功。如果成功，可继续通过LocationResponse获取设备当前位置；否则表示获取位置信息失败。

Method

public abstract Task<TimeCategoriesResponse> getTimeCategories()

获取当前时间状态。时间状态是TimeBarrier类中定义的上午TIME_CATEGORY_MORNING，下午TIME_CATEGORY_AFTERNOON，晚上TIME_CATEGORY_EVENING，夜间TIME_CATEGORY_NIGHT，工作日TIME_CATEGORY_WEEKDAY，休息日TIME_CATEGORY_WEEKEND，节假日TIME_CATEGORY_HOLIDAY，非节假日TIME_CATEGORY_NOT_HOLIDAY。

请注意，时间快照仅在运行API级别24或更高版本的设备上可用。要使用此方法，您的应用必须在AndroidManifest.xml中声明android.permission.ACCESS_FINE_LOCATION权限，并且用户必须在运行时同意。

Return

Type	desc
Task<TimeCategoriesResponse>	返回TimeCategoriesResponse的Task泛型。可以使用Task中的isSuccessful()判断是否成功。如果成功，可继续通过TimeCategoriesResponse获取当前时间状态；否则表示获取时间状态失败。

Method

public abstract Task<TimeCategoriesResponse> getTimeCategoriesByUser(double latitude, double longitude)

获取指定位置的当前时间状态。时间状态是TimeBarrier类中定义的上午TIME_CATEGORY_MORNING，下午TIME_CATEGORY_AFTERNOON，晚上TIME_CATEGORY_EVENING，夜间TIME_CATEGORY_NIGHT，工作日TIME_CATEGORY_WEEKDAY，休息日TIME_CATEGORY_WEEKEND，节假日TIME_CATEGORY_HOLIDAY，非节假日TIME_CATEGORY_NOT_HOLIDAY。

请注意，时间快照仅在运行API级别24或更高版本的设备上可用。

Parameters

Parameter name	Parameter desc
latitude	纬度。
longitude	经度。

Return

Type	desc
Task<TimeCategoriesResponse>	返回TimeCategoriesResponse的Task泛型。可以使用Task中的isSuccessful()判断是否成功。如果成功，可继续通过TimeCategoriesResponse获取当前时间状态；否则表示获取时间状态失败。

Method

public abstract Task<TimeCategoriesResponse> getTimeCategoriesByCountryCode(String countryCode)

根据国家地区代码来获取当前时间状态。国家地区代码是根据ISO 3166-1标准的两位代码来的。使用国家码来获取时间状态时，会按照该国家首都的位置来返回时间状态和时区信息，即使该国家涉及多个时区。

时间状态是TimeBarrier类中定义的上午TIME_CATEGORY_MORNING，下午TIME_CATEGORY_AFTERNOON，晚上TIME_CATEGORY_EVENING，夜间TIME_CATEGORY_NIGHT，工作日TIME_CATEGORY_WEEKDAY，休息日TIME_CATEGORY_WEEKEND，节假日TIME_CATEGORY_HOLIDAY，非节假日TIME_CATEGORY_NOT_HOLIDAY。

请注意，时间快照仅在运行API级别24或更高版本的设备上可用。

Parameters

Parameter name	Parameter desc
countryCode	国家地区代码，遵循ISO 3166-1标准的两位代码。

Return

Type	desc
Task<TimeCategoriesResponse>	返回TimeCategoriesResponse的Task泛型。可以使用Task中的isSuccessful()判断是否成功。如果成功，可继续通过TimeCategoriesResponse获取当前时间状态；否则表示获取时间状态失败。

Method

public abstract Task<TimeCategoriesResponse> getTimeCategoriesByIP()

根据网络IP位置来获取当前时间状态。使用IP查询时间，会根据IP所在的位置，返回该位置的时间信息。需要注意，该接口相较于getTimeCategories精确度较差，但优势是不需要精确位置权限。开发者在使用时，可以进行权衡后考虑。

请注意，时间快照仅在运行API级别24或更高版本的设备上可用。要使用此方法，您的应用必须在AndroidManifest.xml中声明android.permission.ACCESS_COARSE_LOCATION权限。

Return

Type	desc
Task<TimeCategoriesResponse>	返回TimeCategoriesResponse的Task泛型。可以使用Task中的isSuccessful()判断是否成功。如果成功，可继续通过TimeCategoriesResponse获取当前时间状态；否则表示获取时间状态失败。

Method

public abstract Task<TimeCategoriesResponse> getTimeCategoriesForFuture(long futureTimestamp)

根据网络IP位置来获取指定日期时间的时间状态。该接口可以用来查询未来某天的时间状态，输入想要查询日期的时间戳，即可查询该日期的时间状态。需要注意，该接口只支持查询当年度内的时间戳，不支持跨年查询。

Parameters

Parameter name	Parameter desc
futureTimestamp	指定日期的时间戳。该参数只支持传入当年度内任意时刻的时间戳，不支持跨年查询。（时间戳是指格林威治时间1970年01月01日00时00分00秒起至现在的总毫秒数。）

Return

Type	desc
Task<TimeCategoriesResponse>	返回TimeCategoriesResponse的Task泛型。可以使用Task中的isSuccessful()判断是否成功。如果成功，可继续通过TimeCategoriesResponse获取当前时间状态；否则表示获取时间状态失败。

Method

public abstract Task<AmbientLightResponse> getLightIntensity()

获取光照度响应。

请注意，环境光快照仅在运行API级别24或更高版本的设备上可用。

Return

Type	desc
Task<AmbientLightResponse>	返回AmbientLightResponse的Task泛型。可继续通过AmbientLightResponse获取光照度状态AmbientLightStatus。

Method

public abstract Task<WeatherStatusResponse> getWeatherByDevice()

获取设备当前位置的天气状态响应。

由于系统的限制，5秒内调用快照接口不得超过20次；一个小时内，调用快照接口不得超过1000次。该接口为快照接口，遵循该条件限制，调用频率超过时，调用该天气接口将返回失败。

请注意，天气快照仅在运行API级别24或更高版本的设备上可用。要使用此方法，您的应用必须在AndroidManifest.xml中声明android.permission.ACCESS_FINE_LOCATION权限，并且用户必须在运行时提供同意。

Return

Type	desc
Task<WeatherStatusResponse>	返回WeatherStatusResponse的Task泛型。可以调用WeatherStatusResponse中的getWeatherStatus可以获取到天气状态（WeatherStatus），天气状态中携带了设备当前位置的具体天气信息。

Method

public abstract Task<WeatherStatusResponse> getWeatherByIP()

获取设备网络IP地址的天气状态响应。

请注意，天气快照仅在运行API级别24或更高版本的设备上可用。要使用此方法，您的应用必须在AndroidManifest.xml中声明android.permission.ACCESS_COARSE_LOCATION权限。

Return

Type	desc
Task<WeatherStatusResponse>	返回WeatherStatusResponse的Task泛型。可以调用WeatherStatusResponse中的getWeatherStatus可以获取到天气状态（WeatherStatus），天气状态中携带了设备当前位置的具体天气信息。

Method

public abstract Task<WeatherStatusResponse> getWeatherByPosition(WeatherPosition position)

获取指定地名的天气信息。

根据指定的地址来获取天气，地址由国家、省份、城市、地区、县5个层级组成，其中城市名必须传入，其他4个属性非必需。建议将每个层级的地址写全，组成更精确的地址信息，以便获取更精确的天气信息。在输入地址时，需要指明输入地址使用的语言类型，系统将根据地址名的语言类型，返回对应语言的天气信息。

例如可以传入“London”或者“England，London”，然后locale指定为”en_GB”来获取伦敦的天气；传入“中国，南京市”、“中国，江苏省，南京”、“江苏，南京”，然后locale指定为”zh_CN”来获取中国江苏省南京市的天气。

请注意，天气快照仅在运行API级别24或更高版本的设备上可用。

Parameters

Parameter name

Parameter desc

position

需要查询的地点信息，包括地址信息和语言环境。地址由国家、省份、城市、地区、县等组成地点名，其中城市名必须传入，其他4个属性非必需。例如想查看英国伦敦的天气时，可以只传入城市名“伦敦”，或者也可以传入国家名“英国”和城市名“伦敦”。语言环境表示传入地址的语言类型，格式是locale格式，比如en_GB表示英国英语。需要注意的是，必须传入语言类型，且语言类型应当是“语言码_国家码”的格式。

Return

Type	desc
Task<WeatherStatusResponse>	返回WeatherStatusResponse的Task泛型。可以调用WeatherStatusResponse中的getWeatherStatus可以获取到天气状态（WeatherStatus），天气状态中携带了指定位置的具体天气信息。

Method

public abstract Task<BluetoothStatusResponse> getBluetoothStatus(int deviceType)

获取车载蓝牙连接状态。

请注意，车载蓝牙快照仅在运行API级别24或更高版本的设备上可用。

要使用此方法，您的应用必须在AndroidManifest.xml中声明android.permission.BLUETOOTH 权限。

Parameters

Parameter name	Parameter desc
deviceType	车载蓝牙设备类型0：标识车载蓝牙设备

Return

Type	desc
Task<BluetoothStatusResponse>	返回BluetoothStatusResponse的Task泛型。可以使用Task中的isSuccessful()判断是否成功。如果成功，可继续通过BluetoothStatusResponse获取当前车载蓝牙连接状态；否则表示获取车载蓝牙连接状态失败。

Method

public abstract Task<CapabilityResponse> querySupportingCapabilities()

获取Awareness在当前设备所支持的能力。

Return

Type	desc
Task<CapabilityResponse>	返回CapabilityResponse的Task泛型。可以使用Task中的isSuccessful()判断是否成功。如果成功，可继续通过CapabilityResponse获取设备当前各细分能力支持状态；否则表示获取状态失败。

Method

public void enableUpdateWindow(boolean isEnable)

当Awareness Kit和HMS Core升级时，是否出现弹窗。

注意：慎用该功能。如果设置成false将无法触发升级，没有升级弹窗提示，相当于在升级弹窗点击了取消升级。在没有完成升级前，Awareness Kit所有功能将不可用。只能等待完成静默升级后，功能恢复。静默升级触发时间一般为7-14天。