HTTPPost

Syntax

HTTPPost (host,uri[,cgilist,hdrlist,service|port,secure {Default kFalse},verify {Default kTrue},map+ {Default kFalse}]) Returns socket

Description

Note: The flag is set according to whether Omnis was able to make a call to this external command.

This Web command is multi-threaded, allowing another thread to execute in the multi-threaded server while it runs. Note that the same socket cannot safely be used concurrently by more than one thread.

HTTPPost is a client command that submits a POST HTTP request to a Web server.

Host is a Character field containing the hostname or IP address of the Web server.

URI is a Character field containing the URI to GET from the Web Server. For example, "/default.html", or "/cgi-bin/mycgiscript"

CGIList is an optional parameter. It is an Omnis list with two character columns. The list contains the CGI arguments to be posted to the URI. These will be sent as content of type "application/x-www-form-urlencoded". There is one row for each CGI argument. For example

Note: Before the values are sent to the Web server, HTTPPost automatically performs any CGI encoding required to pass special characters in the arguments. There is no need to call the CGIEncode command.

HdrList is an optional parameter. It is an Omnis list with two character columns.. The list contains additional headers to add to the headers of the HTTP POST request. Note that the header name excludes the ‘:’, which HTTPPost inserts automatically when it formats the header.

For example

Note that because CGI arguments are sent as content, you can only supply your own Content-type and Content-length headers if you do not supply CGI arguments.

Service|Port is an optional parameter that specifies the service name or port number of the server. If you specify a service name, the lookup for the port number occurs locally. If you omit this argument, it defaults to the port number specified in the host, or if none is present, it defaults to 80 or 443, the default port for HTTP or HTTPS respectively (depending on the value of Secure).

Secure is an optional Boolean parameter which indicates if a secure connection is required to the server. Pass kTrue for a secure connection, in which case the built-in security technology will be used, so on Windows ‘Secure Channel’ (Schannel) is used, on macOS ‘Secure Transport’ is used, and on Linux OpenSSL is used.

Verify is an optional Boolean parameter which is only significant when Secure is not kFalse. When Verify is kTrue, the command instructs the installed SSL library to verify the server's identity using its certificate; if the verification fails, then the connection will not be established. You can pass Verify as kFalse, to turn off this verification; in this case, the connection will still be encrypted, but there is a chance the server is an impostor. In order to perform the verification, the installed SSL library uses the Certificate Authority Certificates in the cacerts sub-folder of the secure folder in the Omnis folder. If you use your own Certificate Authority to self-sign certificates, you can place its certificate in the cacerts folder, and the installed SSL library will use it after you restart Omnis.

Map+ is an optional Boolean parameter which when true indicates that plus characters in CGI parameter names and values in the CGIList are to be URL encoded as hex.

Socket receives the result of the request. HTTPPost opens a connection to the Web server, and formats and sends an HTTP POST request to the server. If the command succeeds, it returns the socket number for the connection to the WEB server; otherwise, it returns an error number which is less than zero. After successfully issuing HTTPPost, you should call HTTPRead to read the response from the server; ALWAYS call HTTPClose to close the connection and free the socket. Possible error codes are listed in the Web Command Error Codes Appendix.

HTTPPost adds the following header fields by default:

Note: After calling HTTPPost, you can call HTTPSend to send your own content, before you read the response, provided that you include Content-type and Content-length headers in the HdrList.

Example

# Post a HTTP request to the server lServer listening on port 6001
Do  lCGIList.$define(lAttribute,lValue)
Do  lCGIList.$add('Name','John Smith')
Do  lCGIList.$add('Email','john.smith@smiths.com')
Calculate lServer as  '0.0.0.0.0.0'
HTTPPost (lServer,'\default',lCGIList,lHeaderList,6001) Returns iSocket