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