NAME

Win32::RASE - managing dialup entries and network connections on Win32

SYNOPSIS

            

              
              
use Win32::RASE;
            
          

ABSTRACT

This module implements the client part of Win32 RAS API.

It is named RASE(RAS-entry) because it was originally designed to create/delete/change/manage RAS/DUN entries. Now it implements synchronous dialing, hang up and the wide range of RAS/DUN entry manipulations.

The current version of Win32::RASE is available at:

            

              
              
http://www.dux.ru/guest/fno/perl/
            
          

DESCRIPTION

This module is a collection of subroutines. As their names are very long and specific and almost each corresponds to a Win32 API call I decided to export a lot of them by default. Everything is exported except those subs that are claimed as non-exported.

OK, you can require it instead of use.

!!! IMPORTANT !!! All functions (if the other behavior is not stated explicitly) return TRUE on success, FALSE on error to conform the handy calling rule

            

              
              
RESULT = function(PARAMS) or die MESSAGE;
            
          

where RESULT could be scalar or list either. Note that "||" is not the same thing as "or".

The following logic is used: almost all functions croak on obvious programmer's errors like invalid entry-name or such. But they return FALSE and set LastError on internal API errors. It is made to give the programmer a chance to complete all actions and may be to trap some errors without exiting the program.

For example if some phonebook file is corrupted you have a chance to try another one etc.

The following two functions are available after any other function was executed. They are both non-exported to provide feel and look of Win32-Perl built-in functions with the same names.

GetLastError ( )

Returns 0 or the last encountered RAS, TAPI or Windows error number.

            

              
              
$lastErr = Win32::RASE::GetLastError();
            
          

Usually you should call this function after some other function returned undef. In case of Windows error it returns the same value as Win32::GetLastError. Unlike the built-in one it always returns 0 if the last called function finished successfully.

You can use it for example like this:

            

              
              
some_function();
Win32::RASE::GetLastError and die Win32::RASE::FormatMessage;
            
          

or implicitly

            

              
              
some_function() or die Win32::RASE::FormatMessage;
            
          

FormatMessage ( )

Converts the supplied RAS, TAPI or Win32 error number (e.g. returned by Win32::RASE::GetLastError()) to a descriptive string.

            

              
              
$message = Win32::RASE::FormatMessage($err_num);
            
          

Without the parameter assumes that the result of Win32::RASE::GetLastError() was sent.

IsWindow ( )

This function is non-exported for not to corrupt some other GUI related synonym.

            

              
              
Win32::RASE::IsWindow( $hwnd );
            
          

Returns TRUE if $hwnd identifies an existing window, otherwise FALSE.

This function is handy to use before the functions that display a dialog box - to verify the parent window.

=====================================

PHONEBOOK RELATED FUNCTIONS

=====================================

Note that by default all functions in this section work with the default phonebook (on Windows NT).

The registry key "HKEY_CURRENT_USER\Software\Microsoft\RAS Phonebook" has a dword subkey "PhonebookMode" which could have 3 values:

            

              
              
0 - the "system" phonebook is in use.
    This is probably %SYSTEMROOT%\system32\ras\rasphone.pbk
1 - the "user" phonebook is in use.
    This one is located in  %SYSTEMROOT%\system32\ras\<filename>
    <filename> here is the value of "PersonalPhonebookFile" subkey
    that is located under the same key.
2 - the "alternate" phonebook is in use.
    The full path to the alternate phonebook could be found in the
    "AlternatePhonebookPath" subkey under the same key.
            
          

This version of Win32::RASE provides no way to change these registry settings. If "HKEY_CURRENT_USER\Software\Microsoft\RAS Phonebook\PhonebookMode" is equal to 0 Win32::RASE will use the "system" phonebook, in case 1 - the "user" phonebook, in case 2 - the "alternate" phonebook.

The user can use the main Dial-Up Networking dialog box to create personal phonebook files or change defaults (registry settings). The Win32 API does not currently provide support for creating a phonebook file.

IMPORTANT:

At any time you can set a global variable $Win32::RASE::PHONEBOOK to the full path of your phonebook file, and this phonebook will be in use until $Win32::RASE::PHONEBOOK is changed. Setting this variable to 0 or undef returns us to registry defined phonebook(s).

Windows 95/98: Dial-up networking stores phonebook entries in the registry rather than in a phonebook file. Windows 9x does not support personal phonebook files. So $Win32::RASE::PHONEBOOK has no meaning and must always be undef.

All functions treat entry-names as case-sensitive because RAS functions are kinda semi-case-sensitive. Some of them fail when entry was given with case-changes. But at the same time RasSetEntryProperties API call (in RasCopyEntry()) fails to create both QWERTY and QwErTy, it renames instead. Ou-h-h MS, MS...

The moral is: don't use names that differ only in upper/lower case.

There also is a danger in using multiple processes that are calling RAS APIs that update the phonebook. Microsoft reported this problem has been corrected in Service Pack 3.

http://support.microsoft.com/support/ntserver/serviceware/nts40/E9MSKWBJI.ASP

A note on multilink functionality: there are no ways to use Multilink programmatically on Win95/98. So, the current version of the module does not support it for WinNT also. For more info read:

http://support.microsoft.com/support/kb/articles/q198/7/77.asp

Entry names for Windows CE cannot exceed 20 characters. http://msdn.microsoft.com/library/wincesdk/wcecomm/ras_24.htm

A similiar problem is reported for the InternetMail Service (IMS) on MS BackOffice Small Business Server version 4.5 and Windows NT Server version 4.0 http://support.microsoft.com/support/kb/articles/Q217/9/37.asp

So, the entries with long names may be unusable by the other applications.

RasCreateEntryDlg ( )

This function displays a dialog box in which the user types information about the phonebook entry.

            

              
              
RasCreateEntryDlg( [$hwnd] );
$hwnd  - handle to the parent window of the dialog box. Optional.
         If you are using Win32::GUI this would be $Window->{handle}
            
          

As this is a synchronous operation and waits for user input it provides no way to find out whether the new entry was created or not. You should use RasEnumEntries() to understand what has happened.

Here and everywhere in the functions that display a dialog box - if $hwnd is omitted or does not identify an existing window a dialog box is centered on the screen.

RasEditEntryDlg ( )

This function displays a dialog box in which the user types information about the phonebook entry. For a programmatical way to edit an existing entry take a look at RasSetEntryProperties().

            

              
              
RasEditEntryDlg( $entry [, $hwnd] );
$entry - existing phonebook entry to edit.
$hwnd  - handle to the parent window of the dialog box. Optional.
         If you are using Win32::GUI this would be $Window->{handle}
            
          

This is a synchronous operation and waits for user input.

Croaks if $entry does not exist. You should call IsEntry() before to verify $entry.

RasRenameEntry ( )

            

              
              
RasRenameEntry( $oldname, $newname );
            
          

Croaks if $oldname does not exist or $newname already exists. You should call IsEntry() or RasEnumEntries() before to verify both.

RasDeleteEntry ( )

            

              
              
RasDeleteEntry( $entry );
            
          

Croaks if $entry does not exist. You should call IsEntry() or RasEnumEntries() before to verify $entry.

RasEnumEntries ( )

            

              
              
@entries = RasEnumEntries();
            
          

This function lists all entry names in the phonebook.

As this function is heavily used internally it croaks on errors - for example if non-existing phonebook name is given. So, FALSE result means that the selected phonebook is empty.

Command line syntax:

            

              
              
perl -MWin32::RASE -e "$,=q{, };print RasEnumEntries"
            
          

IsEntry ( )

            

              
              
IsEntry ( $entry );
$entry  - name of the RAS/DUN entry
            
          

Returns TRUE if $entry was found in the phonebook, otherwise FALSE.

NOTE! It treats entry-names as case-sensitive (see above).

RasGetEntryDialParams ( )

This function retrieves the connection information saved by the last successful call to the RasDial() or RasSetEntryDialParams() function for a specified phonebook entry.

            

              
              
($UserName, $Password, $Domain, $CallbackNumber) =
                           RasGetEntryDialParams($entry);
$entry          - name of RAS/DUN entry
$UserName       - user's user name ;-)
$Password       - yes, it's that secure
$Domain         - domain on which authentication is to occur
$CallbackNumber - callback phone number
            
          

Croaks if $entry does not exist.

RasGetUserPwd ( )

The short variant of previous.

            

              
              
($UserName, $Password) = RasGetUserPwd($entry);
            
          

Croaks if $entry does not exist.

Command line syntax:

            

              
              
perl -MWin32::RASE -e "print ((RasGetUserPwd('NEV1'))[0])"
perl -MWin32::RASE -e "@_=RasGetUserPwd('NEV1');print qq{@_}"
            
          

RasSetEntryDialParams ( )

This function changes the connection information for a specified phonebook entry.

            

              
              
RasSetEntryDialParams($entry, $UserName, $Password, $Domain,
                      $CallbackNumber, $fRemovePassword);
            
          

All parameters except $entry are optional. undef or omitted parameters are considered to be "" - this means that no changes will be made to this parameter.

            

              
              
$entry           - name of RAS/DUN entry
$UserName        - user name
$Password        - password for the user specified by $UserName.
     If $UserName is an empty string, the password is not changed.
     If $Password is an empty string and $fRemovePassword is FALSE,
     the password is set to the empty string. If $fRemovePassword is
     TRUE, the password stored in this phonebook entry for the user
     specified by $UserName is removed regardless of the contents
     of the $Password string.
$Domain          - domain on which authentication is to occur.
                   15 chars limitation.
$CallbackNumber  - callback phone number
$fRemovePassword - (above) 0 if undefined/omitted
            
          

This is another excerpt from the API docs:

Windows NT: You can use $Password to send a new password to the remote server when you restart a RasDial() connection from a RASCS_PasswordExpired paused state. When changing a password on an entry that calls Microsoft Networks, you should limit the new password to 14 characters in length to avoid down-level compatibility problems.

Croaks if $entry does not exist.

RasGetEntryProperties ( )

This function retrieves the properties of a phonebook entry.

            

              
              
$props = RasGetEntryProperties($entry);
$entry          - name of RAS/DUN entry
$props          - pointer to hash
            
          

The description of the %$props hash is common for this function and RasSetEntryProperties().

            

              
              
KEY                         VALUE
name           - copy of $entry
Flags          - numeric flag value, combination of RASEO_* flags.
                 You don't need to use it directly, it's here for
                 information purpose only. In RasSetEntryProperties()
                 it is ignored if present, you should manipulate
                 mnemonic flags as described below, with the
                 'newFlags' key.
FlagsReadable  - $props->{FlagsReadable} refers to array of
                 "mnemonic flags" that are affecting the behavior
                 of the other properties.
                 Not used by RasSetEntryProperties().
            
          

Manipulating these flags is described in RasSetEntryProperties() section.

            

              
              
ipaddr         - constant ip-address, ignored unless "SpecificIpAddr"
                 is present in the array of "mnemonic flags"
ipaddrDns      - primary DNS server
ipaddrDnsAlt   - secondary(backup) DNS server
ipaddrWins     - IP address of the primary WINS server
ipaddrWinsAlt  - secondary WINS server
            
          

ipaddrDns, ipaddrDnsAlt, ipaddrWins, ipaddrWinsAlt are ignored unless "SpecificNameServers" is present in the array of "mnemonic flags"

All IP-addresses are in xxx.xxx.xxx.xxx decimal form without leading zeros in each part(octet). For example: 195.100.0.28

The common rule here is that empty or blank values will produce 0.0.0.0 (as well as "0.0.0.0" itself).

            

              
              
CountryID        -
CountryName      -
CountryCode      -
AreaCode         -
            
          

(Country ID-Name-Code and AreaCode are described in the TAPIlineGetTranslateCaps() section except that here they are describing the computer you want to dial to.)

In RasSetEntryProperties() CountryName would be ignored. CountryID not matching CountryCode would give error. You could easily give only one of these two values. CountryCode would be counted properly if CountryID is given (described in TAPIlineGetTranslateCaps() section). But if you'll give CountryCode CountryID would be set equal to CountryCode that is sometimes incorrect but does not affect the dialup connection.

You can also check the correctness of the CountryID with the IsCountryID() function.

            

              
              
LocalPhoneNumber - phone number without country/area parts
Script           - script file's path.
                   On Win95 this is DialUp Scripting Tool script.
            
          

Windows NT: To indicate a SWITCH.INF script name, set the first character of the name to "[".

RasSetEntryProperties() function may have a problem saving the full script path (NT, fixed in the Service Pack 4). http://support.microsoft.com/support/kb/articles/Q160/1/90.asp

            

              
              
DeviceType     - one of the following string constants
                 (case-insensitive):
  "modem"    A modem accessed through a COM port
  "isdn"     An ISDN card with corresponding NDISWAN driver installed
  "x25"      An X.25 card with corresponding NDISWAN driver installed
             "x25" type is not implemented in RasSetEntryProperties()
             in this version of the module
  "vpn"      A Microsoft VPN Adapter
            
          

You can read a note about VPN and PPTP in the RasSetEntryProperties() section.

            

              
              
DeviceName    - name of a TAPI device to use with this phonebook entry
NetProtocols  - network protocols to negotiate.
                $props->{NetProtocols} refers to the array that can
                contain one or more of the strings
                (case insensitive in RasSetEntryProperties()):
  "NetBEUI"  NetBIOS End User Interface standard
  "Ipx"      IPX/SPX Compartible
  "Ip"       TCP/IP
FramingProtocol  - framing protocol used by the server.
                   One of the following strings:
                   "PPP", "Slip", "RAS"
                   (case insensitive in RasSetEntryProperties())
            
          

Limitations:

Subentries(multilink dialing) are currently not supported as well as X.25-related parameters. Current version of Win32::RASE also does not allow you to change 'DeviceType' and 'DeviceName' elements. This will be added in some future. Right now any changes in these fields will not affect the RasSetEntryProperties() execution.

Note: don't misuse this function, in list context it returns unreadable things for internal needs.

Croaks if $entry does not exist.

For an easy way to change just the phone-number take a look at the RasChangePhoneNumber() section.

RasPrintEntryProperties ( )

This function provides nice printing of a phonebook entry properties. For debugging, for fun etc.

            

              
              
RasPrintEntryProperties( $entry );
$entry          - name of RAS/DUN entry
            
          

Croaks if $entry does not exist.

RasGetEntryDevProperties ( )

This function retrieves the properties of a device used by the phonebook entry if this entry uses MS Unimodem compartible TSP (Telephone Service Provider) or in other words - Unimodem compartible driver, on Win95 - always.

            

              
              
$props = RasGetEntryDevProperties($entry);
$entry          - name of RAS/DUN entry
$props          - pointer to hash
            
          

(Sorry, the description might not be clear enough, just print your properties with the RasPrintEntryDevProperties() and it'd be much easier.)

The description of the %$props hash is common for this function and RasSetEntryDevProperties() (not implemented yet).

It's much likely that only a small part of the described data is really usefull. Look at the Win32 SDK/MS Platform SDK (TAPI Prorammer's Reference - "comm/datamodem", "COMMCONFIG", "DCB", "MODEMSETTINGS" sections) for more info.

            

              
              
KEY                         VALUE
name         - copy of $entry
DeviceName   - name of a TAPI device to use with this phonebook entry
DeviceType   - described in the RasGetEntryProperties() section
Options      - numeric flag value, combination of the Option flags
               that appear on the Unimodem Option page.
               This member can be a combination of these values:
  TERMINAL_PRE  (1) - Displays the pre-terminal screen.
  TERMINAL_POST (2) - Displays the post-terminal screen.
  MANUAL_DIAL   (4) - Dials the phone manually, if capable of doing so
  LAUNCH_LIGHTS (8) - Displays the modem tray icon.
  Only the LAUNCH_LIGHTS value is set by default
OptionsReadable  - an array ref, a readable representation of those
      Options, that are switched on. The array consists of zero or more
      strings
      "TERMINAL_PRE", "TERMINAL_POST", "MANUAL_DIAL", "LAUNCH_LIGHTS"
WaitBong         - Number of seconds (in two seconds granularity) to
                   replace the wait for credit tone (default - 10 s)
CallSetupFailTimer - the maximum number of seconds the modem should
      wait, after dialing is completed, for an indication that a
      modem-to-modem connection has been established. If a connection
      is not established in this interval, the call is assumed to have
      failed. This member is equivalent to register S7 in Hayes
      compatible modems.
InactivityTimeout  - the maximum number of seconds of inactivity
      allowed after a connection is established. If no data is either
      transmitted or received for this period of time, the call is
      automatically terminated.
      This time-out is used to avoid excessive long distance charges
      or online service charges if an application unexpectedly locks up
      or the user leaves.
SpeakerVolume    - one of the following values: "LOW", "MEDIUM", "HIGH"
      Note that actual volumes are hardware-specific.
SpeakerMode      - one of the following values:
     "OFF"       - The speaker is always off
     "CALLSETUP" - The speaker is on until a connection is established
     "ON"        - The speaker is always on
     "DIAL"      - The speaker is on until a connection is established,
              except that it is off while the modem is actually dialing
PreferredModemOptions - a numeric flag value. Specifies the modem
     options requested by the application. The local and remote modems
     negotiate modem options during call setup; this member specifies
     the initial negotiating position of the local modem. A combination
     of bit flags.
PreferredModemOptionsReadable - refers to array of strings that
     represent bit flags of the previous. Contains zero or more of the
     following strings:
     "COMPRESSION", "ERROR_CONTROL", "FORCED_EC",
     "CELLULAR", "FLOWCONTROL_HARD", "FLOWCONTROL_SOFT",
     "CCITT_OVERRIDE", "SPEED_ADJUST",
     "TONE_DIAL", "BLIND_DIAL", "V23_OVERRIDE"
     Comments:
     CCITT_OVERRIDE - When set, CCITT modulations are enabled for V.21
                      and V.22 or V.23.When clear, bell modulations
                      are enabled for 103 and 212A.
     V23_OVERRIDE   - When set, CCITT modulations are enabled for V.23.
                      When clear, CCITT modulations are enabled for
                      V.21 and V.22.
            
          

For V.23 to be set, both CCITT_OVERRIDE and V23_OVERRIDE must be set.

            

              
              
NegotiatedModemOptions - a numeric flag value. Specifies the modem
     options that are actually in effect. This member is filled in
     after a connection is established and the local and remote
     modems negotiate modem options. This value is read only.
     (On my Win95 - always 0).
NegotiatedModemOptionsReadable - the same ref to array of the readable
     strings as PreferredModemOptionsReadable,
     but for NegotiatedModemOptions.
NegotiatedDCERate - Specifies the DCE rate that is in effect.
     This member is filled in after a connection is established and
     the local and remote modems negotiate modem modulations.
     Also read-only.
            
          

DCE - Open Software Foundation (OSF) Distributed Computing Environment.

The DCB structure defines the control setting for a serial communications device. The following keys are members of the DCB structure.

            

              
              
DCB_BaudRate     - Specifies the baud rate at which the communications
     device operates. This member can be one of the following values:
     110, 300, 600, 1200, 2400, 4800, 9600, 14400, 38400,
     56000, 57600, 115200, 128000, 256000
DCB_Flags        - numeric flag value, concatenation of many DCB flags.
                   You don't need to use it directly, it's here for
                   information purpose only.
DCB_FlagsReadable - an array ref. The array consists of the 13 string
     values. Each string is in the form "flagname:value".
     The values are in most cases 0/1. The flags names are:
  fBinary          - Specifies whether binary mode is enabled.
      The Win32 API does not support nonbinary mode transfers, so this
      member should be 1. Trying to use 0 will not work.
      Under Windows 3.1, if this member is 0, nonbinary mode is
      enabled, and the character specified by the DBC_EofChar member
      is recognized on input and remembered as the end of data. (0/1)
  fParity          - Specifies whether parity checking is enabled (0/1)
  fOutxCtsFlow     - Specifies whether the CTS (clear-to-send) signal
      is monitored for output flow control. If this member is 1 and CTS
      is turned off, output is suspended until CTS is sent again. (0/1)
  fOutxDsrFlow     - Specifies whether the DSR (data-set-ready) signal
      is monitored for output flow control. If this member is 1 and DSR
      is turned off, output is suspended until DSR is sent again. (0/1)
  fDtrControl      - Specifies the DTR (data-terminal-ready)
                     flow control.
    This member can be one of the following values:
    0 - Disables the DTR line when the device is opened and leaves it
        disabled
    1 - Enables the DTR line when the device is opened and leaves it on
    2 - Enables DTR handshaking
  fDsrSensitivity  - Specifies whether the communications driver is
      sensitive to the state of the DSR signal. If this member is 1,
      the driver ignores any bytes received, unless the DSR modem input
      line is high. (0/1)
  fTXContinueOnXoff - Specifies whether transmission stops when the
      input buffer is full and the driver has transmitted the
      DCB_XoffChar character.
      If this member is 1, transmission continues after the input
      buffer has come within DCB_XoffLim bytes of being full and the
      driver has transmitted the DCB_XoffChar character to stop
      receiving bytes.
      If this member is 0, transmission does not continue until the
      input buffer is within DCB_XonLim bytes of being empty and the
      driver has transmitted the DCB_XonChar character to resume
      reception. (0/1)
  fOutX            - Specifies whether XON/XOFF flow control is used
      during transmission. If this member is 1, transmission stops when
      the DCB_XoffChar character is received and starts again when the
      DCB_XonChar character is received. (0/1)
  fInX              - Specifies whether XON/XOFF flow control is used
      during reception. If this member is 1, the DCB_XoffChar character
      is sent when the input buffer comes within DCB_XoffLim bytes of
      being full, and the DCB_XonChar character is sent when the input
      buffer comes within DCB_XonLim bytes of being empty. (0/1)
  fErrorChar        - Specifies whether bytes received with parity
      errors are replaced with the character specified by the
      DCB_ErrorChar member.
      If this member is 1 and the fParity member is 1, replacement
      occurs. (0/1)
  fNull             - pecifies whether null bytes are discarded.
      If this member is 1, null bytes are discarded when received.(0/1)
  fRtsControl       - Specifies the RTS (request-to-send) flow control.
      This member can be one of the following values:
      0 - Disables the RTS line when the device is opened and leaves
          it disabled.
      1 - Enables the RTS line when the device is opened and leaves
          it on.
      2 - Enables RTS handshaking. The driver raises the RTS line when
          the "type-ahead" (input) buffer is less than one-half full
          and lowers the RTS line when the buffer is more than
          three-quarters full.
      3 - Specifies that the RTS line will be high if bytes are
          available for transmission. After all buffered bytes have
          been sent, the RTS line will be low.
  fAbortOnError    - Specifies whether read and write operations are
      terminated if an error occurs. If this member is 1, the driver
      terminates all read and write operations with an error status if
      an error occurs. (0/1)
DCB_XonLim      - Specifies the minimum number of bytes allowed in the
      input buffer before the XON character is sent.
DCB_XoffLim     - Specifies the maximum number of bytes allowed in the
      input buffer before the XOFF character is sent. The maximum
      number of bytes allowed is calculated by subtracting this value
      from the size, in bytes, of the input buffer.
DCB_ByteSize    - Specifies the number of bits in the bytes transmitted
                  and received.
DCB_Parity      - Specifies the parity scheme to be used. This member
                  can be one of the following values:
                  "No parity", "Odd", "Even", "Mark", "Space"
DCB_StopBits    - Specifies the number of stop bits to be used.
                  This member can be one of the following values:
      0 - 1 stop bit
      1 - 1.5 stop bits
      2 - 2 stop bits
DCB_XonChar     - Specifies the value of the XON character for both
                  transmission and reception.
DCB_XoffChar    - Specifies the value of the XOFF character for both
                  transmission and reception.
DCB_ErrorChar   - Specifies the value of the character used to replace
                  bytes received with a parity error.
DCB_EofChar     - Specifies the value of the character used to signal
                  the end of data.
DCB_EvtChar     - Specifies the value of the character used to signal
                  an event.
            
          

Manipulating these flags is described in RasSetEntryDevProperties() section. (not implemented yet).

The function croaks if $entry does not exist.

RasPrintEntryDevProperties ( )

This function provides nice printing of a phonebook entry device properties if this entry uses MS Unimodem compartible TSP (Telephone Service Provider) or in other words - Unimodem compartible driver, on Win95 - always.

Look at the RasGetEntryDevProperties() section and Win32 SDK for more info.

Char values (XonChar, XoffChar, ErrorChar, EofChar, EvtChar) are printed in hexadecimal form like 0x13.

For debugging, for fun etc.

            

              
              
RasPrintEntryDevProperties( $entry );
$entry          - name of RAS/DUN entry
            
          

Croaks if $entry does not exist. Silently returns if the device is not Unimodem-compartible.

RasCopyEntry ( )

This function makes a copy of the existing RAS entry. Some properties of this newly created entry could then be changed with the use of RasSetEntryProperties(). In previous versions of the module it was the only way to create a new entry silently, programmatically. But as of 0.07 we have full featured RasCreateEntry().

You can also create new entry via dialog, see RasCreateEntryDlg().

            

              
              
RasCopyEntry( $oldname, $newname );
            
          

Croaks if $oldname does not exist or $newname already exists. You should call IsEntry() or RasEnumEntries() before to verify both.

$newname must contain at least one non-white-space alphanumeric character and cannot begin with a period (".").

Username, password etc. (see RasGetEntryDialParams() and RasSetEntryDialParams()) are not copied to the newly created entry.

RasSetEntryProperties ( )

This function changes the connection information for an existing entry.

            

              
              
RasSetEntryProperties( $props );
$props          - reference to hash with replacing properties
            
          

Mainly keys/values of the %$props hash are described in the RasGetEntryProperties() section. But here we can use just part of the full hash - if keys are undefined no changes will be made to the corresponding properties. Only $props->{name} has to contain a name of the existing phonebook entry, all other keys are optional.

Those properties that do exist in %$props will replace current properties. If $props->{some-key} is defined and empty ("") the corresponding property will be empty.

DeviceType, CountryName, Flags and FlagsReadable keys are not used by this function. Anyway, all unneeded keys will be ignored without any errors.

As of the version 0.07 you can change the RAS device using with the entry by specifying the new device name in $props->{DeviceName}. The function finds the device type internally, so $props->{DeviceType} is ignored if specified.

If "DeviceName" key is present in the %$props the function resets device properties for $props-{name}> entry to the default values (for the list of device properties see RasGetEntryDevProperties()). RasEnumDevices() function gives the RAS-capable devices enumeration.

Microsoft has confirmed a possible problem: With multiple modems installed under Windows NT 4.0, the RasSetEntryProperties API function calls will reset the selected modem to the first available modem. This problem has been corrected in the latest U.S. Service Pack (4).

Print the whole enumeraton like this:

            

              
              
%devices = RasEnumDevices() or die "Error";
print map "\"$_\" of type \"$devices{$_}\"\n", keys %devices;
            
          

In addition to the keys decribed in the RasGetEntryProperties() section the string value $props->{newFlags} can be used for adding/removing the existing flags within the RAS-entry.

This string has the format: "<token1> <token2>..." (any \s separators are possible)

Each token can be one of the following values (same as mnemonic flags described in the RasGetEntryProperties() section):

            

              
              
UseCountryAndAreaCodes
SpecificIpAddr
SpecificNameServers
IpHeaderCompression
RemoteDefaultGateway
DisableLcpExtensions
TerminalBeforeDial
TerminalAfterDial
ModemLights
SwCompression
RequireEncryptedPw
RequireMsEncryptedPw
RequireDataEncryption
NetworkLogon
UseLogonCredentials
PromoteAlternates
SecureLocalFiles
            
          

These strings are just the meaningful parts of RASEO_* constants' names (from "ras.h" file). They are rather descriptive, you can easily find their meaning by changing and printing an existing RAS entry. Not all of them will work in this version of the module.

Each of these flags could be used with or without the "RASEO_" prefix. With or without `+' or `-' prefix (no blanks between [+-] and "mnemonic flag") - this is the token mentioned above.

Additional token that can't be prefixed with `+' or `-' is "KeepOldFlags", it still can be prefixed with "RASEO_".

If this new flag-string ($props->{newFlags}) is defined the default action is to reset all old flags. "KeepOldFlags" prevents from this cleanup.

The token with `-' will reset the corresponding flag if it was set, otherwise - no effect. The token with `+' will set the corresponding flag if it was not set, otherwise - no effect. The order of tokens is not important, tokens are separated by any number of blanks. Token without `+' or `-' means `+'.

Examples:

"NetworkLogon +SwCompression" - reset old flags and add these two.

"-NetworkLogon -SwCompression KeepOldFlags" - keep old flags and clean these two.

The function croaks if $entry does not exist and on some impossible values of the parameters.

PPTP note (Point to Point Tunneling Protocol): You can use an ip-address in place of LocalPhoneNumber if your DUN/RAS entry is configured to work with VPN (Virtual Private Networking) via PPTP. PPTP appears as a new modem type that can be selected in DUN entry only manually. It DeviceName is "Microsoft VPN Adapter" and DeviceType is "vpn". In this case you can change the ip-address of the VPN-host as if it were local phone number. For example

            

              
              
RasSetEntryProperties({
      name=>"NEV5",
      LocalPhoneNumber=>"21.100.14.12",
});
            
          

You can get info about VPN and PPTP at

http://support.microsoft.com/support/kb/articles/q154/0/91.asp

DUN 1.3 that supports VPN is downloadable from

http://support.microsoft.com/download/support/mslfiles/MSDUN13.EXE

and is described here

http://support.microsoft.com/support/kb/articles/q194/4/77.asp

Thanks to Carl Sewell <csewell@hiwaay.net> for his explanations and testing of VPN features.

Microsoft has confirmed the possible problem: After applying Service Pack 2, the RasSetEntryProperties flags for RASEO_TerminalAfterDial and RASEO_TerminalBeforeDial specified in the Win32 function call are not set. This problem occurs because Service Pack 2 causes the parameters to be ignored. This problem has been corrected in Service Pack 3.

http://support.microsoft.com/support/ntserver/serviceware/nts40/E9MSL2CSA.ASP

Microsoft: When using the RasSetEntryProperties API call to change the connection information for an entry in the phone book or create a new phone-book entry, the szScript ($props-{Script}> in Win32::RASE) parameter of the RASENTRY structure is not always preserved.

http://support.microsoft.com/support/kb/articles/q160/1/90.asp

This problem applies to WinNT 4.0 and was corrected in the latest Microsoft Windows NT 4.0 U.S. Service Pack (4).

The function croaks if the specfied device is not found.

RasCreateEntry ( )

This function creates RAS/DUN entry programmatically (note that RasCreateEntryDlg() displays dialo boxes).

            

              
              
RasCreateEntry( $props );
            
          

Win32::RASE::PHONEBOOK defines the phonebook in which the new entry will be created (WinNT).

For the explanation of the %$props hash see the previous RasSetEntryProperties() function. The main difference is that these keys

            

              
              
name, LocalPhoneNumber, NetProtocols, FramingProtocol, DeviceName
            
          

are mandatory in this hash.

You have to specify at least one of CountryID and CountryCode keys and AreaCode key if $props-{newFlags}> contains "+UseCountryAndAreaCodes".

All ip-addresses if omitted are assumed to be "0.0.0.0". Empty or non-existing $props-{newFlags}> gives zero numeric flag which means that none of the RASEO_* options are in use. Flag "KeepOldFlags" has no meaning but makes no error.

Note that the device settings would be copied from your system defaults and some minor features still could not be customized (see RasGetEntryDevProperties()).

RasChangePhoneNumber ( )

This is a simplified version of the RasSetEntryProperties().

            

              
              
RasChangePhoneNumber($entry, $new_phone_number);
$entry             - name of RAS/DUN entry
$new_phone_number  - fully qualified phone number of the remote
                     computer in almost any human-readable form.
            
          

For example:

            

              
              
'7-095-5555555' or '7(095)5555555' or '7 -( 095)-555-5555'
or '+7 (095) - 5-5-5-5-5-5-5' or '7 095 5555555'
            
          

It is smart enough to adjust entry flags to avoid long distance dialing if country and area codes are the same as in Dialing Properties/Default Location. All other flags are kept unchanged.

Note! country code here is not TAPI countryID.

=====================================

CONNECTION RELATED FUNCTIONS

=====================================

RasEnumConnections ( )

            

              
              
%connections = RasEnumConnections ( );  or as list
($entry1, $hrasconn1, ...) = RasEnumConnections ( );
            
          

Returns handles for each active RAS/DUN connection. $entry is entry-name. $hrasconn is a numeric handle that might be used in RasHangUp() to hang up the active connection or in RasGetConnectStatus() or in RasGetProjectionInfo().

Croaks on errors. Returns FALSE if no one active connection was found.

Note that RasDial() also returns $hrasconn on success.

RasGetProjectionInfo ( )

In the current version projection info is implemented for IP protocol only. This is a subject to change.

            

              
              
($ip, $server_ip) = RasGetProjectionInfo ( $hrasconn );
$hrasconn  - handle of the active connection returned by either
             RasDial() or RasEnumConnections().
$ip        - the client's IP address on the RAS connection
$server_ip - the IP address of the remote PPP peer (that is, the
             server's IP address)
            
          

Both IP addrs are in "nnn.nnn.nnn.nnn" form.

From the API docs:

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 RasGetProjectionInfo() is called 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 RasGetProjectionInfo() is called prior to the RASCS_Authenticated state, it returns ERROR_PROTOCOL_NOT_CONFIGURED.

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 ("").

I guess the last note is probably outdated because my Advanced Dialer has a field for "Server's IP address" - so, it expects that it's always available.

If you are using Win32::RASE in a single process application you can't monitor RASCS_* states (for more info look at RasGetConnectStatus()). So, the rule is: use this function after RasDial() successfully returned $hrasconn.

The typical usage if you have only one connection is:

            

              
              
unless ( $hrasconn = (RasEnumConnections())[1] ) {
print "Dialing sequence not started\n";
} elsif ( ($ip, $server_ip) = RasGetProjectionInfo( $hrasconn ) ) {
print "LOCAL:$ip  SERVER:$server_ip\n";
} elsif ( Win32::RASE::GetLastError == 731 ) {
print "Protocol not configured yet\n";
} else {
die Win32::RASE::FormatMessage();
}
            
          

Note also that LastError=6 means that $hrasconn is an invalid handle.

Command line syntax:

            

              
              
perl -MWin32::RASE -e "$,=', ';print RasGetProjectionInfo((RasEnumConnections)[1])"
            
          

RasHangUp ( )

            

              
              
RasHangUp($hrasconn [, $timeout]);
$hrasconn  - handle of the active connection returned by either
             RasDial() or RasEnumConnections().
$timeout   - in sec, optional (3 sec by default). Maximum time to wait
             for graceful disconnection. You can use float values if
      Time::HiRes is installed. Otherwise cycle uses sleep(1)
             and thus wastes some additional time.
            
          

This function gracefully terminates the connection. You don't need to add any sleep after it.

The connection is terminated even if the RasDial() call has not yet been completed.

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

Returns FALSE if invalid handle was given but this is harmless most of the time. Probably the connection failed itself and $hrasconn is not valid any more. So, you don't have to trap this error.

Returns FALSE on timeout also (connection might be still active). LastError is 0 in this case. So the exact logic is:

            

              
              
if ( RasHangUp($hrasconn, $timeout) ) {
print "Connection is terminated successfully.\n";
} elsif ( !Win32::RASE::GetLastError ) {
print "Timeout. Connection is still active.\n";
} else {
# we don't have to die here
warn Win32::RASE::FormatMessage(), "\n";
}
            
          

For more take a look at the API docs.

HangUp ( )

This is the easier version of previous.

Without parameters it will terminate all active connections, otherwise terminates connections by entry-names given as parameters. Note that this function uses entry-names, not handles.

            

              
              
$code = HangUp ( [$entry1, ...] );
            
          

Returns FALSE if at least one connection was not terminated gracefully, otherwise TRUE even if no one active connecton was found.

Command line syntax:

            

              
              
perl -MWin32::RASE -e HangUp
            
          

RasGetConnectStatus ( )

This function is used to monitor active connection in progress. In most cases it's good to cycle calls to this function after a very small interval, say 0.1 sec or less - at least at the dialing time. It's possible in multithreading process (thread safety is not verified in this version) or one process can monitor another, which is closer to perl practice.

            

              
              
$status = RasGetConnectStatus($hrasconn);
            
          

or

            

              
              
($status, $status_text) = RasGetConnectStatus($hrasconn);
$hrasconn - handle to active RAS/DUN connection
            
          

In scalar context returns numeric status (RASCS_* enumerator values) or FALSE if $hrasconn is not a valid handle (LastError is set to 6).

In list context returns numeric status and the string that characterizes this status in short (the descriptive part of the corresponding RASCS_ constant's name, like "OpenPort") or FALSE if handle is invalid.

FALSE is also returned if handle is "not valid any more", i.e. connection is terminated.

These string constants ("PortOpened" etc.) are stored in a non-exported hash %Win32::RASE::RASCS where the keys are numeric values of the corresponding RASCS_* constants. So

            

              
              
$Win32::RASE::RASCS{1} eq "PortOpened"
            
          

You can check status yourself against exported RASCS_* constants:

            

              
              
RASCS_OpenPort
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_SubEntryConnected
RASCS_SubEntryDisconnected
RASCS_Interactive  =  RASCS_PAUSED
RASCS_RetryAuthentication
RASCS_CallbackSetByCaller
RASCS_PasswordExpired
RASCS_Connected  = RASCS_DONE
RASCS_Disconnected
            
          

From the API docs:

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 = $status & RASCS_DONE;
$fPausedState = $status & RASCS_PAUSED;
$fRunState = !($fDoneState || $fPausedState);
            
          

RasDialDlg ( )

This function tries to establish a RAS connection using a specified phonebook entry and the credentials of the logged-on user. It displays a stream of dialog boxes that indicate the state of the connection operation and returns when the connection is established, or when the user cancels the operation. Windows NT only.

            

              
              
RasDialDlg( $EntryName [, $hwnd, $PhoneNumber] );
$EntryName    - RAS/DUN entry, the only mandatory parameter
$hwnd         - Identifies the window that owns the modal RasDialDlg
                dialog boxes.
                This member can be any valid window handle, or it can
                be 0, undef (or omitted) if the dialog box has no owner
            
          

The dialog box is centered on the owner window unless $hwnd is FALSE or invalid handle, in which case the dialog box is centered on the screen.

            

              
              
$PhoneNumber  - an overriding phone number (if not needed - use "" or
                undef).
            
          

It does not inherit anything from phonebook if specified - no prefix, no callin card, no waiting. You should even add DP before the number for pulse dialing.

Returns TRUE on success, FALSE if user selects "Cancel" button or an error occurs. You can check the last case with Win32::RASE::GetLastError().

            

              
              
if ( RasDialDlg("NEV4") ) {
print "Connection established\n";
} elsif ( !Win32::RASE::GetLastError ) {
print "User selected <Cancel>\n";
} else {
warn Win32::RASE::FormatMessage(), "\n";
}
            
          

RasDial ( )

This function establishes a RAS/DUN connection. The connection data includes callback and user authentication information.

            

              
              
$hrasconn = RasDial($EntryName, $PhoneNumber, $UserName, $Password,
                     $Domain, $CallbackNumber);
$EntryName   - RAS/DUN entry, the only mandatory parameter
$PhoneNumber - an overriding phone number (if not needed - use "" or
               undef).
            
          

It does not inherit anything from the phonebook if specified - no prefix, no calling card, no waiting. You should add DP before the number for pulse dialing.

            

              
              
$UserName    - user's user name (look below)
$Password    - user's password
$Domain      - domain on which authentication is to occur. An empty
     string ("" or undef) specifies the domain in which the remote
     access server is a member (NT only). An asterisk specifies the
     domain stored in the phonebook for the entry.
     It's in addr form (size is limited to 15 chars).
$CallbackNumber - a callback phone number. An empty string ("") or
     undef indicates that callback should not be used. This string is
     ignored unless the user has "Set By Caller" callback permission
     on the RAS server (NT only). An asterisk indicates that the number
     stored in the phonebook should be used for callback.
            
          

Windows NT: [These 2 paragraphs are copied from the API docs. I wanted to add this for some completeness but I was told that probably this is not truth and if Username or Password are empty user will get a dialog box with Username/Password prompts.]

RAS does not actually log the user onto the network. The user does this in the usual manner, for example, by logging on with cached credentials prior to making the connection or by using CTRL+ALT+DEL, after the RAS connection is established.

If both the UserName and Password members are empty strings (""), RAS uses the user name and password of the current logon context for authentication. For a user mode application, RAS uses the credentials of the currently logged-on interactive user. For a Win32 service process, RAS uses the credentials associated with the service.

Windows 95:

RAS uses the UserName and Password strings to log the user onto the network. Windows 95 cannot get the password of the currently logged-on user, so if both the UserName and the Password members are empty strings ("" or undef), RAS leaves the user name and password empty during authentication. I.e. it provides no additional search (look at RasGetEntryDialParams() for that).

Note: It seems that overriding phone number is being dialed "as is" - without using any long-distance/international phone settings. So you have to provide this number with all prefixes and waitings (W etc.) if needed. Additional dashes, blanks and brackets are OK.

            

              
              
$hrasconn  - on success - handle to active RAS/DUN connection,
             otherwise undef
            
          

You can use $hrasconn in RasGetConnectStatus() or RasHangUp(). Note that this function calls RasHangUp() internally on error, so after that, the handle of the failed connection is not available and the port is ready for the next try.

Example:

            

              
              
($err, $errtext) = RasDial("CLICK",undef,"ppblazer","qwerty");
if ($err) {
   print "$err, $errtext\n"; exit;
} else {
   ... your work here ...
}
            
          

Last note: this is the synchronous operation. Nobody knows if it could really hang fast enough if the line is busy (for ex.) The best way would be to run RasDial() in the separate process or thread. In most cases you don't really need $hrasconn in the main process - you can terminate the connection at any time with HangUp(). Or you can easily get $hrasconn with the use of RasEnumConnections().

If you run RasDial() in a child-process and terminate dialing in progress (for ex. on timeout) you have to free the port yourself (RasHangUp() or HangUp()).

For more info take a look at Win32 API docs (RASDIALPARAMS etc).

Command line syntax:

            

              
              
perl -MWin32::RASE -e RasDial(NEV1,undef,ppblazer,'6hTR7dwA')
perl -MWin32::RASE -e "RasDial(NEV1,undef,ppblazer,'6hTR7dwA') or print Win32::RASE::FormatMessage"
perl -MWin32::RASE -e "print RasDial(NEV1,undef,ppblazer,'6hTR7dwA')||Win32::RASE::FormatMessage"
            
          

=====================================

TAPI RELATED FUNCTIONS

=====================================

RasEnumDevices ( )

            

              
              
%devices = RasEnumDevices();
            
          

This function returns the name and type of all available RAS-capable devices. In the %devices hash device names are keys and types are values. Common device types are "modem", "x25", "vpn", "isdn", "rastapi" etc.

Croaks on errors. Returns FALSE if no one RAS capable device was found.

For example the first RAS-capable device name is

            

              
              
$DeviceName = (RasEnumDevices())[0];
            
          

This function fills out a non-exported hash %Win32::RASE::RasDevEnumeration of the same structure as %devices, so in most cases there is no need to call this function more then once.

Command line syntax:

            

              
              
perl -MWin32::RASE -e "print ((RasEnumDevices)[0])"
            
          

RasEnumDevicesByType ( )

The easier version of previous.

            

              
              
@DevNames = RasEnumDevicesByType( $devtype );
            
          

Returns names of RAS-capable devices of type $devtype. For example the first modem's name

            

              
              
$ModemName = (RasEnumDevicesByType("modem"))[0];
            
          

$devtype is case insensitive.

TAPIlineGetTranslateCaps ( )

This function is not exported and is not intended for public use. It is called each time you load Win32::RASE and fills out 3 global variables and global hash (below).

It takes local information from your dialup settings.

            

              
              
($countryID, $countryCode, $areaCode) =
   Win32::RASE::TAPIlineGetTranslateCaps ();
            
          

The return values are describing the Current Location that is selected in you dialing properties.

            

              
              
$countryID  -  the unique number that TAPI assigns to each country.
               It is not what you are typing on your phone, though it
               sometimes has the same value. Different countries always
               have different countryID. This allows multiple entries
               to exist in the country list with the same country code
               (for example, all countries in North America and the
               Caribbean share country code 1, but require separate
               entries in the list).
$countryCode - this really is the code that would be dialed in an
        international call to your computer's location.
$areaCode    - city or area code (local).
            
          

These 3 values are copied to non-exported global variables $Win32::RASE::LOCAL_ID, $Win32::RASE::LOCAL_CODE and $Win32::RASE::LOCAL_AREA.

They are mainly for internal use, just note that they are here.

The complete TAPI countries list is being copied to non-exported global hash %Win32::RASE::TAPIEnumeration. Keys are countryID's, each value points to 3-element array: [0] is country-name, [1] is countryCode described above, [2] is NextCountryID in TAPI-enumeration (TAPI docs, but in most cases you don't need to use this hash explicitly).

Use TAPIEnumerationPrint() to print this hash (for fun ;)

TAPIEnumLocations ( )

Just a handy function (non-exported) to enumerate locations in your Dialing Properties. It's being executed internally when Win32::RASE needs it, so in most cases you don't need to use it explicitly.

            

              
              
($CurrentLocation, %locations) = Win32::RASE::TAPIEnumLocations;
$CurrentLocation   - current dialing location's name
%locations         - keys are location-names, values are anonymous
                     arrays that are filled out like:
   [$CountryID, $CountryCode, $CityCode, $Options, $LocalAccessCode,
    $LongDistanceAccessCode, $TollPrefixList, $PermanentLocationID]
$Options                - 0/1 tone/pulse dialing, this value could be
                          used to define good timeout for RasDial()
$LocalAccessCode        - the access code to be dialed before calls to
                          addresses in the local calling area
$LongDistanceAccessCode - the access code to be dialed before calls to
                          addresses outside the local calling area
$TollPrefixList         - the toll prefix list for the location. The
                          string will contain only prefixes consisting
                          of the digits "0" through "9", separated
                          from each other by a single comma
$PermanentLocationID    - internal unique identifier of the location
            
          

Other values in array are described in TAPIlineGetTranslateCaps().

Example:

            

              
              
($CurrentLocation, %locations) = Win32::RASE::TAPIEnumLocations;
print "$CurrentLocation\n";
print map "$_ => [".(join", ",@{$locations{$_}})."]\n",
    keys %locations;
            
          

TAPISetCurrentLocation ( )

            

              
              
TAPISetCurrentLocation( $location );
$location   - optional, the name of the location that is configured
              in the Dialing Properies.
              If omitted the "Default Location" is used.
            
          

Returns TRUE on success, FALSE if $location was not found in the Dialing Properties, croaks on TAPI errors.

TAPIEnumerationPrint ( )

This function prints nicely formatted TAPI countries table that is stored in the %Win32::RASE::TAPIEnumeration (see above). Not exported by default;

            

              
              
Win32::RASE::TAPIEnumerationPrint();
            
          

Columns: CountryID, CountryName, CountryCode, NextCountryID

For more: TAPIlineGetTranslateCaps() and TAPI docs.

Always returns TRUE.

TAPICountryName ( )

Returns CountryName by CountryID or FALSE if given CountryID does not exist in TAPI-table.

            

              
              
$CountryName = TAPICountryName($CountryID);
            
          

Command line syntax:

            

              
              
perl -MWin32::RASE -e "print TAPICountryName(1)"
            
          

TAPICountryCode ( )

Returns CountryCode by CountryID or FALSE if given CountryID does not exist in TAPI-table.

            

              
              
$CountryCode = TAPICountryCode($CountryID);
            
          

IsCountryID ( )

Returns TRUE if given $CountryID exist in TAPI-table, otherwise FALSE.

            

              
              
IsCountryID($CountryID);
            
          

Just to have such a pretty name ;)

TAPIlineInitialize ( )

This is a non-exported function mainly for internal use. It could be handy only if you'd start writing your own TAPI-related functions.

            

              
              
($hLineApp, $dwNumDevs) = Win32::RASE::TAPIlineInitialize();
            
          

or in scalar context

            

              
              
$hLineApp = Win32::RASE::TAPIlineInitialize();
$hLineApp  - the application's usage non-zero handle for TAPI
$dwNumDevs - number of line devices available to the TAPI application
            
          

Croaks on TAPI errors.

The applicaton should always call TAPIlineShutdown() to release memory resources allocated by TAPI.DLL.

TAPIlineShutdown ( )

This is a non-exported function mainly for internal use. It could be handy only if you'd start writing your own TAPI-related functions.

            

              
              
Win32::RASE::TAPIlineShutdown($hLineApp);
$hLineApp  - the application's usage handle for TAPI
            
          

Returns zero if the request is successful or a negative error number if an error has occurred.

INSTALLATION

As this is just a plain module no special installation is needed. Put it into the Win32 subdirectory somewhere in your @INC.

This module needs Windows Remote Access Service (RAS) or DialUp Networking (DUN) to be properly installed including dialing properties.

rasapi32.dll, tapi32.dll

Win32::API module by Aldo Calpini.

enum.pm (1.014 or later, no compilations) by Byron Brummer (aka Zenin)

Time::HiRes (0.18 or later) by Douglas E. Wegscheid makes work more precise.

CAVEATS

This module has been created and tested in a Win95 environment. Although I expect it to function correctly on any version of Windows NT, that fact has been confirmed for NT 4.0 build 1381 only.

Some of the RAS APIs were not included in the RasAPI32.dll that was shipped with the old releases of Windows 95. To use the RAS APIs mentioned here, you need to install the at least Dial Up Networking (DUN) 1.2b upgrade. This upgrade is available for download on:

http://www.microsoft.com/windows/downloads/contents/Updates/W95DialUpNetw/default.asp

This upgrade was incorporated in Win95 OSR.

From the MS KB# Q157765: Early releases of Windows 95 may require an additional RNAPH.DLL that contains some of new phonebook manipulation APIs. There currently is no workaround for this situation in this version of the module.

Some APIs may also not work properly on WinNT with old Service Packs. Make sure that you are using the last Service Pack available. List of Bugs Fixed in Windows NT 4.0 Service Pack 1, 2, and 3 is available at

http://support.microsoft.com/support/kb/articles/q224/7/92.asp

What can we do here, guys? That's how it goes...

CHANGES

            

              
              
1.00  First public release
1.01  The only thing touched is Makefile.PL. The distribution is packed
      now using UNIX conventions (LF only, unlike the 1.00 dist)
            
          

TODO

NT-only API: RasGetCredentials, RasSetCredentials, RasMonitorDlg, RasPhonebookDlg.

Any suggestions are much appreciated.

BUGS

Please report.

VERSION

This man page documents "Win32::RASE" version 1.01.

January 19, 2000.

CREDITS

Thanks to Carl Sewell <csewell@hiwaay.net> for his great help and patience in testing on NT. If these docs are more or less readable - it's due to his corrections and improvement.

Thanks to Jan Dubois <jan.dubois@ibm.net> for numerous great tips and explanations.

Guys, you are cool! ;)

AUTHOR

Mike Blazer, blazer@mail.nevalink.ru

http://www.dux.ru/guest/fno/perl/

SEE ALSO

Win32 SDK, TAPI docs.

COPYRIGHT

Copyright (C) 1999 Mike Blazer.

This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Win32::RASE

perl -MCPAN -e shell
install Win32::RASE