Signals
| ConditionChanged | (a{sv}: Condition) |
Properties
| Condition | a{sv} (String_Variant_Map) | Read/Write |
Description
The Conditions interface specifies under what conditions an account can be put online. When the conditions are met and the ConnectAutomatically property on the account is set to True, then the account will automatically try to connect. On the other hand, if the conditions are not met, the account won't attempt to connect, not even if requested so.
Rationale:
The main goal is to bind accounts to connectivity: most TCP and UDP based protocols require a network route to be present, while link-local does not. Then, some accounts might work only in certain VPNs.
There is also the case of user preferences: one might want to activate a certain account only when the user is at work, home, or using a particular network.
In cases where it would be beneficial for the user to (temporarily) override connectivity conditions the user should disable connectivity checking by means outside of scope of this specification.
Rationale:
For example, if account manager is using Network Manager for connectivity checking, but the current network connection is not being managed by NM, the user could turn off the checks by configuring the account manager or its connectivity plugins.
Condition is a string → variant map with patterns which must match the connectivity attributes. If any pattern matches, the condition is satisfied. If the condition map is empty, the condition is always satisfied.
The connectivity attributes defined by the account manager MUST have types that would be allowed in an ObserverChannelFilter entry (string and boolean attributes are expected to be most common).
The patterns in the Conditions property MUST either have types allowed for a connectivity attribute (which matches if the attribute is present with value equal to the pattern, using the same comparison rules defined in ObserverChannelFilter) or an array type whose elements could be a connectivity attribute (which matches if the attribute is present with a value listed in the array, or if the array is empty and the attribute is present with any value).
Well known connectivity attributes:
- network - b: TRUE if connected to any IP network, otherwise absent
- essid - s: WLAN ESSID, or absent if not connected to a WiFi network
- cellular - s: cellular network ID, or absent if not connected to a cellular network
- vpn - s: VPN ID, or absent if not connected to a VPN
Signals
ConditionChanged (a{sv}: Condition)
Parameters
- Condition — a{sv} (String_Variant_Map)
Properties
Condition — a{sv} (String_Variant_Map)
The condition map.
Example condition matching any, or no, connectivity (useful for eg. telephony CM which is always trivially online):
Condition = {}
Conditions matching any IPv4 network connection (for most of the protocols, eg. XMPP, IRC, SIP, ...):
Condition = {
"network": TRUE,
}
Conditions matching if at work (using WiFi) or connected to work via VPN:
Condition = {
"essid": "AcmeCompanyWifi",
"vpn": "acme-company-vpn"
}
Condition matching a PPP dialup to a cellular provider:
Condition = {
"cellular": "T-Mobile"
}