TIWApplication

TIWApplication is to an IntraWeb application what TApplication is to a standard Delphi application. Like the latter, TIWApplication is not a visual component. It does not appear on the object inspector and therefore does not have published properties. However, it has a number of public properties and methods that can be accessed via code in the IntraWeb application. Each user session has one TIWApplication instance. It represents the user's "application" or session. Each IWApplication instance is also tied to a particular IP address and TBrowser type and these properties cannot be modified during the IW application life time.

Unit

Class hierarchy

Methods

Create [Public]

Declaration: constructor Create(aBrowser: TBrowser; aRequest: THttpRequest; aResponse: THttpReply; const AIP: string; const AAuthUser, AAuthPassword: string;

Description: Constructs an instance of the class TIWApplication and initializes its data. This method is called internally by IWServer and should not be called directly by user's code.

Parameters:

• aBrowser (TBrowser): The TBrowser object instance representing the user's browser accessing the IW application instance
• aRequest (THttpRequest): The Request object instance. The Request object contains the all the data received during a HTTP request
• aResponse (THttpReply): The Response object instance
• AIP (string): IP from the client accessing your application
• AAuthUser (string): Received user name, used in IW authorization
• AAuthPassword (string): Received user password, used in IW authorization

InitApplication [Public]

Declaration: procedure InitApplication(aBrowser: TBrowser; aRequest: THttpRequest; aResponse: THttpReply; const AIP: string; const AAuthUser, AAuthPassword: string; const AReferringURL: string; AParams: TStrings; const AUrlBase: string);

Description: Initializes a IWApplication instance. This method is called internally by IWServer and should not be called directly by user's code.

Parameters:

• aBrowser (TBrowser): The TBrowser object instance representing the user's browser accessing the IW application instance.
• aRequest (THttpRequest): The Request object instance
• aResponse (THttpReply): The Response object instance
• AIP (string): IP from the client accessing your application
• AAuthUser (string): Received user name, used in IW authorization
• AAuthPassword (string): Received user name, used in IW authorization
• AReferringURL (string): Content of HTTP header field that identifies the URL of the webpage that linked to the resource being requested
• AParams (TStrings): A TStringList containing the received run time parameters
• AUrlBase (string): URL base of the application

SetRenderOverride [Public]

Declaration: procedure SetRenderOverride(aStream: TIWRenderStream);

Description: Sets IW application internal RenderOverride field. It is used to provide an overriden TIWRenderStream.

Parameters:

• aStream (TIWRenderStream): A TIWRenderStream that will be used for rendering.

FindFile [Public]

Declaration: function FindFile(AName: string): THttpFile;

Description: Returns a THttpFile instance submited (uploaded).

Parameters:

• AName (string): Name of the file.

Result: A THttpFile instance or nil if the file is not found.

AddDataModule [Public]

Declaration: procedure AddDataModule(DataModule: TDataModule);

Description: Adds a TDataModule instance to IWApplication's internal DataModule list. This method is called internally by IWServer and should not be called directly by user's code.

Parameters:

• DataModule (TDataModule): Instance of a TDataModule class that should be added.

RemoveDataModule [Public]

Declaration: procedure RemoveDataModule(DataModule: TDataModule);

Description: Removes a TDataModule instance from IWApplication's internal DataModule list. This method is called internally by IWServer and should not be called directly by user's code.

Parameters:

• DataModule (TDataModule): Instance of a TDataModule class that should be removed.

ExecuteActiveForm [Public]

Declaration: function ExecuteActiveForm(AParams: TStrings): boolean;

Description: This method calls TIWBaseForm.ExecuteForm() where IWForms process requests. This method is called internally by IWServer and should not be called directly by user's code.

Parameters:

• AParams (TStrings): A TStringList instance containing request parameters.

Result: True on success. It is False when an exception occurs during IWBaseForm.ExecuteForm().

GenerateActiveForm [Public]

Declaration: procedure GenerateActiveForm(aReply: THttpReply);

Description: This method calls TIWBaseForm.GenerateForm() where IWForm rendering occurs. It also triggers ServerController's OnBeforeRender and OnAfterRender events. This method is called internally by IWServer and should not be called directly by user's code.

Parameters:

• aReply (THttpReply): Contains a THttpReply instance.

GoToURL [Public]

Declaration: procedure GoToURL(const AURL: string);

Description: Use this method to redirect the user to a specific URL. If you want to redirect the user to a URL oustide of your application, you need to supply a full qualified URL, ie, an absolute URL (ex: http://www.atozed.com). If you want to redirect the user to a URL within the application you can use a relative URL (ex: /reports/sales_may_2012.pdf)

Parameters:

• AURL (string): URL to be used in redirection.

Initialize [Public]

Declaration: procedure Initialize(ARequest: THttpRequest; AResponse: THttpReply);

Description: Sets internal Request and Response fields. This method is called internally by IWServer and should not be called directly by user's code.

Parameters:

• ARequest (THttpRequest): The Request object instance.
• AResponse (THttpReply): The Response object instance.

MarkAccess [Public]

Declaration: procedure MarkAccess;

Description: Updates the LastAccess property of TIWApplication with current date and time. This method is called internally by IWServer and should seldom, if ever, be called directly.

FullApplicationURL [Public]

Declaration: class function FullApplicationURL(ARequest: THttpRequest): string;

Description: Returns the full URL for the application

Parameters:

• ARequest (THttpRequest): The request object instance

Result: A string containing the full URL.

RemoveForm [Public]

Declaration: procedure RemoveForm(AForm: TComponent);

Description: Removes a TIWForm instance from IWApplication's internal form list. This method is called internally by IWServer and should not be called directly by user's code.

Parameters:

• AForm (TComponent): Instance of a TIWBaseForm class that should be removed.

ReleaseForm [Public]

Declaration: procedure ReleaseForm(AForm: TComponent);

Description: Adds an instance of TIWBaseForm to the IWApplication's internal FReleasedForms list. Forms in this list should be freed in a later stage during IW processing. This method is called internally by TIWBaseForm.Release() method and should seldom, if ever, be called directly by user's code directly.

Parameters:

• AForm (TComponent): Instance of a TIWBaseForm class that should be released.

SendFile [Public]

Declaration: procedure SendFile(const aPathname: string; const aAttachment: Boolean = False; aContentType: string = ''; aFilename: string = '');

Description: Use this method to send a file to the browser (file download). If you need IntraWeb to send a file outside wwwroot and cache paths, this is the method you should use.

Parameters:

• aPathname (string): The aPathname parameter accepts a path and a file name that is locally accessible by your application. You need to specify a fully path to the file.
• aAttachment (Boolean): The aAttachment parameter indicates if the file will be presented to the user as a download (aAttachment = True) file or if the file will be opened by the browser. For example, if you are sending a PDF file, you can choose to allow the user download it directly or to show the PDF within the browser. aAttachment as False is only valid if the user has an installed application capable of opening the file type.
• aContentType (string): Content type used in response header. If not Content type is provided, IntraWeb will provide one based on file extension.
• aFilename (string): The aFilename parameter can be used to specify a different name to be shown to the user instead of the original file name.

SendStream [Public]

Declaration: procedure SendStream(aStream: TStream; const aAttachment: Boolean = False; const aContentType: string = ''; const aFilename: string = '');

Description: Use this method to send a Stream to the browser (stream download). The AStream parameter accepts any TStream inherited class.

Parameters:

• aStream (TStream): Any TStream descendant. The aStream content will be sent to the browser.
• aAttachment (Boolean): The aAttachment parameter indicates if the stream will be presented to the user as a download (aAttachment = True) file or if the file will be opened by the browser. For example, if you are sending a PDF file, you can choose to allow the user download it directly or to show the PDF within the browser. aAttachment as False is only valid if the user has an installed application capable of opening the file type.
• aContentType (string): The aContentType is used to specify the content type of the stream.
• aFilename (string): he aFilename parameter can be used to specify a default file name to be shown to the user.

SetSendHeaders [Public]

Declaration: procedure SetSendHeaders(const aAttachment: Boolean; const aContentType: string; const aFilename: string);

Description: Used to set HTTP header fields before sending a file or stream. It is called by SendFile() and SendStream() public methods. This method is called internally by IWServer and should not be called directly by user's code.

Parameters:

• aAttachment (Boolean): Indicates if the file/stream should be sent as an attachment.
• aContentType (string): Contains the "Content-Type" HTTP header field.
• aFilename (string): Name of the file in HTTP header.

SetActiveForm [Public]

Declaration: procedure SetActiveForm(AForm: TComponent);

Description: Changes the active form for the application. This method is called internally by IWServer and should not be called directly by user's code.

Parameters:

• AForm (TComponent): A TIWBaseForm instance.

SetUserNameAndPassword [Public]

Declaration: procedure SetUserNameAndPassword(aUserName, aPassword: string);

Description: Used internally by IW classes to set user name and password when using built-in IW Authorization components.

Parameters:

• aUserName (string): user name used in IW authorization components.
• aPassword (string): password used in IW authorization components.

SwitchToSecure [Public]

Declaration: procedure SwitchToSecure;

Description: Call this method to switch to a secure connection when your application supports SSL.

SwitchToNonSecure [Public]

Declaration: procedure SwitchToNonSecure;

Description: Call this method to switch to a non-secure connection when your application supports SSL and your application is on a secure connection.

ShowMessage [Public]

Declaration: procedure ShowMessage(AMsg: string; const AType: TIWShowMessageType = smAlert; ATemplate: string = ''); overload;

Description: Shows a message to the user when executed in the browser context.

Parameters:

• AMsg (string): Message to be displayed
• AType (TIWShowMessageType): Type of the message "dialog"

TIWShowMessageType = (smAlert, smNewWindow, smSameWindow, smSameWindowFrame);

smAlert: A standard alert() dialog is used

smNewWindow: "AMsg" string is displayed in a new pop-up window

smSameWindow: The "AMsg" string is displayed in the same window and replaces the current page. Clicking OK returns to the previous page.

smSameWindowFrame: Works just like smSameWindow. The "AMsg" string is displayed in the same window within a region with scroll bars.

• ATemplate (string): Name of the template to be used in smSameWindow and smSameWindowFrame modes. If no value is provided, IntraWeb will use IWShowMessage.html

NewWindow [Public]

Declaration: procedure NewWindow(const AURL: string); overload;

Description: Creates a new popup window when executed in the browser context.

Parameters:

• AURL (string): contains the address (URL) to the content of the new popup window

NewWindow [Public]

Declaration: procedure NewWindow(const AURL: string; const AName: string; const AWidth: Integer = -1; const AHeight: Integer = -1); overload;

Description: Creates a new popup window when executed in the browser context.

Parameters:

• AURL (string): contains the address (URL) to the content of the new popup window
• AName (string): Name of the window
• AWidth (Integer): Width in pixels of the new window
• AHeight (Integer): Height in pixels of the new window

NewWindow [Public]

Declaration: procedure NewWindow(const AURL: string; const AName: string; const AWidth: Integer; const AHeight: Integer; AOptions: TIWWindowOptions

Description: Creates a new popup window when executed in the browser contex.

Parameters:

• AURL (string): contains the address (URL) to the content of the new popup window
• AName (string): Name of the window
• AWidth (Integer): Width in pixels of the new window
• AHeight (Integer): Height in pixels of the new window
• AOptions (TIWWindowOptions)

  TIWWindowOption = (woButtons, woStatusBar, woMenuBar, woScrollBars, 
					  woResizable, woCopyHistory, woFullScreen, woDetectBlock);
  
  

woButtons: Whether or not to add directory buttons.

woStatusBar: Whether or not to add a status bar.

woMenuBar: Whether or not to display the menu bar.

woScrollBars: Whether or not to display scroll bars.

woResizable: Whether or not the window is resizable.

woCopyHistory: Whether or not to copy the old browser window's history list to the new window.

woFullScreen: Whether or not to display the browser in full-screen mode.

woDetectBlock: Whether or not to use the popup blocker alert. If set, the message may be customized setting the RSPopupBlocked variable in IWResourceStrings unit.

Please note that not all browsers work with every option in the same way.

Terminate [Public]

Declaration: procedure Terminate; overload;

Description: This method terminates the user session. In general, this method is used to terminate the user session after response content has been provided, e.g. inside a content handler Execute() method. If no content is provided, IntraWeb will terminate the session and return code 404 (not found).

Terminate [Public]

Declaration: procedure Terminate(const AMsg: string); overload;

Description: This method terminates the user session and shows the message in the AMsg parameter.

Parameters:

• AMsg (string): AMsg contains a string that will be shown after session termination.

Notes: "AMsg" parameter accepts an HTML fragment which will be rendered inside page's BODY tag.

TerminateAndRedirect [Public]

Declaration: procedure TerminateAndRedirect(const aURL: string);

Description: This method terminates the user session and redirects the user to the URL in the aURL parameter.

Parameters:

• aURL (string): URL used in redirection.

RegisterCallBack [Public]

Declaration: procedure RegisterCallBack(AName: string; ACallbackFunction: TIWCallBackFunction);

Description: Registers a new callback method. If the callback method with the same name already exists, it will be replaced by the new ACallbackFunction provided.

Parameters:

• AName (string): Name of the callback method. This name is used by IntraWeb JavaScript libraries when creating an Async request to the IntraWeb application.
• ACallbackFunction (TIWCallBackFunction): A TIWCallBackFunction reference. This function will be called when PerformCallBack() method executes.

PerformCallBack [Public]

Declaration: procedure PerformCallBack(const AName: string);

Description: Executes a callback method in response to a Async/AJAX request.

Parameters:

• AName (string): Name of the Callback function to be executed, previously registered using RegisterCallback() method.

GetInternalFileURL [Public]

Declaration: function GetInternalFileURL(const AFilename: string): string;

Description: Used internally by rendering methods to get the URL to a given internal file. Internal files are resources (RCDATA) served as normal files, e.g.: IntraWeb's JavaScript library files, images of navigator buttons, etc. These files are kept in a TIWServerInternalFiles instance.

Parameters:

• AFilename (string): The name of the internal file.

Result: A string containing the URL for the internal file.

GetExternalFileURL [Public]

Declaration: function GetExternalFileURL(const AFilename: string): string;

Description:Used internally by rendering methods to get the URL to a given external file. External files are files in IntraWeb's root folder and subfolders (wwwroot).

Parameters:

• AFilename (string): The name of the file.

Result: A string containing the URL for the external file.

Lock [Public]

Declaration: procedure Lock();

Description: Used internally by IntraWeb methods to lock the session. Lock() uses a TCriticalSection object to prevent concurrent access to protected sections of code.

Unlock [Public]

Declaration: procedure Unlock();

Description: Used internally by IntraWeb methods to unlock the session previously locked.

TryLock [Public]

Declaration: function TryLock() : Boolean;

Description: Also locks a protected code section, protecting it from access from other threads. It does not wait for other threads to leave the protected code section.

Result: True if the lock as acquired.

ShowForm [Public]

Declaration: function ShowForm(AFormClass: TComponentClass; AReleaseActiveForm: Boolean = False; AUseExistingInstance: Boolean = False): TComponent;

Description: Creates and Shows a form, or simply shows an existing form. The form becomes the active form of the session. Returns the instance of the form. If AUseExistingInstance is set to True, any existing instance of the same class will be made the active form and displayed. If set to False, a new instance will be created. If AReleaseActiveForm is set to True, the previous active form (i.e. the current active form at the time of the method call) will be released.

Parameters:

• AFormClass (TComponentClass): Class of the form to be created and/or displayed
• AReleaseActiveForm (Boolean): If set the current active form at the time of the method call will be released
• AUseExistingInstance (Boolean): If is set, any existing instance of the same class will be made the active form and displayed, otherwise a new instance will be created

Result: The instance of the form that was created and/or made visible.

Properties

AppUrlBase: string; [Public, Read only]

Use this property to read the master root URL for the application, ie, the relative URL starting from the root website. The property value does not include the host name neither the port. Also, this property is not affected by ServerController.AllowMultipleSessionsPerUser property settings.

May contain one of these values:

• Stand Alone server: "/" (Always contains this exact value)
• ISAPI: "/path/myapp.dll" (This is an example. Depends on web server's path and application name)

SessionUrlBase: string; [Public, Read only]

Use this property to read the relative URL for the application containing AppID (session identifier string) information when ServerController.AllowMultipleSessionsPerUser is TRUE. If ServerController.AllowMultipleSessionsPerUser is false, this property value equals AppUrlBase property.

May contain one of these values:

A) ServerController.AllowMultipleSessionsPerUser = True

• Stand Alone server: "/06oicl90kiigi11327pcr0k33y73/" (This is an example. Depends on AppID value)
• ISAPI: "/path/myapp.dll/06oicl90kiigi11327pcr0k33y73/" (This is an example. Depends on web server path, application name and AppID value)

B) ServerController.AllowMultipleSessionsPerUser = False

• Stand Alone server: "/" (Always contains this exact value)
• ISAPI: "/path/myapp.dll" (This is an example. Depends on web server's path and application name)

InternalUrlBase: string; [Public, Read only]

Internal URL space with $ (exec) command. This is used by internal IntraWeb commands. This property is not affected by ServerController.AllowMultipleSessionsPerUser property settings.

May contain one of these values:

• Stand Alone server: "/$/" (Always contains this exact value)
• ISAPI: "/path/myapp.dll/$/" (This is an example. Depends on web server's path and application name)

SessionInternalUrlBase: string; [Public, Read only]

Internal Url base but also contains AppID (Session identifier string) when ServerController.AllowMultipleSessionsPerUser is TRUE. If ServerController.AllowMultipleSessionsPerUser is false, this property value equals InternalUrlBase property.

May contain one of these values:

A) ServerController.AllowMultipleSessionsPerUser = True

• Stand Alone server: "/$/06oicl90kiigi11327pcr0k33y73/" (This is an example. Depends on AppID value)
• ISAPI: "/path/myapp.dll/$/06oicl90kiigi11327pcr0k33y73/" (This is an example. Depends on web server path, application name and AppID value)

B) ServerController.AllowMultipleSessionsPerUser = False

• Stand Alone server: "/$/" (Always contains this exact value)
• ISAPI: "/path/myapp.dll/$/" (This is an example. Depends on web server's path and application name)

ApplicationURL: string; [Public, Read only]

Use this property to read the current Application URL. If AllowMultipleUserSessions is True, it includes the AppID (Session identifier string), otherwise it is the same as the AppURLBase property.

CallBackProcessing: Boolean; [Public, Read only]

When this property is True, it indicates that the appplication is processing a callback, i.e., an Ajax or Async call.

CallBackResponse: TIWCallBackResponse; [Public, Read only]

This property gives you access to the CallBackResponse object. For more information, read Using the Callback response object.

ApplicationPath: string; [Public, Read only]

Use this property to read the full application path.

ActiveForm: TComponent; [Public, Read only]

This property gives access to the IW form that is being shown to the user. When using this property to check any property or calling any method, you always need to typecast it. Ex: TfrmCustomerForm(WebApplication.ActiveForm).CustomerID.

ActiveFormCount: Integer; [Public, Read only]

Use this property to read the number of IW forms you currently have on memory, i.e., a form that you have created but not yet destroyed.

AppID: string; [Public, Read only]

This is the session identifier field, a unique string used to identify each session. Use this property to read the AppID for the current user session. AppID is used in URL construction when ServerController.AllowMultipleSessionsPerUser is True, and also in HTTP Cookie path field.

AuthPassword: string; [Public, Read only]

Use this property to read the user password when you use the built-in IW Authorization components.

AuthUser: string; [Public, Read only]

Use this property to read the user name when you use the built-in IW Authorization components.

Browser: TBrowser; [Public, Read only]

Use this property to have access to the Browser the the user is using to access your application. See Browser Support section on the Server Controller advanced topics.

Data: TObject; [Public, Read/Write]

This is a general use property that can be used to store information relative to the user session. IntraWeb automatically generates code to create and store aTIWUserSession instance in this property, but you can add your own custom class, like a TList for Data Modules or any kind of structure/information your application needs. See User Session Overview for more information.

DesignMode: Boolean; [Public, Read only]

When true indicates that the IWApplication is in Design time.

ExecAction: string; [Public, Read only]

[property description]

FormAction: string; [Public, Read only]

[property description]

FormCount: integer; [Public, Read only]

Number of forms in IWApplication's internal Form list.

FormWidth: Integer; [Public, Read/Write]

Use this property to read the width of the working area of the user browser.

FormHeight: Integer; [Public, Read/Write]

Use this property to read the height of the working area of the user browser.

FileList: THttpFileList; [Public, Read only]

Contains a list of files submited (uploaded).

Forms[AIndex: Integer]: TComponent; [Public, Read only]

Gives access to IWApplication's internal Form list.

ActiveForms[AIndex: Integer]: TComponent; [Public, Read only]

Gives access to IWApplication's internal ActiveForm list.

IP: string; [Public, Read only]

Use this property to read the IP from the client accessing your application.

IsCallBack: Boolean; [Public, Read/Write]

When true, this property indicates that IWApplication is processing a callback, i.e., an Ajax or Async request.

LastAccess: TDateTime; [Public, Read only]

Contains the date and time of the last session request processed by IW application.

MasterTemplate: string; [Public, Read/Write]

[property description]

ActiveMasterTemplate: string; [Public, Read only]

[property description]

SecureMode: Boolean; [Public, Read only]

When true, the request is using a sercure mode connection (SSL).

ReferringURL: string; [Public, Read only]

Use this property to read the URL that originated the current request.

Response: THttpReply; [Public, Read only]

Use this property to have access to the Response object.

Request: THttpRequest; [Public, Read only]

Use this property to have access to the Request object.

RunParams: TStrings; [Public, Read only]

Use this property to have access to the URL params (ex: /?CustomerID=1000&SaleId=12993) used to activate the current user session. As the RunParams property is a TStrings inherited object, you can use all TStrings method to manage the URL params.

Terminated: boolean; [Public, Read only]

When true indicates that the user session has been terminated.

SessionTimeOut: Integer; [Public, Read/Write]

Use this property to get or set the current Session timeout value (in minutes). Same value as the Server Controller session timeout value.

SessionTimeStamp: TDateTime; [Public, Read only]

Use this property to read the date/time the current session has started. This value refers to the server time.

TrackID: Cardinal; [Public, Read only]

Sequence number of submitted forms. TrackID is initially set to 0 (zero) and is incremented by one at each form submission.

TaggedSessionName: read; [Public, Read/Write]

[property description]

MappedURL: string; [Public, Read/Write]

Used to get ExecAction

Permissions: TIWPermissions; [Public, Read/Write]

[property description]

CacheFiles: TStrings; [Public, Read only]

TStringList containing all IWApplication cache files. These files were added to IW cache using the ctSession cache type. During session destruction all files in CacheFiles list are deleted.

UserCacheUrlBase: string; [Public, Read only]

URL base of user cache. This property is deprecated. The new TIWAppCache class should be used instead.

UserCacheDir: string; [Public, Read only]

Directory of user cache. This property is deprecated. The new TIWAppCache class should be used instead.

See also

Working with WebApplication

TIWAppCache class reference