目录

ModuleInstall

Overview

Provides the on-demand distribution capability offered by AppGallery Kit.

Since: 5.0.3(15)

Summary

[h2]Files

Name Description
module_install.h Declares the APIs provided by the on-demand distribution capability.

[h2]Types

Name Description
typedef struct ModuleInstall_InstalledModule ModuleInstall_InstalledModule Module information.
typedef struct ModuleInstall_FetchModulesResult ModuleInstall_FetchModulesResult Module installation result.
typedef struct ModuleInstall_StatusCallback ModuleInstall_StatusCallback Module installation status callback.
typedef void (*ModuleInstall_OnStatusCallback)(char *bundleName, char *eventInfo) Listener callback.

[h2]Enumerations

Name Description

ModuleInstall_ErrCode {

E_NO_ERROR = 0,

E_PARAMS = 401,

E_QUERY_MODULE = 1006500001,

E_REPEATED_CALL = 1006500002,

E_CONNECT_SA = 1006500004,

E_OFF_WITHOUT_ON = 1006500006,

E_CONNECT_SERVICE_EXTENSION = 1006500007,

E_WRITE_PARAM = 1006500008,

E_REQUEST_SERVER = 1006500009,

E_RESPONSE_INVALID = 1006500010,

E_INNER_ERROR = 1006500011,

E_INTERNAL_COMMUNICATION = 1006500012,

E_INVALID_TASK_ID = 1006500013

}

 Enumerates error codes.

ModuleInstall_InstallStatus {

INSTALLED = 0,

NOT_INSTALLED = 1

}

 Enumerates installation statuses.

ModuleInstall_RequestCode {

MODULE_ALREADY_EXISTS = -8,

MODULE_UNAVAILABLE = -7,

INVALID_REQUEST = -6,

NETWORK_ERROR = -5,

INVOKER_VERIFICATION_FAILED = -4,

FOREGROUND_REQUIRED = -3,

ACTIVE_SESSION_LIMIT_EXCEEDED = -2,

FAILURE = -1,

SUCCESS = 0,

DOWNLOAD_WAIT_WIFI = 1

}

 Enumerates request codes.

ModuleInstall_TaskStatus {

CREATE_TASK_FAILED = -4,

HIGHER_VERSION_INSTALLED = -3,

TASK_ALREADY_EXISTS = -2,

TASK_UNFOUND = -1,

TASK_CREATED = 0,

DOWNLOADING = 1,

DOWNLOAD_PAUSED = 2,

DOWNLOAD_WAITING = 3,

DOWNLOAD_SUCCESSFUL = 4,

DOWNLOAD_FAILED = 5,

DOWNLOAD_WAIT_FOR_WIFI = 6,

INSTALL_WAITING = 20,

INSTALLING = 21,

INSTALL_SUCCESSFUL = 22,

INSTALL_FAILED = 23

}

 Enumerates task statuses.

[h2]Functions

Name Description
ModuleInstall_ErrCode HMS_ModuleInstall_GetInstalledModule(const char *moduleName, unsigned int length, ModuleInstall_InstalledModule **installedModule) Queries whether a module has been installed.
char *HMS_ModuleInstall_GetInstalledModuleName(const ModuleInstall_InstalledModule *installedModule) Obtains the module name.
int HMS_ModuleInstall_GetInstalledModuleType(const ModuleInstall_InstalledModule *installedModule) Obtains the module type.
ModuleInstall_InstallStatus HMS_ModuleInstall_GetModuleInstallStatus(const ModuleInstall_InstalledModule *installedModule) Obtains the module installation status.
ModuleInstall_ErrCode HMS_ModuleInstall_FetchModules(const char *bundleName, unsigned int length, char **moduleNames, unsigned int moduleNamesLength, ModuleInstall_FetchModulesResult **fetchModulesResult) Requests to download a module.
ModuleInstall_RequestCode HMS_ModuleInstall_GetFetchModulesRequestCode(const ModuleInstall_FetchModulesResult *fetchModulesResult) Obtains the module download request code.
ModuleInstall_TaskStatus HMS_ModuleInstall_GetFetchModulesTaskStatus( const ModuleInstall_FetchModulesResult *fetchModulesResult) Obtains the module download task status.
char *HMS_ModuleInstall_GetFetchModulesTaskId(const ModuleInstall_FetchModulesResult *fetchModulesResult) Obtains the module download task ID.
char *HMS_ModuleInstall_GetFetchModulesDesc(const ModuleInstall_FetchModulesResult *fetchModulesResult) Obtains the module download description.
char *HMS_ModuleInstall_GetFetchModules(const ModuleInstall_FetchModulesResult *fetchModulesResult) Obtains the name of the downloaded module.
int HMS_ModuleInstall_GetFetchModulesTotalSize(const ModuleInstall_FetchModulesResult *fetchModulesResult) Obtains the total download size of the module.
int HMS_ModuleInstall_GetFetchModulesDownloadedSize(const ModuleInstall_FetchModulesResult *fetchModulesResult) Obtains the downloaded size of the module.
ModuleInstall_ErrCode HMS_ModuleInstall_CancelTask(const char *taskId, unsigned int length, unsigned int cancelResult) Cancels a download task.
ModuleInstall_ErrCode HMS_ModuleInstall_PauseTask(const char *taskId) Pauses a download task.
ModuleInstall_ErrCode HMS_ModuleInstall_ShowCellularDataConfirmation(const char *taskId, unsigned int length, unsigned int showResult) Displays a mobile data reminder pop-up.
ModuleInstall_StatusCallback *HMS_ModuleInstall_CreateStatusCallback(ModuleInstall_OnStatusCallback *onStatusCallback) Creates a callback for listening for the download progress.
ModuleInstall_ErrCode HMS_ModuleInstall_On(const char *bundleName, unsigned int length, unsigned int appIndex, unsigned int period, ModuleInstall_StatusCallback **callback) Listens for the download progress.
void HMS_ModuleInstall_ReleaseStatusCallback(ModuleInstall_StatusCallback *statusCallback) Releases the callback used for download progress listening.
ModuleInstall_ErrCode HMS_ModuleInstall_Off(const char *bundleName, unsigned int length, unsigned int appIndex) Cancels the download progress listener.

Type Description

[h2]ModuleInstall_InstalledModule

typedef struct ModuleInstall_InstalledModule ModuleInstall_InstalledModule

Description

Module information.

Since: 5.0.3(15)

[h2]ModuleInstall_FetchModulesResult

typedef struct ModuleInstall_FetchModulesResult ModuleInstall_FetchModulesResult

Description

Module installation result.

Since: 5.0.3(15)

[h2]ModuleInstall_StatusCallback

typedef struct ModuleInstall_StatusCallback ModuleInstall_StatusCallback

Description

Module installation status callback.

Since: 5.0.3(15)

[h2]ModuleInstall_OnStatusCallback

typedef void (*ModuleInstall_OnStatusCallback)(char *bundleName, char *eventInfo)

Description

Listener callback.

Since: 5.0.3(15)

Enumeration Description

[h2]ModuleInstall_ErrCode

enum ModuleInstall_ErrCode

Description

Enumerates error codes.

Since: 5.0.3(15)

Value Description
E_NO_ERROR = 0 Successful.
E_PARAMS = 401 Invalid parameter.
E_QUERY_MODULE = 1006500001 Failed to call an API of the Bundle Manager Service (BMS).
E_REPEATED_CALL = 1006500002 The API is called repeatedly with the same input.
E_CONNECT_SA = 1006500004 Service exception.
E_OFF_WITHOUT_ON = 1006500006 Not used together with the HMS_ModuleInstall_On API.
E_CONNECT_SERVICE_EXTENSION = 1006500007 Failed to connect to the service.
E_WRITE_PARAM = 1006500008 Failed to write parameters.
E_REQUEST_SERVER = 1006500009 Failed to request the service.
E_RESPONSE_INVALID = 1006500010 Response parameters cannot be parsed.
E_INNER_ERROR = 1006500011 Internal error.
E_INTERNAL_COMMUNICATION = 1006500012

Internal communication error.

Since: 26.0.0
E_INVALID_TASK_ID = 1006500013

Invalid task ID.

Since: 26.0.0

[h2]ModuleInstall_InstallStatus

enum ModuleInstall_InstallStatus

Description

Enumerates installation statuses.

Since: 5.0.3(15)

Value Description
INSTALLED = 0 Installed.
NOT_INSTALLED = 1 Not installed.

[h2]ModuleInstall_RequestCode

enum ModuleInstall_RequestCode

Description

Enumerates on-demand module download request codes.

Since: 5.0.3(15)

Value Description
MODULE_ALREADY_EXISTS = -8 The module already exists.
MODULE_UNAVAILABLE = -7 The module does not exist or does not match the device.
INVALID_REQUEST = -6 The request is invalid because it contains inaccurate information.
NETWORK_ERROR = -5 The request fails due to a network error.
INVOKER_VERIFICATION_FAILED = -4 The caller information is abnormal.
FOREGROUND_REQUIRED = -3 On-demand loading is allowed only when the app is running in the foreground.
ACTIVE_SESSION_LIMIT_EXCEEDED = -2 The request is denied because at least one download task is in progress.
FAILURE = -1 Failed.
SUCCESS = 0 Successful.
DOWNLOAD_WAIT_WIFI = 1

Mobile data is in use.

Call the HMS_ModuleInstall_ShowCellularDataConfirmation API to ask the user whether to use mobile data for the download.

[h2]ModuleInstall_TaskStatus

enum ModuleInstall_TaskStatus

Description

Enumerates task statuses.

Since: 5.0.3(15)

Value Description
CREATE_TASK_FAILED = -4 Failed to create a download task.
HIGHER_VERSION_INSTALLED = -3 The same or a later version already exists on the user's device.
TASK_ALREADY_EXISTS = -2 The download task already exists.
TASK_UNFOUND = -1 No download task exists.
TASK_CREATED = 0 A download task is created successfully.
DOWNLOADING = 1 Downloading.
DOWNLOAD_PAUSED = 2 Paused.
DOWNLOAD_WAITING = 3 Pending download.
DOWNLOAD_SUCCESSFUL = 4 Download successful.
DOWNLOAD_FAILED = 5 Download failed.
DOWNLOAD_WAIT_FOR_WIFI = 6 Scheduled to download with Wi-Fi.
INSTALL_WAITING = 20 Waiting to install.
INSTALLING = 21 Installing.
INSTALL_SUCCESSFUL = 22 Installation completed.
INSTALL_FAILED = 23 Installation failed.

Function Description

[h2]HMS_ModuleInstall_GetInstalledModule

ModuleInstall_ErrCode HMS_ModuleInstall_GetInstalledModule(const char *moduleName, unsigned int length,
    ModuleInstall_InstalledModule **installedModule)

Description

Queries whether a module has been installed.

System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall

Since: 5.0.3(15)

Parameters:

Name Description
const char *moduleName Module name.
unsigned int length Length of the module name. A module name can contain a maximum of 512 characters.
ModuleInstall_InstalledModule **installedModule Module information.

Returns:

E_NO_ERROR: The operation is successful. E_PARAMS: The input parameters are invalid. E_QUERY_MODULE: An exception occurs when an API of the BMS is called.

[h2]HMS_ModuleInstall_GetInstalledModuleName

char *HMS_ModuleInstall_GetInstalledModuleName(const ModuleInstall_InstalledModule *installedModule)

Description

Obtains the module name.

System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall

Since: 5.0.3(15)

Parameters:

Name Description
ModuleInstall_InstalledModule *installedModule Module information.

Returns:

Module name.

[h2]HMS_ModuleInstall_GetInstalledModuleType

int HMS_ModuleInstall_GetInstalledModuleType(const ModuleInstall_InstalledModule *installedModule)

Description

Obtains the module type.

System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall

Since: 5.0.3(15)

Parameters:

Name Description
ModuleInstall_InstalledModule *installedModule Module information.

Returns:

Module type. For details about the values, please refer to bundleManager.ModuleType. When ModuleInstall_InstallStatus is 1, 0 will be returned by default.

[h2]HMS_ModuleInstall_GetModuleInstallStatus

ModuleInstall_InstallStatus HMS_ModuleInstall_GetModuleInstallStatus(const ModuleInstall_InstalledModule *installedModule)

Description

Obtains the module installation status.

System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall

Since: 5.0.3(15)

Parameters:

Name Description
ModuleInstall_InstalledModule *installedModule Module information.

Returns:

Module installation status. For details, please refer to ModuleInstall_InstallStatus.

[h2]HMS_ModuleInstall_FetchModules

ModuleInstall_ErrCode HMS_ModuleInstall_FetchModules(const char *bundleName, unsigned int length, char **moduleNames, unsigned int moduleNamesLength, ModuleInstall_FetchModulesResult **fetchModulesResult)

Description

Requests to download a module.

System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall

Since: 5.0.3(15)

Parameters:

Name Description
const char *bundleName Package name.
unsigned int length Length of the package name. A package name can contain a maximum of 512 characters.
char **moduleNames Array of module names.
unsigned int moduleNamesLength Length of the module name array. An array can contain a maximum of 512 characters.
ModuleInstall_FetchModulesResult **fetchModulesResult Module installation result.

Returns:

E_NO_ERROR: The operation is successful. E_PARAMS: The input parameters are invalid. E_CONNECT_SA: A service exception occurs. E_CONNECT_SERVICE_EXTENSION: Service connection fails. E_WRITE_PARAM: Failed to write parameters. E_REQUEST_SERVER: The service request fails. E_RESPONSE_INVALID: The response parameters cannot be parsed. E_INNER_ERROR: An internal error occurs.

[h2]HMS_ModuleInstall_GetFetchModulesRequestCode

ModuleInstall_RequestCode HMS_ModuleInstall_GetFetchModulesRequestCode(const ModuleInstall_FetchModulesResult *fetchModulesResult)

Description

Obtains the module download request code.

System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall

Since: 5.0.3(15)

Parameters:

Name Description
ModuleInstall_FetchModulesResult *fetchModulesResult Module installation result.

Returns:

On-demand module download request code. For details, please refer to ModuleInstall_RequestCode.

[h2]HMS_ModuleInstall_GetFetchModulesTaskStatus

ModuleInstall_TaskStatus HMS_ModuleInstall_GetFetchModulesTaskStatus(const ModuleInstall_FetchModulesResult *fetchModulesResult)

Description

Obtains the module download task status.

System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall

Since: 5.0.3(15)

Parameters:

Name Description
const ModuleInstall_FetchModulesResult *fetchModulesResult Module installation result.

Returns:

Module download task status. For details, please refer to ModuleInstall_TaskStatus.

[h2]HMS_ModuleInstall_GetFetchModulesTaskId

char *HMS_ModuleInstall_GetFetchModulesTaskId(const ModuleInstall_FetchModulesResult *fetchModulesResult)

Description

Obtains the module download task ID.

System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall

Since: 5.0.3(15)

Parameters:

Name Description
const ModuleInstall_FetchModulesResult *fetchModulesResult Module installation result.

Returns:

Task ID.

[h2]HMS_ModuleInstall_GetFetchModulesDesc

char *HMS_ModuleInstall_GetFetchModulesDesc(const ModuleInstall_FetchModulesResult *fetchModulesResult)

Description

Obtains the module download description.

System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall

Since: 5.0.3(15)

Parameters:

Name Description
const ModuleInstall_FetchModulesResult *fetchModulesResult Module installation result.

Returns:

Download description.

[h2]HMS_ModuleInstall_GetFetchModules

char* HMS_ModuleInstall_GetFetchModules(const ModuleInstall_FetchModulesResult *fetchModulesResult)

Description

Obtains the name of the downloaded module.

System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall

Since: 5.0.3(15)

Parameters:

Name Description
const ModuleInstall_FetchModulesResult *fetchModulesResult Module installation result.

Returns:

Name of the downloaded module.

[h2]HMS_ModuleInstall_GetFetchModulesTotalSize

int HMS_ModuleInstall_GetFetchModulesTotalSize(const ModuleInstall_FetchModulesResult *fetchModulesResult)

Description

Obtains the total download size of the module.

System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall

Since: 5.0.3(15)

Parameters:

Name Description
const ModuleInstall_FetchModulesResult *fetchModulesResult Module installation result.

Returns:

Total download size.

[h2]HMS_ModuleInstall_GetFetchModulesDownloadedSize

int HMS_ModuleInstall_GetFetchModulesDownloadedSize(const ModuleInstall_FetchModulesResult *fetchModulesResult)

Description

Obtains the downloaded size of the module.

System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall

Since: 5.0.3(15)

Parameters:

Name Description
const ModuleInstall_FetchModulesResult *fetchModulesResult Module installation result.

Returns:

Downloaded size of the module.

[h2]HMS_ModuleInstall_CancelTask

ModuleInstall_ErrCode HMS_ModuleInstall_CancelTask(const char *taskId, unsigned int length, unsigned int cancelResult)

Description

Cancels a download task.

System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall

Since: 5.0.3(15)

Parameters:

Name Description
const char *taskId Task ID.
unsigned int length Length of the task ID. A task ID can contain a maximum of 512 characters.
unsigned int cancelResult

Download cancellation result.

0: Successful.

1: Failed.

Returns:

E_NO_ERROR: The operation is successful. E_PARAMS: The input parameters are invalid. E_CONNECT_SERVICE_EXTENSION: Service connection fails. E_WRITE_PARAM: Failed to write parameters. E_REQUEST_SERVER: The service request fails. E_RESPONSE_INVALID: The response parameters cannot be parsed.

[h2]HMS_ModuleInstall_PauseTask

ModuleInstall_ErrCode HMS_ModuleInstall_PauseTask(const char *taskId)

Description

Pauses a download task.

System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall

Since: 26.0.0

Parameters:

Name Description
const char *taskId Task ID.

Returns:

E_NO_ERROR: The operation is successful. E_INVALID_TASK_ID: Invalid task ID. E_INTERNAL_COMMUNICATION: Internal communication error.

[h2]HMS_ModuleInstall_ShowCellularDataConfirmation

ModuleInstall_ErrCode HMS_ModuleInstall_ShowCellularDataConfirmation(const char *taskId, unsigned int length, unsigned int showResult)

Description

Displays a mobile data reminder pop-up.

System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall

Since: 5.0.3(15)

Parameters:

Name Description
const char *taskId Task ID.
unsigned int length Length of the task ID. A task ID can contain a maximum of 512 characters.
unsigned int showResult

Result of displaying the mobile data reminder pop-up.

0: Successful.

1: Failed.

Returns:

E_NO_ERROR: The operation is successful. E_PARAMS: The input parameters are invalid. E_CONNECT_SERVICE_EXTENSION: Service connection fails. E_WRITE_PARAM: Failed to write parameters. E_REQUEST_SERVER: The service request fails. E_RESPONSE_INVALID: The response parameters cannot be parsed.

[h2]HMS_ModuleInstall_CreateStatusCallback

ModuleInstall_StatusCallback *HMS_ModuleInstall_CreateStatusCallback(ModuleInstall_OnStatusCallback *onStatusCallback)

Description

Creates a callback for listening for the download progress.

System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall

Since: 5.0.3(15)

Parameters:

Name Description
ModuleInstall_OnStatusCallback *onStatusCallback Callback for listening for the download progress.

Returns:

Callback for listening for the download progress.

[h2]HMS_ModuleInstall_On

ModuleInstall_ErrCode HMS_ModuleInstall_On(const char *bundleName, unsigned int length, unsigned int appIndex, unsigned int period, ModuleInstall_StatusCallback **callback)

Description

Listens for the download progress.

System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall

Since: 5.0.3(15)

Parameters:

Name Description
const char *bundleName Package name.
unsigned int length Length of the package name. A package name can contain a maximum of 512 characters.
unsigned int appIndex App twin index.
unsigned int period Listening period.
ModuleInstall_StatusCallback **callback Callback for listening for the download progress.

Returns:

E_NO_ERROR: The operation is successful. E_PARAMS: The input parameters are invalid. E_REPEATED_CALL: The API is called repeatedly. E_CONNECT_SA: A service exception occurs.

[h2]HMS_ModuleInstall_ReleaseStatusCallback

void HMS_ModuleInstall_ReleaseStatusCallback(ModuleInstall_StatusCallback *statusCallback)

Description

Releases the callback used for download progress listening.

System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall

Since: 5.0.3(15)

Parameters:

Name Description
ModuleInstall_StatusCallback *statusCallback Callback for listening for the download progress.

[h2]HMS_ModuleInstall_Off

ModuleInstall_ErrCode HMS_ModuleInstall_Off(const char *bundleName, unsigned int length, unsigned int appIndex)

Description

Cancels the download progress listener.

System capability: SystemCapability.AppGalleryService.Distribution.OnDemandInstall

Since: 5.0.3(15)

Parameters:

Name Description
const char *bundleName Package name.
unsigned int length Length of the package name. A package name can contain a maximum of 512 characters.
unsigned int appIndex App twin index.

Returns:

E_NO_ERROR: The operation is successful. E_PARAMS: The input parameters are invalid. E_OFF_WITHOUT_ON: The API is not used with the listening API. E_CONNECT_SA: A service exception occurs.