. DirectXtras Home
        Home

DirectCommunication Xtra
DirectConnection Xtra
Documentation
License Agreement
Licensing Fees
Order Form
DirectControl Xtra
DirectEmail Xtra
DirectFTP Xtra
DirectImage Xtra
DirectInteraction Xtra
DirectOS Xtra
DirectSMS Xtra
DirectSound Xtra
DirectTransition Xtra
DirectTransition3D Xtra Set I
DirectTransition3D Xtra Set II
DirectTransition3D Xtra Set III
DirectTTS Xtra
XtrAgent
DirectXport Xtra

SpeechPlugin

Special Discounted Bundles

The Gallery
How To Order
Order Form
Check for Upgrades

Sign in
Change Your Profile

Contact Us
















    .
DirectXtras
Xtra Power for Director & Authorware



DirectConnection Xtra
 Connect (and disconnect) your applications to the Internet!

Authorware 4.x Compatible Authorware 5.x CompatibleAuthorware 6.x CompatibleAuthorware 7.x CompatibleDirector 5.x Compatible Director 6.x CompatibleDirector 7.x Compatible Director 8.x CompatibleDirector MX CompatibleDirector MX 2004 Compatible     MacOS 8.x and 9.x CompatibleWindows Compatible   

DirectConnection Xtra™ Version 1.5.1 Documentation




Developed by Tomer Berda, DirectXtras Inc.
(C) Copyright 1998-2003.
Last updated: January 13, 2003.


DirectConnection is a cross-platform Scripting Xtra for Macromedia Director and Authorware that lets you control the process of establishing a dial-up connection with another computer.

A properly written Internet-enabled application should automatically connect to a user's ISP on an as-needed basis.
DirectConnection Xtra makes doing this possible and simple.

By using DirectConnection Xtra you can:

  • Check whether there is an active dial-up connection to the Internet.
  • Connect and disconnect your applications to the Internet on an as-needed basis. No interaction from the user is necessary. The process can take place in the background, invisibly!
  • Connect and disconnect other dial-up connections.
  • Create, delete and modify dial-up connection profiles.
  • Get and set dial-up connection properties.

DirectConnection  Xtra is available for Director 5 and above, Authorware 4 and above, and is compatible with Windows 9X and newer (including 2000, ME, NT, XP) as well as MacOS 8 and 9. The MacOS version supports OT/PPP, RA and FreePPP.


Quick Start

Checking for Internet connection

In order to check whether there's an active dial-up connection to the Internet, your application should first call dcGetActiveConnections() to get a list of all active dial-up connections.

Once you have a list of active dial-up connections, call dcGetConnectionInfo() to check the ClientIpAddress item of each one of them.
If it is not empty string, then the associated dial-up connection is connected to the Internet.

Connect to the Internet

In order to automatically connect your application to the Internet, using the default dial-up connection, your application should first call dcGetDefaultInternetConnection() to locate the default dial-up connection used to connect to the Internet.

If no default configuration is available on the system, your application should call dcGetConnections() to get a list of available dial-up connections, and let the user choose one of them as the default for your application. It's recommended to store the user preference for future uses.

Disconnect from the Internet

In order to disconnect a user from the Internet, you should call dcHangUp() and pass the name of the dial-up connection used to establish the Internet connection.
If your application was not the one who made the connection to the Internet, or you don't know the name of the dial-up connection that is currently connected to the Internet, use the guidelines described in the 'Checking for Internet connection' section above to find the dial-up connection name that is currently connected to the Internet.

Method Reference


dcRegister ( integer SerialNumber )

Once you've registered your copy of DirectConnection Xtra, pass your serial number to this method to get rid of the trial warnings and to activate the run-time version of the Xtra, which you will receive with the registered package.
You have to call this method once during the lifetime of your application, before calling any of the other DirectConnection Xtra methods.
Be sure to protect the dcRegister() call so your serial number will not get exposed to the public.

dcGetConnections ( )

Returns a list containing names of all the available dial-up connections on the system.

On Windows, the returned list applies to connections configured in the dial-up networking. On MacOS, the returned list applies to connections configured in the active PPP control, as specified in the Control Panel->TCP/IP->Connect via menu.

If the returned value is an empty list, you should call dcGetLastErrorCode() or
dcGetLastErrorMessage() to check whether an error has occured. If no error has occured, the reason for the returned empty list is that there are no dial-up connections installed on the system.

dcGetDefaultInternetConnection ( )

Returns the name of the default dial-up connection used to connect to the Internet.

On Windows, the default dial-up connection is configured in the Control Panel->Internet. On MacOS, it is the default connection of the active PPP control, as specified in the Control Panel->TCP/IP->Connect via menu.
If no default connection was configured, the returned value is an empty string.

On Windows, it is recommended to verify that the returned connection is currently available on the system, according to dcGetConnections() method, as it is possible, though not likely, that the default connection was manualy deleted without selecting a different default connection.

dcGetActiveConnections ( )

Returns a list containing names of all active dial-up connections.

If the returned value is an empty list, you should call dcGetLastErrorCode() or
dcGetLastErrorMessage() to check whether an error has occured. If no error has occured, the reason for the returned empty list is that there are no active dial-up connections on the system.

dcGetConnectionStatus ( string ConnectionName )

Retrieves information on the current status of the specified dial-up connection.

If the function succeeds, the returned value is non-zero, describing the connection status.
If the function fails, the returned value is zero, and you should call dcGetLastErrorCode() or dcGetLastErrorMessage() to get more information on why a connection could not be established. You should then call dcHangUp() to terminate the connection.

Parameter :

Connection : Name of the dial-up connection.

Returned values:

The following 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, as they may vary between platforms.

1 - The communication port is about to be opened.
2 - The communication port has been opened successfully.
3 - A device is about to be connected.
4 - A device has connected successfully.
5 - All devices in the device chain have successfully connected.
At this point, the physical link is established.
6 - The authentication process is starting.
7 - An authentication event has occurred.
8 - The client has requested another validation attempt with a new user name/password/domain.
9 - The remote access server has requested a callback number.
10 -
The client has requested to change the password on the account.
11 - The projection phase is starting.
12 - The link-speed calculation phase is starting.
13 - An authentication request is being acknowledged.
14 - Reauthentication is starting.
15 - The client has successfully completed authentication.
16 - The line is about to disconnect in preparation for callback.
17 - The client is delaying in order to give the modem time to reset itself in preparation for callback.
18 - The client is waiting for an incoming call from the remote access server.
19 - Indicates that projection result information is available.

100 - Successful connection.
199 - Disconnecting.
200 - Disconnected
.

0 - Connection has failed. Call dcGetLastErrorCode() or dcGetLastErrorMessage() for more info.

dcDial ( string ConnectionName, integer How, string Password )

Establishes a dial-up connection.

Parameters :

Connection : Name of the dial-up connection to dial.

How : An integer specifing how dcDial() call should operates.

Can be one of the following numbers:

0 - dcDial() call operates synchronously.
It does not return until the connection attempt has completed successfully or failed. If the function succeeds to establish a connection, the returned value is non-zero. If the function fails, the returned value is zero, and you should call dcGetLastErrorCode() or dcGetLastErrorMessage() to get more information on the error.

1 - dcDial() call operates asynchronously.
It returns immediately, before the connection is established.
If the function succeeds, the returned value is non-zero, and you can then call
dcGetConnectionStatus()
to determine the connection status.
If the function fails, the returned value is zero, and you should call dcGetLastErrorCode() or dcGetLastErrorMessage() to get more information on the error.

On MacOS, this option (asynchronous mode) is only supported by OT/PPP where it also hides the progress dialog window when connecting and disconnecting. FreePPP always connect synchronously and ignore this parameter.

Password : A string containing the user's password. This string is used to authenticate the user's access to the remote access server.

On Windows, you can pass an empty string in order to use the password associated with the connection, as returned by dcGetConnectionDialParams(). Specifing a password will cause dcDial() to use it instead of the one associated with the connection. This may be useful in cases where the connection has no password associated with it, for example when the "Save Password" checkbox is not checked.

This parameter is ignored on the MacOS.

 

dcHangUp ( string ConnectionName )

Terminates a dial-up connection.

If the function succeeds, the returned value is non-zero, and you can call
dcGetConnectionStatus()
to determine when the termination proccess completed.
If the function fails, the returned value is zero, and you should call dcGetLastErrorCode() or dcGetLastErrorMessage() to get more information on the error.

Parameter :

Connection : Name of the dial-up connection to terminate.

dcCreateConnection ( )

Creates a new dial-up connection. The function displays a dialog box in which the user types information for the created dial-up connection.

If the function succeeds, the returned value is non-zero.
If the function fails, the returned value is zero, and you should call dcGetLastErrorCode() or dcGetLastErrorMessage() to get more information on the error.

In the MacOS version of the Xtra, this function launches the active PPP control panel, from which the user can create a new dial-up connection.

dcEditConnection ( string ConnectionName )

Edits an existing dial-up connection. The function displays a dialog box in which the user can modify the existing information.

If the function succeeds, the returned value is non-zero.
If the function fails, the returned value is zero, and you should call dcGetLastErrorCode() or dcGetLastErrorMessage() to get more information on the error.

Parameter :

Connection : Name of the dial-up connection to edit.

dcGetConnectionDialParams ( string ConnectionName )

Retrieves the connection information saved by the last successful call to
the dcDial() or dcSetConnectionDialParams() function for a specified dial-up connection.

Parameter :

Connection : Name of the dial-up connection.

If the function fails, the returned value is empty list, and you should call dcGetLastErrorCode() or dcGetLastErrorMessage() to get more information on the error.

If the function succeeds, the returned value is a list in the form of [UserName, Password] containing the user name and password associated with the connection. If the Password item couldn't be retrieved, it is set to empty string.

This function is not available in the MacOS version of the Xtra.

 

dcSetConnectionDialParams
( string ConnectionName, string UserName, string Password )

Changes the connection information saved by the last successful call to
the dcDial() or dcSetConnectionDialParams() function for a specified dial-up connection..

Parameters :

Connection : Name of the dial-up connection.
UserName : String containing the logon name of the user associated with the specified dial-up connection. If UserName is an empty string, the user name and password are not changed.
Password : String containing the password for the user specified by UserName.

If the function succeeds, the returned value is non-zero.
If the function fails, the returned value is zero, and you should call dcGetLastErrorCode() or dcGetLastErrorMessage() to get more information on the error.


This function is not available in the MacOS version of the Xtra.

 

dcGetConnectionInfo ( string ConnectionName )

Retrieves information on the current status of an active connection.

Parameter :

Connection : Name of the dial-up connection.

If the function fails, the returned value is empty list, and you should call dcGetLastErrorCode() or dcGetLastErrorMessage() to get more information on the error.

If the function succeeds, the returned value is a list in the form of
[DeviceType, DeviceName, ClientIpAddress, ServerIpAddress]
where:

DeviceType is a string that specifies the type of the current device, if available.
For example, common device types supported are "modem", "pad", "switch", "isdn", or "null".
DeviceType item is not available in the MacOS version of the Xtra.

DeviceName is a string that specifies the name of the current device, if available.
This would be the name of the modem — for example, "Hayes Smartmodem 2400"; the name of the PAD, for example "US Sprint"; or the name of a switch device, for example "Racal-Guardata".

ClientIpAddress is a string that specifies the client's IP address on the connection. This address string has the form a.b.c.d; for example, "11.101.237.71".
This item is set to an empty string if the specified dial-up connection is not connected to the Internet.

ServerIpAddress is a string that specifies 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 item is set to an empty string, "".

dcGetLastErrorCode ( )

Returns an error code presenting the last error that has occured. Possible errors:

1 - RAS dll is missing.
600 - An operation is pending.
602 - The port is already open.
604 - Wrong information specified.
605 - Cannot set port information.
606 - The port is not connected.
608 - The device does not exist.
609 -
The device type does not exist.
615 - The port was not found.
616 - An asynchronous request is pending.
617 - The port or device is already disconnecting.
618 - The port is not open.
619 - The port is disconnected.
621 - Cannot open the phone book file.
622 - Cannot load the phone book file.
623 - Cannot find the phone book entry.
624 - Cannot write the phone book file.
625 - Invalid information found in the phone book file.
628 - The port was disconnected.
629 - The data link was terminated by the remote machine.
630 - The port was disconnected due to hardware failure.
631 - The port was disconnected by the user.
633 - The port is already in use or is not configured for Remote Access dial out.
634 - Cannot register your computer on on the remote network.
635 - Unknown error.
636 - The wrong device is attached to the port.
638 - The request has timed out.
645 - Internal authentication error.
646 - The account is not permitted to logon at this time of day.
647 - The account is disabled.
648 - The password has expired.
664 - Cannot allocate memory.
676 - The line is busy.
677 -
A person answered instead of a modem.
678 - There is no answer.
679 - Cannot detect carrier.
680 - There is no dial tone.
681 - General error reported by device.
691 - Access denied because username and/or password is invalid on the domain.
692 - Hardware failure in port or attached device.
703 - The Application does not allow user interaction.
The connection requires interaction with the user to complete successfully.
715 - Too many errors occurred because of poor phone line quality.
718 - Timed out waiting for a valid response from the remote PPP peer.
719 - PPP terminated by remote machine.
720 - No PPP control protocols configured.
721 - Remote PPP peer is not responding.
723 - The phone number including prefix and suffix is too long.
731 - The protocol is not configured.

dcGetLastErrorMessage ( )

Returns a human-readable string that describes the last error that has occured.
See
dcGetLastErrorCode() method for possible errors.



DirectXtras Inc.
P.O Box 2645, Menlo Park, CA, 94026, U.S.A
Voice: +1-415-5058249, Fax: +1-801-8585841
Toll Free: 1-800-4453093
E-mail General Information: info@directxtras.com
E-mail Technical Support: support@directxtras.com

Copyright © 1996-2004 DirectXtras Inc. All Rights Reserved.
WebMaster: tamar@directxtras.com
Last Updated: 3/5/2003 5:54:17 PM.