PackageManager

#include <icy/pacm/packagemanager.h>

Loads package manifests and coordinates install, update, and uninstall workflows.

Public Attributes

Return	Name	Description
`Signal< void(const http::Response &)>`	`RemotePackageResponse`	Events.
`Signal< void(LocalPackage &)>`	`PackageUninstalled`	Signals when a package is uninstalled.
`Signal< void(InstallTask &)>`	`InstallTaskCreated`	Signals when an installation task is created, before it is started.
`Signal< void(const InstallTask &)>`	`InstallTaskComplete`	Signals when a package installation tasks completes, either successfully or in error.

RemotePackageResponse

Signal< void(const http::Response &)> RemotePackageResponse

Events.

Signals when the remote package list have been downloaded from the server.

PackageUninstalled

Signal< void(LocalPackage &)> PackageUninstalled

Signals when a package is uninstalled.

InstallTaskCreated

Signal< void(InstallTask &)> InstallTaskCreated

Signals when an installation task is created, before it is started.

InstallTaskComplete

Signal< void(const InstallTask &)> InstallTaskComplete

Signals when a package installation tasks completes, either successfully or in error.

Public Methods

Return	Name	Description
	`PackageManager`	#### Parameters
	`PackageManager`	Deleted constructor.
	`PackageManager`	Deleted constructor.
`void`	`initialize` `virtual`	Initialization Methods.
`void`	`uninitialize` `virtual`	Releases resources and cancels any in-progress tasks.
`bool`	`initialized` `virtual` `const`	Returns true if initialize() has been called successfully.
`void`	`createDirectories` `virtual`	Creates the package manager directory structure if it does not already exist.
`void`	`queryRemotePackages` `virtual`	Queries the server for a list of available packages.
`void`	`loadLocalPackages` `virtual`	Loads all local package manifests from file system. Clears all in memory package manifests.
`void`	`loadLocalPackages` `virtual`	Loads all local package manifests residing the the given directory. This method may be called multiple times for different paths because it does not clear in memory package manifests.
`bool`	`saveLocalPackages` `virtual`	Saves all local package manifests to the data directory.
`bool`	`saveLocalPackage` `virtual`	Saves the local package manifest to the file system.
`void`	`parseRemotePackages` `virtual`	Parse the remote packages from the given JSON data string.
`InstallTask::Ptr`	`installPackage` `virtual`	Package Installation Methods.
`bool`	`installPackages` `virtual`	Installs multiple packages. The same options will be passed to each task. If a InstallMonitor instance was passed in the tasks will need to be started, otherwise they will be auto-started. The PackageManager does not take ownership of the InstallMonitor.
`InstallTask::Ptr`	`updatePackage` `virtual`	Updates a single package. Throws an exception if the package does not exist. The returned InstallTask must be started.
`bool`	`updatePackages` `virtual`	Updates multiple packages. Throws an exception if the package does not exist. If a InstallMonitor instance was passed in the tasks will need to be started, otherwise they will be auto-started. The PackageManager does not take ownership of the InstallMonitor.
`bool`	`updateAllPackages` `virtual`	Updates all installed packages.
`bool`	`uninstallPackages` `virtual`	Uninstalls multiple packages.
`bool`	`uninstallPackage` `virtual`	Uninstalls a single package.
`bool`	`hasUnfinalizedPackages` `virtual`	Returns true if there are updates available that have not yet been finalized. Packages may be unfinalized if there were files in use at the time of installation.
`bool`	`finalizeInstallations` `virtual`	Finalizes active installations by moving all package files to their target destination. If files are to be overwritten they must not be in use or finalization will fail.
`InstallTask::Ptr`	`getInstallTask` `virtual` `const`	Task Helper Methods.
`InstallTaskPtrVec`	`tasks` `virtual` `const`	Returns a list of all tasks.
`void`	`cancelAllTasks` `virtual`	Aborts all package installation tasks. All tasks must be aborted before clearing local or remote manifests.
`PackagePairVec`	`getPackagePairs` `virtual` `const`	Package Helper Methods.
`PackagePairVec`	`getUpdatablePackagePairs` `virtual` `const`	Returns a list of package pairs which may be updated. All pairs will have both local and remote package pointers, and the remote version will be newer than the local version.
`PackagePair`	`getPackagePair` `virtual` `const`	Returns a local and remote package pair. An exception will be thrown if either the local or remote packages aren't available or are invalid.
`PackagePair`	`getOrCreatePackagePair` `virtual`	Returns a local and remote package pair. If the local package doesn't exist it will be created from the remote package. If the remote package doesn't exist a NotFoundException will be thrown.
`InstallTask::Ptr`	`createInstallTask` `virtual`	Creates a package installation task for the given pair.
`std::string`	`installedPackageVersion` `virtual` `const`	Returns the version number of an installed package. Exceptions will be thrown if the package does not exist, or is not fully installed.
`Package::Asset`	`getLatestInstallableAsset` `virtual` `const`	Returns the best asset to install, or throws a descriptive exception if no updates are available, or if the package is already up-to-date. This method takes version and SDK locks into consideration.
`bool`	`hasAvailableUpdates` `virtual` `const`	Returns true if there are updates available for this package, false otherwise.
`void`	`clearCache`	File Helper Methods.
`bool`	`clearPackageCache`	Clears a package archive from the local cache.
`bool`	`clearCacheFile`	Clears a file from the local cache.
`bool`	`hasCachedFile`	Checks if a package archive exists in the local cache.
`bool`	`isSupportedFileType`	Checks if the file type is a supported package archive.
`std::string`	`getCacheFilePath`	Returns the full path of the cached file if it exists, or an empty path if the file doesn't exist.
`std::string`	`getPackageDataDir`	Returns the package data directory for the given package ID.
`Options &`	`mutableOptions` `virtual`	Accessors.
`const Options &`	`options` `virtual` `const`	Returns a read-only view of the current options.
`RemotePackageStore &`	`remotePackages` `virtual`	Returns a reference to the in-memory remote package store.
`LocalPackageStore &`	`localPackages` `virtual`	Returns a reference to the in-memory local package store.

PackageManager

PackageManager(const Options & options)

Parameters

options Configuration for directories, endpoints, and credentials.

PackageManager

PackageManager(const PackageManager &) = delete

Deleted constructor.

PackageManager

PackageManager(PackageManager &&) = delete

Deleted constructor.

initialize

virtual

virtual void initialize()

Initialization Methods.

Initializes the package manager: creates directories, loads local manifests, and queries the remote package index.

uninitialize

virtual

virtual void uninitialize()

Releases resources and cancels any in-progress tasks.

initialized

virtual const

virtual bool initialized() const

Returns true if initialize() has been called successfully.

createDirectories

virtual

virtual void createDirectories()

Creates the package manager directory structure if it does not already exist.

queryRemotePackages

virtual

virtual void queryRemotePackages()

Queries the server for a list of available packages.

loadLocalPackages

virtual

virtual void loadLocalPackages()

Loads all local package manifests from file system. Clears all in memory package manifests.

loadLocalPackages

virtual

virtual void loadLocalPackages(const std::string & dir)

Loads all local package manifests residing the the given directory. This method may be called multiple times for different paths because it does not clear in memory package manifests.

saveLocalPackages

virtual

virtual bool saveLocalPackages(bool whiny)

Saves all local package manifests to the data directory.

Parameters

whiny If true, re-throws on write error; otherwise returns false.

Returns

true on success.

saveLocalPackage

virtual

virtual bool saveLocalPackage(LocalPackage & package, bool whiny)

Saves the local package manifest to the file system.

parseRemotePackages

virtual

virtual void parseRemotePackages(const std::string & data)

Parse the remote packages from the given JSON data string.

installPackage

virtual

virtual InstallTask::Ptr installPackage(const std::string & name, const InstallOptions & options)

Package Installation Methods.

Installs a single package. The returned InstallTask must be started. If the package is already up-to-date, a nullptr will be returned. Any other error will throw a std::runtime_error.

installPackages

virtual

virtual bool installPackages(const StringVec & ids, const InstallOptions & options, InstallMonitor * monitor, bool whiny)

Installs multiple packages. The same options will be passed to each task. If a InstallMonitor instance was passed in the tasks will need to be started, otherwise they will be auto-started. The PackageManager does not take ownership of the InstallMonitor.

updatePackage

virtual

virtual InstallTask::Ptr updatePackage(const std::string & name, const InstallOptions & options)

Updates a single package. Throws an exception if the package does not exist. The returned InstallTask must be started.

updatePackages

virtual

virtual bool updatePackages(const StringVec & ids, const InstallOptions & options, InstallMonitor * monitor, bool whiny)

Updates multiple packages. Throws an exception if the package does not exist. If a InstallMonitor instance was passed in the tasks will need to be started, otherwise they will be auto-started. The PackageManager does not take ownership of the InstallMonitor.

updateAllPackages

virtual

virtual bool updateAllPackages(bool whiny)

Updates all installed packages.

uninstallPackages

virtual

virtual bool uninstallPackages(const StringVec & ids, bool whiny)

Uninstalls multiple packages.

uninstallPackage

virtual

virtual bool uninstallPackage(const std::string & id, bool whiny)

Uninstalls a single package.

hasUnfinalizedPackages

virtual

virtual bool hasUnfinalizedPackages()

Returns true if there are updates available that have not yet been finalized. Packages may be unfinalized if there were files in use at the time of installation.

finalizeInstallations

virtual

virtual bool finalizeInstallations(bool whiny)

Finalizes active installations by moving all package files to their target destination. If files are to be overwritten they must not be in use or finalization will fail.

getInstallTask

virtual const

virtual InstallTask::Ptr getInstallTask(const std::string & id) const

Task Helper Methods.

Gets the install task for the given package ID.

tasks

virtual const

virtual InstallTaskPtrVec tasks() const

Returns a list of all tasks.

cancelAllTasks

virtual

virtual void cancelAllTasks()

Aborts all package installation tasks. All tasks must be aborted before clearing local or remote manifests.

getPackagePairs

virtual const

virtual PackagePairVec getPackagePairs() const

Package Helper Methods.

Returns all package pairs, valid or invalid. Some pairs may not have both local and remote package pointers.

getUpdatablePackagePairs

virtual const

virtual PackagePairVec getUpdatablePackagePairs() const

Returns a list of package pairs which may be updated. All pairs will have both local and remote package pointers, and the remote version will be newer than the local version.

getPackagePair

virtual const

virtual PackagePair getPackagePair(const std::string & id, bool whiny) const

Returns a local and remote package pair. An exception will be thrown if either the local or remote packages aren't available or are invalid.

getOrCreatePackagePair

virtual

virtual PackagePair getOrCreatePackagePair(const std::string & id)

Returns a local and remote package pair. If the local package doesn't exist it will be created from the remote package. If the remote package doesn't exist a NotFoundException will be thrown.

createInstallTask

virtual

virtual InstallTask::Ptr createInstallTask(PackagePair & pair, const InstallOptions & options)

Creates a package installation task for the given pair.

installedPackageVersion

virtual const

virtual std::string installedPackageVersion(const std::string & id) const

Returns the version number of an installed package. Exceptions will be thrown if the package does not exist, or is not fully installed.

getLatestInstallableAsset

virtual const

virtual Package::Asset getLatestInstallableAsset(const PackagePair & pair, const InstallOptions & options) const

Returns the best asset to install, or throws a descriptive exception if no updates are available, or if the package is already up-to-date. This method takes version and SDK locks into consideration.

hasAvailableUpdates

virtual const

virtual bool hasAvailableUpdates(const PackagePair & pair) const

Returns true if there are updates available for this package, false otherwise.

clearCache

void clearCache()

File Helper Methods.

Clears all files in the cache directory.

clearPackageCache

bool clearPackageCache(LocalPackage & package)

Clears a package archive from the local cache.

clearCacheFile

bool clearCacheFile(std::string_view fileName, bool whiny)

Clears a file from the local cache.

hasCachedFile

bool hasCachedFile(Package::Asset & asset)

Checks if a package archive exists in the local cache.

isSupportedFileType

bool isSupportedFileType(std::string_view fileName)

Checks if the file type is a supported package archive.

getCacheFilePath

std::string getCacheFilePath(std::string_view fileName)

Returns the full path of the cached file if it exists, or an empty path if the file doesn't exist.

getPackageDataDir

std::string getPackageDataDir(std::string_view id)

Returns the package data directory for the given package ID.

mutableOptions

virtual

virtual Options & mutableOptions()

Accessors.

Returns the mutable startup configuration for this manager. Callers should finish edits before initialize().

options

virtual const

virtual const Options & options() const

Returns a read-only view of the current options.

remotePackages

virtual

virtual RemotePackageStore & remotePackages()

Returns a reference to the in-memory remote package store.

localPackages

virtual

virtual LocalPackageStore & localPackages()

Returns a reference to the in-memory local package store.

Protected Attributes

Return	Name	Description
`std::mutex`	`_mutex`
`LocalPackageStore`	`_localPackages`
`RemotePackageStore`	`_remotePackages`
`InstallTaskPtrVec`	`_tasks`
`Options`	`_options`

_mutex

std::mutex _mutex

_localPackages

LocalPackageStore _localPackages

_remotePackages

RemotePackageStore _remotePackages

_tasks

InstallTaskPtrVec _tasks

_options

Options _options

Protected Methods

Return	Name	Description
`void`	`onPackageInstallComplete`	Callbacks.

onPackageInstallComplete

void onPackageInstallComplete(InstallTask & task)

Callbacks.