HTTP Protocol

The HTTP protocol allows for network communications over both HTTP and HTTPS.

Devicespec

The HTTP protocol devicespec is:

N:HTTP://HOST:PORT/PATH/?key=val

Open

Opening an HTTP connection is the same as any other protocol, and is defined here: N: SIO Open

AUX1 Values for Open

The aux1 value specifies the HTTP mode to use:

AUX1	Mode
4	GET
6	PROPFIND
8	PUT
12	GET (with headers)
13	POST

These specific aux1 values were chosen because they map to existing Atari conventions. Because of this, you can load and save files to and from HTTP servers transparently. PROPFIND is of course a WEBDAV call allowing for WEBDAV capable servers to return a disk directory. The odd man out, is 13, which is for HTTP POST.

GET has two AUX1 values, because we not only need compatibility to read HTTP documents directly as files on the Atari (with filename resolving), we need to be able to have a mode that can send custom headers (because we need to write those headers to the I/O channel.)

AUX2 values for Open

Currently AUX2 is used to specify the translation mode for CR/LF to EOL. N: AUX2 Values

Relationship to HTTP Set Channel Mode

Sending XIO 77 commands can be used to set the channel mode for an HTTP transaction, so that other forms of data can be communicated, such as getting/setting headers and/or setting POST data.

Note: Because channel modes change the behavior of READ, WRITE, and STATUS on channels opened as read/write, XIO 77 is only meaningful for AUX1 = 12, or 13.

Some examples:

XIO 77,#1,12,0,"N:":REM HTTP BODY, DOES TRANSACTION
XIO 77,#1,12,1,"N:":REM HTTP COLLECT HEADERS
XIO 77,#1,12,2,"N:":REM HTTP GET HEADERS, DOES TRANSACTION
XIO 77,#1,12,3,"N:":REM HTTP SET HEADERS
XIO 77,#1,13,4,"N:":REM HTTP SET POST DATA

GET

When GET is specified, the URL is specified entirely in the devicespec, and subsequent reads will return the HTTP body of the request. Once the body has been returned to the Atari, any subsequent reads will return an error 136 (via the STATUS command).

Using GET to read a file from a web server

Since GET maps directly to CIO AUX1 mode 4, it can be used as a drop-in for reading any file from a web server, e.g.

RUN"N:HTTP://FUJINET-TESTING.IRATA.ONLINE/BLACKJACK.BAS"

GET CIO Example #1 (simple retrieve of file)

Here is an example which retrieves a copy of the GPL 3.0 license from GNU.ORG over HTTPS, and displays it. Closing the result once EOF is reached.

10 DIM A$(128)
11 TRAP 60
20 OPEN #1,4,3,"N:HTTPS://www.gnu.org/licenses/gpl-3.0.txt"
30 INPUT #1,A$
40 ? A$
50 GOTO 40
60 CLOSE #1
70 END

GET CIO Example #2, with custom Headers

This sets a custom header in the query, and collects/gets two headers in the response.

10 DIM A$(128)
20 OPEN #1,12,3,"N:HTTPS://FUJINET-TESTING.IRATA.ONLINE/"
30 XIO 77,#1,12,3,"N:":REM SET HEADERS
40 PRINT #1;"Custom-Header: Foo"
50 XIO 77,#1,12,1,"N:":REM COLLECT HEADERS
60 PRINT #1;"Date":PRINT #1;"ETag"
70 XIO 77,#1,12,2,"N:":REM GET HEADERS
80 INPUT #1,A$:? "Date: ";A$
90 INPUT #1,A$:? "ETag: ";A$
100 XIO 77,#1,12,0,"N:":REM GET BODY
101 TRAP 120
110 INPUT #1,A$:PRINT A$:GOTO 110
120 CLOSE #1:END

PROPFIND

If AUX1=6, then a HTTP PROPFIND request is issued to the target web server. For WebDAV enabled web servers, this should return a directory of files at the given path. AUX2 specifies any additional formatting. If AUX2=128, then a long format is returned showing the entire filename, otherwise, the filename is crunched into 8.3 form. If a web server does not have DAV enabled, this command will fail with an error.

POST

To POST to an HTTP server, open the HTTP end point with AUX1=13. This sets up CIO for both read and write. You then need to issue a Mode change command to write the POST data, followed by either another mode change to GET HEADERS, or BODY to retrieve the results.

POST Example

10 DIM A$(99)
20 OPEN #1,13,3,"N:HTTPS://postb.in/1605156266970-8865795242600"
21 XIO 77,#1,13,4,"N:":REM POST DATA
30 PRINT #1;"foo1=bar1&foo2=bar2&foo3=bar3"
50 XIO 77,#1,13,0,"N:":REM GET BODY
60 TRAP 100
70 INPUT #1,A$:REM THIS CAUSES HTTP TRANSACTION
80 ? A$
90 GOTO 70
100 CLOSE #1:END

PUT

If AUX1=8, then an HTTP PUT request is performed. Any writes to the network device are buffered until the device is closed, upon which, the request is performed. Any failure will be returned as an error upon closing, it is recommended that you should immediately check for an error upon closing and not assume success.

PUT Example

10 OPEN #1,8,0,"N:HTTPS://FUJINET-TESTING.IRATA.ONLINE/TEST.DOC"
11 TRAP 60
20 PRINT #1;"THIS WILL BE WRITTEN TO THE WEB SERVER"
30 PRINT #1;"WHEN THE FILE IS CLOSED."
40 CLOSE #1
50 END
60 PRINT "ERROR WHILE WRITING- ";PEEK(195)
70 END