Clarion Community Help

Overview

There are four (4) easy to use PROCEDUREs provided in ClaRunExt.dll to make it simple for you to make web requests using HTTP or HTTPS. You can send web requests (and receive responses) to Web Servers, REST Web Services, or standard Web Services, with the most commonly used HTTP verbs; POST, GET, PUT, and DELETE. These verbs (or methods) correspond to Create, Read, Update, and Delete (or CRUD) operations, respectively.

Implementation:

Requirements:

Coding

after the MAP section add the line:

INCLUDE('ClaRunExt.INC'),ONCE

create an instance of the class:

HttpReq  ClaRunExtClass

define variables for the parameters, for example:

httpWebAddress    CSTRING(512)          ! the address to send the webRequest

httpVerbMethod    BYTE                ! the HTTP method used in the webRequest, it can be HttpVerb:GET, POST, PUT, DELETE

postData          CSTRING(1024)        ! data passed to the webRequest when using the POST verb

requestParameters CSTRING(512)        ! parameters passed to the the webRequest appended to the http address after the ?

responseOut       CSTRING(64000)        ! the buffer to be filled with the response

filetoStore       CSTRING(512)        ! holds the name of the file to store the response

These are pre-defined EQUATES (ClaRunExt.inc):

HttpVerb:GET          EQUATE(0)

HttpVerb:POST         EQUATE(1)

HttpVerb:PUT          EQUATE(2)

HttpVerb:DELETE       EQUATE(3)

Runtime

Distribute ClaRunExt.dll (requires .Net 3.5 or higher be installed on target machine)

Example Usage:

See .\Examples\ClaTalk\HttpRequest\WebRequest.cwproj

Function descriptions

There are two main PROCEDURE variations; HttpWebRequest(-) and HttpWebRequestToFile(-).

Both of the PROCEDUREs have an override which accepts some additional parameters.

For HttpWebRequest() the shared parameters are:

<;param name=“httpWebAddress”> the address to send the webRequest<;/param>

<;param name=“httpVerbMethod”> the verb method used in the webRequest, it can be HttpVerb:GET, POST, PUT, DELETE<;/param>

<;param name=“postData”> data passed to the webRequest when using the POST verb<;/param>

<;param name=“requestParameters”> parameters passed to the the webRequest appended to the http address after the ?<;/param>

<;param name=“responseOut”> the buffer to be filled with the response, the buffer needs to be big enough to contain the response value<;/param>

in the override variant there are these two added parameters:

<;param name=“contentType”> the request content type, default is “text/xml”<;/param>

<;param name=“headers”> a string containing the headers and values separated by pipes name1|value|name2|value2<;/param>

Both PROCEDUREs have the same RETURN:

<;returns> Zero if the request was successful, if the buffer is not big enough the return value will be the numeric value of the required buffer size. If the value is negative an exception occurred, and the description of the exception is in the responseOut<;/returns>

For HttpWebRequestToFile() the shared parameters are:

<;param name=“httpWebAddress”> the HTTP address to send the webRequest<;/param>

<;param name=“httpVerbMethod”> the verb method used in the webRequest, it can be HttpVerb:GET, POST, PUT, DELETE<;/param>

<;param name=“postData”> data passed to the webRequest when using the POST verb<;/param>

<;param name=“requestParameters”> the parameters passed to the the webRequest appended to the HTTP address after the ?<;/param>

<;param name=“errorOut”> the text of the error message if an error occurred<;/param>

<;param name=“outputFilename”> the name of the file to store the response in <;/param>

in the override variant there are these two added parameters:

<;param name=“contentType”> the request content type, defaults to “text/xml”<;/param>

<;param name=“headers> a string containing the headers and values separated by pipes name1|value|name2|value2<;/param>

Both PROCEDUREs have the same RETURN:

<;returns> Zero if the request was successful, if the buffer is not big enough the return value will be the numeric value of the required buffer size. If the value is negative an exception occurred, and the description of the exception is in the responseOut<;/returns>

Examples:

WebRequest project (WebRequest.sln)

Located in Examples\Clatalk\HttpRequest

This example shows the use of all variations of HttpWebRequest and HttpWebRequestToFile.  It allows you to interactively experiment with all

four HTTP methods; POST, GET, PUT, and DELETE. You specify the server URI, parameters and the HTTP method, and the result (response from the server) is displayed in a Text control, or written to a File.

flickrClient project (flickrClient.sln)

Located in Examples\Clatalk\flickr

This example uses the flickr Http API to make an HTTPRequest for a “feed” of public images. It then parses the requested XML response into a Queue, and displays the Image associated with the current selection in the LIST control.

see also:

HttpWebRequest

HttpWebRequestToFile