HealthService

Get access to health information like step count, sleep totals, etc. More...

Collaboration diagram for HealthService:

Classes
struct	HealthMinuteData

Macros
#define	HealthActivityMaskAll   ((HealthActivityOpenWorkout << 1) - 1)
	A mask value representing all available activities.
#define	PBL_IF_HEALTH_ELSE(if_true, if_false)   (if_true)
#define	HealthActivityMaskAll   ((HealthActivityOpenWorkout << 1) - 1)
	A mask value representing all available activities.
#define	PBL_IF_HEALTH_ELSE(if_true, if_false)   (if_true)

Typedefs
typedef int32_t	HealthValue
	Type used to represent HealthMetric values.
typedef struct HealthMetricAlert	HealthMetricAlert
typedef uint32_t	HealthActivityMask
	Expresses a set of HealthActivity values as a bitmask.
typedef bool(*	HealthActivityIteratorCB) (HealthActivity activity, time_t time_start, time_t time_end, void *context)
typedef void(*	HealthEventHandler) (HealthEventType event, void *context)
typedef enum AmbientLightLevel	AmbientLightLevel
	Light level enum.
typedef int32_t	HealthValue
	Type used to represent HealthMetric values.
typedef struct HealthMetricAlert	HealthMetricAlert
typedef uint32_t	HealthActivityMask
	Expresses a set of HealthActivity values as a bitmask.
typedef bool(*	HealthActivityIteratorCB) (HealthActivity activity, time_t time_start, time_t time_end, void *context)
typedef void(*	HealthEventHandler) (HealthEventType event, void *context)
typedef enum AmbientLightLevel	AmbientLightLevel
	Light level enum.

Enumerations
enum	HealthMetric {   HealthMetricStepCount, HealthMetricActiveSeconds, HealthMetricWalkedDistanceMeters, HealthMetricSleepSeconds,   HealthMetricSleepRestfulSeconds, HealthMetricRestingKCalories, HealthMetricActiveKCalories, HealthMetricHeartRateBPM,   HealthMetricHeartRateRawBPM, HealthMetricStepCount, HealthMetricActiveSeconds, HealthMetricWalkedDistanceMeters,   HealthMetricSleepSeconds, HealthMetricSleepRestfulSeconds, HealthMetricRestingKCalories, HealthMetricActiveKCalories,   HealthMetricHeartRateBPM, HealthMetricHeartRateRawBPM }
enum	HealthServiceTimeScope {   HealthServiceTimeScopeOnce, HealthServiceTimeScopeWeekly, HealthServiceTimeScopeDailyWeekdayOrWeekend, HealthServiceTimeScopeDaily,   HealthServiceTimeScopeOnce, HealthServiceTimeScopeWeekly, HealthServiceTimeScopeDailyWeekdayOrWeekend, HealthServiceTimeScopeDaily }
	Used by health_service_sum_averaged() to specify how the average is computed. More...
enum	HealthAggregation {   HealthAggregationSum, HealthAggregationAvg, HealthAggregationMin, HealthAggregationMax,   HealthAggregationSum, HealthAggregationAvg, HealthAggregationMin, HealthAggregationMax }
enum	HealthActivity {   HealthActivityNone = 0, HealthActivitySleep = 1 << 0, HealthActivityRestfulSleep = 1 << 1, HealthActivityWalk = 1 << 2,   HealthActivityRun = 1 << 3, HealthActivityOpenWorkout = 1 << 4, HealthActivityNone = 0, HealthActivitySleep = 1 << 0,   HealthActivityRestfulSleep = 1 << 1, HealthActivityWalk = 1 << 2, HealthActivityRun = 1 << 3, HealthActivityOpenWorkout = 1 << 4 }
	Health-related activities that can be accessed using. More...
enum	HealthIterationDirection { HealthIterationDirectionPast, HealthIterationDirectionFuture, HealthIterationDirectionPast, HealthIterationDirectionFuture }
enum	HealthServiceAccessibilityMask {   HealthServiceAccessibilityMaskAvailable = 1 << 0, HealthServiceAccessibilityMaskNoPermission = 1 << 1, HealthServiceAccessibilityMaskNotSupported = 1 << 2, HealthServiceAccessibilityMaskNotAvailable = 1 << 3,   HealthServiceAccessibilityMaskAvailable = 1 << 0, HealthServiceAccessibilityMaskNoPermission = 1 << 1, HealthServiceAccessibilityMaskNotSupported = 1 << 2, HealthServiceAccessibilityMaskNotAvailable = 1 << 3 }
enum	HealthEventType {   HealthEventSignificantUpdate = 0, HealthEventMovementUpdate = 1, HealthEventSleepUpdate = 2, HealthEventMetricAlert = 3,   HealthEventHeartRateUpdate = 4, HealthEventSignificantUpdate = 0, HealthEventMovementUpdate = 1, HealthEventSleepUpdate = 2,   HealthEventMetricAlert = 3, HealthEventHeartRateUpdate = 4 }
	Health event enum. Passed into the HealthEventHandler. More...
enum	AmbientLightLevel {   AmbientLightLevelUnknown = 0, AmbientLightLevelVeryDark, AmbientLightLevelDark, AmbientLightLevelLight,   AmbientLightLevelVeryLight, AmbientLightLevelUnknown = 0, AmbientLightLevelVeryDark, AmbientLightLevelDark,   AmbientLightLevelLight, AmbientLightLevelVeryLight }
	Light level enum.
enum	MeasurementSystem {   MeasurementSystemUnknown, MeasurementSystemMetric, MeasurementSystemImperial, MeasurementSystemUnknown,   MeasurementSystemMetric, MeasurementSystemImperial }
	Types of measurement system a HealthMetric may be measured in. More...
enum	HealthMetric {   HealthMetricStepCount, HealthMetricActiveSeconds, HealthMetricWalkedDistanceMeters, HealthMetricSleepSeconds,   HealthMetricSleepRestfulSeconds, HealthMetricRestingKCalories, HealthMetricActiveKCalories, HealthMetricHeartRateBPM,   HealthMetricHeartRateRawBPM, HealthMetricStepCount, HealthMetricActiveSeconds, HealthMetricWalkedDistanceMeters,   HealthMetricSleepSeconds, HealthMetricSleepRestfulSeconds, HealthMetricRestingKCalories, HealthMetricActiveKCalories,   HealthMetricHeartRateBPM, HealthMetricHeartRateRawBPM }
enum	HealthServiceTimeScope {   HealthServiceTimeScopeOnce, HealthServiceTimeScopeWeekly, HealthServiceTimeScopeDailyWeekdayOrWeekend, HealthServiceTimeScopeDaily,   HealthServiceTimeScopeOnce, HealthServiceTimeScopeWeekly, HealthServiceTimeScopeDailyWeekdayOrWeekend, HealthServiceTimeScopeDaily }
	Used by health_service_sum_averaged() to specify how the average is computed. More...
enum	HealthAggregation {   HealthAggregationSum, HealthAggregationAvg, HealthAggregationMin, HealthAggregationMax,   HealthAggregationSum, HealthAggregationAvg, HealthAggregationMin, HealthAggregationMax }
enum	HealthActivity {   HealthActivityNone = 0, HealthActivitySleep = 1 << 0, HealthActivityRestfulSleep = 1 << 1, HealthActivityWalk = 1 << 2,   HealthActivityRun = 1 << 3, HealthActivityOpenWorkout = 1 << 4, HealthActivityNone = 0, HealthActivitySleep = 1 << 0,   HealthActivityRestfulSleep = 1 << 1, HealthActivityWalk = 1 << 2, HealthActivityRun = 1 << 3, HealthActivityOpenWorkout = 1 << 4 }
	Health-related activities that can be accessed using. More...
enum	HealthIterationDirection { HealthIterationDirectionPast, HealthIterationDirectionFuture, HealthIterationDirectionPast, HealthIterationDirectionFuture }
enum	HealthServiceAccessibilityMask {   HealthServiceAccessibilityMaskAvailable = 1 << 0, HealthServiceAccessibilityMaskNoPermission = 1 << 1, HealthServiceAccessibilityMaskNotSupported = 1 << 2, HealthServiceAccessibilityMaskNotAvailable = 1 << 3,   HealthServiceAccessibilityMaskAvailable = 1 << 0, HealthServiceAccessibilityMaskNoPermission = 1 << 1, HealthServiceAccessibilityMaskNotSupported = 1 << 2, HealthServiceAccessibilityMaskNotAvailable = 1 << 3 }
enum	HealthEventType {   HealthEventSignificantUpdate = 0, HealthEventMovementUpdate = 1, HealthEventSleepUpdate = 2, HealthEventMetricAlert = 3,   HealthEventHeartRateUpdate = 4, HealthEventSignificantUpdate = 0, HealthEventMovementUpdate = 1, HealthEventSleepUpdate = 2,   HealthEventMetricAlert = 3, HealthEventHeartRateUpdate = 4 }
	Health event enum. Passed into the HealthEventHandler. More...
enum	AmbientLightLevel {   AmbientLightLevelUnknown = 0, AmbientLightLevelVeryDark, AmbientLightLevelDark, AmbientLightLevelLight,   AmbientLightLevelVeryLight, AmbientLightLevelUnknown = 0, AmbientLightLevelVeryDark, AmbientLightLevelDark,   AmbientLightLevelLight, AmbientLightLevelVeryLight }
	Light level enum.
enum	MeasurementSystem {   MeasurementSystemUnknown, MeasurementSystemMetric, MeasurementSystemImperial, MeasurementSystemUnknown,   MeasurementSystemMetric, MeasurementSystemImperial }
	Types of measurement system a HealthMetric may be measured in. More...

Functions
HealthValue	health_service_sum (HealthMetric metric, time_t time_start, time_t time_end)
HealthValue	health_service_sum_today (HealthMetric metric)
HealthValue	health_service_peek_current_value (HealthMetric metric)
HealthValue	health_service_sum_averaged (HealthMetric metric, time_t time_start, time_t time_end, HealthServiceTimeScope scope)
HealthValue	health_service_aggregate_averaged (HealthMetric metric, time_t time_start, time_t time_end, HealthAggregation aggregation, HealthServiceTimeScope scope)
HealthActivityMask	health_service_peek_current_activities (void)
void	health_service_activities_iterate (HealthActivityMask activity_mask, time_t time_start, time_t time_end, HealthIterationDirection direction, HealthActivityIteratorCB callback, void *context)
HealthServiceAccessibilityMask	health_service_metric_accessible (HealthMetric metric, time_t time_start, time_t time_end)
HealthServiceAccessibilityMask	health_service_metric_averaged_accessible (HealthMetric metric, time_t time_start, time_t time_end, HealthServiceTimeScope scope)
HealthServiceAccessibilityMask	health_service_metric_aggregate_averaged_accessible (HealthMetric metric, time_t time_start, time_t time_end, HealthAggregation aggregation, HealthServiceTimeScope scope)
HealthServiceAccessibilityMask	health_service_any_activity_accessible (HealthActivityMask activity_mask, time_t time_start, time_t time_end)
bool	health_service_events_subscribe (HealthEventHandler handler, void *context)
bool	health_service_events_unsubscribe (void)
bool	health_service_set_heart_rate_sample_period (uint16_t interval_sec)
uint16_t	health_service_get_heart_rate_sample_period_expiration_sec (void)
HealthMetricAlert *	health_service_register_metric_alert (HealthMetric metric, HealthValue threshold)
bool	health_service_cancel_metric_alert (HealthMetricAlert *alert)
uint32_t	health_service_get_minute_history (HealthMinuteData *minute_data, uint32_t max_records, time_t *time_start, time_t *time_end)
MeasurementSystem	health_service_get_measurement_system_for_display (HealthMetric metric)

Detailed Description

Get access to health information like step count, sleep totals, etc.

The HealthService provides your app access to the step count and sleep activity of the user.

Macro Definition Documentation

PBL_IF_HEALTH_ELSE [1/2]

#define PBL_IF_HEALTH_ELSE	(		if_true,
			if_false
	)		(if_true)

Convenience macro to switch between two expressions depending on health support. On platforms with health support the first expression will be chosen, the second otherwise.

PBL_IF_HEALTH_ELSE [2/2]

#define PBL_IF_HEALTH_ELSE	(		if_true,
			if_false
	)		(if_true)

Convenience macro to switch between two expressions depending on health support. On platforms with health support the first expression will be chosen, the second otherwise.

Typedef Documentation

HealthActivityIteratorCB [1/2]

typedef bool(* HealthActivityIteratorCB) (HealthActivity activity, time_t time_start, time_t time_end, void *context)

Callback used by health_service_activities_iterate().

Parameters

activity	Which activity the caller is being informed about.
time_start	Start UTC time of the activity.
time_end	End UTC time of the activity.
context	The context parameter initially passed to health_service_activities_iterate().

Returns

true if you are interested in more activities, or false to stop iterating.

HealthActivityIteratorCB [2/2]

typedef bool(* HealthActivityIteratorCB) (HealthActivity activity, time_t time_start, time_t time_end, void *context)

Callback used by health_service_activities_iterate().

Parameters

activity	Which activity the caller is being informed about.
time_start	Start UTC time of the activity.
time_end	End UTC time of the activity.
context	The context parameter initially passed to health_service_activities_iterate().

Returns

true if you are interested in more activities, or false to stop iterating.

HealthEventHandler [1/2]

typedef void(* HealthEventHandler) (HealthEventType event, void *context)

Developer-supplied event handler, called when a health-related event occurs after subscribing via health_service_events_subscribe();

Parameters

event	The type of health-related event that occured.
context	The developer-supplied context pointer.

HealthEventHandler [2/2]

typedef void(* HealthEventHandler) (HealthEventType event, void *context)

Developer-supplied event handler, called when a health-related event occurs after subscribing via health_service_events_subscribe();

Parameters

event	The type of health-related event that occured.
context	The developer-supplied context pointer.

HealthMetricAlert [1/2]

typedef struct HealthMetricAlert HealthMetricAlert

Type used as a handle to a registered metric alert (returned by health_service_register_metric_alert)

HealthMetricAlert [2/2]

typedef struct HealthMetricAlert HealthMetricAlert

Type used as a handle to a registered metric alert (returned by health_service_register_metric_alert)

Enumeration Type Documentation

HealthActivity [1/2]

enum HealthActivity

Health-related activities that can be accessed using.

Enumerator
HealthActivityNone	No special activity.
HealthActivitySleep	The 'sleeping' activity.
HealthActivityRestfulSleep	The 'restful sleeping' activity.
HealthActivityWalk	The 'walk' activity.
HealthActivityRun	The 'run' activity.
HealthActivityOpenWorkout	The 'generic' activity.
HealthActivityNone	No special activity.
HealthActivitySleep	The 'sleeping' activity.
HealthActivityRestfulSleep	The 'restful sleeping' activity.
HealthActivityWalk	The 'walk' activity.
HealthActivityRun	The 'run' activity.
HealthActivityOpenWorkout	The 'generic' activity.

HealthActivity [2/2]

enum HealthActivity

Health-related activities that can be accessed using.

Enumerator
HealthActivityNone	No special activity.
HealthActivitySleep	The 'sleeping' activity.
HealthActivityRestfulSleep	The 'restful sleeping' activity.
HealthActivityWalk	The 'walk' activity.
HealthActivityRun	The 'run' activity.
HealthActivityOpenWorkout	The 'generic' activity.
HealthActivityNone	No special activity.
HealthActivitySleep	The 'sleeping' activity.
HealthActivityRestfulSleep	The 'restful sleeping' activity.
HealthActivityWalk	The 'walk' activity.
HealthActivityRun	The 'run' activity.
HealthActivityOpenWorkout	The 'generic' activity.

HealthAggregation [1/2]

enum HealthAggregation

Used by health_service_aggregate_averaged() to specify what type of aggregation to perform. This aggregation is applied to the metric before the average is computed.

Enumerator
HealthAggregationSum	Sum the metric. The result is the same as calling health_service_sum_averaged(). This operation is only applicable for metrics that accumulate, like HealthMetricStepCount, HealthMetricActiveSeconds, etc.
HealthAggregationAvg	Use the average of the metric. This is only applicable for metrics that measure instantaneous values, like HealthMetricHeartRateBPM
HealthAggregationMin	Use the minimum value of the metric. This is only applicable for metrics that measure instantaneous values, like HealthMetricHeartRateBPM
HealthAggregationMax	Use the maximum value of the metric. This is only applicable for metrics that measure instantaneous values, like HealthMetricHeartRateBPM
HealthAggregationSum	Sum the metric. The result is the same as calling health_service_sum_averaged(). This operation is only applicable for metrics that accumulate, like HealthMetricStepCount, HealthMetricActiveSeconds, etc.
HealthAggregationAvg	Use the average of the metric. This is only applicable for metrics that measure instantaneous values, like HealthMetricHeartRateBPM
HealthAggregationMin	Use the minimum value of the metric. This is only applicable for metrics that measure instantaneous values, like HealthMetricHeartRateBPM
HealthAggregationMax	Use the maximum value of the metric. This is only applicable for metrics that measure instantaneous values, like HealthMetricHeartRateBPM

HealthAggregation [2/2]

enum HealthAggregation

Used by health_service_aggregate_averaged() to specify what type of aggregation to perform. This aggregation is applied to the metric before the average is computed.

Enumerator
HealthAggregationSum	Sum the metric. The result is the same as calling health_service_sum_averaged(). This operation is only applicable for metrics that accumulate, like HealthMetricStepCount, HealthMetricActiveSeconds, etc.
HealthAggregationAvg	Use the average of the metric. This is only applicable for metrics that measure instantaneous values, like HealthMetricHeartRateBPM
HealthAggregationMin	Use the minimum value of the metric. This is only applicable for metrics that measure instantaneous values, like HealthMetricHeartRateBPM
HealthAggregationMax	Use the maximum value of the metric. This is only applicable for metrics that measure instantaneous values, like HealthMetricHeartRateBPM
HealthAggregationSum	Sum the metric. The result is the same as calling health_service_sum_averaged(). This operation is only applicable for metrics that accumulate, like HealthMetricStepCount, HealthMetricActiveSeconds, etc.
HealthAggregationAvg	Use the average of the metric. This is only applicable for metrics that measure instantaneous values, like HealthMetricHeartRateBPM
HealthAggregationMin	Use the minimum value of the metric. This is only applicable for metrics that measure instantaneous values, like HealthMetricHeartRateBPM
HealthAggregationMax	Use the maximum value of the metric. This is only applicable for metrics that measure instantaneous values, like HealthMetricHeartRateBPM

HealthEventType [1/2]

enum HealthEventType

Health event enum. Passed into the HealthEventHandler.

Enumerator
HealthEventSignificantUpdate	All data is considered as outdated and apps should re-read all health data. This happens after an app is subscribed via health_service_events_subscribe(), on a change of the day, or in other cases that significantly change the underlying data.
HealthEventMovementUpdate	Recent values around HealthMetricStepCount, HealthMetricActiveSeconds, or HealthMetricWalkedDistanceMeters have changed.
HealthEventSleepUpdate	Recent values around HealthMetricSleepSeconds, HealthMetricSleepRestfulSeconds, HealthActivitySleep, and HealthActivityRestfulSleep changed.
HealthEventMetricAlert	A metric has crossed the threshold set by health_service_register_metric_alert.
HealthEventHeartRateUpdate	Value of HealthMetricHeartRateBPM or HealthMetricHeartRateRawBPM has changed.
HealthEventSignificantUpdate	All data is considered as outdated and apps should re-read all health data. This happens after an app is subscribed via health_service_events_subscribe(), on a change of the day, or in other cases that significantly change the underlying data.
HealthEventMovementUpdate	Recent values around HealthMetricStepCount, HealthMetricActiveSeconds, or HealthMetricWalkedDistanceMeters have changed.
HealthEventSleepUpdate	Recent values around HealthMetricSleepSeconds, HealthMetricSleepRestfulSeconds, HealthActivitySleep, and HealthActivityRestfulSleep changed.
HealthEventMetricAlert	A metric has crossed the threshold set by health_service_register_metric_alert.
HealthEventHeartRateUpdate	Value of HealthMetricHeartRateBPM or HealthMetricHeartRateRawBPM has changed.

HealthEventType [2/2]

enum HealthEventType

Health event enum. Passed into the HealthEventHandler.

Enumerator
HealthEventSignificantUpdate	All data is considered as outdated and apps should re-read all health data. This happens after an app is subscribed via health_service_events_subscribe(), on a change of the day, or in other cases that significantly change the underlying data.
HealthEventMovementUpdate	Recent values around HealthMetricStepCount, HealthMetricActiveSeconds, or HealthMetricWalkedDistanceMeters have changed.
HealthEventSleepUpdate	Recent values around HealthMetricSleepSeconds, HealthMetricSleepRestfulSeconds, HealthActivitySleep, and HealthActivityRestfulSleep changed.
HealthEventMetricAlert	A metric has crossed the threshold set by health_service_register_metric_alert.
HealthEventHeartRateUpdate	Value of HealthMetricHeartRateBPM or HealthMetricHeartRateRawBPM has changed.
HealthEventSignificantUpdate	All data is considered as outdated and apps should re-read all health data. This happens after an app is subscribed via health_service_events_subscribe(), on a change of the day, or in other cases that significantly change the underlying data.
HealthEventMovementUpdate	Recent values around HealthMetricStepCount, HealthMetricActiveSeconds, or HealthMetricWalkedDistanceMeters have changed.
HealthEventSleepUpdate	Recent values around HealthMetricSleepSeconds, HealthMetricSleepRestfulSeconds, HealthActivitySleep, and HealthActivityRestfulSleep changed.
HealthEventMetricAlert	A metric has crossed the threshold set by health_service_register_metric_alert.
HealthEventHeartRateUpdate	Value of HealthMetricHeartRateBPM or HealthMetricHeartRateRawBPM has changed.

HealthIterationDirection [1/2]

enum HealthIterationDirection

Iteration direction, passed to health_service_activities_iterate(). When iterating backwards (HealthIterationDirectionPast), activities that have a greater value for time_end come first. When iterating forward (HealthIterationDirectionFuture), activities that have a smaller value for time_start come first.

Enumerator
HealthIterationDirectionPast	Iterate into the past.
HealthIterationDirectionFuture	Iterate into the future.
HealthIterationDirectionPast	Iterate into the past.
HealthIterationDirectionFuture	Iterate into the future.

HealthIterationDirection [2/2]

enum HealthIterationDirection

Iteration direction, passed to health_service_activities_iterate(). When iterating backwards (HealthIterationDirectionPast), activities that have a greater value for time_end come first. When iterating forward (HealthIterationDirectionFuture), activities that have a smaller value for time_start come first.

Enumerator
HealthIterationDirectionPast	Iterate into the past.
HealthIterationDirectionFuture	Iterate into the future.
HealthIterationDirectionPast	Iterate into the past.
HealthIterationDirectionFuture	Iterate into the future.

HealthMetric [1/2]

enum HealthMetric

Health metric values used to retrieve health data. For example, using health_service_sum().

Enumerator
HealthMetricStepCount	The number of steps counted.
HealthMetricActiveSeconds	The number of seconds spent active (i.e. not resting).
HealthMetricWalkedDistanceMeters	The distance walked, in meters.
HealthMetricSleepSeconds	The number of seconds spent sleeping.
HealthMetricSleepRestfulSeconds	The number of sleep seconds in the 'restful' or deep sleep state.
HealthMetricRestingKCalories	The number of kcal (Calories) burned while resting due to resting metabolism.
HealthMetricActiveKCalories	The number of kcal (Calories) burned while active.
HealthMetricHeartRateBPM	The heart rate, in beats per minute. This is a filtered value that is at most 15 minutes old.
HealthMetricHeartRateRawBPM	The raw heart rate value of the most recent sample, in beats per minute.
HealthMetricStepCount	The number of steps counted.
HealthMetricActiveSeconds	The number of seconds spent active (i.e. not resting).
HealthMetricWalkedDistanceMeters	The distance walked, in meters.
HealthMetricSleepSeconds	The number of seconds spent sleeping.
HealthMetricSleepRestfulSeconds	The number of sleep seconds in the 'restful' or deep sleep state.
HealthMetricRestingKCalories	The number of kcal (Calories) burned while resting due to resting metabolism.
HealthMetricActiveKCalories	The number of kcal (Calories) burned while active.
HealthMetricHeartRateBPM	The heart rate, in beats per minute. This is a filtered value that is at most 15 minutes old.
HealthMetricHeartRateRawBPM	The raw heart rate value of the most recent sample, in beats per minute.

HealthMetric [2/2]

enum HealthMetric

Health metric values used to retrieve health data. For example, using health_service_sum().

Enumerator
HealthMetricStepCount	The number of steps counted.
HealthMetricActiveSeconds	The number of seconds spent active (i.e. not resting).
HealthMetricWalkedDistanceMeters	The distance walked, in meters.
HealthMetricSleepSeconds	The number of seconds spent sleeping.
HealthMetricSleepRestfulSeconds	The number of sleep seconds in the 'restful' or deep sleep state.
HealthMetricRestingKCalories	The number of kcal (Calories) burned while resting due to resting metabolism.
HealthMetricActiveKCalories	The number of kcal (Calories) burned while active.
HealthMetricHeartRateBPM	The heart rate, in beats per minute. This is a filtered value that is at most 15 minutes old.
HealthMetricHeartRateRawBPM	The raw heart rate value of the most recent sample, in beats per minute.
HealthMetricStepCount	The number of steps counted.
HealthMetricActiveSeconds	The number of seconds spent active (i.e. not resting).
HealthMetricWalkedDistanceMeters	The distance walked, in meters.
HealthMetricSleepSeconds	The number of seconds spent sleeping.
HealthMetricSleepRestfulSeconds	The number of sleep seconds in the 'restful' or deep sleep state.
HealthMetricRestingKCalories	The number of kcal (Calories) burned while resting due to resting metabolism.
HealthMetricActiveKCalories	The number of kcal (Calories) burned while active.
HealthMetricHeartRateBPM	The heart rate, in beats per minute. This is a filtered value that is at most 15 minutes old.
HealthMetricHeartRateRawBPM	The raw heart rate value of the most recent sample, in beats per minute.

HealthServiceAccessibilityMask [1/2]

enum HealthServiceAccessibilityMask

Possible values returned by health_service_metric_accessible(). The values are used in combination as a bitmask. For example, to check if any data is available for a given request use: bool any_data_available = value & HealthServiceAccessibilityMaskAvailable;

Enumerator
HealthServiceAccessibilityMaskAvailable	Return values are available and represent the collected health information.
HealthServiceAccessibilityMaskNoPermission	The user hasn't granted permission.
HealthServiceAccessibilityMaskNotSupported	The queried combination of time span and HealthMetric or HealthActivityMask is currently unsupported.
HealthServiceAccessibilityMaskNotAvailable	No samples were recorded for the given time span.
HealthServiceAccessibilityMaskAvailable	Return values are available and represent the collected health information.
HealthServiceAccessibilityMaskNoPermission	The user hasn't granted permission.
HealthServiceAccessibilityMaskNotSupported	The queried combination of time span and HealthMetric or HealthActivityMask is currently unsupported.
HealthServiceAccessibilityMaskNotAvailable	No samples were recorded for the given time span.

HealthServiceAccessibilityMask [2/2]

enum HealthServiceAccessibilityMask

Possible values returned by health_service_metric_accessible(). The values are used in combination as a bitmask. For example, to check if any data is available for a given request use: bool any_data_available = value & HealthServiceAccessibilityMaskAvailable;

Enumerator
HealthServiceAccessibilityMaskAvailable	Return values are available and represent the collected health information.
HealthServiceAccessibilityMaskNoPermission	The user hasn't granted permission.
HealthServiceAccessibilityMaskNotSupported	The queried combination of time span and HealthMetric or HealthActivityMask is currently unsupported.
HealthServiceAccessibilityMaskNotAvailable	No samples were recorded for the given time span.
HealthServiceAccessibilityMaskAvailable	Return values are available and represent the collected health information.
HealthServiceAccessibilityMaskNoPermission	The user hasn't granted permission.
HealthServiceAccessibilityMaskNotSupported	The queried combination of time span and HealthMetric or HealthActivityMask is currently unsupported.
HealthServiceAccessibilityMaskNotAvailable	No samples were recorded for the given time span.

HealthServiceTimeScope [1/2]

enum HealthServiceTimeScope

Used by health_service_sum_averaged() to specify how the average is computed.

Enumerator
HealthServiceTimeScopeOnce	No average computed. The result is the same as calling health_service_sum().
HealthServiceTimeScopeWeekly	Compute average using the same day from each week. For example, every Monday if the passed in time range falls on a Monday.
HealthServiceTimeScopeDailyWeekdayOrWeekend	Compute average using either weekdays (Monday to Friday) or weekends (Saturday and Sunday), depending on which day the passed in time range falls.
HealthServiceTimeScopeDaily	Compute average across all days of the week.
HealthServiceTimeScopeOnce	No average computed. The result is the same as calling health_service_sum().
HealthServiceTimeScopeWeekly	Compute average using the same day from each week. For example, every Monday if the passed in time range falls on a Monday.
HealthServiceTimeScopeDailyWeekdayOrWeekend	Compute average using either weekdays (Monday to Friday) or weekends (Saturday and Sunday), depending on which day the passed in time range falls.
HealthServiceTimeScopeDaily	Compute average across all days of the week.

HealthServiceTimeScope [2/2]

enum HealthServiceTimeScope

Used by health_service_sum_averaged() to specify how the average is computed.

Enumerator
HealthServiceTimeScopeOnce	No average computed. The result is the same as calling health_service_sum().
HealthServiceTimeScopeWeekly	Compute average using the same day from each week. For example, every Monday if the passed in time range falls on a Monday.
HealthServiceTimeScopeDailyWeekdayOrWeekend	Compute average using either weekdays (Monday to Friday) or weekends (Saturday and Sunday), depending on which day the passed in time range falls.
HealthServiceTimeScopeDaily	Compute average across all days of the week.
HealthServiceTimeScopeOnce	No average computed. The result is the same as calling health_service_sum().
HealthServiceTimeScopeWeekly	Compute average using the same day from each week. For example, every Monday if the passed in time range falls on a Monday.
HealthServiceTimeScopeDailyWeekdayOrWeekend	Compute average using either weekdays (Monday to Friday) or weekends (Saturday and Sunday), depending on which day the passed in time range falls.
HealthServiceTimeScopeDaily	Compute average across all days of the week.

MeasurementSystem [1/2]

enum MeasurementSystem

Types of measurement system a HealthMetric may be measured in.

Enumerator
MeasurementSystemUnknown	The measurement system is unknown, or does not apply to the chosen metric.
MeasurementSystemMetric	The metric measurement system.
MeasurementSystemImperial	The imperial measurement system.
MeasurementSystemUnknown	The measurement system is unknown, or does not apply to the chosen metric.
MeasurementSystemMetric	The metric measurement system.
MeasurementSystemImperial	The imperial measurement system.

MeasurementSystem [2/2]

enum MeasurementSystem

Types of measurement system a HealthMetric may be measured in.

Enumerator
MeasurementSystemUnknown	The measurement system is unknown, or does not apply to the chosen metric.
MeasurementSystemMetric	The metric measurement system.
MeasurementSystemImperial	The imperial measurement system.
MeasurementSystemUnknown	The measurement system is unknown, or does not apply to the chosen metric.
MeasurementSystemMetric	The metric measurement system.
MeasurementSystemImperial	The imperial measurement system.

Function Documentation

health_service_activities_iterate()

void health_service_activities_iterate	(	HealthActivityMask	activity_mask,
		time_t	time_start,
		time_t	time_end,
		HealthIterationDirection	direction,
		HealthActivityIteratorCB	callback,
		void *	context
	)

Iterates backwards or forward within a given time span to list all recorded activities. For example, this can be used to find the last recorded sleep phase or all deep sleep phases in a given time range. Any activity that overlaps with time_start and time_end will be included, even if the start time starts before time_start or end time ends after time_end.

Parameters

activity_mask	A bitmask containing set of activities you are interested in.
time_start	UTC time of the earliest time you are interested in.
time_end	UTC time of the latest time you are interested in.
direction	The direction in which to iterate.
callback	Developer-supplied callback that is called for each activity iterated over.
context	Developer-supplied context pointer that is passed to the callback.

health_service_aggregate_averaged()

HealthValue health_service_aggregate_averaged	(	HealthMetric	metric,
		time_t	time_start,
		time_t	time_end,
		HealthAggregation	aggregation,
		HealthServiceTimeScope	scope
	)

Return the value of an aggregated metric over a given time range. This call is more flexible than health_service_sum_averaged because it lets you specify which aggregation function to perform.

The aggregation function aggregation is applied to the metric metric over the given time range time_start to time_end first, and then an average is computed based on the passed in scope.

For example, if you want to get the average number of steps taken from 12 AM (midnight) to 9 AM across all days you would specify: time_t time_start = time_start_of_today(); time_t time_end = time_start + (9 * SECONDS_PER_HOUR); HealthValue value = health_service_aggregate_averaged(HealthMetricStepCount, time_start, time_end, HealthAggregationSum, HealthServiceTimeScopeDaily);

If you want to compute the average heart rate on Mondays and today is a Monday, you would specify: time_t time_start = time_start_of_today(), time_t time_end = time_start + SECONDS_PER_DAY, HealthValue value = health_service_aggregate_averaged(HealthMetricHeartRateBPM, time_start, time_end, HealthAggregationAvg, HealthServiceTimeScopeWeekly); To get the average of the minimum heart rate seen on Mondays for example, you would instead pass in HealthAggregationMin

Certain HealthAggregation operations are only applicable to certain types of metrics. See the notes above on HealthAggregation for details. Use health_service_metric_aggregate_averaged_accessible to check for applicability at run time.

Parameters

metric	Which HealthMetric to query.
time_start	UTC time of the start of the query interval.
time_end	UTC time of the end of the query interval.
aggregation	the aggregation function to perform on the metric. This operation is performed across the passed in time range time_start to time_end.
scope	HealthServiceTimeScope value describing how the average should be computed. Use HealthServiceTimeScopeOnce to not compute an average.

Returns

The average of the aggregation performed on the given metric over the given time range, if available.

health_service_any_activity_accessible()

HealthServiceAccessibilityMask health_service_any_activity_accessible	(	HealthActivityMask	activity_mask,
		time_t	time_start,
		time_t	time_end
	)

Check if a certain combination of metric, HealthActivityMask and time span is accessible. Developers should check if the return value is HealthServiceAccessibilityMaskAvailable before calling any other HealthService APIs that involve the given activities.

Parameters

activity_mask	A bitmask of activities you are interested in.
time_start	Earliest UTC time you are interested in.
time_end	Latest UTC time you are interested in.

Returns

A HealthServiceAccessibilityMask representing which of the passed HealthActivityMask values are available under the given constraints.

health_service_cancel_metric_alert()

bool health_service_cancel_metric_alert

(

HealthMetricAlert *

alert

)

Cancel an metric alert previously created with health_service_register_metric_alert.

Parameters

alert

the HealthMetricAlert previously returned by health_service_register_metric_alert

Returns

true on success, false on failure

health_service_events_subscribe()

bool health_service_events_subscribe	(	HealthEventHandler	handler,
		void *	context
	)

Subscribe to HealthService events. This allocates a cache on the application's heap of up to 2048 bytes that will be de-allocated if you call health_service_events_unsubscribe(). If there's not enough heap available, this function will return false and will not subscribe to any events.

Parameters

handler	Developer-supplied event handler function.
context	Developer-supplied context pointer.

Returns

true on success, false on failure.

health_service_events_unsubscribe()

bool health_service_events_unsubscribe

(

void

)

Unsubscribe from HealthService events.

Returns

true on success, false on failure.

health_service_get_heart_rate_sample_period_expiration_sec()

uint16_t health_service_get_heart_rate_sample_period_expiration_sec

(

void

)

Return how long a heart rate sample period request (sent via health_service_set_heart_rate_sample_period) will remain active after the app exits. If there is no current request by this app, this call will return 0.

Returns

The number of seconds the heart rate sample period request will remain active after the app exits, or 0 if there is no active request by this app.

health_service_get_measurement_system_for_display()

MeasurementSystem health_service_get_measurement_system_for_display

(

HealthMetric

metric

)

Get the preferred measurement system for a given HealthMetric, if the user has chosen a preferred system and it is applicable to that metric.

Parameters

metric

A metric value chosen from HealthMetric.

Returns

A value from MeasurementSystem if applicable, else MeasurementSystemUnknown.

health_service_get_minute_history()

uint32_t health_service_get_minute_history	(	HealthMinuteData *	minute_data,
		uint32_t	max_records,
		time_t *	time_start,
		time_t *	time_end
	)

Return historical minute data records. This fills in the minute_data array parameter with minute by minute statistics of the user's steps, average watch orientation, etc. The data is returned in time order, with the oldest minute data returned at minute_data[0].

Parameters

	minute_data	Pointer to an array of HealthMinuteData records that will be filled in with the historical minute data.
	max_records	The maximum number of records the minute_data array can hold.
[in,out]	time_start	On entry, the UTC time of the first requested record. On exit, the UTC time of the first second of the first record actually returned. If time_start on entry is somewhere in the middle of a minute interval, this function behaves as if the caller passed in the start of that minute.
[in,out]	time_end	On entry, the UTC time of the end of the requested range of records. On exit, the UTC time of the end of the last record actually returned (i.e. start time of last record + 60). If time_end on entry is somewhere in the middle of a minute interval, this function behaves as if the caller passed in the end of that minute.

Returns

Actual number of records returned. May be less then the maximum requested.

Note

If the return value is zero, time_start and time_end are meaningless. It's not guaranteed that all records contain valid data, even if the return value is greater than zero. Check HealthMinuteData.is_invalid to see if a given record contains valid data.

health_service_metric_accessible()

HealthServiceAccessibilityMask health_service_metric_accessible	(	HealthMetric	metric,
		time_t	time_start,
		time_t	time_end
	)

Check if a certain combination of metric and time span is accessible using health_service_sum by returning a value of HealthServiceAccessibilityMask. Developers should check if the return value is HealthServiceAccessibilityMaskAvailable before calling health_service_sum.

Note that this call is the same as calling health_service_metric_averaged_accessible(metric, time_start, time_end, HealthServiceTimeScopeOnce)

Parameters

metric	The metric to query for data.
time_start	Earliest UTC time you are interested in.
time_end	Latest UTC time you are interested in.

Returns

A HealthServiceAccessibilityMask representing the accessible metrics in this time range.

health_service_metric_aggregate_averaged_accessible()

HealthServiceAccessibilityMask health_service_metric_aggregate_averaged_accessible	(	HealthMetric	metric,
		time_t	time_start,
		time_t	time_end,
		HealthAggregation	aggregation,
		HealthServiceTimeScope	scope
	)

Check if a certain combination of metric, time span, aggregation operation, and scope is accessible for calculating aggregated, averaged data by returning a value of HealthServiceAccessibilityMask. Developers should check if the return value is HealthServiceAccessibilityMaskAvailable before calling health_service_aggregate_averaged.

Parameters

metric	The metric to query for averaged data.
time_start	Earliest UTC time you are interested in.
time_end	Latest UTC time you are interested in.
aggregation	The aggregation to perform
scope	HealthServiceTimeScope value describing how the average should be computed.

Returns

A \HealthServiceAccessibilityMask value decribing whether averaged data is available.

health_service_metric_averaged_accessible()

HealthServiceAccessibilityMask health_service_metric_averaged_accessible	(	HealthMetric	metric,
		time_t	time_start,
		time_t	time_end,
		HealthServiceTimeScope	scope
	)

Check if a certain combination of metric, time span, and scope is accessible for calculating summed, averaged data by returning a value of HealthServiceAccessibilityMask. Developers should check if the return value is HealthServiceAccessibilityMaskAvailable before calling health_service_sum_averaged.

Note that this call is the same as calling health_service_metric_aggregate_averaged_accessible(metric, time_start, time_end, HealthAggregationSum, HealthServiceTimeScopeOnce)

Parameters

metric	The metric to query for averaged data.
time_start	Earliest UTC time you are interested in.
time_end	Latest UTC time you are interested in.
scope	HealthServiceTimeScope value describing how the average should be computed.

Returns

A \HealthServiceAccessibilityMask value decribing whether averaged data is available.

health_service_peek_current_activities()

HealthActivityMask health_service_peek_current_activities

(

void

)

Return a HealthActivityMask containing a set of bits, one set for each activity that is currently active.

Returns

A bitmask with zero or more HealthActivityMask bits set as appropriate.

health_service_peek_current_value()

HealthValue health_service_peek_current_value

(

HealthMetric

metric

)

Convenience function for peeking at the current value of a metric. This is useful for metrics like HealthMetricHeartRateBPM that represent instantaneous values. It is NOT applicable for metrics like HealthMetricStepCount that must be accumulated over time (it will return 0 if passed that type of metric). This call is equivalent to calling health_service_aggregate_averaged(metric, time(NULL), time(NULL), HealthAggregationAvg, HealthServiceTimeScopeOnce)

Parameters

metric

The metric to query.

Returns

The current value of that metric, if available.

health_service_register_metric_alert()

HealthMetricAlert * health_service_register_metric_alert	(	HealthMetric	metric,
		HealthValue	threshold
	)

Register for an alert when a metric crosses the given threshold. When the metric crosses this threshold (either goes above or below it), a HealthEventMetricAlert event will be generated. To cancel this registration, pass the returned HealthMetricAlert value to health_service_cancel_metric_alert. The only metric currently supported by this call is HealthMetricHeartRateBPM, but future versions may support additional metrics. To see if a specific metric is supported by this call, use: `time_t now = time(NULL); HealthServiceAccessibilityMask accessible = health_service_metric_aggregate_averaged_accessible(metric, now, now, HealthAggregationAvg, HealthServiceTimeScopeOnce); bool alert_supported = (accessible & HealthServiceAccessibilityMaskAvailable); ` In the current implementation, only one alert per metric can be registered at a time. Future implementations may support two or more simulataneous alert registrations per metric. To change the alert threshold in the current implementation, cancel the original registration using health_service_cancel_metric_alert before registering the new threshold.

Parameters

threshold

the threshold value

Returns

handle to the alert registration on success, NULL on failure

health_service_set_heart_rate_sample_period()

bool health_service_set_heart_rate_sample_period

(

uint16_t

interval_sec

)

Set the desired sampling period for heart rate readings. Normally, the system will sample the heart rate using a sampling period that is automatically chosen to provide useful information without undue battery drain (it automatically samples more often during periods of intense activity, and less often when the user is idle). If desired though, an application can request a specific sampling period using this call. The system will use this as a suggestion, but does not guarantee that the requested period will be used. The actual sampling period may be greater or less due to system needs or heart rate sensor reading quality issues. Each time a new heart rate reading becomes available, a HealthEventHeartRateUpdate event will be sent to the application's HealthEventHandler. The sample period request will remain in effect the entire time the app is running unless it is explicitly cancelled (by calling this method again with 0 as the desired interval). If the app exits without first cancelling the request, it will remain in effect even for a limited time afterwards. To determine how long it will remain active after the app exits, use health_service_get_heart_rate_sample_period_expiration_sec. Unless the app explicitly needs to access to historical high-resolution heart rate data, it is best practice to always cancel the sample period request before exiting in order to maximize battery life. Historical heart rate data can be accessed using the health_service_get_minute_history call.

Parameters

interval_sec

desired interval between heart rate reading updates. Pass 0 to go back to automatically chosen intervals.

Returns

true on success, false on failure

health_service_sum()

HealthValue health_service_sum	(	HealthMetric	metric,
		time_t	time_start,
		time_t	time_end
	)

Return the sum of a HealthMetric's values over a time range. The time_start and time_end parameters define the range of time you want the sum for.

Note

The value returned will be based on daily totals, weighted for the length of the specified time range. This may change in the future.

Parameters

metric	The metric to query for data.
time_start	UTC time of the earliest data item to incorporate into the sum.
time_end	UTC time of the most recent data item to incorporate into the sum.

Returns

The sum of that metric over the given time range, if available.

health_service_sum_averaged()

HealthValue health_service_sum_averaged	(	HealthMetric	metric,
		time_t	time_start,
		time_t	time_end,
		HealthServiceTimeScope	scope
	)

Return the value of a metric's sum over a given time range between time_start and time_end. Using this call you can specify the time range that you are interested in getting the average for, as well as a scope specifier on how to compute an average of the sum. For example, if you want to get the average number of steps taken from 12 AM (midnight) to 9 AM across all days you would specify: time_t time_start = time_start_of_today(); time_t time_end = time_start + (9 * SECONDS_PER_HOUR); HealthValue value = health_service_sum_averaged(HealthMetricStepCount, time_start, time_end, HealthServiceTimeScopeDaily);

If you want the average number of steps taken on a weekday (Monday to Friday) and today is a Monday (in the local timezone) you would specify: time_start = time_start_of_today(); time_end = time_start + SECONDS_PER_DAY; HealthValue value = health_service_sum_averaged(HealthMetricStepCount, time_start, time_end, HealthServiceTimeScopeDailyWeekdayOrWeekend);

Note that this call is the same as calling health_service_aggregate_averaged(metric, time_start, time_end, HealthAggregationSum, scope)

Parameters

metric	Which HealthMetric to query.
time_start	UTC time of the start of the query interval.
time_end	UTC time of the end of the query interval.
scope	HealthServiceTimeScope value describing how the average should be computed.

Returns

The average of the sum of the given metric over the given time range, if available.

health_service_sum_today()

HealthValue health_service_sum_today

(

HealthMetric

metric

)

Convenience wrapper for health_service_sum() that returns the sum for today.

Parameters

metric

The metric to query.

Returns

The sum of that metric's data for today, if available.