InstallFromFiles
Install product from provided installer. This function must be called with Administrator privilege. It is recommended to only install one product at a time to reduce chance of failure.
Syntax
Method ID
#define WA_VMOD_PATCH_INSTALL_FROM_FILES 50301
JSON Input Structure
{
"input": {
"method": 50301,
"signature": number,
"path": string,
"force_close": number,
"language": string,
"architecture": string,
"log_dir": string,
"online": number,
"patch_id": number,
"timeout": number,
"skip_signature_check": number,
"freezing_dependencies": [
string,
...
],
"delay": number,
"patches": [
string,
...
],
"force_install": boolean,
"requested_version": string,
"expected_installer_sha256": string,
"instance_id": string,
"enable_rollback": boolean
}
}
Input Properties
| Parameter | Type | Description |
|---|---|---|
signature | number | The signature id of the product returned from the detection call. |
path | string | Path to the installer. |
force_close | number | (optional) (Windows & macOS only) Whether to close running product or not before installing. Value 0 will not close blocking processes, 1 will try to close blocking processes. Default value is 0. |
language | string | (optional) (Windows & macOS only) Language identifier of the product to download (e.g: "en-us", "fr"). If the installer does not allow selecting language then this field is ignored. If the installer allows setting language but the specified language is not supported then the default language of the product is used. |
architecture | string | (optional) (Windows & macOS only) Architecture of product to install ("32-bit", "64-bit" and "arm64" (Mac only)). If the installer does not allow selecting architecture then this field is ignored. If the installer allows setting architecture and this field is not specified then default value is architecture of the installed product, with fallback to OS architecture on Windows. On Mac, only OS architecture is used. |
log_dir | string | (optional) (Windows & macOS only) Directory to contain log files if the installer supports it. An installer may write multiple log files to this directory. Default value is environment's temporary directory. |
online | number | (optional) (Windows & macOS only) Whether to use online database or not. Value 0 will disable online mode, value 1 will enable it. Default value is 0. |
patch_id | number | (optional) (Windows & macOS only) Patch identifier to get download information from local database (for Analog use case). By default, the function determines the correct patch identifier itself. |
timeout | number | (optional) (Windows & macOS only) Set timeout when executing a product (in the second). By default, timeout will be set at 30 minutes (1800 seconds) with recommended value from 1 minutes to 60 minutes (60 seconds to 3600 seconds). This field only accepts number values which is inputted in a correct number format and within ranges from 1 to 2147483647 (value 0 will result in WAAPI_ERROR_INVALID_INPUT_ARGS). Input value that does not satisfy requirements will result in undefined behaviour. Return WAAPI_ERROR_THREAD_TIMEOUT (code -49) when installation failed to respond in a timely manner, this error does not indicate product installation failed. |
skip_signature_check | number | (optional) (Windows & macOS only) Whether to disable the installer verification. Value 1 will disable such verification process. The default value is 1. |
freezing_dependencies | array<string> | (optional) (Linux only) (Linux only) The list of dependencies needs to be frozen. The value is an array of regex strings. Any package that matches the specified regex will not be upgraded. • []: The SDK will update any dependencies package as required from the patch.• ["python.*", "^libc6"]: The SDK will not upgrade dependencies matched mentioned regex.• [".*"]: The SDK will not upgrade any dependency. |
delay | number | (optional) (Linux only) (Linux only) The delay window time in seconds.Example: the patch is released on today. The value of delay is 3 days or 259200.• If the user calls this method during this timeframe, the SDK will return an error. • If the method is called after the 3-day timeframe, the SDK applies the patch. |
patches | array<string> | (optional) (Linux only) (Linux only) (System patching flow) Patch list which will be installed. The list is package names, which can be obtained from GetLatestInstaller (50300) with package manager's signature. |
force_install | boolean | (optional) (Windows only) (Windows only) Forces the SDK to preprocess and install the product even if the provided installer does not comply with security policies. Use this option only if you trust the installer and accept that the SDK may modify it during installation. If set to false (default), the SDK will validate the installer and fail with an error if any security issues are detected. |
requested_version | string | (optional) (Third-party patching flow) Specify the expected version for installation on the endpoint machine. If the installer's version does not match the requested version or the SDK cannot verify the version, the SDK will halt installation. A checksum database may need to be loaded beforehand. Alternatively, a single database patchv2.dat can be used instead. |
expected_installer_sha256 | string | (optional) (Third-party patching flow) The expected SHA-256 hash of the provided installer. If specified, the SDK calculates the SHA-256 hash of the installer and compares it with this value. If they do not match, the SDK halts the installation process. |
instance_id | string | (optional) (macOS and Linux) Specify the id of the target instance. If not specify, the engine will try to target the first detected instance. |
enable_rollback | boolean | (optional) (Windows & macOS only) (Third-party patching flow) Rolls the endpoint back to a previously installed version: when true, the SDK uninstalls the currently installed version and installs requested_version in its place, always performing the uninstall step even if the patch itself wouldn't require it. Defaults to false, in which case InstallFromFiles behaves as it does today.Must be paired with requested_version (the version to roll back to). Supplying enable_rollback: true alone returns WAAPI_ERROR_INVALID_INPUT_ARGS, with no endpoint change.Important note: Rollback is a full uninstall-and-reinstall cycle, not an in-place restore. App data, settings, and cache aren't preserved, and only the default instance is rolled back on multi-instance apps. If either step fails, the SDK does not auto-restore the prior version. |
JSON Output Structure
{
"result": {
"method": 50301,
"code": number,
"timing": number,
"timestamp": string,
"install_return_code": number,
"patch_id": number,
"signature": number,
"version": string,
"language": string,
"architecture": string,
"require_restart": number,
"require_close_first": number,
"require_uninstall_first": number,
"blocking_processes": [
string,
...
],
"log_paths": [
string,
...
],
"new_signature": number,
"source_timestamp": number,
"modified_dependencies": {
"<package_name>": {
"current_version": string,
"status": string
}
},
"patches": [
{
"name": string,
"status": string,
"version": string,
"require_app_restart": number,
"require_restart": number,
"require_uninstall_first": number,
"modified_dependencies": {
"<package_name>": {
"current_version": string,
"status": string
}
}
},
...
]
}
}
Output Properties
| Property | Type | Description |
|---|---|---|
result.method | number | The method ID that generated this result. |
result.code | number | The result code. See Result Codes. |
result.timing | number | The measured time for the method call in milliseconds. |
result.timestamp | string | The timestamp in seconds of when the call was made. |
result.install_return_code | number | (optional) The code returned from the installer after being invoked. |
result.patch_id | number | Internal identifier of the patch data used. |
result.signature | number | The signature identifier from the input. |
result.version | string | Detected version of the newly installed product; may not correct if installation requires restarting. |
result.language | string | The language code used for the installer. Empty value means not specified. |
result.architecture | string | The architecture used for the installer. |
result.require_restart | number | Value 1 means installation requires restarting, value 0 means installation does not require restarting. |
result.require_close_first | number | Value 1 means installation requires running products to be closed, value 0 means it is not required. |
result.require_uninstall_first | number | Value 1 means installation requires existing product to be uninstalled first, value 0 means it is not required. |
result.blocking_processes | array<string> | Name or path of the processes that blocked the installation and were terminated. |
result.log_paths | array<string> | Paths to the log files related to the installation process. |
result.new_signature | number | (optional) The new signature id after updating product to latest version. |
result.source_timestamp | number | (optional) The timestamp of cloud data being used for method with online mode. |
result.modified_dependencies | object | (optional) (Linux only) (Third-party patching flow) List of packages that have been modified when applying the patch. The result only contains packages that have been modified. If a package is not modified, it will not be shown in the list. |
result.modified_dependencies.<package_name> | object | (optional) The package name of a dependency. |
result.modified_dependencies.<package_name>.current_version | string | (optional) The current version of a dependency package on the current client machine. |
result.modified_dependencies.<package_name>.status | string | (optional) The status of a dependency package after the installation. • upgraded: the package is updated to the new version. • installed: the package is newly installed as a result of a patch. • removed: the package is removed as a result of a patch. • downgraded: the package is downgraded to an older version. |
result.patches | array<object> | (optional) (Linux only) (System patching flow) An array contains details of input patches after this method is completed. |
result.patches.name | string | The package name of a patch. |
result.patches.status | string | The state of a patch after this method is completed. • not_found: if patch was not found in result of GetLatestInstaller with System package manager signature. • not_found_in_cache: if this patch was not found in cache downloaded by DownloadMissingPatches. • download_failed: if patch failed in download phase. • cache_failed: if patch was found in OESIS Framework cache but cannot be used to install patch. • install_failed: patch was downloaded successfully but installation failed. • installed: patch was installed successfully. |
result.patches.version | string | The current version of the package on the machine. |
result.patches.require_app_restart | number | Indicate if an application should be restarted to successfully apply the patch. • 1: the application needs to be restarted. • 0: the application does not need to be restarted. |
result.patches.require_restart | number | Indicates if a machine should be restarted after the patch. • 1: the machine needs restart. • 0: the machine does not need to be restarted. |
result.patches.require_uninstall_first | number | Indicates if an application should be removed to successfully apply the patch. • 1: the application needs to be removed. • 0: the application does not need to be removed. |
result.patches.modified_dependencies | object | List of packages that have been modified when applying the patch. The result only contains packages that have been modified. If a package is not modified, it will not be shown in the list. |
result.patches.modified_dependencies.<package_name> | object | (optional) The package name of a dependency. |
result.patches.modified_dependencies.<package_name>.current_version | string | (optional) The current version of a dependency package on the current client machine. |
result.patches.modified_dependencies.<package_name>.status | string | (optional) The status of a dependency package after the installation. • upgraded: the package is updated to the new version. • installed: the package is newly installed as a result of a patch. • removed: the package is removed as a result of a patch. • downgraded: the package is downgraded to an older version. |
Result Codes
This method runs an installer and reports its outcome. A successful call has more than one possible code — see Remarks.
| Code | Constant | Description |
|---|---|---|
| 1006 | WA_VMOD_REDIRECTED_TO_SYSTEM_FLOW | The call was redirected to the system package manager flow (APT / DNF / SNAP) rather than running an installer file. |
| 1005 | WA_VMOD_INSTALLATION_NEED_APPLICATION_RESTART | The product installed successfully and the application must be restarted before the new version is in use. Treat the install as successful, then prompt the user to restart the affected application — a full reboot is not required unless another code asks for one. See Remarks. |
| 1003 | WA_VMOD_INSTALLATION_NEED_RESTART | The product installed successfully and the operating system must be restarted before the new version is in use. Treat the install as successful, then prompt the user to reboot; after the restart, detect the product again to confirm the installed version. See Remarks. |
| 0 | WAAPI_OK | The product installed successfully and no restart is required. |
| -5 | WAAPI_ERROR_NOT_INITIALIZED | This method was called while the SDK is not initialized. Call wa_api_setup and verify it returned a success code before invoking, and do not invoke after wa_api_teardown. |
| -7 | WAAPI_ERROR_COMPONENT_NOT_LICENSED | The license does not permit the mode the SDK is running in — online mode on an offline-only license, or the reverse. Checked before the call is dispatched, so no installer runs. |
| -14 | WAAPI_ERROR_DATABASE_CORRUPTED | The patch database loaded, but this product's entry in it could not be read. Re-download the patch data; re-calling LoadPatchDatabase (50302) on the same file will not help. |
| -16 | WAAPI_ERROR_DATABASE_NOT_INITIALIZED | The patch database has not been loaded. Call LoadPatchDatabase (50302) before this method. |
| -17 | WAAPI_ERROR_NO_CONNECTION | A network source needed during installation could not be reached. Check connectivity and any proxy configuration. |
| -19 | WAAPI_ERROR_INVALID_CREDENTIALS | Credentials supplied for the operating-system update path were rejected. |
| -20 | WAAPI_ERROR_INVALID_INPUT_ARGS | A required input key is missing or malformed — most commonly method, signature, or the installer path list. |
| -21 | WAAPI_ERROR_INVALID_JSON | The provided json_in is not valid JSON, or a JSON document read during installation could not be parsed. |
| -22 | WAAPI_ERROR_ACCESS_DENIED | The installer could not be read, or its location could not be accessed — most often a permissions problem on the file or the folder containing it. Confirm the process has read access to both, and that it can write to the working directory. Elevation is typically required. |
| -23 | WAAPI_ERROR_INVALID_STATE | The system or product is in a state that prevents installation. |
| -26 | WAAPI_ERROR_DISPATCH_EXCEPTION | A C++ exception escaped while the call was being dispatched. The call did not complete. Treat as an internal error and report it with the SDK debug log. |
| -27 | WAAPI_ERROR_NATIVE_API | A call the SDK made into an operating-system or system-library API failed with an error the SDK does not yet classify. Native failures are mapped to specific codes wherever they are recognised — a missing file to WAAPI_ERROR_NOT_FOUND (-28), a permissions failure to WAAPI_ERROR_ACCESS_DENIED (-22), and so on — and this code is the fallback for a case that mapping does not cover. So it tells you where the failure came from, not what it was: read the underlying error from the response's error_message field. On this method such calls arise while preparing and running the installer. |
| -28 | WAAPI_ERROR_NOT_FOUND | The file at the supplied path does not exist, or the product has no entry in the patch database. Confirm the installer path is correct and that the download completed before calling this method. |
| -33 | WAAPI_ERROR_CRYPTO | Verifying the installer could not be completed: computing its hash, or extracting and parsing its certificate chain, failed. Distinct from WAAPI_ERROR_INVALID_SIGNATURE (-47), where the signature was read but does not belong to the expected vendor. |
| -42 | WAAPI_ERROR_SCRIPTING_GENERAL | The product's install script returned output that could not be parsed, or the scripting engine failed. |
| -47 | WAAPI_ERROR_INVALID_SIGNATURE | The installer's signature does not match the signing information recorded for this product. A common cause is the vendor renewing its code-signing certificate before the patch data caught up. Do not run the installer. Refresh the patch data and retry. Only checked when signature verification is requested (skip_signature_check: 0); verification is skipped by default. |
| -48 | WAAPI_ERROR_HASH_MISMATCH | The installer's SHA-256 does not match the expected_installer_sha256 you supplied. Only checked when you pass that value. Do not run the installer — re-download it and recompute the expected hash before retrying. |
| -49 | WAAPI_ERROR_THREAD_TIMEOUT | The installation did not finish within the timeout. Confirm the installer does not require interactive input that would block a silent installation. The installer may still be running, so confirm the product's state before retrying. |
| -50 | WAAPI_ERROR_NO_ACTIVE_USER_SESSION | The product requires an interactive user session and none was available. |
| -58 | WAAPI_ERROR_INVALID_OUTPUT_ARGS | The call succeeded but its response failed the SDK's own output-schema check, so this code replaces the success code. Only occurs while JSON I/O validation is enabled. Treat as an internal error. |
| -63 | WAAPI_ERROR_INVALID_INSTANCE_ID | The value provided for instance_id could not be resolved. |
| -66 | WAAPI_ERROR_TEARDOWN_BUSY | The call arrived while wa_api_teardown was still running; nothing was dispatched. The response body reports WAAPI_ERROR_NOT_INITIALIZED (-5) on this path rather than this code; trust the return value. |
| -69 | WAAPI_ERROR_MEMORY_CORUPTED | A non-standard exception escaped while the call was being dispatched — typically a structured or access-violation fault. Treat as an internal error and report it with the SDK debug log. |
| -70 | WAAPI_ERROR_RESOURCE_BUSY | A resource the installation needs is held by another operation. Retryable once the other operation finishes. |
| -78 | WAAPI_ERROR_FILE_MARKED_MOTW | The installer carries a Mark-of-the-Web tag identifying it as downloaded from an untrusted zone, so it was not executed. Supply a file without the tag. |
| -79 | WAAPI_ERROR_LOW_INTEGRITY_LEVEL | The installer file's integrity level is too low to execute safely, so it was not run. |
| -80 | WAAPI_ERROR_FAILED_TO_PREPROCESS_INSTALLER | The pre-execution preparation of the installer failed — copying it to a working location, clearing its zone tag, or staging it for an unelevated user. The installation was not attempted. |
| -1016 | WA_VMOD_ERROR_INTERNAL_FORMAT_MISMATCH | Patch data needed for this product could not be read because its format was not what the SDK expects. Usually transient — refresh the patch data and retry. |
| -1018 | WA_VMOD_ERROR_4V_NOT_INITIALIZED | The detection engine the patch component depends on is not initialized, so the product could not be resolved. |
| -1026 | WA_VMOD_ERROR_PRODUCT_NOT_SUPPORTED | The requested signature is not present in the loaded patch data — including when the patch database was never loaded — so no installation applies to it. Call LoadPatchDatabase (50302) first, then confirm the signature is patch-supported. |
| -1027 | WA_VMOD_ERROR_LANGUAGE_NOT_SUPPORTED | The installer's language does not match any package the patch database holds for this product. |
| -1028 | WA_VMOD_ERROR_ARCHITECTURE_NOT_SUPPORTED | The installer's architecture does not match any package the patch database holds for this product. Supply an installer matching the endpoint's architecture. |
| -1029 | WA_VMOD_ERROR_NOT_RECOGNIZED_FILE | The supplied file is not an installer this product recognizes. Verify the path points at the installer produced by GetLatestInstaller (50300). |
| -1030 | WA_VMOD_ERROR_CANNOT_TERMINATE_PRODUCT | A process holding the product open could not be closed, so the installation did not proceed. Pass force_close: 1 to close blocking processes automatically, or close the application manually and retry. |
| -1033 | WA_VMOD_ERROR_NEED_UNINSTALL_PRODUCT_FIRST | The installed version cannot be upgraded in place. Uninstall the current version and then retry — the SDK does not uninstall anything on its own. |
| -1034 | WA_VMOD_ERROR_INSTALLATION_FAILED | The installer ran and did not succeed, and the SDK could not narrow the cause further. It also covers the case where the installer reported success but the product's version did not change afterwards. The installer's own exit code and log paths are in the response, and reading those logs is the next step. |
| -1036 | WA_VMOD_ERROR_EXTRACT_FAILED | An archived installer could not be extracted before execution. |
| -1037 | WA_VMOD_ERROR_OUT_OF_MEMORY | The SDK ran out of memory during installation. Retry with more memory available, and close other installers or large applications first. |
| -1038 | WA_VMOD_ERROR_DATA_TYPE_NOT_SUPPORTED | The patch data describes an installer delivery method this SDK build does not support. Refresh the patch data; if it persists, this product cannot be patched automatically with this SDK version — upgrade the SDK or patch it manually. |
| -1041 | WA_VMOD_ERROR_ANOTHER_MSI_INSTALLATION_INPROGRESS | Another Windows Installer operation is already running, so this one could not start. Wait for it to finish and retry. |
| -1042 | WA_VMOD_ERROR_VERSION_MISMATCH | The installer's version does not match the version the patch database recorded for this product. Detect the product again and re-resolve the patch with GetLatestInstaller (50300) before retrying. |
| -1043 | WA_VMOD_ERROR_CANNOT_VERIFY | The installer could not be verified because the material needed to verify it was unavailable — no signing information is recorded for this product, no comparable hash is available, or the file's hash could not be computed. Confirm the file was not modified or truncated after download, and retry. |
| -1046 | WA_VMOD_ERROR_OS_ARCHITECTURE_NOT_SUPPORTED | The product has no installer for this machine's OS architecture. |
| -1051 | WAAPI_ERROR_SYSTEM_PRIVILEGE_REQUIRED | The installation requires the SYSTEM account and the SDK is not running under it. |
| -1052 | WA_VMOD_VERSION_LOCK_NOT_SUPPORTED | A specific version was requested but cannot be served — either it is not in the OESIS database, or the vendor publishes no version-specific installer for this product. Confirm the product supports a version-specific installer before requesting a locked version. |
| -1055 | WAAPI_ERROR_RDP_MULTI_SESSION_UNSUPPORTED | The machine has multiple active remote-desktop sessions, which this installation does not support. |
| -1056 | WAAPI_ERROR_RDP_USER_MISMATCH | The remote-desktop session's user does not match the user the installation must run as. |
| -1064 | WAAPI_VMOD_ERROR_COMPLETING_INSTALLATION_SCENARIO | The product's own installation scenario did not complete. Reported for products that manage their own multi-step installation. |
| -1065 | WAAPI_VMOD_ERROR_INSTALLATION_SCENARIO_CANCELED | The product's installation scenario was canceled before it finished. Reported for products that manage their own multi-step installation. |
| -1072 | WAAPI_ERROR_INSUFFICIENT_DISK_SPACE | There is not enough free disk space to stage or run the installer. |
| -1082 | WAAPI_ERROR_INVALID_INSTALLER | The supplied file is not a valid installer — it could not be identified as an executable package the SDK can run. |
note
Other codes may be returned. See the full Result Codes reference for the complete list.
Remarks
Error Handling
The results of this function are determined by the error code returned by the call. Always check both the function return value and the result.code field in the output JSON. Test success with the WAAPI_SUCCESS macro, which treats any value >= 0 as success, rather than comparing against 0 — this method has three distinct success codes and 0 is only one of them.
A successful installation reports which restart is needed, and the answer comes from the patch data rather than from the installer:
WAAPI_OK(0) — installed, no restart required.WA_VMOD_INSTALLATION_NEED_RESTART(1003) — installed, the operating system must be restarted.WA_VMOD_INSTALLATION_NEED_APPLICATION_RESTART(1005) — installed, the application must be restarted.
Whether a restart is needed — and whether it is the operating system or only the application — is recorded per product in the patch data, and for some products the installer's own outcome decides. Where the patch data says no restart is needed, the call reports 0 even if the installer itself signalled a reboot.
For more detail on how the two restart outcomes are distinguished, see How the OESIS SDK distinguishes OS restart and application restart when patching products.
Prerequisites
Call LoadPatchDatabase (50302) first. Without it the call fails in one of two ways: with WAAPI_ERROR_DATABASE_NOT_INITIALIZED (-16), or with WA_VMOD_ERROR_PRODUCT_NOT_SUPPORTED (-1026) when the signature cannot be found in patch data that was never loaded. Both have the same fix — load the patch database, then confirm the signature is patch-supported. The installer path this method takes is normally the file that GetLatestInstaller (50300) downloaded.
The call requires Administrator privilege, and OPSWAT recommends installing one product at a time rather than running several installations concurrently.
Examples
Examples will be added here demonstrating the usage of this method.
See Also
Last updated: 2026-10-01