This is part of the AXGate documentation included in newObjects
Development Library (NDL). We recommend you download it in order
to get the full information. There are also samples included with the
component. It will be convenient for you to download the raw package
if you are developer (it contains the DLL and the other files without
installation) in order to be able to fetch the files from the archive
on your desktop computer instead of searching the device for
them.
The AXGate keeps all its configuration in a single text file which
must be located in the same directory where the DLL resides. It must
be named AXGate.cfg. The sample file that comes with the component
contains comments to remind you about the meaning of the settings -
once you have read the documentation (note that using the change
password sample will remove the comments). The configuration has two
top level sections CONTROL which is reserved for future use and
PROFILES which contains the profiles definitions. Each profile is
defined in its own section. Here is a template section we will use for
the description below it:
{ ProfileName:
(int)Access=<AccessCode>
(string)Password=<Password>
(string)Name=<Display name>
(string)Description=<Description>
(string)Default=<Default object>
(string)AllowedProtocols=<protocol1>
...
(string)AllowedProtocols=<protocolN>
(string)AllowedURL=<url1>
...
(string)AllowedURL=<url1>
{ CLASSES:
{ ObjectName1:
(string)Type=File
(int)Create=<1|0>
(int)Exclusive=<1|0>
(int)ShareRead=<1|0>
(string)File=<file full path>
} ObjectName1;
{ ObjectName2:
(string)Type=MemoryStream
} ObjectName2;
{ ObjectName3:
(string)Type=OLEStorage
(int)Create=<1|0>
(int)Exclusive=1
(string)File=<file full path>
} ObjectName3;
{ ObjectName4:
(string)Type=SQLite3DB
(string)File=\AXGate.db3
} ObjectName4;
(int)newObjects.utilctls.SFRecord=1
(int){06C9B1B5-13E5-4661-AE98-DFAB98C67AF1}=1
........ and so on .........
} CLASSES;
} ProfileName;
The ProfileName can be any string you want. It must not
contain ":" or ";" characters and <CR>,
<LF> characters. This name is used by the script when it
requests profile activation through the Profile
property.
The most important setting for a profile is Access. The
current version supports the following values:
0 - Default (if Access is omitted). The profile can be used from
any source, the user is asked for a permission to activate it.
1 - The profile can be used from any source, the access is granted
if the PassCode property matches the Password
setting in the profile.
2 - The profile is allowed only if the page has been downloaded
through one of the protocols listed in an AllowedProtocol
option. At least one such option should exist - otherwise the
profile is unusable. The user is asked for a permission to activate
the profile.
3 - Like previous (2) but PassCode property must match the Password
setting.
4 - The profile is allowed if the page has been downloaded from URL
"under" on of the URL specified in an AllowedURL
option. This means that the page URL must begin with one of URL
specified in the AllowedURL options. The user is asked for a
permission to activate the profile.
5 - Like previous (4), but the PassCode property must match
the Password setting.
The Password setting is meaningful only for profiles with Access
set to 1, 3 or 5.
The Name specifies the display name of the profile. This
name is shown to the user when he/she is asked for a permission to
activate the profile or when the "Access denied" message is
shown in case of a profile with password protection.
The Description allows you specify one line (can be quite
long) of description that helps the user decide what to do - allow or
deny profile activation. Used in profiles with Access set to 0, 2, 4
and not used in password protected profiles (Access set to 1, 3, and
5).
The Default setting is optional. If present it specifies one
of the classes listed in the Classes section - the name of the class
or the pre-initialized objects. It allows the CreateObject
method proceed without parameters or with empty string parameter. If
called this way it will return the default object.
The CLASSES section
The regular entries for COM classes are like this:
(int)<ProgID>=<1|0>
or
(int)<ClassID>=<1|0>
You can specify the ProgID of the class you want to list or/and
its ClassID. If ClassID is specified it will allow CreatObject to
accept the ClassID UID string (like this one for instance:
{06C9B1B5-13E5-4661-AE98-DFAB98C67AF1} ). However most of the
developers are used to ProgID strings instead of ClassID so ProgID-s
should be used unless there is a specific reason to use ClassID.
The entry must be set to 1 in order to allow object creation. You
can set it to 0 if you want to disable the object without removing
the entry (for example if you want to disable it temporarily).
The special pre-initialized objects
Version 1.0.0.2 of AXGate supports 3 types of such objects. Each
of them is specified in a section named after the name you want to
use in CreateObject to obtain it. I.e. you will be able to obtain it
when CreateObject is called with the section name you specified.
File
(string)Type=File
This is a SFStream
object attached to a file explicitly specified by the setting:
(string)File=<file path>
File path must be full - for example: \My Documents\myfile.txt
If you want the file to be created if it does not exist yet
instead of causing an error you can specify:
(int)Create=1
Also there are two more settings you can optionally put in the
section:
(int)Exclusive=1
Will open/create the file with exclusive access - no other
application or script will be able to open it while it is in use.
(int)ShareRead=1
If specified instead of Exclusive will allow other applications to
read the file but not write it while you are using it.
When you obtain the object the file is positioned in the
beginning. If you want to append it the first thing you do should
be ofile.Pos=ofile.Size - position at the end of the file.
MemoryStream
(string)Type=MemoryStream
This is a SFStream
attached to a temporary in-memory file.
The file is lost when the page is closed. Can be useful when
transferring data from other sources.
OLE Storage
(string)Type=OLEStorage
This is a SFStorage
object attached to an OLE storage file explicitly specified by the
setting:
(string)File=<file path>
File path must be full - for example: \My Documents\mystorage.stg
As like File you can use:
(int)Create=1
If you want the storage be created if it does not exist yet.
(int)Exclusive=1
Must be specified in order this to work because of the
platform limitations.
The OLE storages are a kind of a virtual file system maintained
in a file. So the storage looks like single file in the device's
file system, but internally it may contain sub-storages
(sub-directories), streams (files) in a tree-like structure as
like the device's file system. There are certain limitations - for
example the sub-elements names must be up to 31 characters long
and no more, but in general it allows the data to be stored in any
convenient way.
SQLiteDB and SQLite3DB
Type can be one of these two:
(string)Type=SQLiteDB
For SQLite COM
or
(string)Type=SQLite3DB
For SQLite3 COM
(string)File=<dbfile_path>
The full path to a database file which will be automatically
opened/created when the object is created.
The SQLite pre-initialized objects enable you to create
profiles with something you can call default database - i.e. the
database is opened with the object creation saving the page some
work.
The usage of the component is well illustrated in the samples
packed with it. By default they are installed in My Documents\AXGate
samples directory. You can download also the raw package which
includes the samples as well. If you are installing AXGate manually
please note that some examples may have the \My Documents\AXGate
samples directory hardcoded in them - if you have problems check their
source code and change it to match the location you are using.
A few words about the usage. In general there are two techniques
depending on the profile(s) you intend to use. The profile with Access
set to 0,2 and 4 require the user to permit the profile activation,
while the others (1,3 and 5) expect the page to set the PassCode
property before activating the profile.
The profile is activated by writing the profile name desired to the
Profile property. When this is done
before returning the control to the script 3 things may happen
depending on the profile type - user is asked to permit the profile
activation, PassCode is checked against the Password setting in the
profile configuration or the access is implicitly denied if the
profile requires the page to be fetched through a particular protocol
or URL not matching the current page properties (the latter applies to
the profiles with Access set to 2,3,4 and 5).
How to create the AXGate object?
You should use code like this:
...
<BODY>
...
<OBJECT
ID="axgate"
CLASSID="clsid:03797ADA-8CCF-4533-B623-2C5DE06B29C7"></OBJECT>
...
It is recommended to place this outside any form in order to make
it easier to access the object. If the declaration is as in the above
sample code you can refer to AXGate using the axgate variable
(corresponds to the ID attribute) after the page is completely
loaded. Note that you cannot refer to the AXGate object while the
page loads but is not yet finished so it is convenient to use BODY's
onLoad event to initialize AXGate with certain profile. Of course, if
your page is constructed in manner that permits you perform the
initialization later (when user clicks something for example) you can
do this later - in response to some other event.
Below we will assume that the above <OBJECT ...> exists
somewhere in the page and we will only list the other sample code
involved. We also assume for the sample purposes that ID of AXGate is
"axgate" - you can name it otherwise, of course.
A typical code for user acknowledged profile looks like this:
var creator;
function InitProfile() {
axgate.Profile = "FullAccess"; // We want the FullAccess standard profile.
creator = axgate.CreateObject();
var o = creator.CreateObject("Someobject.ProgID");
// use o for something
.....
}
Above we use also the "Default" feature which allows us
call CreateObject without parameters and receive the default object.
In the "FullAccess" profile it is the Pack1Creator
from ActiveX Pack1 which in turn provides access to any registered COM
class in the system and also to composite objects. This special
feature of ActiveX Pack1 is handy here but if we want to use some
restricted profile like FileAccess for instance we may write this:
var SFMain;
function InitProfile() {
axgate.PassCode = "<the actual pass code>";
axgate.Profile = "FileAccess"; // We want the FileAccess standard profile.
SFMain = axgate.CreateObject("newObjects.utilctls.SFMain");
// Open a file for example
var file = SFMain.OpenFile("\myfile.txt");
// Write something in there
file.WriteText("Some text ...",1);
..... etc. .....
}
By the way - the FileAccess profile is password protected so we
need to set the PassCode property before activating it. After that
point everything is the same with any profile - we use
axgate.CreateObject("someID") to produce objects from the
profile. Do not forget that the technique in FullAccess profile is an
exception benefiting of the Pack1Creator object - in general ProgID-s
are used as parameters.
A little discussion. In the first case when you attempt to
set the Profile property a dialog will pop-up to ask the user for
permission to access the profile, while in the second sample the
PassCode and the Password will be compared silently and access
provided if they match. Of course placing the password in the source
of the page is not a good idea especially if the page is downloaded
from a random site. This can be convenient and secure for pages in the
local file system but is not wise for online pages. Note that the
standard profiles follow these considerations (review the AXGate.cfg).
Still a password protected profile can be used quite securely online
if the password is not in the page source. You can provide a field
user must fill or use cookies or something else. For example if it is
in a field you can do this:
axgate.PassCode = document.forms[0].PassCode.value;
Where the ID of the field is "PassCode" too. Of course,
in such cases you should init the profile not on load but later when
the user clicks some button for instance to confirm that he/she have
entered something in the password field.
Do not forget that the profiles with Access set to 2,3,4 and 5
allow you restrict their usage for certain protocols or URL only. This
allows you find the balance between security and convenience. The
standard profiles are good for many things but not for everything, of
course. When creating yours consider how secure are they.
For example if may want to collect information in a file and use
the latest entries on the device for some references. Assume that
later (in the end of the day/week) you transfer the collected
information to the desktop for further processing, but still you want
to implement more then just simple forms - for example you want to
allow the user to review whatever entries he/she have collected today,
search through them etc. You can do this using a flat file and a
SFRecord object. Then you will need a File pre-initialized object (see
in the above section) and a few other objects to perform other
supporting operations. If the only access to the local file system is
through this File pre-initialized object everything you expose is that
file where you collect the data. Well even in case of intrusion the
attacker will only destroy the content of the file. Well, but if the
user has been collecting this information for a few days it will be
quite a loss, depending on what kind of attacks you may expect (based
on popularity, the information and other considerations outside the
pure programming) you can decide what way to use. In general password
protection will be ok - as long as the application on the device
consists of one or more pages in the local file system,. So a profile
with Access=3 will do - limit the protocols to file only and
usage of password is safe enough (if someone manages to access the
files of your applications and thus steal the password then something
elsewhere is very wrong and it has nothing to do with your
application, nor with AXGate). But, suppose you want something more -
for example allow the user connect to your corporate site online and
run some additional pages over the local data. the purpose of this can
be some statistics, analysis you publish for the users that do this or
the reason can be even more complex - allow the user select and submit
entry or entries from the locally stored data to the server. This page
is to be more secured than the locally residing pages. You should look
at profiles with Access set to 4 or 5 then. You can specify there the
local URL and the online URL thus restricting the profile usage to
these two locations only. But still password or user acknowledgment?
If the application rarely requires the user to navigate from page to
page user interaction will not be too disturbing, but if not a
password usage may be more convenient. If you manage to implement the
online pages to fill the password from a parameter or a cookie set by
the local pages it will be better - i.e. if it is possible to avoid
putting the password into the page source and even the URL parameters
it is good and secure if something prevents such solution better go
the other way - user interaction.
Can I create the AXGate object directly?
Yes you can use:
var axgate = new ActiveXObject("newObjects.sandbox.AXGate");
This will even work outside IE (in CE version of IIS for instance),
but it will prevent AXGate from knowing where the page came from which
means that this technique should not be used in the typical area of
application of AXGate - HTML pages. It will limit you to profiles with Access set to 0 and 1 only! If you
use this technique in applications other than PIE consider what kind
of profiles will be appropriate - for instance in IIS user
acknowledgment will not be a good idea because a dialog will pop up
every time a page is served. Why should one need AXGate in an ASP page
or in a script? While this is not a specially targeted area AXGate can
help in such scenarios as well. In Pocket PC the Javascript itself
checks for the object safety and refuses to create unsafe objects even
if the script runs in non-browser environment (in ASP page, in a
scripting host, or another application that supports scripting). Thus
with AXGate you can open such an application to more components. Note:
If you use newObjects Micro Script Host application to run small
scripts (ships with AXPack1 family and is also included with AXGate
for completeness) you do not need AXGate in order to create objects,
the hosts Host.CreateObject overcomes the system limitations on its
own.
