6.2.3 Methods
26.3473GPPApplication Programming Interface and URLMultimedia Broadcast/Multicast Service (MBMS)Release 17TS
6.2.3.1 Overview
Table 6.2.3.1-1 provides an overview over the methods defined for the File Delivery Application Service API. Different types are indicated, 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 between the MAA (A) and the MBMS client (C) is provided.
Table 6.2.3.1-1: Methods defined for File Delivery Application Service API
|
Method |
Type |
Direction |
Brief Description |
Clause |
|---|---|---|---|---|
|
registerFdApp |
State change |
A -> C |
MAA registers a callback listener with the MBMS client |
6.2.3.2 |
|
deregisterFdApp |
State change |
A -> C |
MAA deregisters with the MBMS client |
6.2.3.9 |
|
startFdCapture |
State change |
A -> C |
Start download of files over file delivery service |
6.2.3.7 |
|
stopFdCapture |
State change |
A -> C |
Stop download of files for the file delivery service |
6.2.3.13 |
|
getFdActiveServices |
Status query |
C <-> A |
Get list of currently active services |
6.2.3.14 |
|
getFdAvailableFileList |
Status query |
C <-> A |
Retrieves the list of files previously captured for the MAA |
6.2.3.12 |
|
getFdServices |
Status query |
C <-> A |
Retrieves the list of File Delivery services defined in the USD |
6.2.3.4 |
|
getFdDownloadStateList |
Status query |
C <-> A |
Retrieves the state of files pending download |
6.2.3.16 |
|
getVersion |
Status query |
C <-> A |
the version of the File Delivery Application Service interface |
6.2.3.21 |
|
setFdServiceClassFilter |
Update to parameter list |
A -> C |
MAA sets a filter on file delivery services in which it is interested |
6.2.3.6 |
|
setFdStorageLocation |
Update to parameter list |
A -> C |
Sets the storage location to store the MAA downloaded files |
6.2.3.5 |
|
registerFdResponse |
Response |
C -> A |
The response to the MAA service register API |
6.2.3.3 |
|
fileAvailable |
Notification |
C -> A |
Notification to MAA when a new file is downloaded per MAA capture request |
6.2.3.8 |
|
fdServiceListUpdate |
Notification |
C -> A |
Notification to MAA on an update of the available for file delivery services |
6.2.3.17 |
|
fdServiceError |
Notification |
C -> A |
Notification to MAA when there is an error with broadcast download of service |
6.2.3.18 |
|
fileDownloadFailure |
Notification |
C -> A |
Notification to MAA that download of a requested file failed |
6.2.3.10 |
|
inaccessibleLocation |
Notification |
C -> A |
Notification to MAA that the storage location set by the MAA is not accessible by the MBMS Client. |
6.2.3.20 |
|
insufficientStorage |
Notification |
C -> A |
Notification to MAA indicating a warning on the low storage condition |
6.2.3.19 |
|
fileDownloadStateUpdate |
Notification |
C -> A |
Notify MAA of a change in the state of pending file downloads |
6.2.3.15 |
|
fileListAvailable |
Notification |
C -> A |
Notify MAA when the list of downloaded files is available to retrieve |
6.2.3.11 |
|
addSA |
State change |
A -> C |
MAA provides a SA file to the MBMS client |
6.2.3.22 |
|
addSAResponse |
Response |
C -> A |
The response to the MAA set SA API |
6.2.3.23 |
6.2.3.2 Registration
6.2.3.2.1 Overview
This clause defines registerFdApp() interface.
An MAA calls the registerFdApp() interface to register with the MBMS Client to consume File Delivery Application Services. The registerFdApp() interface has two purposes:
1) It signals to the MBMS Client that an MAA is interested to consume MBMS services. This registration may be considered as pre-condition for the MBMS Client to keep checking for updates to the File Delivery Application Services defined.
2) It allows the MAA to identify its callback listeners defined in the File Delivery Application Service API for the MBMS Client to provide asynchronous notifications to the MAA on relevant events associated with the reception of files.
Note: Since some application development frameworks do not support callback functions, an MAA for these frameworks will not provide callback listeners in the registerFdApp() 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.2.3.2.1-1 shows a call flow and the usage of the registerFdApp() interface.
Figure 6.2.3.2.1-1: MAA Registration sequence diagram
6.2.3.2.2 Parameters
The parameters for the registerFdApp() API are:
– string appId – provides a unique ID for the application registering with the MBMS client, which uses this identity to maintain state information (e.g., capture requests and captured files) for a particular MBMS Aware Application. The uniqueness of the ID is in the context of any application that may possibly register with MBMS client. Uniqueness is typically provided at the platform level.
– any platformSpecificAppContext – a platform-specific context for the registering application that enables the MBMS client to get extra information about the application that may be need to enable the application to have access to MBMS services, e.g., to enable application authentication or to enable the application 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 application is interested to register. Each service class string can be any string or it may be empty.
– StorageLocation locationPath – identifies a local directory available on the device storage, which the application can access and where successfully collected files can be copied/moved before notifying that the file is available to the application. The storage location is a string pointing to a directory, or it may be empty, if no location is provided.
– unsigned long registrationValidityDuration – the period of time in seconds following the application de-registration (via the application call to deregisterFdApp(), or when the MBMS client detects that the application is no longer running), and possible exit, over which the eMBMS client still considers the application registered for the purpose of fulfilling any outstanding startFileCapture() requests. The default value of this option is 0 (zero) which signals to the MBMS client to clear any outstanding startFdCapture() requests for that application upon its de-registration, and possible exit.
Note 1: The registrationValidityDuration is provided via the registerFdApp(), rather than via a deregisterFdApp(), to handle abnormal application termination conditions (e.g., application crash or it is terminated by the HLOS) before the application has a chance to invoke the deregisterFdApp().
– ILTEFileDeliveryServiceCallback callBack – provides the MBMS client with the call back functions associated with File Delivery Application Service APIs for the registering MBMS Aware Application.
Note 2: The callback element in the IDL description is optional and only included when the application development framework supports programmatic callback interfaces. If callbacks are not supported on a given application development framework, the same information content as defined on the callback structures is to be provided to the application via the notification method available with that development framework when the respective condition is met.
6.2.3.2.3 Pre-Conditions
The application is assigned a unique application ID appId in the context of its operation (e.g., a smartphone HLOS) with the MBMS client.
The application is pre-configured with the set of service classes that allows it to consume the File Delivery Application Services associated with these service classes.
The application manages the storage of requested files, especially the amount of storage to be used.
The application may use this method at launch or after a deregisterFdApp() has been called.
The application assumes the client in IDLE state or CAPTURE_BACKGROUND state.
The MBMS client may be configured to support a maximum _maxRegistrationValidityDuration.
6.2.3.2.4 Usage of Method for Application
The application uses the method registerFdApp() to register with the MBMS Client to consume File Delivery Application Services.
The application provides its appId and, if applicable, some platform specific application context, platformSpecificAppContext.
The application provides the set of service classes which the application is interested to register.
Setting the registrationValidityDuration enables the application to allow the MBMS client to capture files in the background when the application is not currently running; typically after invoking the deregisterFdApp()or after crashing. The application developer should be aware that received files belong to the application and that the MBMS client does not provide content management functions beyond reception and temporary storage of received files in between consecutive runs of the application.
When the application is not interested in receiving files from File Delivery Application Services while the application is not running, the application should set the registrationValidityDuration to 0 (zero). When the application is interested in receiving files from File Delivery Application Services while the application is not running, the application should set the registrationValidityDuration to a non-zero value and it should call the deregisterFdApp() interface before stop running to disable notifications from the File Delivery Services APIs. If the MBMS client can determine that an application has crashed and exited without invoking the deregisterFdApp() interface, the MBMS client will assume that the application had called the deregisterFdApp() before exiting.
On issuing a registerFdApp() following a deregisterFdApp(), the application will include the same serviceClassList used on the last registerFdApp() or setFdServiceClassFilter()to signal interest on the same set of service classes identified before. The application may change the list of registered service classes by providing a serviceClassList as part of a new registerFdApp() request, similarly to using the setFdServiceClassFilter() method.
The application should define a local directory locationPath on the device, where successfully collected files will be copied/moved before making the file available to the application. If no directory is defined, the locationPath should be an empty string.
The application selects a value for the parameter registrationValidityDuration to constrain the amount of storage the MBMS client will use to collect and keep application-requested files in the MBMS client storage space while the application is not currently running (e.g., has de-registered or crashed). The amount of files cached for an application that does not collect its files may impact the MBMS client’s ability to collect files for other applications. In selecting a value for the registrationValidityDuration the following should consider:
– The frequency and amount of files received during the selected registrationValidityDuration. For instance, assuming that 100MB worth of files are delivered every day:
– The application could select a registrationValidityDuration of Nx24h (e.g., N=10) to request the MBMS client to store at most Nx100MB (e.g., 1GB) if the application is not run by the user in Nx24h.
– The application could ask its user (or have a preconfigured behavior on) how long the user wants files to be collected in-between the user’s access to files delivered to the application. If the user selects a long period (e.g., 2months) the application should not use that large values as the registrationValidityDuration (e.g., this could mean 6GB in the example above). Instead, the application should include behaviors to periodically re-register (e.g., every 5days) and collect received files to manage storage of its application files. Leaving those files in the MBMS client storage space (e.g., 6GB) could exceed the MBMS client storage space allowance and impact the reception of files for other applications.
– The relevance of older vs. newer files when managing the storage for files received if the user does not access the application over a long period of time.
– The application could ask the user how much storage to use for received files and whether to delete older files (newer files preferred), or stop new downloads (older preferred), or however else the application choses to support managing received files.
– As described above, in the absence of the user launching the application for File Delivery Application Services with outstanding startFdCapture() requests, that application should automatically re-register (e.g., every 5days as discussed above) with the MBMS client with a periodicity not greater than registrationValidityDuration and retrieve files captured during the period the application was not currently registered.
– The application should then manage the downloaded files with respect to the amount of storage consumed by files of that application. For instance, the application may prioritize retaining newer versus older files or let the registrationValidityDuration expire (therefore causing the MBMS client to stop continued file downloads for that application) if the user does not consume file contents for that application.
Example 1: Daily headline news application allows the user to collect files from two File Delivery Application Services with new/updated video clip files downloaded twice every day.
– The application registrationValidityDuration is 2days, it re-registers with the MBMS client every 1.5 days and it keeps only the files that are no more than two days old, e.g., as configured by the user.
Example 2: Weekly magazine application allows the user to collect files from a File Delivery Application Service with new/updated files for selected electronic versions of weekly magazines downloaded once a week.
– The application registrationValidityDuration is 15 days, it re-registers with the MBMS client every 7 days and it keeps only the files that are no more than three weeks old, e.g., as configured by the user.
6.2.3.2.5 Expected MBMS Client Actions
When this method is received, the MBMS client registers the app. For more details refer to clause 6.2.2.3.
6.2.3.2.6 Post-Conditions
The application expects a registerFdResponse() as defined in clause 6.2.3.3.
6.2.3.3 File Delivery Application Service Registration Response
6.2.3.3.1 Overview
This subclause defines the registerFdResponse() call.
As illustrated in Figure 6.2.3.2.1-1, the MBMS client responds to an MAA call to the registerFdApp() API with a registerFdResponse() call back providing the result of the registration request.
6.2.3.3.2 Parameters
The parameters for the registerFdResponse() 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 application can proceed with other API interactions with the MBMS client for File Delivery Application Services.
– FAILED_LTE_EMBMS_SERVICE_UNAVAILABLE – Indicates that the registration has failed since the File Delivery Application Service API did not find an MBMS client available on the UE on which the application is running and no MBMS service will be available to the application.
– MISSING_PARAMETER – indicates that the registration has failed since one or more of the required parameter was missing.
– string message – provides an associated text description of the error message. The message may be empty.
– unsigned long acceptedFdRegistrationValidityDuration – when returning REGISTER_SUCCESS, this parameter indicates the registration validity duration the MBMS client will provide to the registering application.
6.2.3.3.3 Pre-Conditions
The MBMS client has received a call via the registerFdApp() API with the parameters documented in clause 6.2.3.2.2.
6.2.3.3.4 Expected MBMS Client Actions
Based on the parameters of the registerFdApp(), the MBMS client provides the response and changes the state. For more details see clause 6.2.2.3.
6.2.3.3.5 Usage of Method for Application
Once the application receives a the registerFdResponse() with the RegResponseCode set to REGISTER_SUCCESS, the application can proceed with other API interactions with the MBMS client, for instance, by issuing startFdCapture() requests.
Based on the response in acceptedFdRegistrationValidityDuration the application should adjust its expectations accordingly if the value returned is not what was requested.
If the MBMS client is temporarily in NOT_AVAILABLE, if the registerFdResponse() signaled a failure with a FAILED_LTE_EMBMS_SERVICE_UNAVAILABLE, the application may periodically recheck if the state of the MBMS client changes by retrying the registerFdRequest() API.
6.2.3.3.6 Post-Conditions
If the MBMS client functions cannot be activated and once the response is sent with a FAILED_LTE_EMBMS_SERVICE_UNAVAILABLE, then MBMS client is at least temporarily in NON_AVAILABLE state.
If the MBMS client functions cannot be activated and once the response is sent with a MISSING_PARAMETER, then MBMS client is at least temporarily in IDLE state.
If the MBMS client functions can be activated and a response is sent with REGISTER_SUCCESS, then MBMS client is in REGISTERED state with the REGISTERED state parameters as set above.
6.2.3.4 Getting information on available File Delivery Application Services
6.2.3.4.1 Overview
This clause defines the getFdServices() interface.
The getFdServices() interface returns the complete list of available File Delivery Application Services information. After a successful registration with the MBMS client, the MBMS Aware Application can use the getFdServices() API to discover the available File Delivery Application Services associated with the service classes registered via the registerFdApp(). Also the MBMS client may use the getFdServices() API after receiving a fdServiceListUpdate() call back notification to changes to the available File Delivery Application Services.
6.2.3.4.2 Parameters
The getFdServices() API does not have any input parameters.
The getFdServices() API returns a list describing the available File Delivery Application Service, 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 IETF 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 IETF RFC 3066 [10].
– EmbmsCommonTypes::ServiceAvailabilityType serviceBroadcastAvailability – signals whether the UE is currently in the broadcast coverage area for the service.
– The possible values are for a File Delivery Application Service:
– -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.
– sequence<string> fileUriList – optionally provides a list of file names for the files that are currently scheduled to be transmitted.
– EmbmsCommonTypes::Date activeDownloadPeriodStartTime – signals the current/next active File Delivery Application Service start time, when files start being broadcast over the air.
– EmbmsCommonTypes::Date activeDownloadPeriodEndTime – signals the current/next active File Delivery Application Service stop time, when files stop being broadcast over the air.
Note that the available File Delivery Application Service list may be empty.
6.2.3.4.3 Pre-Conditions
The MBMS client is in REGISTERED state or in CAPTURE_NOTIFY state and may or may not have acquired any USD information for services that are included in the service class list.
The MBMS client may have updated internal _service[] list.
6.2.3.4.4 Expected MBMS Client Actions
When this method is received, the MBMS client returns its internal parameters. For more details see clause 6.2.2.3.
6.2.3.4.5 Usage of Method for Application
The usage of the parameters serviceNameList, serviceClass, serviceBroadcastAvailability, and serviceLanguage is typically up to the application.
The fileUriList may be used by the application for selective file reception, e.g. when used together with startFdCapture() as defined in clause 6.2.3.7.
The application should use this call right after the registerFdResponse() notification as defined in clause 6.2.3.3 is received or after the fdServiceListUpdate() notification as defined in 6.2.3.17 is received.
The application shall use the serviceId to identify the service in subsequent communication with the MBMS client to manage the files to be captured on that service for the application.
The parameters activeDownloadPeriodStartTime and activeDownloadPeriodEndTime provides the application the ability to determine the current broadcast state for the service as follows:
– If the current time is such that activeDownloadPeriodStartTime ≤ current time ≤ activeDownloadPeriodEndTime, files may be captured for the service at the current time.
– If the activeDownloadPeriodStartTime is in the future, there is currently file capturing expected for the service, but delivery is currently scheduled to start at this advertised time.
– If the activeDownloadPeriodStartTime is set to zero, there is no currently defined broadcast schedule time for the service.
– If the activeDownloadPeriodEndTime is in the past, or there are no activeDownloadPeriodStartTime and no activeDownloadPeriodEndTime defined for the service, then there is currently no broadcast being made for the service, and there is no currently scheduled broadcast time for the service.
6.2.3.4.6 Post-Conditions
This call does not change the MBMS client state.
6.2.3.5 Establishing the location where files are stored for an application
6.2.3.5.1 Overview
This clause defines setFdStorageLocation().
While an application is actively registered with the MBMS client to consume File Delivery Application Services, the MBMS Aware Application can call the setFdStorageLocation() API to set or update the location where files collected for the application are to be stored. This message flow is shown in Figure 6.2.3.5.1-1.
Figure 6.2.3.5.1-1: Sequence diagram for updating the storage location for collected files
6.2.3.5.2 Parameters
The parameters for the setFdStorageLocation() method are:
– StorageLocation locationPath – see clause 6.2.3.2.2.
6.2.3.5.3 Pre-Conditions
The application is registered with the MBMS client to consume File Delivery Application Services, and MBMS client is in REGISTERED or CAPTURE_NOTIFY state.
6.2.3.5.4 Usage of Method for Application
The MBMS Aware Application may invoke the setFdStorageLocation() API call to update the previously defined storage location. This includes the case that the storageLocation was not set previously.
It may also use this API call if it receives an insufficient storage notification as defined in clause 6.2.3.19.
6.2.3.5.5 Expected MBMS Client behaviour
When this method is received, the MBMS client updates the internal parameters and notifies the client. For more details see clause 6.2.2.3.
6.2.3.5.6 Post-Conditions
The MBMS client internal variable _locationPath for this application is updated. No state change is applied.
6.2.3.6 Updating the registered service classes
6.2.3.6.1 Overview
This clause defines setFdServiceClassFilter().
While an application is actively registered with the MBMS client to consume File Delivery Application Services, the MBMS Aware Application can call the setFdServiceClassFilter() API to update the list of service classes the application wants to be registered with, see Figure 6.2.3.6.2-1.
Figure 6.2.3.6.2-1: Sequence diagram for updating the registered service classes for an application
6.2.3.6.2 Parameters
The parameters for the setFdServiceClassFilter() method are:
– sequence<string> serviceClassList – see clause 6.2.3.2.2.
6.2.3.6.3 Pre-Conditions
The application is actively registered with the MBMS client to consume File Delivery Application Services, and MBMS client is in REGISTERED state or CAPTURE_NOTIFY for the application.
6.2.3.6.4 Usage of Method for Application
The MBMS Aware Application may invoke the setFdServiceClassFilter() API to update the previously defined list of service classes that includes additional service classes or includes fewer service classes than the list of service classes.
The application should be aware that the updates are only active once an fdServiceListUpdate() notification is received that confirms the new service class filters.
6.2.3.6.5 Expected MBMS Client Actions
When this method is invoked, the MBMS client updates the internal parameters and notifies the client.
6.2.3.6.6 Post-Conditions
The MBMS client issues an fdServiceListUpdate() notification as defined in clause 6.2.3.17. No state change is applied.
6.2.3.7 Start File Delivery Capture
6.2.3.7.1 Overview
This clause defines the startFdCapture() API.
Once the File Delivery Application Service registration is complete, the MBMS Aware Application can make calls on the startFdCapture() API to selected fileURIs for the files to be received through the MBMS service as shown in Figure 6.2.3.7.1-1.
Figure 6.2.3.7.1-1: File Delivery Application Start Capture
6.2.3.7.2 Parameters
The parameters for the startFdCapture() API are:
– string serviceId – see clause 6.2.3.4.2. The service ID for the service for which the files are captured.
– string fileUri – identifies the files to be captured on the service identified in serviceId. Allowed values include:
– The empty string signals that the MAA is interested in receiving all new files and updates to previously received files.
– A BaseURL, i.e., a complete path for subdirectory (a prefix) identifying a group of files under that directory.
– An absoluteURL, i.e., a complete URL that identifies a single file resource.
– boolean disableFileCopy – when set to true, this signals that the MAA does not want the MBMS client to make the file available on the MAA space.
– boolean captureOnce – when set to true, signals that the file requested via the fileURI (or a file matching a BaseURL in fileURI, or any file if the fileURI is empty) is to be captured only once.
6.2.3.7.3 Pre-Conditions
The application is registered with the MBMS client to consume File Delivery Application Services.
The fileURI format is not validated by the MBMS client.
6.2.3.7.4 Usage of Method for Application
The MBMS Aware Application can make calls on the startFdCapture() API to the select file URIs for the files to be received through the MBMS service with service ID serviceId. It is recommended that http:// or file system names c:/user/… be used as file URIs.
An application may set the fileURI parameter to different values:
– An empty string signals that the application is interested in receiving all new files and updates to previously received files.
– If the fileURI is set to a Base URL as defined in RFC 3986 [11], the application may organize its files in a structured way (in a directory) such as to allow the identification of a group of files. For instance, a headline news clips application may group files under a …\sports\, a …\politics\, etc. folder and allow the user to select what type of headline news of interest and therefore request the MBMS client to capture all the files under …\sports\ if the user is only interested in sports headline news.
– An absolute URL, i.e., a complete URL that identifies a single file resource. A software update application on a given OEM device model may be preconfigured with an absolute URL for the file name that identifies the software image for that device model. That application would use that absolute URL as the file URI when request that its software image be received on a File Delivery Application Service.
The application should avoid overlap requests, e.g. requesting a fileURI and at the same time the Base URL that matches the fileURI.
The application may use the getFdActiveServices() API as defined in clause 6.2.3.14 to get back in synch with fileURI in remaining outstanding startFdCapture() requests.
When application is no longer interested in capturing specific files, it should call the stopFdCapture() interface as defined in clause 6.2.3.13.
A software update application on a given OEM device model may be preconfigured with an absolute URL for the file name that identifies the software image for that device model. That application would use that absolute URL as the file URI when request that its software image be received on a File Delivery Application Service.
6.2.3.7.5 Expected MBMS Client Actions
When this method is received, the MBMS client updates the internal parameters. For more details see clause 6.2.2.4.
6.2.3.7.6 Post-Conditions
The MBMS client is in CAPTURE_NOTIFY state for the requested serviceID.
The parameters of the MBMS client are updated.
After capturing the files requested on a startFdCapture() request, the MBMS Client prepares to send fileAvailable() notification as defined via the registered callback listener.
6.2.3.8 File Available Notification
6.2.3.8.1 Overview
This clause defines the fileAvailable() callback function.
As illustrated in Figure 6, once the MBMS client has successfully collected a file that matches an outstanding startFdCapture() request from an MBMS Aware Application, the MBMS client invokes the fileAvailable() callback function.
6.2.3.8.2 Parameters
The parameters for the fileAvailable() API are:
– string serviceId – definition see above.
– The following is the file information for the received file:
– string fileUri – identifies the file captured on the service identified in serviceId.
– string fileLocation – identifies the location where the MBMS Aware Application can find the collected file.
– string contentType – indicates the MIME type for the file identified in the fileUri.
– unsigned long availabilityDeadline – signals a deadline in seconds when the file stored at the fileLocation will be removed from the MBMS client storage location.
6.2.3.8.3 Pre-Conditions
The MBMS client is in CAPTURE_NOTIFY state for the serviceId.
The MBMS client has successfully received a file that is included in a _fileCaptureRequest[] record. Reception may be through broadcast only or may include unicast repair.
The MBMS client internal variable _locationPath may be defined or may not be defined.
The MBMS client has pre-configured an internal parameter defaultAvailabilityDeadline defining the time a file that is kept in the MBMS client owned storage location.
6.2.3.8.4 Expected MBMS Client Actions
The MBMS client invokes the fileAvailable() notification for each successfully received file that matches a _fileCaptureRequest[] and is included in the _fileURIStatus[]record. For more details see clause 6.2.2.5.
6.2.3.8.5 Usage of Method for Application
Once the application receives the callback, the application may access the file that is announced by the parameters in the callback function. If the storage is not defined by the locationPath application should access the file before the announced availabilityDeadline.
An MBMS Aware Application can retrieve the file using the HTTP GET method if the fileLocation is an HTTP URL.
The MBMS Aware Application needs to arrange for a copy of the file to the application space if the application intends to have access to the file beyond an availabilityDeadline indicated. The file may no longer be accessible after this time
6.2.3.8.6 Post-Conditions
The file is available at the location defined by the fileLocation parameter.
6.2.3.9 File Delivery Application Service De-registration
6.2.3.9.1 Overview
This clause defines the deregisterFdApp() call.
An MAA registers services classes with the MBMS client to request the capture of files on File Delivery Application Services, but the MAA does not have to be currently registered while files are being captured as discussed earlier. The MAA may deregister using the deregisterFdApp() call.
6.2.3.9.2 Parameters
None.
6.2.3.9.3 Pre-Conditions
The MBMS client is in REGISTERED or in CAPTURE_NOTIFY state for this application.
6.2.3.9.4 Usage of Method for Application
MBMS Aware Application registered with the MBMS client via the registerFdApp() API should invoke the deregisterFdApp() before exiting.
If the application deregisters, it will no longer receive notifications from the MBMS client. However, the MBMS client still captures files in the background until the registrationValidityDuration expires.
Nevertheless, the absence of notifications may result in unreceived files, if the MBMS client observes problems, e.g. not being able to access the storage location or the MBMS client having insufficient storage. Hence, the application should continuously check if the storage is still sufficient and accessible, even if is deregistered.
6.2.3.9.5 Expected MBMS Client Actions
The MBMS client no longer sends notifications.
If open file capture requests exist, the MBMS client continues collection files in the background until the time for _registrationValidityDuration expires.
For more details see 6.2.2.4.
6.2.3.9.6 Post-Conditions
The MAA is no longer registered with the MBMS client to receive notifications.
The MBMS client is either in IDLE mode or in CAPTURE_BACKGROUND mode.
6.2.3.10 File Download Failure Notification
6.2.3.10.1 Overview
This clause defines the fileDownloadFailure()callback function.
As illustrated in Figure 6.2.3.10.1-1, once the MBMS client has attempted to collect symbols for a file (possibly even via the unicast file repair procedure), that match an outstanding startFdCapture() request from an MAA, the MBMS client may still not be able to recover the file. Once the MBMS client detects that it failed FEC decoding the file, the MBMS client invokes the fileDownloadFailure() callback function (which the application registered with the MBMS client.
Figure 6.2.3.10.1-1: Signaling download failures
6.2.3.10.2 Parameters
The parameters for the fileDownloadFailure() API are:
– string serviceId – identifies the File Delivery Application Service on.
– string fileUri – identifies the file which failed being received.
6.2.3.10.3 Pre-Conditions
The MBMS client is in CAPTURE_NOTIFY state for the serviceId.
6.2.3.10.4 Expected MBMS Client Actions
The MBMS client provides the fileAvailable() function for each non-successfully received file that matches a _fileCaptureRequest[] and is included in the _fileURIStatus[] record.
6.2.3.10.5 Usage of Method for Application
The application may use this information to identify other ways to access the file, or initiate actions to operate without this file.
6.2.3.10.6 Post-Conditions
The MBMS client may remain in CAPTURE_NOTICE state or if this was the last outstanding capture request it may move to REGISTERED state for the serviceId.
6.2.3.11 File List Available Notification
6.2.3.11.1 Overview
This clause defines the fileListAvailable()callback function.
As illustrated in figure 6, an MBMS Aware Application that is registered when a requested file is successfully received is notified of the availability of the new file via the fileAvailable() API.
Figure 6.2.3.11.1-1 illustrates what happens when an application registers to consume File Delivery Application Services with a non-zero registrationValidityDuration, asks different files to be captured (possibly from different File Delivery Application Services), and then de-registers.
During the registration validity duration period following the application de-registration, the MBMS client collects files matching the outstanding capture requests from the application and keeps the files in its cache while the application is not currently registered.
Figure 6.2.3.11.1-1: Sequence diagram for notifying the application about collected files
6.2.3.11.2 Parameters
The parameters for the fileListAvailable() API are:
– string serviceId – identifies the File Delivery Application service.
6.2.3.11.3 Pre-Conditions
The MBMS client is in CAPTURE_NOTIFY mode.
The MBMS client does have an _fileURIStatus[] entry for which the _notified flag is set to false
6.2.3.11.4 Expected MBMS Client Actions
The MBMS client invokes the fileListAvailable() notification with the following parameters:
– The serviceId is set to the _serviceID.
6.2.3.11.5 Usage of Method for Application
The application receiving this notification may then ask the client on the status of the file list using the getFdDownloadStateList() method defined in clause 6.2.3.16.
6.2.3.11.6 Post-Conditions
No state change is involved.
6.2.3.12 Getting the List of Available Files
6.2.3.12.1 Overview
This clause defines the getFdAvailableFileList() request.
As illustrated in Figure 6.2.3.12.1-1, once the MBMS Aware Application re-registers with the MBMS client, the MBMS client may indicate through the fileListAvailable() callback function to the application know that a list of files have been received for a service and are now ready to be accessed.
That application can then invoke the getFdAvailableFileList() API to retrieve information on these received files.
6.2.3.12.2 Parameters
The parameters for the getFdAvailableFileList() API are:
– Input parameters:
– string serviceId – identifies the File Delivery Application Service on for which the application requests the available file list.
– Output parameters
– A list for records, each containing:
– string fileUri – identifies the file captured on the service identified in serviceId.
– string fileLocation – identifies the location where the MBMS Aware Application can find the collected file.
– string contentType – indicates the MIME type for the file identified in the fileUri.
– unsigned long availabilityDeadline – signals a deadline in seconds when the file stored at the fileLocation will be removed from the MBMS client storage location, if applicable.
6.2.3.12.3 Pre-Conditions
The MBMS client is in CAPTURE_NOTIFY state for the serviceId.
The MBMS client has indicated through the fileListAvailable() callback function to the application know that a list of files have been received for a service and are ready to be accessed.
The MBMS client has pre-configured an internal parameter defaultAvailabilityDeadline defining the time a file that is kept in the MBMS client owned storage location.
6.2.3.12.4 Usage of Method for Application
The application may use this method in order to retrieve information on the received files.
Once the application receives the response, the application may access the files that are announced by the parameters in the callback function. If the storage is not defined by the locationPath the application should access the file before the announced availabilityDeadline.
6.2.3.12.5 Expected MBMS Client Operation
When this method is invoked, the MBMS client provides the file parameters as defined above.
6.2.3.12.6 Post-Conditions
The MBMS client has notified the application about all accessible files.
6.2.3.13 Stop File Delivery Capture
6.2.3.13.1 Overview
This clause defines the stopFdCapture() request.
The application can make startFdCapture() calls to define fileURIs for the files to be received within an MBMS Service. The application may use the use the stopFdCapture()request to undo such a call and stop capturing such requested files. This is shown in Figure 6.2.3.13.1-1.
Figure 6.2.3.13.1-1: File Delivery Application Stop Capture
6.2.3.13.2 Parameters
The parameters for the stopFdCapture() API are identical to the parameters for startFdCapture() as defined in clause 6.2.3.7.2.
6.2.3.13.3 Pre-Conditions
The MBMS client is in CAPTURE_NOTIFY state.
6.2.3.13.4 Usage of Method for Application
The application may use this request to undo such a call and stop capturing such requested files.
The application should cache the requested fileURIs and use the stopFdCapture() API to signal to the MBMS client when the application no longer wishes to receive files matching the fileURIs on earlier capture requests.
If the MBMS Aware application has not properly cached the list of fileURIs on its outstanding startFdCapture() requests, the application should invoke the getFdActiveServices() API described in clause 6.2.3.4 to re-synchronize on its outstanding startFdCapture() requests.
6.2.3.13.5 Expected MBMS Client Actions
Upon receiving a stopFdCapture() the MBMS client updates its internal parameters and sends notifications, if applicable.
6.2.3.13.6 Post-Conditions
Entries in the _fileCaptureRequest[] record may be removed. If by this action the _fileCaptureRequest[] gets empty, the MBMS client changes to REGISTERED state.
6.2.3.14 Getting the list of outstanding fileURIs being captured
6.2.3.14.1 Overview
This clause defines the getFdActiveServices() request.
Figure 6.2.3.14.1-1 illustrates that the application may also invoke the getFdActiveServices() API to retrieve the fileURI for outstanding startFdCapture() requests.
Figure 6.2.3.14.1-1: Sequence diagram for an application to collect info on outstanding startFdCapture() requests
6.2.3.14.2 Parameters
The parameters for the getFdAvailableFileList() API are:
– Input parameters:
– string serviceId – identifies the File Delivery Application Service on for which the application requests outstanding startFdCapture() requests.
– Output parameters:
– A list for records, each containing:
– string fileUri – as defined in clause 6.2.3.7.2.
6.2.3.14.3 Pre-Conditions
The MBMS client is in CAPTURE_NOTIFY state.
6.2.3.14.4 Usage of Method for Application
The application may also invoke the getFdActiveServices() API to retrieve the fileURI for outstanding startFdCapture() requests.
It is recommended that especially after a new registration or once a more recent startFdCapture() with a BaseURL superseded an earlier startFdCapture() with an AbsoluteURL.
6.2.3.14.5 MBMS Client Actions
When this method is invoked, the MBMS client provides the parameters in the call.
6.2.3.14.6 Post-Conditions
This call does not change any state or internal parameters of the MBMS client.
6.2.3.15 Notification on state change for files
6.2.3.15.1 Overview
This clause defines the fileDownloadStateUpdate()callback function.
As illustrated in Figure 6.2.3.15.1-1, after an MBMS Aware Application registers with the MBMS client and requests that files are to be captured, the MBMS client may issue fileDownloadStateUpdate() notifications to an application to signal that the state the MBMS client maintains for file(s) received or being received for the application has changed.
Figure 6.2.3.15.1-1: Sequence diagram for notifying the application about changes to the state of files being collected
6.2.3.15.2 Parameters
The parameters for the fileDownloadStateUpdate()callback function are:
– string serviceId – identifies the File Delivery Application Service on for which a new status is indicated.
6.2.3.15.3 Pre-Conditions
The MBMS client is in the CAPTURE_NOTIFY state.
6.2.3.15.4 Expected MBMS Client Actions
The MBMS client may invoke this method whenever the in the internal _fileURIStatus[] was changed.
6.2.3.15.5 Usage of Method for Application
If the application receives this callback notification, it should issue a getFdDownloadStateList().
6.2.3.15.6 Post-Conditions
No state change is happening, but the application is aware that it can receive updated information from the MBMS client.
6.2.3.16 Getting the state on file(s) received or being received
6.2.3.16.1 Overview
This clause defines the getFdDownloadStateList()request function.
An MBMS Aware application may be interested to retrieve the current state for files downloaded or being downloaded by the MBMS client on behalf of that application. The application may choose to request this information in response to a notification from the MBMS client of such state change via a fileDownloadStateUpdate() notification, but also in other cases.
6.2.3.16.2 Parameters
The parameters for the getFdDownloadStateList() API are:
– Input parameters:
– string serviceId – identifies the File Delivery Application Service on for which the application requests the available file list.
– Output parameters:
– A list for records, each containing:
– string fileUri – identifies the file captured on the service identified in serviceId.
– DownloadState state – state of the file identified by the fileUri. The value can be as follows:
– FD _REQUESTED – capture is requested, but file is neither scheduled nor is reception in process. This may for example be the case if the reception has failed, so the capture request stays open.
– FD_SCHEDULED – scheduled, if a file schedule is delivered and a file is scheduled, but not yet received.
– FD_IN_PROGRESS – the reception of the file is in progress.
6.2.3.16.3 Pre-Conditions
The MBMS client is in CAPTURE_NOTIFY state.
6.2.3.16.4 Usage of Method for MAA
An MAA may be interested to retrieve the current state for files downloaded or being downloaded by the MBMS client on behalf of that MAA. The MAA may choose to request this information in response to a notification from the MBMS client of such state change via a fileDownloadStateUpdate() notification.
The MAA may also detect via updated service definition information (i.e., via a fdServiceListUpdate() followed by a getFdServices()) that a file previously advertised on an earlier getFdServices() and which the MAA requested to be capture is no longer described on the information retrieved via the latest getFdServices(), and the MAA did not receive a fileAvailable() or a fileDownloadFailure() reporting the successful or failed reception of the requested file, respectively. This could happen because the requested file is no longer advertised as available for request (there is no current of future transmission for the file described on a fileSchedule in the schedule description fragment), but the file is still pending file repair.
An interested MAA can request information on the current state for files requested to be downloaded by the MBMS client on behalf of that MAA by invoking the getFdDownloadStateList() API.
6.2.3.16.5 Expected MBMS Client Actions
When this API call is received, the MBMS client provides the state of all files for which a capture request is issued.
6.2.3.16.6 Post-Conditions
There is no state change involved in the client.
6.2.3.17 Notification of updates to the service definition
6.2.3.17.1 Overview
This clause defines the fdServiceListUpdate()callback function.
As illustrated in Figure 6.2.3.15.1-1, after an MBMS Aware Application registers with the MBMS client and possibly requests that files are to be captured, the MBMS client may issue fdServiceListUpdate() notifications to an application to signal that there have been changes to the definition of File Delivery Application Services associated with the service classes the application has registered with the MBMS client.
6.2.3.17.2 Parameters
none
6.2.3.17.3 Pre-Conditions
The MBMS client is in REGISTERED or CAPTURE_NOTIFY mode.
6.2.3.17.4 Expected MBMS Client Operation
The MBMS client invokes this notification when there has been a change to the parameters reported to the application in response to a getFdServices() API.
6.2.3.17.5 Usage of Method for Application
In response to a fdServiceListUpdate() API notification from the MBMS client, the MBMS Aware application should invoke a getFdServices() API and process the updated information accordingly.
6.2.3.17.6 Post-Conditions
There is no change in the client state.
6.2.3.18 Notification of File Delivery Application Service errors
6.2.3.18.1 Overview
This clause defines the fdServiceError() callback function.
As illustrated in Figure 6.2.3.18.1-1, the startFdCapture() request from an MBMS Aware Application may not be served, so the MBMS client will send a failure indication via the fdServiceError() to signal the error code for the result of processing the application’s startFdCapture().
Figure 6.2.3.18.1-2 also illustrates that the fdServiceError() is used to signal the error code for the result of processing the application’s stopFdCapture() request.
Figure 6.2.3.18.1-1: Signaling errors with the startFdCapture() request from the MBMS Aware Application
Figure 6.2.3.18.1-2: Signaling errors with the stopFdCapture() request from the MBMS Aware Application
6.2.3.18.2 Parameters
The parameters for the fdServiceError() callback are:
– string serviceId – identifies the File Delivery Application service for which this notification applies.
– FdErrorCode errorCode – identifies the error code for the reason causing the startFdCapture() or the stopFdCapture() request for the serviceId and fileUri to fail. The available error codes are:
– FD_INVALID_SERVICE – signals that serviceID defined on the startFdCapture() or the stopFdCapture() request is not currently defined or it is not associated with the service classes with the MBMS Aware Application is registered.
– FD_DUPLICATE_FILE_URI – signals that fileUri defined on the startFdCapture() request has already been requested on a previous startFdCapture() request. This is a duplicate request and the previous request is still in effect, i.e., impact to that earlier request. The MBMS client will not signal this error for the same condition on a stopFdCapture() request.
– FD_AMBIGUOUS_FILE_URI – signals that fileUri defined on the startFdCapture() or the stopFdCapture() request creates ambiguity with a previously issued startFdCapture() or stopFdCapture() request. See clauses 6.2.3.7 and 6.2.3.13 for details on the conditions when this error code is generated for the startFdCapture() and the stopFdCapture() request, respectively.
– FD_STOP_FILE_URI_NOT_FOUND – signals that the indicated fileURI does not match an outstanding startFdCapture() request.
– FD_UNKNOWN_ERROR – signals an error condition not explicitly identified.
– string errorMsg – may provide additional textual description of the error condition.
6.2.3.18.3 Pre-Conditions
The MBMS client is in REGISTERED or CAPTURE_NOTIFY mode.
6.2.3.18.4 Expected MBMS Client Actions
If a startFdCapture() or a stopFdCapture() request from an MBMS Aware Application may not be served, the MBMS client will send a failure indication via the fdServiceError() to signal the error code for the result of processing
6.2.3.18.5 Usage of Method for Application
If the application receives such a notification, it should check the capture requests and possibly also invoke the getFdActiveServices() API call to re-synchronize on its outstanding startFdCapture()requests.
6.2.3.18.6 Post-Conditions
No state change applies.
6.2.3.19 Notification on storage limitations
6.2.3.19.1 Overview
This clause defines the insufficientStorage() callback function.
As illustrated in Figure 6.2.3.19.1-1, once a file is to be received for an MBMS Aware Application (at a scheduled transmission time for the respective File Delivery Application Service), the FDT for the FLUTE session for that service will signal the size for that file.
When the MBMS client detects that not enough storage is available on the UE to receive the file, the MBMS client will send the warning indication via the insufficientStorage() API to signal the application of the low storage condition. The application may be able to clean up some of its own files or alert the user to clean up storage space on the UE.
Figure 6.2.3.19.1-1: Signaling a low storage level condition impacting a file download
6.2.3.19.2 Parameters
The parameters for the insufficientStorage() callback are:
– string serviceId – identifies the File Delivery Application service for which this notification applies.
– string fileUri – identifies the file being transmitted on the File Delivery Application Service in serviceId which the MBMS client has started to capture and that will fail download because of insufficient storage on the UE.
– StorageLocation locationPath – identifies a local directory available on the device storage, which the application can access and where successfully collected files can be copied/moved before notifying that the file is available to the application. The storage location is a string pointing to a directory, or it may be empty, if no location is provided.
– unsigned long storageNeeded – indicates the additional storage space that needs to be cleared on the storage Path to enable the download of the file in fileURI to succeed.
– string errorMsg – may provide additional textual description of the error condition.
6.2.3.19.3 Pre-Conditions
The MBMS client is in CAPTURE_NOTIFY state.
6.2.3.19.4 Expected MBMS Client Actions
The insufficientStorage() API is invoked for the applications that are currently registered at the time that the low storage condition is detected.
6.2.3.19.5 Usage of Method for Application
If the MBMS-aware application receives such a notification, it should take appropriate measures to enable to continue the service. This may include to change the service location, clear some storage autonomously or to communicate with the user to release storage.
6.2.3.19.6 Post-Conditions
No state changes occur.
6.2.3.20 Notification on storage access issues
6.2.3.20.1 Overview
This clause defines the inaccessibleLocation() callback function.
As illustrated in Figure 6.2.3.20.1-1, the locationPath where the MAA registered to have its requested files copied may not be available (e.g., SD card not inserted/locked). When the MBMS client detects that the register locationPath is not accessible, the MBMS client will send the warning indication via the inaccessibleLocation() API to signal the MAA of the storage access limitation; this can be done at different times, e.g., following a startFdCapture() as illustrated in Figure 6.2.3.20.1-1. The MAA may select an alternative locationPath, or prompt the user to choose another locationPath. The MAA can notify the MBMS client of the new locationPath via the setFdStorageLocation() API.
Figure 6.2.3.20.1-1: Signaling a storage access condition limitation impacting file download
6.2.3.20.2 Parameters
The parameters for the inaccessibleLocation()callback are:
– string serviceId – identifies the File Delivery Application service for which this notification applies.
– StorageLocation locationPath – indicates the storage location where files are to be stored per the registered locationPath at the time that the download started, which is not accessible by the MBMS client.
– string errorMsg – may provide additional textual description of the error condition.
6.2.3.20.3 Pre-Conditions
The MBMS client is in CAPTURE_NOTIFY state.
6.2.3.20.4 Expected MBMS Client Actions
The inaccessibleLocation() API is only invoked for the applications that are currently registered at the time that the storage inaccessible condition is detected.
6.2.3.20.5 Usage of Method for Application
If the application receives this notification, the application should take appropriated measures. It may for example change the location or may alert the user that the storage is not accessible.
6.2.3.20.6 Post-Conditions
No state change is applied, but the MBMS client may fail to receive files .
6.2.3.21 Checking the version for File Delivery Application Service interface
6.2.3.21.1 Overview
This clause defines the getVersion() request function.
6.2.3.21.2 Parameters
The parameters for the getVersion()API call are:
– string version – identifies the version of the MBMS clients API implementation.
6.2.3.21.3 Pre-Conditions
The MBMS client may be in any state.
6.2.3.21.4 Operation of Method in MBMS Client
The getVersion() API returns the version of the implemented APIs of the MBMS client.
6.2.3.21.5 Usage of Method for Application
In order for the MBMS Aware Application to know the version of the File Delivery Application Service interface, the getVersion() API may be used. If the version number is not supported by the application, it should deregister and not use the API.
6.2.3.21.6 Post-Conditions
Note state change applies.
6.2.3.22 Add SA file
6.2.3.22.1 Overview
This clause defines addSA() interface.
An MAA calls the addSA() interface to provide SA file to the MBMS Client.
Figure 6.2.3.22.1-1 shows a call flow and the usage of the addSA() interface.
Figure 6.2.3.22.1-1: Add SA file sequence diagram
6.2.3.22.2 Parameters
The parameter for the addSA() API is:
– string saFileLocation – identifies the location where the MBMS Client can find the SA file, following the profile 1c (Annex L.3 of 3GPP 26.346 [2]).
– string mimeType – identifies the mimeType and profile of the SA file. If not present, the SA file shall conform to the profile 1c (Annex L.3 of 3GPP 26.346 [2]).
6.2.3.22.3 Pre-Conditions
The application is registered with the MBMS client to consume File Delivery Application Services.
6.2.3.22.4 Usage of Method for Application
The application uses the method addSA() to provide additionnal service announcement information to the MBMS Client.
6.2.3.22.5 Expected MBMS Client Actions
When this method is received, the MBMS client reads the SA file from the location given by the saFileLocation parameter and parses it.
The MBMS Client
– adds the new MBMS user services announced by the SA file to the internal _service[] list for the invoking MAA;
– updates the MBMS user services announced by the SA file whose service ID is already included with the _service[] list for the invoking MAA.
Note: the internal _service[] lists for the other MAA are unchanged.
6.2.3.22.6 Post-Conditions
The application expects a addSAResponse() as defined in clause 6.2.3.23.
6.2.3.23 Add SA file Response
6.2.3.23.1 Overview
This subclause defines the addSAResponse() call.
As illustrated in Figure 6.2.3.22.1-1, the MBMS client responds to an MAA call to the addSA() API with a addSAResponse() call back providing the result of addition of the SA file.
6.2.3.23.2 Parameters
The parameters for the addSAResponse() API are:
– EmbmsCommonTypes::AddSAresponseCode value – provides a result code on the registration request. The allowed values are:
– SUCCESS – indicates that the SA file has been parsed and the announced MBMS user service have been added to the internal _service[] list.
– SA_FILE_INVALID – indicates that the SA file can not be parsed according the announced profile
– string message – provides an associated text description of the error message. The message may be empty.
6.2.3.23.3 Pre-Conditions
The MBMS client has received a call via the addSA() API with the parameters documented in subclause 6.2.3.23.2.
6.2.3.23.4 Usage of Method for Application
If the MBMS-aware application receives such a notification with the response code set to SA_FILE_INVALID, the application may inform the application user or the content provider that the SA file could not be imported by the MBMS client.
6.2.3.23.5 Expected MBMS Client Actions
The parameters of the MBMS client are updated. The MBMS client may issue an fdServiceListUpdate() notification as defined in subclause 6.2.3.17 or any other service list update depending on the application..
6.2.3.23.6 Post-Conditions
There is no change in the client state.