TROHTTPFileDispatcher

Overview

This component allows to turn the Remoting SDK server into lightweight web server. After connected to any HTTP server channel (Super HTTP Channel support is coming soon) it is capable of serving static HTML pages and files from the specified local directory via HTTP protocol.

To start using TROHTTPFileDispatcher component you need to complete the following simple steps:

  • place the component onto a form
  • assign two properties derived from TROExtendedHttpDispatcher
    • Server - should point to the HTTP server channel instance
    • Path - determines the virtual folder path that will be served, see TROExtendedHttpDispatcher description for more information
  • specify the local path that will correspond to the virtual folder from the Path property - assign the Folder property

  • make sure the Folder contains all necessary files
    You may also fine-tune the web server behavior by specifying different DefaultFile or by assigning a handler for the OnRequest event.

    Notice some that users should be aware of:

  • Requests for folders above Path are forbidden. E.g. such requests as http://example.org/js/../secretfolder/secretfile.html will get 403 FORBIDDEN response.

  • Requests for Windows-specific files such as CON, AUX, PRN etc on Windows platforms are forbidden.
  • Any request path containing forbidden characters will get 500 INTERNAL ERROR response.
  • Users may use RegisterContentTypeForExtension procedure to associate certain extension with the certain content type. This is especially useful on non-Windows platforms because there is no registry where this information resides.
  • When OnRequest event is handled user's code takes full responsibility of the request processing, no other processing actions are performed except request validity check before the event is fired.
    This component is often used to build servers to use together with Remoting SDK for JavaScript to serve required JavaScript files to clients. See TROJavaScriptHttpDispatcher for more information.

Location


 

constructor Create  override

Standard component constructor

constructor Create(AOwner: TComponent)

Parameters:

  • AOwner: Owner

Activate  virtual    (declared in TROExtendedHttpDispatcher)

procedure Activate

Assign  override

Copies the contents of another, similar object.

procedure Assign(Source: TPersistent)

Parameters:

  • Source: Instance whose properties will be copied

CanHandlePath    (declared in TROExtendedHttpDispatcher)

Return true if the given path can be handled by the dispatcher. The function compares the Path property content with the given path and chacks if the given path starts with the Path subpath.

function CanHandlePath(aPath: string): Boolean

Parameters:

  • aPath: The request path to check.

Deactivate  virtual    (declared in TROExtendedHttpDispatcher)

procedure Deactivate

DefaultFile

The name of the file that will be served for directory request.
Example: assume we have configured the server to serve for /js/ virtual folder. The request to get http://example.org/js will serve the file specified with this property. Note: the request without trailing slash (http://example.org/js) will be redirected to the location with the trailing slash (http://example.org/js/) using 302 HTTP response code. The user's browser will get the new location and display it to the user seamlessly.
The default value is index.html

property DefaultFile: string read write

FireOnRequest  protected virtual

Fires the OnRequest event.

procedure FireOnRequest(Path: string; Data: TStream; out ContentType: string; out ResultCode: Integer; out Status: string)

Parameters:

  • Path: The request path.
  • Data: The response data - output parameter.
  • ContentType: The response content type - output parameter.
  • ResultCode: The response HTTP result code - output parameter.
  • Status: The response HTTP status message - output parameter.

Folder

The local path that will correspond to the virtual folder from the Path property. If relative path is specified then the path to the program main module will be used as base path.

property Folder: string read write

Notification  protected override    (declared in TROComponent)

Forwards notification messages to all owned components.

procedure Notification(aComponent: TComponent; Operation: TOperation)

Parameters:

  • aComponent: component
  • Operation: operation

NotifyDispose    (declared in TROExtendedHttpDispatcher)

This procedure is called when the server HTTP channel is about to be freed.

procedure NotifyDispose

OnRequest

Allows full customization of serving files by the user.
NOTICE: when this event is handled user's code takes full responsibility of the request processing, no other processing actions are performed except request validity check before the event is fired.

property OnRequest: TROHTTPFileDispatcherEvent read write
delegate:  procedure OnRequest(Sender: TObject; Path: string; Data: TStream; out ContentType: string; out ResultCode: Integer; out Status: string)

Path    (declared in TROExtendedHttpDispatcher)

The request path the dispatcher will be activated for. For example, if this property contains /js then the dispatcher will be activated by the server channel to process such requests as http://example.org:8099/js/* (the asterisk means zero or more characters to continue the request path).

property Path: string read write

Process  override

The main method to perform the request processing ant to form the response. Called every time to process incoming requests if the dispatcher is suitable to process it (determined by CanHandlePath result).

procedure Process(aTransport: IROHTTPTransport; aRequest: IROHTTPRequest; aResponse: IROHTTPResponse; aRequestData: TStream; aResponseData: TStream)

Parameters:

  • aTransport: Http transport.
  • aRequest: Contains object implementing IROHTTPRequest interface that describes the request.
  • aResponse: Contains initialized object implementing IROHTTPResponse interface that should describe the response.
  • aRequestData: The data stream (TStream) that contains the raw HTTP request data except the header part.
  • aResponseData: Contais initialized and empty data stream (TStream) that shpuld be filled with the raw reponse data except the header part.

ReplyWithMessage  protected

Internal utility method - prepares response with specified parameters and puts it into the response object and response stream.

procedure ReplyWithMessage(aCode: Integer; aStatus: string; aMessage: string; aResponse: IROHTTPResponse; aResponseData: TStream)

Parameters:

  • aCode: The HTTP response code.
  • aStatus: The HTTP response status message.
  • aMessage: The user understandable response message.
  • aResponse: The reference to the object describing the HTTP response.
  • aResponseData: The stream that will contain the response data.

ResolveContentType

Resolves and returns content type based on the file extension. Contains the content type table for the most often used extensions, others are resolved using registry (Windows platforms only).

function ResolveContentType(aExtension: string): string

Parameters:

  • aExtension: The file extension to resolve.

ROFreeNotification    (declared in TROComponent)

Forwards notification messages to all owned components.

procedure ROFreeNotification(aComponent: TComponent)

Parameters:

  • aComponent: component

RORemoveFreeNotification    (declared in TROComponent)

Forwards notification messages to all owned components.

procedure RORemoveFreeNotification(aComponent: TComponent)

Parameters:

  • aComponent: component

SendRemoveNotification  protected    (declared in TROComponent)

Forwards notification messages to all owned components.

procedure SendRemoveNotification(aComponent: TComponent)

Parameters:

  • aComponent: component

ServeCustom  protected virtual

Allows further customization of the serving process.

procedure ServeCustom(aFilePath: string; aRequest: IROHTTPRequest; aResponse: IROHTTPResponse; aResponseData: TStream)

Parameters:

  • aFilePath: The requested file path.
  • aRequest: The reference to the object describing the HTTP request.
  • aResponse: The reference to the object describing the HTTP response.
  • aResponseData: The stream that will contain the response data.

ServeFilesFromFolder

Enables or disables serving files from the Folder. When this property has false value then the only option to serve files remains the OnRequest event handler. The default is true.

property ServeFilesFromFolder: Boolean read write

ServeFromFolder  protected virtual

Locates file in the disk folder and forms the proper response.

procedure ServeFromFolder(aFilePath: string; aResponse: IROHTTPResponse; aResponseData: TStream)

Parameters:

  • aFilePath: The requested file path.
  • aResponse: The reference to the object describing the HTTP response.
  • aResponseData: The stream that will contain the response data.

Server    (declared in TROExtendedHttpDispatcher)

Points to the HTTP server channel which the dispatcher works with.

property Server: IROHTTPServer read write

ServeWithEvent  protected virtual

Performs event based serving, fires OnRequest event.

procedure ServeWithEvent(aRequest: IROHTTPRequest; aResponse: IROHTTPResponse; aResponseData: TStream)

Parameters:

  • aRequest: The reference to the object describing the HTTP request.
  • aResponse: The reference to the object describing the HTTP response.
  • aResponseData: The stream that will contain the response data.

 

DefaultFile

The name of the file that will be served for directory request.
Example: assume we have configured the server to serve for /js/ virtual folder. The request to get http://example.org/js will serve the file specified with this property. Note: the request without trailing slash (http://example.org/js) will be redirected to the location with the trailing slash (http://example.org/js/) using 302 HTTP response code. The user's browser will get the new location and display it to the user seamlessly.
The default value is index.html

property DefaultFile: string read write

Folder

The local path that will correspond to the virtual folder from the Path property. If relative path is specified then the path to the program main module will be used as base path.

property Folder: string read write

Path    (declared in TROExtendedHttpDispatcher)

The request path the dispatcher will be activated for. For example, if this property contains /js then the dispatcher will be activated by the server channel to process such requests as http://example.org:8099/js/* (the asterisk means zero or more characters to continue the request path).

property Path: string read write

ServeFilesFromFolder

Enables or disables serving files from the Folder. When this property has false value then the only option to serve files remains the OnRequest event handler. The default is true.

property ServeFilesFromFolder: Boolean read write

Server    (declared in TROExtendedHttpDispatcher)

Points to the HTTP server channel which the dispatcher works with.

property Server: IROHTTPServer read write

 

constructor Create  override

Standard component constructor

constructor Create(AOwner: TComponent)

Parameters:

  • AOwner: Owner

Activate  virtual    (declared in TROExtendedHttpDispatcher)

procedure Activate

Assign  override

Copies the contents of another, similar object.

procedure Assign(Source: TPersistent)

Parameters:

  • Source: Instance whose properties will be copied

CanHandlePath    (declared in TROExtendedHttpDispatcher)

Return true if the given path can be handled by the dispatcher. The function compares the Path property content with the given path and chacks if the given path starts with the Path subpath.

function CanHandlePath(aPath: string): Boolean

Parameters:

  • aPath: The request path to check.

Deactivate  virtual    (declared in TROExtendedHttpDispatcher)

procedure Deactivate

FireOnRequest  protected virtual

Fires the OnRequest event.

procedure FireOnRequest(Path: string; Data: TStream; out ContentType: string; out ResultCode: Integer; out Status: string)

Parameters:

  • Path: The request path.
  • Data: The response data - output parameter.
  • ContentType: The response content type - output parameter.
  • ResultCode: The response HTTP result code - output parameter.
  • Status: The response HTTP status message - output parameter.

Notification  protected override    (declared in TROComponent)

Forwards notification messages to all owned components.

procedure Notification(aComponent: TComponent; Operation: TOperation)

Parameters:

  • aComponent: component
  • Operation: operation

NotifyDispose    (declared in TROExtendedHttpDispatcher)

This procedure is called when the server HTTP channel is about to be freed.

procedure NotifyDispose

Process  override

The main method to perform the request processing ant to form the response. Called every time to process incoming requests if the dispatcher is suitable to process it (determined by CanHandlePath result).

procedure Process(aTransport: IROHTTPTransport; aRequest: IROHTTPRequest; aResponse: IROHTTPResponse; aRequestData: TStream; aResponseData: TStream)

Parameters:

  • aTransport: Http transport.
  • aRequest: Contains object implementing IROHTTPRequest interface that describes the request.
  • aResponse: Contains initialized object implementing IROHTTPResponse interface that should describe the response.
  • aRequestData: The data stream (TStream) that contains the raw HTTP request data except the header part.
  • aResponseData: Contais initialized and empty data stream (TStream) that shpuld be filled with the raw reponse data except the header part.

ReplyWithMessage  protected

Internal utility method - prepares response with specified parameters and puts it into the response object and response stream.

procedure ReplyWithMessage(aCode: Integer; aStatus: string; aMessage: string; aResponse: IROHTTPResponse; aResponseData: TStream)

Parameters:

  • aCode: The HTTP response code.
  • aStatus: The HTTP response status message.
  • aMessage: The user understandable response message.
  • aResponse: The reference to the object describing the HTTP response.
  • aResponseData: The stream that will contain the response data.

ResolveContentType

Resolves and returns content type based on the file extension. Contains the content type table for the most often used extensions, others are resolved using registry (Windows platforms only).

function ResolveContentType(aExtension: string): string

Parameters:

  • aExtension: The file extension to resolve.

ROFreeNotification    (declared in TROComponent)

Forwards notification messages to all owned components.

procedure ROFreeNotification(aComponent: TComponent)

Parameters:

  • aComponent: component

RORemoveFreeNotification    (declared in TROComponent)

Forwards notification messages to all owned components.

procedure RORemoveFreeNotification(aComponent: TComponent)

Parameters:

  • aComponent: component

SendRemoveNotification  protected    (declared in TROComponent)

Forwards notification messages to all owned components.

procedure SendRemoveNotification(aComponent: TComponent)

Parameters:

  • aComponent: component

ServeCustom  protected virtual

Allows further customization of the serving process.

procedure ServeCustom(aFilePath: string; aRequest: IROHTTPRequest; aResponse: IROHTTPResponse; aResponseData: TStream)

Parameters:

  • aFilePath: The requested file path.
  • aRequest: The reference to the object describing the HTTP request.
  • aResponse: The reference to the object describing the HTTP response.
  • aResponseData: The stream that will contain the response data.

ServeFromFolder  protected virtual

Locates file in the disk folder and forms the proper response.

procedure ServeFromFolder(aFilePath: string; aResponse: IROHTTPResponse; aResponseData: TStream)

Parameters:

  • aFilePath: The requested file path.
  • aResponse: The reference to the object describing the HTTP response.
  • aResponseData: The stream that will contain the response data.

ServeWithEvent  protected virtual

Performs event based serving, fires OnRequest event.

procedure ServeWithEvent(aRequest: IROHTTPRequest; aResponse: IROHTTPResponse; aResponseData: TStream)

Parameters:

  • aRequest: The reference to the object describing the HTTP request.
  • aResponse: The reference to the object describing the HTTP response.
  • aResponseData: The stream that will contain the response data.

 

OnRequest

Allows full customization of serving files by the user.
NOTICE: when this event is handled user's code takes full responsibility of the request processing, no other processing actions are performed except request validity check before the event is fired.

property OnRequest: TROHTTPFileDispatcherEvent read write
delegate:  procedure OnRequest(Sender: TObject; Path: string; Data: TStream; out ContentType: string; out ResultCode: Integer; out Status: string)