Re: [PATCH 3/3 v2] doc: Describe property array use with VPN connection SetProperty D-Bus method

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.