NetTalk Document Four - NetDUN (Dial-Up Networking) Object

The NetDUN object gives you the functionality to use and manage dial-up connections. It also allows your application to know when a new dial-up connection has been established, if it was not done through your application. This allows your application to leap into life and use the connection when it is opened. For example you may want to send email when an internet connection becomes available.

You can use the NetDUN object in two ways in your code:

By using the Dial-Up Control Template (see the Dial-Up JUMP START for instructions)
By using the NetDUN object directly. (see both the Dial-Up JUMP START for instructions, as well as the properties, methods & data structures sections)

Important things to know about using NetDUN

1) It's best to have a Dial-up Networking Entry before you can dial. (If you are using the Dial-Up Control Template, you can create a DUN entry by pressing the New button).

"I want to be able to dial a dial-up connection"

This section exists to get you going quickly. You'll need to read the rest of the documentation to access all the other features and functionality of the NetDUN, but if you follow the following instructions you can add the ability to send emails from your application in 10-30 minutes.

Objectives of this Jump Start for Dial-Up Networking:

add the controls and code to allow a user to choose a dial-up entry and dial. (We'll use the Dial-Up Control Template for this).
add the ability to detect when a connection is made and in this case get a web file when this happens.

Example

There is an example of this in the \Clarion\Examples\NetTalk\DialUp Jump Start folder on your drive.

Instructions:

Add the "Activate_NetTalk" Global Extension to your application. Also make sure your application will be compiled in 32-bit mode. (See scenario one for instructions).
Create a window and add the DialUpControls Control Template (In the window editor go to the Populate Menu and choose Control Template). This will add the controls and code necessary for using NetDUN.
Important: Go to the properties of the window (right-click on the title of the window) and change the Timer Property (on the Extra Tab) to 50.

Notes about the control template:
a) It uses a timer of 50 (50/100 sec). If your application uses a timer you will need to adapt your application to a timer rate of 50.
b) If you fail to do step 3, you will not be able to HangUp your connection via the application.
Compile and run your application, to test this. (If you only wanted to use the Control Template then you can stop here).
We are now going to add the code to do something when a connection is established. This code will work when either your application opens a connection or if another application does.

Add the NetTalk procedure extension "IncludeNetTalkObject" to the window in your application that you want to access a Web page from . Set the ObjectName to ThisWebClient, the Base Class to NetWebClient
6) In the code section of the ThisWebClient.ErrorTrap insert the following code:

MyText = 'Could not download website'
display()
setcursor ! Return mouse back to normal.
          ! If an error occurs, the NetWebClient will
          ! display a message, unless you suppress
          ! error messages in the procedure extension
          ! template, in which case you would need to
          ! handle your own error messages.
This code is there to tell the user we could not download the web page. The ThisWebClient is called when something goes wrong when downloading the web page.
In the code section of the ThisWebClient.PageReceived insert the following code:

! This is the code that is called when the page has been downloaded.
! In this case we display it on the screen by putting it in the MyText
! variable.
if ThisWebClient.PageLen <= 0
MyText = ''
elsif ThisWebClient.PageLen < 30000
MyText = ThisWebClient.Page [1 : ThisWebClient.PageLen]
else
MyText = '<<page clipped because it was big><13,10,13,10>' & |
ThisWebClient.Page [ThisWebClient.PageLen - 28000 : ThisWebClient.PageLen]
end
display()
if LastDialedHandle ! If we opened this connection
post (event:accepted,?HangUp) ! Simulate the pressing of the HangUp button
end
setcursor

This is the code that is called when the whole web page has been received. It displays the page's HTML code on the screen. If our application started the Dial-Up connection this code also Hangs Up the connection. If the connection was started by another process then this application leaves the connection open.
In the data section of the ThisDialUp.ConnectionsChanged insert the following code:

lastAliveConnections long, static

This variable stores the last value of the p_AliveConnections that is used below.
In the code section of the ThisDialUp.ConnectionsChanged insert the following code:

if (p_AliveConnections > 0) and (lastAliveConnections <> p_AliveConnections)
! Check that there is a connection

! ---------------------------------------
! Code to Check if this is our connection
clear (self.ConnectionsQ)
self.ConnectionsQ.Handle = LastDialedHandle
get (self.ConnectionsQ, self.ConnectionsQ.Handle)
if errorcode() = 0
    if self.ConnectionsQ.State = 8192
      ! Our connection which we opened has complete
      ! You can put code in here if you want
      MyText = 'Our Dial-Up Connection is established.' &|
               ' Attempting to get web page...'
    end
else
    MyText = 'Another Dial-Up Connection is established.' & |
             ' Attempting to get web page...'
end
display()
! ---------------------------------------

! --------------------------
! Start Go and get a web page now
! --------------------------
setcursor (CURSOR:Wait)

! You start by telling the object what to download.
! You can choose to either download the whole page or just
! the web page header.
ThisWebClient.SetAllHeadersDefault()
! We recommend you call this before Fetch()

! You may want to modify some properties after this.
ThisWebClient.CanUseProxy = 1 ! Can use a proxy
ThisWebClient.HeaderOnly = 0 ! We want the whole page
ThisWebClient.Fetch('www.capesoft.com')
if ThisWebClient.Error
    MyText = 'Could not download website'
    display()
    setcursor
    Message ('This WebSite could not be downloaded. Error ' & |
             ThisWebClient.Error & |
             ' = ' & ThisWebClient.InterpretError())
end
! This tells the object to fetch the www.capesoft.com index page.
! The Fetch() method is asynchronous this means it runs in the
! background and wont have finished when the function returns.
! We only know when it's finished when the PageReceived()
! method is called.
! --------------------------
! End Go and get a web page now
! --------------------------
end
lastAliveConnections = p_AliveConnections ! Store last value

This is the code that first of works out if a new connection is now open, and if so it tells the Web Client object to download the www.capesoft.com web page.
Add a textbox to your screen using a local Data variable called MyText of string (30000)
Compile your application and try it out.

NetDUNConnectionsQType Queue, Type

EntryNameString(NetDUN_MaxEntryName)	This is the name of the Dial-up Entry
StateStr	This is the string description of the State ulong property.
ErrorStr string(50)	This is the string description of the Error ulong property
IP string(32)	The IP address assigned to this connection
ServerIP string(32)	The IP address of the server (i.e. the machine that you dialed into)
Name string(NetDUN_MaxDeviceName)	Device Name
Type string(NetDUN_MaxDeviceType)	Device Type
Handle Ulong	Connection handle (windows handle)
State Ulong	The state of the connection. If connected this is set to 8192
Error Ulong	The error value. 0 = no error.
Size Ulong	Size of structure.

NetDUNDunEntiresQType Queue, Type

EntryName String(NetDUN_MaxEntryName)	This is the name of the Dial-up Entry
PhoneNumber String(256)	The phone number that will be dialed. You need to specify this number before dialing the connection.
CountryCode uLong	This is the country code of the phone number.
AreaCode string(10)	This is the area code of the phone number.
LocalPhoneNumber string(128)	This is the local number of the phone number.
UserName string(NetDUN_UNLEN)	UserName for login. (Note you may need to provide this before dialing).
Password string(NetDUN_PWLEN)	Password for login. (Note you may need to provide this before dialing, specially in Win2K).
Domain string(NetDUN_DNLEN)	Domain for login (blank if unused). (Note you may need to provide this before dialing).
Size Ulong	Size of structure.

NetDUNDevicesQType Queue, Type

DeviceType String(NetDUN_MaxDeviceType)	This is the Type of the Device.
DeviceName String(NetDUN_MaxDeviceName)	This is the Name of the Device.

The bulk of the NetDUN properties are queues. If you look in the examples you can see how to display these queues directly on the screen, otherwise you can process their information directly in your application.

ConnectionsQ &NetDUNConnectionsQType	This queue holds all the information for the current connections. Look at the NetDUN Data Structures for a description of the NetDUNConnectionsQType.
ControlTemplateINIFile String(255)	This property is only used in the Control template. It stores the INI file that will be used to store the Outside line. It defaults to '\.netdemo.ini'. You can change this in your object's Init() method after the parent call.
DevicesQ &NetDUNDevicesQType	This queue holds the information about the various Dial-up devices on the machine. This is normally a list of the modem drivers that have been installed. Look at the NetDUN Data Structures for a description of the NetDUNDevicesQType.
DunEntriesQ &NetDUNDunEntriesQType	This queue holds all the information about the Dial-up connections. These are the entries in what used to be known as the Phone Book. This is the same list that Windows Explorer shows in the "Dial-Up Networking" special folder. Look at the NetDUN Data Structures for a description of the NetDUNDunEntriesQType.
Error Long	Contains the error value of the last transaction. 0 = no error. You can use the InterpretError() method for converting the error code into an error string.
ErrorString String(255)	Contains the last error string that was reported. It only changes the next time an error occurs.
SuppressErrorMsg Byte	Set this to 1 to disable error messages, otherwise leave it as 0.
UseThisThread long	(Advanced Optional Property). This property allows you to manually specify which thread must receive the messages that the NetTalk DLL posts to the NetTalk objects. Set this property before calling the Init() method. Defaults to 0 (no action).

This section exists to get you going quickly. You'll need to read the rest of the documentation to access all the other features and functionality of the NetDUN, but if you follow the following instructions you can add the ability to control the dial-up options from your application in 10-30 minutes.

ConnectionsChanged(long p_AliveConnections)) (Notification Method)	This method is called when a new dial-up connection is established. p_AliveConnections is the number of connections that are "alive" i.e. established. This number may be different to records (self.ConnectionsQ) as there may be some connections that are not yet connected as well as some connections that are in a disconnecting state. Warning, this function is called a good number of times. Basically whenever some state changes with the connection this method is called.
Dial(), ulong	Call this method to dial the currently loaded record in the self.DunEntries queue. (This means you need to do a get (self.DunEntriesQ, x) where x is the index of the DUN entry that you want to dial. Important: Having chosen a Dial-Up Networking Entry (and have loaded it in self.DunEntriesQ) you need to specify the following fields in self.DunEntriesQ: self.DunEntriesQ.PhoneNumber and in some cases (specially if you are using Win2K) you will need to specify: self.DunEntriesQ.UserName self.DunEntriesQ.Password self.DunEntriesQ.Domain (if used).
DeleteDunEntry()	Call this method to delete a DUN entry in windows. This deletes the currently loaded record in the self.DunEntries queue. (This means you need to do a get (self.DunEntriesQ, x) where x is the index of the DUN entry that you want to dial.
EditDunEntry()	Call this method to edit a DUN entry in windows. This method loads the Windows Dialup Window. This edits the currently loaded record in the self.DunEntries queue. (This means you need to do a get (self.DunEntriesQ, x) where x is the index of the DUN entry that you want to dial.
ErrorTrap (string p_errorStr, string p_functionName)	This function is called when an error occurs.
GetConnections()	Call this method to get the list of current connections. The connections are placed in self.connectionQ
GetDunEntries()	Call this method to get a list of the Dial-up entries. They are returned in self.DunEntriesQ
GetDevices()	Call this method to get a list of the Devices. They are returned in self.DevicesQ.
HangUp()	Call this function to hangup the connection currently loaded in the self.ConnectionsQ. This means you need to do a get (self.ConnectionsQ, x) where x is the index of the connection queue record that you want to hangup.
Init()	Initialises the object. This is done for you by the template.
InterpretError(),string	Returns the a description of the self.error error code.
Kill()	Kills the object. This is done for you by the NetTalk template.
NewDunEntry()	Call this method to create a new DUN entry in windows. This method loads the Windows Dialup Window.
Prime()	Internal method.
RenameDunEntry (string p_NewName)	Call this method to rename a DUN entry in windows. This renames the currently loaded record in the self.DunEntries queue. (This means you need to do a get (self.DunEntriesQ, x) where x is the index of the DUN entry that you want to dial. You need to specify the new name in the method parameters.
TakeEvent()	Internal Method

Using the NetDUN Object

Introduction

Jump Start

Instructions:

NetDUN Structures

NetDUN Properties

NetDUN Methods

NetDUN Class (Dial-Up Networking)

	Version beta www.capesoft.com Updated 07 June 2011