AppGeoLocation Method (CLIENT)

PLB Web Only, 9.9

The AppGeoLocation method provides information about a mobile device's location such as latitude and longitude. The method uses the following format:

Where:

label

Optional. A Program Execution Label.

object

Required. A CLIENT object.

return

Optional. A Numeric Variable that returns the success or failure of the method.

type

Required. A Numeric Variable or decimal number that specifies the type of location information to be retrieved.

options

Optional. A Character String Variable or string literal that specifies a JSON object string that is passed directly to the Cordova routine to customize the retrieval of the geolocation position.

Flags Affected: OVER, ZERO

Note the following:

1. This method is only used for a Sunbelt PL/B Web Client App using Cordova\PhoneGap operations. See the following link for details on the Cordova plugin used:

 

     https://www.npmjs.com/package/cordova-plugin-geolocation

 

2. The ZERO flag is set when the {return} value is zero.

3. The OVER flag is set if the value returned is too large to be stored into the {return} variable.

4. The supported {type} values are defined as follows:

 

Value	Type	This Type
0	AppGeoGetLocation	returns a result using the PLB AppEventLocation event with the event data being returned in ARG1 in JSON notation.
1	AppGeoWatchLocation	returns the device's current position when a change in position is detected. The result event and {options} parameter are the same as described for the AppGeoGetLocation type.
2	AppGeoClearWatch	will cancel any previously setup AppGeoWatchLocation.

 

5. The {options} parameter is passed directly as a JSON object to the Cordova routine to customize the retrieval of the geolocation position. The {options} JSON object fields are defined as follows for the AppGeoGetLocation and AppGeoWatchLocation types

 

Field	Description
enableHighAccuracy	Provides a hint that the application needs the best possible results. By default, the device attempts to retrieve a `Position` using network-based methods. Setting this property to `true` tells the framework to use more accurate methods, such as satellite positioning.
timeout	The maximum length of time (milliseconds) that is allowed to pass from the call until the corresponding event.
maximumAge	Accept a cached position whose age is no greater than the specified time in milliseconds.

 

6. This method starts an asynchronous operation on the mobile device which returns the result using the 'AppEventLocation' CLIENT object event where the event data is returned in ARG1 which contains a JSON notation stream.

 

The event number used in EVENTREG is:

 

AppEventLocation EQU 115 //Event number for EVENTREG.

 

The event result is defined as follows:

 

The event data returned by this method can be either a JSON Error object string or a JSON Position object string found in the PLB Event ARG1 parameter.

 

JSON Error Object Event Data fields are defined as follows:

 

Field	Description
code	One of the pre-defined error codes listed below:   PERMISSION_DENIED EQU 1 Returned when users do not allow the app to retrieve position information.   POSITION_UNAVAILABLE EQU 2 Returned when the device is unable to retrieve a position. In general, this means the device is not connected to a network or can't get a satellite fix.   TIMEOUT EQU 3 Returned when the device is unable to retrieve a position within the time specified by 'the timeout` included in the Options parameter.
message	Error message.

 

Position JSON Object Event Data fields are defined as follows:

 

Field	Description
latitude	Latitude in decimal degrees.
longitude	Longitude in decimal degrees.
altitude	Height of the position in meters above the ellipsoid.
accuracy	Accuracy level of the latitude and longitude coordinates in meters.
altitudeAccuracy	Accuracy level of the altitude coordinate in meters.
heading	Direction of travel, specified in degrees counting clockwise relative to the true north.
speed	Current ground speed of the device, specified in meters per second.
timestamp	Creation timestamp.

Sample Code

FileLoc DIM 250

Opt INIT "{ #"maximumAge#": 3000, #"timeout#": 5000,":

             " #"enableHighAccuracy#": true }"

.

        EventReg Client,AppEventLocation,GeoEvent,ARG1=FileLoc

.

        Client.AppGeoLocation Using *Type=AppGeoGetLocation,*Options=Opt

See Also: CLIENT, Client Methods, Method Syntax