HTTP

Parameters

opcode  (Num)  [in]

1 (XHTTPOP_REQ) = general HTTP request. Opcode must be set to "1" in all cases.

status  (Signed number)  [out]

0 = ok (for simple functions)

>0 = response code returned from HTTP server (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.)

<0 = Operational errors (see ashinc:HTTP.DEF HTTPERR_xxx)

flags  (Num)  [in]

sum of options flags. These flags are listed in ashinc:HTTP.DEF.

Symbol	Value	Description
XHTTPF_SSL	&h00001	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	&h00002	Tells upload routine to use POST format with Content-Type: application/x-www-form-urlencoded
XHTTPF_REQUPLOAD	&h00004	Tells upload routine to use POST format with Content-Type: multipart/form-data. Used for uploading files only, i.e. requires XHTTPF_FILEREQ. See Customizing REQUPLOAD Headers.
XHTTPF_REQHEAD	&h00008	Makes the request a HEAD request
XHTTPF_REQXML	&h00010	Deprecated. Use XHTTPF_REQPOST + XHTTPF_HDRBODY instead; see Customizing POST headers. Old description: Makes the request a POST using text/xml content
XHTTPF_REQGET	&h00020	Simple GET (text of HTML page)
XHTTPF_REQPUT	&h00040	Simple PUT
XHTTPF_DOWNLOAD	&h00080	Download a file
XHTTPF_FILEREQ	&h00100	Request arg is a filespec (or list of) not a buffer
XHTTPF_FILERESP	&h00200	Response arg is a filespec not a buffer
XHTTPF_DEBUG	&h00400	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	&h00800	Parse file into headers (added individually) and body. See Customizing POST headers.
XHTTPF_PARMBODY	&h01000	Like HDRBODY but use AddParam instead of AddHeader
XHTTPF_SETFROMURL	&h02000	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	&h04000	File parms are server-relative; transfer to PC
XHTTPF_REQGETRAW	&h08000	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.DLL 1.4.132)
HTTPF_SSL_TLS1	&h10000	Combine with XHTTPF_SSL to request TLS 1.0 variation
HTTPF_SSL_SSL2	&h20000	Combine with XHTTPF_SSL to request SSL 2.0 variation
HTTPF_SSL_SSL3	&h40000	Combine with XHTTPF_SSL to request SSL 3.0 variation
HTTPF_SSL_PCT1	&h80000	Combine with XHTTPF_SSL to request PCT 1.0 variation
HTTPF_GETSTSTXT	&h100000	Retrieve HTTP status text from last operation (see Comments)
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, but see Comments about 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 Comments). 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.

 

properties  (String)  [in]

An optional list of name=value clauses delimited by semicolons, e.g.: name1=value;name2=value2,value3;...;nameN=valueM. 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.

 

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

 

Note:

• Prior to ashnet.dll 1.4.131, the normal return code for this operation was 0, and errors would return -12. In ashnet.dll 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 SOSLIB function Fn'HttpGet() 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 the EXLIB directory [908,25] for several other examples.