Skip to content

Class: cWebHttpHandler

Properties | Events | Methods | Index of Classes

Handles HTTP requests for REST and other HTTP services.

Hierarchy

Library: Web Application Class Library
Package: cWebHttpHandler.pkg

Description

Use this class to build HTTP services within your web application. For example, REST JSON services, but also binary services like file streaming and file upload handling. The class works at the level of HTTP requests, and you process the request using APIs that read and write string values or binary data as UChar arrays. Compared to cWebService, it has a relatively low-level API.

To use this class, you create an object which you bind to a specific URL using the psPath property. The psPath property determines the place of the handler in the IIS configuration structure and works relative to the website/virtual directory where your application is registered.

The psVerbs property tells the handler which verbs are allowed.

Events are called when a request comes in (OnHttpRequest and more specific ones like OnHttpPost). These events receive details as parameters and can use functions like HttpRequestHeader, RequestDataString, RequestDataUChar, UrlParameter, and ServerVariable to get details from the request.

The cWebHttpMultipartFormDataHandler subclass can be used to handle HTTP requests in the multipart/form-data format. That format is commonly used for file uploads in Web Applications.

When compiling your application in the Studio, the configuration for your HTTP Handler objects is written to the web.config file (inside AppHtml). This is done based on the objects it finds in your application. The web.config is an IIS configuration file that might also contain other settings from other IIS Modules. When installing DataFlex, a module is registered in IIS that accesses this configuration and redirects the request handling to the cWebHttpHandler object. This module is enabled for your application when registering it from the Studio or the Web Application Administrator.

Handling HTTP GET Requests

Sample

The following example shows how to handle a GET request using the cWebHttpHandler.

Use cWebHttpHandler.pkg

Object oSimpleHTTPHandler is a cWebHttpHandler
    Set psPath to "SayHello"
    Set psVerbs to "GET"

    Procedure OnHttpGet String sPath String sAcceptType
        String sName

        Get UrlParameter "name" to sName

        Send AddHttpResponseHeader "Content-Type" "text/html"

        Send OutputString ''
        Send OutputString 'Hello World!'
        Send OutputString (SFormat('

# Hello World %1!

', sName))
        Send OutputString ''
    End_Procedure
End_Object

This handler will respond to the SayHello path inside the location where the application is published in IIS. For example, http://localhost/MyApplication/SayHello?name=John if the application is published in the MyApplication virtual directory.

cWebHttpHandler

Simple REST Example

The example below shows how a simple REST handler could be built. In this example, a GET request is handled, and based on the URL, it will return a specific customer. The example shows how to use AddHttpResponseHeader, OutputUChar, and SetResponseStatus. Note that this example assumes functions like CustomerDetails and CustomerOverview to exist and work with cJsonObject handles. See 'DemoSimpleRestService.wo' inside the WebOrder for a more complete sample.

Use cWebHttpHandler.pkg
Use cJsonObject.pkg

Object oSampleRestService is a cWebHttpHandler
    Set psPath to "SampleRestService"
    Set psVerbs to "GET"

    Procedure OnHttpGet String sPath String sAcceptType
        String[] aParts
        Handle hoJson
        UChar[] ucData

        Get StrSplitToArray sPath "/" to aParts

        If (SizeOfArray(aParts) > 1) Begin
            If (Lowercase(aParts[1]) = "customers") Begin
                If (SizeOfArray(aParts) > 2) Begin
                    Get CustomerDetails aParts[2] to hoJson
                End
                Else Begin
                    Get CustomerOverview to hoJson
                End

                Get StringifyUtf8 of hoJson to ucData
                Send Destroy of hoJson

                Send AddHttpResponseHeader "Content-Type" "application/json"
                Send OutputUChar ucData
            End
            Else Begin
                Send SetResponseStatus 404 "Entity not known" 0
            End
        End
        Else Begin
            Send SetResponseStatus 404 "Not found" 0
        End
    End_Procedure
End_Object

Sample

The example below shows how a POST request works. It shows how to read request data using RequestDataUChar and parses this into a JSON object.

Procedure OnHttpPost String sPath String sContentType String sAcceptType Integer iSize
    String[] aParts
    Handle hoJson hoResponse
    UChar[] ucData
    Boolean bSuccess

    Get StrSplitToArray sPath "/" to aParts

    If (SizeOfArray(aParts) > 2 and Lowercase(aParts[1]) = "customers") Begin
        Get RequestDataUChar iSize to ucData
        Get Create (RefClass(cJsonObject)) to hoJson
        Get ParseUtf8 of hoJson ucData to bSuccess

        If (bSuccess) Begin
            Get SaveCustomer hoJson to hoResponse

            Get StringifyUtf8 of hoResponse to ucData
            Send Destroy of hoResponse
            Send Destroy of hoJson

            Send AddHttpResponseHeader "Content-Type" "application/json"
            Send OutputUChar ucData
        End
        Else Begin
            Send SetResponseStatus 500 "Unable to parse JSON" 0
            Send OutputString (psParseError(hoJson))
        End
    End
    Else Begin
        Send SetResponseStatus 404 "Entity not known" 0
    End
End_Procedure