NetDial Component

Properties   Methods   Events   Config Settings   Errors  

The NetDial component can be used to call the Remote Access System (RAS) to initiate or break connections to remote hosts, list connections, and phonebook entries.

Syntax

nsoftware.IPWorks.Netdial

Remarks

The user can either directly provide a PhoneNumber, User, and Password, and optionally a Domain and CallbackNumber, or can get those entries from PhonebookEntry of Phonebook. The calls are blocking but progress information is given through the Status event, and Windows messages will come during connect or disconnect methods.

The user can get information on the phonebook entries and connections by calling the respective methods of the component. ConnectedEntry and PhonebookEntry events will fire with the required information.

Support is also provided for creating or deleting phonebook entries as well as for listing the various RAS devices supported by the system.

This component is not available in Mono.

Property List

The following is the full list of the properties of the component with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the component with short descriptions. Click on the links for further details.

CallbackNumber Property (NetDial Component)

This property includes the callback number to give when directly dialing the remote machine.

Syntax

• C#
• VB.NET

public string CallbackNumber { get; set; }

Public Property CallbackNumber As String

Default Value

""

Remarks

This property contains the callback number to give when directly dialing the remote machine. User, PhoneNumber, and Password, and optionally Domain and CallbackNumber, are used when PhonebookEntry is empty.

Calling the Connect method attempts a connection.

Domain Property (NetDial Component)

This property includes the name of the domain to join when dialing the Remote Access System (RAS) connection.

Syntax

• C#
• VB.NET

public string Domain { get; set; }

Public Property Domain As String

Default Value

""

Remarks

This property contains the name of the domain to join when dialing the RAS connection. User, PhoneNumber, and Password, and optionally Domain and CallbackNumber, are used when PhonebookEntry is empty.

Calling the Connect method attempts a connection.

EntryDeviceName Property (NetDial Component)

This property includes the device of the phonebook entry pointed to by PhonebookEntry .

Syntax

• C#
• VB.NET

public string EntryDeviceName { get; set; }

Public Property EntryDeviceName As String

Default Value

""

Remarks

This property contains the device of the phonebook entry pointed to by PhonebookEntry. This property is filled in automatically every time PhonebookEntry is set to an existing entry.

EntryDeviceType Property (NetDial Component)

This property includes the device type of the phonebook entry pointed to by PhonebookEntry .

Syntax

• C#
• VB.NET

public string EntryDeviceType { get; set; }

Public Property EntryDeviceType As String

Default Value

""

Remarks

This property contains the device type of the phonebook entry pointed to by PhonebookEntry. This property is filled in automatically every time PhonebookEntry is set to an existing entry.

EntryDNSServer Property (NetDial Component)

This property includes the DNS server of the phonebook entry pointed to by PhonebookEntry .

Syntax

• C#
• VB.NET

public string EntryDNSServer { get; set; }

Public Property EntryDNSServer As String

Default Value

""

Remarks

This property contains the DNS server of the phonebook entry pointed to by PhonebookEntry. This property is filled in automatically every time PhonebookEntry is set to an existing entry.

EntryIPAddress Property (NetDial Component)

This property includes the IP address of the phonebook entry pointed to by PhonebookEntry .

Syntax

• C#
• VB.NET

public string EntryIPAddress { get; set; }

Public Property EntryIPAddress As String

Default Value

""

Remarks

This property contains the IP address of the phonebook entry pointed to by PhonebookEntry. This property is filled in automatically every time PhonebookEntry is set to an existing entry.

EntryPhoneNumber Property (NetDial Component)

This property includes the phone number for the phonebook entry pointed to by PhonebookEntry .

Syntax

• C#
• VB.NET

public string EntryPhoneNumber { get; set; }

Public Property EntryPhoneNumber As String

Default Value

""

Remarks

This property contains the phone number for the phonebook entry pointed to by PhonebookEntry. This property is filled in automatically every time PhonebookEntry is set to an existing entry.

EntryWINSServer Property (NetDial Component)

This property includes the WINS server of the phonebook entry pointed to by PhonebookEntry .

Syntax

• C#
• VB.NET

public string EntryWINSServer { get; set; }

Public Property EntryWINSServer As String

Default Value

""

Remarks

This property contains the WINS server of the phonebook entry pointed to by PhonebookEntry. This property is filled in automatically every time PhonebookEntry is set to an existing entry.

Handle Property (NetDial Component)

This property includes the handle of the connection. It is 0 if it is invalid or not connected.

Syntax

• C#
• VB.NET

public object Handle { get; set; }

Public Property Handle As Object

Default Value

0

Remarks

This property is used when trying to disconnect a connection through the Disconnect method. The ConnectedEntry event provides the handle of each connection. Assigning an invalid value to this property and attempting to disconnect may cause the application to behave in an unpredictable manner.

This property is not available at design time.

Idle Property (NetDial Component)

The current status of the component.

Syntax

• C#
• VB.NET

public bool Idle { get; }

Public ReadOnly Property Idle As Boolean

Default Value

True

Remarks

Idle will be False if the component is currently busy (communicating and/or waiting for an answer), and True at all other times.

This property is read-only.

Password Property (NetDial Component)

This property includes the password to use when direct dialing the remote machine.

Syntax

• C#
• VB.NET

public string Password { get; set; }

Public Property Password As String

Default Value

""

Remarks

This property contains the password to use when direct dialing the remote machine. User, PhoneNumber, and Password, and optionally Domain and CallbackNumber, are used when PhonebookEntry is empty.

Calling the Connect method attempts a connection.

Phonebook Property (NetDial Component)

This property reads the PhonebookEntry when dialing the remote machine.

Syntax

• C#
• VB.NET

public string Phonebook { get; set; }

Public Property Phonebook As String

Default Value

""

Remarks

This property reads the PhonebookEntry when dialing the remote machine. This property is valuable only in Windows NT 4.0 and higher in cases in which multiple phonebooks can be specified. The PhonebookEntry is relative to Phonebook. If it is empty, the default phonebook is used.

PhonebookEntry Property (NetDial Component)

This property includes the name of PhonebookEntry to use when dialing the remote machine.

Syntax

• C#
• VB.NET

public string PhonebookEntry { get; set; }

Public Property PhonebookEntry As String

Default Value

""

Remarks

This property is read from the default phonebook (in Windows 95) or from the Phonebook property.

Note: This property must not be empty when dialing on Pocket PC (Windows CE).

When the component is initialized, it will attempt to populate this property with the system's default entry.

PhoneNumber Property (NetDial Component)

This property includes the number to dial when directly dialing the remote machine without the help of a PhonebookEntry .

Syntax

• C#
• VB.NET

public string PhoneNumber { get; set; }

Public Property PhoneNumber As String

Default Value

""

Remarks

This property contains the number to dial when directly dialing the remote machine without the help of a PhonebookEntry. User, PhoneNumber, and Password, and optionally Domain and CallbackNumber, are used when PhonebookEntry is empty.

Calling the Connect method attempts a connection.

RASAvailable Property (NetDial Component)

When set to True, the Remote Access System (RAS) is available.

Syntax

• C#
• VB.NET

public bool RASAvailable { get; }

Public ReadOnly Property RASAvailable As Boolean

Default Value

True

Remarks

If this property is False, the component throws an exception when attempting to connect. RAS must be installed before the component can be used.

This property is read-only.

Timeout Property (NetDial Component)

This property includes a timeout for the component.

Syntax

• C#
• VB.NET

public int Timeout { get; set; }

Public Property Timeout As Integer

Default Value

60

Remarks

If this property is set to 0, all operations will run uninterrupted until successful completion or an error condition is encountered.

If this property is set to a positive value, the component will wait for the operation to complete before returning control.

The default value for this property is 60 (seconds).

User Property (NetDial Component)

This property includes the name of the login user when directly dialing the remote machine.

Syntax

• C#
• VB.NET

public string User { get; set; }

Public Property User As String

Default Value

""

Remarks

This property contains the name of the login user when directly dialing the remote machine. User, PhoneNumber, and Password, and optionally Domain and CallbackNumber, are used when PhonebookEntry is empty.

Calling the Connect method attempts a connection.

Config Method (NetDial Component)

Sets or retrieves a configuration setting.

Syntax

• C#
• VB.NET

public string Config(string configurationString);

Async Version
public async Task<string> Config(string configurationString);
public async Task<string> Config(string configurationString, CancellationToken cancellationToken);

Public Function Config(ByVal ConfigurationString As String) As String

Async Version
Public Function Config(ByVal ConfigurationString As String) As Task(Of String)
Public Function Config(ByVal ConfigurationString As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

Connect Method (NetDial Component)

This method attempts to dial the PhonebookEntry from Phonebook .

Syntax

• C#
• VB.NET

public void Connect();

Async Version
public async Task Connect();
public async Task Connect(CancellationToken cancellationToken);

Public Sub Connect()

Async Version
Public Sub Connect() As Task
Public Sub Connect(cancellationToken As CancellationToken) As Task

Remarks

This method attempts to dial the PhonebookEntry from Phonebook. If it is empty, then the PhoneNumber, CallbackNumber, and Domain (if applicable) are used to connect. The component does not return until the operation is completed, but during this time, Status events are fired showing the ongoing progress.

Example 1. Dialing a Phonebook:

NetDialControl.Phonebook = "MyPhonebook" NetDialControl.Connect()

Example 2. Direct Dialing a Phone Number:

NetDialControl.PhoneNumber = "MyPhonebook" NetDialControl.User = "username" NetDialControl.Password = "mypassword" NetDialControl.Connect()

Note: Direct dialing is not supported on Pocket PC (Windows CE).

CreateEntry Method (NetDial Component)

This method creates a PhonebookEntry .

Syntax

• C#
• VB.NET

public void CreateEntry();

Async Version
public async Task CreateEntry();
public async Task CreateEntry(CancellationToken cancellationToken);

Public Sub CreateEntry()

Async Version
Public Sub CreateEntry() As Task
Public Sub CreateEntry(cancellationToken As CancellationToken) As Task

Remarks

This method creates a new phonebook entry PhonebookEntry with the values in EntryPhoneNumber, EntryDNSServer, EntryWINSServer, EntryIPAddress, and EntryDeviceName. If the entry already exists or the entry cannot be created, the component throws an exception.

Example. Creating a New Phonebook Entry:

NetDialControl.PhonebookEntry = "NewEntry" NetDialControl.EntryPhoneNumber = "5555555" NetDialControl.CreateEntry()

DeleteEntry Method (NetDial Component)

This method deletes a PhonebookEntry .

Syntax

• C#
• VB.NET

public void DeleteEntry();

Async Version
public async Task DeleteEntry();
public async Task DeleteEntry(CancellationToken cancellationToken);

Public Sub DeleteEntry()

Async Version
Public Sub DeleteEntry() As Task
Public Sub DeleteEntry(cancellationToken As CancellationToken) As Task

Remarks

This method deletes the phonebook entry specified by PhonebookEntry and Phonebook.

Disconnect Method (NetDial Component)

This method disconnects the last successfully made connection.

Syntax

• C#
• VB.NET

public void Disconnect();

Async Version
public async Task Disconnect();
public async Task Disconnect(CancellationToken cancellationToken);

Public Sub Disconnect()

Async Version
Public Sub Disconnect() As Task
Public Sub Disconnect(cancellationToken As CancellationToken) As Task

Remarks

This method disconnects the last successfully made connection or the current one if the call is made within a ConnectedEntry event.

DoEvents Method (NetDial Component)

Processes events from the internal message queue.

Syntax

• C#
• VB.NET

public void DoEvents();

Async Version
public async Task DoEvents();
public async Task DoEvents(CancellationToken cancellationToken);

Public Sub DoEvents()

Async Version
Public Sub DoEvents() As Task
Public Sub DoEvents(cancellationToken As CancellationToken) As Task

Remarks

When DoEvents is called, the component processes any available events. If no events are available, it waits for a preset period of time, and then returns.

Interrupt Method (NetDial Component)

Interrupt the current method.

Syntax

• C#
• VB.NET

public void Interrupt();

Async Version
public async Task Interrupt();
public async Task Interrupt(CancellationToken cancellationToken);

Public Sub Interrupt()

Async Version
Public Sub Interrupt() As Task
Public Sub Interrupt(cancellationToken As CancellationToken) As Task

Remarks

If there is no method in progress, Interrupt simply returns, doing nothing.

ListConnections Method (NetDial Component)

This method lists all of the current connections.

Syntax

• C#
• VB.NET

public void ListConnections();

Async Version
public async Task ListConnections();
public async Task ListConnections(CancellationToken cancellationToken);

Public Sub ListConnections()

Async Version
Public Sub ListConnections() As Task
Public Sub ListConnections(cancellationToken As CancellationToken) As Task

Remarks

This method lists all of the connections in all devices and gives the results in ConnectedEntry events.

ListDevices Method (NetDial Component)

This method lists all of the dial devices.

Syntax

• C#
• VB.NET

public void ListDevices();

Async Version
public async Task ListDevices();
public async Task ListDevices(CancellationToken cancellationToken);

Public Sub ListDevices()

Async Version
Public Sub ListDevices() As Task
Public Sub ListDevices(cancellationToken As CancellationToken) As Task

Remarks

This method lists all of the dial devices. The results are provided through the Device event.

ListPhonebook Method (NetDial Component)

This method lists all of the entries in Phonebook .

Syntax

• C#
• VB.NET

public void ListPhonebook();

Async Version
public async Task ListPhonebook();
public async Task ListPhonebook(CancellationToken cancellationToken);

Public Sub ListPhonebook()

Async Version
Public Sub ListPhonebook() As Task
Public Sub ListPhonebook(cancellationToken As CancellationToken) As Task

Remarks

This method lists all of the entries in Phonebook (Windows 95 has only one default Phonebook). Entries are given in PhonebookEntry events.

Reset Method (NetDial Component)

Reset the component.

Syntax

• C#
• VB.NET

public void Reset();

Async Version
public async Task Reset();
public async Task Reset(CancellationToken cancellationToken);

Public Sub Reset()

Async Version
Public Sub Reset() As Task
Public Sub Reset(cancellationToken As CancellationToken) As Task

Remarks

This method will reset the component's properties to their default values.

ShowDialDialog Method (NetDial Component)

This method shows the standard Remote Access System (RAS) dialog for dialing the PhonebookEntry from Phonebook .

Syntax

• C#
• VB.NET

public void ShowDialDialog();

Async Version
public async Task ShowDialDialog();
public async Task ShowDialDialog(CancellationToken cancellationToken);

Public Sub ShowDialDialog()

Async Version
Public Sub ShowDialDialog() As Task
Public Sub ShowDialDialog(cancellationToken As CancellationToken) As Task

Remarks

This method shows the standard RAS dialog for dialing the PhonebookEntry from Phonebook. The component will display the standard RAS dialog box for PhonebookEntry and allow the dial to take place with user interaction. If you prefer the dial to occur without user interaction, use the Connect method.

ConnectedEntry Event (NetDial Component)

This event is fired for every connected device when the ListConnections method is called.

Syntax

• C#
• VB.NET

public event OnConnectedEntryHandler OnConnectedEntry;

public delegate void OnConnectedEntryHandler(object sender, NetdialConnectedEntryEventArgs e);

public class NetdialConnectedEntryEventArgs : EventArgs {
  public object Handle { get; }
  public string Entry { get; }
  public string DeviceName { get; }
  public string DeviceType { get; }
  public string StatusDescription { get; }
}

Public Event OnConnectedEntry As OnConnectedEntryHandler

Public Delegate Sub OnConnectedEntryHandler(sender As Object, e As NetdialConnectedEntryEventArgs)

Public Class NetdialConnectedEntryEventArgs Inherits EventArgs
  Public ReadOnly Property Handle As Object
  Public ReadOnly Property Entry As String
  Public ReadOnly Property DeviceName As String
  Public ReadOnly Property DeviceType As String
  Public ReadOnly Property StatusDescription As String
End Class

Remarks

The Handle parameter can be used to disconnect the entry. You should assign Handle to the Handle property and then call the Disconnect method.

Device Event (NetDial Component)

This event is fired for every dial device when the ListDevices method is called.

Syntax

• C#
• VB.NET

public event OnDeviceHandler OnDevice;

public delegate void OnDeviceHandler(object sender, NetdialDeviceEventArgs e);

public class NetdialDeviceEventArgs : EventArgs {
  public string DeviceName { get; }
  public string DeviceType { get; }
}

Public Event OnDevice As OnDeviceHandler

Public Delegate Sub OnDeviceHandler(sender As Object, e As NetdialDeviceEventArgs)

Public Class NetdialDeviceEventArgs Inherits EventArgs
  Public ReadOnly Property DeviceName As String
  Public ReadOnly Property DeviceType As String
End Class

Remarks

DeviceName provides the name of the device, and DeviceType provides the corresponding device type (e.g., 'modem').

Error Event (NetDial Component)

Information about errors during data delivery.

Syntax

• C#
• VB.NET

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, NetdialErrorEventArgs e);

public class NetdialErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}

Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As NetdialErrorEventArgs)

Public Class NetdialErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the component throws an exception.

ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

PhonebookEntry Event (NetDial Component)

This event is fired for every Phonebook entry when the ListPhonebook method is called.

Syntax

• C#
• VB.NET

public event OnPhonebookEntryHandler OnPhonebookEntry;

public delegate void OnPhonebookEntryHandler(object sender, NetdialPhonebookEntryEventArgs e);

public class NetdialPhonebookEntryEventArgs : EventArgs {
  public string Entry { get; }
}

Public Event OnPhonebookEntry As OnPhonebookEntryHandler

Public Delegate Sub OnPhonebookEntryHandler(sender As Object, e As NetdialPhonebookEntryEventArgs)

Public Class NetdialPhonebookEntryEventArgs Inherits EventArgs
  Public ReadOnly Property Entry As String
End Class

Remarks

To get extended entry information, set the PhonebookEntry property to the value supplied in the Entry parameter.

Status Event (NetDial Component)

This event is fired during connection or disconnection attempts.

Syntax

• C#
• VB.NET

public event OnStatusHandler OnStatus;

public delegate void OnStatusHandler(object sender, NetdialStatusEventArgs e);

public class NetdialStatusEventArgs : EventArgs {
  public int Operation { get; }
  public int StatusCode { get; }
  public string OperationDescription { get; }
  public string StatusDescription { get; }
}

Public Event OnStatus As OnStatusHandler

Public Delegate Sub OnStatusHandler(sender As Object, e As NetdialStatusEventArgs)

Public Class NetdialStatusEventArgs Inherits EventArgs
  Public ReadOnly Property Operation As Integer
  Public ReadOnly Property StatusCode As Integer
  Public ReadOnly Property OperationDescription As String
  Public ReadOnly Property StatusDescription As String
End Class

Remarks

The Operation parameter indicates the operation currently in progress.

The StatusCode shows the status of the operation.

The OperationDescription and StatusDescription parameters are the corresponding descriptions.

Config Settings (NetDial Component)

NetDial Config Settings

Base Config Settings

Trappable Errors (NetDial Component)

NetDial Errors