API Documentation

Documentation for developing SailfishOS applications

NetProxy Class

(Sailfish::Mdm::NetProxy)

The NetProxy class controls the network proxy servers in use. More...

Header: #include <mdm-netproxy.h>

Public Types

enum ActiveType { Service, Global }
enum ProxyType { Invalid, Direct, Manual, Automatic }

Properties

Public Functions

NetProxy(QObject *parent = nullptr)
virtual ~NetProxy()
ActiveType activeType() const
QUrl automaticUrl() const
QString getIdentifier() const
QStringList getIdentifiers(const QString &technology) const
QString getName() const
QStringList getTechnologies() const
bool isValid() const
QStringList manualExclusions() const
QList<QUrl> manualProxies() const
bool selectProxy(const QString &identifier)
bool setActiveType(ActiveType type)
bool setAutomaticUrl(const QUrl &url)
bool setManualExclusions(const QStringList &exclusions)
bool setManualProxies(const QList<QUrl> &proxies)
bool setType(ProxyType type)
ProxyType type() const

Signals

void activeTypeChanged(ActiveType type)
void automaticUrlChanged(const QUrl &url)
void manualExclusionsChanged(const QStringList &exclusions)
void manualProxiesChanged(const QList<QUrl> &proxies)
void proxyConfigChanged()
void typeChanged(ProxyType type)
void validChanged(bool valid)

Detailed Description

The NetProxy class controls the network proxy servers in use.

A proxy can be either direct (no proxy), manual (use the specified proxy servers) or auto (determine the proxy by reference to a PAC file).

The type of proxy is determined by the protocol. For example, for a manual mode proxy, specifying a proxy with an http prefix will identify it as a web proxy.

Proxies can be applied either for specific services or globally. If the global proxy is active it will override the proxies set for specific services (including deactivating them if this is with the global proxy stipulates).

 CONFIG += link_pkgconfig
 PKGCONFIG += sailfishmdm

and then #include <mdm-netproxy.h>.

Example of usage:

 #include <mdm-netproxy.h>
 void setGlobalProxy(const QUrl &server)
 {
     auto proxy = new Sailfish::Mdm::NetProxy(nullptr);

     QObject::connect(proxy, &Sailfish::Mdm::NetProxy::validChanged, [proxy, server] {
         QString identifier = "global";
         bool found = proxy->selectProxy(identifier);

         if (found) {
             proxy->setType(Sailfish::Mdm::NetProxy::ProxyType::Manual);
             proxy->setManualProxies(QList<QUrl>({server}));
             proxy->setManualExclusions(QStringList());
         }
     });
 }

This example assumes you have an application loop running, so that you can receive the signal. For example using something along the following lines.

 #include <QCoreApplication>
 #include <QTimer>
 #include <mdm-netproxy.h>

 int main(int argc, char *argv[])
 {
     QCoreApplication app(argc, argv);

     // Set the global proxy
     setGlobalProxy(QUrl("https://jolla.com"));

     // Wait for a bit and then quit
     QTimer::singleShot(5000, [&app] {
         app.quit();
     });

     return app.exec();
 }

Member Type Documentation

enum NetProxy::ActiveType

Specifies whether individual service proxies or the global proxy is in operation.

It's either one or the other: it can't be a mixture. For more fine-grained control, individual service proxies should be used, or a global PAC file.

ConstantValueDescription
Sailfish::Mdm::NetProxy::Service0The individual service proxies are in operation.
Sailfish::Mdm::NetProxy::Global1The global proxy is in operation.

See also activeType, setActiveType(), activeType(), and activeTypeChanged().

enum NetProxy::ProxyType

The type of the current configuration, used to determine how to choose a proxy.

ConstantValueDescription
Sailfish::Mdm::NetProxy::Invalid0No valid proxy type set.
Sailfish::Mdm::NetProxy::Direct1Pass the request on directly and don't use any proxy.
Sailfish::Mdm::NetProxy::Manual2Select a proxy from the list of configured proxies.
Sailfish::Mdm::NetProxy::Automatic3Use a PAC file to determine the proxy to use.

See also type, setType(), type(), and typeChanged().

Property Documentation

activeType : ActiveType

This property holds the currently active proxy set: either the service proxies or the global proxy.

Usually individal services have their own service settings. The global proxy can be used to override all of these individual settings. The activeType property determines which of these is the case.

Access functions:

ActiveType activeType() const
bool setActiveType(ActiveType type)

Notifier signal:

void activeTypeChanged(ActiveType type)

See also ActiveType, setActiveType(), and activeTypeChanged().

automaticUrl : QUrl

This property holds the URL of the PAC file to use for the currently selected service.

This configuration option only applies to the automatic proxy type.

In the case of an automatic proxy, the proxy is determined by a PAC file, which contains a javascript routine for selecting an appropriate proxy, based on the detalis of the request being made. This configuration option specifies the location of the PAC file to use.

Access functions:

QUrl automaticUrl() const
bool setAutomaticUrl(const QUrl &url)

Notifier signal:

void automaticUrlChanged(const QUrl &url)

See also automaticUrl, setAutomaticUrl(), and automaticUrlChanged().

manualExclusions : QStringList

This property holds the domain exclusions for the currently selected service.

This configuration option only applies to the manual proxy type.

In the case of a manual proxy, a proxy is chosen from a list of configured proxies. However, if the request is being made to one of the excluded domains, then a direct request will be made instead.

Access functions:

QStringList manualExclusions() const
bool setManualExclusions(const QStringList &exclusions)

Notifier signal:

void manualExclusionsChanged(const QStringList &exclusions)

See also setManualExclusions() and manualExclusionsChanged().

manualProxies : QList<QUrl>

This property holds the proxy servers configured for the currently selected manually configured proxy.

This configuration option only applies to the manual proxy type.

In the case of a manual proxy, the proxy to be used will be chosen from the list of proxies returned.

Access functions:

QList<QUrl> manualProxies() const
bool setManualProxies(const QList<QUrl> &proxies)

Notifier signal:

void manualProxiesChanged(const QList<QUrl> &proxies)

See also setManualProxies() and manualProxiesChanged().

type : ProxyType

This property holds the type of the currently selected proxy, either direct, manual or auto.

This is a property of the currently selected proxy (for a particular service, or the global proxy).

A proxy can either by direct, in which case there is no proxy in use, it can be manual, in which case a specific list of proxies must be provided, or it is auto, in which case the proxy is chosen by reference to a PAC file, which chooses which proxy to use based on the contents of the PAC file (which is actually a piece of JavaScript logic).

Access functions:

ProxyType type() const
bool setType(ProxyType type)

Notifier signal:

void typeChanged(ProxyType type)

See also ProxyType, setType(), type(), and typeChanged().

valid : const bool

This property holds whether the NetProxy instance is in a valid state.

If the state is not set to valid, then the main functionality (apart from that relating to the validity of the instance) shouldn't yet be used.

When a NetProxy instance is initially created it must collect various pieces of data asynchronously from other part of the system. The valid flag will be set to false until this process completed.

There are certain events which may cause the flag to change back to false during the lifetime of the instance. Attach to the validChanged() signal to remain aware of its state.

Access functions:

bool isValid() const

Notifier signal:

void validChanged(bool valid)

Member Function Documentation

NetProxy::NetProxy(QObject *parent = nullptr)

Constructs a new NetProxy with the given parent.

[virtual] NetProxy::~NetProxy()

Destroys the instance of NetProxy. The destructor is virtual.

[signal] void NetProxy::activeTypeChanged(ActiveType type)

Signal sent if the currently active proxy type switches from the service proxies to the global proxy or vice versa.

Note: Notifier signal for property activeType.

See also ActiveType, activeType, activeType(), and setActiveType().

[signal] void NetProxy::automaticUrlChanged(const QUrl &url)

The url for the currently selected service automatic proxy has changed.

Signal sent if the proxy is set to automatic, and the url of the PAC file to use to determine the proxy changes, for the currently selected service.

Note: Notifier signal for property automaticUrl.

See also automaticUrl and setAutomaticUrl().

QString NetProxy::getIdentifier() const

Returns the identifier for the currently selected service.

This will be the same identifier that was original used to select the service, and will also be one of the identifiers returned by calling getIdentifiers().

If the global proxy is selected, then the identifier returned will be global.

If no proxy is currently selected, an empty string will be returned.

QStringList NetProxy::getIdentifiers(const QString &technology) const

Returns a list of unique identifiers to the services which support proxies.

The identifiers will match those provided by connman. The usual use for this method is to extract the appropriate identifier for passing in to the selectProxy() method.

Identifiers can be listed filtered by technology. Passing an empty string will return all identifiers, regardless of technology.

In addition to the connman services, the identifier global will also be returned under the global technology, in reference to the global proxy.

See also getTechnologies() and selectProxy().

QString NetProxy::getName() const

Returns the human-readable name of the currently selected service.

If the global proxy is selected, then the identifier returned will be Global Proxy.

If no proxy is currently selected, an empty string will be returned.

QStringList NetProxy::getTechnologies() const

Returns the networking technologies that support proxy configuration.

The technologies will match those provided by connman, such as wifi or cellular. In addition a global technology will be returned, which refers to the global proxy.

See also getIdentifiers().

[signal] void NetProxy::manualExclusionsChanged(const QStringList &exclusions)

The list of exclusions for the currently selected service manual proxy has changed.

Signal sent if the proxy is set to manual, and the list of exclusions to use to determine the proxy changes, for the currently selected service.

Note: Notifier signal for property manualExclusions.

See also manualExclusions and setManualExclusions().

[signal] void NetProxy::manualProxiesChanged(const QList<QUrl> &proxies)

The list of proxies for the currently selected service manual proxy has changed.

Signal sent if the proxy is set to manual, and the list of proxies to use to determine the proxy changes, for the currently selected service.

Note: Notifier signal for property manualProxies.

See also manualProxies and setManualProxies().

[signal] void NetProxy::proxyConfigChanged()

Signal sent if any of the proxy configuration values for the currently selected service change.

This includes the proxy type, server list, exclusions list and url. It may also be triggered by a switch from service proxies to the global proxy or vice versa.

If you're interested in the change of a specific property it may be more convenient to connect to the singal for the specific property.

bool NetProxy::selectProxy(const QString &identifier)

Select a proxy to operate on.

Many different proxies may be operational on a device at once. To make changes to a specific proxy relating to a specific services, the proxy must first be selected using this method. Once selected, the other NetProxy operations, such as setting the proxy method, can then be used.

A common approach is to list the identifiers using getIdentifiers(), pass an identifier to selectProxy, and then perform further operations on the proxy using other NetProxy methods.

The global identifier should be used to select the global proxy. The identifier must be one of the values returned by getIdentifiers().

Returns true if the selection succeeded, false otherwise.

See also getIdentifiers().

bool NetProxy::setActiveType(ActiveType type)

Set whether the individal service proxies or global proxy should be active.

Pass in a type to set either the services proxies as being active, or the global proxy as being active.

Either individual service proxies can be applied, or the global proxy, but not both at the same time. This method allows switching between the two.

Returns true if the type was set, or false if no change was made (for example in case an attempt is made to set it to the current value).

Fails silently in the case of asynchronous errors.

Note: Setter function for property activeType.

See also ActiveType, activeType, activeType(), and activeTypeChanged().

bool NetProxy::setAutomaticUrl(const QUrl &url)

Set the URL of the PAC file to use for the currently selected service to url.

This configuration option only applies to the automatic proxy type.

In the case of an automatic proxy, the proxy is determined by a PAC file, which contains a JavaScript routine for selecting an appropriate proxy, based on the details of the request being made. This configuration option specifies the location of the PAC file to use.

Returns true if the value changed, or false otherwise. Situations in which false could be returned include if the value did not change, or there is no currently selected service.

Fails silently in the case of asynchronous errors.

Note: Setter function for property automaticUrl.

See also automaticUrl and automaticUrlChanged().

bool NetProxy::setManualExclusions(const QStringList &exclusions)

Set the domain exclusions for the currently selected service.

This configuration option only applies to the manual proxy type.

In the case of a manual proxy, a proxy is chosen from a list of configured proxies. However, if the request is being made to one of the excluded domains, then a direct request will be made instead.

Returns true if the value changed, or false otherwise. Situations in which false could be returned include if the value did not change, or there is no currently selected service.

Fails silently in the case of asynchronous errors.

Note: Setter function for property manualExclusions.

See also manualExclusions and manualExclusionsChanged().

bool NetProxy::setManualProxies(const QList<QUrl> &proxies)

Set the proxies proxy servers to use for the currently selected manually configured proxy.

This configuration option only applies to the manual proxy type.

In the case of a manual proxy, the proxy to be used will be chosen from the list of proxies supplied.

Returns true if the value changed, or false otherwise. Situations in which false could be returned include if the value did not change, or there is no currently selected service.

Fails silently in the case of asynchronous errors.

Note: Setter function for property manualProxies.

See also manualProxies and manualProxiesChanged().

bool NetProxy::setType(ProxyType type)

Set the type of the currently selected proxy.

A proxy can either by direct, in which case there is no proxy in use, it can be manual, in which case a specific list of proxies must be provided, or it is auto, in which case the proxy is chosen by reference to a PAC file, which chooses which proxy to use based on the contents of the PAC file (which is actually a piece of JavasScript logic).

Returns true if the value changed, or false otherwise. Situations in which false could be returned include if the value did not change, or there is no currently selected service.

Fails silently in the case of asynchronous errors.

Note: Setter function for property type.

See also ProxyType, type, type(), and typeChanged().

ProxyType NetProxy::type() const

Returns the type of the currently selected proxy.

A proxy can either by direct, in which case there is no proxy in use, it can be manual, in which case a specific list of proxies must be provided, or it is auto, in which case the proxy is chosen by reference to a PAC file, which chooses which proxy to use based on the contents of the PAC file (which is actually a piece of JavaScript logic).

Note: Getter function for property type.

See also ProxyType and setType().

[signal] void NetProxy::typeChanged(ProxyType type)

The type of currently selected proxy, either service or global, has changed.

Signal sent if the type of the currently selected proxy is switched from service to global or vice versa.

Note: Notifier signal for property type.

See also ProxyType, type, type(), and setType().

We use cookies to improve your user experience and to help us to develop our services. By continuing to browse the site, you approve of our use of cookies.