GPS

eon_mobile_geolocationex object

Opens the GPS functionality and gets the current position. You would need to make sure GPS is enabled on the mobile device, and there is good network connection.

Usage example

Express & delivery services:

Track the detailed parcel delivery progress: the time and place of departure, the real-time positioning of the delivery men, passage and arrival, etc.
Geomarketing:

The online advertising can use this type of marketing, relying on IP addresses to locate the user logged into the Website, and then customizing advertising based on this information.
Public transportation:

If a user doesn't know the best way to get to somewhere, the user can use the GPS API to find out nearby bus stops and metro locations.
Tourism:

By combining with Map API, travel agencies can provide better vacation tips for the current location and season.

eon_mobile_geolocationex object

Properties
Events
Functions
Structures
Code Example

Properties

integer ii_errorcode
powerobject ipo_bindevent
string is_bindwitherrorevent
string is_bindwithlocationchangedevent
string is_errortext

integer ii_errorcode

Error code which is returned when the oe_error event is triggered.

10 - kCLErrorLocationUnknown. Location is currently unknown, but CL will keep trying.

11 - kCLErrorDenied. CL access has been denied (eg, user declined location use).

12 - kCLErrorNetwork. General network-related error.

13 - kCLErrorHeadingFailure. Heading could not be determined.

14 - kCLErrorRegionMonitoringDenied. Location region monitoring has been denied by the user.

15 - kCLErrorRegionMonitoringFailure. A registered region cannot be monitored.

16 - kCLErrorRegionMonitoringSetupDelayed. CL could not immediately initialize region monitoring.

17 - kCLErrorRegionMonitoringResponseDelayed. While events for this fence will be delivered, delivery will not occur immediately.

18 - kCLErrorGeocodeFoundNoResult. A geocode request yielded no result.

19 - kCLErrorGeocodeFoundPartialResult. A geocode request yielded a partial result.

20 - kCLErrorGeocodeCanceled. A geocode request was cancelled.

21 - kCLErrorDeferredFailed. Deferred mode failed.

22 - kCLErrorDeferredNotUpdatingLocation. Deferred mode failed because location updates disabled or paused.

23 - kCLErrorDeferredAccuracyTooLow. Deferred mode not supported for the requested accuracy.

24 - kCLErrorDeferredDistanceFiltered. Deferred mode does not support distance filters.

25 - kCLErrorDeferredCanceled. Deferred mode request canceled a previous request.

powerobject ipo_bindevent

The object to bind with the oe_locationchanged event and oe_error event.

string is_bindwitherrorevent

The name of the event bound with the oe_error event of the powerobject ipo_bindevent.

string is_bindwithlocationchangedevent

The name of the event bound with the oe_locationchanged event of the powerobject ipo_bindevent.

string is_errortext

Error message which is returned when the oe_error event is triggered.

Events

oe_error
oe_locationchanged

oe_error

Description

It will be triggered automatically if there is an error when using the GPS functionality.

Supported on mobile client only.

Note: This event will update the value of is_errortext and ii_errorcode properties.

Syntax

None.

Return value

None.

oe_locationchanged

Description

It will be triggered automatically when the position (longitude and/or latitude) changes after getting the GPS information.

Supported on mobile client only.

Note: The user can obtain the new position information by calling the of_getcurrentposition function. WPARAM and LPARAM are both empty.

When the messages for this event in the message queue reaches 500, the new messages for this event will not be stored, they will be directly discarded.

Syntax

oe_locationchanged ( decimal dec_longitude, decimal dec_latitude, decimal dec_altitude, decimal dec_accuracy, decimal dec_altitudeaccuracy, decimal dec_heading, decimal dec_speed, datetime dt_timestamp )

Parameter Name	Parameter Type	Description
`dec_longitude`	Decimal	The longitude value of the current position.
`dec_latitude`	Decimal	The latitude value of the current position.
`dec_altitude`	Decimal	The altitude value of the current position.
`dec_accuracy`	Decimal	The latitude and longitude positioning accuracy.
`dec_altitudeaccuracy`	Decimal	The altitude positioning accuracy.
`dec_heading`	Decimal	The degrees clockwise from true north (0 to 359.99 degrees).
`dec_speed`	Decimal	The displacement velocity (m/sec).
`dt_timestamp`	DateTime	The time stamp to get the current position information.

Return value

None.

Functions

of_close
of_getcurrentposition
of_isenabled
of_open
of_register

of_close

Description

Closes the GPS functionality.

Supported on mobile client only.

Syntax

gps.of_close ( )

Argument Type	Argument	Description
eon_mobile_geolocationex	`gps`	The name of the eon_mobile_geolocationex object.

Return value

Integer.

1 - Success.

-1 - If it is called in PowerBuilder or Appeon Web, or there is an error.

of_getcurrentposition

Description

Gets the current position information. Be sure to call this function separately from the of_open function, otherwise, this function will not work as expected. The best practice is to call this function in a user event which is bound with the oe_locationchanged event, because the oe_locationchanged event will be automatically triggered once the of_open function is finished. The recommended steps are:

Call the of_register function to bind the user event with the oe_locationchanged event.
Call the of_open function.
In the user event that is bound in Step 1, call the of_getcurrentposition function.

Supported on mobile client only.

Syntax

gps.of_getcurrentposition ( ref eon_mobile_str_coordinates astr_coordinates )

Argument Type

Argument

Description

eon_mobile_geolocationex

gps

The name of the eon_mobile_geolocationex object.

eon_mobile_str_coordinates

astr_coordinates

The returned detailed position information.

See variable list of eon_mobile_str_coordinates.

Return value

Integer.

1 - Success.

-1 - If it is called in PowerBuilder or Appeon Web, or there is an error.

Code example

The following code example shows you how to call of_getcurrentposition and of_open functions separately (in different events), in order for of_getcurrentposition to work normally.

//instance variables of w_1 window
   eon_mobile_geolocationex  ignv_aws

//in the constructor event of w_1 window
……
if appeongetclienttype()="MOBILE" then
   ignv_aws = CREATE eon_mobile_geolocationex
      If ignv_aws.of_isenabled() = 1 Then
         ignv_aws.of_open (0, 1)
      Else
         destroy ignv_aws
         messagebox('', 'GPS Disabled')
      End If
end if
……

// in clicked event of cb_1 of w_1 window
……
if isvalid( ignv_aws) then
   ignv_aws.of_getcurrentposition (astr_coordinates)
   ignv_aws.of_close()
   messagebox('Long',astr_coordinates.dec_longitude)
   messagebox('Long',astr_coordinates.dec_latitude)
end if
……

The following code example shows you how to call of_open and of_getcurrentposition in the same event. But this code example only works in the iOS application, not in the Android application.

if appeongetclienttype()="MOBILE" then
   eon_mobile_geolocationex  lgnv_aws
       lgnv_aws = CREATE eon_mobile_geolocationex
       If lgnv_aws.of_isenabled() = 1 Then
              lgnv_aws.of_open (0, 1)
           sleep(1)
              lgnv_aws.of_getcurrentposition (astr_coordinates)
              lgnv_aws.of_close()
              messagebox('Long',astr_coordinates.dec_longitude)
              messagebox('Long',astr_coordinates.dec_latitude)
        Else
              messagebox('', 'GPS Disabled')
        End If
    destroy lgnv_aws
end if

of_isenabled

Description

Detects if the GPS service can be used.

Supported on mobile client only.

Syntax

gps.of_isenabled ( )

Argument Type	Argument	Description
eon_mobile_geolocationex	`gps`	The name of the eon_mobile_geolocationex object.

None.

Return value

Integer

1 - Enabled.

0 - Disabled.

-1 - If it is called in PowerBuilder or Appeon Web, or there is an error.

of_open

Description

Opens the GPS functionality. The execution time of this function relies on the network connection between the mobile device and the GPS satellites. Only after this function is finished, can of_getcurrentposition work normally.

Supported on mobile client only.

Syntax

gps.of_open ( value integer ai_locationaccuracy, value integer ai_distancefilter )

Argument Type

Argument

Description

eon_mobile_geolocationex

gps

The name of the eon_mobile_geolocationex object.

integer

ai_locationaccuracy

Location accuracy update, recommended to use 0 or 1 for the automatic selection.

0 - Use the highest-level of accuracy.

1 - Use the highest possible accuracy and combine it with additional sensor data. This level of accuracy is intended for use in navigation applications that require precise position information at all times and are intended to be used only while the device is plugged in.

>1 - User-defined accuracy (in meters).

integer

ai_distancefilter

Location filter, used to control the location update message frequency (in meters).

0 - Notifies by every update.

>0 - Updates only when the location change exceeds this value.

Return value

Integer.

1 - Success.

-1 - If it is called in PowerBuilder or Appeon Web, or there is an error.

of_register

Description

Binds user-defined events with the oe_error event and the oe_locationchanged event.

After the oe_error event and the oe_locationchanged event are triggered, the bound events will be triggered automatically. The bound events can be utilized to extend the events of the GPS object (which is an NVO object), as NVO object cannot be extended in the PB IDE. If you do not want to extend the events, then you do not need to call the of_register function, as it will be called internally and automatically.

Supported on mobile client only.

Syntax

gps.of_register ( value powerobject apb_bind, value string as_changedevent, value string as_errorevent )

Argument Type	Argument	Description
eon_mobile_geolocationex	`gps`	The name of the eon_mobile_geolocationex object.
powerobject	`apb_bind`	The object to be bound with the oe_error event and oe_locationchanged event.
string	`as_changedevent`	The event to be bound with the oe_locationchanged event. If this parameter is set to null, oe_locationchanged event of the bound object will be triggered; in such case, make sure the bound object has the oe_locationchanged event and the same parameter amount and type.
string	`as_errorevent`	The event to be bound with the oe_error event.

Return value

Integer.

1 - Success.

-1 - If it is called in PowerBuilder or Appeon Web, or there is an error.

Structures

eon_mobile_str_coordinates

eon_mobile_str_coordinates

Description

Struct.

The detailed position information.

Property

Type	Variable Name	Description
decimal{6}	`dec_longitude`	The longitude value of the current position.
decimal{6}	`dec_latitude`	The latitude value of the current position.
decimal{2}	`dec_altitude`	The altitude value of the current position.
decimal{2}	`dec_accuracy`	The latitude and longitude positioning accuracy.
decimal{2}	`dec_altitudeaccuracy`	The altitude positioning accuracy.
decimal{2}	`dec_heading`	The degrees clockwise from true north (0 to 359.99 degrees).
decimal{2}	`dec_speed`	The displacement velocity (m/sec).
datetime	`dt_timestamp`	The time stamp to get the current position information.

Code Example

To get the GPS information of the photo you take:

eon_mobile_cameraex inv_camera
eon_mobile_geolocationex inv_gps

inv_gps = create eon_mobile_geolocationex
inv_camera = create eon_mobile_cameraex

// opens the geolocation function
inv_gps.of_open (3, 0)

// take a photo
li_return = inv_camera.of_takefile (1, false, ls_filepath)

if li_return = 1 then         
…             
    // get current location info for the photo
inv_gps.of_getcurrentposition (istr_coordinates)
…
end if

To mark the movement on the map:

Adds an eon_mobile_mapex object -- uo_map -- to the window.
Declares an instance variable.
```
eon_mobile_geolocationex inv_gps
```

Registers the GPS service with the Open event of the window.

inv_gps = create eon_mobile_geolocationex
eon_mobile_str_mapoption lstr_mapoption

// Sets the default argument of the map
lstr_mapoption.b_allowmove = true
lstr_mapoption.b_allowzoom = true
lstr_mapoption.b_locatetocurrentlocation = true
lstr_mapoption.i_mapaccuracy = 5

// Opens the map
uo_map.of_open (lstr_mapoption)

// The ue_gps event will be triggered when the positioning accuracy is 3
// meters and the location update range is beyond 100 meters.
inv_gps.of_open (3, 100)

// Bind the "ue_gps" event and "ue_gpserror" event of the Window to 
// the "oe_locationchanged" event and "oe_error" event of Geolocation object.
inv_gps.of_register (this, "ue_gps", "ue_gpserror")

Records the movement and adds it as an annotation to the map.

// ue_gps event

eon_mobile_str_coordinates lstr_coordinates
eon_mobile_str_annotation lstr_annotation_appeon

// Get the gps data of the current position
inv_gps.of_getcurrentposition (lstr_coordinates)

// Displays the latitude and longitude of the position in the static text
st_latitude.text = string (lstr_coordinates.dec_latitude)
st_longitude.text = string (lstr_coordinates.dec_longitude)

// Records the gps information of the current position to an annotation
lstr_annotation_appeon.dec_latitude= lstr_coordinates.dec_latitude
lstr_annotation_appeon.dec_longitude = lstr_coordinates.dec_longitude
lstr_annotation_appeon.i_pincolor = 1
lstr_annotation_appeon.s_title= string (lstr_coordinates.dt_timestamp, "hh:mm:ss")

// Adds this annotation to the map
uo_map.of_addannotation (lstr_annotation_appeon, true)

Captures the GPS error.

// ue_gpserror event
// Displays the error number and the error message
messagebox ("Error "+string(inv_gps.ii_errorcode), inv_gps.is_errortext)

Prev	Up	Next
Device	Home	Image

Workarounds & APIs GuideMobile Device API

GPS

eon_mobile_geolocationex object

Properties

integer ii_errorcode

powerobject ipo_bindevent

string is_bindwitherrorevent

string is_bindwithlocationchangedevent

string is_errortext

Events

oe_error

oe_locationchanged

Functions

of_close

of_getcurrentposition

of_isenabled

of_open

of_register

Structures

eon_mobile_str_coordinates

Code Example

Workarounds & APIs Guide
Mobile Device API