Updated October 2022; see History
HTTP handles various kinds of HTTP requests. See the subtopics listed at the bottom of this page for in-depth comments.
xcall HTTP, opcode, status, flags, url, request, response {,properties, certpw}
Parameters
opcode (Num) [in]
1 (XHTTPOP_REQ) = general HTTP request. Opcode must be set to "1" in all cases.
status (Signed Num) [out]
0 = ok (for simple functions)
>0 = response code returned from HTTP server. It generally means that operation succeeded in communicating with the server. Whether that represents an unqualified success will depend on the application and the body of the response. Note that these HTTP response codes are standardized; detailed descriptions can be found by searching the Internet for "HTTP Response Codes".
<0 = Operational errors; see ashinc:HTTP.DEF
flags (Num) [in]
sum of options flags. These flags are listed in ashinc:HTTP.DEF.
Symbol |
Value |
Description |
|---|---|---|
XHTTPF_SSL |
&h00000001 |
Use a secure protocol (SSL/TLS) per preference of server. See XHTTPF_SSL_xxx below to coerce a particular variation. Note: must be set explicitly (not automatic from "https:" in url.) |
XHTTPF_REQPOST |
&h00000002 |
Send the request as an HTTP POST transaction. Default headers will be automatically generated according to the request document (see request parameter). Add XHTTFP_DEBUG to see the generated headers in debug.req, and see Customizing POST headers for customizing them. |
XHTTPF_REQUPLOAD |
&h00000004 |
Variation of an HTTP POST transaction used exclusively for uploading files containing data (not to be confused with file-based requests). Requires XHTTPF_FILEREQ. See Customizing REQUPLOAD Headers. |
XHTTPF_REQHEAD |
&h00000008 |
Makes the request a HEAD request |
XHTTPF_REQXML |
&h00000010 |
Deprecated. Use XHTTPF_REQPOST + XHTTPF_HDRBODY instead; see Customizing POST headers. Old description: Makes the request a POST using text/xml content |
XHTTPF_REQGET |
&h00000020 |
Simple GET (text of HTML page). Also see XHTTPF_REQGETX below. |
XHTTPF_REQPUT |
&h00000040 |
Simple PUT |
XHTTPF_DOWNLOAD |
&h00000080 |
Download a file |
XHTTPF_FILEREQ |
&h00000100 |
Request arg is a filespec (or list of) not a buffer |
XHTTPF_FILERESP |
&h00000200 |
Response arg is a filespec not a buffer |
XHTTPF_DEBUG |
&h00000400 |
Outputs copy of the generated request to debug.req; transcript of the transmission and internal calls to debug.log; appends connection summary to ashnet.log. |
XHTTPF_HDRBODY |
&h00000800 |
Parse file into headers (added individually) and body. See Customizing POST headers. |
XHTTPF_PARMBODY |
&h00001000 |
Like HDRBODY but use AddParam instead of AddHeader |
XHTTPF_SETFROMURL |
&h00002000 |
Extract path and form info from URL for use in the request header. Typically not used with XHTTPF_REQPOST, since it will strip any ?<suffix> from the resulting POST header. |
XHTTPF_FORCEXFR |
&h00004000 |
File parms are server-relative; transfer to PC |
XHTTPF_REQGETRAW |
&h00008000 |
Like XHTTPF_REQGET (&h0020) but works around a limitation of XHTTPF_REQGET in which certain characters outside the range supported by Latin1/ANSI (e.g. Russian or Chinese) would just be dropped from the response. Can also be used to retrieve binary data containing embedded nulls (such as a file), although you must then use XHTTPF_FILERESP (&h0200) to write the response to a file. Added in ASHNET 1.4.132. |
HTTPF_SSL_TLS1 |
&h00010000 |
XHTTPF_SSL modifier: request TLS 1.0 or higher |
HTTPF_SSL_SSL2 |
&h00020000 |
XHTTPF_SSL modifier: request SSL 2.0 |
HTTPF_SSL_SSL3 |
&h00040000 |
XHTTPF_SSL modifier: request SSL 3.0 |
HTTPF_SSL_PCT1 |
&h00080000 |
XHTTPF_SSL modifier: request PCT 1.0 |
HTTPF_GETSTSTXT |
&h00100000 |
Retrieve HTTP status text from last operation. |
XHTTPF_SSL_TLS11 |
&h01000000 |
XHTTPF_SSL modifier: request TLS 1.1 or higher |
XHTTPF_SSL_TLS12 |
&h02000000 |
XHTTPF_SSL modifier: request TLS 1.2 or higher |
XHTTPF_REQGETX |
&h01000000 |
Implements a more advanced version of the "GET" operation. The main visible difference is that the returned reponse will be more detailed in the case of a successful connection but a failed transaction, due to some kind of logic or validation issue on the server. Also supports Customizing GET Headers. |
Definition file: http.def |
||
url (String) [in]
Fully qualified URL, with optional path and/or {:port}. URL maximum length is 1024. For example:
"http://www.microsabio.net/dist/51dev/temphold/junk.zip"
"https://www.paypal.com"
"http://someserver.com:10080/some/path" (see History notes below)
request (String) [in]
Contains content of the request, for operations that require it, such as uploading files, POST, etc. Depending on XHTTPF_FILEREQ flag, may be a string buffer or a filespec (native or A-Shell, but see subtopic ATE). For the XHTTPF_REQUPLOAD option, can be a list of filespecs with semi-colon delimiters and an optional prefix indicating the content-type of the file and the "name" attribute to associate with it; see Customizing REQUPLOAD Headers. Note that some options only work with file mode, while some may only work with string mode.
response (String) [in/out] (If S,0, must be pre-initialized to desired maximum length)
Returns the body of the response, or in the case of XHTTPF_GETSTSTXT, the HTTP status text from the prior XCALL HTTP operation. If XHTTPF_FILERESP is set, then the passed-in value of response is interpreted as a filespec (native) and the actual response is written to that file. Otherwise the response is returned in the specified parameter. Beginning with A-Shell 6.4.1555, response accepts AMOS-style filespecs; see History note.
properties (String) [in]
An optional list of name=value clauses delimited by semicolons, e.g.: name1=value;name2=value2,value3;...;nameN=valueN. See the following topic HTTP Properties Parameter for a table of properties. Note: to maintain backwards compatibility with old and now deprecated certfile parameter and syntax: if there is no "=" (equals sign) character in the string, it will be intepreted as the old certfile spec.
certpw (String) [in]
Optional password for the PFX file. See History note of 2022 October.
Example
Simple file download: here we download a JPG file from our public server, using XHTTPF_DOWNLOAD.
++include ashinc:http.def
map1 params
map2 flags,b,4
map2 url$,s,100,"http://www.microsabio.net/dist/other/images/EditorShot.jpg"
map2 response$,s,20,"download.jpg"
map2 status,f
flags = XHTTPF_DOWNLOAD or XHTTPF_FILERESP
xcall HTTP, XHTTPOP_REQ, status, flags, url$, "", response$
? "status: ";status;
if status = 0 or status = 200 then
? "ok"
else
? "error - ";response$;" may contain details (as text)"
endif
Comments
| • | Prior to ASHNET 1.4.131, the normal return code for this operation was 0, and errors would return -12. In ASHNET 1.4.131 and later, it returns HTTP status codes (200 for ok, most everything else would be an error.) |
| • | In the case of an error, the response file may contain details (in text) rather than the downloaded file. |
| • | For ATE compatibility, use XCALL ATHTTP instead of XCALL HTTP. ATHTTP also works with local Windows as a pass-through to HTTP. |
| • | The function Fn'HttpGet() in SOSLIB:[907,10] can also download files, although it uses multiple XCALL TCPX operations to do so. The approach shown here is somewhat more efficient when running under Windows, but less efficient under ATE (due to the need to transfer files back and forth between the ATE client and the server). |
| • | If the URL is https: (secure), simply add the XHTTPF_SSL flag. |
See Also
| • | EXLIB:[908,25] for several other examples. |
Subtopics
•ATE
•Customizing REQUPLOAD Headers
