NetDial Module

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

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

Property List

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

Method List

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

Event List

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

Config Settings

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

CallbackNumber Property (NetDial Module)

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

Syntax

• Swift
• Objective-C

public var callbackNumber: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=callbackNumber,setter=setCallbackNumber:) NSString* callbackNumber;

- (NSString*)callbackNumber;
- (void)setCallbackNumber :(NSString*)newCallbackNumber;

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

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

Syntax

• Swift
• Objective-C

public var domain: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=domain,setter=setDomain:) NSString* domain;

- (NSString*)domain;
- (void)setDomain :(NSString*)newDomain;

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

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

Syntax

• Swift
• Objective-C

public var entryDeviceName: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=entryDeviceName,setter=setEntryDeviceName:) NSString* entryDeviceName;

- (NSString*)entryDeviceName;
- (void)setEntryDeviceName :(NSString*)newEntryDeviceName;

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

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

Syntax

• Swift
• Objective-C

public var entryDeviceType: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=entryDeviceType,setter=setEntryDeviceType:) NSString* entryDeviceType;

- (NSString*)entryDeviceType;
- (void)setEntryDeviceType :(NSString*)newEntryDeviceType;

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

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

Syntax

• Swift
• Objective-C

public var entryDNSServer: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=entryDNSServer,setter=setEntryDNSServer:) NSString* entryDNSServer;

- (NSString*)entryDNSServer;
- (void)setEntryDNSServer :(NSString*)newEntryDNSServer;

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

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

Syntax

• Swift
• Objective-C

public var entryIPAddress: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=entryIPAddress,setter=setEntryIPAddress:) NSString* entryIPAddress;

- (NSString*)entryIPAddress;
- (void)setEntryIPAddress :(NSString*)newEntryIPAddress;

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

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

Syntax

• Swift
• Objective-C

public var entryPhoneNumber: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=entryPhoneNumber,setter=setEntryPhoneNumber:) NSString* entryPhoneNumber;

- (NSString*)entryPhoneNumber;
- (void)setEntryPhoneNumber :(NSString*)newEntryPhoneNumber;

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

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

Syntax

• Swift
• Objective-C

public var entryWINSServer: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=entryWINSServer,setter=setEntryWINSServer:) NSString* entryWINSServer;

- (NSString*)entryWINSServer;
- (void)setEntryWINSServer :(NSString*)newEntryWINSServer;

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

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

Syntax

• Swift
• Objective-C

public var handle: Int32 {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=handle,setter=setHandle:) int handle;

- (int)handle;
- (void)setHandle :(int)newHandle;

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.

Idle Property (NetDial Module)

The current status of the module.

Syntax

• Swift
• Objective-C

public var idle: Bool {
  get {...}
}

@property (nonatomic,readonly,assign,getter=idle) BOOL idle;

- (BOOL)idle;

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

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

Syntax

• Swift
• Objective-C

public var password: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=password,setter=setPassword:) NSString* password;

- (NSString*)password;
- (void)setPassword :(NSString*)newPassword;

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

This property reads the PhonebookEntry when dialing the remote machine.

Syntax

• Swift
• Objective-C

public var phonebook: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=phonebook,setter=setPhonebook:) NSString* phonebook;

- (NSString*)phonebook;
- (void)setPhonebook :(NSString*)newPhonebook;

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

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

Syntax

• Swift
• Objective-C

public var phonebookEntry: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=phonebookEntry,setter=setPhonebookEntry:) NSString* phonebookEntry;

- (NSString*)phonebookEntry;
- (void)setPhonebookEntry :(NSString*)newPhonebookEntry;

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 class is initialized, it will attempt to populate this property with the system's default entry.

PhoneNumber Property (NetDial Module)

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

Syntax

• Swift
• Objective-C

public var phoneNumber: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=phoneNumber,setter=setPhoneNumber:) NSString* phoneNumber;

- (NSString*)phoneNumber;
- (void)setPhoneNumber :(NSString*)newPhoneNumber;

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

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

Syntax

• Swift
• Objective-C

public var rasAvailable: Bool {
  get {...}
}

@property (nonatomic,readonly,assign,getter=RASAvailable) BOOL RASAvailable;

- (BOOL)RASAvailable;

Default Value

True

Remarks

If this property is False, the class when attempting to connect. RAS must be installed before the class can be used.

This property is read-only.

Timeout Property (NetDial Module)

This property includes a timeout for the module.

Syntax

• Swift
• Objective-C

public var timeout: Int32 {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=timeout,setter=setTimeout:) int timeout;

- (int)timeout;
- (void)setTimeout :(int)newTimeout;

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 class will wait for the operation to complete before returning control.

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

User Property (NetDial Module)

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

Syntax

• Swift
• Objective-C

public var user: String {
  get {...}
  set {...}
}

@property (nonatomic,readwrite,assign,getter=user,setter=setUser:) NSString* user;

- (NSString*)user;
- (void)setUser :(NSString*)newUser;

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

Sets or retrieves a configuration setting.

Syntax

• Swift
• Objective-C

public func config(configurationString: String) throws -> String

- (NSString*)config:(NSString*)configurationString;

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, 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 Module)

This method attempts to dial the PhonebookEntry from Phonebook .

Syntax

• Swift
• Objective-C

public func connect() throws -> Void

- (void)connect;

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 class 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 Module)

This method creates a PhonebookEntry .

Syntax

• Swift
• Objective-C

public func createEntry() throws -> Void

- (void)createEntry;

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

Example. Creating a New Phonebook Entry:

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

DeleteEntry Method (NetDial Module)

This method deletes a PhonebookEntry .

Syntax

• Swift
• Objective-C

public func deleteEntry() throws -> Void

- (void)deleteEntry;

Remarks

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

Disconnect Method (NetDial Module)

This method disconnects the last successfully made connection.

Syntax

• Swift
• Objective-C

public func disconnect() throws -> Void

- (void)disconnect;

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

Processes events from the internal message queue.

Syntax

• Swift
• Objective-C

public func doEvents() throws -> Void

- (void)doEvents;

Remarks

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

Interrupt Method (NetDial Module)

Interrupt the current method.

Syntax

• Swift
• Objective-C

public func interrupt() throws -> Void

- (void)interrupt;

Remarks

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

ListConnections Method (NetDial Module)

This method lists all of the current connections.

Syntax

• Swift
• Objective-C

public func listConnections() throws -> Void

- (void)listConnections;

Remarks

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

ListDevices Method (NetDial Module)

This method lists all of the dial devices.

Syntax

• Swift
• Objective-C

public func listDevices() throws -> Void

- (void)listDevices;

Remarks

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

ListPhonebook Method (NetDial Module)

This method lists all of the entries in Phonebook .

Syntax

• Swift
• Objective-C

public func listPhonebook() throws -> Void

- (void)listPhonebook;

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

Reset the component.

Syntax

• Swift
• Objective-C

public func reset() throws -> Void

- (void)reset;

Remarks

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

ShowDialDialog Method (NetDial Module)

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

Syntax

• Swift
• Objective-C

public func showDialDialog() throws -> Void

- (void)showDialDialog;

Remarks

This method shows the standard RAS dialog for dialing the PhonebookEntry from Phonebook. The class 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 Module)

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

Syntax

• Swift
• Objective-C

func onConnectedEntry(handle: Int32, entry: String, deviceName: String, deviceType: String, statusDescription: String)

- (void)onConnectedEntry:(int)handle :(NSString*)entry :(NSString*)deviceName :(NSString*)deviceType :(NSString*)statusDescription;

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

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

Syntax

• Swift
• Objective-C

func onDevice(deviceName: String, deviceType: String)

- (void)onDevice:(NSString*)deviceName :(NSString*)deviceType;

Remarks

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

Error Event (NetDial Module)

Fired when information is available about errors during data delivery.

Syntax

• Swift
• Objective-C

func onError(errorCode: Int32, description: String)

- (void)onError:(int)errorCode :(NSString*)description;

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the class .

The ErrorCode parameter contains an error code, and the Description parameter 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 Module)

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

Syntax

• Swift
• Objective-C

func onPhonebookEntry(entry: String)

- (void)onPhonebookEntry:(NSString*)entry;

Remarks

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

Status Event (NetDial Module)

This event is fired during connection or disconnection attempts.

Syntax

• Swift
• Objective-C

func onStatus(operation: Int32, statusCode: Int32, operationDescription: String, statusDescription: String)

- (void)onStatus:(int)operation :(int)statusCode :(NSString*)operationDescription :(NSString*)statusDescription;

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

NetDial Config Settings

Base Config Settings

Trappable Errors (NetDial Module)

NetDial Errors