EsRas ActiveX control

Ake Hedman Brattberg, Gruvbyn 415, S-820 50 LOOS, Sweden (ah@brattberg.se) (http://www.ljusdal.se/esource)

96-08-13

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.

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:

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.

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.ljusdal.se/esource/ftp/misc). 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

msvcrt40.dll

oc30.dll

olepro32.dll

regsvr32.exe

As noted above you may also need to copy the rnaph.dll to your system directory. This file should be included with this control but if it isn't it can be found in the above archive.

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. In Windows 95 the registry is used so here it does not matter what you set this property to.
  2. Set the property EntryName to the phonebook entry you would like to dial.
  3. Set the bUseCurrent property to False. 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.
  4. Call the Dial method with the flag parameter set to 0.
  5. Check the RasNotification method 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.

Simple Dial

Define a new RAS entry without user intervention


Properties


Properties with a prefix of Entry belongs to the RASENTRY structure in rnaph.h.

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.

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.

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 :
FlagMeaning
RASEO_UseCountryAndAreaCodesIf set, the dwCountryID, dwCountryCode, and szAreaCode fields 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.

RASEO_SpecificIpAddrIf this flag is set, Dial-Up Networking will try to use the IP address specified by ipaddr as the IP address for the dial-up connection. If not set the value of the ipaddr field 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.

RASEO_SpecificNameServersIf this flag is set, the ipaddrDns, ipaddrDnsAlt, ipaddrWins, and ipaddrWinsAlt members are used to specify the name server addresses for the dial-up connection. If this flag is not set, Dial-Up Networking will ignore the values in iaDNSAddr, iaDNSAddrAlt, iaWINSAddr, and iaWINSAddrAlt members.

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)

RASEO_IpHeaderCompressionIf this flag is set, Dial-Up Networking 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.

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

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

Windows 95: This flag is currently ignored by Windows 95

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

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

This flag should not be set 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.

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

Windows 95 usability recommendation : This flag should be set 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.

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

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

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

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

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

Windows 95: This flag is currently ignored by Windows 95

RASEO_RequireDataEncryptionSetting this flag means data encryption must be negotiated successfully or the connection should be dropped. This flag is ignored unless RASEO_RequireMsEncryptedPw 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

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

RASEO_UseLogonCredentialsSetting 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 RASEO_RequireMsEncryptedPw is also set. 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

RASEO_PromoteAlternatesSetting this flag applies when alternate phone numbers are defined by the dwAlternaltesOffset field. 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.

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

Windows 95 : This flag is currently ignored by Windows 95

You can use the following Boolean properties instead of EntryfOptions
EntryUseCountryAndAreaCodes
EntrySpecificIpAddr
EntrySpecificNameServers
EntryIpHeaderCompression
EntryRemoteDefaultGateway
EntryDisableLcpExtensions
EntryTerminalBeforeDial
EntryTerminalAfterDial
EntryModemLights
EntrySwCompression
EntryRequireEncryptedPw
EntryRequireMsEncryptedPw
EntryRequireDataEncryption
EntryNetworkLogon
EntryUseLogonCredentials
EntryPromoteAlternates

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 EntryIpddr 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 values in iaDNSAddr, iaDNSAddrAlt, iaWINSAddr, and iaWINSAddrAlt members.

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.
FlagMeaning
RASNP_NetbeuiNegotiate NETBEUI
RASNP_IpxNegotiate IPX
RASNP_IpNegotiate TCP/IP

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.

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.
ConstantMeaning
RASFP_PppPoint-to-Point Protocol (PPP)
RASFP_SlipSerial Line Internet Protocol (SLIP)
RASFP_RasMicrosoft proprietary protocol implemented in NT 3.1 and WfW 3.11

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 EntryNetProtocol

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 EntryNetProtocol

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 EntryNetProtocol

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:
StringMeaning
"modem"modem accessed via a COM port
"isdn"ISDN card with corresponding NDISWAN driver installed
"x25"X.25 card with corresponding NDISWAN driver installed.

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.

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

#if (WINVER >= 0x400)

RASCS_StartAuthentication, // Windows 95 only

RASCS_CallbackComplete, // Windows 95 only

RASCS_LogonNetwork, // Windows 95 only

#endif

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, Dial uses the default settings that are noted following.

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.

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.

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

Methods


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.

DoEnumEntries()

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

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

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

DialExtensions

Windows NT

If the supplied flag has bit 1 set. The values stored in the property DialExtOptions and the Boolean variants DialExtIgnoreModemSpeaker, DialExtIgnireSoftCompression, 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, DialExtIgnireSoftCompression, 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.

GetEntryProperties( LPCTSTR EntryName )

Get the Entry-properties for an EntryName. The EntryName must be exactly as the entry otherwise errorNo is set to 14. (TODO Strange!) The EntryName must also be available in the phonebook.

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

The following proporties are set by this call

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

BOOL Hangup()

The HangUp function terminates a 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 RasDial call has not yet been completed.

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

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

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,

#if (WINVER >= 0x400)

RASCS_StartAuthentication, // Windows 95 only

RASCS_CallbackComplete, // Windows 95 only

RASCS_LogonNetwork, // Windows 95 only

#endif

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:

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.ljusdal.se/esource 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 the request to f0002@brattberg.se

Register this control & Pricing

When you register the control we will send you the esras.lic file which will make the splash screen go away.

If you are entitled to a free registration, (please read our license agreement later in this document to find out if you are) , you have to fill in the form available at http://www.ljusdal.se/esource to receive the esras.lic file and get your free license. Note that the free license does not allow you to get support or distribute applications made with the control unless these also are made available free of charge or is used within your nonprofit organization.

If you are not entitled for a free licens you have to pay for the control. This could be done in several ways.

You can register with a credit card.

We work together with PsL on this and here is how you go ahead: Note that this option is for CREDIT CARD ORDERS ONLY.

EsRas has Item Number 14607 at PsL.

You can order with MC, Visa, Amex, or Discover from Public (software) Library by calling (USA) 800-2424-PsL or (USA) 713-524-6394 or by FAX to (USA) 713-524-6398 or by CIS Email to 71355,470 Internet email to 71355,470@compuserv.com.

You can also mail credit card orders to PsL at P.O.Box 35705, Houston, TX 77235-5705, USA.


THE ABOVE NUMBERS ARE FOR CREDIT CARD ORDERS ONLY.


BRATTBERG CANNOT BE REACHED AT THESE NUMBERS.

Any questions about the status of the shipment of the order, refunds, registration options, product details, technical support, volume discounts, dealer pricing, site licenses, non-credit card orders, etc, must be directed to Brattberg, Gruvbyn 415A, S-820 50 LOOS, Sweden Phone: +46 657 10620, Fax: +46 657 105 13 email: f0002@brattberg.se or by use of on-line facilities at http://www.ljusdal.se/esource.

To insure that you get the latest version, PsL will notify us the day of your order and we will ship the EsRas directly to you. If you take the option of email-shipping you will usually have the licensed control the same day.

You can also make this registration online via you web-browser. The URL: is

http://206.109.101.6/cgi-win/psl_ord.exe/ITEM14607

or follow the links at

http://www.ljusdal.se/esource/esras

You can also go to

http://206.109.101.6/register.htm

and look up EsRAS to make your online registration. But for the last time. This is only for Credit card orders.

We can invoice your organisation.

Some, mostly larger, companies need an invoice before they can make any financial transactions . We can handle this situation as well. Just send us a fax ( +46 657 10620) or email (f0002@brattberg.se) or use the online facilities at http://www.ljusdal.se/esource or send a mail to Brattberg, Gruvbyn 415A, S-820 50 LOOS, Sweden to place your order.

We will add a Invoice fee (Currently $10) and sails tax (if you are located within the European Community) to your order. You get a credit of 30 days. We usually ship the control the same day we receive your order.

You can send us a check.

If you send us a check it should be made payable to Brattberg, Gryvbyn 415A, S-820 50 LOOS, Sweden. Please add $5 to the total amount of your order if you use this option. If you fax us a copy of your check we will ship the control to you (just email) the same day we receive the fax.

You can make a bank transfer to us.

There are several options you can use for this kind of transfer. You can make a SWIFT transfer to FOBA SESS 7759-15-01828.

You can use our Banktransfer account (Bankgiro in Swedish) which is

You can send money in an envelop.

Put the money for the control in an envelop and post to us. This works most of the time but the risk is yours not ours.

Registration Fees

EsRas Control $12

You get access to all versions of a control under one year. This means that a control that is published as 16-bit/32-bit ActiveX (OCX) and 16-bit/32-bit DLL and a VBX are all covered by this registration fee. You also get free support.

EsRas Control Source $450

This is the source for the control. This option gives you the source for all versions of a control for one year. This means that a control that is published as 16-bit/32-bit ActiveX (OCX) and 16-bit/32-bit DLL and a VBX are all covered by this registration fee.

Brattberg Control Subscription $150

Yes its only $150! This option gives you all controls and all source produced in our company for one year. You also get support as if you bought each of the controls.

Traditional media (Diskette) $10

We ship anywhere in the world with Worldwide First Class/Airmail if you select this option. The only media supported is 3.5" diskettes.

Additional information we want from you when you place an order:

  1. If you want your control to be sent to you by email we need your email address. We also want to know if you prefer MIME (base64) or BINHEX coding of the control attachment.
  2. You can get access to a protected directory on our WWW-server where you can fetch your registered control. If you want this option please state so in your order.
  3. If you want to be added to the EsRAS mailing list please state so. This is the official support channel for EsRAS.
  4. If you want to be added to the EsRAS auto distribution list please state so. By participating in this option you get all updates of the EsRAS control automatically sent to you as soon as they are available.

Mailing Lists & Support

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

We also have set up mailinglists for all of our controls. If you want to subscribe to the EsRAS mailinglist send a letter to esras-request@ljusdal.se with "subscribe" as your subject. This will make you a subscriber of this list. You can also send a letter with "help" as the subject to get more information. To unsubscribe to the list just send a letter with "unsubscribe" as the subject. After a subscribing to a list you can send your comments, questions etc. to esras@ljusdal.se.

We also have mailinglists for all other controls and

  1. brattberg@ljusdal.se which contains news about our company and our products. This is news about controls, the company, new technologies and other things we think can be of interest to our customers and partners. If you want to subscribe send a letter to brattberg-request@ljusdal.se with "subscribe" as your subject.
  2. activex@ljusdal.se which contains news information about the ActiveX technology and our ActiveX controls. If you want to subscribe send a letter to activex-request@ljusdal.se with "subscribe" as your subject.
  3. vbx@ljusdal.se which contains news information about the VBX technology and our VBX controls. If you want to subscribe send a letter to activex-request@ljusdal.se with "subscribe" as your subject
  4. dll@ljusdal.se which contains news information about our DLL controls. If you want to subscribe send a letter to activex-request@ljusdal.se with "subscribe" as your subject
  5. You can find forms for subscribing to the mailinglists at http://www.ljusdal.se/esource

We also check the newsgroup comp.lang.basic.visual.3rdparty on a regular basis and will try to help on all questions posted there we also check the relevant newsgroups at the Microsoft news server from time to time.

How to contact us

If you need to contact us the preferred way is through email. Please send a mail to f0002@brattberg.se

If you want to use phone please call us at +46 657 10620 and if you want to fax us please use +46 657 10513.

If you want to send a snailmail you can send it to

BRATTBERG

Gruvbyn 415A

S-820 50 LOOS

Sweden

We always check the newsgroup comp.lang.basic.visual.3dparty and will try to help on any support questions put there related to our controls.


License

We have a very liberal license policy so please read the license agreement text below . You are not allowed to use this control for other then evaluation purposes without register it with us. But if you are a student or involved in a non-profit organization there is no registration fee. Please read the license agreement to find out if you are entitled to a free registration or not.

If you intend to use the control in a commercial organization or want to develop an application which you intend to sell you will find that the license cost is very moderate. Please read the complete license agreement.

Brattberg End User License agreement (EULA)