A CURL Wrapper for Neutralino
This cross-platform CURL wrapper comes with the following features:
- Fast downloads and uploads via HTTP, HTTPS, FTP, FTPS.
- Supports custom HTTP-headers, e.g. for API authentication.
- No more headaches about CORS.
- Custom parameters support all possible CURL-protocols, like IMAP, POP3, SMTP, SMB, SCP, TELNET, WS, MQTT, LDAP and more.
- Emits JS events to for progress monitoring.
Clone this repo, and cd to the project folder.
Copy the content from _install/YOUR_PLATFORM/bin/
to resources/bin/
.
Then enter
neu update --latest
neu run
neutralino-curl is not a classic WebSocket-bound extension. It only consists of the CURL binary for your platform and a JS lib.
- Copy the content from
_install/YOUR_PLATFORM/bin/
toextensions/curl/bin/
. - Include
extensions/neutralino-curl/curl.js
in yourindex.hml
file. - Init CURL and add the required events to
main.js
.
The extensions
folder needs to be placed beside your resources..neu
folder:
app.exe
resources.neu
extensions
The extensions
folder goes into your app bundle's Resources
folder. This can be automated with Neutralino Build Scripts.
let CURL = new NeutralinoCurl();
Set HTTP custom-headers. Use this once, it applies to all further operations:
CURL.addHttpHeader('X-API-Token', '1234');
CURL.addHttpHeader('X-API-User', 'jimbo');
GET-Request:
let result = await CURL.get("https://domain.com/api-endpoint");
POST-Request:
let d = {
field1: 1,
field2: 2
}
await CURL.post("https://domain.com/api-endpoint", d);
Download:
await CURL.download("https://file.zip");
Download as:
await CURL.download("https://file.zip", 'renamed_file.zip');
Upload :
await CURL.upload("file.zip, "https://server.com");
Set credentials. Use this once, it applies to all further operations:
CURL.setCredentials('username', 'password')
Download:
await CURL.download("ftp://server.com/file.zip");
Download as:
await CURL.download("ftp://server.com/file.zip", "renamed_file.zip");
Upload:
await CURL.upload("file.zip", "ftp://server.com/path")
You can use any command-line parameter and protocol, supported by the curl binary by using CURL.run()
. If curl's output goes to stdout, the curlData
event with curl's output in e.detail
is triggered.
The following example lists all messages on a POP3-server:
await CURL.run('-k -l -u username:password pop3://mail.server.com');
Keep in mind, that special, shell-relevant characters in passwords need to be escaped:
// This will fail:
await CURL.run('-k -l -u [email protected]:My$Password! pop3://mail.server.com');
// This is the way:
await CURL.run('-k -l -u [email protected]:My\\$Password\\! pop3://mail.server.com');
Read more about the fantastic possibilites of curl here.
Method | Description |
---|---|
addHttpHeader(key, value) | Add a custom HTTP-header to the header-list. Headers are sent with each HTTP-upload or -download. key: HTTP-Header name value: HTTP-Header content |
clearHttpHeader() | Clears the HTTP-header list. |
get(url) | GET-Request. Returns data as string. url: API-endpoint |
post(url, data) | POST-Request. url: API-endpoint data: POSt-data as stringified JSON. |
download(src, dst) | Download a file via HTTP, HTTPS, FTP or FTPS. src: URL dst: File-path (optional) |
upload(src, dst) | Upload a file via HTTP, HTTPS, FTP or FTPS. src: File-path dst: URL |
resetProgress() | Resets the progress counter and emits a curlProgress event with data 0.0 , which in turn clears a connected progressbar. |
run(args) | Run the curl-binary with custom arguments. This method is also called from download() and upload() internally.args: Curl command-line parameters |
setCredentials(usr, pwd) | Set credentials for FTP/FTPS operations. usr: Username pwd: Password |
Event | Description |
---|---|
curlStart | Emitted before the CURL binary is launched. |
curlProgress(e) | Emitted with each download- or upload-progress step. e.detail contains the current progress value as float. |
curlData(e) | Using CURL.run() with custom args, all data is collected from curl's stdout and sent via e.detail for further processing. |
curlStop(e) | Emitted after the CURL binary stopped. e.detail contains the exit code as an integer. Read about CURL exit codes here. |