Sascha Kimmel
March 2000

This is Windows®-specific (Windows 95, 98) and will not work on any other OS.

ras.zip [4,8k]         


Introduction

So you have finished developing your BETA program which uses some Internet functions.
But what if your program needs to connect to the Internet?
How can you realize this in BETA?
The answer is: it is possible by using the BETA library provided here.
This library makes it quite easy to connect to the Internet via Remote Access Service (RAS) or Dial-Up-Networking (DUN) as you probably know it.
The library only works on Windows (nti). It has been tested on Windows 98 and should almost work on Windows 95/NT/2000 as well - please let me know if it works for you if you are using one of the previously mentioned operation systems.


Overview

The library provides all necessary functions for connecting, disconnecting and getting information about the RAS connections installed on the client machine.
RAS is implemented as a single object, so that you need to instantiate one in your program. See below for details.

The following methods/attributes are available:

The RAS object

  • installed: check to see if RAS is installed on the machine
  • connect: connect to the Internet using a specific RAS entry
  • connectExt: like connect, except that you can provide username and password here
  • disconnect: disconnects all open RAS connections
  • isConnected: returns RAS status
  • noOfConnections: number of RAS connections currently in use
  • getConnectionName: returns the name of a specific connection
  • getConnections: returns all currently used connection names as an array
  • phonebook
    • entries: number of phonebook (*1) entries on the PC
    • getEntry: returns the name of a specific phonebook (*1) entry
    • getAll: returns all phonebook (*1) entries as an array

(*1) a phonebook entry is defined by Microsoft® as a DUN-connection which you can find in "My Computer" -> "Dial-Up Networking":


This example shows six phonebook entries (Windows® 98)


Usage

This is a sample program illustrating the use of the RAS object: 


...

myRAS:@RAS;
noOfConn,noOfEntries:@integer;
do

(** RAS **)

(** Check if RAS is installed on this machine **)
(if myRAS.installed 
	then 
	'RAS is installed!'->putLine;
	
	(** get all available connections **)
	myRAS.phonebook.Entries->noOfEntries->putInt; ' connection(s) found!'->PutLine;
	(for i:noOfEntries repeat i->putInt; ') '->putText; i->myRAS.phonebook.getEntry->putLine; for);
	
	(** already connected ? **)
	(if myRAS.isConnected 
		then
		'Already connected!'->putLine;
		
		(** How many RAS connections are currently active? **)
		'There are '->putText; myRAS.noOfConnections->noOfConn->putInt; ' connections active!'->putLine;
		
		(** Show the names of the active connections **)
		(for i:noOfConn repeat i->putInt; ') '->putText; i->myRAS.getconnectionName(# onError::(# do 'An Error occured!'->putLine #); #)->putLine; for);
		else
		
		(** else start to dial the following RAS entry **)
		('easyMSN analog')->myRAS.Connect(# onError::(# do 'An error occured: '->putText; which->putInt; newLine; #) #);
	if);
	else 
	'No RAS installed!'->putLine; 
if);

...
installed (OUT: @boolean)
Before trying to establish a connection or getting any phonebook entries you should always check if RAS is installed on the machine.
Returns TRUE if RAS is installed and FALSE otherwise.


phonebook
The phonebook consists of phonebook entries, which are defined by their unique name:
  • entries (OUT: @integer)
    Returns the number of phonebook entries available on this machine (@integer).
  • getEntry (IN: @integer; OUT: ^text)
    Returns a specific entry. Input is the specific entry number (<= this(phonebook).entries), returns an entry description as ^text.
    You simply get the name of the connection, e.g. "Arcor" (see screenshot above).
  • getAll (OUT: array:[entries]^text)
    Returns an array of ^text containing all phonebook entry names.


connect (IN: ^text)
Enter parameter is the name of the connection to be used for establishing the connection, e.g. "Arcor".
onError is called if an error occurs.
The username, password and TCP/IP, phone number settings are automatically pulled from the DUN configuration of the specific connection.
Please note: due to the current implementation the system is blocked until a connection is established or if an error occurs.
Future versions will also contain the possibility of getting the current status, e.g. dialing, authenticating etc.


connectExt (IN: ^text, ^text, ^text)
Like connect except that username and password have to be entered.


isConnected (OUT: @boolean)
Returns TRUE if at least one RAS connection is currently available, i.e. connected.
This also works if the connection was not initiated by your program, e.g. if the user established the connection manually.
You should always perform this check before using connect to avoid errors!


noOfConnections (OUT: @integer)
Returns the number of RAS connections currently available, ie.e connected.
If you do not have more than one modem this value will always be 0 (if not(isConnected)) or 1 (if isConnected).


getConnectionName (IN: @integer; OUT: ^text)
Returns the RAS description of the specific connection (if established).
This again is the textual description (i.e. name) of the DUN entry (see connect).


getConnections (OUT: array[noOfConnections]^text)
Returns an array of ^text containing all connection names.


disconnect
Disconnects ALL RAS connections.
Please note: Not only the connections established by your program will be terminated, all connections at all will be disconnected.
This normally is not a problem, because most users only have one modem connected.


Use of this library
This library is distributed "as is" without warranty of any kind.
You are allowed to use this library in your own programs (non-commercial and commercial) for free.


This text © 2000-2006 by tricos media. All rights reserved.
tricos Mediaservice is in no way affiliated with MjØlner Informatics.