B.2 IDL for File Delivery Application Service API
26.3473GPPApplication Programming Interface and URLMultimedia Broadcast/Multicast Service (MBMS)Release 17TS
#include "EmbmsCommonTypes.idl"
module FileDeliveryService
{
//Forward Declaration
interface ILTEFileDeliveryServiceCallback;
/**
* @name DownloadState
* @brief List of the file download state
*/
enum DownloadState
{
FD_IN_PROGRESS /**< File download is in progress */
};
/**
* @name FdErrorCode
* @brief List of the errors for File Delivery service
*/
enum FdErrorCode
{
FD_INVALID_SERVICE, /**< Invalid service ID */
FD_DUPLICATE_FILE_URI, /**< There is another pending capture request for the specified file URI. */
FD_AMBIGUOUS_FILE_URI, /**< The specified file URI cannot identify a pending capture request. */
FD_STOP_FILE_URI_NOT_FOUND, /**< The file URI specified on a stopFdCapture does not match an outstanding startFdCapture() request. */
FD_UNKNOWN_ERROR /**< Unknown error */
};
/**
* @name cacheControl
* @brief List of the errors for File Delivery service
*/
enum cacheControlMode
{
FD_NO_CACHE, /**< The application uses Cache directives to manage how long to retain files.
When FD_NO_CACHE is selected, the file (or set of files)
won’t be cached, which can be useful when the file is expected to be
highly dynamic (changes to the file occur quite often) or if the file
will be used only once by the receiver application. */
FD_MAX_STALE, /**< The application uses Cache directives to manage how long to retain files.
When FD_MAX_STALE is selected, the file (or set of files)
won’t be cached, which can be useful when the file is expected to be
highly dynamic (changes to the file occur quite often) or if the file
will be used only once by the receiver application. */
FD_EXPIRES /**< The application uses Cache directives to manage how long to retain files.
When FD_EXPIRES is selected, indicates the file has expected expiry time.
In that case cacheControlExpires value is the expiry time*/
};
/**
* @name RegisterFdResponseNotification
* @brief Fd app registration information
*/
struct RegisterFdResponseNotification
{
EmbmsCommonTypes::RegResponseCode value; /**< Result of registration value as defined in RegResponseCode */
string message; /**< Message described the result */
unsigned long acceptedFdRegistrationValidityDuration; /**< Accepted registeration validity duration */
};
/**
* @name FileInfo
* @brief Downloaded file information
*/
struct FileInfo
{
string fileUri; /**< File URI */
string fileLocation; /**< The physical location of the file or HTTP URL where the file can be accessed */
string contentType; /**< MIME type as described in FDT of the file */
unsigned long availabilityDeadline; /**< The maximum time that embms client guarantees to keep the file in its storage */
};
/**
* @name RegisterFdAppData
* @brief File delivery app registration information
*/
struct RegisterFdAppData
{
string appId; /**< The application ID used during the registration */
any platformSpecificAppContext; /**< The platformSpecificAppContext provides a
platform-specific app context
object to enable the API implementation to get extra information
about the application. */
sequence<string> serviceClassList; /**< List of service classes */
StorageLocation locationPath; /**< Local storage location on the device where collected files are copied */
unsigned long registrationValidityDuration; /**< The period of time in seconds that the eMBMS client honors
the app registration and file capture requests
after the app deregisters and exits.
This enables the app to let the eMBMS client capture
files in the background when the application is not currently registered.
Default value of this option is 0 which means middleware clears
any outstanding startFdCapture requests.* /
};
/**
* @name StartFdCaptureData
* @brief File delivery start capture information. It is used in StartFdCapture API
*/
struct StartFdCaptureData
{
string serviceId; /**< File delivery service ID from FdServiceInfo */
string fileUri; /**< File URI for the file(s) to be captured.
If empty, this implies capture all files. If an absolute URL,
this implies only the capture of that particular file.
If a Base URL, this implies the capture of all files that have that Base URL. */
boolean disableFileCopy; /**< Disables copying of files to register locationPath */
boolean captureOnce; /**< Capture the file only once and the bearer would be deactivated after file gets downloaded*/
};
/**
* @name StopFdCaptureData
* @brief File delivery stop capture information. It is used in StopFdCapture API
*/
struct StopFdCaptureData
{
string serviceId; /**< File delivery service ID from FdServiceInfo */
string fileUri; /**< File URI. If empty, then it stops capture on all files.
The path of the URI should contain the complete folder or file name. */
};
/**
* @name FileList
* @brief List of file URIs
*/
struct FileList
{
sequence<string> fileUriList; /**< List of file URIs */
};
/**
* @name ServiceNameLang
* @brief Name and language information
*/
struct ServiceNameLang
{
string name; /**< Name */
string lang; /**< Language */
};
/**
* @name FdServiceInfo
* @brief File delivery service information
*/
struct FdServiceInfo
{
sequence<ServiceNameLang> serviceNameList; /**< List of Service name and language */
string serviceClass; /**< Service class */
string serviceId; /**< Service ID */
string serviceLanguage; /**< Service language */
EmbmsCommonTypes::ServiceAvailabilityType serviceBroadcastAvailability; /**< Service broadcast availability */
sequence<string> fileUriList; /**< List of file URIs */
EmbmsCommonTypes::Date activeDownloadPeriodStartTime; /**< The current/next active file download service start time, when files start being broadcast over the air */
EmbmsCommonTypes::Date activeDownloadPeriodEndTime; /**< The current/next active file download service end time, when files stop being broadcast over the air */
};
/**
* @name FdServices
* @brief List of FD service info objects
*/
typedef sequence<FdServiceInfo> FdServices;
/**
* @name FdServiceClassList
* @brief ServiceClass information that the app is interested in. It is for the SetFdServiceClassFilter API.
*/
typedef sequence<string> FdServiceClassList;
/**
* @name ActiveFdService
* @brief Information about active file capture
*/
struct ActiveFdService
{
string serviceId; /**< File delivery service ID from FdServiceInfo */
sequence< string > fileUri; /**< File URI list */
};
/**
* @name ActiveFdServiceList
* @brief List of File delivery service ID from FdServiceInfo
* @see getFdActiveServices()
*/
typedef sequence< ActiveFdService > ActiveFdServiceList;
/**
* @name StorageLocation
* @brief Local storage location on the device where collected files are copied.
* It is used in the SetStorageLocation and registerFdApp API.
*/
typedef string StorageLocation;
/**
* @name FileAvailableNotification
* @brief Information about the downloaded file.
*/
struct FileAvailableNotification
{
string serviceId; /**< File delivery service ID from FdServiceInfo */
FileInfo downloadedFileInfo; /**< Downloaded file information */
};
/**
* @name FdServiceErrorNotification
* @brief File delivery service error information. It is used by the FdServiceErrorNotification API.
*/
struct FdServiceErrorNotification
{
string serviceId; /**< File delivery service ID from FdServiceInfo */
string fileUri; /**< File URI */
FdErrorCode errorCode; /**< File delivery service error ID */
string errorMsg; /**< error message */
};
/**
* @name FileDownloadFailureNotification
* @brief File download failure information.
* @see FileDownloadFailureNotification()
*/
struct FileDownloadFailureNotification
{
string serviceId; /**< File delivery service ID from FdServiceInfo */
string fileUri; /**< File URI */
};
/**
* @name StorageError
* @brief Insufficient storage notification information
* @see StorageError()
*/
struct StorageErrorNotification
{
string serviceId; /**< File delivery service ID from FdServiceInfo */
string fileUri; /**< File URI */
StorageLocation storagePath; /**< Storage path that does not have sufficient storage to complete the file download */
unsigned long storageNeeded; /**< Storage needed to complete the file download */
};
/**
* @name InaccessibleLocationNotification
* @brief Inaccessible storage notification information
* @see InaccessibleLocation()
*/
struct InaccessibleLocationNotification
{
string serviceId; /**< File delivery service ID from FdServiceInfo */
string message; /**< Message with additional information */
StorageLocation locationPath; /**< The path that is not accessible */
};
/**
* @name FdDownloadStateInfo
* @brief Information returned by getFdDownloadStateList().
* @see getFdDownloadStateList()
*/
struct FdDownloadStateInfo
{
string fileUri; /**< File URI */
DownloadState state; /**< State of files from DownloadState. */
};
/**
* @name FileDownloadStateInfoList
* @brief List of FdDownloadStateInfo
* @see getFdDownloadStateList()
*/
typedef sequence<FdDownloadStateInfo> FileDownloadStateInfoList;
/**
* @name FileDownloadStateUpdateNotification
* @brief File download state update notification information
* @see fileDownloadStateUpdate()
*/
struct FileDownloadStateUpdateNotification
{
string serviceId; /**< File delivery service ID from FdServiceInfo */
};
/**
* @name GetFdDownloadStateListData
* @brief Information needed to call getFdDownloadStateList(). The returned list of getFdDownloadStateList() is filtered based on the options set in GetFdDownloadStateList.
* @see getFdDownloadStateList()
*/
struct GetFdDownloadStateListData
{
string serviceId; /**< Active file delivery service ID from FdServiceInfo. */
};
/**
* @name AvailableFileList
* @brief List of FileInfo
* @see getFdAvailableFileList()
*/
typedef sequence < FileInfo > AvailableFileList;
/**
* @name FileListAvailableNotification
* @brief File List Available notification information
* @see fileListAvailable()
*/
struct FileListAvailableNotification
{
string serviceId; /**<File delivery service ID from FdServiceInfo. */
};
/**
* @name addSAResponseNotification
* @brief Information about the service announcement addition.
*/
struct addSAResponseNotification
{
AddSAResponseCode responseCode; /**< Response code for the addSA */
string message; /**< error message */
};
interface ILTEFileDeliveryService
{
/**
@name getVersion
@brief Retrieves the version of the current File delivery service interface implementation
@return Interface Version
**/
string getVersion();
/**
@name registerFdApp
@brief Application registers a callback listener with the EMBMS client
@param[in] regInfo Information required for application registration
@param[in] cb Callback listener
@see RegisterFdAppData
@see registerFdResponse()
@return ResultCode
**/
EmbmsCommonTypes::ResultCode registerFdApp(in RegisterFdAppData regInfo, in ILTEFileDeliveryServiceCallback callBack);
/**
@name deregisterFdApp
@brief Application deregisters with the EMBMS client
@pre Application calls registerFdApp
@return ResultCode
**/
EmbmsCommonTypes::ResultCode deregisterFdApp();
/**
@name startFdCapture
@brief Start download of files over file delivery service over broadcast
@param StartFdCapture Struct includes parameters for StartFdCapture request
@pre Application is registered for File Delivery service
@see fileAvailable()
@see StartFdCaptureData
@return ResultCode
**/
EmbmsCommonTypes::ResultCode startFdCapture(in StartFdCaptureData info);
/**
@name stopFdCapture
@brief Stop download of files for the file Delivery service over broadcast
@param stopFdCapture Struct includes parameters for stopFdCapture
@pre Application is registered for File Delivery service
@see StopFdCaptureData
@return ResultCode
**/
EmbmsCommonTypes::ResultCode stopFdCapture(in StopFdCaptureData info);
/**
@name getFdActiveServices
@brief Get list of currently active services
@param[out] ActiveFdServiceList The list of services the app has
@pre Application is registered for File delivery service
@see ActiveFdServiceList
@return ResultCode
**/
EmbmsCommonTypes::ResultCode getFdActiveServices(out ActiveFdServiceList services);
/**
@name getFdAvailableFileList
@brief Retrieves the list of files previously captured for the
application.
@param[in] File delivery service ID from FdServiceInfo
@param[out] FileList List of files previously captured and filtered based on serviceId
@pre Application is registered for File delivery service and received fileListAvailable() notification
@see fileListAvailable()
@return ResultCode
**/
EmbmsCommonTypes::ResultCode getFdAvailableFileList(in string serviceId, out AvailableFileList files);
/**
@name getFdServices
@brief Retrieves the list of File Delivery services defined in the USD.
List of services is filtered by the service class filter,
if a filter has been set by the application
@param[out] FDServices List of filtered File delivery services
@pre Application is registered for File delivery service and received fdServiceListUpdate() notification
@see fdServiceListUpdate()
@see FdServices
@return ResultCode
**/
EmbmsCommonTypes::ResultCode getFdServices(out FdServices services);
/**
@name getFdDownloadStateList
@brief Retrieves the state of files pending download
@param GetFileDownloadState Includes parameters for getFileDownloadState
@pre Application is registered for File Delivery service and received fileDownloadStateUpdate() notification
@see fileDownloadStateUpdate()
@see GetFdDownloadStateListData
@see FileDownloadStateInfoList
@return ResultCode
**/
EmbmsCommonTypes::ResultCode getFdDownloadStateList(in GetFdDownloadStateListData info, out FileDownloadStateInfoList fdStateList);
/**
@name setFdServiceClassFilter
@brief Application sets a filter on file delivery services in which it is interested
@param[in] serviceClassInfo List of service class filters requested by the application
@pre Application is registered successfully with file delivery service
@see SetFdServiceClassFilterData
@see fdServiceListUpdate()
@see getFdServices()
@return ResultCode
**/
EmbmsCommonTypes::ResultCode setFdServiceClassFilter(in FdServiceClassList serviceClassInfo);
/**
@name setFdStorageLocation
@brief Sets the storage location to store the application downloaded files
@param[in] StorageLocation Includes parameters for setStorageLocation request
@pre Application is registered for File Delivery service
@see StorageLocation
@return ResultCode
**/
EmbmsCommonTypes::ResultCode setFdStorageLocation(in StorageLocation locationPath);
/**
@name addSA
@brief provides the announcement of additional MBMS user services to the MBMS client
@param saFileLocation location of the SA file
@see addSAResponse
@return ResultCode
**/
EmbmsCommonTypes::ResultCode addSA(in string saFileLocation);
};
interface ILTEFileDeliveryServiceCallback
{
/**
@name registerFdResponse
@brief The response to the application streaming service register API.
@param Notification Parameters for register File delivery response
@pre Application called registerFdApp
@see RegisterFdResponseNotification
@see registerFdApp()
**/
void registerFdResponse(in RegisterFdResponseNotification info);
/**
@name fileAvailable
@brief Notification to application when a new file is downloaded per
application capture request
@param FileAvailableNotification Includes parameters for the downloaded file
@pre Application is registered for File Delivery service and application called startFdCapture()
@see FileAvailableNotification
**/
void fileAvailable(in FileAvailableNotification notification);
/**
@name fdServiceListUpdate
@brief Notification to application on an update of the available for file delivery services.
Update may be due to the received USD or the network configuration
@pre Application is registered for file delivery service
@post Call getFdServices()
**/
void fdServiceListUpdate();
/**
@name fdServiceError
@brief Notification to application when there is an error with broadcast download of service
@param Notification Parameters for service error notification
@pre Application is registered for streaming service and called startFdServiceCapture
@see FdServiceErrorNotification
**/
void fdServiceError(in FdServiceErrorNotification notification);
/**
@name fileDownloadFailure
@brief Notification to application that download of a requested file
failed
@param FileDownloadFailureNotification Includes information about the failed file download
@pre Application is registered for File Delivery service and application called startFdCapture()
@see FileDownloadFailureNotification
**/
void fileDownloadFailure(in FileDownloadFailureNotification notification);
/**
@name storageError
@brief Notification to application that the storage location set by the
application does not have enough storage for the file download
@param StorageError Includes parameters to specify the file and
storage requirement
@pre Application is registered for file delivery service and application called startFdCapture()
@see StorageError
**/
void storageError(in StorageErrorNotification info);
/**
@name inaccessibleLocation
@brief Notification to application that the storage location set by the
application is not accessible by the eMBMS Client
@param InaccessibleLocation Includes the inaccessible storage path
@pre Application is registered for File delivery service
@see InaccessibleLocation
Application calls setStorageLocation
**/
void inaccessibleLocation(in InaccessibleLocationNotification info);
/**
@name fileDownloadStateUpdate
@brief Notify application of a change in the state of pending file
downloads
@param FileDownloadStateUpdate Includes parameters for fileDownloadStateUpdate()
@pre Application is registered for File delivery service
@post call getFdDownloadStateList()
@see FileDownloadStateUpdate
**/
void fileDownloadStateUpdate(in FileDownloadStateUpdateNotification info);
/**
@name fileListAvailable
@brief Notify application when the list of downloaded files is available to retrieve
@param[in] FileListAvailable Includes parameters for fileListAvailable
@pre Application is registered for File Delivery service
@post call getFdAvailableFileList()
**/
void fileListAvailable(in FileListAvailableNotification info);
/**
@name addSAResponse
@brief The response to the add service announcement API.
@param [in] Parameters for register File delivery response
@pre Application called addSA
@see AddSAResponseCode
@see addSA()
**/
void addSAResponse(in AddSAResponseNotification info);
};
};
module EmbmsCommonTypes
{
//Common types
typedef unsigned long long Date;
/**
* @name ResultCode
* @brief The return value of the API
*/
enum ResultCode
{
SUCCESS, /**< Success */
REGISTRATION_IN_PROGRESS, /**< Failed due to registration in progress */
NO_VALID_REGISTRATION, /**< Failed due to no valid registration */
MISSING_PARAMETER, /**< A mandatory parameter is missing */ UNKNOWN_ERROR /**< Failed with unknown error */
};
/**
* @name ServiceAvailabilityType
* @brief Indicates service availability state
*/
enum ServiceAvailabilityType
{
BROADCAST_AVAILABLE, /**< Service is available via broadcast */
BROADCAST_UNAVAILABLE, /**< Service is unavailable via broadcast */ SERVICE_UNAVAILABLE /**< Service is unavailable */
};
/**
* @name RegResponseCode
* @brief Indicates app registration response
*/
enum RegResponseCode
{
REGISTER_SUCCESS, /**< Registration was successful */
FAILED_LTE_EMBMS_SERVICE_UNAVAILABLE /**< Registration failed because LTE eMBMS is unavailable on device */
};
/**
* @name AddSAResponseCode
* @brief Indicates the response to the add service announcement API
*/
enum addSAResponseCode
{
SUCCESS, /**< Success */
SA_FILE_INVALID /**< SA file is not valid or not found */
};
};