source: orbit/iOS/Orbit/CoreMotion.framework/Headers/CMMotionManager.h @ 876e42b

Servo
Last change on this file since 876e42b was 876e42b, checked in by Steve Castellotti <sc@…>, 7 years ago
  • Property mode set to 100644
File size: 12.9 KB
Line 
1/*
2 *  CMMotionManager.h
3 *  CoreMotion
4 *
5 *  Copyright (c) 2010 Apple Inc. All rights reserved.
6 *
7 */
8
9#import <Foundation/Foundation.h>
10
11#import <CoreMotion/CMAccelerometer.h>
12#import <CoreMotion/CMGyro.h>
13#import <CoreMotion/CMDeviceMotion.h>
14#import <CoreMotion/CMMagnetometer.h>
15
16/*
17 * There are two methods to receive data from CMMotionManager: push and pull.
18 *
19 * Before using either method, be sure to set the update interval property
20 * appropriate to the type of data you're interested in. These properties are:
21 * accelerometerUpdateInterval, gyroUpdateInterval, and deviceMotionUpdateInterval.
22 *
23 * To use the pull method, simply call startAccelerometerUpdates, startGyroUpdates,
24 * and/or startDeviceMotionUpdates, depending on the type of data desired. Then,
25 * whenever a new sample of data is desired, simply examine the appropriate
26 * CMMotionManager property (accelerometerData, gyroData, or deviceMotion).
27 *
28 * To use the push method, simply call startAccelerometerUpdatesToQueue:withHandler:,
29 * startGyroUpdatesToQueue:withHandler:, and/or
30 * startDeviceMotionUpdatesToQueue:withHandler:, depending on the type of data
31 * desired. You'll need to pass an NSOperationQueue and block to each call. When a new sample of
32 * data arrives, a new instance of the block will be added to the appropriate NSOperationQueue.
33 * When you stop the updates (see below), all operations in the given NSOperationQueue will be
34 * cancelled, so it is recommended to pass CMMotionManager a queue that will not be used in other
35 * contexts.
36 *
37 * Regardless of whether you used push or pull, when you're done, be sure to call the stop method
38 * appropriate for the type of updates you started.  These methods are: stopAccelerometerUpdates,
39 * stopGyroUpdates, and stopDeviceMotionUpdates.
40 *
41 */
42
43/*
44 *  CMAccelerometerHandler
45 * 
46 *  Discussion:
47 *    Typedef of block to be invoked when accelerometer data is available.
48 */
49typedef void (^CMAccelerometerHandler)(CMAccelerometerData *accelerometerData, NSError *error);
50
51/*
52 *  CMGyroHandler
53 * 
54 *  Discussion:
55 *    Typedef of block to be invoked when gyro data is available.
56 */
57typedef void (^CMGyroHandler)(CMGyroData *gyroData, NSError *error);
58
59/*
60 *  CMDeviceMotionHandler
61 * 
62 *  Discussion:
63 *    Typedef of block to be invoked when device motion data is available.
64 */
65typedef void (^CMDeviceMotionHandler)(CMDeviceMotion *motion, NSError *error);
66
67/*
68 *  CMMagnetometerHandler
69 * 
70 *  Discussion:
71 *    Typedef of block to be invoked when magnetometer data is available.
72 */
73typedef void (^CMMagnetometerHandler)(CMMagnetometerData *magnetometerData, NSError *error) NS_AVAILABLE(NA,5_0);
74
75/*
76 *  CMMotionManager
77 * 
78 *  Discussion:
79 *    The CMMotionManager object is your entry point to the motion service.
80 */
81NS_CLASS_AVAILABLE(NA,4_0)
82@interface CMMotionManager : NSObject
83{
84@private
85        id _internal;
86}
87
88/*
89 *  accelerometerUpdateInterval
90 * 
91 *  Discussion:
92 *                      The interval at which to deliver accelerometer data to the specified
93 *                      handler once startAccelerometerUpdatesToQueue:withHandler: is called.
94 *                      The units are in seconds. The value of this property is capped to
95 *                      certain minimum and maximum values. The maximum value is determined by
96 *                      the maximum frequency supported by the hardware. If sensitive to the
97 *                      interval of acceleration data, an application should always check the
98 *                      timestamps on the delivered CMAcceleration instances to determine the
99 *                      true update interval.
100 */
101@property(assign, nonatomic) NSTimeInterval accelerometerUpdateInterval;
102
103/*
104 *  accelerometerAvailable
105 * 
106 *  Discussion:
107 *      Determines whether accelerometer is available.
108 */
109@property(readonly, nonatomic, getter=isAccelerometerAvailable) BOOL accelerometerAvailable;
110
111/*
112 *  accelerometerActive
113 * 
114 *  Discussion:
115 *                      Determines whether the CMMotionManager is currently providing
116 *                      accelerometer updates.
117 */
118@property(readonly, nonatomic, getter=isAccelerometerActive) BOOL accelerometerActive;
119
120/*
121 *  accelerometerData
122 * 
123 *  Discussion:
124 *                      Returns the latest sample of accelerometer data, or nil if none is available.
125 */
126
127@property(readonly) CMAccelerometerData *accelerometerData;
128
129/*
130 *  startAccelerometerUpdates
131 * 
132 *  Discussion:
133 *                      Starts accelerometer updates with no handler. To receive the latest accelerometer data
134 *                      when desired, examine the accelerometerData property.
135 */
136- (void)startAccelerometerUpdates;
137
138/*
139 *  startAccelerometerUpdatesToQueue:withHandler:
140 * 
141 *  Discussion:
142 *                      Starts accelerometer updates, providing data to the given handler through the given queue.
143 *                      Note that when the updates are stopped, all operations in the
144 *                      given NSOperationQueue will be cancelled.
145 */
146- (void)startAccelerometerUpdatesToQueue:(NSOperationQueue *)queue withHandler:(CMAccelerometerHandler)handler;
147
148/*
149 *  stopAccelerometerUpdates
150 * 
151 *  Discussion:
152 *                      Stop accelerometer updates.
153 */
154- (void)stopAccelerometerUpdates;
155
156/*
157 *  gyroUpdateInterval
158 * 
159 *  Discussion:
160 *      The interval at which to deliver gyro data to the specified
161 *                      handler once startGyroUpdatesToQueue:withHandler: is called.
162 *                      The units are in seconds. The value of this property is capped to
163 *                      certain minimum and maximum values. The maximum value is determined by
164 *                      the maximum frequency supported by the hardware. If sensitive to the
165 *                      interval of gyro data, an application should always check the
166 *                      timestamps on the delivered CMGyroData instances to determine the
167 *                      true update interval.
168 */
169@property(assign, nonatomic) NSTimeInterval gyroUpdateInterval;
170
171/*
172 *  gyroAvailable
173 * 
174 *  Discussion:
175 *      Determines whether gyro is available.
176 */
177@property(readonly, nonatomic, getter=isGyroAvailable) BOOL gyroAvailable;
178
179/*
180 *  gyroActive
181 * 
182 *  Discussion:
183 *      Determines whether the CMMotionManager is currently providing gyro updates.
184 */
185@property(readonly, nonatomic, getter=isGyroActive) BOOL gyroActive;
186
187/*
188 *  gyroData
189 * 
190 *  Discussion:
191 *              Returns the latest sample of gyro data, or nil if none is available.
192 */
193@property(readonly) CMGyroData *gyroData;
194
195/*
196 *  startGyroUpdates
197 * 
198 *  Discussion:
199 *                      Starts gyro updates with no handler. To receive the latest gyro data
200 *                      when desired, examine the gyroData property.
201 */
202- (void)startGyroUpdates;
203
204/*
205 *  startGyroUpdatesToQueue:withHandler:
206 * 
207 *  Discussion:
208 *                      Starts gyro updates, providing data to the given handler through the given queue.
209 *                      Note that when the updates are stopped, all operations in the
210 *                      given NSOperationQueue will be cancelled.
211
212 */
213- (void)startGyroUpdatesToQueue:(NSOperationQueue *)queue withHandler:(CMGyroHandler)handler;
214
215/*
216 *  stopGyroUpdates
217 * 
218 *  Discussion:
219 *                      Stops gyro updates.
220 */
221- (void)stopGyroUpdates;
222
223/*
224 *  magnetometerUpdateInterval
225 * 
226 *  Discussion:
227 *      The interval at which to deliver magnetometer data to the specified
228 *                      handler once startMagnetometerUpdatesToQueue:withHandler: is called.
229 *                      The units are in seconds. The value of this property is capped to
230 *                      certain minimum and maximum values. The maximum value is determined by
231 *                      the maximum frequency supported by the hardware. If sensitive to the
232 *                      interval of magnetometer data, an application should always check the
233 *                      timestamps on the delivered CMMagnetometerData instances to determine the
234 *                      true update interval.
235 */
236@property(assign, nonatomic) NSTimeInterval magnetometerUpdateInterval NS_AVAILABLE(NA,5_0);
237
238/*
239 *  magnetometerAvailable
240 * 
241 *  Discussion:
242 *      Determines whether magetometer is available.
243 */
244@property(readonly, nonatomic, getter=isMagnetometerAvailable) BOOL magnetometerAvailable NS_AVAILABLE(NA,5_0);
245
246/*
247 *  magnetometerActive
248 * 
249 *  Discussion:
250 *      Determines whether the CMMotionManager is currently providing magnetometer updates.
251 */
252@property(readonly, nonatomic, getter=isMagnetometerActive) BOOL magnetometerActive NS_AVAILABLE(NA,5_0);
253
254/*
255 *  magnetometerData
256 * 
257 *  Discussion:
258 *      Returns the latest sample of magnetometer data, or nil if none is available.
259 */
260@property(readonly) CMMagnetometerData *magnetometerData NS_AVAILABLE(NA,5_0);
261
262/*
263 *  startMagnetometerUpdates
264 * 
265 *  Discussion:
266 *      Starts magnetometer updates with no handler. To receive the latest magnetometer data
267 *          when desired, examine the magnetometerData property.
268 */
269- (void)startMagnetometerUpdates NS_AVAILABLE(NA,5_0);
270
271/*
272 *  startMagnetometerUpdatesToQueue:withHandler:
273 * 
274 *  Discussion:
275 *      Starts magnetometer updates, providing data to the given handler through the given queue.
276 */
277- (void)startMagnetometerUpdatesToQueue:(NSOperationQueue *)queue withHandler:(CMMagnetometerHandler)handler NS_AVAILABLE(NA,5_0);
278
279/*
280 *  stopMagnetometerUpdates
281 * 
282 *  Discussion:
283 *      Stops magnetometer updates.
284 */
285- (void)stopMagnetometerUpdates NS_AVAILABLE(NA,5_0);
286
287/*
288 *  deviceMotionUpdateInterval
289 * 
290 *  Discussion:
291 *      The interval at which to deliver device motion data to the specified
292 *                      handler once startDeviceMotionUpdatesToQueue:withHandler: is called.
293 *                      The units are in seconds. The value of this property is capped to
294 *                      certain minimum and maximum values. The maximum value is determined by
295 *                      the maximum frequency supported by the hardware. If sensitive to the
296 *                      interval of device motion data, an application should always check the
297 *                      timestamps on the delivered CMDeviceMotion instances to determine the
298 *                      true update interval.
299 */
300@property(assign, nonatomic) NSTimeInterval deviceMotionUpdateInterval;
301
302/*
303 *  availableAttitudeReferenceFrames
304 * 
305 *  Discussion:
306 *     Returns a bitmask specifying the available attitude reference frames on the device.
307 */
308+ (NSUInteger)availableAttitudeReferenceFrames NS_AVAILABLE(NA,5_0);
309
310/*
311 *  attitudeReferenceFrame
312 * 
313 *  Discussion:
314 *              If device motion is active, returns the reference frame currently in-use.
315 *              If device motion is not active, returns the default attitude reference frame
316 *              for the device. If device motion is not available on the device, the value
317 *              is undefined.
318 *             
319 */
320@property(readonly, nonatomic) CMAttitudeReferenceFrame attitudeReferenceFrame NS_AVAILABLE(NA,5_0);
321
322/*
323 *  deviceMotionAvailable
324 * 
325 *  Discussion:
326 *      Determines whether device motion is available using any available attitude reference frame.
327 */
328@property(readonly, nonatomic, getter=isDeviceMotionAvailable) BOOL deviceMotionAvailable;
329
330/*
331 *  deviceMotionActive
332 * 
333 *  Discussion:
334 *      Determines whether the CMMotionManager is currently providing device
335 *                      motion updates.
336 */
337@property(readonly, nonatomic, getter=isDeviceMotionActive) BOOL deviceMotionActive;
338
339/*
340 *  deviceMotion
341 * 
342 *  Discussion:
343 *                      Returns the latest sample of device motion data, or nil if none is available.
344 */
345@property(readonly) CMDeviceMotion *deviceMotion;
346
347/*
348 *  startDeviceMotionUpdates
349 * 
350 *  Discussion:
351 *                      Starts device motion updates with no handler. To receive the latest device motion data
352 *                      when desired, examine the deviceMotion property. Uses the default reference frame for
353 *                      the device. Examine CMMotionManager's attitudeReferenceFrame to determine this.
354 */
355- (void)startDeviceMotionUpdates;
356
357/*
358 *  startDeviceMotionUpdatesToQueue:withHandler:
359 * 
360 *  Discussion:
361 *                      Starts device motion updates, providing data to the given handler through the given queue.
362 *                      Uses the default reference frame for the device. Examine CMMotionManager's
363 *                      attitudeReferenceFrame to determine this.
364 *                     
365 */
366- (void)startDeviceMotionUpdatesToQueue:(NSOperationQueue *)queue withHandler:(CMDeviceMotionHandler)handler;
367
368/*
369 *  startDeviceMotionUpdatesUsingReferenceFrame:
370 * 
371 *  Discussion:
372 *                      Starts device motion updates with no handler. To receive the latest device motion data
373 *                      when desired, examine the deviceMotion property. The specified frame will be used as
374 *                      reference for the attitude estimates.
375 *
376 */
377- (void)startDeviceMotionUpdatesUsingReferenceFrame:(CMAttitudeReferenceFrame)referenceFrame NS_AVAILABLE(NA,5_0);
378
379/*
380 *  startDeviceMotionUpdatesUsingReferenceFrame:toQueue:withHandler
381 * 
382 *  Discussion:
383 *                      Starts device motion updates, providing data to the given handler through the given queue.
384 *                      The specified frame will be used as reference for the attitude estimates.
385 *
386 */
387- (void)startDeviceMotionUpdatesUsingReferenceFrame:(CMAttitudeReferenceFrame)referenceFrame toQueue:(NSOperationQueue *)queue withHandler:(CMDeviceMotionHandler)handler NS_AVAILABLE(NA,5_0);
388
389/*
390 *  stopDeviceMotionUpdates
391 * 
392 *  Discussion:
393 *                      Stops device motion updates.
394 */
395- (void)stopDeviceMotionUpdates;
396
397/*
398 *  showsDeviceMovementDisplay
399 * 
400 *  Discussion:
401 *      When the device requires movement, showsDeviceMovementDisplay indicates if the system device
402 *          movement display should be shown. Note that when device requires movement,
403 *          CMErrorDeviceRequiresMovement is reported once via CMDeviceMotionHandler. By default,
404 *          showsDeviceMovementDisplay is NO.
405 */
406@property(assign, nonatomic) BOOL showsDeviceMovementDisplay NS_AVAILABLE(NA,5_0);
407
408@end
Note: See TracBrowser for help on using the repository browser.