HTTP support (OMHTTP)

The OMHTTP library provides portable access to Hypertext Transmission Protocol (HTTP) communications. This library uses two data structures specific to it: the HttpRequest shelf and the HttpResponse shelf. These shelves are standard stream shelves, with a number of predefined keyed items. As with any other stream shelf, you are free to access and modify the contents. Both shelves are subject to all usual shelf and stream operations, and you may test or modify them at will. However, you should observe and maintain the data format of both shelves, or the HTTP functions may behave in an unexpected fashion. To ensure data integrity, access the items on these shelves only through their respective functions.

The HttpRequest shelf is used to create an HTTP-formatted request message, which can then be sent to an HTTP server. Most simple requests can be created using HttpRequestSetFromUrl, which will create sufficient items in the HttpRequest shelf to cover most circumstances. This shelf contains the following keyed items:

  • last-error—a string describing any errors encountered during the last function call. If no errors were detected, it is a zero-length string.
  • host—the IP address of the host. This value must be a valid IP address.
  • port—the HTTP server port number. This must be a string representation of a valid port number. The default value is 80.
  • proxy-host—the IP address of the proxy host. This value must be a valid IP address.
  • proxy-port—the HTTP proxy server port number. This must be a string representation of a valid port number. The default value is 80.
  • method—the HTTP request method. The default value is GET.
  • path—the path and file name of the resource on the HTTP server to access. The path must begin with the / character, which is the default value.
  • http-version—the version of HTTP used to format the message. The default value is HTTP/1.0.
  • cookie-version—the version of cookie support. The default value is 1.
  • entity-body—additional information to send to the server. The default value is a zero-length string.

The HttpResponse shelf contains the information needed to construct an HTTP-formatted response message that an HTTP server will return to a client after receiving a request. It contains the following keyed items:

  • last-error—a string describing any errors that occurred during the last function call. If no errors were detected, it is a zero-length string.
  • http-version—the version of HTTP used to format the message. The default value is HTTP/1.0.
  • status-code—the numeric status code indicating the success of the request. The default value is 200, indicating success.
  • reason-phrase—a textual explanation of the status code. The default value is OK.
  • entity-body—the body of information to return to the client. The default is a zero-length string.

Categories of OMHTTP functions

The functions in the HTTP library generally fall into one of three broad categories, depending on what sort of program they are commonly called in. Though there is no technical reason they cannot be called elsewhere, the functions are used most often in the following types of programs:

These functions are found most often in client programs:

The following functions are found most often in server programs:

A small number of functions appear in either a client or a server program:

The following task topics show you how to use the HTTP library:

The functions in this library use the following data structures:

  • HttpRequest—to create an HTTP-formatted request message, which can then be sent to an HTTP server.
  • HttpResponse—contains the information needed to construct an HTTP-formatted response message that an HTTP server will return to a client after receiving a request.

Usage Note

To use OMHTTP, you must include the following code near the top of your program: 

  include "omhttp.xin"

Functions