AssetInterface Class Reference

#include <assets.h>

Inheritance diagram for AssetInterface:

Detailed Description

An Asset represents digital content which can be managed by an asset repository. The management includes versioning, meta data and automatic updates.

Public Member Functions

MAXON_METHOD void SetId (const IdAndVersion &aid, Int update, const AssetRepositoryRef &repository, const Url &url=GetPtrSizedZeroRef< Url >())
 
MAXON_METHOD const AssetType & GetType () const
 
MAXON_METHOD Result< AssetDescription > GetDescription () const
 
MAXON_METHOD Result< BoolGetReferencedAssets (Bool onlyUpdatable, const ValueReceiver< const AssetReference & > &receiver) const
 
MAXON_METHOD Result< BoolGetPendingUpdates (const Block< const AssetBase > &updatedAssets, const ValueReceiver< const AssetReference &, const AssetBase & > &receiver) const
 
MAXON_METHOD void SetMetaData (const AssetMetaData &data)
 
MAXON_METHOD AssetMetaData GetMetaData () const
 

Static Public Member Functions

static MAXON_METHOD const AssetRepositoryRef & GetBuiltinRepository ()
 
static MAXON_METHOD const AssetRepositoryRef & GetApplicationRepository ()
 
static MAXON_METHOD const UpdatableAssetRepositoryRef & GetUserPrefsRepository ()
 
static MAXON_METHOD Result< UpdatableAssetRepositoryRef > CreateRepositoryFromUrl (const Id &rid, const Class< AssetRepositoryRef > &repoType, const Block< const AssetRepositoryRef > &bases, const Url &url, Bool writable, Bool derivedInPrefs, Bool tempRepository, const BackgroundEntryTuple &backgroundJob={})
 
static MAXON_METHOD Result< IdMakeUuid (const Char *prefix, Bool compact)
 
static MAXON_METHOD Result< UrlAddRepositoryScope (const Url &url, const AssetRepositoryRef &repository)
 
static MAXON_METHOD Result< InternedIdGetLanguageMetaDataId (const Id &languageId)
 
static MAXON_METHOD Result< StringGetVersionString (const AssetDescription &asset)
 
static MAXON_METHOD Result< StringGetVersionString (const Asset &asset)
 
static MAXON_METHOD Result< AssetDescription > ResolveAsset (const Url &url, const AssetRepositoryRef &repository)
 
static MAXON_METHOD Result< UrlGetAssetUrl (const AssetDescription &asset, Bool isLatest)
 
static MAXON_METHOD Result< BoolIsAssetValid (const AssetDescription &asset)
 
static MAXON_METHOD Result< BoolIsAssetVisible (const AssetDescription &asset)
 
static MAXON_METHOD Result< AssetVersionValidityDataIsAssetVersionValid (const AssetDescription &asset)
 
static MAXON_METHOD Result< AssetLicenseValidityDataIsAssetLicenseValid (const AssetDescription &asset)
 
static MAXON_METHOD Result< void > ResolveAssetsWithMissingAssets (const AssetRepositoryRef &searchRepository, const Id &typeId, const IdAndVersion &idVersion, const UniversalDateTime &assetCreationDate, HashSet< IdAndVersion > &checked, const Delegate< Result< void >(const AssetDescription &, HashSet< IdAndVersion > &checked)> &callbackFound, const Delegate< Result< void >(Bool outdated)> &callbackMissing)
 

Private Member Functions

 MAXON_INTERFACE (AssetInterface, MAXON_REFERENCE_COPY_ON_WRITE, "net.maxon.interface.asset")
 

Member Function Documentation

◆ MAXON_INTERFACE()

MAXON_INTERFACE ( AssetInterface  ,
MAXON_REFERENCE_COPY_ON_WRITE  ,
"net.maxon.interface.asset"   
)
private

◆ GetBuiltinRepository()

static MAXON_METHOD const AssetRepositoryRef& GetBuiltinRepository ( )
static

Returns the built-in repository. This contains the built-in assets which are defined by program code (i.e., not by a data format to read them from a data stream).

Returns
Reference to the built-in repository.
See also
BuiltinAssetLoaders

◆ GetApplicationRepository()

static MAXON_METHOD const AssetRepositoryRef& GetApplicationRepository ( )
static

Returns the application repository. The application repository uses the built-in repository as base and adds the assets found in the resources of the asset.module.

Returns
Reference to the application repository.

◆ GetUserPrefsRepository()

static MAXON_METHOD const UpdatableAssetRepositoryRef& GetUserPrefsRepository ( )
static

Returns the asset repository in the user preferences folder. This repository is writable for the user.

Returns
Reference to the repository in the user preferences folder.

◆ CreateRepositoryFromUrl()

static MAXON_METHOD Result<UpdatableAssetRepositoryRef> CreateRepositoryFromUrl ( const Id rid,
const Class< AssetRepositoryRef > &  repoType,
const Block< const AssetRepositoryRef > &  bases,
const Url url,
Bool  writable,
Bool  derivedInPrefs,
Bool  tempRepository,
const BackgroundEntryTuple backgroundJob = {} 
)
static

Creates an asset repository for the given Url. If there already is a directory structure in the expected format it is read as far as needed to initialize the repository with the found assets, otherwise such a directory structure is created.

Parameters
[in]ridThe repository identifier. There mustn't be a base with the same identifier.
[in]repoTypeSee AssetRepositoryTypes registry.
[in]basesThe base repositories for the new repository.
[in]urlThe root directory to use for the repository.
[in]writableTrue if the repository shall be writable.
[in]derivedInPrefsTrue if derived meta data shall be stored in the user preferences folder. This is mandatory if #url is a read-only Url.
[in]tempRepositoryTrue if the repository should not be registered as a description database.
[in]backgroundJobOptional background job to report errors, warnings, progress, cancellation.
Returns
An asset repository stored at #url.

◆ MakeUuid()

static MAXON_METHOD Result<Id> MakeUuid ( const Char prefix,
Bool  compact 
)
static

Creates a UUID (universally unique identifier). If prefix is given, the returned identifier starts with prefix, followed by an @ sign, followed by the UUID such as {base@5e75b5e319f64055ac5387490d7355c0}, otherwise it is a UUID only. If prefix already contains an @ sign, only the part before that sign is used.

If compact is true, a Base64-encoding with $ and _ as last characters is used for the UUID instead of the default Hex encoding, and it's ensured that the resulting characters of the encoding don't start with a digit. This results in shorter UUIDs like {FR4pAc$UFR_jXb16rXadEB}. In compact mode and when there are dot characters in prefix, only the part of prefix after the last dot is used.

Parameters
[in]prefixThe prefix for the identifier, may be nullptr. Only the characters up to the first @ sign are used.
[in]compactTrue if the shorter Base64-encoding shall be used, false for Hex encoding.
Returns
A new UUID. It is safe to assume that this UUID differs from any other UUID returned by this method.

◆ AddRepositoryScope()

static MAXON_METHOD Result<Url> AddRepositoryScope ( const Url url,
const AssetRepositoryRef &  repository 
)
static

AddRepositoryScope resolves the asset url and caching the assetdescription in the url.

Parameters
[in]urlUrl to investigate.
[in]repositoryRepository to search.
Returns
Modified url which contains the AssetDescription on success.

◆ GetLanguageMetaDataId()

static MAXON_METHOD Result<InternedId> GetLanguageMetaDataId ( const Id languageId)
static

GetLanguageMetaDataId returns the standardized InternedId for the given languageid.

Parameters
[in]languageIdLanguage id.
Returns
InternedId on success.

◆ GetVersionString() [1/2]

static MAXON_METHOD Result<String> GetVersionString ( const AssetDescription &  asset)
static

GetVersionString returns the version string for the given asset.

Parameters
[in]assetAsset to look at.
Returns
Version string on success.

◆ GetVersionString() [2/2]

static MAXON_METHOD Result<String> GetVersionString ( const Asset asset)
static

GetVersionString returns the version string for the given asset.

Parameters
[in]assetAsset to look at.
Returns
Version string on success.

◆ SetId()

MAXON_METHOD void SetId ( const IdAndVersion aid,
Int  update,
const AssetRepositoryRef &  repository,
const Url url = GetPtrSizedZeroRef< Url >() 
)

Sets identifier, version and repository of this asset. This method should only be called by the owning asset repository when it stores an asset to establish the link between asset and repository.

Parameters
[in]aidIdentifier and version identifier of the asset.
[in]updateUpdate counter, see AssetBaseWithUpdateInterface::GetUpdate.
[in]repositoryThe repository which stored the asset.
[in]urlAn optional Url where the repository stored the asset. @MAXON_ANNOTATION{returnsThis}

◆ GetType()

MAXON_METHOD const AssetType& GetType ( ) const

Returns the AssetType of this asset.

Returns
The asset's type.

◆ GetDescription()

MAXON_METHOD Result<AssetDescription> GetDescription ( ) const

GetDescription returns the AssetDescription of the given Asset.

Returns
AssetDescription on success.

◆ GetReferencedAssets()

MAXON_METHOD Result<Bool> GetReferencedAssets ( Bool  onlyUpdatable,
const ValueReceiver< const AssetReference & > &  receiver 
) const

Yields all direct references which this asset makes to other assets. The AssetReference objects are used later for the update mechanism: The method UpdatableAssetInterface::Update gets a block of tuples (AssetReference, AssetBase) as input, and each tuple indicates to which asset an AssetReference shall be updated. So for example if an asset has two links to the same asset this has to be reported as two AssetReference objects, and when only the first one is passed to UpdatableAssetInterface::Update only the first link has to be updated, while the second has to remain unchanged.

Parameters
[in]onlyUpdatableIf true only references which use updatable links shall be reported (update policy different from ASSET_UPDATE_POLICY::NEVER), otherwise all references.
[in]receiverReceiver to which references are reported.
Returns
false if the receiver cancelled further evaluation, true otherwise.

◆ GetPendingUpdates()

MAXON_METHOD Result<Bool> GetPendingUpdates ( const Block< const AssetBase > &  updatedAssets,
const ValueReceiver< const AssetReference &, const AssetBase & > &  receiver 
) const

Yields all possible AssetReference updates for this asset due to #updatedAssets to #receiver. This method finds all direct references which this asset makes to other assets, and checks if they are affected by the list of #updatedAssets. This check takes into account the update policy of the AssetLink used for the reference. Whenever there is an updatable AssetLink and #updatedAssets contains a newer version for that link, this is reported by a call to #receiver with the reference as first argument and the newer asset from #updatedAssets as second argument.

Parameters
[in]updatedAssetsA block of assets with (potentially) newer versions.
[in]receiverReceiver to which all pending updates due to #updatedAssets are reported.
Returns
false if the receiver cancelled further evaluation, true otherwise.

◆ SetMetaData()

MAXON_METHOD void SetMetaData ( const AssetMetaData &  data)

Sets the meta data object to use for this asset. This method should only be called by the owning asset repository.

Parameters
[in]dataThe meta data of the asset.

◆ GetMetaData()

MAXON_METHOD AssetMetaData GetMetaData ( ) const

Returns the meta data of this asset.

Returns
The meta data of this asset.

◆ ResolveAsset()

static MAXON_METHOD Result<AssetDescription> ResolveAsset ( const Url url,
const AssetRepositoryRef &  repository 
)
static

Returns the asset description from a given url with the URLSCHEME_ASSET.

Parameters
[in]urlUrl to search.
[in]repositoryLookup repository.
Returns
AssetDescription on success.

◆ GetAssetUrl()

static MAXON_METHOD Result<Url> GetAssetUrl ( const AssetDescription &  asset,
Bool  isLatest 
)
static

Returns the url to access the asset data. e.g. asset:///file_634545662344

Parameters
[in]assetasset to convert.
[in]isLatestTrue if the asset is the latest asset. In that case the version will not be added to the url.

◆ IsAssetValid()

static MAXON_METHOD Result<Bool> IsAssetValid ( const AssetDescription &  asset)
static

Checks if the asset is valid for the current license and program version.

Parameters
[in]assetAsset to check
Returns
true if asset is valid, otherwise false.

◆ IsAssetVisible()

static MAXON_METHOD Result<Bool> IsAssetVisible ( const AssetDescription &  asset)
static

Checks if the asset is visible for the current license and program version.

Parameters
[in]assetAsset to check
Returns
true if asset is visible, otherwise false.

◆ IsAssetVersionValid()

static MAXON_METHOD Result<AssetVersionValidityData> IsAssetVersionValid ( const AssetDescription &  asset)
static

Checks if the asset is valid for the current program version.

Parameters
[in]assetAsset to check
Returns
Version validity result.

◆ IsAssetLicenseValid()

static MAXON_METHOD Result<AssetLicenseValidityData> IsAssetLicenseValid ( const AssetDescription &  asset)
static

Checks if the asset is valid for the current license.

Parameters
[in]assetAsset to check
Returns
License validity result.

◆ ResolveAssetsWithMissingAssets()

static MAXON_METHOD Result<void> ResolveAssetsWithMissingAssets ( const AssetRepositoryRef &  searchRepository,
const Id typeId,
const IdAndVersion idVersion,
const UniversalDateTime assetCreationDate,
HashSet< IdAndVersion > &  checked,
const Delegate< Result< void >(const AssetDescription &, HashSet< IdAndVersion > &checked)> &  callbackFound,
const Delegate< Result< void >(Bool outdated)> &  callbackMissing 
)
static

Checks if the asset idVersion can be found in the given searchRepository to resolve missing assets

Parameters
[in]searchRepositoryRepository to search for the asset
[in]typeIdType of the asset
[in]idVersionId and version of the asset
[in]assetCreationDate[optional] Argument with the creation date of the asset. Pass UniversalDateTime() when unknown.
[in]checkedHashSet to prevent stackoverflow.
[in]callbackFound[optional] Callback that is called if the asset could be found. It might happen that the passed asset is the renamed/updated version of the searched one.
[in]callbackMissing[optional] Callback that is called if the asset could not be found.
Returns
OK on success.