HTTPER documentation

What is it good for

HTTPER is command-line driven utility for communication using Hypertext Transfer Protocol on TCP/IP networks. HTTPER can be used in scripts for unattended web check, for scheduled HTTP download/upload, or for investigation of HTTP headers.

Installation

HTTPER is Win32 console application. It requires MS Windows and TCP/IP protocol installed. Copy HTTPER.EXE to any directory in PATH. No other installation is necessary.

HyperText Transfer Protocol

HTTP is specified in RFC2616. The Client who wants to get a piece of information from the Server has to know its IP address and full name of desired object on the web server. Then the Client establishes TCP connection with the Server and sends so called Request. Server replies with a Response which may contain requested data - e.g. HTML file, text, picture.
In ordinary web browsing this all is hidden when a user clicks on a favourite link in his/her Internet Explorer. Using HTTPER utility is different: the request must be prepared in advance as a text file and the received response is stored on disk rather than displayed with all bells and whistles.
HTTPER can also act as a special HTTP server. Unlike real servers (Apache, IIS etc.) it does not parse the request. HTTPER server only sends the off-shelf response and quits.

Request format

HTTP Request contains a Request Header optionally followed by more data - Post File. Request Header consists of one or more lines of text. The first line contains three space-separated words:

Method Request-URI HTTP-Version

Method: Most usefull methods are GET and POST.
Request-URI: specifies path and name of requested object on the server. The path uses Unix convention - directories are separated with a solidus "/". Most servers response with default HTML file whose name is default.html or INDEX.HTM when the sole solidus is used in HTTP request.
HTTP-Version: Current frequently used versions are specified as HTTP/1.0 or HTTP/1.1.

More lines of text may follow in the Request Header looking like ParameterName: Value pairs, for instance

GET /pictures/blondie.jpg HTTP/1.0
If-Unmodified-Since: Sat, 22 Oct 2001 19:43:31 GMT

Request Header is terminated with an empty line (CR+LF).

Response Format

HTTP Response also has a text header followed with requested data. The first line of header - Status tells the client how the request will be answered:

HTTP-Version Status-Code Reason-Phrase

HTTP-Version: Negotiated version used by the Server.
Status-Code: Numeric status.
Reason-Phrase: Human-readable form of request status.

Next header lines often specify the requested object properties, its size, age, MIME-type.

HTTP/1.0 200 OK
Content-Length: 23456
Content-Type: image/gif

The last empty line terminates the response header.

HTTPER command line syntax

HTTPER /role /Timeout=x IP_addr:port Request Response

/role: This option commands HTTPER to act as a /Client or /Server and can be abbreviated as /C and /S. Default is /Client.
/Timeout=: Time in seconds when the communication will be aborted if it doesn't terminate itself. Following examples set the timeout to 5 minutes:
/Timeout=300s, /T:300, -t300. Value of 0 will switch the timeout off. If the parameter is omitted, default timeout is 2 minutes for Client and 10 minutes for Server. You can always abort HTTPER manually with Ctrl-Break.
IP_addr: IP address is mandatory. It must be given in numeric form as four numbers 0-255 separated with fullstop ".". The TCP port may follow IP address and is separated with colon ":". Default is HTTP port :80.
In client role this parameter specifies remote server which you want to communicate with. In the case of HTTPER server the IP address represents interface which the server should bind to. In most cases the special local address 0.0.0.0 will do the job.
Request: When HTTPER is used as a client, Request specifies existing file with prepared request.
In server role, the Request sets the name of file where the client's request will be stored. Any existing file with this name will be overwritten.
Response: HTTPER client writes received Response to this file.
In server role this parameter specifies an existing file which will be returned to client.

As already mentioned, both Request and Response contain a header and optional message body. HTTPER is able to detach these two components into two separate files and, vice versa, to join separate header and body files before sending them away. All you have to do is write two file names separated with plus sign "+" instead of single file. Always put at least one space on both sides of "+", e.g.
HTTPER /C 200.100.50.25 Request.TXT ResponseHeader.TXT + Content.html
Server's response will disjoin, the header goes to ResponseHeader.TXT and data to Content.html.

File names may contain the full path, for instance "D:\PATH\FILE.TXT", or may be in UNC form, e.g. \\SERVER\SHARE\PATH\FILE.HTM, or device name such as NULL, CON, LPT1. File name must be enclosed in quotes if it contains white spaces.

If the Response parameter is omitted, response goes to standard system output and will be presented on display. In server role the omitted response is expected on standard input and should be answered from keyboard.

If both Request and Response are omitted, all files are redirected to system console. Client writes the request on keyboard and the received response will be displayed on monitor. HTTPER server first displays the received request and then prompts the user to response live from keyboard.

HTTPER utility reports the communication status on screen. These prompts start with # sign. They don't mix up with normal HTTPER output because they are directed to standard error output.

HTTPER will set this ERRORLEVEL on exit:

0: Normal exit, data transferred OK.
4: Remote refused communication. It may not listen on a given TCP port.
8: Remote not found. Network may be down or IP address does not exist.
12: HTTPER timed out.
16: File read or write error, e.g. full disk.
20: Some of the files given on command line was not found.
24: Wrong IP:port address format.
28: Invalid syntax, Help was displayed.

Experimentation with HTTP

Try yourself following exercises if you want to get acquainted with HTTProtocol and HTTPER utility.

Getting a web page

Let's download a home page from an existing WWW server on intranet or Internet. Its numeric IP address can be derived from domain addres using

PING domain_address

If some of professional web server such as Apache, Personal Web Server, MS IIS is running on your computer, you can try the universal IP address for this computer 127.0.0.1 (localhost). HTTPER.EXE will be used as a client. When prompted # Enter Request enter the GET request:

HTTPER /Client 127.0.0.1
# Enter Request  (terminate with Ctrl-Z)
GET / HTTP/1.0

^Z
# Connecting to server... (abort with Ctrl-Break)

Dont forget the empty line which signalises the end of HTTP header. Terminate keyboard input with Ctrl-Z followed by Enter. HTTPER replies with informative message # Connecting to server... (abort with Ctrl-Break) and if the connection succeeds the home page should flood on your display. You may want to repeat the download and redirect the output do a disk file or pause the display with MORE:
HTTPER /C 127.0.0.1 | MORE
If the full address of desired object at server is known, it can be specified in the header's first line. The following example will download a picture and store it to disk.

ECHO GET /pictures/blondie.jpg HTTP/1.0>"REQUEST.TXT"
ECHO:>>"REQUEST.TXT"
HTTPER /C 200.100.50.25 "REQUEST.TXT"  NULL + "BLONDIE.JPG"

# Connecting to server...  (abort with Ctrl-Break)

# Content received OK.

REQUEST.TXT was created on the fly with two ECHO statements. Server's response was split: response header was thrown away using NULL device and the pure data content was stored as BLONDIE.JPG. You could view the response header if you specify CON instead of NULL.

Posting a form

Web form filled by client can be sent to server using GET or POST method. Input fields are sent as

Name=Value

Characters non acceptable in URI-address must be encoded. Acceptable characters are "A..Z", "a..z", "0..9", "$", -", "_", ".". Other characters should be encoded using their ASCII value prefixed with percent sign "%", e.g. %3B instead of semicolon, %25 instead of percent etc. The space can be encoded as %20 or as plus sign "+". Name=Value pairs are separated with "&".
The GET method appends the encoded pairs with a question mark "?" to the Request-URI in first header line. URI specifies some script on server which will handle provided parameters. Name of the script can be discovered from ACTION= parameter in source HTML file. Using HTTPER client, the request may look like this:

GET /cgi-bin/script.cgi?Name=Joe+Smith&Email=smith@hotmail.com HTTP/1.0

Alternative method is POST. Request-URI specifies only the script address and parameters are sent in the request body:
POST /cgi-bin/script.cgi HTTP/1.0 Content-Type: application/x-www-form-urlencoded Content-Length: 38 Name=Joe+Smith&Email=smith@hotmail.com
POST method requires content type and size be specified in request header which makes it difficult to enter request live from keyboard. It's better to create the header in text editor as a file named "REQUEST.TXT" and set the file as HTTPER parameter:
HTTPER /C 200.100.50.25 "REQUEST.TXT" # Connecting to server... (abort with Ctrl-Break)

Simulating a web server

In the next experiment we will need a real internet explorer such as MSIE or Netscape Navigator. Open a console window and launch HTTPER.EXE in server role interactively: HTTPER /S 0.0.0.0 In case some other WWW server is running on your PC, such as MS Personal Web Server, you'll get a message # Error binding socket. Choose other TCP port, e.g.
HTTPER /S 0.0.0.0:12345. Then put something like http://127.0.0.1:12345/anything/you/like in the Address dialog window of your explorer.
HTTPER server welcomes its first client and displays the received Request header. Have a look what information is your internet explorer giving away to the world. When prompted # Enter Response (terminate with Ctrl-Z) write something wise, for instance Hello World!. When you press Ctrl-Z and Enter you should see the same text in the explorer window.

Real web servers must answer many requests at the same time. HTTPER.EXE is a bit stupid - it ignores the content of received request and always responses with the file specified on command line. HTTPER terminates itself immediatly once it has answered the first request. In automatic communication system this can be bypassed with cyclic calling HTTPER /Server in a batch.

Passing a file to Client

In server role we try to sent a picture "BLONDIE.JPG", 23456 bytes long, to an internet explorer. The response header must be prepared first. The header should tell the client that everything is OK to make our Explorer happy. Corresponding status code is 200. Furthermore, the header should specify content size and type, otherwise Explorer would display the content as an ugly byte code instead of nice girl. So let's go ahead with header RESPONSE.TXT:

ECHO HTTP/1.0 200 OK>RESPONSE.TXT
ECHO Content-Type: image/jpeg>>RESPONSE.TXT
ECHO Content-Length: 23456>>RESPONSE.TXT
ECHO:>>RESPONSE.TXT
HTTPER /S 0.0.0.0:12345 CON  "RESPONSE.TXT" + "BLONDIE.JPG"
# Listening to client...  (abort with Ctrl-Break)

Now direct your Internet Explorer to the address http://127.0.0.1:12345 and watch the result. Of course, if you are experimenting with two separate computers, the real remote IP address must be given instead of localhost 127.0.0.1.

HTTP upload

Open two console windows and set each one to different current directory. Now we try to copy a file BLONDIE.JPG from one window (client) to another (server) using HTTProtocol. HTTPER /Server will receive the posted file:

ECHO HTTP/1.0 200 OK>RESPONSE.TXT
ECHO:>>RESPONSE.TXT
HTTPER /S 0.0.0.0:12345 CON + RECEIVED.JPG RESPONSE.TXT
# Listening to client...  (abort with Ctrl-Break)

Received request will be disjoined, the header goes to console and the posted file will be stored as RECEIVED.JPG. Server's response will be sent from RESPONSE.TXT which was made on the fly.
In client window we will ask HTTPER to post a file:

ECHO POST / HTTP/1.0>REQUEST.TXT
ECHO Content-Type: image/jpeg>>REQUEST.TXT
ECHO Content-Length: 23456>>REQUEST.TXT
ECHO:>>REQUEST.TXT
HTTPER /C 127.0.0.1:12345  REQUEST.TXT + BLONDIE.JPG

# Connecting to server...  (abort with Ctrl-Break)
HTTP/1.0 200 OK


# Content received OK.

Now make DIR in server window and the RECEIVED.JPG should be there.