netHead()

Synopsis

int netHead( string url, mapping &result [, mapping options]);

Parameter

1. Parameter	Description
   url	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 a mapping, which holds the header data by default.
   	"headers" (always)	Contains a mapping with key (header name) and value (header) pairs (key=HeaderName, value=HeaderValue). It can also be empty.
   	Further key/value pairs are possible, but are not very useful for this function. You can find them in the result mapping for netGet().
   options	You can use the following keys for the mapping variable "options":
   	"target" (string)	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. CAUTION: you can use the target key but since only header data is returned, the file is empty.
   	"headers" (mapping)	Additional header that is transferred to the server during the communication. 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 algorithm information "key" (string) - private key in PEM encoded form. "alogorithm"(string) - The used algorithm, possible values: "RSA", "DSA", "EC" (Elliptic Curve) Example A PEM encoded certificate file can be loaded from the local disk as follows: fileToString(getPath(CONFIG_REL_PATH, "certificate.pem"), cert); and then the returned string can be passed as value to 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.
   	"clearConnectionCache"	Flushes the internal cache of network connections. In contrast to clearAccessCache the authentication data is preserved.

Return value

The function returns 0 if it was successfully executed and in case of errors -1.

Description

The function netHead allows you to download data. The function only queries headers and does not receive any content.

Example

The example checks the header:

main()
{
  mapping m;
  netHead("http://www.etm.at", m);
  if ( m["httpStatusCode"] == 200 )
    DebugN("Everything OK");
  else
    DebugN(m["httpStatusText"]);
}

Assignment

HTTP functions

Availability

UI, CTRL