Xbasic

HTTP_POST Function

Syntax

Result as P = http_post(url as C [,body as B [,cookie as C [,port as N [,timeout as N [,show_before_send as L [,validate_ssl_cert as L [,SSLCipherList as C]]]]]]])

Arguments

urlCharacter

The address of the server that will receive your data. Character

bodyBinary

The parameters you wish to send. The size of this field is unlimited.

cookieCharacter

Default = "". Cookie data.

portNumeric

Default = 80. The port to use.

timeoutNumeric

Default = 8000 milliseconds. The number of milliseconds to wait before timing out.

show_before_sendLogical

Default = .F.. When .T., displays the request before being sent. Useful for debugging.

validate_ssl_certLogical

Default = .T.. If the specified URL starts with "https://", this flag controls whether or not the certificate offered by the server will be validated. If set to .T., the request will always fail. If set to .F., the request may succeed, but the server's identity is not guaranteed.

SSLCipherListCharacter

SSL Cipher List

Returns

ResultPointer

A dot variable containing the server's response.

error_textCharacter

The error message, if any. If no error occurs, error_text will be empty.

error_codeNumeric

The error number, if any. If no error occurs, error_code will be 0.

headersCharacter

Response headers. If error_code is 0, the result will contain a dot variable, parsed_headers, with a property representing each response header.

bodyCharacter

Response body.

parsed_headersPointer

Contains all the headers in the response split out into individual properties. If an error occurred when trying to communicate with the server, parsed_headers will be empty. parsed_headers will always contain the following properties in addition to the headers in the response:

http_versionCharacter

The HTTP version used.

reason_phraseCharacter

A description of the status code.

status_codeNumeric

The response status code. See Status Codes for a list of status codes.

Description

Use the HTTP method POST to retrieve the specified URL

Discussion

The HTTP_POST() function downloads from URL using HTTP/1.1 POST. The function returns a pointer with the parsed response from the server. If error_code is "0", parsed_response will contain the headers in the result:

? amazon_response.parsed_headers
= Connection = "close"
ContentType = "text/html;charset=UTF-8"
Date = "Thu, 22 Dec 2016 22:55:14 GMT"
http_version = "HTTP/1.1"
reason_phrase = "OK"
Server = "Server"
SetCookie = "session-id-time=2113167314l; Domain=.amazon.com; Expires=Wed, 17-Dec-2036 22:55:14 GMT; Path=/"
status_code = 200
StrictTransportSecurity = "max-age=47474747; includeSubDomains; preload"
Vary = "Accept-Encoding,User-Agent"
xamzid1 = "AZ9PQH4SJQ41F075Z3SD"
XFrameOptions = "SAMEORIGIN"
xuacompatible = "IE=edge"
HTTP_POST sends using a content type of "Content-Type: application/x-www-form-urlencoded". To send a request using a different content type, use HTTP_FETCH().

Status code 200 indicates that the page exists. Status code 404 indicates that it does not. Other status codes you may encounter, along with the meanings of each, are documented in Status Codes.

 Handling Redirects

When the server responds with a 30* code, HTTP_POST() does not automatically use the new URL. The developer needs to examine result.parsed_headers.status_code, then if appropriate, try the URL provided in result.parsed_headers.location. Refer to HTTP_GET() for an example.

 HTTP POST vs HTTP GET

HTTP POST is different from HTTP GET in two significant ways. Some devices may restrict the total length of a URL to 128 characters, which may trim the arguments appended by a GET command. There is no such restriction with POST commands. You may save (bookmark) and refresh URLs formatted through HTTP GET. The arguments sent by HTTP POST are not saved in a bookmark.

 Example

Search Amazon.com for a book.

dim bookname as C
bookname = ui_get_text("book name", "What book are you looking for?")

dim req_body as C
req_body = "url=index%3Dstripbooks&field-keywords=" + urlencode(bookname) + "&go.x=1&go.y=1&go=Go"
dim amazon_search as P
amazon_search = http_post("https://www.amazon.com/exec/obidos/search-handle-form/103-9603918-793183", req_body)

if (amazon_search.error_code = 0) then
    if (amazon_search.parsed_headers.status_code = 200) then
        a5_show_html(amazon_search.body)
    else
        ui_msg_box("An error occurred.","An error occurred. Status Code is " + amazon_search.parsed_headers.status_code + ". Reason: " + amazon_search.parsed_headers.reason_phrase)
    end if
else
    ui_msg_box("An error occurred.","Unable to reach server."+crlf()+"Error Code: "+amazon_search.error_code+crlf()+"Error Message: " + amazon_search.error_text)
end if

See Also