Resources | developer.brewmp.com Resources | developer.brewmp.com

Developer

resources

Using interfaces for Brew MP 1.0.3 and higher

This section discusses how to use the newer position determination interfaces introduced in Brew MP 1.0.3 and higher.

Invoking a position fix using pd_IPosition

pd_IPosition can request a position fix by following this process:

  1. The application registers for a signal using pd_IPosition_OnPositionEvent().
  2. Configure the GPS engine using pd_IPosition_SetFixCriteria().
  3. The application makes a position fix request using pd_IPosition_RequestPosition().
  4. On receiving the signal, the application get the position information using pd_IPosition_GetPositionInfo().

Using pd_IPosition_RequestPosition(), you can request a position fix without configuring the GPS engine, in which case, the default configuration is used.

Step 1: Register to receive position events

To register to receive position events, create a signal and then call pd_IPosition_OnPositionEvent(), passing in that signal.

Step 2: Configuring the GPS engine

When using the pd_IPosition interface, optionally configure the position determination engine based on the needs of the application by calling pd_IPosition_SetFixCriteria() to set the parameters of the pd_FixCriteriaType data structure.

AEEResult pd_IPosition_SetFixCriteria(

   pd_IPosition* pif,

   pd_FixCriteriaType* fixCriteria 

   );
See the C/C++ API Reference on the Brew MP website for more information on the pd_IPosition_SetFixCriteria() return codes.

These are the parameters in the pd_FixCriteriaType data structure:

  • validMask
  • recurrenceType
  • preferredOperationMode
  • preferredAccuracy
  • preferredResponseTime
  • minInterval

See pd_FixCriteriaType documentation in the pd_Def.h file for more information.

Step 3: Requesting a position fix

Applications can use pd_IPosition_RequestPosition() to make a position request and will receive a signal notification registered through pd_IPosition_OnPositionEvent(). The application should then use pd_IPosition_GetPositionInfo() to retrieve the pd_PositionInfo structure and check for the status. If the status parameter is pd_SESS_STATUS_IN_PROGRESS, the application should reenable the signal until it gets pd_SESS_STATUS_SUCCESS or any failure status.

To determine the validity of information received for a specific field, applications can filter it using the appropriate mask. For example, to verify the validity of the latitude information:

 pd_PositionInfo posInfo;
posInfo.dwFlags & pd_VALID_LAT	 

Step 4: Processing the result

The response to the fix request triggers the callback function associated with the signal registered through pd_IPosition_OnPositionEvent(). If the status is pd_SESS_STATUS_SUCCESS, the request is successful. Otherwise, the request returns an error code.

A status of pd_SESS_STATUS_IN_PROGRESS is an intermediate position report. The application should re-enable the signal if necessary and wait for the final position report (that is, when the operation returns a status of pd_SESS_STATUS_SUCCESS).

See the C/C++ API Reference on the Brew MP website for more information.