 |
Version 5.1 |
|
|
Web Applications
The CommuniGate Pro Web Application module provides access to various CommuniGate Pro
Objects (accounts, messages, mailing lists, web files) via any Web (HTTP/HTML/WML/cHTML) browser.
The HTTP module receives HTTP client browser requests that come to the WebUser port(s),
and passes those requests to the Web Application module. The Web Application module either retrieves the requested file,
or it starts some internal web application code and converts the result into the HTML, WML or other markup format.
The result is returned to the HTTP module that delivers it back to the client browser.
Read this section if you want to customize your CommuniGate Pro Server WebUser Interface.
|
|
|
Stateless and Session-based Processing
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.
Skins
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.
Skin Files Hierarchy
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.
Languages and Skin Text Dataset
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.
Serving Regular Files
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.
Serving Web Application (WSSP) Files
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.
Creating and Managing Skins
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:
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 file first. If the compiler parser detects an error, the file is not uploaded, the source of
the file 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.
Request Processing
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.
Code Components for Stateless Requests
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 the request is a WML request,
the wlogin.wssp page is used.
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 (wStartPage for WML sessions) Skin string.
If login operation was successful, but the request contained the restoreSessionPage
parameter, the resume.wssp (wresume.wssp for WML sessions) 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.
Error Pages
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.
Code Components for Session 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 retreived 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 retreived 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, wMailboxes
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, wMailbox
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), retreived 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, wContacts
Processed in the same way as the Mailbox page.
Name: Notes, wNotes
Processed in the same way as the Mailbox page.
Name: Calendar, wCalendar
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 substructed
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.
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 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 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.
Result Dataset
- mailbox
- a string with the mailbox name.
- refreshTime
- the mailbox view refresh time (in seconds), retreived 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, wTasks
The HTTP request must contain the Mailbox parameter - the name of a Tasks-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 contains the day number that specifies the first day to be displayed in the Tasks view.
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 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 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 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.
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), retreived 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 numberic 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 origanizer.
- canCancelTask
- this YES string element is added if the message is a cancel request from a Task origanizer.
- 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 represenation 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 retreieves all
Acc parameters from the request. Each Acc parameter should have a numeric value.
For each retreieved 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 retreived, 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 Mailboix 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.
Generic Code Components
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, attachements, digests,
inline images and other letter components. To build a HTML presentation,
the component uses
Code Components for Message Rendering.
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.
Redirect-type Response
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.
CommuniGate® Pro Guide. Copyright © 1998-2007, Stalker Software, Inc.