CLHeading Class

CLHeading Class ReferenceData Management: Device Information

2010-05-11

Apple Inc.© 2010 Apple Inc.All rights reserved.

No part of this publication may be reproduced,stored in a retrieval system, or transmitted, inany form or by any means, mechanical,electronic, photocopying, recording, orotherwise, without prior written permission ofApple Inc., with the following exceptions: Anyperson is hereby authorized to storedocumentation on a single computer forpersonal use only and to print copies ofdocumentation for personal use provided thatthe documentation contains Apple’s copyrightnotice.

The Apple logo is a trademark of Apple Inc.

No licenses, express or implied, are grantedwith respect to any of the technology describedin this document. Apple retains all intellectualproperty rights associated with the technologydescribed in this document. This document isintended to assist application developers todevelop applications only for Apple-labeledcomputers.

Apple Inc.1 Infinite LoopCupertino, CA 95014408-996-1010

Apple, the Apple logo, and Objective-C aretrademarks of Apple Inc., registered in theUnited States and other countries.

IOS is a trademark or registered trademark ofCisco in the U.S. and other countries and is usedunder license.

Even though Apple has reviewed this document,APPLE MAKES NO WARRANTY OR REPRESENTATION,EITHER EXPRESS OR IMPLIED, WITH RESPECT TOTHIS DOCUMENT, ITS QUALITY, ACCURACY,MERCHANTABILITY, OR FITNESS FOR A PARTICULARPURPOSE. AS A RESULT, THIS DOCUMENT ISPROVIDED “AS IS,” AND YOU, THE READER, AREASSUMING THE ENTIRE RISK AS TO ITS QUALITYAND ACCURACY.

IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT,INDIRECT, SPECIAL, INCIDENTAL, ORCONSEQUENTIAL DAMAGES RESULTING FROM ANYDEFECT OR INACCURACY IN THIS DOCUMENT, evenif advised of the possibility of such damages.

THE WARRANTY AND REMEDIES SET FORTH ABOVEARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORALOR WRITTEN, EXPRESS OR IMPLIED. No Appledealer, agent, or employee is authorized to makeany modification, extension, or addition to thiswarranty.

Some states do not allow the exclusion or limitationof implied warranties or liability for incidental orconsequential damages, so the above limitation orexclusion may not apply to you. This warranty gives

you specific legal rights, and you may also haveother rights which vary from state to state.

Contents

CLHeading Class Reference 5

Overview 5Tasks 5

Accessing the Heading Attributes 5Accessing the Raw Heading Data 6

Properties 6headingAccuracy 6magneticHeading 6timestamp 7trueHeading 7x 8y 8z 9

Instance Methods 9description 9

Constants 9CLHeadingComponentValue 9

Document Revision History 11

32010-05-11 | © 2010 Apple Inc. All Rights Reserved.


CONTENTS

Inherits from NSObject

Conforms to NSCodingNSCopyingNSObject (NSObject)

Availability Available in iOS 3.0 and later.

Declared in CLHeading.h

Related sample code Teslameter

Overview

A CLHeading object contains heading data generated by a CLLocationManager object. The heading dataconsists of computed values for true and magnetic north. It also includes the raw data for the three-dimensionalvector used to compute those values.

Typically, you do not create instances of this class yourself, nor do you subclass it. Instead, you receiveinstances of this class through the delegate assigned to the CLLocationManager object whosestartUpdatingHeading method you called.

Note: If you want heading objects to contain valid data for the trueHeading (page 7) property, yourlocation manager object should also be configured to deliver location updates. You can start the delivery ofthese updates by calling the location manager object’s startUpdatingLocation method.

Tasks

Accessing the Heading Attributes

magneticHeading (page 6) propertyThe heading (measured in degrees) relative to magnetic north. (read-only)

trueHeading (page 7) propertyThe heading (measured in degrees) relative to true north. (read-only)

Overview 52010-05-11 | © 2010 Apple Inc. All Rights Reserved.

CLHeading Class Reference

headingAccuracy (page 6) propertyThe maximum deviation (measured in degrees) between the reported heading and the truegeomagnetic heading. (read-only)

timestamp (page 7) propertyThe time at which this heading was determined. (read-only)

– description (page 9)Returns the heading data in a formatted text string.

Accessing the Raw Heading Data

x (page 8) propertyThe geomagnetic data (measured in microteslas) for the x-axis. (read-only)

y (page 8) propertyThe geomagnetic data (measured in microteslas) for the y-axis. (read-only)

z (page 9) propertyThe geomagnetic data (measured in microteslas) for the z-axis. (read-only)

Properties

For more about Objective-C properties, see “Properties” in The Objective-C Programming Language.

headingAccuracyThe maximum deviation (measured in degrees) between the reported heading and the true geomagneticheading. (read-only)

@property(readonly, nonatomic) CLLocationDirection headingAccuracy

DiscussionA positive value in this property represents the potential error between the value reported by themagneticHeading (page 6) property and the actual direction of magnetic north. Thus, the lower the valueof this property, the more accurate the heading. A negative value means that the reported heading is invalid,which can occur when the device is uncalibrated or there is strong interference from local magnetic fields.

AvailabilityAvailable in iOS 3.0 and later.

Declared InCLHeading.h

magneticHeadingThe heading (measured in degrees) relative to magnetic north. (read-only)

6 Properties2010-05-11 | © 2010 Apple Inc. All Rights Reserved.


@property(readonly, nonatomic) CLLocationDirection magneticHeading

DiscussionThe value in this property represents the heading relative to the magnetic North Pole, which is different fromthe geographic North Pole. The value 0 means the device is pointed toward magnetic north, 90 means it ispointed east, 180 means it is pointed south, and so on. The value in this property should always be valid.

In iOS 3.x and earlier, the value in this property is always measured relative to the top of the device in aportrait orientation, regardless of the device’s actual physical or interface orientation. In iOS 4.0 and later,the value is measured relative to the heading orientation specified by the location manager. For moreinformation, see the headingOrientation property in CLLocationManager Class Reference.

If the headingAccuracy property contains a negative value, the value in this property should be consideredunreliable.


See Also @property headingAccuracy (page 6) @property trueHeading (page 7)


timestampThe time at which this heading was determined. (read-only)

@property(readonly, nonatomic) NSDate *timestamp



trueHeadingThe heading (measured in degrees) relative to true north. (read-only)

@property(readonly, nonatomic) CLLocationDirection trueHeading

DiscussionThe value in this property represents the heading relative to the geographic North Pole. The value 0 meansthe device is pointed toward true north, 90 means it is pointed due east, 180 means it is pointed due south,and so on. A negative value indicates that the heading could not be determined.

In iOS 3.x and earlier, the value in this property is always measured relative to the top of the device in aportrait orientation, regardless of the device’s actual physical or interface orientation. In iOS 4.0 and later,the value is measured relative to the heading orientation specified by the location manager. For moreinformation, see the headingOrientation property in CLLocationManager Class Reference.

Properties 72010-05-11 | © 2010 Apple Inc. All Rights Reserved.


Important: This property contains a valid value only if location updates are also enabled for the correspondinglocation manager object. Because the position of true north is different from the position of magnetic northon the Earth’s surface, Core Location needs the current location of the device to compute the value of thisproperty.


See Also @property magneticHeading (page 6)


xThe geomagnetic data (measured in microteslas) for the x-axis. (read-only)

@property(readonly, nonatomic) CLHeadingComponentValue x

DiscussionThe value reported by this property is normalized to the range -128 to +128. This value represents the x-axisdeviation from the magnetic field lines being tracked by the device.


Related Sample CodeTeslameter


yThe geomagnetic data (measured in microteslas) for the y-axis. (read-only)

@property(readonly, nonatomic) CLHeadingComponentValue y

DiscussionThe value reported by this property is normalized to the range -128 to +128. This value represents the y-axisdeviation from the magnetic field lines being tracked by the device.




8 Properties2010-05-11 | © 2010 Apple Inc. All Rights Reserved.


zThe geomagnetic data (measured in microteslas) for the z-axis. (read-only)

@property(readonly, nonatomic) CLHeadingComponentValue z

DiscussionThe value reported by this property is normalized to the range -128 to +128. This value represents the z-axisdeviation from the magnetic field lines being tracked by the device.




Instance Methods

descriptionReturns the heading data in a formatted text string.

- (NSString *)description

Return ValueA string of the form “magneticHeading <magnetic> trueHeading <heading> accuracy <accuracy> x <x> y<y> z <z> @ <date-time>” where <magnetic>, <heading>, <accuracy>, <x>, <y>, and <z> are formattedfloating-point numbers and <date-time> is a formatted date string that includes date, time, and time zoneinformation.



Constants

CLHeadingComponentValueA type used to report magnetic differences reported by the onboard hardware.

typedef double CLHeadingComponentValue;


Instance Methods 92010-05-11 | © 2010 Apple Inc. All Rights Reserved.



10 Constants2010-05-11 | © 2010 Apple Inc. All Rights Reserved.


This table describes the changes to CLHeading Class Reference.

NotesDate

Updated the class overview to reflect changes in iOS 4.0.2010-05-11

New document that describes heading information for a device.2009-05-12


REVISION HISTORY

Document Revision History


REVISION HISTORY

Document Revision History

Documents

CLHeading Class