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 http://qt-project.org/doc/qt-5/qurl.html#ParsingMode-enum
and http://tools.ietf.org/html/rfc3986.
The function is terminated in case of an invalid URL and it
returns -1.
|
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:
The mapping contains a httpStatusCode (e.g.200, 202, 204).
The Status-Code element is a 3-digit integer result code of the
attempt to understand and satisfy the request.
When 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" (always) ... Contains a mapping with key
(header name) and value (header) pairs. It can also be
empty.
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" (always) ... 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" (always) ... 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"
See https://tools.ietf.org/html/rfc2616#section-6.1.1
-
"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:
[mapping 1 items]
"sslErrors" : mapping 4 items
"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 tex
|
options |
You can use the following keys for the mapping variable
"options":
-
"target" (string) ... 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.
-
"headers" (mapping) ... Additional header that is
transferred to the server:
key=HeaderName, value=HeaderValue. e.g.
makeMapping("User-Agent", "my special user
agent");
If you specify a header which already exists, the
existing header is overwritten.
-
"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 chapter netGet.
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 alogorithm
information
"key" (string) - private key in PEM encoded form.
"alogorithm"(string) - The used alorithm, 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 after which the
call will return with an error code of -2 (timeout
expired). The operation in progress will be aborted.
-
clearAccessCache...Flushes the internal cache of
authentication data and network connections. Note
that 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.
|