6.4.3 Methods
26.3473GPPApplication Programming Interface and URLMultimedia Broadcast/Multicast Service (MBMS)Release 17TS
6.4.3.1 Overview
Table 6.4-2 provides an overview over the methods defined for the MBMS Packet Delivery Service API. Different types are provided, namely state changes triggered by the MAA, status query of the MAA to the client, parameter updates as well as notifications from the client. The direction of the main communication flow is provided between the MAA (A) and the MBMS Client (C).
Table 6.4-2: Methods defined for MBMS Packet Delivery Service API
|
Method |
Type |
Direction |
Brief Description |
Section |
|---|---|---|---|---|
|
registerPacketApp |
State change |
A -> C |
MAA registers a callback listener with the MBMS client |
6.4.3.2 |
|
deregisterPacketApp |
State change |
A -> C |
MAA deregisters with the MBMS client |
6.4.3.10 |
|
startPacketService |
State change |
A -> C |
Starts Packet service |
6.4.3.7 |
|
stopPacketService |
State change |
A -> C |
Stop Packet service |
6.4.3.9 |
|
getPacketServices |
Status query |
C <-> A |
Get list of currently active services |
6.4.3.4 |
|
getVersion |
Status query |
C <-> A |
Get the API version |
6.4.3.13 |
|
setPacketServiceClassFilter |
Update to parameter list |
A -> C |
MAA sets a filter on MBMS Packet Delivery services in which it is interested |
6.4.3.5 |
|
registerPacketResponse |
Update to parameter list |
C -> A |
The response to the MAA Packet service register API |
6.4.3.3 |
|
serviceStarted |
Notification |
C -> A |
Notification to MAA when the MBMS Packet Delivery service started |
6.4.3.8 |
|
rtpServiceListUpdate |
Notification |
C -> A |
Notification to MAA on an update of the available for MBMS Packet Delivery services |
6.4.3.6 |
|
rtpServiceError |
Notification |
C -> A |
Notification to MAA when there is an error with the reception download of service |
6.4.3.12 |
|
serviceStalled |
Notification |
C -> A |
Notification to MAA that MBMS Packet Delivery service failed |
6.4.3.11 |
|
addSA |
Update to parameter list |
A -> C |
Adds service announcement to the MBMS client on MBMS packet delivery services |
6.2.3.22 |
|
addSAResponse |
Notification |
C -> A |
Call back to addSA() |
6.2.3.23 |
6.4.3.2 Registration
6.4.3.2.1 Overview
This clause defines registerPacketApp() interface.
An MAA calls the registerPacketApp() interface to register with the MBMS Client to consume MBMS Packet Delivery services. The registerPacketApp() interface has two purposes:
– It signals to the MBMS Client that an MAA is interested to consume MBMS Packet Delivery Services.
– It allows the MAA to identify its callback listeners defined in the MBMS Packet Delivery service API for the MBMS Client to provide asynchronous notifications to the MAA on relevant events associated with Packet-over-MBMS.
Note: Since some application development frameworks do not support callback functions, an MAA for these frameworks will not provide callback listeners in the registerPacketApp() interface. Instead, the MAA will implement the necessary approach available on these frameworks to receive event notifications from the MBMS Client in place of callback functions. The notifications implemented on these frameworks will include the same information content as defined on the structures for the IDL callback functions.
Figure 6.4-2 shows the registration process.
Figure 6.4-2 MAA Registration sequence diagram
6.4.3.2.2 Parameters
The parameters for the registerPacketApp() API are:
– ServiceType serviceType – provides the service type that the MAA wants to access. Different service types for packet streaming are defined in clause 4.3.
– string appId – provides a unique ID for the MAA registering with the MBMS client, which uses this identity to maintain state information for a particular MAA. The uniqueness of the ID is in the context of any MAA that may possibly register with MBMS client. Uniqueness is typically provided on platform level.
– any platformSpecificAppContext – a platform-specific context for the registering MAA that enables the MBMS client to get extra information about the MAA that may be need to enable the MAA to have access to MBMS services, e.g., to enable MAA authentication or to enable the MAA to communicate with the MBMS client via platform (e.g., HLOS) services.
– sequence<string> serviceClassList – provides a comma-separated list of service classes which the MAA is interested to register. Each service class string can be any string or it may be empty.
– ILTEPacketServiceCallback callBack – provides the MBMS client with the call back functions associated with MBMS Packet Delivery Service APIs for the registering MAA.
Note: The callback element in the IDL description is optional and only included when the MAA development framework supports programmatic callback interfaces. If callbacks are not supported on a given MAA development framework, the same information content as defined on the callback structures is to be provided to the MAA via the notification method available with that development framework when the respective condition is met.
6.4.3.2.3 Pre-Conditions
The MAA has assigned a unique application ID appId in the context of its operation (e.g., a smartphone HLOS) with the MBMS client.
The MAA is pre-configured with the set of service classes that allows it to consume the MBMS packet delivery services of the specified type associated with these service classes.
The MAA has access to a packet client that can consume the service type.
The MAA may use this method at launch or after a deregisterPacketApp() has been called.
The MBMS client is in IDLE state.
6.4.3.2.4 Usage of Method for MAA
The MAA uses the method registerPacketApp() to register with the MBMS Client to consume Packet Delivery services of a specific type using the serviceType parameter. Different service types are defined in clause 4.3.
The MAA provides its appId and, if applicable, some platform specific MAA context, platformSpecificAppContext.
The MAA provides the set of service classes which the MAA is interested to register.
6.4.3.2.5 Expected MBMS Client Actions
When this method is invoked, the MBMS registers the MAA, if possible. For more details refer to clause 6.4.2.3.
6.4.3.2.6 Post-Conditions
The MAA expects the registerPacketResponse() as defined in 6.4.3.3.
6.4.3.3 MBMS Packet Delivery Service Registration Response
6.4.3.3.1 Overview
This clause defines registerPacketResponse() call.
As illustrated in Figure 6.4-2, the MBMS client responds to an MAA call to the registerPacketApp() API with a registerPacketResponse() call back providing the result of the registration request.
6.4.3.3.2 Parameters
The parameters for the registerPacketResponse() API are:
– EmbmsCommonTypes::RegResponseCode value – provides a result code on the registration request. The allowed values are:
– REGISTER_SUCCESS – indicates that the registration has been processed successfully and the MAA can proceed with other API interactions with the MBMS client for MBMS Packet Delivery Services.
– FAILED_LTE_EMBMS_SERVICE_UNAVAILABLE – Indicates that the registration has failed since the MBMS Packet Delivery Service API did not find an MBMS client available on the UE on which the MAA is running and no MBMS service will be available to the MAA.
– MISSING_PARAMETER – indicates that the registration has failed since one or more of the required parameter was missing.
– NOT_SUPPORTED_SERVICE_TYPE – indicates that the service type requested in serviceType is not supported by the MBMS client.
– string message – provides an associated text description of the error message. The message may be empty.
6.4.3.3.3 Pre-Conditions
The MBMS client has received a call via the registerPacketApp() API as defined in clause 6.4.3.2.
6.4.3.3.4 Expected MBMS Client Actions
The MBMS client responds accordingly and depending on the response moves to one of the states: IDLE, NOT_AVAILABLE, or REGISTERED. For more details refer to clause 6.4.2.4.
6.4.3.3.5 Usage of Method for MAA
Once the MAA receives a the registerPacketResponse() with the RegResponseCode set to REGISTER_SUCCESS, the MAA can proceed with other API interactions with the MBMS client.
If the MBMS client is temporarily in NOT_AVAILABLE, if the registerPacketResponse() signaled a failure with a FAILED_LTE_EMBMS_SERVICE_UNAVAILABLE, the MAA may periodically recheck if the state of the MBMS client changes by retrying the registerPacketApp() API.
If the MBMS client is responding with MISSING_PARAMETERS, the MAA should fix the parameters and retry the registerPacketApp() API.
If the MBMS client is responding with NON_SUPPORTED_SERVICE_TYPE, the MAA may check if other service types can be used to possible access the services, for example if the MAA supports handling other service types.
6.4.3.3.6 Post-Conditions
If the MBMS client functions cannot be activated and once the response is sent, then MBMS client is at least temporarily in NOT_AVAILABLE state.
If the MBMS client functions can be activated and respective response is sent, then MBMS client is in REGISTERED state with the REGISTERED parameters as set above.
6.4.3.4 Getting information on available MBMS Packet Delivery Services
6.4.3.4.1 Overview
This clause defines getPacketServices() API call.
The registerPacketApp() interface returns the complete list of available MBMS Packet Delivery Services information. As illustrated in Figure 6.4-2, after a successful registration with the MBMS client, the MAA can use the getPacketServices() API to discover the available MBMS Packet Delivery Services associated with the service classes registered via the registerPacketApp().
6.4.3.4.2 Parameters
The getPacketServices() API returns a list describing the available MBMS Packet Delivery Services, where each service is described by the following output only parameters:
– sequence<ServiceNameLang> serviceNameList – optionally provides a list of the service title name in possibly different languages. Each (name, lang) pair defines a title for the service on the language indicated.
– string name – offers a title for the user service on the language identified in the lang parameter.
– string lang – identifies a natural language identifier per RFC 3066 [10].
– string serviceClass – identifies the service class which is associated with the service.
– string serviceId – provides the unique service ID for the service. The uniqueness is among all services provided by the BMSC.
– string serviceLanguage – indicates the available language for the service and represented as an identifier per RFC3066 [10].
– EmbmsCommonTypes::ServiceAvailabilityType serviceBroadcastAvailability – signals whether the UE is currently in the broadcast coverage area for the service.
– The possible values are:
– BROADCAST_AVAILABLE – if content for the service is broadcast at the current device location.
– BROADCAST_UNAVAILABLE – if content for the service is not broadcast at the current device location.
– string sdpUri – provides an HTTP URL where the SDP for the MBMS Packet Delivery Service is hosted and available for media client access.
– string interfaceName – provides the network interface name from which the started MBMS Packet Delivery Service can be received by the media clients.
– EmbmsCommonTypes::Date activeServicePeriodStartTime – signals the current/next active MBMS Packet Delivery Service start time, when data starts being broadcast over the air.
– EmbmsCommonTypes::Date activeServicePeriodEndTime – signals the current/next active MBMS Packet Delivery Service stop time, when Packet data stops being broadcasted over the air.
6.4.3.4.3 Pre-Conditions
The MBMS client is in REGISTERED state.
6.4.3.4.4 Expected MBMS Client Actions
When this method is invoked, the MBMS client returns the Packet service parameters. For more details refer to clause 6.4.2.4.
6.4.3.4.5 Usage of Method for MAA
The MAA should use this call right after the registerPacketResponse() notification as defined in clause 6.4.3.3 is received or after the rtpServiceListUpdate() notification as defined in clause 6.4.3.6 is received.
The MAA should use the serviceId to identify the service in subsequent communication with the MBMS client to manage the MBMS Packet Delivery service.
The usage of the parameters serviceNameList, serviceClass, serviceBroadcastAvailability, and serviceLanguage is typically up to the MAA.
The sdpURI should be used by the MAA to initiate playback by initiating a Packet client. The MAA should assume that the Packet Session can be consumed by the Packet client without any further interaction with the MAA. The interfaceName should be used by the Packet client to filter the data stream reception from a specific network interface.
The parameters activeServicePeriodStartTime and activeServicePeriodEndTime provides the MAA the ability to determine the current broadcast state for the service as follows:
– If the current time is such that activeServicePeriodStartTime ≤ current time ≤ activeServicePeriodEndTime, Packet content is being broadcast for the service at the current time.
– If the activeServicePeriodStartTime is in the future, there is currently no broadcast being made for the service, but broadcast transmission is currently scheduled to start at this advertised time.
– If the activeServicePeriodStartTime is set to zero, there is no currently defined broadcast schedule time for the service.
6.4.3.4.6 Post-Conditions
This call does not change the MBMS client state.
The MAA uses the serviceId to identify the service in subsequent communication with the MBMS client.
6.4.3.5 Updating the registered service classes
6.4.3.5.1 Overview
This clause defines setPacketServiceClassFilter() call.
While an MAA is actively registered with the MBMS client to consume MBMS Packet Delivery services, the MAA can call the setPacketServiceClassFilter() API to update the list of service classes the MAA wants to be registered with, see figure 6.4.3.5.1-1.
Figure 6.4.3.5.1-1: Sequence diagram for updating the registered service classes for an MAA
6.4.3.5.2 Parameters
The parameters for the setPacketServiceClassFilter() method are:
– sequence<string> serviceClassList – see clause 6.4.3.2.2.
6.4.3.5.3 Pre-Conditions
The MAA is actively registered with the MBMS client to consume MBMS Packet Delivery services, and MBMS client is in REGISTERED state for the MAA.
6.4.3.5.4 Expected MBMS Client Actions
When this method is invoked, the MBMS client shall update the internal parameters and is expected to provide a packetServiceListUpdate() notification as defined in clause 6.4.3.6. For more details refer to clause 6.4.2.4.
6.4.3.5.5 Usage of Method for MAA
The MAA may invoke the setPacketServiceClassFilter() API to update the previously defined new list of service classes that includes additional service classes or includes fewer service classes than the list of service classes.
The MAA should be aware that the updates are only active once an packetServiceListUpdate() notification is received that confirms the new service class filters.
6.4.3.5.6 Post-Conditions
The MBMS client issues an packetServiceListUpdate() notification as defined in clause 6.4.3.6.
6.4.3.6 Updating the Packet Service List
6.4.3.6.1 Overview
This clause defines packetServiceListUpdate() notification.
This notification is used by the MBMS client to inform the MAA about a successful API call setPacketServiceClassFilter() as shown in Figure 6.4-3 or other updates in Packet service list.
6.4.3.6.2 Parameters
None.
6.4.3.6.3 Pre-Conditions
The MBMS client is in REGISTERED state for the MAA. The MAA has issued a setPacketServiceClassFilter()API call.
6.3.3.6.4 Expected MBMS Client Actions
The MBMS client issues this notification as a response to a successful setPacketServiceClassFilter()API call or to the response to updates of the service list provided in the SDP. For more details see clause 6.4.2.4.
6.4.3.6.5 Usage of Method for MAA
The MAA is informed about the updates of the service class list and may issues a getPacketServices() API call as defined in clause 6.4.3.4 to obtain the updated service list.
6.4.3.6.6 Post-Conditions
The MAA has the latest service list. No state change is involved.
6.4.3.7 Start MBMS Packet Delivery Service
6.4.3.7.1 Overview
This clause defines startPacketService() API.
After the MBMS Packet Delivery Service registration, the MAA can make calls on the startPacketService() API for the MBMS client to start reception of content received over broadcast, as shown in Figure 6.4.3.7.1-1.
Figure 6.4.3.7.1-1: MAA starts MBMS Packet Delivery services
6.4.3.7.2 Parameters
The parameters for the startPacketService() API are:
– string serviceId – see clause 6.4.3.4.2.
6.4.3.7.3 Pre-Conditions
The MBMS client is in REGISTERED state.
The MAA has the latest service list, for example through the getPacketServices() API call as defined in clause 6.4.3.4.
6.4.3.7.4 Usage of Method for MAA
The MAA can make calls on the startPacketService() API for the MBMS client to start reception of Packet data over the MBMS system.
When the MAA is no longer interested in consuming the Packet Session, it should call the stopPacketService() API call as defined in clause 6.4.3.9. It should also inform the media client to stop packet reception.
6.4.3.7.5 MBMS Client Actions
When this method is invoked, the MBMS client starts the Packet service, if possible. For more details see clause 6.4.2.4.
6.4.3.7.6 Post-Conditions
The MAA expects a serviceStarted() notification as defined in clause 6.4.3.8 or an appropriate error message.
6.4.3.8 Notification that MBMS Packet Delivery Service has started
6.4.3.8.1 Overview
Once the MBMS client has successfully collected all necessary information to start the service the MBMS client invokes the serviceStarted() callback function.
6.4.3.8.2 Parameters
The parameters for the serviceStarted() API are:
– string serviceId – see definition in clause 6.4.3.2.2.
6.4.3.8.3 Pre-Conditions
The MAA issued a startPacketService() API call.
The MBMS client is in REGISTERED state for the serviceId.
6.4.3.8.4 Expected MBMS Client Actions
The MBMS client issues this notification if the service is started successful. For details see clause 6.4.2.4.
6.4.3.8.5 Usage of Method for MAA
Once the MAA receives the callback on the successful start of the service with the serviceId, the MAA may start the MBMS Packet Delivery service initiating a Packet Session at a Packet client by handing over the sdpURI received during the registration process for this service. The media client iniates the packet forwarding.
6.4.3.8.6 Post-Conditions
The Packet client can communicate with the MBMS client. The MBMS client makes available the MBMS Packet Delivery service based on the SDP referenced in by the sdpURI of the service.
6.4.3.9 Stop MBMS Packet Delivery Service
6.4.3.9.1 Overview
This clause defines stopPacketService() API.
As figure 6.4-4 illustrates, when an MAA that issued a startPacketService() for a service is no longer interested in consuming the Packet session for that service, it will call the stopPacketService() API call.
6.4.3.9.2 Parameters
The parameter for the stopPacketService() API is:
– string serviceId – see definition in clause 6.4.3.2.2.
6.4.3.9.3 Pre-Conditions
The MBMS client is in ACTIVE state for this MAA.
6.4.3.9.4 Usage of Method for MAA
If an MAA is no longer interested in consuming the Packet service, it should call the stopPacketService() API call. Latest at the same time, the MAA should inform the Packet client about the termination of the service and the Packet client should no longer receive data that are referenced by the sdpURI.
6.4.3.9.5 MBMS Client Actions
The MBMS terminates the reception and no longer forwards the packets to the media client. For more details see clause 6.4.2.5.
6.4.3.9.6 Post-Conditions
The MBMS client is in REGISTERED state. The Packet Session referenced by the sdpURI can no longer be accessed as the referenced data will no longer be provided at the announced location in the SDP.
6.4.3.10 MBMS Packet Delivery Service De-registration
6.4.3.10.1 Overview
This clause defines deregisterPacketApp() API.
An MAA registers service classes with the MBMS client to request the start of streaming for MBMS Packet Delivery Services. The MAA that registered with the MBMS client via the registerPacketApp() API should invoke the deregisterPacketApp() before exiting. An implicit stopPacketService() call is performed for all MBMS Packet Delivery Services that have been started since the last registerPacketApp() call. If there are no MAA interested in an MBMS Packet Delivery Service, the MBMS client stops capturing data for this Service.
The MBMS client stops monitoring for Service Announcement updates when there are no MAAs registered. There are no parameters for the registerPacketApp() API.
6.4.3.10.2 Parameters
None.
6.4.3.10.3 Pre-Conditions
The MBMS client is in REGISTERED state for this MAA.
6.4.3.10.4 Usage of Method for MAA
MAA registered with the MBMS client via the registerPacketApp() API should invoke the deregisterPacketApp() before exiting.
6.4.3.10.5 MBMS Client Actions
The MBMS client no longer sends notifications and clears all context for the MAA.
6.4.3.10.6 Post-Conditions
The MAA is no longer registered with the MBMS client.
The MBMS client is in IDLE mode.
6.4.3.11 Notification that MBMS Packet Delivery Service has stalled
6.4.3.11.1 Overview
This clause the serviceStalled() notification.
The MBMS client enables consumption of a MBMS Packet Delivery service if the current setting for serviceBroadcastAvailability is BROADCAST_AVAILABLE or BROADCAST_UNAVAILABLE. Other circumstances may also prevent the broadcast reception of that service (e.g., a frequency conflict). In these circumstances, the MBMS client will signal the MAA that the service is temporarily not available for playback by invoking the serviceStalled() API.
When broadcast reception of the service is re-established, the MBMS client will signal the MAA that the service is again available for playback by invoking the serviceStarted() API. This is illustrated in Figure 6.4-5.
Figure 6.4-5: Signaling that a MBMS Packet Delivery service stalled
6.4.3.11.2 Parameters
The parameter for the serviceStalled() API are:
– string serviceId – identifies the MBMS Packet Delivery Service for which broadcast receptions have temporarily stalled.
– StalledReasonCode reason – provides specific information on what caused the service to stall. Valid options are:
– RADIO_CONFLICT – indicates a frequency conflict, namely the service requested to be started via a startPacketService() cannot be started at this time since the MBMS client is actively receiving another service on a different frequency band.
– END_OF_SESSION – indicates that playback has reached the end of the scheduled transmission for the service as described by the schedule description fragment for the service. This should indicate that the advertised activeServicePeriodEndTime time has been reached.
– OUT_OF_COVERAGE – indicates a UE mobility event to an area where the service is not available via broadcast.
– STALLED_UNKNOWN_REASON – indicates that another unspecified condition caused the service interruption.
6.4.3.11.3 Pre-Conditions
The MBMS client is in ACTIVE mode.
6.4.3.11.4 Expected MBMS Client Actions
The MBMS client provides a serviceStalled() notification in case it can no longer provide the referenced resources in the Packet Session provided with sdpURI. For more details refer to clause 6.4.2.5.
6.4.3.11.5 Usage of Method for MAA
The MAA should stop the Packet client playback on reception of the serviceStalled() notification. However, unless the MAA is no longer interested in the content, it should not issue a stopPacketService() call in order to allow the MBMS client from trying to collect Packet content once the download problem is resolved. The MAA may inform the user of the temporary service interruption.
If the media client maintains in STALLED state for too long, the MAA should stop the service by issuing a stopPacketService().
6.4.3.11.6 Post-Conditions
The MBMS client is in STALLED mode.
6.4.3.12 Notification of MBMS Packet Delivery Service errors
6.4.3.12.1 Overview
This clause defines the packetServiceError() notification.
As illustrated in Figure 6.4-5, the startPacketService() request from an MAA may not be served, so the MBMS client will send a failure indication via the packetServiceError() to signal the error code for the result of processing the MAA’s startPacketService().
Figure 6.4-5: Signaling errors with the startPacketService() request from the Packet-over-MBMS
Figure 6.4-6 also illustrates that the packetServiceError() is used to signal the error code for the result of processing the MAA’s a stopPacketService() request.
Figure 6.4-6: Signaling errors with the stopPacketService() request from the Packet-over-MBMS
6.4.3.12.2 Parameters
The parameters for the rtpServiceError() API are:
– string serviceId – identifies the MBMS Packet Delivery Service on which the MBMS client failed.
– PacketErrorCode errorCode – identifies the error code for the reason causing the startPacketService() or the stopPacketService() request for the serviceId to fail. The available error codes are:
– Packet_INVALID_SERVICE – signals that serviceID defined on the startPacketService() or the stopPacketService() request is not currently defined or it is not associated with the service classes with the MAA is registered.
– Packet_UNKNOWN_ERROR – signals an error condition not explicitly identified.
– string errorMsg – may provide additional textual description of the error condition.
6.4.3.12.3 Pre-Conditions
The MBMS client has received a the startPacketService() or a stopPacketService() request.
6.4.3.12.4 Expected MBMS Client Actions
The MBMS client will send a failure indication via the packetServiceError() to signal the error code for the result of processing the MAA. For more details refer to clauses 6.4.2.4 and 6.4.2.5.
6.4.3.12.5 Usage of Method for MAA
If the MAA receives this notification, it should revalidate the capture call. The MAA should also update the service list by issuing a getPacketServices() as defined in clause 6.4.3.4.
6.4.3.12.6 Post-Conditions
No state change is applied.
6.4.3.13 Checking the version for MBMS Packet Delivery Service interface
6.4.3.13.1 Overview
This clause defines the getVersion() request function.
6.4.3.13.2 Parameters
The parameters for the getVersion()API call are:
– string version – identifies the version of the MBMS clients API implementation.
6.4.3.13.3 Pre-Conditions
The MBMS client may be in any state.
6.4.3.13.4 Usage of Method for MAA
In order for the MAA to know the version of the MBMS Packet Delivery Service interface, the getVersion() API may be used. If the version number is not supported by the MAA, it should deregister and not use the API.
6.4.3.13.5 MBMS Client Actions
The getVersion() API returns the version of the implemented APIs of the MBMS client.
6.4.3.13.6 Post-Conditions
No state changes apply.