diff --git a/PhoenixAPI.md b/PhoenixAPI.md index dad9dee..6725f0c 100644 --- a/PhoenixAPI.md +++ b/PhoenixAPI.md @@ -21,7 +21,7 @@ Click on a Command below for more information. | [[DISM]] | Execute DISM with the provided arguments. | | [[FileCopyEx]] | Copy a single file and it's .mui's (if they exist) from a specified directory. | | [[FileDeleteEx]] | Delete a file if it exists. | -| [[FileSearch]] | Search for a file and return it's full path if it exists. If the file cannot be found an empty string is returned. | +| [[FileSearch]] | Search for a file and return it's full path if it exists. | | [[GetBinaryResource]] | Extract a binary resource from an executable file. | | [[GetStringResource]] | Extract a string resource from an executable file. | | [[InnoCleanup]] | Cleanup extracted Inno Setup files. | @@ -29,7 +29,7 @@ Click on a Command below for more information. | [[InnoRename]] | Rename extracted Inno Setup files. | | [[Innounp]] | Execute Innounp (Inno Setup Unpacker) with the provided arguments. | | [[JSONCompact]] | Compact/minify a JSON value. | -| [[JSONDelete]] | Add a new element/text/attribute to an XML file. | +| [[JSONDelete]] | Delete a JSON value. | | [[JSONPretty]] | Format and indent the JSON file for easy human reading. | | [[JSONRead]] | Read a JSON value. | | [[JSONWrite]] | Set/Modify an JSON value. | @@ -44,8 +44,9 @@ Click on a Command below for more information. | [[RunFromRam]] | Choose to redirect the programs folder to Boot.wim | | [[SetFileACL]] | Give full control for "Everyone" on a file or directory. | | [[SetRegACL]] | Take ownership and grant full control for "Everyone" on a registry key. | +| [[WebGetEx]] | Downloads files from the Internet. | | [[WixExtract]] | Extract files from an Windows Installer XML Toolset (WiX) installer. | -| [[XMLAdd]] | Delete a JSON value. | +| [[XMLAdd]] | Add a new element/text/attribute to an XML file. | | [[XMLDelete]] | Delete an XML path/value. | | [[XMLRead]] | Read an XML value. | | [[XMLRename]] | Rename a value in an XML file. | diff --git a/PhoenixAPI/WebGetEx.md b/PhoenixAPI/WebGetEx.md new file mode 100644 index 0000000..6ca3df0 --- /dev/null +++ b/PhoenixAPI/WebGetEx.md @@ -0,0 +1,72 @@ +# WebGet + +Downloads files from the Internet. + +This command is an extended version of the builtin PEBakery `WebGet` command. It utilizes Aria2 as the download engine and is useful for URL's that include javascript based redirects or CDN protection such as CloudFlare. + +Unless you require the extended functionality it is recommended to use the native `WebGet` command. + +## Syntax + +```pebakery +WebGet,,[,=][,Referer=][,TimeOut=][,UserAgent=][,NOERR] +``` + +### Arguments + +Optional arguments may be specified in any order. + +| Argument | Description | +| --- | --- | +| URL | URL of the file to download. Supported URI's are `HTTP`, `HTTPS`. | +| DestPath | The full path where the downloaded file will be saved. If the path does not exist it will be created. If the file exists it will be overwritten. | +| Hash Verification | **(Optional)** Downloads can be verified by validating the hash value of the downloaded file in the form of `=`. | +| | HashType= - Hash type to calculate. Supported hash types: `MD5`, `SHA1`, `SHA256`, `SHA384`, `SHA512`. | +| | HashDigest - The Hash digest used to verify the downloaded file. | +| Referer= | **(Optional)** Set an http referrer (Referer). | +| TimeOut= | **(Optional)** The time-span (in seconds) to wait for a response before the request times out. **Default:** 10 | +| UserAgent= | **(Optional)** Set a custom User-Agent string used to identify PEBakery to the website. | + +### Flags + +Flags may be specified in any order. + +| Flag | Description | +| --- | --- | +| NOERR | **(Optional)** Do not halt the build if the download fails. It will be the script developer's responsibility to handle the situation gracefully. | + +### Return Codes + +| Variable | Description | +| --- | --- | +| #r | When used in conjunction with the NOERR flag the return code can be tested and corrective action taken when a failure occurs. | +| | 0 - The request was successful. | +| | Non-Zero - Aria2 exit code reference: https://aria2.github.io/manual/en/html/aria2c.html#exit-status | + +## Remarks + +No checks are done to ensure that the local machine has a valid Internet connection or that there is enough disk space to download the file. If required these tests can be made using PEBakery's *Conditional Operators*. + +It is normally not necessary to modify User-Agent strings used to identify an application or browser to the website, however some strict or poorly behaved websites may have issues with various User-Agent strings. If you encounter this situation you may set a custom User-Agent to work around the issue. + +The WebGet User-Agent is resolved in the following order: + +1 The User-Agent defined by the `UserAgent=` argument (per-command). +1 Aria2 default user agent of `aria2/%VERSION` where $VERSION is replaced by the Aria2 program version. + +## Related + +## Examples + +### Example 1 + +```pebakery +// zlib source code will be downloaded to %BaseDir%\zlib.tar.gz. +WebGetEx,"https://zlib.net/zlib-1.2.11.tar.gz",%BaseDir%\zlib.tar.gz + +// Downloaded tar.gz file will be validated with its SHA256 digest. +WebGetEx,"https://zlib.net/zlib-1.2.11.tar.gz",%BaseDir%\zlib.tar.gz,SHA256=c3e5e9fdd5004dcb542feda5ee4f0ff0744628baf8ed2dd5d66f8ca1197cb1a1 + +// Download zlib.tar.gz and specify timout and referer +WebGetEx,"https://zlib.net/zlib-1.2.11.tar.gz",%BaseDir%\zlib.tar.gz,Referer=https://www.google.com,Timeout=30 +```