TMAGRAS - DELPHI RAS COMPONENT - RELEASE 4
==========================================
Last Updated: 5th November 1999, Release 4.10
by Angus Robertson, Magenta Systems Ltd, England
Email: delphi@magsys.co.uk, http://www.magsys.co.uk/delphi/
Copyright Magenta Systems Ltd, 1999.
Compatible with Delphi 3, 4 and 5 (but mainly tested on D5)
Windows 95, 98, NT 4.0 and Windows 2000/NT5
Overview
--------
TMagRas Release 4 is a set of installable Delphi non-visual
components, supplied with a demo program, for accessing Dial Up
Networking or Remote Access Services functions. This is a major update
of Daniel Polistchuck's and Mike Armstrong's earlier TRAS component
(little of which remains). It allows Delphi developers to add full
RAS functionality to their applications, including dialling and
monitoring multiple connections, creating and editing phonebooks
(without using Windows dialogs), and getting performance information for
connections. TMagRas supports Windows 95, 98, NT 4.0 and Windows 2000,
allowing an application to support all the various RAS extensions in
NT and W2K, including sub entries for multi-channel ISDN connections.
Performance statistics are returned separately for each connection in
NT4 and each channel in W2K.
TMagRas is supplied as three separate Delphi components, TMagRasCon
which includes dialling and monitoring and limited connection editing,
TMagRasPer with performance statistics, and TMagRasEdt to create and
edit connections/phonebooks. A demo program illustrates use of the
components, including monitoring multiple connections, creating a
simple new connection with minimal properties, and editing detailed
connection properties (seven tabs of settings) including Windows 2000
extensions.
TMagRas is copyrighted software, but the compiled component DCUs may be
used without cost in applications for use by the developer or within
their company but which are not otherwise distributed (including
freeware and shareware). The component source code may be licensed for
a cost of £100 (UKP) (£117.50 with tax), which is about $165 or 157 euro
less tax. Developers that license the source may distribute
applications using TMagRas. The compiled components are available for
Delphi 3, 4 and 5. Delphi 2 did not support COM/GUID so the source
API would need changes for that old version. At the time of writing,
documentation for TMagRas is sparse although a help file is planned by
the end of 1999. So if you don't understand how to use the components
from studying the demo program and the component properties (in the
magras?.prp files) you will either need to be patient until the help
file is completed, or license the component source code.
TRAS Release 3.0 will not be supported nor enhanced, but it still
being made available without cost, complete with Delphi source code, to
those that do not need the new functionality in TMagRas Release 4.0.
Please note that Release 3.0 did not allow connections/phonebooks to be
created or edited, except using dialogs.
Changes in TMagRas Release 4.00
1 - Added Ex versions of all main functions using a specified connection
handle rather than the internal one, to allow proper support for
multiple connections. The application will need to keep track of the
connection handles for each connection, to allow status to be requested
separately and for hang-up.
2 - All functions now use NT4 and W2K extensions dynamically, so the
same compiled application will run on all three platforms ignoring stuff
not supported. This means TMagRas will now start multilink ISDN calls
under NT4 and W2K.
3 - Added Subhandle handling to identify multilink ISDN calls separately
(GetSubHandle and GetSubHandles).
4 - Added some minimal TAPI functions to translate addresses
(TranslateAddr), but note there is no TAPI modem list so dialling
preferences always come from the first modem. The separate Magenta TAPI
component does all this properly.
5 - The event handlers how have properties to identify whether dialling
or status events are being made (StateEventSource), the connection
handle (StateRasConn) and from which subentry with multilink ISDN calls
(StateSubEntry). Note that, due to the requirement to handle multiple
calls, StateChanged events are no longer suppresed when they have not
changed, so the application must keep track of the status for each call.
6 - When listing active connections (GetConnections), the device name
and type, phonebook name, subentry and telephone number (NT only) are
now made available. A flag is set (ConnChangedFlag) when the connection
list changes to save the application needing to keep checking.
7 - Performance statistics have been separated from the main component,
to avoid the overhead in applications not needing this functionality.
All the main connection functions are in TMagRasCon (magrascon.pas),
performance statistics are in TMagRasPer (magrasper.pas) while full
editing of phonebooks is in TMagRasEdt (magrasedt.pas). Include files
are now magrasapi.pas, magtapiapi.pas and winperf.pas.
7 - Performance statistics now supports separate comms ports on NT4 and
separate connections (by handle) on W2K. The previous properties return
combined information for all connections, while separate information is
available from several arrays: PerfXmitCur, PerfRecvCur and PerfConnSpd
(not NT4), with PerfPortNam showing the NT comm port, and PerfRasConn
and PerfSubEnt needing to be set for W2K. Note that Win9x does not give
separate statistics for different connections and NT4 gives the same
statistics for each multilink connection.
8 - GetEntryProperties (in TMagRasCon) has been extended to return
AutodialDll, AutodialFunc, TotSubEntries (so you know whether to check
for multilink connection handles) and AltPhoneNrList which is a list of
alternate numbers to dial. For multilink connections, arrays include
the subentry details, SubDeviceType, SubDeviceName, SubDevicePort,
SubLocalPhoneNumber and SubPhoneCanonical.
9 - PutEntryProperties (in TMagRasCon) has been added to update minimal
properies in a phonebook, just PhoneCanonical, AutodialDll and
AutodialFunc. GetEntryProperties must be called before
PutEntryProperties. These two functions are used on the 'Some Props'
page in the demo application.
10 - Full editing of phonebooks has been added with TMagRasEdt.
GetAllEntryProps gets all the properties for a specified connection
including subentries. DefaultProps clears all connection properties,
PPPDefault clears and then defaults to minimal PPP, while
PutAllEntryProps creates a new named connection or updates an existing
connection. These functions are used in the 'Full Props' and 'Quick
New' pages of the demo application. The former displays all the
connection properties including multilink subentries and allows them to
be updated, it is very complicated! The latter is requests just the
minimal information to create a new PPP connection and should be easily
understood. Note that there is no validation in the connection of
properties being written to the connection, so saving may fail for
instance if you tick use a DNS address but leave it blank. Precise
behavious differs between platforms, but generally invalid properties
are simply ignored and reset. Full details of the properties are
available in the Microsoft API and MSDN documentation, part of which is
contained in the file 'rasentry.txt'.
Changes in TMagRas Release 4.10
1 - Performance statistics now support two adaptors for Win9x, so that
the devices used for the first two connections can now be monitored
separately. Note that Windows does not say which adaptor is monitoring
which connected, so they must be allocated sequentially.
2 - A performance statistics reset now clears all arrays so 'all' stats
restart correctly on NT4.
3 - Added DefCountryId propertry to ease created connections/phonebooks.
4 - No longer store component version on form.
5 - TotSubEntries is now set as 2 for Win9x ISDN multilink, but there
are no modem/dial details since the RAS API was never completed by
Microsoft.
6 - Changed TConnectionList.Clear to ClearFree to avoid overwrite
problem in D3.
Installation
------------
Since TMagRas does need design time properties, it need not be installed
on the component bar as such, but may be created in the application as
needed, as shown in the demo program.
Compiler versions of the component are distributed in separate sub
directories according to the compiler version. The API source is in the
root directory.
TAPI Functions
--------------
Note that Magenta Systems also has available some TAPI functions that
allow monitoring on modems and ISDN adaptors using events, avoiding
needing to continually poll using the RAS APIs. TAPI also monitors
non-RAS modem usage and will monitor incoming calls. A TAPI function is
also used to convert the canonical telephone number into a dialable
number according to telephony dialling properties (a basic version of
this is included in TMAgRasCon).
See the web site for more details on the TAPI functions.
Distribution
------------
TMagRas is distributed in three separate archives:
rasdem41.zip contains the executable demo program
rasobj41.zip contains the compiled component objects
rassrc41.zip contains the component source code
The first two archives may be downloaded from Magenta's web site at
http://www.magsys.co.uk/delphi/ and may be freely distributed via web
pages, FTP sites, BBS and conferencing systems or on CD-ROM in unaltered
zip format, but no charge may be made other than reasonable media or
bandwidth cost. If you list the component somewhere, even as a link,
please let us know so you can be informed of new versions.
The component source archive is currently distributed by email, to
licensed users only, and may be be distributed in an way.
Copyright Information
---------------------
TMagRas Release 4.10 is copyright Magenta Systems Ltd, England, 1999.
Magenta Systems Ltd
9 Vincent Road
Croydon
CR0 6ED
United Kingdom
Phone 020 8656 3636, International Phone +44 20 8656 3636
Fax 020 8656 8127, International Fax +44 20 8656 8127
If the above telephone numbers do not work outside the UK,
use the old London dialling code instead:
Phone +44 181 656 3636, Fax +44 181 656 8127
Email: delphi@magsys.co.uk
Web: http://www.magsys.co.uk/delphi/
There is also a support conference on the CIX conferencing system,
cix:magsoft. Information on joining CIX may be found at
http://www.cix.co.uk/.