You.i Engine
CYIRemoteAssetCatalog Class Reference

Detailed Description

An asset representing remote asset catalogs.

This class represents a catalog of assets hosted remotely. It can download an asset manifest and undecoded asset data, and decode asset data belonging to this catalog.

An asset manifest can be downloaded by calling DownloadManifest or DownloadManifestAndAssets.

Assets to download must be added to the download list prior to being downloaded using AddAssetToDownloadList. The assets names to add to the download list must be known to the user for the appropriate manifest that is downloaded. These assets can then be downloaded by calling DownloadAssets or DownloadManifestAndAssets. While downloading assets that have dependecies on other files, their dependencies will be added to the download list and downloaded.

When download has completed assets can be decoded by calling GetAsset.

Note
Font resources are not supported and must be included with the application package.
Assets will be downloaded for the current device configuration. If the configuration changes, then the assets must be redownloaded. For example: if the device orientation changes from portrait to landscape.

#include <asset/YiRemoteAssetCatalog.h>

Inheritance diagram for CYIRemoteAssetCatalog:

Public Types

enum  FailureType {
  FailureType::InvalidURL,
  FailureType::NetworkError,
  FailureType::InvalidAsset,
  FailureType::InvalidManifest
}
 
- Public Types inherited from CYIAsset
enum  PathType {
  PathType::Absolute = 0,
  PathType::Relative
}
 

Public Member Functions

virtual ~CYIRemoteAssetCatalog ()
 
const CYIUrlGetUrl () const
 
uint64_t GetCatalogID () const
 
CYIString GetAbsoluteCatalogUrlForAsset (const CYIString &assetName) const
 
CYIString GetRelativeCatalogUrlForAsset (const CYIString &assetName) const
 
void DownloadManifest (const CYIUrl &url)
 
void DownloadAssets ()
 
void DownloadManifestAndAssets (const CYIUrl &url)
 
void CancelDownload ()
 
virtual std::pair< size_t, size_tGetApproximateSize () const override
 
bool AddAssetToDownloadList (const CYIString &assetName, const CYIRuntimeTypeInfo &assetTypeInfo)
 
void RemoveAssetFromDownloadList (const CYIString &assetName)
 
std::shared_ptr< CYIAssetGetAsset (const CYIString &assetName) const
 
void ClearData ()
 
std::vector< CYIStringGetAssetList () const
 
const CYIAssetManifestGetAssetManifest () const
 
bool IsManifestDownloaded () const
 
bool IsAssetInDownloadList (const CYIString &assetName) const
 
CYIUrl GetAssetDownloadURL (const CYIString &assetName) const
 
- Public Member Functions inherited from CYIAsset
virtual ~CYIAsset ()
 
const CYIStringGetPath () const
 
CYIAssetLoadParamsGetLoadParameters () const
 
bool SetName (const CYIString &name)
 
const CYIStringGetName () const
 
bool Load ()
 
void Unload ()
 
bool IsLoaded () const
 
bool Equals (const std::shared_ptr< CYIAsset > &pAsset)
 
virtual bool Prepare ()
 
- Public Member Functions inherited from CYISignalHandler
 CYISignalHandler ()
 
 CYISignalHandler (const CYISignalHandler &rSignalHandler)
 
virtual ~CYISignalHandler ()
 
CYISignalHandleroperator= (const CYISignalHandler &rSignalHandler)
 
void MoveToThread (CYIThread *pThread)
 This function allows the user to override the default thread affinity to any CYIThread that may or may not be running. More...
 
CYIThreadHandle GetThreadAffinity () const
 
void SetThreadAffinity (const CYIThreadHandle &rThreadAffinity)
 
virtual bool IsConnected () const
 
virtual bool IsConnected (const CYISignalBase &rSignal) const
 
void Disconnect (CYISignalBase &rSignal)
 
void DisconnectFromAllSignals ()
 
- Public Member Functions inherited from CYIThread::Listener
 Listener ()
 
virtual ~Listener ()
 
virtual void OnThreadStarted (CYIThread *)
 
virtual void OnThreadTerminated (CYIThread *)
 
virtual void OnThreadFinished (CYIThread *)
 

Static Public Member Functions

static std::shared_ptr< CYIRemoteAssetCatalogCreate (const CYIString &name)
 

Public Attributes

CYISignal< const CYIUrl & > AssetDownloadCompleted
 
CYISignal< const CYIUrl &, const FailureType, const CYIUrl &> AssetDownloadFailed
 
CYISignal< const CYIUrl &, const FailureTypeManifestDownloadFailed
 
CYISignal< const CYIUrl & > DownloadCancelled
 
CYISignal< const CYIUrl & > ManifestDownloadCompleted
 

Protected Member Functions

 CYIRemoteAssetCatalog (const CYIString &name)
 
const std::vector< char > & GetData (const CYIString &assetName) const
 
void OnManifestDownloadCompleted (const std::shared_ptr< CYIHTTPRequest > &pRequest, const std::shared_ptr< CYIHTTPResponse > &pResponse, bool cachedResponse)
 
void OnManifestDownloadFailed (const std::shared_ptr< CYIHTTPRequest > &pRequest, const CYIHTTPService::HTTPStatusCode statusCode, const CYIString &errorMessage)
 
void OnAssetDownloadCompleted (const CYIUrl &url)
 
void OnAssetDownloadFailed (CYIDownloadHelper::FailureType failureType, const CYIUrl &url)
 
std::shared_ptr< CYIAssetDecodeAsset (const CYIString &path, CYIAssetLoadParams *pLoadParams=nullptr) const
 
CYIUrl GetAssetDownloadURL (const CYIString &assetName, const CYIRuntimeTypeInfo &typeInfo) const
 
bool QueueTemplateDependenciesForDownload (const CYIString &assetName)
 
- Protected Member Functions inherited from CYIAsset
 CYIAsset ()
 
ssize_t GetID () const
 
void SetPath (const CYIString &path, PathType pathType)
 
void SetApproximateSize (size_t size)
 
void SetLoaded (bool assetLoaded)
 
void SetLoadParameters (std::unique_ptr< CYIAssetLoadParams > pParams)
 
virtual void OnLoad ()
 
virtual void OnUnload ()
 

Friends

class CYIAssetLoader
 

Additional Inherited Members

- Static Protected Attributes inherited from CYIAsset
static ssize_t INVALID_ID
 

Member Enumeration Documentation

◆ FailureType

The types of failures that may occur in downloading, parsing, or decoding a manifest and its assets.

Enumerator
InvalidURL 

Occurs if the manifest URL provided is invalid.

NetworkError 

Occurs if while downloading, the HTTP request fails for any reason.

InvalidAsset 

Occurs if while parsing or decoding, the asset is invalid for the specified type.

InvalidManifest 

Occurs if the manifest is empty while attempting to fetch assets.

Constructor & Destructor Documentation

◆ ~CYIRemoteAssetCatalog()

virtual CYIRemoteAssetCatalog::~CYIRemoteAssetCatalog ( )
virtual

◆ CYIRemoteAssetCatalog()

CYIRemoteAssetCatalog::CYIRemoteAssetCatalog ( const CYIString name)
protected

Constructs a CYIRemoteAssetCatalog initialized with name so that it can be retrieved later or shared with other objects.

See also
CYIAsset::SetName

Member Function Documentation

◆ AddAssetToDownloadList()

bool CYIRemoteAssetCatalog::AddAssetToDownloadList ( const CYIString assetName,
const CYIRuntimeTypeInfo assetTypeInfo 
)

Adds an asset named assetName and with the type assetTypeInfo to the list of assets to download. Returns false when the assetName is empty, or when the asset is already added to the download list.

Note
If a manifest download is in progress it will be cancelled.

◆ CancelDownload()

void CYIRemoteAssetCatalog::CancelDownload ( )

Cancels the download of the manifest associated with this catalog and cancels the downloads of all assets.

◆ ClearData()

void CYIRemoteAssetCatalog::ClearData ( )

Clears all of the downloaded undecoded data held by this catalog and the manifest. It will also remove all asset names from the download list.

◆ Create()

static std::shared_ptr<CYIRemoteAssetCatalog> CYIRemoteAssetCatalog::Create ( const CYIString name)
static

Returns a new instance of CYIRemoteAssetCatalog initialized with name.

Note
During the creation of the CYIRemoteAssetCatalog it will add itself to the asset manager using CYIAssetManager::AddAsset.
See also
CYIRemoteAssetCatalog

◆ DecodeAsset()

std::shared_ptr<CYIAsset> CYIRemoteAssetCatalog::DecodeAsset ( const CYIString path,
CYIAssetLoadParams pLoadParams = nullptr 
) const
protected

Decodes an asset from the catalog with the given path, adds it to the CYIAssetManager, and returns it.

Note
Decoding may fail if:
  • The path is not a valid catalog path
  • The path is not valid for this catalog
  • The asset in the path is not in the download list for this catalog
  • The asset has not finished downloading
  • There is no data for the asset; or
  • The asset has not been downloaded
See also
CYIAssetLoader::Load

◆ DownloadAssets()

void CYIRemoteAssetCatalog::DownloadAssets ( )

Downloads the undecoded asset data of the named assets specified by calling AddAssetToDownloadList. This function will emit either AssetDownloadCompleted on success or AssetDownloadFailed on failure.

Note
The signals AssetDownloadCompleted and AssetDownloadFailed must be connected before calling this function.

◆ DownloadManifest()

void CYIRemoteAssetCatalog::DownloadManifest ( const CYIUrl url)

Sets the URL of the manifest associated with this catalog to url and downloads it. This function will emit either ManifestDownloadCompleted on success or ManifestDownloadFailed on failure.

Note
If there are downloads in progress they will be cancelled.
This function will clear the downloaded, undecoded data of all of the assets. In-memory assets will not be cleared.

◆ DownloadManifestAndAssets()

void CYIRemoteAssetCatalog::DownloadManifestAndAssets ( const CYIUrl url)

Sets the URL of the manifest associated with this catalog to url, downloads it, and then downloads the assets specified by calling AddAssetToDownloadList.

Note
If there are downloads in progress they will be cancelled.
This function will clear the downloaded, undecoded data of all of the assets. In-memory assets will not be cleared.
The signals AssetDownloadCompleted and AssetDownloadFailed must be connected before calling this function.
See also
DownloadManifest
DownloadAssets

◆ GetAbsoluteCatalogUrlForAsset()

CYIString CYIRemoteAssetCatalog::GetAbsoluteCatalogUrlForAsset ( const CYIString assetName) const

Returns the absolute path to the asset with name assetName. The catalog url for an absolute path will be in the following format: (catalog://[ID]:abs/path/assetName).

◆ GetApproximateSize()

virtual std::pair<size_t, size_t> CYIRemoteAssetCatalog::GetApproximateSize ( ) const
overridevirtual

Calculates and returns the approximate number of bytes currently used by this asset. The first item of the returned pair object represents the memory currently taken in the CPU main memory, and the second item of the returned pair object represents the memory currently taken in the GPU memory.

Note
This function only returns an approximate memory consumption as the exact memory consumption changes depending on the used C++ libraries and on the specific GPU infrastructure and drivers used by the system.

Reimplemented from CYIAsset.

◆ GetAsset()

std::shared_ptr<CYIAsset> CYIRemoteAssetCatalog::GetAsset ( const CYIString assetName) const

Decodes and returns an asset from the catalog with the given asset name, assetName.

See also
DecodeAsset
CYIAssetLoader::LoadFromPath

◆ GetAssetDownloadURL() [1/2]

CYIUrl CYIRemoteAssetCatalog::GetAssetDownloadURL ( const CYIString assetName) const

Get the full download url for the given asset.

◆ GetAssetDownloadURL() [2/2]

CYIUrl CYIRemoteAssetCatalog::GetAssetDownloadURL ( const CYIString assetName,
const CYIRuntimeTypeInfo typeInfo 
) const
protected

Get the full download url for the given asset.

◆ GetAssetList()

std::vector<CYIString> CYIRemoteAssetCatalog::GetAssetList ( ) const

Returns a list of asset names for the assets specified by calling AddAssetToDownloadList.

◆ GetAssetManifest()

const CYIAssetManifest& CYIRemoteAssetCatalog::GetAssetManifest ( ) const

Returns the asset manifest contained in this catalog.

◆ GetCatalogID()

uint64_t CYIRemoteAssetCatalog::GetCatalogID ( ) const

Returns the ID of the catalog. The ID is generated and unique.

◆ GetData()

const std::vector<char>& CYIRemoteAssetCatalog::GetData ( const CYIString assetName) const
protected

Returns the undecoded, downloaded data for the asset added to this catalog with the name assetName. If the asset is not found or has not finished downloading it will return an empty vector.

◆ GetRelativeCatalogUrlForAsset()

CYIString CYIRemoteAssetCatalog::GetRelativeCatalogUrlForAsset ( const CYIString assetName) const

Returns the relative path to the asset with name assetName. The catalog url for an relative path will be in the following format: (catalog://[ID]:rel/assetName).

◆ GetUrl()

const CYIUrl& CYIRemoteAssetCatalog::GetUrl ( ) const

Returns the URL of the manifest associated with this catalog.

◆ IsAssetInDownloadList()

bool CYIRemoteAssetCatalog::IsAssetInDownloadList ( const CYIString assetName) const

Returns true if the asset with name assetName is in the list of assets to download.

See also
AddAssetToDownloadList

◆ IsManifestDownloaded()

bool CYIRemoteAssetCatalog::IsManifestDownloaded ( ) const

Returns true if the manifest download completed successfully.

◆ OnAssetDownloadCompleted()

void CYIRemoteAssetCatalog::OnAssetDownloadCompleted ( const CYIUrl url)
protected

Called when the asset with url has finished downloading.

◆ OnAssetDownloadFailed()

void CYIRemoteAssetCatalog::OnAssetDownloadFailed ( CYIDownloadHelper::FailureType  failureType,
const CYIUrl url 
)
protected

Called when the asset with url has failed downloading.

Note
This function will cancel all current downloads.

◆ OnManifestDownloadCompleted()

void CYIRemoteAssetCatalog::OnManifestDownloadCompleted ( const std::shared_ptr< CYIHTTPRequest > &  pRequest,
const std::shared_ptr< CYIHTTPResponse > &  pResponse,
bool  cachedResponse 
)
protected

Called when the catalog manifest download is complete to parse the manifest.

◆ OnManifestDownloadFailed()

void CYIRemoteAssetCatalog::OnManifestDownloadFailed ( const std::shared_ptr< CYIHTTPRequest > &  pRequest,
const CYIHTTPService::HTTPStatusCode  statusCode,
const CYIString errorMessage 
)
protected

Called when the catalog manifest download has failed.

◆ QueueTemplateDependenciesForDownload()

bool CYIRemoteAssetCatalog::QueueTemplateDependenciesForDownload ( const CYIString assetName)
protected

Queues all of the dependencies for an asset from the catalog with the given assetName for download. Returns true if dependencies were added to the download list to download; false if there were no dependencies or all of the dependencies have already been added to the download list.

◆ RemoveAssetFromDownloadList()

void CYIRemoteAssetCatalog::RemoveAssetFromDownloadList ( const CYIString assetName)

Removes an asset with the name assetName from the list of assets to download.

Note
If the download of the asset with the name assetName is in progress it will cancel the current download, and clear any downloaded data.

Friends And Related Function Documentation

◆ CYIAssetLoader

friend class CYIAssetLoader
friend

Member Data Documentation

◆ AssetDownloadCompleted

CYISignal<const CYIUrl &> CYIRemoteAssetCatalog::AssetDownloadCompleted

Emitted when the download of the assets has finished and provides the URL of the completed manifest download.

◆ AssetDownloadFailed

CYISignal<const CYIUrl & , const FailureType, const CYIUrl & > CYIRemoteAssetCatalog::AssetDownloadFailed

Emitted when the download of the assets has failed and provides the URL of the manifest, the URL of the asset, and the failure reason.

◆ DownloadCancelled

CYISignal<const CYIUrl &> CYIRemoteAssetCatalog::DownloadCancelled

Emitted when the manifest download or asset download has been cancelled and provides the URL of the manifest.

◆ ManifestDownloadCompleted

CYISignal<const CYIUrl &> CYIRemoteAssetCatalog::ManifestDownloadCompleted

Emitted when the catalog download has completed and provides the URL of the completed manifest download.

◆ ManifestDownloadFailed

CYISignal<const CYIUrl &, const FailureType> CYIRemoteAssetCatalog::ManifestDownloadFailed

Emitted when the download has failed and provides the URL of the failed manifest download with the failure reason.


The documentation for this class was generated from the following file: