com.motorola.iden.position
Interface PositionConnection

public interface PositionConnection

This interface supports creation of a connection to a position source that allows applications to obtain position information. An object of this type is obtained through generic connector as Connector.open("mposition:parameters"). Only one connection is allowed at a time. The API must be called from separate thread. Only one request of getPosition() can be made and pending at a time. If an application makes multiple requests without getting response from the previous request null position will be returned. Application should handle all the status code before checking position's response code and using it. The MIDlet must use the generic Connector class to create PositionConnection. Example com.motorola.iden.PositionConnection sc = (com.motorola.iden.PositionConnection)Connector.open(String name); String name should be one of the following: name = "mposition:delay=no" name = "mposition:delay=low" name = "mposition:delay=high"

MOTOROLA and the Stylized M Logo are registered trademarks of Motorola, Inc. Reg. U.S. Pat. & Tm. Off.
?Copyright 2002 Motorola, Inc. All Rights Reserved.

Field Summary

static int	POSITION_NO_RESPONSE This constant indicates that the device is not responding.
static int	POSITION_RESPONSE_ERROR This constant indicates that an error occurred while retrieving the position.
static int	POSITION_RESPONSE_NO_ALMANAC_OVERRIDE This constant indicates that the Almanac is outdated, and the user is restricted to override.
static int	POSITION_RESPONSE_OK This constant indicates that the obtained position is a valid position.
static int	POSITION_RESPONSE_RESTRICTED This constant indicates that the user has set the device to not provide the position information.
static int	POSITION_WAITING_RESPONSE This constant indicates that the API is waiting for a response from the position device.

Method Summary

java.lang.String	getNMEASentence(int type) A method for API to get nmea sentences
AggregatePosition	getPosition() A method for applications to obtain the position with same delay value of Connector.open(String parameter).
AggregatePosition	getPosition(java.lang.String name) A method for applications to obtain a new position with appropriate delay type.
int	getStatus() A method returning the status of the underlying position device.
boolean	requestPending() A method returning the request pending flag of the device.
void	stopNMEASentence() A method for API to stop nmea messages

Field Detail

POSITION_RESPONSE_OK

public static final int POSITION_RESPONSE_OK

This constant indicates that the obtained position is a valid position. All position's attributes will be available.

POSITION_WAITING_RESPONSE

public static final int POSITION_WAITING_RESPONSE

This constant indicates that the API is waiting for a response from the position device. POSITION_WAITING_RESPONSE will be returned if getStatus() method is called before getPostion() method returns.

POSITION_NO_RESPONSE

public static final int POSITION_NO_RESPONSE

This constant indicates that the device is not responding. No position information will be available, and all the attributes of the position will be set to UNAVAILABLE.

POSITION_RESPONSE_ERROR

public static final int POSITION_RESPONSE_ERROR

This constant indicates that an error occurred while retrieving the position. If possible, the cell latitude and longitude will be available, but all position's attributes will be set to UNAVAILABLE.

POSITION_RESPONSE_RESTRICTED

public static final int POSITION_RESPONSE_RESTRICTED

This constant indicates that the user has set the device to not provide the position information. No position information will be available, and the position's attributes will be set to UNAVAILABLE

POSITION_RESPONSE_NO_ALMANAC_OVERRIDE

public static final int POSITION_RESPONSE_NO_ALMANAC_OVERRIDE

This constant indicates that the Almanac is outdated, and the user is restricted to override. No position information will be available, and all the attributes of the position will be set to UNAVAILABLE.

Method Detail

getStatus

public int getStatus()

A method returning the status of the underlying position device. This status is updated after each getPosition() method call which could be invoked by this application or other applications. This method does not block.

Returns:

an integer that indicates the current status.
POSITION_RESPONSE_OK
POSITION_WAITING_RESPONSE
POSITION_NO_RESPONSE
POSITION_RESPONSE_ERROR
POSITION_RESPONSE_RESTRICTED
POSITION_RESPONSE_NO_ALMANAC_OVERRIDE

getPosition

public AggregatePosition getPosition()

A method for applications to obtain the position with same delay value of Connector.open(String parameter). If the API has been called first time and GPS privacy setting is set to "by permission" or Application privacy setting is set to "Ask" application will be suspended for user permission. If the Almanac is out of date user will be prompted for permission to override it only once if user has not been asked before. User's response can be checked via getStatus() method.

Returns:

AggregatePosition if no error occurs, and null otherwise.

getPosition

public AggregatePosition getPosition(java.lang.String name)

A method for applications to obtain a new position with appropriate delay type. Possible delay type is "delay=no" or "delay=low" or "delay=high" or "delay=low;fix=extended" or "delay=high;fix=extended"
Using the "fix=extended" tag, will return accurate velocity and heading direction; however there is a time penalty since it takes longer to calculate velocity and heading direction.
If the API has been called first time and GPS privacy setting is set to "by permission" or Application privacy setting is set to "Ask" application will be suspended for user permission. If the Almanac is out of date user will be prompted for permission to override it only once if user has not been asked before. User's response can be checked via getStatus() method.

Parameters:

name - a position connection property.

Returns:

AggregatePosition if no error occurs, and null otherwise.

requestPending

public boolean requestPending()

A method returning the request pending flag of the device.

Returns:

an boolean true if request is pending.

getNMEASentence

public java.lang.String getNMEASentence(int type)
                                 throws java.lang.IllegalArgumentException

A method for API to get nmea sentences

Parameters:

type - of message

stopNMEASentence

public void stopNMEASentence()

A method for API to stop nmea messages

Parameters:

none -