RASDial ActiveX Conrol


Updated May 18, 1997

Description

RASDial.OCX is an ActiveX control that interfaces many programming languages like Visual Basic, Access and Visual C++ 4.0 to the Remote Access Service provided by Windows 95 and Windows NT. It allows programmers to establish dialup networking connections automatically and close them down when needed.

Two versions of RASDial are available:

If you download version 2.0 from the COOL.STF homepage, you'll get constant nag screens. To remove the nag screens and to receive a registered version of the control, you need to order the registered version of RASDial. Please see our order page.

Compatibility

Version 1.2: Windows 95, Windows NT 3.51 or later
Version 2.0: Windows 95, Windows NT 4.0 beta 2 or later

Installation

Transfer RASDial.OCX to your Windows System folder. If using Version 2.0 of RASDial and Windows 95, you also need to transfer RNAPH.DLL to your Windows System folder. Once transferred, RASDial is registered by typing:

REGSVR32 \Windows\System\RASDial.OCX (Windows 95)
or
REGSVR32 \Winnt\System32\RASDial.OCX (Windows NT)

REGSVR32.EXE can be found on the Visual Basic 4.0 CD-ROM. If REGSVR32 fails, it's probably because you don't have the MFC 4.0 DLL library installed on your system. This is available from many sources on the Internet, including the COOL.STF homepage. Note that on Windows NT you must have RAS installed in order to register RASDial.

RASDial also comes with an example Visual Basic 4.0 program so you can learn how the control works by example. Make sure RASDial has been registered before loading the example project.

Support

Generally speaking, only registered version 2.0 users are supported. However, as time permits, we'll try to support version 1.2 and un-registered version 2.0. Send email to rod@coolstf.com with your questions.

Visual FoxPro Users

Because RASDial uses OLE events, you need to add the following code to the Load method of the form that contains RASDial:

_vfp.autoyield = .F.

and then the following code in the Unload method:

_vfp.autoyield = .T.

RAS Dial ActiveX Control

RAS Dial is used to establish and disconnect Remote Access connections.

Properties

CallbackNumber - string - Callback number if callback is requested (dialing to Windows NT only)

Domain - string - The Window NT domain to log onto. Defaults to '*' which signals the current domain

EntryName - string - Name of the entry to dial

Password - string - Password used for authentication

PhoneNumber - string - Phone number to dial if EntryName is blank

UserName - string - User name used for authentication

RasStatus - read only long - Returns either the RAS connection status or RAS error status. Returns zero if no connection is in process. Less than 600 indicates connection status, greater than 600 indicates an error.

AsyncMode - boolean - If set to true, as the RAS connection progresses the Status event is fired. If set to false, the Dial method will not return control until either the connection is made or fails.

ConnectString - string - version 2.0 only - Used to locate the "Connected to..." window displayed by Windows 95 RAS. This defaults to "Connected to " (note the trailing space). If you use a non-English version of Windows 95, fill this field with whatever RAS displays in the connection status Window.

Handle - long - version 2.0 only - Returns the handle associated with the RAS connection. This property should generally not be modified - it is provided for use with the RAS Information ActiveX control to allow existing connections to be hung-up.

Methods

Dial - Dials the connection. Returns status. Values less than 600 indicate status, greater than 600 indicate an error.

Hangup - Closes the connection

MinimizeRas - Windows 95 only - Minimizes the "Connected to..." window displayed by Windows 95 RAS.

Events

Status (rasconnstatus as long, dwerror as long) - Fires as each state in the connection occurs.

Programming Notes

The following lists things to watch out for when using this OLE control:

RAS Information ActiveX Control

RAS Information provides information about RAS. This control is only supplied with version 2.0 of RASDial.

Properties

None

Methods

GetConnections - Gets active connections via the ConnectionInformation event

GetCountries - Gets country codes, IDs and names via the CountryInformation event

GetDevices - Gets devices supported by RAS via the DeviceInformation event

GetEntries - Gets RAS phonebook entries via the EntryInformation event

Events

ConnectionInformation(Handle As Long, EntryName As String, DeviceType As String, DeviceName As String) - Fires for each active RAS connection (note than on Windows 95 there can only be one connection). Handle can be passed to the RAS Dial control to hangup an active connection.

CountryInformation(CountryID As Long, CountryCode As Long, CountryName As String) - Fires for each country that RAS supports. This information is needed when editing or creating phonebook entries.

DeviceInformation(DeviceName As String, DeviceType As String) - Fires for each device that RAS supports. This information is needed when editing or creating phonebook entries.

EntryInformation(EntryName As String) - Fires for each entry in the RAS phonebook.

Programming Notes

After using any of the methods in the RAS Information control, the code following the method statement will not be executed until the associated event has fired for each item of data required. If the method returns no data (for example using GetConnections with no active connections), the event will not fire and execution will continue with the following statement. For example:

Sub Command1_Click()
' Get entries in the RAS Phone Book.
RASInformation.GetEntries
' All done with getting entries
MsgBox "Got all entries"
End Sub

Private Sub RASInfo_EntryInformation(ByVal EntryName As String)
'Add each entry name to the list
List1.AddItem EntryName

End Sub

RAS Phone Book ActiveX Control

Allows RAS phonebook entries to be manipulated via either ActiveX properties or by displaying the standard Windows RAS dialogs. This control is only supplied with version 2.0 of RASDial.

Properties

AlternateOffset - long - Windows NT only - Specifies the offset from the beginning of the PhoneNumber string listing alternate phone numbers which will be dialed in order if the primary number fails to connect. The numbers are listed in consecutive null-terminated strings where two consecutive null characters indicate the end of the list.

AreaCode - string - Specifies the area code part of the telphone number.

CallBackNumber - string - Specifies the callback number if calling a Windows NT RAS server and the RAS server has the callback feature enabled for the user specified in UserName.

CountryCode - long - Specifies the country code for the RAS entry. Use the RAS Information ActiveX control GetCountries method to obtain a list of valid country codes.

CountryID - long - Specifies the country ID for the RAS entry. Use the RAS Information ActiveX control GetCountries method to obtain a list of valid country IDs.

DeviceName - string - Specifies the name of the device used by the RAS entry. Use the RAS Information ActiveX control GetDevices method to obtain a list of valid device names.

DeviceType - string - Specifies the name of the device type used by the RAS entry. Use the RAS Information ActiveX control GetDevices method to obtain a list of valid device types.

DisableLCPExtensions - boolean - Windows NT only - If set, the PPP LCP extensions defined in RFC 1570 are disabled. This may be necessary to connect to certain older PPP implementations, but interferes with features such as server-callback. This flag should be cleared unless specifically required.

DNSAddress - string - Specifies the Domain Name Server address used by the RAS connection if the TCP/IP protocol is enabled. This property must follow the standard IP dotted decimal notation, for example "204.157.123.4". If connecting to a server running DHCP, this property should contain "0.0.0.0"

DNSAddressAlt - string - Specifies the alternate Domain Name Server address used by the RAS connection if the TCP/IP protocol is enabled. This field must follow the standard IP dotted decimal notation, for example "204.157.123.4". If connecting to a server running DHCP, this property should contain "0.0.0.0"

Domain - string - Specifies the Windows NT domain to log onto if the NetworkLogon property is set true. Do not confuse Windows NT domains with Internet domain names - they are not the same thing.

EntryName - string - Specifies the RAS phonebook entry name.

FramePPP - boolean - Signals that PPP should be used as the framing protocol on the phone connection. PPP is the most popular method of dialup networking.

FrameSLIP - boolean - Signals that SLIP should be used as the framing protocol on the phone connection. SLIP is generally used by older systems, including Unix networks.

FrameRAS - boolean - Signals that the Microsoft RAS framing protocol be used on the phone connection. This protocol is used for connecting to Windows NT 3.1 servers or Windows for Workgroups.

Note: Only one of the above framing protocols may be set at any one time. Additionally at least one of the above framing protocols must be set.

FrameSize - long - Specifies the frame size used if the SLIP framing protocol is used. Valid values are 1006 and 1500.

HeaderCompression - boolean - If this flag is set, RAS will negotiate to use IP header compression on PPP connections. If this flag is not set, IP header compression will not be negotiated. This flag corresponds to the "Use IP Header Compression" checkbox in the TCP/IP settings dialog. It is normally advisable to set this flag since IP header compression significantly improves performance. The flag should only be cleared when connecting to a server which does not correctly negotiate IP header compression.

IPAddress - string - Contains the IP address used for the RAS connection if the TCP/IP protocol is enabled. If the server assigns addresses automatically, this property must be set to "0.0.0.0".

ISDNChannels - long - Windows NT only - Specifies the number of ISDN channels used when connecting via an ISDN device. Note that this field is only supported when the DeviceType is set to "isdn". Modem style ISDN Terminal Adapters (like the Motorola BitSurfr) are considered as modem devices and therefore do not support this property.

ModemLights - boolean - If this flag is set, the system task bar modem lights are enabled when the connection is active. Windows 95: This flag corresponds to the "Display modem status" checkbox on the Options page of the modem properties. These properties are accessed through the "configure" button on the phone book entry property page. Windows NT: This flag is currently ignored. The appearance of modem lights is controlled by the "Show modem and ISDN lights" checkbox on the global Dialing Preference-General dialog.

NetIPX - boolean - Signals that the IPX/SPX compatible protocol be used on the RAS connection.

NetNETBEUI - boolean - Signals that the NetBEUI protocol be used on the RAS connection.

NetTCPIP - boolean - Signals that the TCP/IP protocol be used on the RAS connection.

NetworkLogon - booleans - Specifies that RAS will attempt to log onto the Windows NT domain specified in the Domain property.

Password - string - not currently used. This field is ignored in the current version of RAS.

PasswordReturned - boolean - Signals after reading a phonebook entry if the Password field contains valid data. In the current version of RAS, this field is never set true.

PromoteAlternates - boolean - Windows NT only - Setting this flag applies when alternate phone numbers are defined by the AlternaltesOffset property. When set, alternate phone numbers that connect successfully are automatically promoted to primary phone number, bumping the current primary phone number down into the alternate list.

RemoteDefaultGateway - boolean - If this flag is set, then the default route for IP packets will be through the dial-up adapter when the connection is active. If this flag is clear, the default route will not be modified. This flag corresponds to the "Use default gateway on remote network" checkbox in the TCP/IP settings dialog.

RequireDataEncryption - boolean - Windows NT only - Setting this flag means data encryption must be negotiated successfully or the connection should be dropped. This flag is ignored unless RequireMSEncryptedPassword property is also set.

RequireEncryptedPassword - boolean - Setting this flag means that only secure password schemes can be used to authenticate the client with the server. This prevents the PPP driver from using the PAP plain-text authentication protocol to authenticate the client. CHAP, and SPAP authentication protocols are also supported. The flag should be cleared for increased interoperability and should be set for increased security.

RequireMSEncryptedPassword - boolean - Windows NT only - Setting this flag means that only Microsoft's secure password schemes can be used to authenticate the client with the server. This prevents the PPP driver from using the PPP plain-text authentication protocol or MD5-CHAP, MS-CHAP or SPAP. The flag should be cleared for maximum interoperability and should be set for maximum security. This flag takes precedence over the RequireEncryptedPassword property.

Script - string - Contains the name of the script file. The filename should be a full pathname. Windows NT: To indicate a Windows NT switch.inf script name set the first character of the name to "[".

SoftwareCompression - boolean - Setting this flag means that software compression will be negotiated on the link. This flag corresponds to the "enable software compression" checkbox on the "Server Type" dialog. Setting this flag causes the PPP driver to attempt to negotiate CCP with the server. The flag should be set by default but clearing this flag can reduce the negotiation period if the server does not support a compatible compression protocol.

SpecificIPAddress - boolean - If this flag is set, Dial-Up Networking will try to use the IP address specified by IPAddress as the IP address for the dial-up connection. If not set the value of the IPAddress property is ignored. Setting this flag corresponds to selecting the "Specify an IP address" setting in the TCP/IP settings dialog. Clearing it corresponds to selecting the "Server assigned IP address" setting in the TCP/IP settings dialog. Currently, an IP address set in the phonebook entry properties or retrieved from a server overrides the IP address set in the network control panel.

SpecificNameServers - boolean - Setting this flag corresponds to selecting the "Specify name server addresses" setting in the TCP/IP settings dialog. Clearing it corresponds to selecting the "Server assigned name server addresses" setting in the TCP/IP settings dialog.

TerminalAfterDial - boolean - Specifies that a terminal screen should be displayed after the modem connection has been completed.

TerminalBeforeDial - boolean - Specifies that a terminal screen should be displayed before RAS attempts to dial a connection.

UseCountryAndAreaCodes - boolean - If set, the CountryID, CountryCode, and AreaCode properties are used to construct the phone number. Otherwise, these fields are ignored. Windows NT: This flag corresponds to the "Use country and area codes" checkbox on the Phone dialog.

UseLogonCredentials - boolean - Windows NT only - Setting this flag causes the username, password, and domain of the currently logged on user to be used when dialing this entry. This flag is ignored unless the RequireMsEncryptedPassword property is also true. Note that this setting is ignored at RasDial API level where empty UserName and Password properties give the same result.

UserName - string - Specifies the user name used for authenticating on the remote system.

WINSAddress - string - Contains the IP address of the primary WINS server when using the TCP/IP protocol and NetBIOS over TCP/IP is enabled. This field must follow the standard IP dotted decimal notation, for example "204.157.123.4". If connecting to a server running DHCP, this property should contain "0.0.0.0"

WINSAddressAlt - string - Contains the IP address of the secondary WINS server when using the TCP/IP protocol and NetBIOS over TCP/IP is enabled. This field must follow the standard IP dotted decimal notation, for example "204.157.123.4". If connecting to a server running DHCP, this property should contain "0.0.0.0"

X25Address - string - Windows NT only - Set this property to "" unless the entry should dial using an X.25 PAD or native X.25 device. The field identifies the X.25 address to which you wish to connect.

X25Facilities - string - Windows NT only - The property specifies facilities you wish to request from your X.25 host at connection. This field is ignored unless X25Address property is filled in.

X25PadType - string - Windows NT only - Set this field to "" unless the entry should dial through an X.25 PAD. The field identifies the X.25 PAD type.

X25UserData - string - Windows NT only - The field specifies additional connection information supplied to the X.25 host at connection. This field is ignored unless X25Address property is filled in.

Methods

CreatePhonebookEntry - Adds an entry to the RAS phonebook by using the standard Windows dialog.

DeleteEntry - Deletes the RAS phonebook entry specified by the EntryName property.

EditPhonebookEntry - Edits the RAS phonebook entry specified by EntryName using the standard Windows dialog.

GetEntry - Retrieves the RAS phonebook entry specified by the EntryName property and sets the RAS Phone Book ActiveX properties to reflect the phonebook settings.

SetEntry - Writes a RAS phonebook entry, named by the EntryName property to the RAS phonebook. If the entry already exists, it will be overwritten, otherwise a new entry will be created.

ValidateEntryName - Verifies that the RAS phonebook entry named in EntryName is a valid phonebook entry. Generates an error if the name is invalid or already exists. This method is used to verify that a potential new RAS name is unique and valid.

Events

None

Programming Notes

If errors occur when using any of the above methods, the RAS Phone Book ActiveX control generates runtime errors. You can use the Visual Basic 'err' function to determine the error:

1000 - Unable to allocate memory for the operation
1001 - Invalid Phone Book name
1002 - Incorrectly formatted IP address
>1600 - RAS error code plus 1000. Subtract 1000 from this value to match the list of RAS errors

Note that the example program supplied with RASDial contains a .BAS module with all the errors that RAS can generate.