Class: cWebHttpHandler

Properties  Events  Methods    Index of Classes

Handles HTTP requests for REST and other HTTP services

Hierarchy

cObject
---cBaseWebComponent
------cWebHttpHandler
---------cWebHttpMultipartFormdataHandler

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 API's that read and write string values or binary data as UChar arrays. Compared to cWebService it has pretty 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 an 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 '<html>'
        Send OutputString '<head><title>Hello world!</title></head>'
        Send OutputString (SFormat('<body><h1>Hi %1!</h1></body>', sName))
        Send OutputString '</html>'
    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.



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 working 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 works. It shows how to read request data using RequestDataUChar and parses this in 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