EsRas ActiveX control

Eurosource, Gruvbyn 415, S-820 50 LOOS, Sweden
(info@eurosource.se) (http://www.eurosource.se)
Updated: 1999-01-10

This control encapsulate the RAS functions available in Windows. It is currently only available in a 32-bit version for use with Windows 95 and Windows NT. The control also support all the extended RAS functions to manipulate phonebook entries.

You can use the control to:

• Perform dial and logon to a remote network or computer. Do a job on a network(ed) computer and then terminate the connection.
• Define new RAS entries.
• Check on current RAS entries and connections.

If you look at all the properties for this control you may well feel overwhelmed but don't get scared. You can do a lot with this control with the use of very few properties. See the cookbook and the samples for examples on how to use the control. Also try the sample and most important look at the property values for predefined dial enteries. The structure is really simple. Properties that starts with Entry- belongs to ras-enteries and so on.

History

Build 51

Added HangupEx( hRasConn) method.
Added GetEntryDialParams method - Undocumented.
Added SetEntryDialParams method - Undocumented.
Some bugs on the NT platform fixed.
      

Installation

Transfer EsRas32.ocx to your \windows\system or \winnt35\system32 directory and register it by executing the command:

RegSvr32 \Windows\System\ESRAS32.OCX

RegSvr32.exe can be found on the Visual Basic 4.0 CD-ROM and in our ftp archive (http://www.eurosource.se ). If RegSvr32.exe 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 our ftp archive as MFC40DLL.ZIP. Regsvr32.exe is also included in this archive. If you want to check if you already got the files in mfc40dll.zip they are

mfc40.dll
msvcrt.dl
olepro32.dll
regsvr32.exe

To use this control you need the RASAPI32.DLL installed in your system and probably also the RNAPH.DLL that is shipped with EsRas. The functions in RNAPH.DLL will eventually be exported from the RASPAI32.DLL and making the RNAPH.DLL obsolete. For the same reason you have to ship the RNAPH.DLL with any application that use this control. This dll should be installed in the system directory.

The actual dependencys for the control is

msvcrt.dll
mfc42.dll
oleaut32.dll
olepro32.dll

On older systems you also need rnaph.dll. When you make installations you should include all of the above files.The control will register without the rnaph.dll but will be unusable on older systems. So your installation program should include this file as well. If your targe is Windows NT you can exclude it.

Cookbook or how to use the EsRas Control

Dialling using an existing phonebook entry.

1. If you are working in Windows NT and want to use another phonebook then the default, set the Phonebook property to the full path of the phonebook or NULL to use the default phonebook. In Windows 95 the registry is used so here it does not matter what you set this property to. The default phonebook is used in Windows NT if set to NULL.
2. Set the property EntryName to the phonebook entry you would like to dial.
3. Set the bUseCurrent property to False and call the GetEntryDialParms. This means that Dial should use the values that you used in your last successful RAS session to this EntryName host. These values are stored in the properties DialCallbackNumber, DialDomain, DialPassword, DialPhoneNumber and DialUserName. You can change any of them to use other values. This is the place to do that. If you would like to use your current logon credentials set bUseCurrent to TRUE.
4. Call the Dial method with the flag parameter set to 0.
5. Check the RasNotification event for a code equal to RASCS_Connected (se the constants.bas file) indicating a successful connection. You can also check the Connected event for a successful connect.
6. ……….Do what you have to do in the connected state……….
7. Use the HangUp method to terminate the connection. This is very important. If you don't use HangUp after a connection you will find yourself restarting your computer more often than before.

Defining a new phonebook entry under program control

1. Set the EntryName property to a unique name for your new entry.
2. Set all Entry- properties valid for your Entry. It can be good to first get default values for Entry- properties by calling the GetEntryProperties method.
3. Call the SetEntryProperties to set the new values.
4. Call the GetEntryDialParams method to get the dial parameters.
5. Set the properties DialCallbackNumber, DialUserName DialPassword DialDomain to the values of your choice.
6. Call SetEntryDialParams method to set the new values.

Hang up a connection initiated by another program

1. Call the DoEnumConnections method
2. In the  EnumConnection event you get both the ras handle and EntryName for all open connections. Use the HangUpEx method with the Ras-handle as argument to close the desired connection.

Properties
Methods
Events

Properties

AmbErrorNo
AmbNetBiosErrorString
AmbbLana
bUseCurrent
CountryInfoCountryID
CountryInfoCountryCode
CountryInfoNextCountryID
CountryInfoCountry
Connected
ConnState
DialPhoneNumber
DialCallbackNumber
DialUserName
DialfPassword
DialPassword
DialDomain
DialfPassword
DialExtOptions
DialExtUsePrefixSuffix
DialExtPausedStates
DialExtIgnoreModemSpeaker
DialExtSetModemSpeaker
DialExtIgnoreSoftwareCompression
DialExtSetSoftwareCompression
EntryName
EntryfOptions
EntryUseCountryAndAreaCodes
EntrySpecificIpAddr
EntrySpecificNameServers
EntryIpHeaderCompression
EntryRemoteDefaultGateway
EntryDisableLcpExtensions
EntryTerminalBeforeDial
EntryTerminalAfterDial
EntryModemLights
EntrySwCompression
EntryRequireEncryptedPw
EntryRequireMsEncryptedPw
EntryRequireDataEncryption
EntryNetworkLogon
EntryUseLogonCredentials
EntryPromoteAlternates
EntryCountryID
EntryCountryCode
EntryAreaCode
EntryLocalPhoneNumber
EntryIpAddr
EntryIpAddrDns
EntryIpAddrDnsAlt
EntryIpAddrWins
EntryIPAddrWinsAlt
EntryFrameSize
EntryNetProtocols
EntryProtocolsNetbeui
EntryProtocolsIpx
EntryProtocolsIp
EntryFramingProtocol
EntryFramingProtocolPpp
EntryProtocolSlip
EntryProtocolRas
EntryScript
EntryautoDialDll
EntryAutodialFunc
EntryDeviceType
EntryDeviceName
EntryX25PadType
EntryX25Address
EntryX25Facilities
EntryX25UserData
EntryChannels
ErrorNo
hRasConn
IpxErrorNo
IpxAddress
IPErrorNo
IpAddress
IpServerAddress
NbfErrorNo
NbfNetBiosErrorNo
NbfNetBiosErrorString
NbfWorkstationName
NbfbLana
Phonebook

note. Properties with a prefix of Entry belongs to the RASENTRY structure in rnaph.h and belongs to the entry information.

unsigned long AmbErrorNo

This property contains information about a remote access projection operation for a specified remote access component protocol in this case the result of a remote access server (RAS) Authentication Message Block (AMB) projection operation.

The property contains the result of the PPP control protocol negotiation. A value of zero indicates success. A nonzero value indicates failure, and is the actual fatal error that occurred during the control protocol negotiation, the error that prevented the projection from completing successfully.

Always check ErrorNo after reading this value to be certain that the value is correct. ErrorNo is 0 for a valid result or contains one of the following error codes.

ERROR_BUFFER_TOO_SMALL, ERROR_INVALID_HANDLE, ERROR_INVALID_PARAMETER, ERROR_INVALID_SIZE or

ERROR_PROTOCOL_NOT_CONFIGURED which means that the control protocol for which information was requested neither succeeded nor failed, because the connection's phonebook entry did not require that an attempt to negotiate the protocol be made. This is a RAS error code.

Remarks

Remote access projection is the process whereby a remote access server and a remote client negotiate network protocol-specific information. A remote access server uses this network protocol-specific information to represent a remote client on the network.

Windows NT: Remote access projection information is not available until the operating system has executed the RasDial RASCS_Projected state on the remote access connection. If this property is read prior to the RASCS_Projected state, it returns ERROR_PROJECTION_NOT_COMPLETE.

Windows 95: Windows 95 Dial-Up Networking does not support the RASCS_Projected state. The projection phase may be done during the RASCS_Authenticate state. If the authentication is successful, the connection operation proceeds to the RASCS_Authenticated state, and projection information is available for successfully configured protocols. If this property is read prior to the RASCS_Authenticated state, it returns ERROR_PROTOCOL_NOT_CONFIGURED.

LPSTR AmbNetBiosErrorString

This property contains information about a remote access projection operation for a specified remote access component protocol in this case the result of a remote access server (RAS) Authentication Message Block (AMB) projection operation.

If AmbErrorNo has the value ERROR_NAME_EXISTS_ON_NET, this property contains a zero-terminated string that is the NetBIOS name that caused the conflict. For other values for the AmbErrorNo property, this property contains a null string.

Always check ErrorNo after reading this value to be certain that the value is correct. ErrorNo is 0 for a valid result or contains an error code. The error codes is described under AmbErrorNo property.

short AmbbLana

This property contains information about a remote access projection operation for a specified remote access component protocol in this case the result of a remote access server (RAS) Authentication Message Block (AMB) projection operation.

Identifies the NetBIOS network adapter identifier, or LANA, on which the remote access connection was established. This member contains the value 0xFF if a connection was not established.

Always check ErrorNo after reading this value to be certain that the value is correct. ErrorNo is 0 for a valid result or contains an error code. The error codes is described under AmbErrorNo property.

BOOL bUseCurrent

Set this property to TRUE to use the current logon credentials when you use the Dial method.

unsigned long CountryInfoCountryID

Specifies the TAPI Country ID. Setting this property to a value retrieves the other CountryInfo-properties ( CountryInfoCountryCode, CountryInfoCountry and CountryInfoNextCountryID ).

To enumerate all of the known country information, the property CountryInfoCountryID should be set to 1. The function will return the information of the first country in the list along with the next country ID in the property CountryInfoNextCountryID. This value can then be used to request the information for the next country. The information for the last country will be returned with the property CountryInfoNextCountryID set to 0.

unsigned long CountryInfoCountryCode

Specifies the TAPI Country Code. Read only.

unsigned long CountryInfoNextCountryID

Specifies the next TAPI Country ID.

unsigned long CountryInfoCountry

Specifies the Country in real text as a null terminated string.

BOOL Connected

This readonly property returns TRUE if in connected state and otherwise False.

A CTL_E_INVALIDPROPERTYVALUE error is thrown if an error occurs during the read of the state. The property ErrorNo can also be set if an error occurs.

Short ConnState

This readonly property returns the connection state as defined by RASCONNSTATE as follows

typedef enum _RASCONNSTATE {
    RASCS_OpenPort = 0,
    RASCS_PortOpened,
    RASCS_ConnectDevice,
    RASCS_DeviceConnected,
    RASCS_AllDevicesConnected,
    RASCS_Authenticate,
    RASCS_AuthNotify,
    RASCS_AuthRetry,
    RASCS_AuthCallback,
    RASCS_AuthChangePassword,
    RASCS_AuthProject,
    RASCS_AuthLinkSpeed,
    RASCS_AuthAck,
    RASCS_ReAuthenticate,
    RASCS_Authenticated,
    RASCS_PrepareForCallback,
    RASCS_WaitForModemReset,
    RASCS_WaitForCallback,
    RASCS_Projected,
    RASCS_StartAuthentication, // Windows 95 only
    RASCS_CallbackComplete, // Windows 95 only
    RASCS_LogonNetwork, // Windows 95 only
    RASCS_Interactive = RASCS_PAUSED,
    RASCS_RetryAuthentication,
    RASCS_CallbackSetByCaller,
    RASCS_PasswordExpired,
    RASCS_Connected = RASCS_DONE,
    RASCS_Disconnected
} RASCONNSTATE ;

A CTL_E_INVALIDPROPERTYVALUE error is thrown if an error occurs during the read of the state. The ErrorNo property can also be set if an error occurs during the Dial.

-1 is returned if there is no connection.

Long hRasConn

Handle for an open connection or NULL.

LPSTR DialPhoneNumber

The phone number for a phonebook entry.

LPSTR DialCallbackNumber

The callback number for a phonebook entry.

LPSTR DialUserName

The User name for a phonebook entry.

LPSTR DialPassword

The password for a phonebook entry. Se also the property DialfPassword.

LPSTR DialDomain

The domain for a phonebook entry.

BOOL DialfPassword

True if the password in the DialPassword property is valid.

Unsigned long DialExtOptions

The RASDIALEXTENSIONS structure contains information about extended features of the Dial method. You can enable one or more of these extensions by passing a pointer to a RASDIALEXTENSIONS structure when you execute the Dial method. If you do not pass a pointer to a RASDIALEXTENSIONS structure to Dial it uses the default settings that are noted bellow.

RDEOPT_UsePrefixSuffix

If this bit flag is one, Dial uses the prefix and suffix that is in the RAS phonebook. If this bit flag is zero, Dial ignores the prefix and suffix that is in the RAS phonebook.

If no phonebook entry name is specified in the call to Dial, the actual value of this bit flag is ignored, and it is assumed to be zero.

RDEOPT_PausedStates

If this bit flag is one, Dial accepts paused states. Examples of paused states are terminal mode, retry logon, change password, and set callback number. If this bit flag is zero, Dial reports a fatal error if it enters a paused state.

RDEOPT_IgnoreModemSpeaker

If this bit flag is one, Dial ignores the modem speaker setting that is in the RAS phonebook, and uses the setting specified by the RDEOPT_SetModemSpeaker bit flag. If this bit flag is zero, Dial uses the modem speaker setting that is in the RAS phonebook, and ignores the setting specified by the RDEOPT_SetModemSpeaker bit flag.

If no phonebook entry name is specified in the call to Dial, the choice is between using a default setting or the setting specified by the RDEOPT_SetModemSpeaker bit flag. The default setting is used if RDEOPT_IgnoreModemSpeaker is zero. The setting specified by RDEOPT_SetModemSpeaker is used if RDEOPT_IgnoreModemSpeaker is one.

RDEOPT_SetModemSpeaker

If this bit flag is one, and RDEOPT_IgnoreModemSpeaker is one, Dial sets the modem speaker on. If this bit flag is zero, and RDEOPT_IgnoreModemSpeaker is one, Dial sets the modem speaker off. If RDEOPT_IgnoreModemSpeaker is zero, Dial ignores the value of RDEOPT_SetModemSpeaker, and sets the modem speaker based on the RAS phonebook setting or the default setting.

RDEOPT_IgnoreSoftwareCompression

If this bit flag is one, Dial ignores the software compression setting that is in the RAS phonebook, and uses the setting specified by the RDEOPT_SetSoftwareCompression bit flag. If this bit flag is zero, Dial uses the software compression setting that is in the RAS phonebook, and ignores the setting specified by the RDEOPT_SetSoftwareCompression bit flag. If no phonebook entry name is specified in the call to Dial, the choice is between using a default setting or the setting specified by the RDEOPT_SetSoftwareCompression bit flag. The default setting is used if RDEOPT_IgnoreSoftwareCompression is zero. The setting specified by RDEOPT_SetSoftwareCompression is used if RDEOPT_IgnoreSoftwareCompression is one.

RDEOPT_SetSoftwareCompression

If this bit flag is one, and RDEOPT_IgnoreSoftwareCompression is one, Dial uses software compression. If this bit flag is zero, and RDEOPT_IgnoreSoftwareCompression is one, Dial does not use software compression. If RDEOPT_IgnoreSoftwareCompression is zero, Dial ignores the value of RDEOPT_SetSoftwareCompression, and sets the software compression state based on the RAS phonebook setting or the default setting.

The default value for each of these bit flags is zero.

Each of this bits can be set/read by the following Boolean properties.

DialExtUsePrefixSuffix, DialExtPausedStates, DialExtIgnoreModemSpeaker, DialExtSetModemSpeaker, DialExtIgnoreSoftwareCompression, DialExtSetSoftwareCompression

Bool DialExtUsePrefixSuffix

If this property is True, Dial uses the prefix and suffix that is in the RAS phonebook. If this property is False, Dial ignores the prefix and suffix that is in the RAS phonebook.

If no phonebook entry name is specified in the call to Dial, the actual value of this bit flag is ignored, and it is assumed to be set to False.

Se also the property DialExtOptions where all of the bits can be set/reset and read in one operation.

Bool DialExtPausedStates

If this property is set to True, Dial accepts paused states. Examples of paused states are terminal mode, retry logon, change password, and set callback number. If this property is set to False, Dial reports a fatal error if it enters a paused state.

Se also the property DialExtOptions where all of the bits can be set/reset and read in one operation.

Bool DialExtIgnoreModemSpeaker

If this property is set to True, Dial ignores the modem speaker setting that is in the RAS phonebook, and uses the setting specified by the SetModemSpeaker property. If this property is False, Dial uses the modem speaker setting that is in the RAS phonebook, and ignores the setting specified by the SetModemSpeaker property.

If no phonebook entry name is specified in the call to Dial, the choice is between using a default setting or the setting specified by the SetModemSpeaker property. The default setting is used if IgnoreModemSpeaker is False. The setting specified by SetModemSpeaker is used if IgnoreModemSpeaker is set to True.

Se also the property DialExtOptions where all of the bits can be set/reset and read in one operation.

Bool DialExtSetModemSpeaker

If this property is set to True and the property IgnoreModemSpeaker is True, Dial sets the modem speaker on. If this property is False and IgnoreModemSpeaker is True, Dial sets the modem speaker off. If the IgnoreModemSpeaker property is False, Dial ignores the value of the SetModemSpeaker property, and sets the modem speaker based on the RAS phonebook setting or the default setting.

Se also the property DialExtOptions where all of the bits can be set/reset and read in one operation.

Bool DialExtIgnoreSoftwareCompression

If this property is set to True, Dial ignores the software compression setting that is in the RAS phonebook, and uses the setting specified by the SetSoftwareCompression property. If this property is False, Dial uses the software compression setting that is in the RAS phonebook, and ignores the setting specified by the SetSoftwareCompression property.

If no phonebook entry name is specified in the call to Dial, the choice is between using a default setting or the setting specified by the SetSoftwareCompression property. The default setting is used if the IgnoreSoftwareCompression property is False. The setting specified by the SetSoftwareCompression property is used if the IgnoreSoftwareCompression property is set to True.

Se also the property DialExtOptions where all of the bits can be set/reset and read in one operation.

Bool DialExtSetSoftwareCompression

If this property is set to True, and the property IgnoreSoftwareCompression is set to True, Dial uses software compression. If this property is set to False and the IgnoreSoftwareCompression property is set to True, Dial does not use software compression. If the IgnoreSoftwareCompression property is set to False, Dial ignores the value of the SetSoftwareCompression property, and sets the software compression state based on the RAS phonebook setting or the default setting.

Se also the property DialExtOptions where all of the bits can be set/reset and read in one operation.

LPSTR EntryName

Get/sets the current EntryName.

If this property is set with an invalid EntryName a CTL_E_INVALIDPROPERTYVALUE error is thrown. The ErrorNo property is set to the actual error wish can be ERROR_INVALID_NAME.

If you set this property to an EntryName that is available in the current phonebook the data for this entry is fetched and stored in the Entry-properties. This is the same as calling the GetEntryProperties method.

When you set this property to a string that is not available in the current phonebook defaults are set for most of the Entry-properties. You can thus set it to an empty string to obtain default properties.

Windows 95: The following characters are not allowed in an entryname.

• | vertical bar
• > greater than symbol
• < less than symbol
• ? question mark
• * asterisk
• \ backward slash
• / forward slash
• : colon
  

Windows NT: The entry name should not begin with a "."

unsigned long EntryfOptions

Specifies connection options.

Holds the dwfOptions value in the RASENTRY structure. This value is also available in the form of several BOOL properties describing each of the bits in dwfOptions.

Specifies connection options. One or more of the following flags can be set :

BOOL EntryUseCountryAndAreaCodes

If set, the EntryCountryID, EntryCountryCode, and EntryAreaCode properties are used to construct the phone number. Otherwise, these properties is ignored.

Windows NT: This flag corresponds to the "Use country and area codes" checkbox on the Phone dialog.

Se also the property EntryfOptions.

BOOL EntrySpecificIpAddr

If this flag is True, Dial-Up Networking will try to use the IP address specified by EntryIpaddr as the IP address for the dial-up connection. If set to false the value of the EntryIpaddr property is ignored.

Setting the RASEO_SpecificIpAddr flag corresponds to selecting the "Specify an IP address" setting in the TCP/IP settings dialog. Clearing the RASEO_SpecificIpAddr flag 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.

Se also the property EntryfOptions.

BOOL EntrySpecificNameServers

If this flag is set to True, the EntryIpaddrDns, EntryIpaddrDnsAlt, EntryIpaddrWins, and EntryIpaddrWinsAlt properties are used to specify the name server addresses for the dial-up connection. If this flag is set to False, Dial-Up Networking will ignore the properties EntryIpaddrDns, EntryIpaddrDnsAlt, EntryIpaddrWins, and EntryIpaddrWinsAlt

Setting the RASEO_SpecificNameServers flag corresponds to selecting the "Specify name server addresses" setting in the TCP/IP settings dialog. Clearing the RASEO_SpecificNameServers flag corresponds to selecting the "Server assigned name server addresses" setting in the TCP/IP settings dialog.

Windows 95: Currently, if a DNS address is set in the network control panel then the address set via the phonebook entry properties or retrieved from a server will be ignored. In other words, the addresses in the network control panel override the addresses in the phonebook entry properties. (note : that this is the opposite of the client IP address behavior)

Se also the property EntryfOptions.

BOOL EntryIpHeaderCompression

If this flag is set to True, Dial-Up Networking will negotiate to use IP header compression on PPP connections.

If this flag is set to False, 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.

Se also the property EntryfOptions.

BOOL EntryRemoteDefaultGateway

If this flag is set to True, 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.

Se also the property EntryfOptions.

BOOL EntryDisableLcpExtensions

If set to True, 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 set to False unless specifically required.

Windows 95: This flag is currently ignored by Windows 95

Se also the property EntryfOptions.

BOOL EntryTerminalBeforeDial

Display a terminal window for user input before dialing the connection.

Windows 95: This flag corresponds to the "Bring up terminal window before dialing" checkbox on the Options page of the modem properties. These properties are accessed through the "configure" button on the phone book entry property page.

Se also the property EntryfOptions.

BOOL EntryTerminalAfterDial

Display a terminal window for user input after dialing the connection.

This flag should not be set to True if a dial-up networking script is to be associated with the connection since scripting has it's own terminal implementation.

Windows 95: This flag corresponds to the "Bring up terminal window after dialing" checkbox on the Options page of the modem properties. These properties are accessed through the "configure" button on the phone book entry property page.

Se also the property EntryfOptions.

BOOL EntryModemLights

If this flag is set, the system task bar modem lights are enabled when the connection is active.

Windows 95 recommendations : This flag should be set to True if the application using the phonebook entry does not provide an alternate activity monitor.

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.

Se also the property EntryfOptions.

BOOL EntrySwCompression

Setting this flag to True 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 to True by default but if set to False this flag can reduce the negotiation period if the server does not support a compatible compression protocol.

Se also the property EntryfOptions.

BOOL EntryRequireEncryptedPw

Setting this flag to True 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.

Windows 95: This flag corresponds to the "Require encrypted password" checkbox on the "Server Type" dialog.

Windows NT: This flag corresponds to the "Require encrypted password" checkbox on the "Security" dialog. See also the property EntryRequireMsEncryptedPw.

Se also the property EntryfOptions.

BOOL EntryRequireMsEncryptedPw

Setting this flag to True 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 EntryRequireEncryptedPw property.

Windows NT: This flag corresponds to the "Require Microsoft encrypted password" checkbox on the "Security" dialog. See also EntryRequireDataEncryption.

Windows 95: This flag is currently ignored by Windows 95

Se also the property EntryfOptions.

BOOL EntryRequireDataEncryption

Setting this flag to True means data encryption must be negotiated successfully or the connection should be dropped. This flag is ignored unless the EntryRequireMsEncryptedPw property is also set.

Windows NT: This flag corresponds to the "Require data encryption" checkbox on the "Security" dialog.

Windows 95: This flag is currently ignored by Windows 95

Se also the property EntryfOptions.

BOOL EntryNetworkLogon

Setting this flag instructs dial-up networking to log on to the network after the point to point connection is established.

Windows 95: This flag corresponds to the "Log on to Network" checkbox on the "Server Type" dialog. This flag should be set when the client is logging on to networks where the user must be logged on to access file servers. This flag should not be set for internet access since the network that is being accessed has no servers to authenticate the client.

Windows NT: This flag currently has no effect on Windows NT.

Se also the property EntryfOptions.

BOOL EntryUseLogonCredentials

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 property EntryRequireMsEncryptedPw is also set to True. Note that this setting is ignored at RasDial API level where empty szUserName and szPassword arguments give the same result.

Windows NT: This flag corresponds to the "Use current username and password" checkbox on the Security dialog.

Windows 95: This flag is ignored by Windows 95

Se also the property EntryfOptions.

BOOL EntryPromoteAlternates

New Behaviour Please ignore!!!!!

Setting this flag applies when alternate phone numbers are defined by the EntryAlternaltesOffset property. When set to True, alternate phone numbers that connect successfully are automatically promoted to primary phone number, bumping the current primary phone number down into the alternate list.

Windows NT: This flag corresponds to the checkbox on the Alternate Numbers dialog.

Windows 95: This flag is currently ignored by Windows 95

Se also the property EntryfOptions.

Unsigned long EntryCountryID

Specifies the TAPI Country ID. Se the CountryInfoCountryID property for info on how to enumerate country identifiers. See the property EntryUseCountryAndAreaCodes above.

Unsigned long EntryCountryCode

Specifies the country code portion of the phone number. The country code must match the country ID retrieved using the CountryInfoCountryID property. See the property EntryUseCountryAndAreaCodes above. If the country code is null, the code will be set automatically based on the country ID

LPSTR EntryAreaCode

Specifies the area code as a character string. The area code should be an empty string if the location does not have an area code. See property EntryUseCountryAndAreaCodes above. The area code should not contain brackets or other delimiters e.g. "206" is a valid area code. "(206)" is not.

CTL_E_INVALIDPROPERTYVALUE is thrown if the Areacode string is to long (>RAS_MaxAreaCode).

LPSTR EntryLocalPhoneNumber

Specifies the telephone number as a null-terminated string. The entire phone number can be supplied here, or can be broken up into area and country codes. The difference is the way the property appears to the user when edited. See the property EntryUseCountryAndAreaCodes.

CTL_E_INVALIDPROPERTYVALUE is thrown if the Areacode string is to long (>RAS_MaxPhoneNumber).

LPSTR EntryIpAddr

Specifies the IP address to be used while this connection is active. See the property EntrySpecificIpAddr.

If a bad IP address is supplied or if the IP address string has a length greater than RAS_MaxIpAddress a CTL_E_INVALIDPROPERTYVALUE error is thrown.

LPSTR EntryIpAddrDns

Specifies the IP address of the DNS server to be used while this connection is active. See the property EntrySpecificNameServers.

If a bad IP address is supplied or if the IP address string has a length greater than RAS_MaxIpAddress a CTL_E_INVALIDPROPERTYVALUE error is thrown.

LPSTR EntryIpAddrDnsAlt

Specifies the IP address of a secondary or backup DNS server to be used while this connection is active. See the property EntrySpecificNameServers.

If a bad IP address is supplied or if the IP address string has a length greater than RAS_MaxIpAddress a CTL_E_INVALIDPROPERTYVALUE error is thrown.

LPSTR EntryIpAddrWins

Specifies the IP address of the WINS server to be used while this connection is active. See the property EntrySpecificNameServers.

If a bad IP address is supplied or if the IP address string has a length greater than RAS_MaxIpAddress a CTL_E_INVALIDPROPERTYVALUE error is thrown.

LPSTR EntryIPAddrWinsAlt

Specifies the IP address of a secondary WINS server to be used while this connection is active. See the property EntrySpecificNameServers.

If a bad IP address is supplied or if the IP address string has a length greater than RAS_MaxIpAddress a CTL_E_INVALIDPROPERTYVALUE error is thrown.

long EntryFrameSize

Specifies the network protocol frame size. This is currently ignored unless the framing protocol is Slip. The value should be either 1006 or 1500.

Windows 95: This property is currently ignored by Windows 95

A CTL_E_INVALIDPROPERTYVALUE error is thrown if the value is set to something other than 1006 or 1500.

usigned long EntryNetProtocols

Specifies the network protocols to negotiate.

Windows 95: The protocol will only be negotiated if the corresponding network stack is bound to the dial-up adapter. This bit vector corresponds to the "Allowed Network Protocols" section of the "Server Type" dialog.

One or more of the following flags can be set.

Warning! Use this property with extreme care as no check for validity of the data is performed. Use the Boolean properties instead.

There are Boolean properties for each of these flags. EntryProtocolsNetbeui, EntryProtocolsIpx and EntryProtocolsIp which you can both read and set the flags.

BOOL EntryProtocolsNetbeui

If set to True the NETBEUI protocol will be negotiated.

Equivalent to specifying RASNP_Netbeui in the property EntryNetProtocols

BOOL EntryProtocolsIpx

If set to True the IPX protocol will be negotiated.

Equivalent to specifying RASNP_Ipx in the property EntryNetProtocols

BOOL EntryProtocolsIp

If set to True the IP (Internet) protocol will be negotiated.

Equivalent to specifying RASNP_Ip in the property EntryNetProtocols

unsigned long EntryFramingProtocol

Specifies the framing protocol used by the server. PPP is the emerging standard. SLIP is used mainly in UNIX environments.

Note : To use Compressed SLIP, set the RASFP_Slip option and the IP header compression flag.

Warning! Use this property with extreme care as no check for validity of the data is performed. Use the Boolean properties instead.

There are boolan properties for each of these flags. EntryFramingProtocolPpp, EntryProtocolSlip and EntryProtocolRas.

BOOL EntryFramingProtocolPpp

Specifies that the framing protocol used to connect to the server should be Point-to-Point Protocol (PPP). PPP is the emerging standard.

Equivalent to specifying RASFP_Ppp in the property EntryNetProtocols

BOOL EntryProtocolSlip

Specifies that the framing protocol used to connect to the server should be Serial Line Internet Protocol (SLIP). SLIP is used mainly in UNIX environments.

Equivalent to specifying RASFP_Slip in the property EntryNetProtocols

BOOL EntryProtocolRas

Specifies that the framing protocol used to connect to the server should be RAS. This is a Microsoft proprietary protocol implemented in NT 3.1 and WfW 3.11

Equivalent to specifying RASFP_Ras in the property EntryNetProtocols

LPSTR EntryScript

A null-terminated string containing 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 "[".

LPSTR EntryautoDialDll

A null-terminated string containing the filename of the Dynamic-Linked Library for the customized auto-dial handler. The filename should be a full pathname. If the property contains an empty string, the default dialing User Interface is used and the property EntryAutodialFunc is ignored.

LPSTR EntryAutodialFunc

A null-terminated string containing the exported name of the function for the customized auto-dial handler. The auto-dial handler function has the following prototype:

BOOL WINAPI AutoDialHandler(
    HWND hwndParent,
    LPCSTR lpszEntry,
    DWORD dwFlags,
    LPDWORD pdwRetCode
);

Parameters

hwndParent
A handle of the parent window.

lpszEntry
Points to a null terminated string that specifies the phonebook entry to use.

dwFlags
Reserved; must be zero.

lpdwRetCode
Points to a DWORD that will be filled in with ERROR_SUCCESS or an error code on exit.

Return Value
If the auto-dial handler wishes to dial, it should do so by presenting its own dialing User Interface and calling the RasDial function to do the actual dialing. It should then return TRUE to indicate that it took over the dialing, and return ERROR_SUCCESS or an error code in lpdwRetCode if the dialing succeeded or failed, respectively. If the auto-dial handler does not wish to dial, it should return FALSE and the default dialing User Interface will be used.

LPSTR EntryDeviceType

A null-terminated string indicating the RAS device type referenced by the property EntryDeviceName which can be one of the following string constants:

Windows 95: The X.25 device type is not currently supported by Windows 95

If set to something else then the above strings a CTL_E_INVALIDPROPERTYVALUE error is thrown

LPSTR EntryDeviceName

A null-terminated string containing the name of the TAPI device to use with this phonebook entry. See the method DoEnumDevices.

LPSTR EntryX25PadType

Set this property to "" unless the entry should dial through an X.25 PAD. The property identifies the X.25 PAD type.

Windows NT : On Windows NT, this currently maps to a section name in PAD.INF.

Windows 95 : This property is currently ignored by Windows 95.

LPSTR EntryX25Address

Set this property to "" unless the entry should dial using an X.25 PAD or native X.25 device. The property identifies the X.25 address to which you wish to connect.

Windows 95 : This property is currently ignored by Windows 95.

LPSTR EntryX25Facilities

The property specifies facilities you wish to request from your X.25 host at connection. This property is ignored unless EntryX25Address in filled.

Windows 95 : This property is currently ignored by Windows 95.

LPSTR EntryX25UserData

The property specifies additional connection information supplied to the X.25 host at connection. This property is ignored unless EntryX25Address in filled.

Windows 95 : This property is currently ignored by Windows 95.

unsigned long EntryChannels

This Property indicates the number of B-channels to aggregate for this connection. The property is ignored unless a device type of "isdn" is specified. A typical value is 2.

long ErrorNo

Contains the last error code. The code can be one of the following.

unsigned long IpxErrorNo

This property contains information about a remote access projection operation for a specified remote access component protocol in this case the result of a PPP Internetwork Packet Exchange (IPX) projection operation.

Contains the result of the PPP control protocol negotiation. A value of zero indicates success. A nonzero value indicates failure, and is the actual fatal error that occurred during the control protocol negotiation, the error that prevented the projection from completing successfully.

Always check the ErrorNo property after reading this value to be certain that the value is correct. ErrorNo is 0 for a valid result or contains an error code. The error codes is described under AmbErrorNo property.

LPSTR IpxAddress

This property contains information about a remote access projection operation for a specified remote access component protocol in this case the result of a PPP Internetwork Packet Exchange (IPX) projection operation.

Contains a zero-terminated string that is the client's IPX address on the RAS connection. This address string has the form net.node; for example, "1234ABCD.12AB34CD56EF".

Always check ErrorNo after reading this value to be certain that the value is correct. ErrorNo is 0 for a valid result or contains an error code. The error codes is described under AmbErrorNo property.

unsigned long IPErrorNo

This property contains information about a remote access projection operation for a specified remote access component protocol in this case the result of a PPP Internet Protocol (IP) projection operation.

Contains the result of the PPP control protocol negotiation. A value of zero indicates success. A nonzero value indicates failure, and is the actual fatal error that occurred during the control protocol negotiation, the error that prevented the projection from completing successfully.

Always check ErrorNo after reading this value to be certain that the value is correct. ErrorNo is 0 for a valid result or contains an error code. The error codes is described under AmbErrorNo property.

LPSTR IpAddress

This property contains information about a remote access projection operation for a specified remote access component protocol in this case the result of a PPP Internet Protocol (IP) projection operation.

Contains a zero-terminated string that is the client's IP address on the RAS connection. This address string has the form a.b.c.d; for example, "11.101.237.71".

Always check ErrorNo after reading this value to be certain that the value is correct. ErrorNo is 0 for a valid result or contains an error code. The error codes is described under AmbErrorNo property.

LPSTR IpServerAddress

This property contains information about a remote access projection operation for a specified remote access component protocol in this case the result of a PPP Internet Protocol (IP) projection operation.

Contains a null-terminated string that is the IP address of the remote PPP peer (that is, the server's IP address). This string is in "a.b.c.d" form. PPP does not require that servers provide this address, but Windows NT servers will consistently return the address anyway. Other PPP vendors may not provide the address. If the address is not available, this member returns an empty string, "".

Always check ErrorNo after reading this value to be certain that the value is correct. ErrorNo is 0 for a valid result or contains an error code. The error codes is described under AmbErrorNo property.

Remarks

The IpServerAddress was added to the RASPPPIP structure beginning with Windows NT 3.51 and the initial release of Windows 95. Beginning with these systems.

unsigned long NbfErrorNo

This property contains information about a remote access projection operation for a specified remote access component protocol in this case the result of a PPP NetBEUI Framer (NBF) projection operation.

Contains the result of the PPP control protocol negotiation. A value of zero indicates success. A nonzero value indicates failure, and is the actual fatal error that occurred during the control protocol negotiation, the error that prevented the projection from completing successfully.

Always check ErrorNo after reading this value to be certain that the value is correct. ErrorNo is 0 for a valid result or contains an error code. The error codes is described under AmbErrorNo property.

unsigned long NbfNetBiosErrorNo

This property contains information about a remote access projection operation for a specified remote access component protocol in this case the result of a PPP NetBEUI Framer (NBF) projection operation.

If NbfErrorNo has the value ERROR_SERVER_NOT_RESPONDING or ERROR_NETBIOS_ERROR, this property contains the NetBIOS error that occurred. For other values of the NbfErrorNo property, this field contains zero.

Always check ErrorNo after reading this value to be certain that the value is correct. ErrorNo is 0 for a valid result or contains an error code. The error codes is described under AmbErrorNo property.

LPSTR NbfNetBiosErrorString

This property contains information about a remote access projection operation for a specified remote access component protocol in this case the result of a PPP NetBEUI Framer (NBF) projection operation.

If NbfErrorNo has the value ERROR_NAME_EXISTS_ON_NET, this property contains a zero-terminated string that is the NetBIOS name that caused the conflict. For other values of NbfErrorNo this property contains a null string.

Windows 95: This member is undefined.

Always check ErrorNo after reading this value to be certain that the value is correct. ErrorNo is 0 for a valid result or contains an error code. The error codes is described under AmbErrorNo property.

LPSTR NbfWorkstationName

This property contains information about a remote access projection operation for a specified remote access component protocol in this case the result of a PPP NetBEUI Framer (NBF) projection operation.

Contains a zero-terminated string that is the local workstation's computer name. This unique computer name is the closest NetBIOS equivalent to a client's NetBEUI address on a remote access connection.

Always check ErrorNo after reading this value to be certain that the value is correct. ErrorNo is 0 for a valid result or contains an error code. The error codes is described under AmbErrorNo property.

short NbfbLana

This property contains information about a remote access projection operation for a specified remote access component protocol in this case the result of a PPP NetBEUI Framer (NBF) projection operation.

Identifies the NetBIOS network adapter identifier, or LANA, on which the remote access connection was established. This member contains the value 0xFF if a connection was not established.

Always check ErrorNo after reading this value to be certain that the value is correct. ErrorNo is 0 for a

LPSTR Phonebook

Points to a null terminated string that specifies the full path and filename of the phonebook file. This parameter can be NULL, in which case the default phonebook file is used (normal use).

This parameter should always be NULL for Windows 95 since the phonebook entries are stored in the registry. This handled by the control and you just have to disregard this property if you work in Windows 95.

Default is NULL.

Methods

DeletePhonebookEntry
DoEnumConnections
DoEnumDevices
DoEnumEntries
DoEnumEntriesEx
Dial
DialExtensions
GetEntryProperties
Hangup
HangUpEx
RenameEntry
SetEntryProperties
ShowEditEntryDialog
ShowNewEntryDialog

BOOL DeletePhonebookEntry()

Removes the phonebook entry specified by the property EntryName and the current phonebook (in Windows NT specified by the Phonebook property).

Returns True if the entry could be removed. Otherwise False is returned and ErrorNo is set to a valid error code describing the cause of the error.

DoEnumConnections()

Call this method to enumerate open connections. After a call check the EnumConnection event for results of the enumeration.

True is returned if the method succeeded.

DoEnumDevices()

Call this method to enumerate devices usable for establishing a Ras-connection. Check the EnumDevice event for results of the enumeration for all devices on the machine.

BOOL DoEnumEntries()

Call this method to enumerate entries defined for a RAS phonebook.

After a call check the EnumEntry event for results of the enumeration.

LPSTR DoEnumEntriesEx()

Call this method to enumerate entries defined for a RAS phonebook.

The difference between this method and DoEnumEntries is that you get the event name back when calling it. You call the method until you receive an entryname with null length wich indicates that all enteries have been enumerated.

You can use code as the following to fill a listbox with entery name.

Private Sub btnEnumEntriesEx_Click()
    Dim result As String
    Screen.MousePointer = 11
    List2.Clear

    Do
        result = EsRas1.DoEnumEntriesEx()
        List2.AddItem result
    Loop While (Len(result) > 0)

    Screen.MousePointer = 0
End Sub

BOOL Dial (short flag)

The Dial method establishes a Remote Access Service (RAS) connection between a RAS client and a RAS server. The connection data includes callback and user authentication information.

The property bUseCurrent specifies which data should be used for the dial session. If bUseCurrent is set to True the properties DialCallbackNumber, DialDomain, DialPassword, DialPhoneNumber and DialUserName is ignored. The username and password of the current user is used instead.

If bUseCurrent is set to False. The properties DialCallbackNumber, DialDomain, DialPassword, DialPhoneNumber and DialUserName are used together with the data stored for the selected phonebook entry.

If the EntryName property is set no an empty string when the dial method is called, a simple modem connection is established on the first available modemport. In this case the DialPhoneNumber property have to contain a valid phonenumber. If the DialPhoneNumber property doesn't contain a phonenumber the dial method returns FALSE and set the ErrorNo property to -1.

If the DialPhoneNumber property is an empty string the phonenumber stored in phonebook is used. If no EntryName is set this property must contain a value otherwise Dial will fail.

If the DialCallbackNumber property is an empty string this indicates that no callback should be used. If the DialCallBackNumber property contains an asterisk ("*") this indicates that the number stored in phonebook should be used for callback (This is the default for the DialCallBackNumber property).

The DialDomain property contains the domain on which authentication is to occur. An empty string specifies the domain in which the remote access server is a member. An asterisk specifies the domain stored in the phonebook for the selected EntryName.

The RasNotification event reports the states entered during the dial.

The flag argument

bit 1 - If set Use DialExtension properties. (Ignored in Windows 95)
bit 2 -
bit 3 -
bit 4 - If set the hRasConn is used again. This is used to resume after a paused state.

Windows NT

If the supplied flag has bit 1 set. The values stored in the property DialExtOptions and the Boolean variants DialExtIgnoreModemSpeaker, DialExtIgnoreSoftCompression, DialExtPausedStates, DialExtSetModemSpeaker, DialExtSetSoftCompression, DialExtUsePrefixSuffix are used.

If the supplied flag has bit 1 cleared all of these peroperties will be ignored and defaults will be used.

Windows 95

The values stored in the property DialExtOptions and the Boolean variants DialExtIgnoreModemSpeaker, DialExtIgnoreSoftCompression, DialExtPausedStates, DialExtSetModemSpeaker, DialExtSetSoftCompression, DialExtUsePrefixSuffix is ignored. On Windows 95, Dial always uses the default behaviours for the these properties.

Return Value

If the function succeeds, the immediate return value is TRUE. In addition, the function stores a handle to the RAS connection into the property hRasConn..

If the function fails, the immediate return value is False and the property ErrorNo is set to an error either from the set listed in the RAS header file or ERROR_NOT_ENOUGH_MEMORY.

Remarks

Errors that occur after the immediate return can be detected by reading the ConnState property which give the state and also sets the ErrorNo property. This Data is available until an application calls the HangUp method to hang up the connection.

An application must eventually call HangUp whenever a non-NULL connection handle is available in the hRasConn property. This applies even if Dial returns False (error).

An application can safely call HangUp from the RasNotification event. If this is done, however, the hangup does not occur until the routine returns.

Windows NT

If the DialExtensions properties enables RDEOPT_PausedStates, the Dial function pauses whenever it enters a state in which the RASCS_PAUSED bit is set to one. To restart Dial from such a paused state, call Dial again, with bit 4 in flag set (flag=8).

To specify that Dial should enter a RASCS_CallbackSetByCaller state, set the CallbackNumber property to "*" on the initial call to Dial. When your notification handler is called with this state, you can set the the callback number to a number supplied by the user.

Windows 95

Windows 95 does not support the RASCS_CallbackSetByCaller state or any of the other paused states.

BOOL GetEntryDialParams()

Get the info in the RASDIALPARAMS structure and place the result in DialUsername, DialPassword, DialDomain, DialPhoneNumber and DialCallbackNumber. Note however that DialPhoneNumber currently is unused. If the returned password is valid the DialfPassword property is set to TRUE.

You must set the EntryName property before you call this method.

TRUE is returned on success.

GetEntryProperties( LPCTSTR EntryName )

Get the Entry-properties for an EntryName. The EntryName must be exactly as the entry otherwise ErrorNo is set to 14. The EntryName must also be available in the phonebook.

If called with EntryName set to "" default values are returned.

Properties that have names proceded bu Entry- is set by this call.

*** Alternates for phonenumber is not implemented yet.***

BOOL Hangup()

The HangUp method terminates the current remote access connection. The connection is specified with a Remote Access Service (RAS) connection handle. The function releases all RASAPI32.DLL resources associated with the handle.

The connection is terminated even if the Dial call has not yet been completed.

After this call, the hrasconn property can no longer be used.

BOOL HangupEx( long hRasConn )

Added in build 51

The HangUpEx method terminates a remote access connection. The connection is specified with a Remote Access Service (RAS) connection handle.

You can use this method to terminate a connection where the handle ( hRasConn ) is known. This handle can be obtained by a call of the DoEnumConnection method which gives info on all open connections.

BOOL RenameEntry(LPCTSTR NewName)

Changes the EntryName to NewName for a RAS entry.

If the name could be changed True is returned. Otherwise False is returned and the property ErrorNo contains the error code describing the failure.

BOOL SetEntryDialParams( BOOL fRemovePassword)

Set the info in the RASDIALPARAMS structure fetching information from the  DialUsername, DialPassword, DialDomain, DialPhoneNumber and DialCallbackNumber. Note however that DialPhoneNumber currently is unused. Set fRemovePassword to TRUE to remove password information.

You must set the EntryName property before you call this method.

TRUE is returned on success.

BOOL SetEntryProperties()

Stores the current Entry- properties in the phonebook as properties used for the current EntryName.

BOOL ShowEditEntryDialog()

With this method and a valid value in the EntryName property you can let the user edit an existing phonebook entry. The method displays a dialog box in which the user can modify the existing information.

BOOL ShowNewEntryDialog()

With a call to this method a dialog is displayed that helps your user to create a new phonebook entry.

Events

Connected
Disconnected
EnumEntry
EnumConnection
EnumDevice
RasNotification

Connected

This event is fired when a RAS connection has been established.

Disconnected

A failed connection.

This event is fired when a RAS connection is terminated. The event is only fired if this happens during a connection phase. Don't expect the event after a Connect event have been received.

EnumEntry(LPCTSTR Name)

The result of a DoEnumEntries method call is reported in this event. Name contains the string describing the entry.

To indicate the end of data a Name with length null is received as the last event.

EnumConnection(long hrasconn, LPCTSTR EntryName, LPCTSTR DeviceType, LPCTSTR DeviceName)

The result of a DoEnumConnections method call is reported in this event. hrasconn contains the handle for the active connection. EntryName is a string describing the phonebook entry. DeviceType is a string describing the device. DeviceName is the TAPI devicename.

If a connections was made without specifying a phonebook entry name, the information returned for this connection will give the connection entry name preceded by ".".

To indicate the end of data a Name with length null is returned.

EnumDevice(LPCTSTR DeviceName, LPCTSTR DeviceType)

The result of a DoEnumDevices method call is reported in this event. DeviceName contains the string describing the device. DeviceType is a string describing the devicetype.

To indicate the end of data a DeviceName/DeviceType with length null is received as the last event.

RasNotification(long code, LPCTSTR message)

This event gives information during the RAS-dial. The code is an enumerated value with info on the state and message is a clear text message describing the code.

The following codes can be received

• RASCS_OpenPort = 0,
• RASCS_PortOpened,
• RASCS_ConnectDevice,
• RASCS_DeviceConnected,
• RASCS_AllDevicesConnected,
• RASCS_Authenticate,
• RASCS_AuthNotify,
• RASCS_AuthRetry,
• RASCS_AuthCallback,
• RASCS_AuthChangePassword,
• RASCS_AuthProject,
• RASCS_AuthLinkSpeed,
• RASCS_AuthAck,
• RASCS_ReAuthenticate,
• RASCS_Authenticated,
• RASCS_PrepareForCallback,
• RASCS_WaitForModemReset,
• RASCS_WaitForCallback,
• RASCS_Projected,
• RASCS_StartAuthentication, // Windows 95 only
• RASCS_CallbackComplete, // Windows 95 only
• RASCS_LogonNetwork, // Windows 95 only
• RASCS_Interactive = RASCS_PAUSED,
• RASCS_RetryAuthentication,
• RASCS_CallbackSetByCaller,
• RASCS_PasswordExpired,
• RASCS_Connected = RASCS_DONE,
• RASCS_Disconnected
  

The enumerator values are listed here in the general order in which the connection states occur. However, you should not write code that depends on the order or occurrence of particular connection states, because this may vary between platforms.

RASCS_OpenPort
The communication port is about to be opened.

RASCS_PortOpened
The communication port has been opened successfully.

RASCS_ConnectDevice
A device is about to be connected. RasGetConnectStatus can be called to determine the name and type of the device being connected.

RASCS_DeviceConnected
A device has connected successfully. RasGetConnectStatus can be called to determine the name and type of the device being connected.
For a simple modem connection, RASCS_ConnectDevice and RASCS_DeviceConnected will be called only once. For a dial-up X.25 PAD connection, the pair will be called first for the modem, then for the PAD. If a preconnect switch is configured, the pair will be called for the switch before any other devices connect. Likewise, the pair will be called for a postconnect switch after any other devices connect.

Windows 95: Note that Windows 95 does not currently support multi-stage connections such as the X.25 PAD connection described above.

RASCS_AllDevicesConnected
All devices in the device chain have successfully connected. At this point, the physical link is established.

RASCS_Authenticate
The authentication process is starting. Remote access does not allow the remote client to generate any traffic on the LAN until authentication has been successfully completed. Remote access authentication on a Windows NT or Windows 95 server consists of:

• Validating the username/password on the specified domain.
• Projecting the client onto the LAN. This means that the remote access server does what is necessary to send and receive data on the LAN on behalf of the client. For example, the remote access server might need to add a NetBIOS name that corresponds to the client's computer name.
• Callback processing in which the client hangs up and the server calls back. (The user needs special permissions on the remote access server for this.)
• Calculating the link speed. This is necessary to correctly set transport timeouts to match the relatively slow speed of the remote link.

RASCS_AuthNotify
An authentication event has occurred. If the property ErrorNo is zero, this event will be immediately followed by one of the more specific authentication states following. If the ErrorNo property is nonzero, authentication has failed, and the error value indicates why.

RASCS_AuthRetry
The client has requested another validation attempt with a new username/password/domain. This state does not occur in Windows NT version 3.1.

RASCS_AuthCallback
The remote access server has requested a callback number. This occurs only if the user has "Set By Caller" callback privilege on the server.

RASCS_AuthChangePassword
The client has requested to change the password on the account. This state does not occur in Windows NT version 3.1.

RASCS_AuthProject
The projection phase is starting.

RASCS_AuthLinkSpeed
The link-speed calculation phase is starting.

RASCS_AuthAck
An authentication request is being acknowledged.

RASCS_ReAuthenticate
Reauthentication (after callback) is starting.

RASCS_Authenticated
The client has successfully completed authentication.

RASCS_PrepareForCallback
The line is about to disconnect in preparation for callback.

RASCS_WaitForModemReset
The client is delaying in order to give the modem time to reset itself in preparation for callback.

RASCS_WaitForCallback
The client is waiting for an incoming call from the remote access server.

RASCS_Projected
This state occurs after the RASCS_AuthProject state. It indicates that projection result information is available. You can access the projection result information by calling RasGetProjectionInfo.

RASCS_StartAuthentication Windows 95 only:
Indicates that user authentication is being initiated or retried.

RASCS_CallbackComplete Windows 95 only:
Indicates that the client has been called back and is about to resume authentication.

RASCS_LogonNetwork Windows 95 only:
Indicates that the client is logging on to the network.

RASCS_Interactive
This state corresponds to the terminal state supported by RASPHONE.EXE. This state does not occur in Windows NT version 3.1.

RASCS_RetryAuthentication
This state corresponds to the retry authentication state supported by RASPHONE.EXE. This state does not occur in Windows NT version 3.1.

RASCS_CallbackSetByCaller
This state corresponds to the Callback state supported by RASPHONE.EXE. This state does not occur in Windows NT version 3.1.

RASCS_PasswordExpired
This state corresponds to the change password state supported by RASPHONE.EXE. This state does not occur in Windows NT version 3.1.

RASCS_Connected
Successful connection.

RASCS_Disconnected
Disconnection or failed connection.
The connection process states are divided into three classes: running states, paused states, and terminal states.

An application can easily determine the class of a specific state by performing Boolean bit operations with the RASCS_PAUSED and RASCS_DONE bitmasks. Here are some examples:

fDoneState = (state & RASCS_DONE);
fPausedState = (state & RASCS_PAUSED);
fRunState = !(fDoneState || fPausedState);

Where to get the control?

It is possible that you are reading this documentation without having access to the control itself. If you have Internet access you just need to connect to http://www.eurosource.se and fetch a fully working sample of the control. At this location you can also find samples on how to use the control.

We can email the control anywhere in the world if you send us a request to do so. Please state if you want MIME or BINHEX coding. Send request to sales@eurosource.se

If you use the unregistered version of the control a splash screen is displayed from time to time reminding you to register.To get rid of this nag-screen you need to register. Information is available at our site.

We ship anywhere in the world with World-wide First Class/Airmail if you select this option. The only media supported is 3.5" diskettes.The charge for this type of delivery is $15 (USD) extra.

Support

You can get support by sending email to support@eurosource.se. You can also find relevant information on-line at http://www.eurosource.se

We also check the newsgroup comp.lang.basic.visual.3rdparty on a regular basis and will try to help on all questions posted there.

How to contact us

• If you need to contact us the preferred way is through email. Please send a mail to info@eurosource.se
• If you want to use phone please call us at +46 657 10620 and Fax: +46 657 10612.
• If you want to send a snailmail you can send it to
• Eurosource, Gruvbyn 415A, S-820 50 LOOS, SWEDEN