Extension SDK for BEA WebLogic Network Gatekeeper
User Location
The following sections contain descriptions of plug-ins of User location type:
Network plug-in
User location interfaces
All User location interfaces are defined in the file UlResource_IF.idl in bea\wlng21\esdk\idl\plugin_if\mobility.
The interfaces use definitions in the files UlResource_data.idl and MobilityResource_data.idl.
Figure 13-1 User location plugin interface
Interfaces that should be implemented by the plug-in are listed in the table below.
Table 13-1 Interfaces that shall be implemented by a plug-in for user location
|
Interface
|
Description
|
|
Resource
|
Initial object obtained from Plug-in Manager. Base interface implemented by all plug-ins.
|
|
IrUserLocation
|
The user location plug-in interface provides functions for getting the position for a terminal, starting triggered and period location request.
|
|
IrUserLocationExt
|
The extended user location plug-in interface provides functions for getting the position for a terminal, starting triggered and period location request.
|
Interfaces that are implemented by the user location SC.
Table 13-2 Interfaces that are implemented by the user location SC, used by a user location plug-in.
|
Interface
|
Description
|
|
IrAppUserLocation
|
Call back interface for positioning results.
|
|
IrAppUserLocationExt
|
Extended call back interface for positioning results.
|
IrUserLocation
IrUserLocation inherits from the Resource interface and contains and adds an method for using ordering positioning requests.
Table 13-3 IrUserLocation
|
Method
|
Description
|
|
locationReportReq
|
Deprecated.
|
|
extendedLocationReportReq
|
Deprecated.
|
|
triggeredLocationReportingStartReq
|
Deprecated.
|
|
triggeredLocationReportingStop
|
Stops a previously started triggered location report request.
|
IrUserLocationExt
IrUserLocationExt is an extended version of the IrUserLocationExt interface and should be used instead of this.
Table 13-4 IrUserLocationExt
|
Method
|
Description
|
|
locationReportCtxReq
|
Request of a report on the location of one or several terminals
|
|
extendedLocationReportCtxReq
|
Request of a report on the location of one or several terminals. More information, such as altitude, can be provided in the response to the request that in the response to locationReportCtxReq.
|
|
triggeredLocationReportingStartCtxReq
|
Request for user location reports when the location of a terminal is changed, so it enters or exits a specific location. The reports are triggered by location change.
|
|
geoLocationReportReq
|
Request of report on the location for one or several terminals where the result is delivered as geographical data such as address, zip code and so on.
|
|
periodicLocationReportingStartReq
|
Request to start a periodic report on the location for one or several terminal. The desired interval between positioning reports is defined.
|
|
periodicLocationReportingStop
|
Request to stop a previously started periodic report.
|
IrAppUserLocation
IrAppUserLocation listens for events originating in the plug-in. There may be several listeners registered for each plug-in.
This interface inherits from the SCS interface. It makes it possible to narrow a SC object retrieved from the SC Manager to an IrAppUserLocation.
Table 13-5 IrAppUserLocation
|
Method
|
Description
|
|
locationReportRes
|
Delivers a report containing locations for one or several terminals to the Service Capability implementation.
|
|
locationReportErr
|
Informs the Service Capability implementation that a location report request has failed.
|
|
extendedLocationReportRes
|
Delivers a report containing extended location information about one or several users to the Service Capability implementation.
|
|
extendedLocationReportErr
|
Informs the Service Capability implementation that an extended location report request has failed.
|
|
triggeredLocationReport
|
Delivers a report containing triggered location information about one or several terminals to the Service Capability implementation.
|
|
triggeredLocationReportErr
|
Informs the Service Capability implementation that a triggered location report request has failed.
|
IrAppUserLocationExt
IrAppUserLocationExt listens for events originating in the plug-in. There may be several listeners registered for each plug-in. This interface extends the IrAppUserLocation interface and should be used instead of that.
This interface inherits from the SCS interface. It makes it possible to narrow a SC object retrieved from the SC Manager to an MessageListener.
Table 13-6 IrAppUserLocationExt
|
Method
|
Description
|
|
geoLocationReportRes
|
Delivers a report containing locations for one or several terminals.
|
|
triggeredGeoLocationReport
|
Delivers a report containing geographical information on the position for one or several terminals. The position data is geographical data such as address, zip code and so on.
|
|
triggeredGeoLocationReportErr
|
Informs the Service Capability implementation that a triggered geographical location report request has failed.
|
|
periodicLocationReport
|
Delivers a periodic report containing locations for one or several terminals.
|
|
periodicLocationReportErr
|
Informs the Service Capability implementation that a periodic location report request has failed.
|
Use cases for user location
Application-initiated user location
The following sequence diagram show a basic positioning request and an extended user location request between a User location client (for example ESPA user location SC) and a plug-in.
Figure 13-2 Application-initiated send message
Details about the sequence diagram:
- Prior to this sequence the user location client has received a plug-in. See General usage (application-initiated events).
- The MessagingResourceClient application performs a locationReportCtxReq call to the implementation of the IrUserLocationExt interface. This interface is implemented in the plug-in. The call-back interface, IrAppUserLocation, is provided in call.
- The plug-in reports the location via locationReportRes. If the plug-in experienced problems getting the position, locationReportErr is used.
- The MessagingResourceClient application performs a extendedLocationReportCtxReq call to the implementation of the IrUserLocationExt interface. This interface is implemented in the plug-in. The call-back interface, IrAppUserLocation, is provided in call. The response to extendedLocationReportCtxReq provides can provide more detailed information such as altitude.
- The plug-in reports the location via extendedLocationReportRes. If the plug-in experienced problems getting the position, extendedLocationReportErr is used.
Network-triggered user location request
The current implementation of the ESPA User location SC, does not support network triggered events. A new user location implementation can however benefit from the network triggered parts of the user location plug-in interface.
The network triggered part of the user location uses the IrUserLocationExt interface, and starts a triggered location report using triggeredLocationReportingStartCtxReq. Supplied with this request is the call-back interface and the area of interest, together with information on wether the information shall be supplied when entering or leaving this specified area.
Note that the area can be either an area defined by longitude and latitudes or as an abstract geographical area, such as an a street or city.
The responses to the triggered user location request shall be sent to triggeredGeoLocationReport, defined in the IrAppUserLocationExt interface, or triggeredLocationReport, defined in the IrAppUserLocation interface.
