%HTTP_CLIENT_HEAD

Request document headers from a server

WSupported on Windows
USupported on Unix
VSupported on OpenVMS
NSupported in Synergy .NET
 
status = %HTTP_CLIENT_HEAD(uri, [timeout], handle, length, error, [headers], [log_file], 
&        [protocols], [ciphers], [cert_file], [CA_file], [HTTP_RELURI][, version])

Return value

status

Returns 0 if successful or an error number if unsuccessful.

Arguments

uri

The absolute URI (Uniform Resource Indicator) of the document to retrieve. (a)

timeout

(optional) The number of seconds to wait from the time a request is sent (after the connection to the server) until a response is received from the server. The default is 0, which specifies wait forever. (n)

handle

The static memory handle containing the retrieved document. (D_HANDLE)

length

The length of the retrieved document. (n)

error

Returned with an error message if status is nonzero. Otherwise, it is blank. (a)

headers

(optional) An array of one or more HTTP header strings. Each string has the form header_name[:value]. ([*]a)

log_file

(optional) The name and location of a log file to log HTTP packet contents. (a)

protocols

(optional) One or more SSL protocol versions in effect, separated by a plus sign (for example, SSLVER_TLS1_1+SSLVER_TLS1_2+SSLVER_TLS1_3): (n)

SSLVER_ALL = All protocols are available.

SSLVER_TLS1_2 = TLS version 1.2 (default)

SSLVER_TLS1_3 = TLS version 1.3

SSLVER_TLS1_1 = TLS version 1.1 (deprecated)

Important

We recommend using TLS 1.2 and higher for secure sites. Protocol versions lower than TLS 1.1 (including SSLVER_SSL2, SSLVER_SSL3, and SSLVER_TLS1) result in an "Invalid SSL protocol specified" error.  

ciphers

(Unix and OpenVMS only; optional) A cipher list that specifies the encryption methods in effect. On Windows, ciphers is ignored and the system default ciphers are used. (a)

cert_file

(optional) The name of the client certificate file or, on Windows, a certificate in the Windows Certificate Store. For details see The cert_file and CA_file arguments below. (a)

CA_file

(optional) The name of a file containing certificate authorities that the client trusts or, on Windows, the keyword “cert_store,” to reference the certificate authorities contained in the Windows Certificate Store. For details see The cert_file and CA_file arguments below. (a)

HTTP_RELURI

(optional) If passed, the absolute URI is translated and sent as a relative path in the HTTP request. If not passed, the absolute URI is sent with the path exactly as specified. (n)

version

(optional) A string that contains the HTTP version number to be placed in the document header. The default version number is 1.0. (a)

Discussion

%HTTP_CLIENT_HEAD sends a header request to an HTTP or HTTPS server to retrieve the headers for a document. %HTTP_CLIENT_HEAD is similar to %HTTP_CLIENT_GET, except it only returns headers, allowing you to find out what %HTTP_CLIENT_GET would return if you were to call it. Chunked encoding is supported with HTTP version 1.1 and higher.

The value of uri determines what type of connection will be made to the server. If you pass an HTTP URI, the client establishes an HTTP connection. If you pass an HTTPS URI, the client establishes an SSL connection. See Using the HTTP document transport API for details about the uri syntax, including information on the automatic escaping of special characters.

If handle and length have a value of 0, %HTTP_CLIENT_HEAD allocates a memory handle for you. If, instead of 0, you pass a valid memory handle, that handle is used, but %HTTP_CLIENT_HEAD resizes the handle to the size of the retrieved document. In either case, it’s your responsibility to free any memory used by this routine.

For most applications, the standard default HTTP headers will work as provided. However, some HTTP servers require extra header values to process the HTTP message properly. The headers argument therefore enables you to add or modify headers for client requests. If you pass in a header name that was previously set, the last header value passed for that name will be the one sent in the HTTP message. An individual HTTP header can have a maximum of 499 bytes with %HTTP_CLIENT_HEAD. Headers longer than 499 bytes will be truncated. If this limitation is a problem, you can use %HTTP_HEAD, which has a header size limit of 2048, instead. An HTTP header array is limited to a maximum of 100 elements, and each element can have up to 2048 bytes with %HTTP_HEAD.

Passing a log_file causes both the HTTP request packet and the HTTP response packet to be logged to the specified file. This logging feature is available primarily for debugging purposes and should not normally be turned on in a secure production environment. Logs of a request packet include the HTTP method (in this case, HEAD), the URI, the HTTP version, all HTTP headers, and the body of the HTTP packet. Logs of a response packet include the HTTP version, status, reason, all HTTP headers, and the body of the HTTP packet. Log entries are always appended to an existing log file. If the log file does not exist, it is created. A log file can only be created on a local drive; remote drives are not supported.

On Unix and OpenVMS, if ciphers is not specified, the ciphers designated by the cipher list format value DEFAULT are in effect. See Ciphers (Unix and OpenVMS) for more detailed information and a list of supported ciphers.

The cert_file and CA_file arguments

A PEM certificate file may contain both the certificate and private key. If it doesn’t contain the private key, the Synergy HTTP document transport API will load a PEM-based key file whose name is derived by appending “key.pem” to the end of the certificate filename. For example, for a certificate file named test.der or test.pem, the API will load a key file named testkey.pem. If an authentication error occurs, the error is returned and the connection is terminated.

For cert_file, the format for specifying a certificate in the Windows Certificate Store is as follows: 

store_location\store_name\thumbprint

or

store_location\store_name\common_name

where

store_location is one of the following: CurrentUser, LocalMachine, CurrentService, Services, Users, CurrentUserGroupPolicy, LocalMachineGroupPolicy, LocalMachineEnterprise.

store_name is one of the following: My, Root, Trust, CA.

thumbprint is the 40-character certificate thumbprint.

common_name is the certificate’s common name, which you provided when the certificate was purchased or created.

Note

The thumbprint and the common name can be obtained from the Details tab in the Windows Certificate Manager (certlm.msc for local machine certificates or certmgr.msc for user certificates). The thumbprint is unique for the certificate, but will change when it is renewed, which can be as often as every 30 days. Consequently, you may wish to use the common name instead, as long as it is unique. Thumbprint is included in the list of fields on the Details tab; to see the common name, select “Subject” from that list and look for the “CN” value (this will typically be the same as the “Issued To” value in the certificate list).

The specification can include a leading backslash.

For example, 

LocalComputer\My\d7890d96a266ad39d340aa991e17a2875ccf8175

Or 

\LocalComputer\Root\MyCert

More information about the store location and store name is available in System Store Locations in the Microsoft documentation.

Important

If you pass an HTTPS URI but don’t specify CA_file, server verification will be turned off. Because this poses a security risk, we recommend that you not do it unless you only need encryption without verification.

Examples

headerArray[1] = "Content-Type:text/xml"
clear timeout, handle, length, errormsg
URI = "http://www.synergex.com/ie_home.htm"
logfile = "c:\clt.log"
rtn = %http_client_head(uri, timeout, handle, length, errormsg,
  &   headerArray, logfile)