|
Snapdragon® Telematics Application Framework (TelAF) Interface Specification
|
This API provides access to the device's physical position and movement information.
The functions of this API are provided by the tafLocationSvc application service.
The following example illustrates how to bind to the positioning service.
bindings:
{
clientExe.clientComponent.taf_locPos -> tafLocationSvc.taf_locPos
}
The taf_locPos_Get2DLocation() function gets the last updated latitude, longitude, and the horizontal accuracy values:
int32_t latitude;
int32_t longitude;
int32_t hAccuracy;
if (taf_locPos_Get2DLocation(&latitude, &longitude, &hAccuracy) == LE_OK)
{
// Process after succesfully getting the 2 dimension location information.
}
For example, the latitude and longitude are given in degrees with 6 decimal places like
The taf_locPos_Get3DLocation() function gets the last updated latitude, longitude, altitude, and their associated accuracy values.
int32_t latitude;
int32_t longitude;
int32_t hAccuracy;
int32_t altitude;
int32_t vAccuracy;
if (taf_locPos_Get3DLocation(&latitude, &longitude, &hAccuracy,&altitude, &vAccuracy) == LE_OK)
{
// Process after succesfully getting the 3 dimensional location information.
}
The taf_locPos_GetTime() function gets the time of last updated position.
uint16_t hrsPtr;
uint16_t minPtr;
uint16_t secPtr;
uint16_t msecondsPtr;
if (taf_locPos_GetTime(&hrsPtr, &minPtr, &secPtr,&msecondsPtr) == LE_OK)
{
// Process after succesfully getting the time information.
}
The taf_locPos_GetDate() function gets the date of last updated position.
uint16_t yearPtr;
uint16_t monthPtr;
uint16_t dayPtr;
if (taf_locPos_GetDate(&yearPtr, &monthPtr, &dayPtr) == LE_OK)
{
// Process after succesfully getting the date information.
}
The taf_locPos_GetDirection() function gets the last updated direction value in degrees and its associated accuracy value.
uint32_t direction;
uint32_t directionAccuracy;
if (taf_locPos_GetDirection(&direction, &directionAccuracy) == LE_OK)
{
// Process after succesfully getting the direction information.
}
The taf_locPos_GetMotion() function gets motion's data (horizontal speed and accuracy; verticial speed and accuracy).
uint32_t hSpeed, hAccuracy;
int32_t vSpeed, vAccuracy;
if (taf_locPos_GetMotion(&hSpeed, &hAccuracy, &vSpeed, &vAccuracy)) == LE_OK)
{
// Process after succesfully getting the Motion data.
}
The taf_locPos_GetFixState() function gets the position fix state. The fix state allows the user to determine if it is a 2-dimensional or a 3-dimensional position fix.
taf_locPos_FixState_t fixState;
if(taf_locPos_GetFixState(&fixState)== LE_OK)
{
// Process after succesfully getting the fix state.
}
The taf_locPos_SetDistanceResolution() function sets the resolution for the positioning distance values.
if(taf_locPos_SetDistanceResolution(RES_DECIMETER) == LE_OK))
{
// Process after succesfully setting the distance resolution.
}
To be notified when the device is in motion, you must register a handler function to get the new position data. The taf_locPos_AddMovementHandler() API registers that handler. The horizontal and vertical change is measured in meters so only movement over the threshhold triggers notification (0 means not to notify about changes).
static void NavigationHandler
(
taf_locPos_SampleRef_t positionSampleRef,
void* contextPtr
)
{
int32_t latitude, longitude, horizontalAccuracy;
LE_ASSERT_OK(taf_locPos_sample_Get2DLocation(positionSampleRef, &latitude,
&longitude, &horizontalAccuracy));
taf_locPos_sample_Release(positionSampleRef);
}
static taf_locPos_MovementHandlerRef_t navigationHandlerRef;
navigationHandlerRef = taf_locPos_AddMovementHandler(0, 0, NavigationHandler, NULL);
LE_ASSERT(NULL != navigationHandlerRef);
taf_locPos_RemoveMovementHandler(navigationHandlerRef);
The handler gives a reference to the position sample object that triggered the notification. You can then access parameters using accessor functions and release the object when done with it.
The accessor functions are:
int32_t longi, lat, haccuracy;
if(taf_locPos_sample_Get2DLocation(positionSampleRef, &longi, &lat, &haccuracy) == LE_OK)
{
// Process after succesfully getting the 2 dimensional location information.
}
int32_t hours, min, sec;
if(taf_locPos_sample_GetTime(positionSampleRef, &hours, &min, &sec) == LE_OK)
{
// Process after succesfully getting the time information.
}
int32_t year, month, day;
if(taf_locPos_sample_GetDate(positionSampleRef, &year, &month, &day) == LE_OK)
{
// Process after succesfully getting the time information.
}
int32_t altitude,altitudeAccuracy,
if(taf_locPos_sample_GetAltitude(positionSampleRef, &altitude, &altitudeAccuracy) == LE_OK)
{
// Process after succesfully getting the altitude information.
}
int32_t hSpeed,hSpeedAccuracy,
if(taf_locPos_sample_GetHorizontalSpeed(positionSampleRef, &hSpeed, &hSpeedAccuracy) == LE_OK)
{
// Process after succesfully getting the horizontal speed information.
}
int32_t vSpeed,vSpeedAccuracy,
if(taf_locPos_sample_GetVerticalSpeed(positionSampleRef, &vSpeed, &vSpeedAccuracy) == LE_OK)
{
// Process after succesfully getting the vertifical speed information.
}
int32_t direction,directionAccuracy,
if(taf_locPos_sample_GetDirection(positionSampleRef, &direction, &directionAccuracy) == LE_OK)
{
// Process after succesfully getting the direction information.
}
taf_locPos_FixState_t fixState;
if(taf_locPos_sample_GetFixState(&fixState)== LE_OK)
{
// Process after succesfully getting the fix state.
}
taf_locPos_sample_Release() releases the object.
You can remove the handler function by calling the taf_locPos_RemoveMovementHandler() API.
The acquisition rate value can be set or with taf_locPos_SetAcquisitionRate() and retrieved with taf_locPos_GetAcquisitionRate(). It is also set when calling taf_locPos_AddMovementHandler(). The acquisition rate is calculated from the horizontal and vertical magnitude parameters set in this function. This calculated acquisition rate can be retrieved by calling taf_locPos_GetAcquisitionRate().
if(taf_locPos_SetAcquisitionRate(3000) == LE_OK)
{
// Process after succesfully setting the acquisition rate.
}
uint32_t acquisitionRate=0;
if(taf_locPos_GetAcquisitionRate(&fixState)== LE_OK)
{
// Process after succesfully getting the acquisition rate.
}