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

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, you must first open with AUX1 mode 13. Upon opening, you then write your post data in the format the server expects. By default, this is MIME type application/x-www-form-urlencoded. Once you are finished writing, you must issue the HTTP POST to send the data to the server. You can then read back the resulting data.

POST Example

10 DIM A$(99)
20 OPEN #1,13,3,"N:HTTPS://postb.in/1605156266970-8865795242600"
30 PRINT #1;"foo1=bar1"
40 PRINT #1;"foo2=bar2"
50 XIO 80,#1,13,3,"N:":REM 80 is 'P' for POST
60 TRAP 100
70 INPUT #1,A$
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

Additional Features

There are other calls which are important for HTTP use:

Retrieving Headers

This is used to specify the headers that you want returned in any HTTP request. When in this mode (with AUX2=1), individual lines written to the network device will specify the desired headers. Each header should be specified on its own line, terminated by an end of line character (EOL). Once done writing headers, you should issue the HTTP Collect Headers command again, with AUX2=0, to finish the process. A HTTP Headers command can be subsequently issued, with reads, to get the desired headers, which will be returned in the exact order specified in the preceding collect headers call.

Retrieving Example

10 DIM A$(128)
20 OPEN #1,4,3,"N:HTTPS://FUJINET-TESTING.IRATA.ONLINE/"
30 XIO 67,#1,4,1,"N:":REM COLLECT HEADERS BEGIN
40 PRINT #1;"Server"
50 PRINT #1;"Date"
60 PRINT #1;"Content-Type"
70 PRINT #1;"Content-Length"
80 PRINT #1;"Last-Modified"
90 PRINT #1;"Connection"
100 PRINT #1;"Vary"
110 PRINT #1;"ETag"
120 PRINT #1;"Accept-Ranges"
130 XIO 67,#1,4,0,"N:":REM COLLECT HEADERS DONE
140 XIO 72,#1,4,1,"N:":REM HEADERS BEGIN
150 INPUT #1,A$:? "Server: ";A$
160 INPUT #1,A$:? "Date: ";A$
170 INPUT #1,A$:? "Content-Type: ";A$
180 INPUT #1,A$:? "Last-Modified: ";A$
190 INPUT #1,A$:? "Connection: ";A$
200 INPUT #1,A$:? "Vary: ";A$
210 INPUT #1,A$:? "Etag: ";A$
220 XIO 72,#1,4,0,"N:":REM HEADERS DONE
230 REM RETURN BODY
240 TRAP 300
250 INPUT #1,A$:? A$:GOTO 250
300 CLOSE #1:END

Setting Headers

Conversely, the HTTP Headers command can also be used to WRITE specific headers to the HTTP server. Any written lines while HTTP Headers is active, with AUX1=1 will be queued to the HTTP server when the HTTP Headers command is finished, request is actually started, such as when the response body is read.

Setting Headers Example

10 DIM A$(99)
20 OPEN #1,4,3,"N:HTTP://ATARI-TESTING.IRATA.ONLINE/"
21 TRAP 80
30 XIO 72,#1,4,1,"N:":REM HEADERS BEGIN
40 PRINT #1;"Crazy Header: Some Value"
50 PRINT #1;"Another Crazy Header: Some other Value"
60 XIO 72,#1,4,0,"N:":REM HEADERS DONE
70 INPUT #1,A$:? A$:GOTO 70
80 CLOSE #1:END