cObject
---cBaseWebComponent
------cWebHttpHandler
---------cWebHttpMultipartFormDataHandler
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.
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>Hello World %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.
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
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