TMAGRAS - DELPHI RAS COMPONENT - RELEASE 4
==========================================

Last Updated: 13th April 2000, Release 4.40
by Angus Robertson, Magenta Systems Ltd, England

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

Compatible with Delphi 3, 4 and 5 (but mainly tested on D5)
Windows 95, 98, NT 4.0 and 2000.   


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.  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 $165 or 157 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.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. 


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

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

2 - Recognise Windows ME (sort of)

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.  

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


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

TMagRas is distributed in three separate archives:

rasdem44.zip contains the executable demo program only. 
rasobj44.zip contains the compiled component objects, help, demo and 
   example programs (no executables). 
rassrc44.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 Release 4.40 is copyright Magenta Systems Ltd, England, 2000.

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

