From Xojo Documentation
Jump to: navigation, search

WebApplication.HandleSpecialURL ( Request as WebRequest ) As Boolean

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.


This event will be 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.

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


This example 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.

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

MsgBox("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 fired. Below is the code from the HandleSpecialURL event.

// There is minimal error handling in this example. For instance, the
// path may not be a session identifier.
Dim 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.
Dim 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)

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

See Also

WebRequest, WebSession, WebSessionContext

Personal tools

Starting Out
Dig Deeper
More Help