On Fri, Dec 20, 2019 at 11:56:46AM +0200, Jussi Laakkonen wrote:
Include documentation for the use of dict array with the SetProperty
D-Bus method in VPN connection API.
Add error PermissionDenied for SetProperty and ClearProperty into VPN
connection API. Add missing NotSupported error for SetProperty into VPN
connection API.
---
Changes since v2:
* Removed SetProperties D-Bus method description from API.
* Reformatted the SetProperties description under SetProperty
description in the API.
* Changed the commit title to be more appropriate.
doc/vpn-connection-api.txt | 43 ++++++++++++++++++++++++++++++++++----
1 file changed, 39 insertions(+), 4 deletions(-)
diff --git a/doc/vpn-connection-api.txt b/doc/vpn-connection-api.txt
index 1fd3be26..80080ebe 100644
--- a/doc/vpn-connection-api.txt
+++ b/doc/vpn-connection-api.txt
@@ -14,13 +14,47 @@ Methods dict GetProperties() [experimental]
void SetProperty(string name, variant value) [experimental]
- Changes the value of the specified property. Only
- properties that are listed as read-write are
- changeable. On success a PropertyChanged signal
- will be emitted.
+ Changes the value of the specified property or the
+ properties defined as a dict passed as variant, where
+ the format is equal to the dict returned by
+ GetProperties(). Only properties that are listed as
+ read-write are changeable. On success a
+ PropertyChanged signal will be emitted for the
+ specified property or for all changed properties
+ individually. If there is no change in property value
+ no PropertyChanged signal is sent. Configuration is
+ written to disk when one or more values are changed.
+ In case a dict of properties are given, configuration
+ write is done after all properties are processed.
+ Specifics in dict use in contrast to setting a single
+ property:
+ - Dict can contain values set as empty strings
+ or arrays. This causes the values to be
+ cleared as if using ClearProperty().
+ - If there are errors with the properties,
+ InvalidProperty or PermissionDenied error is
+ returned. InvalidProperty is sent when there
+ is at least one invalid property, in this
+ case there can be also properties that
+ cannot be changed (immutable properties).
+ If there are only immutable properties
+ PermissionDenied error is returned.
+ - The properties that are invalid or immutable
+ are reported back at the end of the error
+ message as a comma separated property name
+ list.
+ - One invalid/immutable property does not
+ cause the rest of the properties to be
+ ignored. If there are valid and invalid
+ properties, the valid properties emit
+ PropertyChanged signal and invalid are
+ reported back with an InvalidProperty
+ message.
In the case of the dictionary, the property name can be anything,
correct? Maybe we should define it to something like SetProperties?
Patch applied.
Thanks,
Daniel