roHttpServer

Object Creation: The roHttpServer object is created with an roAssociativeArray.

CreateObject("roHttpServer", parameters As roAssociativeArray)

Currently, the associative array can contain a single parameter:

• port: The port number of the embedded web server

ifHttpServer

Each “Add” handler method described below takes an associative array as its parameter. Values in the associative array specify how the handler behaves. See the table at the end of this section for common key:value pairs.

GetFailureReason() As String

Yields additional useful information if an roHttpServer method fails.

AddGetFromString(parameters As roAssociativeArray) As Boolean

Causes any HTTP GET requests for the specified URL path to be met directly with the contents of the "body" member of the parameter associative array. The MIME type (and potentially the entire character set) should be specified if the request is expected to come from a web browser. The request is handled entirely within the roHttpServer method; no events are sent to the message port.

AddGetFromFile(parameters As roAssociativeArray) As Boolean

Causes any HTTP GET requests for the specified URL path to be met directly from the specified file. You should always specify the MIME type (and possibly the character set) if you expect the request to come from a web browser. The request is handled entirely within the roHttpServer method; no events are sent to the message port.

AddGetFromFolder(parameters As roAssociativeArray) As Boolean

Constructs a dynamic handler that serves up static files, which will appear as children of the defined storage folder. This method accepts an associative array with the following parameters:

• folder: The file path of the folder that will act as the root directory of the server. If this parameter is absent, everything on the storage device will be served.
• url_prefix: The URL prefix under which files will be served. If this parameter is absent, the URL will match from root.
• filters: An array of filters. Each filter is an associative array with the following parameters:
  • re: The regular expression to match against the request URL.
  • ext: The extension to match against the leaf file of the request URL.

• • headers: An associative array containing arbitrary headers to be included with the automatic response.
  • content_type: The contents of the "Content-Type" header included with the automatic response. This cannot be set in the same filter as the headers. The MIME type and character set can be specified together (e.g. "text/plain; charset=utf-8").

AddGetFromEvent(parameters As roAssociativeArray) As Boolean

Requests that an event of type roHttpEvent be sent to the configured message port. This occurs when an HTTP GET request is made for the specified URL path.

AddPostToString(parameters As roAssociativeArray) As Boolean

Requests that an event of type roHttpEvent be sent to the configured message port. This occurs when an HTTP POST request is made for the specified URL path. Use the roHttpEvent.GetRequestBodyString() method to retrieve the posted body.

AddPostToFile(parameters As roAssociativeArray) As Boolean

Requests that, when an HTTP POST request is made to the specified URL path, the request body be stored in a temporary file according to the parameters["destination_directory"] value in the associative array. When this request is complete, an roHttpEvent event is sent to the configured message port. Use the roHttpEvent.GetRequestBodyFile() method to retrieve the name of the temporary file. If the file still exists at the time the response is sent, it will be automatically deleted. However, if the player reboots or loses power during the POST process, the file will not be deleted. For this reason, we recommend using a dedicated subdirectory as the "destination_directory" and wiping this subdirectory during startup (using DeleteDirecotry()) before adding handlers that refer to it.

AddPostToFormData(parameters As roAssociativeArray) As Boolean

Requests that, when an HTTP POST request is made to the specified URL path, an attempt be made to store form data (passed as application/x-www-form-urlencoded or multipart/form-data) in an associative array that can be retrieved by calling the roHttpEvent.GetFormData() method.

AddMethodFromEvent(parameters As roAssociativeArray) As Boolean

Requests that an event of type roHttpEvent be sent to the configured message port. Unlike AddGetFromEvent(), this method can support arbitrary HTTP methods. The HTTP method is specified using the method member in the associative array.

AddMethodToFile(parameters As roAssociativeArray) As Boolean

Requests that, when an arbitrary HTTP request is made to the specified URL path, the request body be stored in a temporary file according to the parameters["destination_directory"] value in the associative array. The HTTP method is specified using the method member in the associative array. When the request is complete, an roHttpEvent event is sent to the configured message port. Use the roHttpEvent.GetRequestBodyFile() method to retrieve the name of the temporary file. If the file still exists at the time the response is sent, it will be automatically deleted.

AddMethodToString(parameters As roAssociativeArray) As Boolean

Attempts to support an arbitrary HTTP method. The request body is placed in a string and an event is raised. This makes the request body available via the roHttpEvent.GetRequestBodyString() method. A response can be sent in the same manner as the AddGetToEvent() method.

SetupDWSLink(parameters As Dynamic) As Boolean

Generates a tab in the Diagnostic Web Server (DWS) that links to files hosted by the roHttpServer instance. The tab will function differently depending on the parameters passed to the method.

• title As String: Generates a tab with title that links directly to the base ip_address:port of the roHttpServer instance.
• {title:[title As String], tab:”no”}: Generates a tab with title that links to a DWS page. This page will contain a single link to the base ip_address:port of the roHttpServer instance.
• {title:[title As String], link1:[params As roAssociativeArray], link2:[params As roAssociativeArray], ...,}: Generates a tab with title that links to a DWS page. This page can contain any number of links to files hosted by the roHttpServer instance. Each link is configured with an associative array containing the following key:value pairs:
  • name: The name of the link on the DWS page
  • url: The url_path of the file hosted by the roHttpServer instance (see the table below for details)

server1.SetupDWSLink("My AWS Link")
server2.SetupDWSLink({ title: "My AWS Link", tab: "no" })
server3.SetupDWSLink({ title: "Link> ", link1: { name: "Name 1", url: "/mylink1.jpg" }, link2: { name: "Name 2", url: "/mylink2.jpg" } })

Parameters for "Add" Handler Methods 

The following table describes common key:value pairs for "Add" handler methods:

ifMessagePort

SetPort(port As roMessagePort)

Posts messages of type roHttpEvent to the attached message port.