%HTTP_SERVER_CREATE

Create an HTTP or HTTPS server class object

WTSupported in traditional Synergy 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): (n)

SSLVER_ALL = All protocols are available.

SSLVER_TLS1_2 = TLS version 1.2 (default)

SSLVER_SSL2 = SSL version 2 (deprecated)

SSLVER_SSL3 = SSL version 3 (deprecated)

SSLVER_TLS1 = TLS version 1.0 (deprecated)

SSLVER_TLS1_1 = TLS version 1.1 (deprecated)

Important

We recommend using TLS 1.2 for secure sites. If a protocol version lower than SSLVER_TLS1_1 is specified, an "Invalid SSL protocol specified" error will occur.  

ciphers

(optional) A cipher list that specifies the encryption methods in effect. (a)

cert_file

(optional) The name of the server certificate file. (a)

CA_file

(optional) The name of a file containing certificate authorities that the server trusts. (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.

If ciphers is not specified, the ciphers designated by the cipher list format value DEFAULT are in effect. See Ciphers for more detailed information and a list of supported ciphers.

If specified, cert_file must be the name of an existing file in PEM or DER format. 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 specified, CA_file must be the name of an existing file in PEM or DER format, and client authentication will occur when a request is received by %HTTP_SERVER_RECEIVE.

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 following examples available from CodeExchange in the Resource Center on the Synergex website: HTTPexample.zip and url_encode.zip.