GotRequest

GotRequest
Prev	Events	Next

Metreos.Providers.Http.GotRequest

Summary

GotRequest is fired whenever an HTTP request sent to the application server is routed to a script.

Usage

The GotRequest event allows one to build scripts with HTTP server capabilities for any well-formed HTTP client, such as modern web browsers, Cisco IP phones, and HTTP client libraries in development environments. The script which receives the HTTP request should in general be sure to respond to the request with the SendResponse action.

The GotRequest event can be either a triggering event or a non-triggering event, meaning an HTTP request can either cause a script to initiate and begin executing, or an HTTP request can route to an already-running script.

The determination if an incoming HTTP request should be treated as a triggering event or a non-triggering event is based on the presence of session information in the request. Specifically, the following describes how HTTP requests are processed by the HTTP provider:

If the HTTP request contains no session information, the HTTP request is sent up to the Application Runtime Environment as a triggering event, at which point:
- If the event signature of the request matches the event filter criteria of an enabled script, that script will initiate and begin executing.
- Otherwise if no enabled script's event filter criteria matches the event signature of the incoming request, the GotRequest is not handled, and the HTTP provider will then send a 404 response to the client, because no script is available to process the request.
If the HTTP request does contain session information, meaning that either a cookie, query parameter, or header with the name of metreosSessionId has the RoutingGuid of a script as its value, then the event is sent to the Application Runtime Environment as a non-triggering event. The event is routed to a script with a RoutingGuid matching that found in the session information from the request, at which point:
- If the event signature of the request matches the event filter criteria of one of the HTTP event handler functions defined in that routed-to script, that event will be placed into the script event queue of that script to be handled so that it will be processed by the script--or if there are no functions currently being processed in the script then the event will be processed immediately.
- Otherwise if no event handler function defined matches the event signature within the routed-to script or if the script with the specified RoutingGuid has already ended, the GotRequest is not handled, and the HTTP provider will then resend the same GotRequest event as a triggering event (essentially the same event as before but without the RoutingGuid included). All the behavior and rules of an HTTP GotRequest triggering event, defined in step 1 above then apply.

The type QueryParamCollection can be used to easily access query parameters associated with the incoming HTTP request.

The GotRequest has all headers supplied as custom event parameters. To access these headers, one must create a local variable in the designer and initialize the variable, supplying the name of the header of interest as the value of the InitializeWith property. Be sure to also specify the DefaultValue property so that the script starts gracefully in the case that the header is not present in the request. One can also use the value of the default value parameter to determine if the header is present or not in the request--by comparing the value of the local variable to the value of the default value, one can determine if it was initialized with the header value or the default value.

Remarks

The HTTP Provider listens on port 8000 for script-bound HTTP requests. This port is not configurable.

The HTTP Provider does not support HTTPS.

If one does not send a response with their script within 5 minutes, the HTTP provider will automatically send a 404 back to the client.

Event Parameters
Parameter Name	.NET Type	Description
Body	`System.String`	The content of the request. If the `Method` is a POST, then one can initialize a `FormCollection` with this event parameter, in order to access the useful utilities found in the `FormCollection` type.
Url	`System.String`	The path portion of the request URI, always starting with the initial '/' after the `Host` portion parameter of the URI, and ending with the last character in the URI or, if '?' is present in the URI, the character before the first occurrence of '?'.
RemoteHost	`System.String`	The IP address and port of the remote client, of the form IP:PORT.
RemoteIpAddress	`System.String`	The IP address of the remote client.
Host	`System.String`	Host portion of the request URI of the form 'IP:PORT'. 'PORT' in this case is always 8000, because it is not configurable.
Hostname	`System.String`	The host portion of the request URI. Port information is not contained within this parameter.
Port	`System.Int32`	The port portion of the request URI.
Query	`System.String`	The query string portion of the request URI, always starting with the initial '?' after the `Url` portion of the URI, and ending with the last character in the URI. One can initialize a `QueryParamCollection` with this event parameter, in order to access the useful utilities found in the `QueryParamCollection` type.
Method	`System.String`	The request method, such as GET or POST.