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
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.

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://ATARI-TESTING.IRATA.ONLINE/BLACKJACK.BAS"

GET CIO Example

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

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://ATARI-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:

Collect 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 Collect Headers command again, with AUX2=0, to finish the process. A 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.

Collect Headers Example

10 DIM A$(128)
20 OPEN #1,8,0,""