CMStepCounter Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/CoreMotion.framework
Availability
Available in iOS 7.0 and later.
Declared in
CMStepCounter.h

Overview

The CMStepCounter class provides access to the number of steps the user has taken with the device. Step information is gathered on devices with the appropriate built-in hardware and stored so that you can run queries to determine the user’s recent physical activity. You use this class to gather both current step data and any historical data.

Tasks

Determining Step Counting Availability

Starting and Stopping Step Counting Updates

Getting Historical Step Counting Data

Class Methods

isStepCountingAvailable

Returns a Boolean indicating whether step-counting support is available on the current device.

+ (BOOL)isStepCountingAvailable
Return Value

YES if step-counting support is available or NO if it is not.

Discussion

Step-counting support is not available on all iOS devices. Use this method to determine if support is available on the current device.

Availability
  • Available in iOS 7.0 and later.
Declared In
CMStepCounter.h

Instance Methods

queryStepCountStartingFrom:to:toQueue:withHandler:

Gathers and returns historical step count data for the specified time period.

- (void)queryStepCountStartingFrom:(NSDate *)start to:(NSDate *)end toQueue:(NSOperationQueue *)queue withHandler:(CMStepQueryHandler)handler
Parameters
start

The start time to use when gathering step count data. This parameter must not be nil.

end

The end time to use when gathering step count data. This parameter must not be nil.

queue

The operation queue on which to execute the specified handler block. You can specify a custom queue or use the operation queue associated with your app’s main thread. This parameter must not be nil.

handler

The block to execute with the results. For information about the parameters of this block, see CMStepQueryHandler. This parameter must not be nil.

Discussion

This method runs asynchronously, returning immediately and delivering the results to the specified handler block. The system stores only the last seven days worth of step data at most. If there are no samples for the specified range of time, a value of 0 is passed to the handler block.

Availability
  • Available in iOS 7.0 and later.
Declared In
CMStepCounter.h

startStepCountingUpdatesToQueue:updateOn:withHandler:

Starts the delivery of current step-counting data to your app.

- (void)startStepCountingUpdatesToQueue:(NSOperationQueue *)queue updateOn:(NSInteger)stepCounts withHandler:(CMStepUpdateHandler)handler
Parameters
queue

The operation queue on which to execute the specified handler block. You can specify a custom queue or use the operation queue associated with your app’s main thread. This parameter must not be nil.

stepCounts

The number of steps to record before executing the handler block. The number of steps must be greater than 0.

handler

The block to execute when the number of steps has been reached or exceeded. For information about the parameters of this block, see CMStepUpdateHandler. This property must not be nil.

Discussion

This method initiates tracking of the user’s steps and calls the provided block periodically to deliver the results. When you call this method, the step counter resets the current step count value to 0 and begins counting. Each time the step counter records the number of steps in the stepCounts parameter, it executes the specified handler block. For example, if stepCounts is 100, it would send updates at 100 steps, 200 steps, 300 steps, and so on. The number of steps reported to your handler is always the total number of steps since you called this method.

The handler block is executed on a best effort basis each time the step count threshold is exceeded. If your app is suspended when the threshold is exceeded, the block is not executed. When your app resumes, the block is not executed until the threshold is exceeded again.

To stop the delivery of step-counting updates, call the stopStepCountingUpdates method. Updates also stop when the step counter object itself is deallocated.

Availability
  • Available in iOS 7.0 and later.
Declared In
CMStepCounter.h

stopStepCountingUpdates

Stops the delivery of step-counting updates to your app.

- (void)stopStepCountingUpdates
Discussion

Call this method to stop the delivery of updates that you started by calling the startStepCountingUpdatesToQueue:updateOn:withHandler: method. This method does not stop queries started using the queryStepCountStartingFrom:to:toQueue:withHandler: method.

Availability
  • Available in iOS 7.0 and later.
Declared In
CMStepCounter.h

Constants

CMStepQueryHandler

A block that reports the number of steps for a query operation.

typedef void (^CMStepQueryHandler)(NSInteger numberOfSteps, NSError *error);
Discussion

This block takes two parameters:

numberOfSteps

The number of steps that occurred between the start and end times specified by the query.

error

An error object indicating that there was a problem gathering the data or nil if the number of steps was determined correctly.

Availability
  • Available in iOS 7.0 and later.
Declared In
CMStepCounter.h

CMStepUpdateHandler

A block that reports the number of steps recorded since updates began.

typedef void (^CMStepUpdateHandler)(NSInteger numberOfSteps, NSDate *timestamp, NSError *error);
Discussion

This block takes the following parameters:

numberOfSteps

The total number of steps since the startStepCountingUpdatesToQueue:updateOn:withHandler: method was called.

timestamp

The time at which the current step count was reported.

error

An error object indicating that there was a problem gathering the data or nil if the number of steps was determined correctly.

Availability
  • Available in iOS 7.0 and later.
Declared In
CMStepCounter.h