GPS

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
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

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

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:

  1. Call the of_register function to bind the user event with the oe_locationchanged event.

  2. Call the of_open function.

  3. 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

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:

    1. Adds an eon_mobile_mapex object -- uo_map -- to the window.

    2. Declares an instance variable.

      eon_mobile_geolocationex inv_gps
    3. 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")
    4. 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)
    5. 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)