Extended HTTP Requests

USE: Extended HTTP Requests

(Details - Use - Extend)

The Extended HTTP Requests building block can be integrated in your modelling tool implementation by downloading the necessary files and integrating them into your library and modelling tool installation.

Installation / Configuration

The following steps serve as a guide through the installation and setup procedure:

  1. Download Necessary Resources
    The necessary files can be downloaded in this package. The package contains:

  • Readme.txt – Additional information about the project, the files and how to use them.
  • HttpRequestDll.dll – The DLL file that handles the connection and HTTP request/response.
  • ASC_HttpRequestDll.asc – The AdoScript file containing some minor configuration (i.e. where is the DLL file located?) and the procedures. While the DLL could be called directly the here defined procedures provide an easier to handle interface.
  • Lazarus project files – available so that the user can extend the functionality if so desired.
  • Free Pascal Compiler License information
     

2.    Copy the DLL

For use during development: copy the HttpRequestDll.dll file into the ADOxx installation folder (typically "C:\Program Files (x86)\BOC\ADOxx151UL5_EN_SA\"). If it is not possible to copy the file into the ADOxx installation directory, then copy it to a place where ADOxx can access it and configure the provided script file (see next step).

For use in a built modelling tool: When using the "AutoPDP Tool Packaging" tool make sure to provide the DLL with the library and state where it should be located.

3.    Configure the Script File (if necessary)

When the DLL is not found in the ADOxx/Modelling tool installation directory, e.g. because the user doesn't have the necessary rights to copy it there or because it is located in a subfolder, then a small change to the ASC_HttpRequestDll.asc Script file is necessary: It contains a global variable (around line 50) "global_str_dll_httprequest", which specifies the location of the DLL file (including the file name). Adapt it as necessary.

4.    Add the Script to Your Library

The easiest way to add the Script to your library is by importing the ASC_HttpRequestDll.asc Script File into the library through the ADOxx Development Toolkit File Management (Menu: Extras -> File management…; see Video tutorial) and then automatically loading it during the modelling tool initialization. The latter can be achieved by extending the "ON_EVENT "AppInitialized" {…" section of the external coupling in the library configuration (select dynamic library -> Library attributes -> External coupling) with the following line: EXECUTE file:("db:\\ASC_HttpRequestDll.asc")

Once those steps are performed any AdoScript executed in the modelling toolkit will be able to access the provided procedures to make HTTP calls to online resources/services.

Use – Performing HTTP Calls

The following is a short documentation of the provided AdoScript file. For greater details check out the Readme.txt, the ASC_HttpRequestDll.asc file and the HttpRequestDll project files (source code in HttpRequestDll.lpr).

Global Variables:

  • global_str_dll_httprequest – specifies the location of the DLL file, including the file name. Default loads it from the modelling toolkit's installation directory: HttpRequestDll.dll

Global Procedures :

There are twelve  (3 * 2 * 2) procedures available, based on three aspects:

  • Decoding of the provided request body before sending it. Two options are available: send-as-is and base64 decode before sending.
  • The format of the returned body. Three options are available: normal string, base64 encoded string and byte array.
  • If basic authentication (username + password) should be used.
Note: Details about the different parameters will be provided at the end. The following procedures send the provided body "as-is":
  • HTTP_SEND_REQUEST (str_url) str_method:string
        map_reqheaders:map
        str_reqbody:string
        val_respcode:reference
        map_respheaders:reference
        str_respbody:reference
    sends an HTTP Request to the specified URL. The returned body of the response is provided as a normal string. Be aware that a NUL byte (\0) terminates the string.

  • HTTP_SEND_AUTH_REQUEST (str_url) str_method:string
        str_username:string
        str_password:string
        map_reqheaders:map
        str_reqbody:string
        val_respcode:reference
        map_respheaders:reference
        str_respbody:reference
    sends an HTTP Request to the specified URL with the provided authentication information (username and password). The returned body of the response is provided as a normal string. Be aware that a NUL byte (\0) terminates the string.

  • HTTP_SEND_REQUEST_BASE (str_url) str_method:string
        map_reqheaders:map
        str_reqbody:string
        val_respcode:reference
        map_respheaders:reference
        str_respbody:reference
    sends an HTTP Request to the specified URL. The returned body of the response is provided as a base64 encoded string. This is important since strings are terminated by a NUL (\0) byte and if the response can contain NUL bytes in the middle of the content, as for example can be the case with PNG images, then only part of the response would be available. ADOxx provides a "base64decode" function to decode base64 encoded content if necessary and is able to write files from a base64 string (FWRITE command of the AdoScript message port).

  • HTTP_SEND_AUTH_REQUEST_BASE (str_url) str_method:string
        str_username:string
        str_password:string
        map_reqheaders:map
        str_reqbody:string
        val_respcode:reference
        map_respheaders:reference
        str_respbody:reference
    sends an HTTP Request to the specified URL with the provided authentication information (username and password). The returned body of the response is provided as a base64 encoded string. This is important since strings are terminated by a NUL (\0) byte and if the response can contain NUL bytes in the middle of the content, as for example can be the case with PNG images, then only part of the response would be available. ADOxx provides a "base64decode" function to decode base64 encoded content if necessary and is able to write files from a base64 string (FWRITE command of the AdoScript message port).

  • HTTP_SEND_REQUEST_BYTES (str_url) str_method:string
        map_reqheaders:map
        str_reqbody:string
        val_respcode:reference
        map_respheaders:reference
        arr_respbody:reference
    sends an HTTP Request to the specified URL. The returned body of the response is provided as an array containing the byte values. This can again be important when NUL bytes are possible in the middle of the content.

  • HTTP_SEND_AUTH_REQUEST_BYTES (str_url) str_method:string
        str_username:string
        str_password:string
        map_reqheaders:map
        str_reqbody:string
        val_respcode:reference
        map_respheaders:reference
        arr_respbody:reference
    sends an HTTP Request to the specified URL with the provided authentication information (username and password). The returned body of the response is provided as an array containing the byte values. This can again be important when NUL bytes are possible in the middle of the content.

Additionally each of the above described procedures is provided with an "_INBASE" suffix. These procedures will first decode the provided body using base64 before it is sent to the specified URL. This can be necessary when for example uploading a PNG image. Otherwise, these behave the same:
  • HTTP_SEND_REQUEST_INBASE (str_urlstr_method:string
        map_reqheaders:map
        str_reqbody:string
        val_respcode:reference
        map_respheaders:reference
        str_respbody:reference

  • HTTP_SEND_AUTH_REQUEST_INBASE (str_urlstr_method:string
        str_username:string
        str_password:string
        map_reqheaders:map
        str_reqbody:string
        val_respcode:reference
        map_respheaders:reference
        str_respbody:reference

  • HTTP_SEND_REQUEST_BASE_INBASE (str_urlstr_method:string
        map_reqheaders:map
        str_reqbody:string
        val_respcode:reference
        map_respheaders:reference
        str_respbody:reference

  • HTTP_SEND_AUTH_REQUEST_BASE_INBASE (str_urlstr_method:string
        str_username:string
        str_password:string
        map_reqheaders:map
        str_reqbody:string
        val_respcode:reference
        map_respheaders:reference
        str_respbody:reference

  • HTTP_SEND_REQUEST_BYTES_INBASE (str_urlstr_method:string
        map_reqheaders:map
        str_reqbody:string
        val_respcode:reference
        map_respheaders:reference
        arr_respbody:reference

  • HTTP_SEND_AUTH_REQUEST_BYTES_INBASE (str_urlstr_method:string
        str_username:string
        str_password:string
        map_reqheaders:map
        str_reqbody:string
        val_respcode:reference
        map_respheaders:reference
        arr_respbody:reference

 

Parameters used by the procedures:

  • str_url – the URL that should be contacted provided as a string. Very likely it should start with "http://".

  • str_method – the HTTP method that should be sent with the request. As it is a string any possible value can be used, however that doesn't mean that the server understands them. Should be provided in uppercase. Typical examples are: OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE.
  • str_username – used in procedures for authentication on the server. Should specify the user name as a string.
  • str_password – used in procedures for authentication on the server. Should specify the password as a string.
  • map_reqheaders – the headers that should be sent with the request as a map. The keys of the map should be the field names and their values should be the values for those fields. Both keys and values should be of type string. "Host" and "Content-Length" seem to always be present automatically, but others like "Accept", "Content-Type" or "Authorization" have to be specified manually.
  • str_reqbody – the body of the request that should be sent as a string. The request body is sent as provided! This means that if for example a POST request with a "Content-Type" application/x-www-form-urlencoded (form data) is sent, the body string has to be encoded into the right format before calling this procedure.
  • val_respcode – a reference variable that will contain an integer with the response code. It is possible for the response code to be zero if something goes wrong before the HTTP call could be sent (e.g. the DLL could not be found). Examples for response codes are: 200, 400, 401, 500, 502 etc., couldn't find 404 though.
  • map_respheaders – a reference variable that will contain a map with the headers of the response. Both keys and values will be of type string.
  • str_respbody / arr_respbody – a reference variable that will hold the body of the response. Will either be a string, when using the normal or base64 procedure, or an array, when using the bytes procedure.

For help with using maps in AdoScript, please check out this link. Also note that AdoScript maps as a string and JSON objects are very similar.

Use – Utility Procedures

Additionally some utility procedures are provided which can make life easier when performing HTTP calls, which are documented here. For greater details check out the Readme.txt, the ASC_HttpRequestDll.asc file and the HttpRequestDll project files (source code in HttpRequestDll.lpr).

Global Variables:

global_str_dll_httprequest – specifies the location of the DLL file, including the file name. Default loads it from the modelling toolkit's installation directory: HttpRequestDll.dll

Global Procedures:

  • HTTP_URL_ENCODE (str_contentstr_allowedset:string str_encoded:reference 
    takes a text and uses URL encoding to escape any unsafe/not-allowed characters. Characters which are not allowed are replaced with one or more %xx where xx is an 8-bit hexadecimal number. Useful for sending POST requests with content-type 'application/x-www-form-urlencoded'.
    • str_content – a string containing the content to encode
    • str_allowedset – specifies which set of allowed characters should be used. Possible values are "JS" , "Inter", "Lax" or "VeryLax". "JS" allows the same characters as the on the Java Script encodeURIComponent() function (from Firefox / Chrome). Probably the safest bet in most cases. "Inter" is a list of characters based from several sources, including the URI specification. "Lax" allows everything except non-ASCII characters, ASCII control characters (0x00 to 0x20 and 0x7F), # (0x23), % (0x25), & (0x26), + (0x2B), = (0x3D) and ? (0x3F). "VeryLax" allows everything except non-ASCII characters, ASCII control characters (0x00 to 0x20 and 0x7F), % (0x25), & (0x26) and = (0x3D)
    • str_encoded – a reference that will contain the result of the encoding.
  • HTTP_URL_ENCODE_QUERY (map_contentstr_allowedset:string str_encoded:reference 
    takes a map containing key-value pairs and uses URL encoding to escape any unsafe/not-allowed characters and builds a string which follows the structure of the query-portion of a URL. This is used for example by data which is sent as 'application/x-www-form-urlencoded'. Characters which are not allowed are replaced with one or more %xx where xx is an 8-bit hexadecimal number.
    • map_content - a map containing keys and their values which should be transformed into the structure of the URL-query-portion.
    • str_allowedset – specifies which set of allowed characters should be used. Possible values are "JS" , "Inter", "Lax" or "VeryLax". "JS" allows the same characters as the on the Java Script encodeURIComponent() function (from Firefox / Chrome). Probably the safest bet in most cases. "Inter" is a list of characters based from several sources, including the URI specification. "Lax" allows everything except non-ASCII characters, ASCII control characters (0x00 to 0x20 and 0x7F), # (0x23), % (0x25), & (0x26), + (0x2B), = (0x3D) and ? (0x3F). "VeryLax" allows everything except non-ASCII characters, ASCII control characters (0x00 to 0x20 and 0x7F), % (0x25), & (0x26) and = (0x3D)
    • str_encoded – a reference that will contain the result of the encoding.