%HTTP_SERVER_CREATE

Create an HTTP or HTTPS server class object

WSupported on Windows
USupported on Unix
VSupported on OpenVMS

 

 
status = %HTTP_SERVER_CREATE(instance_id, port, error, [protocols], [ciphers], [cert_file], 
&        [CA_file][, IP_flag])

Return value

status

Returns 0 if successful or an error number if unsuccessful.

Arguments

instance_id

Returned with the static memory handle of this instance of a Synergy HTTP or HTTPS server, which will be used as the instance_id by all other %HTTP_SERVER_XXX calls. (D_HANDLE)

port

The number of the port on which the server will listen. (n)

error

Returned with an error message if status is nonzero. Otherwise, it is blank. (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 server 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 server 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)

IP_flag

(optional) Indicates which Internet Protocol versions are allowed. (n)

0 = Only IPv4 is allowed. (default)

nonzero = IPv4 or IPv6 is allowed.

Discussion

%HTTP_SERVER_CREATE creates a socket to listen for requests on the specified port. To create an HTTPS server that only accepts HTTPS connections, pass the cert_file argument. If cert_file is not specified, %HTTP_SERVER_CREATE creates an HTTP server.

The instance_id is a returned memory handle that is used by the other %HTTP_SERVER_xxx calls. You must call %HTTP_SERVER_CREATE before calling any of the other server methods. Use %HTTP_SERVER_DELETE to free the memory allocated by this call.

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

Client authentication will occur when a request is received by %HTTP_SERVER_RECEIVE.

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.

Examples

UsePort = 80
rtnvlu = %http_server_create(httpsvr, UsePort, errorMsg)
do
  begin
    rtnvlu = %http_server_receive(httpsvr, URI, method, timeout, 
  &          req_handle, req_length, errorMsg, headerArray, logfile)
    .
    .
    .
    rtnvlu = %http_server_send(httpsvr, status, reason, resp_handle
  &          resp_length, errorMsg, headerArray, logfile)
    .
    .
    .
  end
until(ExitCondition)
rtnvlu = %http_server_delete(httpsvr)
    .
    .
    .

Also see the URL_Encoding example available from Synergy CodeExchange in the Synergex Resource Center.