TIdCustomHTTPServer
Specifies properties, methods, and events for the Indy HTTP Server implementation.
Unit
Description
TIdCustomHTTPServer is a
TIdTCPServer descendant that specifies properties, methods, and events for an implementation of the Hypertext Transfer Protocol (HTTP) as described in the Internet Standards document:
- RFC 1945 - Hypertext Transfer Protocol [HTTP] version 1.0 (http://www.rfc-editor.org/rfc/rfc1945.txt)
- RFC 2616 - Hypertext Transfer Protocol [HTTP] version 1.1 (http://www.rfc-editor.org/rfc/rfc2616.txt)
Application do not normally create instances of TIdCustomHTTPServer. Most properties, methods, and events in TIdCustomHTTPServer are protected to allow descendant classes to override their implementaion. Use TIdHTTPServer to access published properties, method, and events.
TIdCustomHTTPServer also supports the Secure Hypertext Transport protocol (HTTPS) as described in the Internet Standards document:
- RFC 2660 - The Secure HyperText Transfer Protocol (http://www.rfc-editor.org/rfc/rfc2660.txt)
Assign an instance of TIdServerInterceptOpenSSL to the Intercept property to allow use of the HTTPS protocol. For the Windows platform, you must install the Indy OpenSSL support .DLL's available at http://www.intelicom.si to enable Secure Socket Layer support.
Requests a new session when an existing session is not found.
property AutoStartSession: boolean;
Description
AutoStartSession is a Boolean property that indicates a new HTTP session should be created when a persistent HTTP session does not exist in
SessionList.
AutoStartSession is used when a threaded HTTP client connection executes, and SessionState indicates that persistent sessions are maintained on the HTTP server. AutoStartSession allows CreateSession to be called when an HTTP session cannot be found in SessionList containing the GSessionIDCookie for the client IP address.
Note: Even when AutoStartSession is True, CreateSession will not be called when OnInvalidSession indicates that the session should not be allowed to continue.
The default value for AutoStartSession is Id_TId_HTTPAutoStartSession as assigned in the Create constructor.
Default port number for the server.
property DefaultPort: integer;
Description
DefaultPort is a published property in
TIdHTTPServer that identifies the default port number for listener threads in the server, as described in the Hypertext Transfer Protocol specification. The default value for DefaultPort is
IdPORT_HTTP.
Indicates if a client connection should remain open for subsequent use in an HTTP session.
property KeepAlive: Boolean;
Description
KeepAlive is a Boolean property that indicates if the HTTP server should keep the connection open for the session established in an executing client thread. When KeepAlive is True, the connection used for the HTTP response is give a 'keep-alive' header in the response content. When KeepAlive is False, the connection header 'close' is used in the HTTP response.
The default value for KeepAlive is Id_TId_HTTPServer_KeepAlive, as assigned in the Create constructor.
Represents the MIME type table for the HTTP server implementation.
Description
MIMETable is a read-only
TIdMimeTable property that is used to retrieve the registered MIME type for a file requested in the
ServeFile method. Values in MIMETable may be assigned to the ContentType property in the
TIdHTTPResponseInfo containing headers written in the HTTP response.
MIMETable is initialized in the Create constructor, and loaded with default values using TIdMimeTable.BuildCache. MIMETable is freed in the Destroy method.
Requests parsing of query parameters in client requests.
property ParseParams: boolean;
Description
ParseParams is a Boolean property that indicates the string list should be populated with the query values from the client request query string (GET method) or form values (POST method).
For a client request in the form:
http://www.mydomain.com/test.htm?color=blue&size=10&style=44
The Params property would contain:
color=blue size=10 style=44
The developer has easy access to the value of named parameters using the RequestInfo.Params.Values property:
Color := RequestInfo.Params.Values['Color'];
To parse non-standard request query or form data, the ParseParams property should be set to false, and the developer will need to build a parser to extract the parameters from the UnparsedParams property.
Indicates the server software used to generate the HTTP response.
property ServerSoftware: string;
Description
ServerSoftware is a String property that contains textual values that identify the server software used to generate the values in the HTTP response.
Container for HTTP sessions for the server.
Description
Indicates that the server uses persistent HTTP sessions.
property SessionState: Boolean;
Description
SessionState is a Boolean property that indicates persistent sessions are used by the HTTP server to service requests from peer threads. SessionState is used by
CreateSession to determine if a new persistent session is created and added to the session list.
SessionState is used to get the cookie value for a session, and to determine if a persistent session matching the 'IDHTTPSESSIONID' cookie and Remote IP address should be retrieved from the session list.
specifies the default time-to-live for persistent HTTP sessions.
property SessionTimeOut: Integer;
Description
SessionTimeOut is an Integer property that specifies the default time-to-live for persistent HTTP sessions created by the HTTP server. SessionTimeOut is assigned as the default SessionTimeOut for the server session list when the HTTP server becomes active.
SessionTimeOut is used determine when a persistent HTTP session has expired, or become stale. Stale persistent sessions are removed from the HTTP session list.
Constructor for the object instance.
constructor Create(AOwner: TComponent); override;
Parameters
AOwner: TComponent
Owner of the object instance.
Description
Create is the constructor for the
TIdHTTPServer instance. Create calls the inherited Create method using AOwner. Create allocates resources needed for the
SessionList and
MIMETable properties, and sets the following properties to their default values:
Create also sets an internal flag that indicates if an executing theaded client connection can execute even when OnCOmmandGet is unassigned (False).
Creates a new HTTP session.
Parameters
HTTPResponse: TIdHTTPResponseInfo
The response to use for the session.
HTTPRequest: TIdHTTPRequestInfo
The request to use for the session.
Return Value
TIdHTTPSession - The session created for the HTTP request and response.
Description
CreateSession is a
TIdHTTPSession function used to get a new persistent HTTP session for the server implementation. CreateSession initializes a new HTTP session with a unique SessionID for the IP address specified in the HTTPRequest parameter. SessionID is added to the HTTPResponse as the
GSessionIDCookie cookie. The new session is assigned to both the HTTP Request and the HTTP Response for the executing client thread, and added to the
SessionList for the server.
If SessionState is False, CreateSession will perform no action and return the value Nil.
Frees the object instance.
destructor Destroy; override;
Description
Destroy is the destructor for the object instance. Destroy insures that the server is not Active, or listening for new connections. Destroy frees resources allocated to the
MIMETable and
SessionList properties. Destroy calls the inherited method to complete destruction of the object instance.
Frees the named HTTP session.
function EndSession(const SessionName: string): boolean;
Parameters
const SessionName: string
Identifier of the session to be freed.
Return Value
Boolean - True when the named session is found and freed.
Description
EndSession is a Boolean function that allows the HTTP server to free the
TIdHTTPSession using the name specified in SessionName. EndSession attempts to locate the
TIdHTTPSession in
SessionList that has a SessionID matching SessionName. When a session is found that matches SessionName, it is freed from the
SessionList and the return value for the method is set to True.
EndSession uses SessionList.GetSession to find the named session. If a valid session reference is retrieved, the session is freed.
Requests a file transfer to the HTTP client.
Parameters
AThread: TIdPeerThread
The peer thread requesting the file.
ResponseInfo: TIdHTTPResponseInfo
The response object used to write headers for the HTTP response.
aFile: TFileName
Return Value
Cardinal - Number of bytes written to the peer thread connection.
Description
ServeFile is a Cardinal function used to
send the contents of a file on the HTTP server to the HTTP client represented by the peer thread connection.
ServeFile uses MIMETable to determine the content type for the requested file.
ServeFile uses AResponseInfo to write the HTTP response headers, and writes the content of the file in AFile to the peer thread Connection.
Represents the event handler for unknown HTTP commands.
Parameters
asCommand
The command from the HTTP request.
asData
The data from the HTTP request.
asVersion
The version number from the HTTP request.
Thread
The peer thread generating the event.
Description
OnCommandOther is the
TIdHTTPOtherEvent event handler used to respond to unknown HTTP commands. OnCommandOther is used during execution of the threaded client connection when a command other than GET, POST, or HEAD is received in the HTTP request.
The application must assign a procedure to the OnCommandOther event handler to allow the server to respond to the unknown HTTP command. Use OnCommandOther to generate custom Response or Error messages, handle non-standard HTTP commands, or perform processing specific to the HTTP server implementation when an error occurs.
Event signalled when a session is needed a client connection.
Parameters
ASender
THread of execution for the threaded client connection.
VHTTPSession
HTTP session for the event notification.
Description
OnCreateSession is a
TOnCreateSession property that represents the event handler signalled when an HTTP session is needed for a threaded client connection. OnCreateSession is signalled when
TIdCustomHTTPServer.CreateSession is used and
TIdCustomHTTPServer.SessionState is True, and allows the server implementation to retrieve or create an HTTP session using the requirements or logic desired.
Applications must assign a procedure to the OnCreateSession event handler to allow responsing to the event notification. When OnCreateSession is unassigned, the HTTP server will use the TIdHTTPDefaultSessionList.CreateUniqueSession method to initialize an HTTP session.
Event handler signalled when a session cannot be restored for a specific SessionID.
Parameters
ContinueProcessing
Indicates that a new session can be created. InvalidSessionID - Session ID found in a Request Cookie.
RequestInfo
Header sent in the client request.
ResponseInfo
Header to include in a response.
Thread
Client connection generating the event notification.
Description
OnInvalidSession is a
TIdHTTPInvalidSessionEvent property that represents the event handler signalled when a persistent session with the specified SessionID cannot be restored from
SessionList.
OnInvalidSession is signalled when the threaded client connection in Thread is executed. InvalidSessionID is the GSessionIDCookie value that identifies the session to be restored. The event handler can set the value of ContinueProcessing to indicate if the server can create a new session for the threaded client connection.
Applications must assign a procedure to the event handler to allow responding to the event notification.
Specifies the event handler for terminating HTTP sessions.
Description
OnSessionEnd is the
TOnSessionEndEvent event handler used to respond to the event notification for termination of a HTTP session. OnSessionEnd is assigned to the OnSessionEnd event handler for the HTTP session list used by server. The event handler is assigned when the server becomes active.
Specifies the event handler for creating a new HTTP session.
Description
OnSessionStart is the
TOnSessionStartEvent event handler used to respond to the event notification for creation of a new HTTP session. OnSessionStart is assigned to the OnSessionStart event handler for the HTTP session list used by server. The event handler is assigned when the server becomes active.