netGet()
The function netGet allows to download data.
Synopsis
int netGet( string url, mapping|string|blob &result [, mapping options]);
Parameter
Parameter | Meaning |
---|---|
url |
The URL (http, https, ftp and file - file only applies to local files). Since the URL has to correspond to specific syntax rules, the QT implementation of the URL parser tries to correct errors in the syntax. See the section "QUrl::TolerantMode" in the description Qt - QURL Parsing Mode and Uniform Resource Identifier (URI)- Generic Syntax. The function is terminated in case of an invalid URL and it returns -1. |
result | see Mapping "result" |
options | see Mapping "options" |
Return value
The function returns 0 if it was successfully executed and in case of errors -1.
Description
The function netGet allows to download data. The result" variable contains the data received from the server. If you pass a string or a blob variable to the "result" parameter, the variable only contains "Content" data but not a "Header" transmission. If a mapping variable is passed to the result parameter, keys are set. The keys are described in the table above.
Mapping "result"
The result variable contains the data that was received from the server by default. The data is saved by default directly in memory of the "result" variable. The parameter can be a mapping, a string or a blob. Thus, 3 parameter types can be used. If you pass a string or a blob variable, the variable only contains the "content" data but no "header" transmission.
Mapping:
If you pass a mapping in the result variable, the following keys are optionally set. The Keys with the text (always) are always set. See https://tools.ietf.org/html/rfc2616#section-6.1.1.
- headers
-
Contains a mapping with key (header name) and value (header) pairs. It can also be empty. The entry is always available.
Example:
"Last-Modified" : "Mon, 09 Sep 2013 09:08:45 GMT" "Date" : "Wed, 16 Jul 2014 07:37:13 GMT" "Content-Length" : "1127" "Content-Type" : "image/png"
- content
-
Contains the received data. The data type is string by default. You can specify the data type by using the variable options. If you specified a target file by using the "options" variable, the content here is always empty. See keyword "target" under options further below.
- url
-
The URL that was used for the last query. It can differ from the original URL if a redirection answer is received from the server in the HTTP protocol (see Redirection Handling under options mapping in the next row of this table).
- httpStatusCode / httpStatusText
-
In an http/https communication the httpStatusCode and httpStatusText contain the last HTTP status code (int) and the respective "Reson Phrase" (string), e.g.
"httpStatusCode" : 200 "httpStatusText" : "OK"
- target
-
If you specify a target file by using the options variable, the "target" key word here contains the absolute file path. For options mapping see the next row of this table.
- errorString
-
The errorString contains a "readable" descriptive text if an error occurs in the communication. The parameters "error" and "errorString" are always set together. In this case, the function always returns -1.
- error
-
In case of errors, the function returns a string key word from the following list:
- - "RedirectionLoop" ... Too many redirects encountered (see Redirection Handling)
- - All values from the enum are described on the following home page. The prefix string is not used, e.g. "ConnectionRefusedError" https://doc.qt.io/qt-5/qnetworkreply.html#NetworkError-enum
- sslErrors
-
If an SSL error occurs when establishing the communication, the list of SSL errors are passed in a mapping. The key in the mapping is a string key word from the following list. The value for the key is a descriptive text of the error. If the SSL errors are not ignored (see "ignoreSslErrors" under "options" mapping in the next row of this table), the function returns -1 and is terminated. Furthermore, the "result" variable does not contain any further keys.
Possible SSL key words:
- "UnableToGetIssuerCertificate"
- "UnableToDecryptCertificateSignature"
- "UnableToDecodeIssuerPublicKey"
- "CertificateSignatureFailed"
- "CertificateNotYetValid"
- "CertificateExpired"
- "InvalidNotBeforeField"
- "InvalidNotAfterField"
- "SelfSignedCertificate"
- "SelfSignedCertificateInChain"
- "UnableToGetLocalIssuerCertificate"
- "UnableToVerifyFirstCertificate"
- "CertificateRevoked"
- "InvalidCaCertificate"
- "PathLengthExceeded"
- "InvalidPurpose"
- "CertificateUntrusted"
- "CertificateRejected"
- "SubjectIssuerMismatch"
- "AuthorityIssuerSerialNumberMismatch"
- "NoPeerCertificate"
- "HostNameMismatch"
- "NoSslSupport"
- "CertificateBlacklisted"
- "UnspecifiedError"
The "result" mapping looks as follows:
"sslErrors" :
- "CertificateUntrusted" : "The root CA certificate is not trusted for this purpose"
- "UnableToVerifyFirstCertificate" : "No certificates could be verified"
- "UnableToGetLocalIssuerCertificate" : "The issuer certificate of a locally looked up certificate could not be found"
- "HostNameMismatch" : "The host name did not match any of the valid hosts for this certificate"
- sslErrors2
-
Further information on the SSL errors such as certificate information.
Possible key words:
- "errorString": Readable Errorstring "The certificate is self-signed, and untrusted"
- "certificate": contains details about the certificate (if the error contains a certificate. Otherwise this "certificate" key does not exist).
- "digest": Unique identifier for each certifcate e.g. "52bfdc363d0832f1a38cfcb612779bf69e4c8d8d"
- "text": certificate text
Mapping "options"
You can use the following keys for the variable "options":
- target
-
An absolute path to a directory or to a file the content of the response is saved in.
If you specify a directory path, the file name from the URL is added to the directory path to create a final file name.
This file name is also saved in the "result" variable under key word "target". The file must be opened for reading or the function returns -1 and is terminated.
A file is created if it does not exist. The following calls create a file in /tmp/console.png:
netGet("http://localhost/pictures/console.png", m, makeMapping("target","/tmp/console.png")); netGet("http://localhost/pictures/console.png", m, makeMapping("target", "/tmp"));
- headers
-
Additional header that is transferred to the server during the communication. key=HeaderName, value=HeaderValue, e.g.
makeMapping("User-Agent", "my special user agent");
Anmerkung: If you specify a header which already exists, the existing header is overwritten. - content
-
Specifies the data type of the content saved in the "result" variable. Permitted data types are string and blob, e.g.
options["content"] = ""; // string options["content"] = (blob)""; // blob
- ignoreSslErrors
-
If you pass a value unequal to dyn_string or an empty dyn_string, all SSL errors are ignored.
All occurred SSL errors are, however, returned and you can find them in the result["sslErrors"] mapping.
If you specify a dyn_string, you specify which SSL errors may be ignored. If there are other SSL errors, the function returns -1 and is terminated.
For possible SSL error key words, see "sslErrors" in the row above under variable "result", e.g.
options["ignoreSslErrors"] = ""; //All SSL errors are ignored options["ignoreSslErrors"] = makeDynString("CertificateUntrusted");//Ignore CertificateUntrusted errors
- followRedirection
-
If you specify false for the bool parameter, the automatic "Redirection Handling" is deactivated. In the Redirection Handling, the HTTP protocol allows the server to send a "redirection" answer. Thereby, a client knows that the required resource is reachable under another URL. The function netGet follows these instructions by default. In order to avoid a redirection loop (e.g. A -> A oder A -> B -> C -> A, etc.), the number of answers is limited. If this number is exceeded, the function returns -1 ("RedirectionLoop" error) and is terminated. You can activate or deactivate the redirection handling by using the "followRedirection" key for the options mapping, e.g.:
options["followRedirection"] = false; // automatic redirection deactivated options["followRedirection"] = true; // automatic redirection activated (default)
- sslConfig
-
The sslConfig is a mapping that contains the certificate information required for secure comminication and contains following keys:
- "localCertificate" (string) - PEM encoded certificate
- "privateKey" (mapping) - key and algorithm information
- "key" (string) - private key in PEM encoded form.
- "algorithm"(string) - The used algorithm, possible values: "RSA", "DSA", "EC" (Elliptic Curve)
Example
A PEM encoded certificate file can be loaded from the local disk like this:
fileToString(getPath(CONFIG_REL_PATH, "certificate.pem"), cert);
and then the returned string can be passed as value for the key "localCertificate".
- timeout
-
Defines a timeout in seconds after which the call will return with an error code of -2 (timeout expired). The operation in progress will be aborted. timeout is of data type "time". If you specify an "int", it is converted into seconds.
- clearAccessCache
-
Flushes the internal cache of authentication data and network connections.
Anmerkung: This key must only be specified for the options mapping. You do not need to specify a value for it. - clearConnectionCache
-
Flushes the internal cache of network connections. In contrast to clearAccessCache the authentication data is preserved. Note that this key must only be specified for the options mapping. You do not need to specify a value for it.
Download Data
main()
{
/* Downloads data. The parameter "res" is a string and only contains the content data nut not header.
Replace the address by your address in the code below */
string res;
netGet("ftp://<user>:<password>@<host>:<port>/file path", res);
}
Replace address
main()
{
/*Replace the address by your address in the code below */
mapping m;
DebugN(netGet("ftp://<user>:<password>@<host>:<port>/file path", m));
DebugN(m);
}
Certificates
main()
{
mapping m;
string cert;
fileToString(getPath(CONFIG_REL_PATH, "certificate.pem"), cert);
string privkey;
fileToString(getPath(CONFIG_REL_PATH, "privkey.pem"), privkey);
int ret = netGet("https://localhost:8079/netGetExample", m,
makeMapping("sslConfig",
makeMapping("localCertificate", cert,
"privateKey", makeMapping("key", privkey, "algorithm", "RSA"))));
DebugN(ret, m);
}
Assignment
HTTP functions
Availability
UI, CTRL