WebApplication.HandleSpecialURL

Event

WebApplication.HandleSpecialURL(Request As WebRequest) As Boolean

New in 2011r2

Supported for all project types and targets.

The /special/ or /api/ path of a web application URL allows you to handle communication from outside services (such as PayPal Instant Payment Notifications) and prepare your own HTTP output. For example, if your URL is http://mydomain.com/myapp.cgi, the special url path is http://mydomain.com/myapp.cgi/special/. This can be useful for creating your own web services.

Notes

To call a web service implemented using HandlSpecialURL you would use an address similar to this:

http://127.0.0.1:8080/api/GetAllCustomers

The above address is to a standalone web app running on the local machine. In this method, Request.Path contains "GetAllCustomers".

Starting with 2018r1, the Date header is added to the incoming request.

This event is passed a WebRequest object which contains all the information necessary to generate your content. If you have handled the request, return true, otherwise your output will be ignored.

Because this is an application-level URL, the event is handled without a session context. Unhandled exceptions will be handled by WebApplication.UnhandledException. If you return False from WebApplication.UnhandledException this event will output Internal Server Error html. This will not cause your app to terminate.

Calls to this event are threaded so that simultaneous calls from clients can be handled properly.

In CGI mode, the headers sent with the WebRequest object have the same limitations as they do in WebSession.Header.

Session is not available from this event handler.

For Xojo Cloud, you must provide the full URL, including "index.cgi". For example: http://demos.xojo.com/EEWS/index.cgi/special/GetAllCustomers

Sample Code

This code demonstrates how to use this event for session-specific communication. The session identifier will need to be passed as part of the url, either as part of the path itself, or in the query parameters. In the case of this example, the session identifier will be part of the path itself.

The first part of this example is the action event of a button. We have added a property to Session called RandomValue. The button will create a random number and assign it to this property, inform the user which number was chosen, then display a url inside the /special path.

Var r As New Random
r.RandomizeSeed
Session.RandomValue = r.InRange(100, 999)

MessageBox("The value displayed will be " + Str(Session.RandomValue, "0"))
ShowURL(App.URL + "/special/" + Session.Identifier)

Because the URL is within the /special/ path, HandleSpecialURL will be called. Below is the code for the HandleSpecialURL event.

// There is minimal error handling in this example. For instance, the
// path may not be a session identifier.
Var sessionID As String = Request.Path

// We need to find the session for the given SessionID. For security
// reasons, always lookup the session with the Request.RemoteAddress
// value. Passing the address as part of the request in any way would
// pose a security risk to your end user.
// We will create a WebSessionContext object to put this session in
// context, causing our Session object to become value.
Var sessionContext As New WebSessionContext(Self.SessionWithIdentifier(sessionID))

// Now we will output the value of Session.RandomValue
Request.Print("<!DOCTYPE html>" + EndOfLine)
Request.Print("<html>" + EndOfLine)
Request.Print("<head>" + EndOfLine)
Request.Print("<title>Example Output</title>" + EndOfLine)
Request.Print("</head>" + EndOfLine)
Request.Print("<body>" + EndOfLine)
Request.Print("<h1>Example Output</h1>" + EndOfLine)
Request.Print("<p>RandomValue = " + Str(Session.RandomValue, "0") + "</p>" + EndOfLine)
Request.Print("</body>" + EndOfLine)
Request.Print("</html>")

// Return true to signal that we handled the request
Return True