CommuniGate Pro: Web Applications

Regular HTTP servers are stateless processors: a user's browser may send several sequential requests, but the HTTP server does not keep any information about the browser or the client between the requests. Each request is processed individually.

The Web Application Server allows users to "log in", providing a name of some CommuniGate Pro Account and the account password. For each successful login, a Session is started. The session keeps the information about user actions and requests, so all HTTP requests sent to the same session can share and use the same set of session data.

To maintain a session, all session requests have URLs in the following form:

http://hostname:serverport/Session/sessionID/sessionRequest

where the sessionID string identifies the session, and the sessionRequest is the name of the file to retrieve or the application component to run.

The Web Application Sessions have time-out counters. If no HTTP request has been sent to a session during the configurable time-out interval, the Session is closed. The session user can close the session by sending a request for the special Bye page.

The Server WebUser Interface implements Skins. Each Skin is a set of files that define how the information is presented to users. Skins files include:

WSSP files used to build "web pages" (HTML, WML, etc.) and format the page data.
static service files - graphic elements, style sheets, etc.
Language files containing various static text strings (messages, page and button titles, tags, etc.) referenced from WSSP files.

The CommuniGate Pro software comes with one Unnamed Stock Skin, providing the very basic and simple HTML and WML interface. It also comes with some Named Stock Skins that provide more visually rich interfaces. This Stock Skins are stored in the application directory, they are parts of the software package, and they should not be modified by server administrators.

CommuniGate Pro installations can also use Unnamed and Named custom Skins. Custom Skins can be created as Server-wide Skins. These custom Skins are available to all users. Each CommuniGate Pro Domain can also have its own set of custom Skins, available only to the users of that Domain.

When a user connects to the WebUser Interface service (the HTTP User port), the hostname string specified in a stateless request URL is used to find the CommuniGate Pro Domain. When the Domain is found, its Default Account WebUser Preferences are retrieved and the SkinName (Layout) and Language Settings are used.

The SkinName Setting specified the name of the Skin to use (if that Setting is empty, the Unnamed Skin is used).

If the Skin with the specified Name is not found in the set of the Domain Skins, the Server-wide Skin sets are checked. If the Skin with the specified name is still not found, the Stock Skin with this name is used. If the Named Stock Skin is not found either, the Unnamed Stock Skin is used.

Since Domains can have their own Skin sets, the same request sent to different Domains can display different pages: the Default WebUser Preferences can specified different Skin Names in different Domains, and even if the Preferences are the same, different Skins with the same name can exist in different Domains.

Stateless requests can use any Skin available for the addressed Domain. To use an alternative Skin, a Stateless HTTP request should specify the Skin name using the Skin request parameter.

The Language Setting retrieved from the Domain effective Default Account WebUser Preferences specifies the language to use on the stateless page. To use an alternative language, a Stateless HTTP request should specify the language name using the Language request parameter.

Session-based HTTP requests do not use the hostname string specified in the URL. Instead, when a user logs in, and a Web Application session is created for the specified CommuniGate Pro Account, the effective Account WebUser preferences are retrieved. Those preferences contain the name of the Skin to use (an empty value specifies an Unnamed Skin). The Skin with the specified name is selected from the Skin set of the Account Domain (note that the Domain specified with the request URL can be different).
If the Account Domain does not have the specified Skin, the Server-wide Skin is used.

Session-based HTTP requests use the Language specified with the Account WebUser Preferences.

WAP/WML Skins

The HTTP module checks the content of the Accept request header field. If this field contains a wml substring, the module assumes that the request comes from a WML browser.

Requests coming from WML browsers are processed using WML Skins. For Stateless requests the name of the Skin to use is taken from the WAP/WML Layout parameter of the Default WebUser Preferences for the addressed Domain. When a user logs in using a WML browser, the name of the Session Skin to use is taken from the WAP/WML Layout parameter of the WebUser Preferences for the user Account.

All Skins with names starting with letters WML are considered to be WML Skins. These Skins appear in the list of available Skins for the WAP/WML Layout parameters, and these Skins are removed from the list of available Skins for the regular Layout parameters.

cHTML (I-Mode) Skins

The HTTP module checks the content of the User-Agent request header field.
If this field contains a DoCoMo substring, the module assumes that the request comes from a Japanese I-Mode browser.
If this field contains a portalmmm substring, the module assumes that the request comes from a European I-Mode browser.

I-Mode requests are processed with special I-Mode Skins in the same way as WML requests are processed with WML Skins. The special I-Mode/cHTML WebUser Preferences parameter is used to specify the name of the I-Mode Skin to use.

All Skins with names starting with letters IMode are considered to be cHTML Skins. These Skins appear in the list of available Skins for the I-Mode/cHTML Layout parameters, and these Skins are removed from the list of available Skins for the regular Layout parameters.

For all pages retrieved for Japanese cHTML browsers the charset is set to Shift-JIS, and all pages are converted into that charset.
For all pages retrieved for European cHTML browsers the charset is set to windows-1252, and all pages are converted into that charset.

When a WebUser Interface request is processed, the Server needs to retrieve certain files from the selected Skin. If the requested file is not found in the selected Skin, and the selected Skin is a Domain Skin, the file is retrieved from the Server-wide Skin with the same name. If the requested file is not found in the Server-wide Skin, the Stock Skin with the same name is checked. If the file is still not found, and the selected Skin is a Named Skin, then unnamed Server-wide and unnamed Stock Skins are checked.

Initially, when no Domain has any custom Skin, and the Server-wide Skins are empty, all Domains can use the Stock Skins only. The Unnamed Skin is selected by default.
By uploading files into the Server-wide Unnamed Skin, the Server Administrator can "shadow" the Unnamed Stock Skin files, and this can change the application look and feel for all Domains.
By uploading files into the Unnamed Skin of some CommuniGate Pro Domain, the Server or Domain Administrator can "shadow" the Stock Skin and Server-wide Unnamed Skin files and change the look and feel for that particular Domain.

This hierarchy allows Server and Domain Administrators to use new Skins that are designed "from scratch", or to develop small Skin variation, re-using the already existing Skins.

The Dynamic Cluster installations have two sets of the Server-wide Skins - one set is used for local Server Domains, while the other, Cluster set is used for all Shared Domains in the Cluster. Modifications of these Cluster-wide Skins, as well as modifications of any Skin in any Shared Domain are automatically distributed to all Cluster Members.

Each Skin can have a Text Dataset - the strings.data text file. This "default language" file contains a dictionary. The WSSP script pages can use various commands to retrieve data from this Text Dataset dictionary.

A Skin can contain additional, localized Text Dataset files - language.data files, where language is the language name (french.data, japanese.data, etc.). If a non-default language is selected, the Text Dataset from the specified language file is used.

When the selected Text Dataset of the selected Skin does not contain the requested data, the same language Text Datasets are checked in all Skin "parents" (as specified above). If the requested data is still not found, the "default language" Text Dataset is used.

Use the UTF-8 character set to place non-ASCII symbols strings into a Text Dataset file. Check the http://www.unicode.org site to learn more about Unicode and the UTF-8 charset.

You may want to break one Text Dataset file into several files. You can place several strings.subname.data files into a Skin. These files are read when the strings.data file is read. The file content (a dictionary) is added to the Text Dataset dictionary as the subname key value.
The language.subname.data files are processed in the same way, extending the localized Text Datasets.

When a URL specifies a file with any file name extension other than .wssp, the Web Application module retrieves this file from the selected Skin, places it into the internal Skin Cache, and returns that file to the client browser via the HTTP module connection.

The specified file names are always converted into the lowercase letters.

When the Web Application module receives a request for the same file, it is retrieved from the Skin Cache.

If the file has been requested using a Session-based URL, the session time-out counter is reset. This can be used to create a frame in the client browser window, and make that frame periodically retrieve some file using the session URL. As a result, this session inactivity timer can be reset to keep the session alive as long as this frame is displayed in the user's browser.

System and Domain administrators can upload custom files into server-wide and Domain Skins to modify the Web Application look and feel.
For example, the Stock Skin uses the Logo.gif file for most of its pages. By uploading a custom Logo.gif file to a server-wide Unnamed Skin you can change the look of the Web Application pages even without creating and uploading custom page (WSSP) files.

To include a file reference to into a .wssp page retrieved with a Stateless request, use the %%filesRef%% prefix in the .wssp code:

... href="%%filesRef%%filename.extension" ...

See the Code Components for Stateless Requests section for more details.

Sessions can use Named Skins, and the session-based pages usually need to refer to regular files in the same Skin. References in the "session realm" (href="filename.extension" or href="/Session/sessionID/filename.extension") work, but they do not allow client browsers to cache these files between sessions, since each session has its own sessionID, and file URLs are different for each session. To allow client browsers to cache regular files, use the %%SESSION(filesRef)%% prefix for file URLs:

... href="%%SESSION(filesRef)%%/filename.extension" ...

See the Session Dataset description for more details.

When a URL specifies a resource with the .wssp file name extension, the Web Application module retrieves the specified WSSP file from the Skin, and Compiles it into some internal code. The module then runs the Web Application code associated with the file name. This code produces a dataset with various string, array, and dictionary data. Then the module runs the WSSP internal (compiled) code to produce an HTML page using this dataset, and returns the resulting HTML page to the browser using the HTTP module connection.

The specified resource names are always converted into the lowercase letters.

The WSSP Scripting section explains the WSSP file format. System and Domain administrators can create custom WSSP files and upload them to the server-wide and Domain Skins to modify the Web Application look and feel.

The section below lists the available Web Application code components, defining the set of WSSP pages that this version of CommuniGate Pro server can generate. It specifies how each component processes the form parameters sent to it, and what data is included into the dataset it generates.

You can create and manage Skins using the WebAdmin Interface, CLI/API, or any client/protocol (such as FTP) that can access the Account File Storage.

WebAdmin Editor

The WebAdmin Interface provides Skin Editor pages to manage Server-wide, Cluster-wide, and Domain Skins.

To manage the Server-wide and Cluster-wide Skins, open the Domains realm of the WebAdmin Interface, and click the Skins link.

To manage the Domain Skins, open that Domain page in the Domains realm of the WebAdmin Interface, and click the Skins link. The Domain Administrator should have the CanModifySkins Access Right to be able to create and modify the Domain Skins.

When the Domain Skins Editor page is opened, and there is no Unnamed Skin for the Domain, the page contains the Create Unnamed Skin button. Click this button to create the Unnamed Skin for this Domain.

The Skin Editor page contains the list of all files "visible" in this Skin: it lists files directly uploaded to this particular Skin, as well as all files uploaded to the Skins used as the "default files" source for this Skin:

	Name	Size	Modified

	Help.gif	155	25-Sep-06
default	addressbook.wssi	1143	23-Sep-06
default	alerts.wssp	1727	26-Sep-07
default	answeredletter.gif	890	27-Feb-06
default	attachedFile.gif	1147	27-Feb-07
...
default	mailbox.wssp	5806	28-Sep-06
	mailboxes.wssp	3452	02-Oct-06
...
default	strings.data	28K	27-Oct-06
default	german.data	31K	28-Oct-06
...
default	website.wssp	592	28-Sep-06
default	websitebody.wssi	2648	28-Sep-06

Files directly uploaded to the Skin have a checkbox in the Marker column. Files from the other skins "visible" in this Skin have the word default in that column.

You can download any of the Skin files by clicking the file name.

You can upload a file to the Skin by clicking the Browse button and selecting a file on your workstation, then clicking the Upload button.

You can delete any of the files uploaded to the Skin by selecting the checkboxes and clicking the Delete Marked button.

If you are uploading a .wssp or a .wssi file, the Editor tries to compile that WSSP file first.
If you are uploading a .wcgp or a .wcgi file, the Editor tries to compile that CG/PL file first.
If you are uploading a .data file, the Editor tries to parse it as a dictionary file first.
If the compiler or the parser detects an error, the file is not uploaded, and the file content is displayed on the Editor page, with the red <--ERROR--> marker indicating the location of the error.

When you upload a file to any Skin, that Skin cache is automatically cleared. If you upload a file to a Shared Domain Skin or to a Cluster-wide Skin, the update automatically propagates to all Cluster Members.

You can upload a set of files by uploading a TAR-archive (a file with .tar name extension). For example, when you have a TAR-archive with a predesigned Skin you can open the Skin you want to modify (the Server-wide Unnamed Skin or Domain-wide Unnamed Skin or some Named Skin), and upload the .tar file. The Server will unpack the archive and store each file individually, as if they were uploaded one-by-one.

The Editor page for the Unnamed Skin contains the list of all Named Skins:

To create a Named Skin, enter its name, and click the Create button.

To remove Named Skins, use the checkboxes to select the Skins, and then click Remove Marked button. Only empty Skins (Skins without any files) can be removed.

To remove the Unnamed Skin, remove all its files and all Named Skins, and then click Remove Unnamed Skin button.

To open a Skin, click its name. The Editor will display the Skin Name, and it will provide the UP link to the Unnamed Skin page.

The Named Skin Editor allows you to rename the Skin by entering a new Skin Name and clicking the Rename Skin button.

CLI/API

The Command Line Interface/API can be used to manage Skins. See the Web Skins Administration section for the details.

Virtual File Storage Area

The Skins can be modified using FTP and HTTP clients, CG/PL applications, and any other method that provides access to the Account File Storage.
Special $DomainSkins, $ServerSkins, and $ClusterSkins directories provide access to the Domain and Server/Cluster-wide Skins.

The CommuniGate Pro Web Application module processes a request for a WSSP file by calling a code component that produces a dataset - a dictionary containing text string keys and values, associated with those keys. Values can be text strings, arrays of values, or dictionaries.

For example, when a Domain default page is requested, the code component called and it produces a dictionary that contains keys such as canAutoSignup, hasMailLists, hasCertificate.

The Web Application module then uses the script code from a WSSP file to convert this data into into an HTML or other markup language page.

This section lists the available CommuniGate Pro code components, specifies when those components are called, explains how the code components process the <FORM> parameters, and specifies the content of the dataset produced by each code component.

The Web Application module checks the Skin HTTP parameter for all Stateless requests. If this parameter exists, the module tries to open a Named Skin with the specified name, otherwise the Unnamed Skin (for the addressed Domain) is used.

The Web Application module checks the Language HTTP parameter for all Stateless requests. If this parameter exists, the module uses it to selected a non-default Text DataSet for the selected Skin.

The Web Application module places certain data into datasets produced with all Stateless Requests code components. The following list specifies these "generic" dataset elements that can be used with all Stateless WSSP pages:

filesRef: This element value is a string that can be used to form a URL that refers to a file (image, style sheet, data, etc.) from the same Skin in the same Domain. The <img src="%%filesRef%%Logo.jpeg"> HTML element will display the Logo.jpg file "visible" in the current Skin.
serverName: This element value is a string with this CommuniGate Pro server name (its Main Domain Name).
skinName: This optional element value is the current Skin name string.
language: If a non-default language was selected, this optional element contains a string - the selected language name.
domainName: This element value is a string containing the CommuniGate Pro Domain name. This element exists only if the Server has succeeded to direct the Stateless Request to one of the server Domains.
charset: This element value is the value of the charset element from the Domain Skin Text Dataset. Individual code components may specify other values for the charset element (see below).
secureChannel: This element exists and has the YES string value if the request has been received via a secure (HTTPS) connection.
isWML: This element exists and has the YES string value if the request has been received from a WML browser.

The following sections specify the Stateless URLs, the name of the code component called, the actions taken by the component, the dataset produced with that component, and the name of the WSSP file used to produce the HTTP response.

URLs: /, /default.html

these URLs are used to process Login operations.

Actions

If the HTTP request has the username and password parameters, the code tries to authenticate the client using these parameter values. If the supplied credentials are correct, a new WebUser Session is created, and a request for the "entry page" is sent to the Session. This request usually returns an HTML "jump page" that is sent back to the user browser. It forces the browser to enter the "Session realm".

If the request has the DisableIPWatch parameter, the "Fixed IP Address" security feature will be disabled for this session, even if the Account WebUser preferences enable it.

If the request has the DisableUseCookie parameter, the "Use Cookies" security feature will be disabled for this session, even if the Account WebUser preferences enable it.

If the request has SessionSkin parameter with a string value not equal to *, the session is opened using the Skin specified with this parameter. The Skin is searched in the Domain of the logged-in user (which can be different than the Domain used to display the Login page).

Result Dataset

If username or password parameter has not been specified, or a WebUser Session could not be created, the component generates the following dataset:

autoSignup

this element (with the string YES as the value) is added to the dataset if the addressed Domain provides the Auto-Signup operation.

clientAddress

this string element contains the IP address of the user browser.

errorCode

this element is added to the dataset if the Login operation has failed. The value is a string with the error code.

forgotPassword

this element (with the string YES as the value) is added to the dataset if the errorCode value is "Incorrect Password" or "Unknown Account".

hasCertificate

this element (with the string YES as the value) is added to the dataset if the addressed Domain has a custom Certificate.

hasDirectory

this element (with the string YES as the value) is added to the dataset if the default Skin for the addressed Domain has an array element GuestDirectoryFields in its Text Dataset, and that array is not empty.

hasLists

this element (with the string YES as the value) is added to the dataset if the addressed Domain has at least one Mailing List. This element is always added if the addressed Domain is a Shared Domain.

skinNames

this element contains an array - the list of skin names available in the addressed Domain.

loginName

this string element is added to the dataset if the user has tried to log in, but failed. The value specified in the username parameter becomes the loginName element value.

restoreSessionPage

this string element is added to the dataset if the user has been disconnected. It contains the name of the interrupted request session page name.
To allow an interrupted request to resume, the restoreSessionPage HTTP parameter with this element value should be included into the HTTP request generated by this page.

restoreCharset

this string element is added to the dataset if the user has been disconnected. It contains the charset used in the interrupted request.
To allow an interrupted request to resume, the restoreCharset HTTP parameter with this element value should be included into the HTTP request generated by this page.

restoreParameters

this array element is added to the dataset if the user has been disconnected. Each array element is a dictionary with the following elements:

name: name of an interrupted request parameter.
value: encoded value of an interrupted request parameter.

To allow an interrupted request to resume, parameters with these names and values should be included into the HTTP request generated by this page.

WSSP page

the login.wssp page is used to generate the HTTP response.

If login operation was successful, the HTTP Redirect response is returned, with the Redirect URL pointing to the StartPage wssp page within a newly created Session. The StartPage is specified as the StartPage Skin string.

If login operation was successful, but the request contained the restoreSessionPage parameter, the resume.wssp page is displayed (as a Stateless one).

The Result Dataset for this page contains:

restoreParameters: see description above.
sessionID: the SessionID for the newly created session (the same value as the value of SESSION(ID) function that can be used on session wssp pages).
jumpPage: the wssp page to open if the user wants to resume the interrupted operation (it includes optional parameters).

URL: /RecoveryPassword.wssp

this URL is used to process Password Recovery operations.

Actions

If the HTTP request has the username and Send parameters, the component tries to find the specified Account, retrieves the Account password, and the RecoverPassword Account Setting. If the password can be decrypted and the RecoverPassword is specified, an E-mail message containing the password is composed and sent to the RecoverPassword E-mail address.

Result Dataset

errorCode: this element is added to the dataset if the Password Recovery operation has failed. The value is a string with the error code.
messageCode: this element is added to the dataset if the Password Recovery operation has succeeded. The value is the PasswordSent string.

WSSP page

the recoverypassword.wssp page is used to generate the HTTP response.

URL: /Signup.wssp

this URL is used to process Auto-Signup operations.

Actions

If the HTTP request has the username, password1, password2, and the realName parameters, the component tries to create the specified Account. Before it tries to create an Account, it checks if the password1 and password2 strings are the same. If a new Account is created, its UseAppPassword setting is set to YES, the Password and RealName settings are set to the specified values. If the HTTP request contains a non-empty ForgotPassword parameter, it is used as the RecoverPassword Account Setting.

The component checks if the request contains one or more PublicInfo string parameters. The value of the parameter must be one of the Public Info Attributes specified in the Directory Integration settings. The component than checks if there is a non-empty request parameter with this name, and adds the parameter value to the initial Account settings.
Example: to provide a City field on the Auto-Signup page, include the <INPUT type="hidden" name="PublicInfo" value="City"> control and the <INPUT type="text" name="City" value="" size=30 maxlength=255> control into the Signup.wssp HTML code.

If an Account has been created, a new WebUser Session is created, and a request for the "entry page" is sent to the Session (see above).

Result Dataset

If username, password1, password2, or the realName parameter has not been specified in the HTTP request, or a new Account could not be created, the component generates the following dataset:

errorCode: this element is added to the dataset if the Auto-Signup operation has failed. The value is a string with the error code.
userName: this element is added to the dataset if HTTP request contained a non-empty userName parameter. The element value is the value of the parameter.
realName: this element is added to the dataset if HTTP request contained a non-empty realName parameter. The element value is the value of the parameter.
recoverPassword: this element is added to the dataset if HTTP request contained a non-empty recoverPassword parameter. The element value is the value of the parameter.

WSSP page

the signup.wssp page is used to generate the HTTP response.

URL: /List/, /List/default.html

this URL is used to retrieve the list of the browsable Domain Mailing Lists.

Actions

The HTTP request parameters are not processed.

Result Dataset

The component generates the following dataset:

errorCode

this element is added to the dataset if the list retrieval operation has failed. The value is a string with the error code.

lists

this element contains an array of mailing list descriptors. Each descriptor is a dictionary with the following keys and values:

name: a string with the mailing list name.
realName: the mailing list "description" string.
browse: the string describing the mailing list archive browsing policies. The string value can be anyone or subscribers.

WSSP page

the listlist.wssp page is used to generate the HTTP response.

URL: /List/listname/, /List/listname/List.html

this URL is used to retrieve a portion of the mailing list records for the listname Mailing List.

The code component actually uses the generic Mailbox Code Component.

Actions

The component checks if the HTTP request contains the NextMessage parameter with a numeric value. If it exists, the value is interpreted as the unique message ID (UID) in the list archive Mailbox, and the component tries to find this message in the selected Mailbox "view", and tries to find the next message in the view.

The component checks if the HTTP request contains the PrevMessage parameter with a numeric value. If it exists, the value is interpreted as the unique message ID in the list archive Mailbox, and the component tries to find this message in the selected Mailbox "view", and tries to find the previous message in the view.

If the next or previous message is found, its UID is added to the dataset (see below) and the generic Mailbox component is not used for processing.

If no next/previous message is found, the generic Mailbox component is used to process the HTTP request parameters and to compose the resulting dataset.

Result Dataset

listName: a string with the Mailing List name.

If a next or previous message is found:

messageJump: a string with the found message UID.

If a next or previous message was not requested in the HTTP request parameters or it was not found:

realName: the Mailing List Description string
charset: the Mailing List Preferred charset string

the generic Mailbox code component is used to generate the rest of the resulting dataset.

WSSP page

the listmailbox.wssp page is used to generate the HTTP response.

URL: /List/listname/Message/uid.html

this URL is used to retrieve the message with uid unique ID from the listname mailing list archive.

The code component actually uses the generic Message Code Component.

Actions

The generic Message component is used to process the HTTP request parameters and to compose the resulting dataset.

Result Dataset

listName: a string with the Mailing List name.
nextMsg: this element is added if there is a next message in the archive Mailbox view. The element value is a string with the next message UID.
prevMsg: this element is added if there is a previous message in the archive Mailbox view. The element value is a string with the previous message UID.

The generic Message code component is used to generate the rest of the resulting dataset.

WSSP page

the listmessage.wssp page is used to generate the HTTP response.

The WSSP mechanism is used to generate HTTP response body for error responses. The following table lists the HTTP error codes, the situations when this error code is generated, and the WSSP file used to product the HTTP error response body.

Code	Error conditions	WSSP file used
301	the requested resource has been moved	`moved.wssp`
404	the requested resource does not exist	`notfound.wssp`
401	the requested page requires the HTTP Authorization (request header)	`unauthorized.wssp`
401	the credentials in the HTTP Authorization request header are incorrect	`denied.wssp`
500	generic system error	`failure.wssp`
501	generic system error	`error.wssp`

These WSSP pages are processed using datasets generated for all Stateless requests, with the following additional elements:

errorCode: this element is added to the dataset if there is an error code to be reported to the user.
hostName: this element is added to the dataset if the HTTP request contained the Host: field. The element value is that request field parameter.

The disconnected.wssp page is used when an HTTP request was sent to a WebUser Session, but the session has not been found. The page is processed using a dataset generated for all Stateless requests.

When a new WebUser Session is created, the Skin specified in the Account WebUser Preferences is opened and is used as the "Session Skin". The string StartPage is retrieved from that Skin Text Dataset, and a jump page is composed and sent to the user browser. The jump page redirects the user browser into the "Session Realm", to the page specified with the StartPage string.

HTTP requests to the "Session realm" (requests with URLs started with /Session/) are processed as Session Requests. The second component of the Session Request URL is a unique Session ID, the HTTP module uses it to find the WebUser session.

If the specified session is not found, or the Session has the Fixed Network Address option set, and the HTTP request did not come from the same IP address as the Login request that started the session, the disconnected.wssp page is displayed (see above).

After the Session is found, the Web Application module processes the rest of the request URL as the "request inside this session realm". If the request URL specifies a regular file, that file is retrieved from the Session Skin, and it is sent back to the user browser.

For each .wssp request a code component is called. It processes the HTTP request parameters and generates a result dataset. Then the .wssp file is retrieved from the Skin, and it is used to compose the HTTP response.

If the result dataset does not contain the blockAlerts element, the Web Application module checks if there is a pending Alert for the session user. If one or several pending alerts are found, the Alerts code component is called, and the Alerts.wssp file is used to compose the HTTP response.

The Web Application module checks for certain HTTP request parameters and processes them for all .wssp page requests. The following list specifies these "generic" actions:

EmptyTrashNow: If the HTTP request contains this parameter, and the Mailbox or Mailbox alias with the name Trash can be opened with the "Can Delete" Mailbox Access Right, then the code component removes all messages from that Mailbox. If this operation fails, the error code is placed into the resulting dataset as the errorCode string element.
SMIMEUnlock: If the HTTP request contains this parameter and the session does not have an Active Private Key, and the encrypted Private Key exists in the Account Settings, and the HTTP request contains the SMIMEPassword parameter, the module tries to activate ("unlock") the Private Key using the supplied password. If the operation fails, the error code is placed into the resulting dataset as the SMIMEError string element.

The Web Application module places certain data into datasets produced with all Session Requests code components. The following list specifies these "generic" dataset elements that can be used with all Session WSSP pages:

messageText: This string element is added if the HTTP request contains the messageText parameter. The element value is the same as the HTTP parameter value.
messageCode: This string element is added if the HTTP request contains the messageCode parameter. The element value is the same as the HTTP parameter value.
secureChannel: This element exists and has the YES string value if the request has been received via a secure (HTTPS) connection.
isWML: This element exists and has the YES string value if the request has been received from a WML browser.
charset: This string element contains the Preferred Charset selected in the User Preferences, if the Use UTF8 mode is set to Never. Otherwise, this element contains the utf-8 string.
Note: it's just a default value, individual code components can specify different values for this dataset element.
SMIMEActive: This element exists and has the YES string value if the session has an unlocked (Active) SMIME Private Key.
SMIMEInactive: This element exists and has the YES string value if the session does not have an unlocked (Active) SMIME Private Key, but the user has the Private Key in the Account Settings, and the Key can be unlocked.
mailboxes: The list of all selectable Mailboxes visible to the user.

If a .wssp request specifies an unknown code component, but the .wssp file with the specified name can be retrieved from the Session Skin, that .wssp file is processed using the dataset with the "generic" elements only, and the result is sent back to the user browser.

Example: The Stock Skin uses Hello.wssp requests. There is no code component with this name, so a dataset with the generic values is composed, and the Hello.wssp file is used to process this dataset.

The following sections specify the names of existing code components (names for .wssp requests), the actions taken by these component, and the dataset produced with these components.

The code component results are processed using the .wssp files with the same names as the code component names.

Name: Mailboxes

Actions

If the HTTP request contains the Create parameter and the NewName parameter is a non-empty string, the component tries to create a Mailbox with the specified name. If this operation fails, the errorCode element with the error code text is added to the result dataset. If the Mailbox is created, the messageCode element with MailboxCreated string value is added to the result dataset, and the created Mailbox name is added to the list of subscribed Mailboxes, if the Show Subscribed Mailboxes option is selected in the Account WebUser Preferences.
If the request contains the newClass parameter, then the created Mailbox is set to the specified class.

If the HTTP request contains the Filter parameter, only the Mailboxes with names containing this parameter value are included into the list.

Result Dataset

The code component creates a list of all Account Mailboxes and Mailbox Aliases (if the Show All Account Mailboxes option is selected in the Account WebUser Preferences), or the list of all subscribed Mailboxes (if the Show Subscribed Mailboxes option is selected). If both options are selected, these two lists are merged into one.

filter

this string element contains the current value of the HTTP Filter parameter.

newName

this string element contains the current value of the HTTP NewName parameter.

mailboxClasses

this array elements contains strings - names of all supported Mailbox classes.

mailboxList

this element is an array with one dictionary-type element for each Mailbox in the composed Mailbox list. Each dictionary contains the following elements:

mailboxName: this string element contains the Mailbox name.
parent: this string element exists if the Mailbox is a submailbox of some other Mailbox. The string contains the name of that parent Mailbox.
nonSelectable: this string element with the value Yes is added if the Mailbox is not selectable. If it is added, none of the following elements is added to the dictionary.
isList: this element is added if the Mailbox is the main Mailbox (archive) for a Mailing List (this also means that there is a Mailing List with the same name).
nMessages: this string element contains the number of messages in the Mailbox. If the number cannot be retrieved, the element value is the ??? string.
nRecent: this string element contains the number of "Recent" messages in the Mailbox.
numUnread: this string element contains the number of "Unseen" messages in the Mailbox.
size: this string element contains the "rounded" size of the Mailbox.
mailboxClass: this optional string element contains the Mailbox class (for non-mail Mailboxes).
mailboxPage: this string element contains the name of the wssp page to be used to process this Mailbox class.

nSelected

this string element contains the number of elements in the mailboxList array.

trashSize

this string element is added only if the Account has the Trash Mailbox. It contains the Trash Mailbox size.

currentStorage

this string element contains the "rounded-up" total size of Account Mailboxes.

storageLimit

this string element contains the "rounded-up" Account total Mailbox size limit. If the Account does not have the total Mailbox size limit, this element contains the unlimited string.

Name: Mailbox

The HTTP request must contain the Mailbox parameter - the name of the Mailbox to be displayed.

Actions

For each Mailbox, the module creates a session object that contains the Mailbox view parameters. When the object is created, these parameters are initiated with the WebUser Preferences values.

The HTTP request Msg parameters are interpreted as "message set elements". A request can contain several parameters, and each parameter should have a numeric value - the Unique ID of a Mailbox message.

If the HTTP request contains the Forward or Redirect parameter and the RedirectAddresses parameter is not empty, a "message set" is composed using the Msg parameters, and the message set messages are forwarded or redirected to the specified addresses.
If the HTTP request contains the ListApprove parameter and the Mailbox is an "approval" or "requests" Mailbox for some mailing list, the request is processed as the Redirect request with the effective address being the mailing list address or the "subscription" request for that list.
If the operation has been successful, the messageCode element with the MessagesForwardedInfo or MessagesRedirectedInfo string value is added to the result dataset. Otherwise, the errorCode element with the operation error code string value is added to the result dataset.

If the HTTP request contains the Copy or Move parameter and the MailboxName parameter contains a name of some selectable Mailbox, a "message set" is composed using the Msg parameters, and the message set messages are copied to the specified Mailbox. If the Move parameter was specified, the message set messages are marked as Deleted, physically deleted, or moved to Trash - depending on the WebUser Preferences.
If the operation has been successful, the messageCode element with the MessagesCopiedInfo string value is added to the result dataset. Otherwise, the errorCode element with the operation error code string value is added to the result dataset.

If the WebUser Preferences DeleteMethod option is set to Move To Trash, and the HTTP request contains the Delete parameter, a "message set" is composed using the Msg parameters, the message set messages are copied to the Trash Mailbox and deleted. If the Trash Mailbox did not exist, it is created.

If the HTTP request contains the DeleteAll parameter, all Mailbox messages are deleted, using the method specified with the WebUser Preferences DeleteMethod option.

If the HTTP request contains the read, unread, flag, unflag, delete, or undelete parameters, a "message set" is composed using the Msg parameters, and the flags for the message set messages are modified. The delete and undelete parameters are processed in this way only if the WebUser Preferences DeleteMethod option is not set to Move To Trash.
If the operation has not been successful, the errorCode element with the operation error code string value is added to the result dataset.

If the WebUser Preferences DeleteMethod option is not set to Move To Trash, and the HTTP request contains the Purge parameter, all Mailbox messages with the Deleted flag are deleted.
If the operation has not been successful, the errorCode element with the operation error code string value is added to the result dataset.

If the HTTP request contains the NextMessage parameter with a numeric value, the value is interpreted as the unique ID (UID) of a Mailbox message, and the component tries to find the next Mailbox message. If such a message is found, its UID is added to the Result Dataset as the messageJump element.

If the HTTP request contains the PrevMessage parameter with a numeric value, the value is interpreted as the UID of a Mailbox message, and the component tries to find the previous Mailbox message. If such a message is found, its UID is added to the Result Dataset as the messageJump element.

If the HTTP request contains the NextUnread parameter and the Mailbox contains an unread message, the UID of that unread message is added to the Result Dataset as the messageJump element.

If the messageJump element was not added to the Result Dataset, the code component uses the generic Mailbox component to process the HTTP request parameters and to compose the resulting dataset.

Result Dataset

mailbox: a string with the Mailbox name.
mailboxClass: if this string element exists, it contains the Mailbox class.
mailboxPage: this string element contains the name of the wssp page that should be used to display Mailboxes of this class.
isSentBox: this element exists and contains the YES string if the current Mailbox is the Mailbox selected to keep copies of sent messages.
isDraftsBox: this element exists and contains the YES string if the current Mailbox is the Mailbox selected to keep message drafts.

If a next unread, next, or previous message is found:

messageJump: a string with the found message UID.

If a next unread, next, or previous message was not requested in the HTTP request parameters or it was not found:

refreshTime: the Mailbox view refresh time (in seconds), retrieved from the WebUser Preferences.
listApproval: this string element exists if the Mailbox is the approval Mailbox for a mailing list. The element contains the E-mail address of that mailing list.

The generic Mailbox code component is used to generate the rest of the resulting dataset.

Name: Contacts

Processed in the same way as the Mailbox page.

Name: Notes

Processed in the same way as the Mailbox page.

Name: Calendar

The HTTP request must contain the Mailbox parameter - the name of a Calendar-type Mailbox to be displayed.

Actions

For each Mailbox, the module creates a session object that contains the Mailbox view parameters. When the object is created, these parameters are initiated with the WebUser Preferences values. The object also contains the month number for the "monthly calendar" view. It is initially set to the current month. The object contains the day number that specifies the first day to be displayed in the Calendar view. The object also contains the "byDay" flag that controls how the calendar data is stored in the dataset (by days or by time intervals).

The HTTP request prevMonthlyCalendar parameter can specify the number of months to be subtracted from the "monthly calendar" month number.

The HTTP request nextMonthlyCalendar parameter can specify the number of months to be added to the "monthly calendar" month number.

The HTTP request JumpDay parameter can specify the "day number in the epoch" that will become the first day to be displayed in the Calendar view.

The HTTP request byDay parameter can specify the new byDay flag value.

Result Dataset

mailbox

a string with the Mailbox name.

refreshTime

the Mailbox view refresh time (in seconds), retrieved from the WebUser Preferences.

weekDayNames

the array containing weekday name strings, starting with the day specified as the first weekday in the WebUser Preferences.

todayDay

the day of month for the current date.

todayMonth

the current month.

todayYear

the current year.

todayDayNum

the "day number in the epoch" for the current day.

monthlyCalendar

an array containing one element for each week of the months to be displayed in the "monthly calendar". Each week element is an array with 7 elements. If the element does not correspond to a month day (i.e. the element corresponds to a day before the first day of month or after the last day of month), the element is an empty string. Otherwise the element is a dictionary containing the following subelements:

day: a string with the day of the month corresponding to this element.
workDay: an optional YES string added if the day is a working day.
dayNum: the "day number in the epoch" for this day.

year

the string with the number of the year the first displayed day belongs to.

byDay

the optional element containing the YES string. It is added if the byDay flag is set.

timeSlices

an array containing time slice starting times if the byDay flag is set. Each element is a dictionary containing the following values:

hour: the hour number in the 24-hour system.
PMhour: the hour number in the 12-hour system if the hour value is 12 or more.
minute: the minute number. Always 2 digits.

calendarDays

an array containing calendar view elements if the byDay flag is set. Each element is a dictionary presenting calendar data for one day. It contains the following elements:

weekDay

the weekday name of this day

year

the number of the year this day belongs to

month

the name of month this day belongs to

day

the day number in the month

dayNum

the "day number in the epoch"

allDayEvents

an optional array containing descriptors for all-day events for this day. Each array element is a dictionary containing "Event elements" (see below)

events

an array containing descriptors this day events. Each descriptor corresponds to one time interval, it is a dictionary containing "Event elements" (if there is an Event in this time interval) and the following elements:

nTimeSlices: the length of the descriptor time interval, in time slices.
conflicts: an optional array containing UIDs of other Events conflicting with the Event displayed in this time interval.
status: if the time interval does not contain an Event and it does not belong to a "working time" period, this element contains the UNAVAILABLE string.

calendarDays

an array containing calendar days if the byDay flag is not set. Each element is a dictionary containing the following values:

weekDay: the weekday name of this day
year: the number of the year this day belongs to
month: the name of month this day belongs to
day: the day number in the month
dayNum: the "day number in the epoch"

allDayEvents

an array containing information about All-Day Events if the byDay flag is not set. The array has one element for each displayed day. This element is an empty string if there is no All-Day Events in that day, or it is an array containing dictionary subelements for each All-Day Event taking place that day. Each dictionary subelement contains the "Event elements" for one All-Day Event.

calendarSlices

an array containing information for a time interval if the byDay flag is not set. Each array element is a dictionary containing the following elements:

hour

the hour number in the 24-hour system.

PMhour

the hour number in the 12-hour system if the hour value is 12 or more.

minute

the minute number. Always 2 digits.

days

an array with the calendar data for this time interval in each day. Each element is a dictionary with the day data containing the "Event elements" if this time interval contains an Event in that day, and also the following elements:

nTimeSlices: the length of the descriptor time interval, in time slices.
conflicts: an optional array containing UIDs of other Events conflicting with the Event displayed in this time interval.
status: if the time interval does not contain an Event and it does not belong to a "working time" period, this element contains the UNAVAILABLE string.

The "Event elements" are:

summary: the string with Event Summary text.
ID: a numeric string with the UID of the Event message in the Mailbox.
status: a string with the Event busy status.
priority: a numeric with the Event priority value. This element exists only if the Event priority is not zero.

Name: Tasks

The HTTP request must contain the Mailbox parameter - the name of a Tasks-type Mailbox to be displayed.

Actions

The HTTP request JumpDay parameter can specify the "day number in the epoch" that will become the first day to be displayed in the Tasks view.

The HTTP request showCompleted parameter can specify the new showCompleted flag value.

Result Dataset

mailbox

a string with the Mailbox name.

refreshTime

the Mailbox view refresh time (in seconds), retrieved from the WebUser Preferences.

showCompleted

the optional element containing the YES string. It is added if the showCompleted flag is set.

numTotal

the total number of calendaring items in the Mailbox.

numSelected

the total number of selected Task items.

tasks

an array with selected tasks. Each element is a dictionary describing a task. It contains the following elements:

nBefore: this number string exists if the Task starts after the initial time displayed in the Tasks view. It shows how many Task view time periods should be skipped before the Task starts.
nDuration: this number string specifies the time interval (in time periods) between either the Task start time or the Task view first display time (whatever is later) and the Task Due time or the Task view last display time (whatever is earlier).
nAfter: this numeric string exists if the Task ends before the Task view end time. It shows how many Task view time periods should be skipped after the Task ends.
ID: a string with the UID of the Task message in the Mailbox.
percentComplete: a numeric string with the Percent-Complete value of the Task object.
summary: a string with the Task summary
priority: a numeric string with the Task priority if it was set (is not zero).

Name: Message

The HTTP request must contain the Mailbox parameter (the name of the Mailbox containing the messages to be displayed), and the MSG parameter - the Unique ID of that message in the Mailbox.

Actions

If the HTTP request contains the Copy or Move parameter and the MailboxName parameter contains a name of some selectable Mailbox, the message is copied to the specified Mailbox. If the Move parameter was specified, the message is marked as Deleted, or it is deleted - depending on the WebUser Preferences.
If the operation has been successful, the messageCode element with the MessageCopied string value is added to the result dataset. Otherwise, the errorCode element with the operation error code string value is added to the result dataset.
If the Move operation has removed the message, the backToMailbox element with the Yes value is added to the result dataset, and the code component stops request processing.

If the HTTP request contains the Redirect parameter and the RedirectAddresses parameter is not empty,the message is redirected to the specified addresses.
If the HTTP request contains the ListApprove parameter and the message Mailbox is an "approval" Mailbox for some mailing list, the request is processed as the Redirect request with the effective address being the mailing list address.
If the operation has been successful, the messageCode element with the MessageRedirected string value is added to the result dataset. Otherwise, the errorCode element with the operation error code string value is added to the result dataset.

If the HTTP request contains the TakeAddress parameter the message From: address is added to the Account address book.

If the HTTP request contains the TakeCertificate parameter the certificate from the message digital signature is added to the Account address book.

If the HTTP request contains the StoreFiles parameter and the selectedWebFolder parameter contains a name of the File Storage folder, the file parts of the message (attachments, images) are stored in the specified folder.
If the operation has been successful, the messageCode element with the FilesCopied string value is added to the result dataset. Otherwise, the errorCode element with the operation error code string value is added to the result dataset.

If the HTTP request contains the read, unread, flag, unflag, delete, or undelete parameters, the message flags are modified.
If the operation has not been successful, the errorCode element with the operation error code string value is added to the result dataset.

Then the code component use the generic Message component to process the HTTP request parameters and the compose the resulting dataset.

Result Dataset

mailbox: A string with the Mailbox name.

If the message has not been removed:

MSG

A string with the message UID.

flagged, recent, deleted, flagged, media, isDraft

These elements with the Yes value are added if the message has the corresponding flags.

status

This string element has the following values:

Deleted - if the message has the Deleted flag set, otherwise
Draft - if the message has the Draft flag set, otherwise
Redirected - if the message has the Redirected flag set, otherwise
Unread - if the message does not have the Seen flag set, otherwise
Answered - if the message has the Answered flag set, otherwise
Read

messageBody

A string with HTML presentation of the message, generated using the generic Message code component.

charset

The charset to use for message display. This element can be set with the generic Message code component.

nextMsg

this element is added if there is a next message in the Mailbox view. The element value is a string with the next message UID.

prevMsg

this element is added if there is a previous message in the Mailbox view. The element value is a string with the previous message UID.

hasFiles

this YES string element is added if there is the message contains a file part.

editableContact

this YES string element is added if the message is a VCard object that can be updated.

editableGroup

this YES string element is added if the message is a Group object that can be updated.

editableNote

this YES string element is added if the message is a Note object that can be updated.

editableEvent

this YES string element is added if the message is an Event "published" by this user and it that can be updated.

editableTask

this YES string element is added if the message is a Task "published" by this user and it that can be updated.

canCancelEvent

this YES string element is added if the message is an Event this user can cancel.

canCancelTask

this YES string element is added if the message is a Task this user can cancel.

canAcceptDecline

this YES string element is added if the message is a Task or Event request.

percentComplete

this element containing a number is added if the message is an Task delegated to this user by someone else.

statusCode

this optional string element contains the status of the message if the message is a Task or an Event.

conflictingID

this optional string element contains the UID of the Default Calendar Mailbox message that conflicts with the displayed Event Request.

canUpdatePartStatus

this YES string element is added if the message is a reply to the user's Task or Event request.

canCancelEvent

this YES string element is added if the message is a cancel request from an Event organizer.

canCancelTask

this YES string element is added if the message is a cancel request from a Task organizer.

listApproval

this string element exists if the message Mailbox is the approval Mailbox for a mailing list. The element contains the E-mail address of that mailing list.

Name: Compose

Actions

If the HTTP request contains the charset parameter, the parameter value is used as the desired charset - the charset to be used in the composed message.

The optional Operation HTTP request parameter specifies the type of the Compose operation and it can have the Reply, ReplyAll, Forward, or EditDraft value.
If this parameter is specified, the OrigMessage parameter (with the UID of the original message) and the OrigMailbox parameter (with the name of the Mailbox containing the original message) must be specified.

If the HTTP request contains the Operation parameter and it does not contain the filled parameter, the original message header fields are used to compose the Subject, To, Cc, and the message body data for the new message.
Otherwise, the Subject, To, Cc, Bcc, and Body HTTP request parameters are used as the new message data.

If the HTTP request contains the AddressBook parameter and it does not contain the CloseBook parameter, or if HTTP request contains the OpenBook parameter the generic AddressBook code component is used to process the request parameters and to form some result dataset elements.

If the HTTP request contains the isEvent parameter, the Calendar Event item is being composed. If the HTTP request contains the isTask parameter, the Calendar Task (ToDo) item is being composed. If the HTTP request contains the isNote parameter, the Note item is being composed.

If the HTTP request contains the Send parameter, the composed message is submitted to the Server Queue. If the HTTP request contains the Save parameter, the composed message is stored as a Draft in the selected Drafts Mailbox.
In both cases all HTTP request Attachment parameters are added to the message as attachments.

Result Dataset

operation

This string element is added to the result dataset if the HTTP request contains the Operation parameter. The element value equals the request parameter value.

origMessage

This element containing the UID of the original message is added to the result dataset if the HTTP request contains the OrigMessage parameter.

origMailbox

This element with the name of the Mailbox containing the original message is added to the result dataset if the HTTP request contains the OrigMailbox parameter.

sentOrSaved

This element with Yes value is added to the result dataset if the Send or SaveDraft operation has completed successfully. If this element is added:

The sent element with the Yes value is added if the operation was the Send operation.
The messageCode element with the MessageSent or MessageSaved value is added to dataset.
No other element listed below is added to the result dataset.

Subject, To, Cc, Bcc

These elements contain strings with the current header fields data.

From

This element contains a string with the From address specified in the WebUser Preferences.

addressBook

This element with the Yes value is added to the result dataset if the HTTP request contains the AddressBook parameter and does not contain the CloseBook parameter or if the HTTP request contains the OpenBook parameter.

body

This string element contains the current message body text.

mailerWidth

This string element contains the MailerWidth WebUser Preferences option value.

forwardedMessage

This optional string element contains the HTML representation of the original message. This element is added to the result dataset if the HTTP request Operation parameter is Forward.

DSN

This element with the Yes value is added to the result dataset if the HTTP request contains the DSN parameter.

SaveSent

This element with the Yes value is added to the result dataset if the WebUser Preferences contain a non-empty SentBox option and the HTTP does not contain the Filled parameter or the HTTP request contains the SaveSent parameter.

desiredCharset

This string element contains the name of charset to be used in the composed message.

charset

This element is the UTF-8 string if the Use UTF8 WebUser Preferences option is set to "for Reading and Composing". Otherwise, this element contains the same value as the desiredCharset result dataset element.

isEvent

This element with the Yes value is added to the result dataset if the item being composed is a Calendar Event item.

isTask

This element with the Yes value is added to the result dataset if the item being composed is a Calendar Task (ToDo) item.

isNote

This element with the Yes value is added to the result dataset if the item being composed is a Note item.

The following elements are added if the item being composed is a Calendar item:

allDayEvent: This element with the Yes value is added to the result dataset if the item is an All-Day Event. The element value is controlled with the HTTP parameter of the same name.

Name: MailboxSettings

The HTTP request must contain the Mailbox parameter - the name of the Mailbox to manage.

Actions

If the HTTP request contains the Remove parameter, the Mailbox is removed. If the HTTP request also contains the RemoveSub parameter, all Mailbox submailboxes are removed, too.
If the operation has been successful and the Show Subscribed Mailboxes option is selected in the WebUser Preferences, the deleted Mailbox(es) are removed from the Account subscription list.
If the operation has been successful, the removed element with the Yes string value is added to the result data set and the code component stops request processing. Otherwise, the errorCode element with the operation error code string value is added to the result dataset.

If the HTTP request contains the Rename parameter and the NewName parameters is not empty, the Mailbox is renamed. The NewName parameter value is converted into the "UTF-7 Mailbox Name encoding" format and is used as the new Mailbox name.
If the HTTP request also contains the RenameSub parameter, all Mailbox submailboxes are renamed, too.
If the operation has been successful and the Show Subscribed Mailboxes option is selected in the WebUser Preferences, the renamed Mailbox(es) are renamed in the Account subscription list.
If the operation has been successful, the removed element with the Yes string value is added to the result data set and the code component stops request processing. Otherwise, the errorCode element with the operation error code string value is added to the result dataset.

If the HTTP request contains the Update parameter, the code component retrieves all Acc parameters from the request. Each Acc parameter should have a numeric value. For each retrieved Acc parameter value nnn, the Znnn parameter is retrieved. If it contains a non-empty string, all Knnn request parameters are retrieved, where K is a Mailbox access right letter.
The list of Znnn name strings with their Knnn parameter sets are used to form and set the new ACL list for the selected Mailbox.
If the ACL update operation has been successful, the messageCode element with the Updated string value is added to the result dataset. Otherwise, the errorCode element with the operation error code string value is added to the result dataset.

If the HTTP request contains the DeleteAll parameter, all Mailbox messages are deleted, using the method specified with the WebUser Preferences DeleteMethod option. If the operation has been successful, the messageCode element with the MessagesDeleted string value is added to the result dataset.

Result Dataset

renamed

This element with the Yes string value is added to the dataset if the Mailbox has been renamed. In this case no other element is added to the result dataset.

removed

This element with the Yes string value is added to the dataset if the Mailbox has been removed. In this case no other element is added to the result dataset.

rights

This array element contains the Mailbox ACL (Access Control List) elements. Each array element is a dictionary with the following elements:

ident: this string element contains the ACL element name.
index: this string element contains the element number in the ACL set.
lookup, select, seen, flags, insert, post, create, delete, admin: these elements with Yes string values are added when the ACL element includes these Mailbox access rights.

Name: Alerts

This code component can be called implicitly, if the Web Application module has detected a pending Alert message.

Actions

If the HTTP request contains the AlertTime parameter, that parameter should contain a time stamp in the ACAP format. The code component confirms all Alerts older than the specified time.

If the HTTP request contains the returnURL parameter, the parameter value is added to the result dataset (as the returnURL element).

Result Dataset

alerts

This element is added to the result dataset if there are pending Alerts for the session user. The element value is an array of dictionary elements, each element describing one alert message. Each dictionary contains the following elements:

time: A string element containing the time when the alert was posted.
text: A string element containing the alert message text.

currentTime

This element is added to the result dataset if there are pending Alerts for the session user. Its string value contains the current time in the ACAP format.

returnURL

If the Alerts page was retrieved automatically, when some other page had to be displayed, the encoded URL for that other page is placed into this string element.

Name: Subscription

Actions

If the HTTP request contains the Open parameter, the MailboxName parameter value is converted into the "UTF-7 Mailbox Name encoding" format, the converted string is added to the result dataset as the jump element, and the request processing ends.

If the HTTP request contains the Update parameter:

All Elem request parameters are retrieved, converted into the "UTF-7 Mailbox Name encoding" format, and form the new Account Subscription list.
All AliasName request are retrieved, they should contain numeric values. For each retrieved numeric value nnn, the parameters pairs annn and mnnn are retrieved. If both parameters exist and contain non-empty strings, the strings are converted into the "UTF-7 Mailbox Name encoding" format, and are used to form the new set of Account Mailbox Aliases.
If the Subscription or Mailbox Aliases update operation fails, the errorCode element is added to the result dataset. Otherwise the messageCode element with the Updated string value is added to the result dataset.

Result Dataset

jump

The name of the Mailbox to open ("to jump to"). If this element exists, none of the following elements is added to the result dataset.

subscription

This array element contains the Account subscription list. Each array element is a string with some Mailbox name.

aliases

This array element contains the Account Mailbox Aliases list. Each array element is a dictionary with the following elements:

index: A string with this Mailbox Alias element index.
name: A string with the Mailbox Alias name.
ref: A string with the name of the Mailbox this Alias points to.

Name: Password

Actions

If the HTTP request contains the ModifyPassword parameter, the request should also contain the OldPassword parameter, and that parameter should match the current Account password. If the OldPassword parameter value is correct:

The RecoverPassword request parameter value is set as the new RecoverPassword Account setting. The messageCode element with the Updated string value is added to the result dataset.
If the Account user is allowed to modify the Account password, the NewPassword1 and NewPassword2 parameters are checked. If they are non-empty and match each other, then the Account password is updated using these parameters value.

If the password has been updated successfully, the messageCode element with the PasswordChanged string value is added to the result dataset. If the password update operation failed, the errorCode element is added to the result dataset.

Result Dataset

RecoverPassword: This string element contains the Account RecoverPassword setting value.

Name: PublicInfo

Actions

If the HTTP request contains the Update parameter, the request should also contain zero, one, or several ID parameters, each with a numeric value. For each ID parameter, its numeric value nnn is used to retrieve the pair of Nnnn and Vnnn string parameters. The value of the Nnnn parameter specifies the name of the Account Public Info setting, the value of the Vnnn parameter specifies the setting value. These pairs are used to set the new Account Public Info settings. If an empty string is specified as a setting value, the setting is removed from the Account Settings.

If the Public Info settings have been updated successfully, the messageCode element with the Updated string value is added to the result dataset. If the password update operation failed, the errorCode element is added to the result dataset.

Result Dataset

publicInfo

This array element contains a set Public Info elements. It contains one element for each Public Info Setting specified with the Directory Integration settings. Each array element is a dictionary with the following elements:

id: this string element contains the element number in the set.
name: this string element contains the Public Info setting name.
value: this string element contains the current Public Info setting value. This element exists only if the Account contains this Public Info setting.

Name: WebSite

The code component uses the generic WebSite component to process the HTTP parameters and to form the result dataset. Before the generic component is called, the following elements are added to the result dataset:

Result Dataset

fileRef: The WebFile/ string.
pageRef: The website.wssp string.

Name: Bye

Actions

The code component can delete old messages from the Trash (as specified in the WebUser preferences) and closes the session. The session will be destroyed as soon as this HTTP request is processed, so the bye.wssp code can use session data, but the produced HTML code should not contain references to session objects.

Result Dataset

blockAlerts: This element has the Yes string value. It is added to the result dataset to prevent Alert processing.

The Web Application module has several generic components used to process both stateless and session requests.

Generic Mailbox component

Actions

If the HTTP request contains Filter, Search, Limit parameters, these parameter values are used to modify the Mailbox "viewer" current Filter, Search, Limit values.

If the HTTP request parameter Skip exists, it should have a numeric value. This number is used to set the current first message index - the number of the first message to be displayed on this page.

If the HTTP request contains the parameter Next, then the current first message index is increased by the current Limit value.

If the HTTP request contains the parameter Prev, then the current first message index is decreased by the current Limit value.

If the HTTP request contains the parameter Sort, its numeric value specifies the number of "sorting" column (to sort the Mailbox view by the first column, the Sort parameter should be 0).

If the HTTP request contains the parameter SDir, its numeric value specifies the sorting order: the value 1 requests ascending order, the value 0 - descending order, the value -1 reverses the current sorting order.

Result Dataset

checkAll

This element has the CHECKED string value. It is added to the result dataset if the HTTP request contains the MarkAll parameters.

filter

The string value of this element is the current Filter string.

search

The string value of this element is the current Search string.

limit

The string value of this element is the current Limit value (a number).

sentBox

This element has the YES string value and exists only if this Mailbox is a Sent-type Mailbox.

headers

The array value of this element contains Mailbox view column headers. Each array element is a dictionary with the following elements:

index: This string element contains the column number.
name: This string element contains the column name.
hilited: This element has the YES string value and exists only if this column is the sorting column.
sdir: If this column is not the sorting column, this element contains the current sorting order (0 or 1). If this column is the sorting column, this element contains the reversed current sorting order (1 - current sorting order).
ralign: This element has the YES string value and exists only if this is a date- or size-type column and thus needs the reversed horizontal alignment.

messages

The array value of this element contains the Mailbox view data. Each array element is a dictionary with message data, and it contains the following elements:

id

this element contains the message Unique ID (UID)

color

if the message has the X-Color header field with a valid HTML "color" string as its value, this element exists and contains the value of that header field.

notText

this optional element has the YES string value; it exists if the message Content-Type is not text.

notAltText

this optional element has the YES string value; it exists if the message Content-Type is not text and the message Content-Type/Subtype is not multipart/alternative.

fields

this array element contains message column data. The columns are stored in the same order as columns in the headers result dataset element. Each element is a dictionary. It contains the following elements:

hilited

This element has the YES string value and exists only if this column is the sorting column.

sdir

If this column is not the sorting column, this element contains the current sorting order (0 or 1) If this column is the sorting column, this element contains the reversed current sorting order (1 - current sorting order).

ralign

This element has the YES string value and exists only if this is a date- or size-type column and thus needs the reversed horizontal alignment.

isRef

This element exists for the selected column and for the first "clickable" column. If it exists, it contains the string YES.

value

This element contains the column data. It exists for all columns except for the Status column. For the Sent and Received columns the element contains the "date" value - values of that type can be displayed using the DATE:, DATETIMESHORT and similar prefixes.

isStatus

This YES string element exists if the column is the Status column.

isDate

This This YES string element element exists if the column is the Sent or Recieved column and the value element contains the "date"-type value.

isPty

This YES string element exists if the column is the Priority column.

status

This element exists if the column is the Status column. If it exists, it contains the one of the following strings:

If the message has the Deleted flag - Deleted, otherwise
If the message has the Draft flag - Draft, otherwise
If the message has the Redirected flag - Redirected, otherwise
If the message does not have the Seen flag - Unread, otherwise
If the message has the Answered flag - Answered, otherwise
Read

flagged

This element exists if the column is the Status column and the message has the Flagged flag. If it exists, it contains the string YES.

recent

This element exists if the column is the Status column and the message has the Recent flag. If it exists, it contains the string YES.

hidden

This element exists if the column is the Status column and the message has the Hidden flag. If it exists, it contains the string YES.

media

This element exists if the column is the Status column and the message has the Media flag. If it exists, it contains the string YES.

firstNumber

This string element contains the number of the first message in the view.

firstNumber1

This string element contains the number of the first message in the view increased by 1.

lastNumber

This string element contains the number of the first message in the view increased by the number of the messages array elements if this array is not empty, or increased by 1 if the messages array is empty.

numTotal

The total number of messages in this Mailbox.

numUnread

The total number of unread messages (messages without the Seen flag) in this Mailbox.

numSelected

The total number of Mailbox messages that can be displayed with the current Filter and Search values.

multiPage

This element with the YES string value is added if the nSelected value is not equal to the number of the messages array elements.

sortColumn

This element contains the number of the currently selected sorting column.

sortAscending

This element contains 1 is the currently selected sorting order is ascending, and 0 if it is descending.

Generic Message component

The generic Message component is used to convert the an RFC822 message into an HTML text. It processes simple and multi-part messages, attachments, digests, inline images and other letter components. To build a HTML presentation, the component uses Code Components for Message Rendering.

The Web Application module can render messages, converting them into a markup (HTML) text. This process is controlled by the Application module itself. It detects the MIME structure of the message, and processes each part recursively. For each part, a dataset is produced and a .wssp file is used to produce a markup language presentation.

Message Rendering code components do not perform any actions.

A Result Dataset produced by every Message Rendering code component includes the following fields:

MIMEPart: this string element contains a URL reference for the message or the message part that is being rendered.
filesRef: this string element contains the URL prefix needed to retrieve files from the proper Skin. When a message is being rendered withing some WebUser Session, this string is the same as the SESSION(filesRef) string.
isWML: this string element exists and contains the YES string if the message should be displayed using the WML markup language.
printVersion: this string element exists and contains the YES string if the message should be displayed in a printable form.

The following Message Rendering code components are implemented:

Name: RFC822Message

This code component is used to render a mail message - a message stored in a Mailbox or a message/rfc822 MIME subpart of some other message.

Result Dataset

RFC822Header: this string element contains the rendered markup presentation of the message RFC822 header.
RFC822Body: this string element contains the rendered markup presentation of the message RFC822/MIME body.
isSubPart: this optional element exists and has the YES string value if the message is a MIME subpart of some other message.

Name: RFC822Header

This code component is used to render an RFC822 mail message header.

Result Dataset

RFC822Fields

this element is an array with one dictionary-type element for each "visible" field in the header. Each dictionary contains the following elements:

name: this string element contains the header field name.
value: this string element contains the MIME-decoded field value.

Name: AttachmentPart, ImagePart

This code component is used to render an image or an attachment. Images and attachments can be separate MIME parts, or can be embedded into text parts using UUENCODE encoding.

Result Dataset

attachmentName: this string contains the file name as it is stored in the message data.
fileName: this string contains the "cleaned" file name (with all path components removed and image file name suffix added if necessary).
embeddedPart: if this string parameter exists, the file is an "embedded" UUENCODE data, and the string specifies the embedded component number inside the MIME part.
decodedSize: this string element contains the approximate size of the decoded file data.

Name: DeliveryReportPart

This code component is used to render a message/report MIME subpart.

Result Dataset

MessageFields

this array element contains one dictionary element for each message-level report field. Each dictionary element contains the following elements:

name: this string element contains the report field name.
value: this string element contains the MIME-decoded report field value.

Reports

this array element contains one array element for each recipient report. Each recipient report is an array containing one dictionary element for each recipient-level report field. Each dictionary element contains the following elements:

name: this string element contains the report field name.
value: this string element contains the MIME-decoded report field value.

Name: DispositionReportPart

This code component is used to render a message/disposition-notification MIME subpart.

Result Dataset

fields

this array element contains one dictionary element for each message-level report field. Each dictionary element contains the following elements:

name: this string element contains the report field name.
value: this string element contains the MIME-decoded report field value.

Name: EncryptedPart

This code component is used to render an encrypted MIME subpart.

Result Dataset

decryptedPart: this array element contains the rendered markup presentation of the decrypted content. The element exists only if decryption was successful.
decryptionErrorCode: if this string element exists, it contains the error message explaining why content decryption has failed.
cipherName: This string element contains the name of the cipher used for content encryption.
keyLength: This string element contains the size of the encryption cipher key (in bits).

Name: SignedPart

This code component is used to render a signed MIME subpart.

Result Dataset

signedPart

this array element contains the rendered markup presentation of the signed content. The element exists only if decoding was successful (for binary-type signed messages).

encoding

this string element contains words "Binary" or "Text" depending on the format of the signed subpart.

decryptionErrorCode

if this string element exists, it contains the error message explaining why binary content decoding has failed.

digesterName

This string element contains the name of the digester used for digital signing.

signatures

If this array element exists, then the signed content was verified by at least one digital signature. Each element of this array is a dictionary with signature data. These dictionaries contain the following elements:

contact: this string element contains the E-mail address of the signer
commonName: this string element contains the "real name" of the signer
Country, Province, Organization, Unit: these optional string elements contain additional information about the signer.

Name: CalendarPart

This code component is used to render an iCalendar subpart.

Result Dataset

Summary, Location, Comment

these string element contain the iCalendar attribute data.

Priority

this numeric string element contains the iCalendar element PRIORITY attribute value.

dateFrom

this date element contains the iCalendar element DTSTART attribute value.

method

this string element contains the iCalendar object METHOD parameter.

description

this string element contains the formatted DESCRIPTION attribute value.

organizer

this optional dictionary element contains the ORGANIZER attribute. The dictionary can contain various parameters specified for that attribute ("cn", etc.). The E-mail address (the value) of the attribute is available as the theValue element of this dictionary.

attendees

this optional array element contains dictionary elements for each ATTENDEE attribute. Each dictionary can contain various parameters specified for that attribute ("cn", "role", etc.). The E-mail address (the value) of the attribute is available as the theValue element of this dictionary.

isEvent

this optional element exists and contains the YES string if the iCalendar element is a VEVENT. The following optional elements may exist only if this isEvent element exists:

allDayEvent: this optional element exists and contains the YES string if the VEVENT is an All-Day Event.
recurrence: this optional element exists and contains the YES string if the VEVENT is a recurrent Event.
duration: this optional numeric string element exists and contains the Event duration in second if the VEVENT is a recurrent event.
dateTill: this optional date element exists and contains the Event "end date" if the Event is not a recurrent one, and if it's not a 1-day All-Day Event.
busyStatus: this optional string element contains the status of the Event if the iCalendar method is PUBLISH.

isTask

this optional element exists and contains the YES string if the iCalendar element is a VTODO. The following optional elements may exist only if this isTask element exists:

dateTill: this optional date element contains the VTODO "due date".
percentComplete: this numeric string element contains the VTODO PERCENT-COMPLETE attribute value.

Name: vCardPart

This code component is used to render an vCard subpart.

Result Dataset

FN

this string element contains the Formatted Name vCard attribute value.

UID

this string element contains the UID vCard attribute value.

REV

this date element contains the REV vCard attribute value.

elements

this array element contains dictionary elements for other vCard attributes. Each dictionary has the following elements:

name: a string with vCard attribute name
value: the vCard element value. The value can be a dictionary or an array of dictionary elements if vCard has several attributes of the same name. Each dictionary contains the attribute parameters and the attribute value as theValue element.

Session and Stateless requests processed using WSSP files produce markup language documents. Before these documents are sent to the client browser, their first lines are checked. If the first document line starts with the <REDIRECT> tag, the rest of the document first line is interpreted as a URL.

The Server returns the 301 ("Moved") response code with the Location header containing the specified URL.

The Server also processes the <RELREDIRECT> tag at the beginning of the document. It is processed in the same way as the <REDIRECT> tag, but the URL placed into the Location header is prefixed with the http or https prefix, the server name (and, optionally, port number) retrieved from the request URL.

Session and Stateless requests can be processed using CG/PL applications (rather than the code components built into the Server). These CG/PL applications are called Web Applications.

A stateless request addressing a /programName.wcgp or /programName.wcgp/some_url resource makes the Server load the programname.wcgp CG/PL application from the selected Skin.
If the application produces any output, it is returned to the client browser, otherwise the 404 Not Found error is returned.

An application can be started by addressing a /auth/programName.wcgp or /auth/programName.wcgp/some_url resource. Such an HTTP request is authenticated first, and the application is executed on behalf of the authenticated Account.

An application can be started by addressing the /sys/programName.wcgp resource. The application is executed in the Server-wide or the Cluster-wide Unnamed Skin environment on behalf of the postmaster Account in the Main Domain. The sysEntry code section of the programName.wcgp file is executed.

Session requests addressing a /programName.wcgp in the Session (/Session/sessionID/) realm makes the Server load the programname.wcgp CG/PL application from the Session Skin.
Only the GET, POST, and HEAD HTTP requests are supported.
If the application produces any output, it is returned to the client browser, otherwise the 404 Not Found error is returned.
The application is executed on behalf of the Account the Session belongs to.

When a CG/PL module is loaded to process an HTTP request, the main module entry is executed.

Web Applications can use CG/PL external-declarations. When a code section (a procedure or a function) declared as external is called, a file with the code section name and the .wcgi extension is loaded from the current Skin. The program code in this file must contain the code section with the specified name and of the proper type (a procedure or a function).
The program code in an .wcgi file may contain other code sections as well.

CG/PL Web Applications can use the following built-in procedures and functions.

HTTP Request Input

GetHTTPParameter(name [ ,index ]): This function retrieves an HTTP request parameter. HTTP request parameters include URL parameters and/or form fields.
The name value should be a string specifying the HTTP request parameter name.
An HTTP request can contain several parameters with the same name. If the index parameter is present, its value should be a number specifying which HTTP request parameter of the specified name should be retrieved.
If the HTTP request contains the FormCharset parameter, its value is interpreted as the character set name. The function converts the raw parameter data into the UTF-8 character set. If the FormCharset parameter is absent, the raw parameter data is assumed to be encoded using the UTF-8 character set.
If the parameter value contains several lines, the EOL (line separator) symbols are converted to those used with the Server host OS.
This function returns a string containing the parameter value. If the parameter with the specified name and, optionally, index is not found, this function returns a null-value.
GetHTTPBinaryParameter(name [ ,index ]): This function retrieves an HTTP request parameter raw data.
This function returns a datablock containing the parameter value. If the parameter with the specified name and, optionally, index is not found, this function returns a null-value.
GetHTTPField(name): This function retrieves the name HTTP request field.
The following fields are supported: Authorization, Referer, Destination, Cookie, User-Agent, Host.
If the name value is an empty string, the HTTP request URL (without the optional URL parameters) is returned.
If the name value is the Schema string, the request URL schema used (the http or https string) is returned.
If the name value is the Host string, the request Host field is returned, with the optional "port" part removed.
If the name value is the Port string, the port number from the Host field is returned; if no port is specified in that field, the number 80 is returned for clear text connections, and the number 443 for secure connections.
If the specified field name if not in the supported set, or if the request does not contain the specified field, this function returns a null-value.
GetHTTPQuery(): This function retrieves the parameter string from the HTTP request URL.
If the request URL does not contain parameters, the function return a null-value.
GetHTTPMethod(): This function retrieves the HTTP request method string (GET, POST, etc.).
GetHTTPType(): This function retrieves the HTTP request body Content type.
GetHTTPSubtype(): This function retrieves the HTTP request body Content subtype.
GetHTTPData(name): This function retrieves the HTTP request body.
If the request body content subtype is xml or it ends with +xml, the function tries to convert the body content into XML and returns an XML object.
If the request body content type is text, the function converts the body content into UTF-8 and returns a string.
Otherwise, the function returns a datablock.
If any conversion operation fails, or if the request body is absent or it is too long, the function return a null-value.

HTTP Response Output

SetHTTPResponseData(data): This procedure sets the HTTP response body.
The data value should be either a string, a datablock, a dictionary, or an XML object.
SetHTTPResponseType(mimeType,subtype): This procedure sets the HTTP response Content-Type field values.
The mimeType and subtype values should be strings containing valid MIME atoms.
SetHTTPResponseCode(code): This procedure sets the HTTP response code.
The code value should be a number in the 200..999 range or a string.
If the string starts with a 3-digit prefix and the - symbol, then the prefix specifies the HTTP response code, and the rest of the string specifies the HTTP response text.
If there is no such prefix in the code string value, then the HTTP response code is set to 500, and the entire string is used as the HTTP response text.
RemoteIPAddress(): This function returns an ip-address object specifying the IP Address the HTTP request was received from.
ProxiedIPAddress(): If the HTTP request was relayed by some external HTTP proxy, this function returns the original client IP Address. Otherwise the function returns a null-object.
SendHTTPContinue(): This function sends the 100-Continue HTTP response.
If the response is successfully sent, the function returns a null-value, otherwise it returns an error code string.
AddHTTPResponseField(fieldName,fieldValue): This procedure adds a field to the HTTP response.
The fieldName and fieldValue values should be strings.
ProcessWSSP(pageName,resultSet): This procedure composes the HTTP response body using the specified WSSP page and the result dataset.
The pageName value should be a string with the page name (without the wssp suffix). This page is retrieved from the currently selected Skin.
The resultSet value should be a dictionary. The Server modifies this dictionary adding the common Session or stateless processing elements (see above), and then it is passed to the WSSP interpreter.
The resulting page is set as the HTTP response body.

Session Data

Functions and procedures listed in this section are available only for Session HTTP requests.

SessionData(): This function returns the Session Dataset dictionary.

Web Applications

Stateless and Session-based Processing

Skins

WAP/WML Skins

cHTML (I-Mode) Skins

Skin Files Hierarchy

Languages and Skin Text Dataset

Serving Regular Files

Serving Web Application (WSSP) Files

Creating and Managing Skins

WebAdmin Editor

CLI/API

Virtual File Storage Area

Request Processing

Code Components for Stateless Requests

Error Pages

Code Components for Session Requests

Generic Code Components

Code Components for Message Rendering

Redirect-type Response

CG/PL Applications

HTTP Request Input

HTTP Response Output

Session Data