TMAGRAS - DELPHI RAS COMPONENT - RELEASE 4.51
=============================================

Last Updated: 23 January 2001, Release 4.51
by Angus Robertson, Magenta Systems Ltd, England

Email: delphi@magsys.co.uk, http://www.magsys.co.uk/delphi/
Copyright Magenta Systems Ltd, 2001.

Compatible with Delphi 3, 4 and 5 (but tested only on D5)
Windows 95, 98, ME, NT 4.0, 2000 and Whistler (2002/Net).


Overview
--------

TMagRas Release 4 is a set of installable Delphi non-visual components,
supplied with several demo and example programs and a help file, for
accessing Dial Up Networking or Remote Access Services functions. 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, ME, NT4 and 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.  Seven example programs illustrate various aspects of the
components and may be copied to quickly add specific RAS functionality
to applications.

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 $150 or 160 euro
less tax.  Developers that license the source may distribute
applications using TMagRas without further cost.

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.  The component should be usable with Borland C++ Builder,
but currently OBJ files are not available so you will need to license
the source code and recompile.


Changes in TMagRas Release 4.51
-------------------------------

1 - Removed ConnectEx/ConnectNT 4.50 fix for fSubEntry not allowed as
zero so that W2K will again dial multilink.

2 - Default fSubEntry on creation to 1 so W2K does not dial multilink
(unless set to 0).

3 - Recognise Windows Whistler (aka 2002 or net), only basic testing so
far, seems OK.  Whistler added one new RAS API, RasDeleteSubEntry, but
this is not supported yet in TMagRasEdt.

4 - Corrected DisConnectEx so the timeout actually works and state
events are notified while waiting for timeout.  Existing applications may
now get one or more events that should have happened before, but didn't.

5 - Added TEncryptionType = encryptOptional which is the 'Typical'
default in W2K, and prevent the Windows dialog showing custom encryption.

6 - Added bCustomScript property for W2K.

7 - In TAPI event handler, only de-allocate calls in idle event, not
when disconnected.



Changes in TMagRas Release 4.50
-------------------------------

1 - All literals in the RAS and TAPI components have been moved to resource
strings for translation in magrasstr.pas and magtapistr.pas.  The Delphi
wizard can then be used to convert the strings into a resource file, or the
files could be changed to functions which return different languages
dynamically.

2 - Added onStateEvent (as an alternative to onStateChanged) which buffers
dial callback state messages to avoid dialling being blocked and possible
reentrancy issues (since callback can not be stopped).  It uses a queue to
avoid missing rapidly changing events. The event returns TRasStateRec with
all the state properties, rather than reading component properties that may
have already been changed by subsequent state changes.  Note that
CurDevName, CurDevType and ConnectPhoneNr are only set if the event source
is status (not dial).

This change has fixed a long term cosmetic problem in the demo program
where a second row appeared incorrectly in the ListView while a call was
being dialled.

3 - GetConnectStatusEx now updates CurDevName and CurDevType since the W2K
final now sets these correctly. ConnectPhoneNr is returned by NT4/W2K.
These settings are very useful to see if RAS connected using the device
specified in the phonebook entry (it may choose others) and to see what
phone number was really dialler (note it's the dialable format usually
starting with T (for tone dialling) and may include a calling card number,
so it not really suitable for displaying to users.

4 - Added ConnectNT similar to ConnectEx but NT4/W2K only, supports
dialextensions for paused states and speaker on/off.  The handle passed
must be zero to dial a new call, a non-zero handle will resume dialling a
call that has been paused for a callback number or authentication. Note
that paused states have not been tested yet!!

5 - Fixed an occasional problem in NT4 where performance statistics failed
by optionally using PDH.DLL (which must be redistributed) when the normal
registry version fails.  Tests show that only the RAS Total object returns
any data, so the RAS Port object code is currently disabled.

6 - In the TAPI component, on NT some ISDN had channel names starting from
0 not 1, so now allocate ports sequentially, 1/2/3/4 Win9x/NT, 2/1/4/3 W2K.
Also minor change to ensure call not returned if deallocated. Increased VPN
modems to 30. OnTapiStatus now sets tinfo2 to disconnect reason.



Changes in TMagRas Release 4.41
-------------------------------

1 - Corrected Str2IP so that it correctly converts IP addresses with a
single last digit and without trailing spaces (function rewitten).  This
problem meant that PutAllEntryProps sometimes ignored IP addresses,
unless they had trailing spaces (which TMaskEdit added in the demo
programs).

2 - Added IsIPStr to check an ASCII representation of an IP address is
valid.

3 - Improved validation of IP addresses, stop numbers > 255 and zero
first.

4 - In TMagRasCon, CreatePhonebook and EditPhonebook now both need
Application.Handle passed as a parameter.  This avoids the Forms unit
being included in some apps.  Graphics and Control units now conditional
as well to ease linking.


Changes in TMagRas Release 4.40
-------------------------------

1 - Added a help file and seven new simple example programs.

2 - Recognise Windows Millennium (aka WinMill)

3 - Compiled as TComponent again to allow use as an NT service.
Previously TMagRas was descended from TCustomControl to allow use in
an ActiveX (and may still be conditionally compiled by changing the
CUSTCNTL directive in the source). Warning: this change means that
applications compiled with TMagRas 4.0 to 4.3 will throw up errors on
the Height and Width properties that are now removed (but were never
used).

4 - Minor tidying up of unused properties and code.

5 - Added DPK package files to build a package from the TMagRas and
TMagTAPI components, to ease installation.  BPL/DPL/DCP files are not
supplied since these would double the zip size.


Changes in TMagRas Release 4.30
-------------------------------

1 - This version has been tested with Windows 2000 build 2195, which is
the final retail version.  GetDialParams no longer returns the
connection password, but what Microsoft call a 'handle' that is 16
asterisks. Passing this 'handle' back to SetDialParams causes the
existing password to be unchanged, and so Connect causes the existing
password to be used.  So if your applications checks that what is saved
is also returned, it will fail under W2K.  Avoided what appears to be a
bug in W2K whereby dialling properties were lost after saving an entry
and it's subentries - now save a second time after doing the subentries,
silly but it works.

2 - Added Str2IP to TMagRasEdt to convert and validate IP addresses.

3 - Added DUNVersion and DUNInfo properties to TMagRasCon to return the
DUN version.  A look-up table uses the build of RASAPI.DLL (in
DUNVersion) to create a version description like 'DUN 1.1/Win95/OSR2'
(in DUNInfo).

4 - Corrected PhoneNumber being ignored for dialling (error in 4.00 and
later), so the number dialled was always the default from the phonebook
entry.  You should set PhoneNumber to blank before calling Connect to
use the default number.

5 - GetEntryProperties now completes LocalPhoneNumber not PhoneNumber,
to avoid confusion when dialling calls.

6 - Added GetTransCaps which gets modem and country dialling properties
so we can offer better display of canonical numbers (we need to know the
local city code).  The function completes DialProps, DialLocation,
DialCard and DialCountry for the current dialling location.  Full
informtation on the content of these records is in the TAPI API info.

7 - Added UseCountryAndAreaCodes and PromoteAlternates properties for
use with dialling properties, and EntryOptions which is 32-bits of flags
where other properties are needed.



Changes in TMagRas Release 4.20
-------------------------------

1 - Make sure Win9x modem device configuration set correctly for new or
edited connections/phonebooks.  Previously an error would appear when
attempting to access modem properties when editing a phonebook using the
normal dialog.  Also set default modem device configuration when
updating Win9x connections, if it's missing.

2 - Structures are now available to edit the Win9x modem device info,
but the properties are not currently being processed.

3 - Corrected GetEntryProperties canonical phone number on NT4/W2K when
area code set but dialling properties disabled.


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.


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'.



Installation
------------

Since TMagRas does not 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 RASDEMO4 program.  However the
seven example programs do require TMagRas to be properly installed.

TMagRas is supplied in a zip file with common files such as the Help and
API sources in the root, the demo and example programs in /DEMO, and
three further directories containing the DCU/RES/DPK files for Delphi 3,
4 and 5.

To install the component, the files from the root and from ONE of the
Delphi directories should be copied into the same library directory,
typically a common directory used for third party components (like
LIBMISC).  This directory needs to be added to the Delphi Library Path
in Tools, Environment Options.  The MAGRASx0.DPK package file (where x
is the compiler version) should then be opened from File/Open.  Make
sure the DCP Output directory is the same as the DPK (in Options or
Environment Options), then compile the package, and it should be
automatically installed onto the Component palette.  Once installed,
open and compile one the example programs to check for errors.


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).  TMagTAPI is available free of charge
to users that license the source to TMagRas.  There is currently no help
file for the TAPI functions.  The TAPI functions do not support making
any calls at present.


Distribution
------------

TMagRas is distributed in three separate archives:

rasdem45.zip contains the executable demo program only.
rasobj45.zip contains the compiled component objects, help, demo and
   example programs (no executables).
rassrc45.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 code zip is available to licensed users only from a
restricted area of the web site, and may not be distributed in an way.


Copyright Information
---------------------

TMagRas is copyright Magenta Systems Ltd, England, 2001.

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/.


