HTTP Request Handler

Client-Side Event Handlers

Meaningful URLs and History Management

Introduction

Use the cWebHttpHandler class to implement custom HTTP services. The request handling is done completely in DataFlex code reducing the need for server-side script languages. Examples of HTTP services are REST JSON services or binary file streaming services. Compared to the cWebService class the cWebHttpHandler has a more low-level interface that provides full control over the response being generated.

HTTP

HTTP stands for hypertext transfer protocol and is the standard for transferring data across the web. The protocol describes a format for communication between a client and a server. The protocol is stateless and operations are performed by sending request messages to the server where the server will answer with a response. A request consists a command (verb like GET, POST, ..), URL, headers and optionally a request body. The response consists of a status code (200 successful, 500 error, 401 unauthorized), headers and optionally a response body.

The HTTP headers can be seen as name value pairs and well-known examples are the ‘Content-Type’ and ‘Content-Length’ headers. The request body and response body consist of data, which can be binary or textual data (like images, JSON, XML). Usually the headers provide information about the data.

When using a secure connection HTTP is called HTTPS, on the DataFlex server side nothing changes for HTTPS, this is all handled in the web server (Internet Information Server).

Usage

To create an HTTP handler within your web application you use the “Web HTTP Handler” template found on the “Web Object” tab of the “Create New…” dialog. This adds a file to your project with a single object based on the cWebHttpHandler class. This single object is the entry point of your HTTP handler. You can have multiple HTTP handlers in a single application. The first step is to configure to which path the HTTP handler listens using the psPath property. This property specifies a virtual path to which your HTTP handler will listen. This path is relative to where your application is registered in IIS (usually as a virtual directory). The psVerbs property allows filtering of specific requests types by providing a comma separated list of verbs ("POST,GET,PUT,DELETE,PATCH").

For each request that comes in matching the path and the verbs an event method is called on your object. The OnHttpRequest is sent for each request where OnHttpPost or OnHttpGet are only called for the specific verbs. Implement these events to handle the request. Handling a request typically means reading information from the request (functions like HttpRequestHeader, ServerVariable and RequestDataString), performing an operation and then generating a response. The generation of the response involves setting the response status (SetResponseStatus), adding headers (AddHttpResponseHeader) and writing the response body (OutputString / OutputUChar).

Technique

The HTTP Request Handler is implemented as a native module for the Internet Information Server that reads its configuration from web.config. This web.config file is part of the IIS configuration schema and is located in the AppHtml folder of the workspace. The studio generates the configuration in web.config while compiling the application, based on the cWebHttpHandler objects it finds. Registration of the IIS module is performed by the installer and it is activated for the web application when registering your application using the studio or the web application administrator.

Samples

See the cWebHttpHandler class reference for examples.

See Also