29.198-063GPPOpen Service Access (OSA) Application Programming Interface (API)Part 6: Mobility Service Capability Feature (SCF)Release 9TS

8.1 User Location Interface Classes

The User Location service (UL) provides a general geographic location service. UL has functionality to allow applications to obtain the geographical location and the status of fixed, mobile and IP based telephony users.

UL is supplemented by User Location Camel service (ULC) to provide information about network related information. There is also some specialised functionality to handle emergency calls in the User Location Emergency service (ULE).

The UL service provides the IpUserLocation and IpTriggeredUserLocation interfaces. Most methods are asynchronous, in that they do not lock a thread into waiting whilst a transaction performs. In this way, the client machine can handle many more calls, than one that uses synchronous message calls. To handle responses and reports, the developer must implement IpAppUserLocation and IpAppTriggeredUserLocation interfaces to provide the callback mechanism.

When periodic or triggered location reporting is used, errors may be reported either when the recurrent reporting is requested, as an error per user in reports or in the corresponding err-method when the error concerns all subscribers in an assignment.

8.1.1 Interface Class IpUserLocation

Inherits from: IpService.

This interface is the ‘service manager’ interface for the User Location Service.

The user location interface provides the management functions to the user location service. The application programmer can use this interface to obtain the geographical location of users.

This interface, or IpTriggeredUserLocation, shall be implemented by a User Location SCF as a minimum requirement.

The locationReportReq() method, or the extendedLocationReportReq() method, or both the periodicLocationReportingStartReq() and periodicLocationReportingStop() methods shall be implemented as a minimum requirement, if this interface is implemented.

8.1.1.1 Method locationReportReq()

Request of a report on the location for one or several users.

Returns: assignmentId.

Specifies the assignment ID of the location-report request.

Parameters

appLocation : in IpAppUserLocationRef

Specifies the application interface for callbacks from the User Location service.

users : in TpAddressSet

Specifies the user(s) for which the location shall be reported.

Returns

TpAssignmentID

Raises

TpCommonExceptions, P_APPLICATION_NOT_ACTIVATED, P_INFORMATION_NOT_AVAILABLE, P_INVALID_INTERFACE_TYPE

8.1.1.2 Method extendedLocationReportReq()

Advanced request of report on the location for one or several users.

Returns: assignmentId.

Specifies the assignment ID of the extended location-report request.

Parameters

appLocation : in IpAppUserLocationRef

Specifies the application interface for callbacks from the User Location service.

users : in TpAddressSet

Specifies the user(s) for which the location shall be reported

request : in TpLocationRequest

Specifies among others the requested location type, accuracy, response time and priority.

Returns

TpAssignmentID

Raises

TpCommonExceptions, P_APPLICATION_NOT_ACTIVATED, P_REQUESTED_ACCURACY_CANNOT_BE_DELIVERED, P_REQUESTED_RESPONSE_TIME_CANNOT_BE_DELIVERED, P_INFORMATION_NOT_AVAILABLE, P_INVALID_INTERFACE_TYPE

8.1.1.3 Method periodicLocationReportingStartReq()

Request of periodic reports on the location for one or several users.

Returns: assignmentId.

Specifies the assignment ID of the periodic location-reporting request.

Parameters

appLocation : in IpAppUserLocationRef

Specifies the application interface for callbacks from the User Location service.

users : in TpAddressSet

Specifies the user(s) for which the location shall be reported.

request : in TpLocationRequest

Specifies among others the requested location type, accuracy, response time and priority.

reportingInterval : in TpDuration

Specifies the requested interval in milliseconds between the reports.

Returns

TpAssignmentID

Raises

TpCommonExceptions, P_INVALID_REPORTING_INTERVAL, P_REQUESTED_ACCURACY_CANNOT_BE_DELIVERED, P_REQUESTED_RESPONSE_TIME_CANNOT_BE_DELIVERED, P_APPLICATION_NOT_ACTIVATED, P_INFORMATION_NOT_AVAILABLE, P_INVALID_INTERFACE_TYPE

8.1.1.4 Method periodicLocationReportingStop()

Termination of periodic reports on the location for one or several users.

Parameters

stopRequest : in TpMobilityStopAssignmentData

Specifies how the assignment shall be stopped, i.e. if whole or just parts of the assignment should be stopped.

Raises

TpCommonExceptions, P_INVALID_ASSIGNMENT_ID

8.1.1.5 Method getNextPeriodicLocationRequest()

This method is used by the application to query the request set created with periodicLocationReportingStartReq. Since a lot of data can potentially be returned (which might cause problem in the middleware), this method must be used in an iterative way. Each method invocation may return part of the total set of requests if the set is too large to return it at once. The reset parameter permits the application to indicate whether an invocation to getNextPeriodicLocationRequest is requesting more requests from the total set of requests or is requesting that the total set of requests shall be returned from the beginning.

Returns the set of requests and an indication whether all off the requests have been obtained or if more requests are available that have not yet been obtained by the application.

Note that the (maximum) number of items provided to the application is determined by the gateway.

Parameters

reset : in TpBoolean

TRUE: indicates that the application is intended to obtain the set of requests starting at the beginning.

FALSE: indicates that the application requests the next set of requests that have not (yet) been obtained since the last call to this method with this parameter set to TRUE.

The first time this method is invoked, reset shall be set to TRUE. Following the receipt of a final indication, for the next call to this method reset shall be set to TRUE. P_TASK_REFUSED may be thrown if these conditions are not met.

Returns

TpPeriodicLocationRequestSetEntry

Raises

TpCommonExceptions

8.1.2 Interface Class IpAppUserLocation

Inherits from: IpInterface.

The user-location application interface is implemented by the client application developer and is used to handle user location request responses.

8.1.2.1 Method locationReportRes()

A report containing locations for one or several users is delivered.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the location-report request.

locations : in TpUserLocationSet

Specifies the location(s) of one or several users.

8.1.2.2 Method locationReportErr()

This method indicates that the location report request has failed.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the failed location report request.

cause : in TpMobilityError

Specifies the error that led to the failure.

diagnostic : in TpMobilityDiagnostic

Specifies additional information about the error that led to the failure.

8.1.2.3 Method extendedLocationReportRes()

A report containing extended location information for one or several users is delivered.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the extended location-report request.

locations : in TpUserLocationExtendedSet

Specifies the location(s) of one or several users.

8.1.2.4 Method extendedLocationReportErr()

This method indicates that the extended location report request has failed.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the failed extended location report request.

cause : in TpMobilityError

Specifies the error that led to the failure.

diagnostic : in TpMobilityDiagnostic

Specifies additional information about the error that led to the failure.

8.1.2.5 Method periodicLocationReport()

A report containing periodic location information for one or several users is delivered.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the periodic location-reporting request.

locations : in TpUserLocationExtendedSet

Specifies the location(s) of one or several users.

8.1.2.6 Method periodicLocationReportErr()

This method indicates that a requested periodic location report has failed. Note that errors only concerning individual users are reported in the ordinary periodicLocationReport() message.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the failed periodic location reporting start request.

cause : in TpMobilityError

Specifies the error that led to the failure.

diagnostic : in TpMobilityDiagnostic

Specifies additional information about the error that led to the failure.

8.1.3 Interface Class IpTriggeredUserLocation

Inherits from: IpUserLocation.

This interface can be used as an extended version of the User Location: Service Interface.

The triggered user location interface represents the interface to the triggered user location functions. The application programmer can use this interface to request user location reports that are triggered by location change.

This interface, or IpUserLocation, shall be implemented by a User Location SCF as a minimum requirement.

The triggeredLocationReportingStartReq() and triggeredLocationReportingStop() methods shall be implemented as a minimum requirement. An implementation of IpTriggeredUserLocation is not required to implement the minimum mandatory methods of IpUserLocation.

8.1.3.1 Method triggeredLocationReportingStartReq()

Request for user location reports when the location is changed (reports are triggered by location change).

Returns: assignmentId.

Specifies the assignment ID of the triggered location-reporting request.

Parameters

appLocation : in IpAppTriggeredUserLocationRef

Specifies the application interface for callbacks from the User Location service.

users : in TpAddressSet

Specifies the user(s) for which the location shall be reported.

request : in TpLocationRequest

Specifies among others the requested location type, accuracy, response time and priority.

triggers : in TpLocationTriggerSet

Specifies the trigger conditions.

Returns

TpAssignmentID

Raises

TpCommonExceptions, P_REQUESTED_ACCURACY_CANNOT_BE_DELIVERED, P_REQUESTED_RESPONSE_TIME_CANNOT_BE_DELIVERED, P_TRIGGER_CONDITIONS_NOT_SUBSCRIBED, P_UNKNOWN_SUBSCRIBER, P_APPLICATION_NOT_ACTIVATED, P_INFORMATION_NOT_AVAILABLE, P_INVALID_INTERFACE_TYPE

8.1.3.2 Method triggeredLocationReportingStop()

Stop triggered user location reporting.

Parameters

stopRequest : in TpMobilityStopAssignmentData

Specifies how the assignment shall be stopped, i.e. if whole or just parts of the assignment should be stopped.

Raises

TpCommonExceptions, P_INVALID_ASSIGNMENT_ID

8.1.3.3 Method getNextTriggeredLocationRequest()

This method is used by the application to query the request set created with triggeredLocationReportingStartReq. Since a lot of data can potentially be returned (which might cause problem in the middleware), this method must be used in an iterative way. Each method invocation may return part of the total set of requests if the set is too large to return it at once. The reset parameter permits the application to indicate whether an invocation to getNextTriggeredLocationRequest is requesting more requests from the total set of requests or is requesting that the total set of requests shall be returned from the beginning.

Returns the set of requests and an indication whether all off the requests have been obtained or if more requests are available that have not yet been obtained by the application.

Note that the (maximum) number of items provided to the application is determined by the gateway.

Parameters

reset : in TpBoolean

TRUE: indicates that the application is intended to obtain the set of requests starting at the beginning.

FALSE: indicates that the application requests the next set of requests that have not (yet) been obtained since the last call to this method with this parameter set to TRUE.

The first time this method is invoked, reset shall be set to TRUE. Following the receipt of a final indication, for the next call to this method reset shall be set to TRUE. P_TASK_REFUSED may be thrown if these conditions are not met.

Returns

TpTriggeredLocationRequestSetEntry

Raises

TpCommonExceptions

8.1.4 Interface Class IpAppTriggeredUserLocation

Inherits from: IpAppUserLocation.

This interface must be used as a specialised version of the User Location: Application Interface if the Triggered User Location: Service Interface is used.

The triggered user location application interface is implemented by the client application developer and is used to handle triggered location reports.

8.1.4.1 Method triggeredLocationReport()

A triggered report containing location for a user is delivered.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the triggered location-reporting request.

location : in TpUserLocationExtended

Specifies the location of the user.

criterion : in TpLocationTriggerCriteria

Specifies the criterion that triggered the report.

8.1.4.2 Method triggeredLocationReportErr()

This method indicates that a requested triggered location report has failed. Note that errors only concerning individual users are reported in the ordinary triggeredLocationReport() message.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the failed triggered location reporting start request.

cause : in TpMobilityError

Specifies the error that led to the failure.

diagnostic : in TpMobilityDiagnostic

Specifies additional information about the error that led to the failure.

8.1.4.3 Method triggeredReportingEnded()

The user status or user location triggering has stopped because the max life time allowed for this triggering has exceeded.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the triggered request.

8.2 User Location Camel Interface Classes

The ULC provides location information, based on network-related information, rather than the geographical co-ordinates that can be retrieved via the general User Location Service.

Using the ULC functions, an application programmer can request the VLR Number, the location Area Identification and the Cell Global Identification and other mobile-telephony-specific location information.

The ULC provides the IpUserLocationCamel interface. Most methods are asynchronous, in that they do not lock a thread into waiting whilst a transaction performs. In this way, the client machine can handle many more calls, than one that uses synchronous message calls. To handle responses and reports, the developer must implement IpAppUserLocationCamel interface to provide the callback mechanism.

8.2.1 Interface Class IpUserLocationCamel

Inherits from: IpService.

This interface is the ‘service manager’ interface for ULC.

This interface shall be implemented by a User Location Camel SCF.

The locationReportReq() method, or both the periodicLocationReportingStartReq() and periodicLocationReportingStop() methods, or both the triggeredLocationReportingStartReq() and triggeredLocationReportingStop() methods shall be implemented as a minimum requirement.

8.2.1.1 Method locationReportReq()

Request for mobile-related location information on one or several camel users.

Returns: assignmentId.

Specifies the assignment ID of the location-report request.

Parameters

appLocationCamel : in IpAppUserLocationCamelRef

Specifies the application interface for callbacks from the User Location Camel service.

users : in TpAddressSet

Specifies the user(s) for which the location shall be reported.

Returns

TpAssignmentID

Raises

TpCommonExceptions, P_UNKNOWN_SUBSCRIBER, P_APPLICATION_NOT_ACTIVATED, P_INFORMATION_NOT_AVAILABLE, P_INVALID_INTERFACE_TYPE

8.2.1.2 Method periodicLocationReportingStartReq()

Request for periodic mobile location reports on one or several users.

Returns: assignmentId.

Specifies the assignment ID of the periodic location-reporting request.

Parameters

appLocationCamel : in IpAppUserLocationCamelRef

Specifies the application interface for callbacks from the User Location Camel service.

users : in TpAddressSet

Specifies the user(s) for which the location shall be reported.

reportingInterval : in TpDuration

Specifies the requested interval in milliseconds between the reports.

Returns

TpAssignmentID

Raises

TpCommonExceptions, P_INVALID_REPORTING_INTERVAL, P_UNKNOWN_SUBSCRIBER, P_APPLICATION_NOT_ACTIVATED, P_INFORMATION_NOT_AVAILABLE, P_INVALID_INTERFACE_TYPE

8.2.1.3 Method periodicLocationReportingStop()

This method stops the sending of periodic mobile location reports for one or several users.

Parameters

stopRequest : in TpMobilityStopAssignmentData

Specifies how the assignment shall be stopped, i.e. if whole or just parts of the assignment should be stopped.

Raises

TpCommonExceptions, P_INVALID_ASSIGNMENT_ID

8.2.1.4 Method triggeredLocationReportingStartReq()

Request for user location reports, containing mobile related information, when the location is changed (the report is triggered by the location change).

Returns: assignmentId.

Specifies the assignment ID of the triggered location-reporting request.

Parameters

appLocationCamel : in IpAppUserLocationCamelRef

Specifies the application interface for callbacks from the User Location Camel service.

users : in TpAddressSet

Specifies the user(s) for which the location shall be reported.

trigger : in TpLocationTriggerCamel

Specifies the trigger conditions.

Returns

TpAssignmentID

Raises

TpCommonExceptions, P_UNKNOWN_SUBSCRIBER, P_APPLICATION_NOT_ACTIVATED, P_INFORMATION_NOT_AVAILABLE, P_INVALID_INTERFACE_TYPE

8.2.1.5 Method triggeredLocationReportingStop()

Request that triggered mobile location reporting should stop.

Parameters

stopRequest : in TpMobilityStopAssignmentData

Specifies how the assignment shall be stopped, i.e. if whole or just parts of the assignment should be stopped.

Raises

TpCommonExceptions, P_INVALID_ASSIGNMENT_ID

8.2.1.6 Method getNextPeriodicLocationRequest()

This method is used by the application to query the request set created with periodicLocationReportingStartReq. Since a lot of data can potentially be returned (which might cause problem in the middleware), this method must be used in an iterative way. Each method invocation may return part of the total set of requests if the set is too large to return it at once. The reset parameter permits the application to indicate whether an invocation to getNextPeriodicLocationRequest is requesting more requests from the total set of requests or is requesting that the total set of requests shall be returned from the beginning.

Returns the set of requests and an indication whether all off the requests have been obtained or if more requests are available that have not yet been obtained by the application.

Note that the (maximum) number of items provided to the application is determined by the gateway.

Parameters

reset : in TpBoolean

TRUE: indicates that the application is intended to obtain the set of requests starting at the beginning.

FALSE: indicates that the application requests the next set of requests that have not (yet) been obtained since the last call to this method with this parameter set to TRUE.

The first time this method is invoked, reset shall be set to TRUE. Following the receipt of a final indication, for the next call to this method reset shall be set to TRUE. P_TASK_REFUSED may be thrown if these conditions are not met.

Returns

TpPeriodicLocationRequestSetEntry

Raises

TpCommonExceptions

8.2.1.7 Method getNextTriggeredLocationRequest()

This method is used by the application to query the request set created with triggeredLocationReportingStartReq. Since a lot of data can potentially be returned (which might cause problem in the middleware), this method must be used in an iterative way. Each method invocation may return part of the total set of requests if the set is too large to return it at once. The reset parameter permits the application to indicate whether an invocation to getNextTriggeredLocationRequest is requesting more requests from the total set of requests or is requesting that the total set of requests shall be returned from the beginning.

Returns the set of requests and an indication whether all off the requests have been obtained or if more requests are available that have not yet been obtained by the application.

Note that the (maximum) number of items provided to the application is determined by the gateway.

Parameters

reset : in TpBoolean

TRUE: indicates that the application is intended to obtain the set of requests starting at the beginning.

FALSE: indicates that the application requests the next set of requests that have not (yet) been obtained since the last call to this method with this parameter set to TRUE.

The first time this method is invoked, reset shall be set to TRUE. Following the receipt of a final indication, for the next call to this method reset shall be set to TRUE. P_TASK_REFUSED may be thrown if these conditions are not met.

Returns

TpTriggeredLocationRequestSetEntry

Raises

TpCommonExceptions

8.2.2 Interface Class IpAppUserLocationCamel

Inherits from: IpInterface.

The user location Camel application interface is implemented by the client application developer and is used to handle location reports that are specific for mobile telephony users.

8.2.2.1 Method locationReportRes()

Delivery of a mobile location report. The report is containing mobile-related location information for one or several users.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the location-report request.

locations : in TpUserLocationCamelSet

Specifies the location(s) of one or several users.

8.2.2.2 Method locationReportErr()

This method indicates that the location report request has failed.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the failed location report request.

cause : in TpMobilityError

Specifies the error that led to the failure.

diagnostic : in TpMobilityDiagnostic

Specifies additional information about the error that led to the failure.

8.2.2.3 Method periodicLocationReport()

Periodic delivery of mobile location reports. The reports are containing mobile-related location information for one or several users.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the periodic location-reporting request.

locations : in TpUserLocationCamelSet

Specifies the location(s) of one or several users.

8.2.2.4 Method periodicLocationReportErr()

This method indicates that a requested periodic location report has failed. Note that errors only concerning individual users are reported in the ordinary periodicLocationReport() message.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the failed periodic location reporting start request.

cause : in TpMobilityError

Specifies the error that led to the failure.

diagnostic : in TpMobilityDiagnostic

Specifies additional information about the error that led to the failure.

8.2.2.5 Method triggeredLocationReport()

Delivery of a report that is indicating that the user’s mobile location has changed.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the triggered location-reporting request.

location : in TpUserLocationCamel

Specifies the location of the user.

criterion : in TpLocationTriggerCamel

Specifies the criterion that triggered the report.

8.2.2.6 Method triggeredLocationReportErr()

This method indicates that a requested triggered location report has failed. Note that errors only concerning individual users are reported in the ordinary triggeredLocationReport() message.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the failed triggered location reporting start request.

cause : in TpMobilityError

Specifies the error that led to the failure.

diagnostic : in TpMobilityDiagnostic

Specifies additional information about the error that led to the failure.

8.2.2.7 Method triggeredReportingEnded()

The user status or user location triggering has stopped because the max life time allowed for this triggering has exceeded.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the triggered request.

8.3 User Location Emergency Interface Classes

In the case of an emergency call, the network may locate the caller automatically. The resulting location is sent directly to an application that is dedicated to handle emergency user location. If the dedicated emergency call application is using the API, the location is sent to the application using a callback method in the IpAppUserLocationEmergency interface.

However, the network does not always send the location immediately (probably when the location procedure is not finished when the call is set up). In this case the network will send an identifier of the caller that can be used to locate the caller using the interface IpUserLocationEmergency.

8.3.1 Interface Class IpUserLocationEmergency

Inherits from: IpService.

The application programmer can use this interface to obtain the location of users who initiate emergency calls.

This interface shall be implemented by a Mobility SCF.

The emergencyLocationReportReq() method, or the subscribeEmergencyLocationReports() and unSubscribeEmergencyLocationReports() methods shall be implemented as a minimum requirement.

8.3.1.1 Method emergencyLocationReportReq()

Request of report on the location for one user that is making an emergency call.

Returns: assignmentId.

Specifies the assignment ID of the emergency location-report request.

Parameters

appEmergencyLocation : in IpAppUserLocationEmergencyRef

Specifies the application interface for callbacks from the User Location Emergency service.

request : in TpUserLocationEmergencyRequest

Specifies among others the identity of the user or terminal, requested location type, accuracy, response time and priority.

Returns

TpAssignmentID

Raises

TpCommonExceptions, P_UNKNOWN_SUBSCRIBER, P_INFORMATION_NOT_AVAILABLE, P_APPLICATION_NOT_ACTIVATED, P_INVALID_INTERFACE_TYPE

8.3.1.2 Method subscribeEmergencyLocationReports()

Subscribe to network initiated emergency user location reports.

Returns: assignmentId.

Specifies the assignment ID of the subscription.

Parameters

appEmergencyLocation : in IpAppUserLocationEmergencyRef

Specifies the application interface for callbacks from the User Location Emergency service.

Returns

TpAssignmentID

Raises

TpCommonExceptions, P_INVALID_INTERFACE_TYPE

8.3.1.3 Method unSubscribeEmergencyLocationReports()

This method cancels a subscription to network initiated emergency user location reports.

The assignment ID does not correspond to one of a valid assignment.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the subscription.

Raises

TpCommonExceptions, P_INVALID_ASSIGNMENT_ID

8.3.2 Interface Class IpAppUserLocationEmergency

Inherits from: IpInterface.

The user-location emergency application interface is implemented by the client application developer and is used to handle emergency user location reports.

8.3.1.1 Method emergencyLocationReport()

Delivery of an emergency user location report.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the emergency location-report request or the emergency location report subscription.

location : in TpUserLocationEmergency

Specifies the identity and location of the user that makes the emergency call.

8.3.2.2 Method emergencyLocationReportErr()

This method indicates that the emergency location report request has failed.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the failed emergency location report request.

cause : in TpMobilityError

Specifies the error that led to the failure.

diagnostic : in TpMobilityDiagnostic

Specifies additional information about the error that led to the failure.

8.4 User Status Interface Classes

The User Status Service (US) provides a general user status service. US allow applications to obtain the status of fixed, mobile and IP-based telephony users.

The US provides the IpUserStatus interface. Most methods are asynchronous, in that they do not lock a thread into waiting whilst a transaction performs. In this way, the client machine can handle many more calls, than one that uses synchronous message calls. To handle responses and reports, the developer must implement IpAppUserStatus interface to provide the callback mechanism.

8.4.1 Interface Class IpAppUserStatus

Inherits from: IpInterface.

The user-status application interface is implemented by the client application developer and is used to handle user status reports.

8.4.1.1 Method statusReportRes()

Delivery of a report, that is containing one or several user’s status.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the status-report request.

status : in TpUserStatusSet

Specifies the status of one or several users.

8.4.1.2 Method statusReportErr()

This method indicates that the status report request has failed.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the failed status report request.

cause : in TpMobilityError

Specifies the error that led to the failure.

diagnostic : in TpMobilityDiagnostic

Specifies additional information about the error that led to the failure.

8.4.1.3 Method triggeredStatusReport()

Delivery of a report that is indicating that a user’s status has changed.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the triggered status-reporting request.

status : in TpUserStatus

Specifies the status of the user.

8.4.1.4 Method triggeredStatusReportErr()

This method indicates that a requested triggered status reporting has failed. Note that errors only concerning individual users are reported in the ordinary triggeredStatusReport() message.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the failed triggered status reporting start request.

cause : in TpMobilityError

Specifies the error that led to the failure.

diagnostic : in TpMobilityDiagnostic

Specifies additional information about the error that led to the failure.

8.4.1.5 Method extendedStatusReportRes()

Delivery of a report, that is containing one or several user’s status.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the status-report request.

status : in TpUserStatusExtendedSet

Specifies the status of one or several users.

8.4.1.6 Method extendedStatusReportErr()

This method indicates that the status report request has failed.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the failed status report request.

cause : in TpMobilityError

Specifies the error that led to the failure.

diagnostic : in TpMobilityDiagnostic

Specifies additional information about the error that led to the failure.

8.4.1.7 Method extTriggeredStatusReport()

Delivery of a report that is indicating that a user’s status has changed.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the triggered status-reporting request.

status : in TpUserStatusExtended

Specifies the status of the user.

8.4.1.8 Method extTriggeredStatusReportErr()

This method indicates that a requested triggered status reporting has failed. Note that errors only concerning individual users are reported in the ordinary extTriggeredStatusReport() message.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the failed triggered status reporting start request.

cause : in TpMobilityError

Specifies the error that led to the failure.

diagnostic : in TpMobilityDiagnostic

Specifies additional information about the error that led to the failure.

8.4.1.9 Method triggeredReportingEnded()

The user status or user location triggering has stopped because the max life time allowed for this triggering has exceeded.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the triggered request.

8.4.2 Interface Class IpUserStatus

Inherits from: IpService.

The application programmer can use this interface to obtain the status of fixed, mobile and IP-based telephony users.

This interface shall be implemented by a User Status SCF.

The statusReportReq() method, or both the triggeredStatusReportingStartReq() and trigggeredStatusReportingStop() methods shall be implemented as a minimum requirement.

8.4.2.1 Method statusReportReq()

Request for a report on the status of one or several users.

Returns: assignmentId.

Specifies the assignment ID of the status-report request.

Parameters

appStatus : in IpAppUserStatusRef

Specifies the application interface for callbacks from the User Status service.

users : in TpAddressSet

Specifies the user(s) for which the status shall be reported.

Returns

TpAssignmentID

Raises

TpCommonExceptions, P_UNKNOWN_SUBSCRIBER, P_INFORMATION_NOT_AVAILABLE, P_APPLICATION_NOT_ACTIVATED, P_INVALID_INTERFACE_TYPE

8.4.2.2 Method triggeredStatusReportingStartReq()

Request for triggered status reports when one or several user’s status is changed. The user status service will send a report when the status changes.

Returns: assignmentId.

Specifies the assignment ID of the triggered status-reporting request.

Parameters

appStatus : in IpAppUserStatusRef

Specifies the application interface for callbacks from the User Status service.

users : in TpAddressSet

Specifies the user(s) for which the status changes shall be reported.

Returns

TpAssignmentID

Raises

TpCommonExceptions, P_UNKNOWN_SUBSCRIBER, P_INFORMATION_NOT_AVAILABLE, P_APPLICATION_NOT_ACTIVATED, P_INVALID_INTERFACE_TYPE

8.4.2.3 Method triggeredStatusReportingStop()

This method stops the sending of status reports for one or several users.

Parameters

stopRequest : in TpMobilityStopAssignmentData

Specifies how the assignment shall be stopped, i.e. if whole or just parts of the assignment should be stopped.

Raises

TpCommonExceptions, P_INVALID_ASSIGNMENT_ID

8.4.2.4 Method getNextTriggeredStatusRequest()

This method is used by the application to query the request set created with triggeredStatusReportingStartReq. Since a lot of data can potentially be returned (which might cause problem in the middleware), this method must be used in an iterative way. Each method invocation may return part of the total set of requests if the set is too large to return it at once. The reset parameter permits the application to indicate whether an invocation to getNextTriggeredStatusRequest is requesting more requests from the total set of requests or is requesting that the total set of requests shall be returned from the beginning.

Returns the set of requests and an indication whether all off the requests have been obtained or if more requests are available that have not yet been obtained by the application.

Note that the (maximum) number of items provided to the application is determined by the gateway.

Parameters

reset : in TpBoolean

TRUE: indicates that the application is intended to obtain the set of requests starting at the beginning.

FALSE: indicates that the application requests the next set of requests that have not (yet) been obtained since the last call to this method with this parameter set to TRUE.

The first time this method is invoked, reset shall be set to TRUE. Following the receipt of a final indication, for the next call to this method reset shall be set to TRUE. P_TASK_REFUSED may be thrown if these conditions are not met.

Returns

TpTriggeredStatusRequestSetEntry

Raises

TpCommonExceptions

8.4.2.5 Method extendedStatusReportReq()

Request for a report on the status of one or several users.

A user can be identified by the following address types:

– MSISDN indicated with address plan P_ADDRESS_PLAN_E164.

– IP Address indicated with address plan P_ADDRESS_PLAN_IP.

– User Name indicated with address plan P_ADDRESS_PLAN_UNDEFINED.

Returns: assignmentID.

Parameters

appStatus : in IpAppUserStatusRef

Specifies the application interface for callbacks from the User Status service.

users : in TpAddressSet

Specifies the user(s) for which the status shall be reported.

Returns

TpAssignmentID

Raises

TpCommonExceptions, P_UNKNOWN_SUBSCRIBER, P_INFORMATION_NOT_AVAILABLE, P_APPLICATION_NOT_ACTIVATED, P_INVALID_INTERFACE_TYPE

8.4.2.6 Method extTriggeredStatusReportingStartReq()

Request for triggered status reports when one or several user’s status is changed. The user status service will send a report when the status changes.

Returns: assignmentId.

Specifies the assignment ID of the triggered status-reporting request.

Parameters

appStatus : in IpAppUserStatusRef

Specifies the application interface for callbacks from the User Status service.

users : in TpAddressSet

Specifies the user(s) for which the status changes shall be reported.

Returns

TpAssignmentID

Raises

TpCommonExceptions, P_UNKNOWN_SUBSCRIBER, P_INFORMATION_NOT_AVAILABLE, P_APPLICATION_NOT_ACTIVATED, P_INVALID_INTERFACE_TYPE

8.4.2.7 Method extTriggeredStatusReportingStop()

This method stops the sending of status reports for one or several users.

Parameters

stopRequest : in TpMobilityStopAssignmentData

Specifies how the assignment shall be stopped, i.e. if whole or just parts of the assignment should be stopped.

Raises

TpCommonExceptions, P_INVALID_ASSIGNMENT_ID

8.5 User Binding Interface Classes

In order to create a feature rich services creation environment for (mobile) "IP" networks where not only terminal mobility but also personal mobility is supported, User Binding notification functions, which enable applications to know UE binding requests, control and make use of them, are provided. The interfaces detailed below support UE binding notification functions.

8.5.1 Interface Class IpUserBinding

Inherits from: IpService.

The application programmer can use this interface to obtain binding details of users who bind to the network.

8.5.1.1 Method triggeredBindingRequestNotificationStartReq()

Request for triggered status reports when one or several user’s binding details are requested to be changed. The User Binding service will send a notification when the user’s binding details are requested to be changed.

Returns the assignment ID of the triggered binding request notification.

Parameters

appStatus : in IpAppUserBindingRef

Specifies the application interface for callbacks from the User Binding service.

users : in TpAddressSet

Specifies the user(s) for which the binding change requests shall be reported.

criteria : in TpBindingNotificationCriteriaSet

Specifies the criteria that must be matched by the binding change request notifications.

Returns

TpAssignmentID

Raises

TpCommonExceptions, P_UNKNOWN_SUBSCRIBER, P_INFORMATION_NOT_AVAILABLE, P_APPLICATION_NOT_ACTIVATED, P_INVALID_INTERFACE_TYPE

8.5.1.2 Method triggeredBindingRequestNotificationStop()

This method stops the sending of the notifications of binding change requests identified by the assignment ID.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the triggered binding-request notification.

Raises

TpCommonExceptions, P_INVALID_ASSIGNMENT_ID

8.5.2 Interface Class IpAppUserBinding

Inherits from: IpInterface.

The user-binding application interface is implemented by the client application developer and is used to handle binding notification requests.

8.5.2.1 Method triggeredBindingRequestNotification()

Delivery of a report that is indicating that a user’s binding details are requested to be changed. The application returns acceptable bindings.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the triggered binding-request notification.

address : in TpAddress

Specifies the address of the user whose binding details are requested to be changed.

contactInformation : in TpBindingSet

Specifies the binding details of the user.

Returns

TpBindingSet

8.5.2.2 Method triggeredBindingRequestNotificationStartErr()

This method indicates that the request for notification of binding requests has failed.

Parameters

assignmentId : in TpAssignmentID

Specifies the assignment ID of the failed request for notification of binding requests.

cause : in TpMobilityError

Specifies the error that led to the failure.

diagnostic : in TpMobilityDiagnostic

Specifies additional information about the error that led to the failure.