omni::ext::ExtensionManager

class ExtensionManager : public carb::IObject 

The manager class that is responsible for all Extensions.

See also

IExtensions::createExtensionManager

Public Functions

virtual void processAndApplyAllChanges() = 0

Process all outstanding extension changes since the previous call to this function.

If an extension was changed it will be reloaded. If it was added or removed (including adding new folders) changes will also be applied. Events (kEventScriptChanged, kEventFolderChanged) are also dispatched.

virtual size_t getExtensionCount() const = 0

Returns the number of registered local extensions.

Returns: the number of registered local extensions

virtual void getExtensions(ExtensionInfo *extensions) const = 0

Fills an array with information about registered local extensions.

Parameters: extensions – The array of ExtensionInfo structs to be filled. It must be large enough to hold getExtensionCount() entries.

virtual carb::dictionary::Item *getExtensionDict(const char *extId) const = 0

Get an extension info dictionary for a single extension.

See also

carb::dictionary::IDictionary

Parameters: extId – The extension ID to retrieve info for
Returns: A carb::dictionary::Item pointer containing the information; nullptr if the extension was not found.

inline void setExtensionEnabled(const char *extensionId, bool enabled)

Helper function to enable or disable a single extension.

See also

setExtensionEnabledBatch

Note

The operation is deferred until processAndApplyAllChanges() is called. Use setExtensionEnabledImmediate() to perform the action immediately.

Parameters

extensionId – The extension ID to enable or disable
enabled – true to enable the extension; false to disable the extension

virtual void setExtensionEnabledBatch(const char **extensionIds, size_t extensionIdCount, bool enabled) = 0

Enables or disables several extensions.

Note

The operation is deferred until processAndApplyAllChanges() is called. Use setExtensionEnabledBatchImmediate() to perform the action immediately.

Parameters

extensionIds – An array of extension IDs that should be enabled or disabled
extensionIdCount – The number of items in extensionIds
enabled – true to enable the extensions; false to disable the extensions

inline bool setExtensionEnabledImmediate(const char *extensionId, bool enabled)

Helper function to enable or disable a single extension, immediately.

See also

setExtensionEnabledBatchImmediate

Parameters

extensionId – The extension ID to enable or disable
enabled – true to enable the extension; false to disable the extension

Returns

true if the operation could be completed; false otherwise

virtual bool setExtensionEnabledBatchImmediate(const char **extensionIds, size_t extensionIdCount, bool enabled) = 0

Enables or disables several extensions immediately.

Parameters

extensionIds – An array of extension IDs that should be enabled or disabled
extensionIdCount – The number of items in extensionIds
enabled – true to enable the extensions; false to disable the extensions

Returns

true if the operation could be completed; false otherwise

virtual void setExtensionsExcluded(const char **extensionIds, size_t extensionIdCount) = 0

Set extensions to exclude on following solver/startup routines.

Note

The extensions set persist until next call to this function.

Parameters

extensionIds – An array of extension IDs that should be excluded
extensionIdCount – The number of items in extensionIds

virtual size_t getFolderCount() const = 0

Gets number of monitored extension folders.

Returns: Extension folder count.

virtual void getFolders(ExtensionFolderInfo *extensionFolderInfos) const = 0

Gets monitored extension folders.

Parameters: extensionFolderInfos – The extension folder info array to be filled. It must be large enough to hold getFolderCount() entries.

virtual void addPath(const char *path, ExtensionPathType type = ExtensionPathType::eCollection) = 0

Add extension path.

See also

removePath()

Parameters

path – The path to add (folder or direct path)
type – An ExtensionPathType describing how path should be treated

virtual void removePath(const char *path) = 0

Remove extension path.

See also

addPath()

Parameters: path – The path previously given to addPath()

virtual carb::events::IEventStream *getChangeEventStream() const = 0

Accesses the IEventStream that is used for change events.

See also

carb::events::IEventStream

Returns: The carb::events::IEventStream used for change events

virtual IExtensionManagerHooks *getHooks() const = 0

Interface to install hooks to “extend” extension manager.

Returns: an IExtensionManagerHooks instance to allow hooking the Extension Manager

virtual bool addRegistryProvider(const char *providerName, IRegistryProvider *provider) = 0

Adds a new registry provider.

See also

IRegistryProvider, removeRegistryProvider()

Parameters

providerName – unique name for the registry provider
provider – a IRegistryProvider instance that will be retained by *this

Returns

true if registration was successful; false otherwise (i.e. the provided name was not unique)

virtual void removeRegistryProvider(const char *providerName) = 0

Removes a registry provider.

See also

IRegistryProvider, addRegistryProvider()

Parameters: providerName – the unique name previously passed to addRegistryProvider()

virtual size_t getRegistryProviderCount() const = 0

Gets the number of current registry providers.

Returns: the number of registry providers

virtual void getRegistryProviders(RegistryProviderInfo *infos) = 0

Fills an array with info about current registry providers.

Parameters: infos – an array of RegistryProviderInfo objects to be filled. It must be large enough to hold getRegistryProviderCount() entries.

virtual void refreshRegistry() = 0: Non blocking call to initiate registry refresh.

virtual bool syncRegistry() = 0

Blocking call to synchronize with remote registry.

Returns: true if the synchronization was successful; false if an error occurred.

virtual size_t getRegistryExtensionCount() const = 0: Gets the number of extensions in the registry.

virtual void getRegistryExtensions(ExtensionInfo *extensions) const = 0

Fills an array with compatible extensions in the registry.

Parameters: extensions – an array of ExtensionInfo objects to be filled. It must be large enough to hold getRegistryExtensionCount() entries.

virtual size_t getRegistryExtensionPackageCount() const = 0: Gets the number of extension packages in the registry.

virtual void getRegistryExtensionPackages(ExtensionInfo *extensions) const = 0

Fills the array with all extension packages in the registry.

Note

this function will return all extensions in the registry, including packages for other platforms, incompatible with current runtime.

Parameters: extensions – an array of ExtensionInfo objects to be filled. It must be large enough to hold getRegistryExtensionPackageCount() entries.

virtual carb::dictionary::Item *getRegistryExtensionDict(const char *extId) = 0

Get an extension info dictionary for a single extension from the registry.

See also

carb::dictionary::IDictionary

Parameters: extId – The extension ID to retrieve information for
Returns: A carb::dictionary::Item containing information about the given extension; nullptr if the extension ID was not found.

virtual bool publishExtension(const char *extId, const char *providerName = "", bool allowOverwrite = false) = 0

Package and upload extension to the registry.

See also

unpublishExtension()

Note

If providerName is empty and there are multiple providers, the provider specified in the setting key /app/extensions/registryPublishDefault is used.

Parameters

extId – The extension ID to publish
providerName – The provider name to use for publish. If an empty string is provided and multiple providers are registered, the provider specified in the setting key /app/extensions/registryPublishDefault is used.
allowOverwrite – If true, the extension already specified in the registry maybe overwritten

virtual bool unpublishExtension(const char *extId, const char *providerName = "") = 0

Removes an extension from the registry.

See also

publishExtension()

Note

If providerName is empty and there are multiple providers, the provider specified in the setting key /app/extensions/registryPublishDefault is used.

Parameters

extId – The extension ID to unpublish
providerName – The provider name to use. If an empty string is provided and multiple providers are registered, the provider specified in the setting key /app/extensions/registryPublishDefault is used.

virtual bool pullExtension(const char *extId) = 0

Downloads the specified extension from the registry.

See also

pullExtensionAsync()

Note

This is a blocking call. Use pullExtensionAsync() if asynchronous behavior is desired.

Parameters: extId – The extension ID to download
Returns: true if the extension was downloaded successfully; false otherwise.

virtual void pullExtensionAsync(const char *extId) = 0

Starts an asynchronous extension download from the registry.

See also

pullExtension()

Note

this function returns immediately

Parameters: extId – The extension ID to download

virtual void fetchExtensionSummaries(ExtensionSummary **summaries, size_t *summaryCount) = 0

Fetches extension summaries for all extensions.

Summary are extensions grouped by version. One summary per fullname(name+tag).

Note

The array that is received is valid until the next call to this function.

Parameters

summaries – [out] Receives an array of ExtensionSummary instances
summaryCount – [out] Receives the size of the array passed to summaries.

virtual void fetchExtensionVersions(const char *nameAndVersion, ExtensionInfo **extensions, size_t *extensionCount) = 0

Fetch all matching compatible extensions.

A partial version can also be passed. So omni.foo, omni.foo-2, omni.foo-1.2.3 all valid values for nameAndVersion.

Note

The returned array is valid until next call of this function.

Parameters

nameAndVersion – The name (and optional partial or full version) to search
extensions – [out] Receives an array of ExtensionInfo instances
extensionCount – [out] Receives the size of the array passed to extensions

virtual void fetchExtensionPackages(const char *nameAndVersion, ExtensionInfo **extensions, size_t *extensionCount) = 0

Fetch all matching extension packages.

A partial version can also be passed. So omni.foo, omni.foo-2, omni.foo-1.2.3 all valid values for nameAndVersion.

This function will return all extensions in the registry, including packages for other platforms, incompatible with current runtime.

Note

The returned array is valid until next call of this function.

Parameters

nameAndVersion – The name (and optional partial or full version) to search
extensions – [out] Receives an array of ExtensionInfo instances
extensionCount – [out] Receives the size of the array passed to extensions

virtual void disableAllExtensions() = 0: Disables all enabled extensions.

Note

this is called automatically upon destruction.

virtual void addUserPaths() = 0

Adds user paths from persistent settings.

All of the extension search path from persistent settings are added as ExtensionPathType::eCollectionUser.

virtual void addCachePath() = 0

Add cache paths from settings.

All of the cache paths from settings are added as ExtensionPathType::eCollectionCache. This is necessary for registry usage.

virtual bool generateVersionLock(const char *extId, const VersionLockDesc &desc) = 0

Generate settings that contains versions of started dependencies to lock them (experimental).

Parameters

extId – The extension ID
desc – A VersionLockDesc descriptor

Returns

true if generation succeeded; false otherwise

virtual bool addPathProtocolProvider(const char *scheme, IPathProtocolProvider *provider) = 0

Adds a new path protocol provider.

See also

removePathProtocolProvider()

Parameters

scheme – A unique name for this provider
provider – A IPathProtocolProvider instance that will be retained by the Extension Manager

Returns

true if the provider was registered; false otherwise (i.e. if scheme is not unique)

virtual void removePathProtocolProvider(const char *scheme) = 0

Removes a path protocol provider.

See also

addPathProtocolProvider()

Parameters: scheme – The unique name previously passed to addPathProtocolProvider()

virtual bool solveExtensions(const SolverInput &input, ExtensionInfo **extensions, size_t *extensionCount, const char **errorMessage) = 0

Runs the extension dependencies solver on the input.

Input is a list of extension, they can be names, full id, partial versions like ommi.foo-2.

If solver succeeds it returns a list of extensions that satisfy the input and true, otherwise errorMessage contains explanation of what failed.

Note

The returned array and error message is valid until next call of this function.

Parameters

input – The SolverInput containing a list of extensions
extensions – [out] If true returned, receives an array of ExtensionInfo instances that satisfy input, otherwise undefined
extensionCount – [out] If true returned, receives the count of items passed to extensions, otherwise undefined
errorMessage – [out] If false returned, receives an error message, otherwise undefined

Returns

true if the solver succeeds and extensions and extensionCount contain the array of extensions that satisfy input; false otherwise, errorMessage contains a description of the error, but extensions and extensionCount are undefined and should not be accessed.

virtual size_t getExtensionPackageCount() const = 0

Gets number of local extension packages.

Returns: the number of local extension packages

virtual void getExtensionPackages(ExtensionInfo *extensions) const = 0

Fills an array with local extension packages.

Note

This function will return all local extensions, including packages for other platforms, incompatible with current targets.

Parameters: extensions – An array of ExtensionInfo instances to be filled. It must be large enough to hold getExtensionPackageCount() entries.

virtual bool uninstallExtension(const char *extId) = 0

Removes a downloaded extension.

Parameters: extId – The extension ID to remove
Returns: true if the extension was removed; false otherwise

virtual size_t addRef() = 0

Atomically add one to the reference count.

Returns: The current reference count after one was added, though this value may change before read if other threads are also modifying the reference count. The return value is guaranteed to be non-zero.

virtual size_t release() = 0

Atomically subtracts one from the reference count.

If the result is zero, carb::deleteHandler() is called for this.

Returns: The current reference count after one was subtracted. If zero is returned, carb::deleteHandler() was called for this.

Public Static Functions

static inline constexpr carb::InterfaceDesc getInterfaceDesc() noexcept

Returns information about this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns: The carb::InterfaceDesc struct with information about this interface.

static inline constexpr carb::InterfaceDesc getLatestInterfaceDesc() noexcept

Returns information about the latest version of this interface.

Auto-generated by CARB_PLUGIN_INTERFACE() or CARB_PLUGIN_INTERFACE_EX.

Returns: The carb::InterfaceDesc struct with information about the latest version of this interface.