Parasol Framework Manual

Manages user settings for proxy servers.

The proxy server class provides a global management service for a user's proxy servers. You can alter proxy settings manually or present the user with a dialog box to edit and create new proxies. Scanning functions are also provided with filtering, allowing you to scan for proxies that should be used with the user's network connection.

Proxy objects are designed to work similarly to database recordsets. Creating a new proxy object will allow you to create a new proxy record if all required fields are set and the object is saved.

Searching through the records with the Find() and FindNext() methods will move the recordset through each entry the proxy database. You may change existing values of any proxy and then save the changes by calling the SaveSettings() action.

Structure

The Proxy class consists of the following fields:

Access	Name	Type	Comment
	Enabled	INT	All proxies are enabled by default until this field is set to `false`.
To disable a proxy, set this field to `false` or call the Disable() action. This prevents the proxy from being discovered in searches.
	GatewayFilter	STRING	The IP address of the gateway that the proxy is limited to.
The GatewayFilter defines the IP address of the gateway that this proxy is limited to. It is intended to limit the results of searches performed by the Find() method.
	Host	INT	If `true`, the proxy settings are derived from the host operating system's default settings.
If Host is set to `true`, the proxy settings are derived from the host operating system's default settings. Hosted proxies are treated differently to user proxies - they have priority, and any changes are applied directly to the host system rather than the user's configuration.
	NetworkFilter	STRING	The name of the network that the proxy is limited to.
The NetworkFilter defines the name of the network that this proxy is limited to. It is intended to limit the results of searches performed by the Find() method. This filter must not be set if the proxy needs to work on an unnamed network.
	Password	STRING	The password to use when authenticating against the proxy server.
If the proxy requires authentication, the user password may be set here to enable an automated authentication process. If the password is not set, a dialog will need to be used to prompt the user for the password before communicating with the proxy.
	Port	INT	Defines the ports supported by this proxy.
The Port defines the port that the proxy server is supporting, e.g. port 80 for HTTP.
	ProxyName	STRING	A human readable name for the proxy server entry.
A proxy can be given a human readable name by setting this field.
	Record	INT	The unique ID of the current proxy record.
The Record is set to the unique ID of the current proxy record. If no record is indexed then the Record is set to zero. If Record is set manually, the proxy object will attempt to lookup that record. `ERR::Okay` will be returned if the record is found and all record fields will be updated to reflect the data of that proxy.
	Server	STRING	The destination address of the proxy server - may be an IP address or resolvable domain name.
The domain name or IP address of the proxy server must be defined here.
	ServerPort	INT	The port that is used for proxy server communication.
The port used to communicate with the proxy server must be defined here.
	Username	STRING	The username to use when authenticating against the proxy server.
If the proxy requires authentication, the user name may be set here to enable an automated authentication process. If the username is not set, a dialog will be required to prompt the user for the user name before communicating with the proxy server.

Actions

The following actions are currently supported:

	Name	Comment
	Disable	Marks a proxy as disabled.
	`ERR acDisable(*Object)` Calling the Disable() action will mark the proxy as disabled. Disabled proxies remain in the system but are ignored by programs that scan the database for active proxies. The change will not come into effect until the proxy record is saved.
	Enable	Enables a proxy.
	`ERR acEnable(*Object)` Calling the Enable() action will mark the proxy as enabled. The change will not come into effect until the proxy record is saved.
	SaveSettings	Permanently saves user configurable settings for a proxy.
	`ERR acSaveSettings(*Object)` This action saves a user's settings for a proxy. Saving the proxy settings will make them available to the user on subsequent logins. Settings are saved to the user's local account under `user:config/network/proxies.cfg`. It is possible for the administrator to define proxy settings as the default for all users by copying the `proxies.cfg` file to the `system:users/default/config/network/` folder.

Methods

The following methods are currently supported:

Name Comment

DeleteRecord Removes a proxy from the database.

ERR prx::DeleteRecord(OBJECTPTR Object)

Call the DeleteRecord() method to remove a proxy from the system. The proxy will be permanently removed from the proxy database on the success of this function.

Error Codes

Okay	Proxy deleted.

Find Search for a proxy that matches a set of filters.

ERR prx::Find(OBJECTPTR Object, LONG Port, LONG Enabled)

Input	Description
Port	The port number to access. If zero, all proxies will be returned if you perform a looped search.
Enabled	Set to `true` to return only enabled proxies, `false` for disabled proxies or `-1` for all proxies.

The following example searches for all proxies available for use on port 80 (HTTP).

objProxy::create proxy;
if (proxy.ok()) {
   if (prxFind(*proxy, 80) IS ERR::Okay) {
      do {
         ...
      } while (prxFindNext(*proxy) IS ERR::Okay);
   }
}

Error Codes

Okay	A proxy was discovered.
NoSearchResult	No matching proxy was discovered.

FindNext Continues an initiated search.

ERR prx::FindNext(OBJECTPTR Object)

This method continues searches that have been initiated by the Find() method. If a proxy is found that matches the filter, ERR::Okay is returned and the details of the proxy object will reflect the data of the discovered record. ERR::NoSearchResult is returned if there are no more matching proxies.

Error Codes

Okay	A proxy was discovered.
NoSearchResult	No matching proxy was discovered.

Class Info
ID	ID_PROXY
Category	Network
Include	modules/proxy.h
Version	1

Proxy Class

Structure

Actions

Methods

Error Codes

Error Codes

Error Codes

Class Info

Class List