Compass API (old draft. for new, see API reference)

/******************** Compass Specific Routines ***********************/

/*
Here are the most common use cases that I envision:

1. Tell me what my current heading is.
2. Tell me when my heading changes.
3. Tell me when my heading changes, but I only want to be notified every x seconds.
4. Tell me when my heading changes more than y degrees.

Use case #4 really only seems to be an alternate method of setting the reporting granularity, the other method being #3.
*/

/**
* The range of orientation values (and thus basis and trigger values)
* is from 0 to 360, with 0 meaning that the host device is pointing due north,
* 90 meaning that the device is pointing due east, 180 meaning that the host
* device is pointing due south, and 270 meaning the device is pointing due west.
* More precisely, orientation, basis, and trigger values must be greater than
* or equal to 0, and less than 360.
**/

/**
* SFCompassEventCallback:
* @self: A #SFCompass object
* @old: The last orientation
* @new: The current orientation
* @userdata: userdata set in sf_compass_connect_*_func ()
*
* Prototype of callback of COMPASS events
*
*
* The last orientation will be automatically set to @new after the callback invokes.
*
*
*
* typedef struct {
* gfloat orientation; //degrees from true north. 90=east; 270=west; etc.
* gfloat declination; //the angle in degrees between the local magnetic field and true north.
//Negative values indicate that magnetic north lies counterclockwise
//from true north. A value of 0 indicates either that the host device
//lies on an agonic line (magnetic north == true north). A value
//less than -180 indicates that the declination value is invalid
// because no geolocation coordinates were provided.
* } SFOrientation;
*/

/**
* sf_compass_new::
* @ctm: A #SFCustomer object created by sf_new()
* @err: A return location for a #GError, or %NULL
*
* Create a new #SFCompass object.
*
* Returns: A #SFCompass object. NULL indicates an error
*/
SFCompass* sf_compass_new (SFCustomer* ctm, GError** err);

/**
* sf_compass_destroy:
* @self: A #SFCompass object created by sf_compass_new()
*
* Destroy a #SFCompass object. All events or parameters configured
* are stale after this call. You may call sf_compass_new() to re-create
* a new object to re-request services.
*
* NOTE: You may directly use g_object_unref()
*/
void sf_compass_destroy (SFCompass* self);

/**
* sf_compass_set_changing_parameters:
* @self: A #SFCompass object
* @threshold: the reporting threshold, in degrees. The event will be fired
* only when abs( current orientation - previous orientation ) > threshold.
* If *threshold* is zero, the *callback* set in sf_compass_connect_change_func()
* will be called every time orientation is sampled.
* @period: sample interval, in milliseconds. The *callback* set in
* sf_compass_connect_change_func will be called if *threshold* has been
* crossed. If zero, orientation will be sampled at the default interval
* of 500 milliseconds.
*/
void sf_compass_set_changing_parameters (SFCompass* self,
gfloat threshold,
gulong period);

/**
* sf_compass_connect_change_func:
* @self: A #SFCompass object
* @callback: A #GCallback converted by macro G_CALLBACK(). The native prototype
* should be SFCompassEventCallback
* @userdata: Data to pass to callback calls
*
* Connect a callback to orientation changing event. You may directly use
* g_signal_connect() to do same thing.
*
* compass = sf_compass_new ();
* g_signal_connect (compass, "compass-heading-change", G_CALLBACK (your_func),
* your_userdata);
*
* NOTE: Before this routine, you should call sf_compass_set_changing_parameters() to set up gate.
*
* NOTE: The event will be fired when the device orientation varies either direction
* by at least the amount specified in *threshold*. The current orientation
* value is reported in the orientation parameter of *callback*, and will be used
* as the basis for subsequent event firings.
*
* Returns: A handler ID
*/
gulong sf_compass_connect_change_func (SFCompass* self, GCallback callback, gpointer userdata);

/**
* sf_compass_disconnect_func:
* @self: A #SFCompass object
* @handler_id: handler_id returned by sf_compass_connect_change_func()
*
* Disconnect callback from Compass event.
*
* NOTE: This is just a helper function of g_signal_handler_disconnect()
*/
void sf_compass_disconnect_func (SFCompass* self, gulong handler_id);

/**
* sf_compass_set_location:
* @self: A #SFCompass object
* @location: an #SFCompassLocation struct that allows the compass to provide more
* accurate orientation information.
*
* typedef struct {
* gfloat latitude, //degrees. positive is east
* gfloat longitude, // degrees. positive is north
* gfloat altitude // meters above mean sea level
* } SFCompassLocation;
*
* Because the earth's magnetic field can vary by geolocation, heading
* calculations can be skewed by up to 40 degrees. With geolocation data,
* the sensor framework can calculate the difference between magnetic north
* and true north, sometimes referred to as magnetic declination.
* SFCompasPosition values will used by the underlying
* compass sensor to obtain a more accurate heading. In many cases,
* this kind of precision is not necessary. If this function is not called
* the orientation calculations will assume that true north == magnetic north,
* and the declination value will be zero.
*
* Once this function is called with a valid location, the sensor framework
* will continue to use the location value until either
*
* 1. a new SFCompasPosition is provided by calling this function again, or
* 2. the sensor frameork is reset in which case the compass location is
* unknown.
*
* NOTE: the geolocation data provided by calling this function will be used
* to determine orientation values that are returned by
* sf_compass_get_orientation ()
* and passed as the orientation parameter of *callback*.
*
* Returns: 0 indicates success; -1 means invaid parameter or commucation
* failed with sensor daemon
**/
gint sf_compass_set_location (SFCompass* self, SFCompassLocation location);

/**
* sf_compass_get_orientation:
* @self: A #SFCompass object
*
* Get the current orientation of the host device
*
* Returns: Current orientation of the host device.
*
* The range of the return value is
* is 0 to 360, with 0 meaning that the host device is pointing due north,
* 90 meaning that the device is pointing due east, 180 meaning that the host
* device is pointing due south, 270 meaning the host is pointing due west, etc.
* More precisely, the return values will be greater than
* or equal to 0 and less than 360.
*
* NOTE: if sf_compass_set_location has been called with a valid SFPosition
* struct prior to this call, geolocation data will be used to increase
* accuracy, and the SFOrientation.declination value will be valid.
* If sf_compass_set_location has not been called, it is assumed that
* magnetic north == true north, and SFOrientation.declination will have a
* value less than -180.
*/
SFOrientation sf_compass_get_orientation (SFCompass* self);