doc/vpn-connection-api.txt

   1 vpn connection
   2 ==============
   3
   4 Service         net.connman.vpn
   5 Interface       net.connman.vpn.Connection
   6 Object path     [variable prefix]/{connection0,connection1,...}
   7
   8 Methods         dict GetProperties()  [experimental]
   9
  10                         Returns properties for the connection object. See
  11                         the properties section for available properties.
  12
  13                         Possible Errors: [connection].Error.InvalidArguments
  14
  15                 void SetProperty(string name, variant value) [experimental]
  16
  17                         Changes the value of the specified property or the
  18                         properties defined as a dict passed as variant, where
  19                         the format is equal to the dict returned by
  20                         GetProperties(). Only properties that are listed as
  21                         read-write are changeable. Property name "Properties"
  22                         indicates a dict of properties. On success a
  23                         PropertyChanged signal will be emitted for the
  24                         specified property or for all changed properties
  25                         individually. If there is no change in property value
  26                         no PropertyChanged signal is sent. Configuration is
  27                         written to disk when one or more values are changed.
  28                         In case a dict of properties are given, configuration
  29                         write is done after all properties are processed.
  30                         Specifics in dict use in contrast to setting a single
  31                         property:
  32                                 - Dict can contain values set as empty strings
  33                                   or arrays. This causes the values to be
  34                                   cleared as if using ClearProperty().
  35                                 - If there are errors with the properties,
  36                                   InvalidProperty or PermissionDenied error is
  37                                   returned. InvalidProperty is sent when there
  38                                   is at least one invalid property, in this
  39                                   case there can be also properties that
  40                                   cannot be changed (immutable properties).
  41                                   If there are only immutable properties
  42                                   PermissionDenied error is returned.
  43                                 - The properties that are invalid or immutable
  44                                   are reported back at the end of the error
  45                                   message as a comma separated property name
  46                                   list.
  47                                 - One invalid/immutable property does not
  48                                   cause the rest of the properties to be
  49                                   ignored. If there are valid and invalid
  50                                   properties, the valid properties emit
  51                                   PropertyChanged signal and invalid are
  52                                   reported back with an InvalidProperty
  53                                   message.
  54
  55                         Possible Errors: [connection].Error.InvalidArguments
  56                                          [connection].Error.InvalidProperty
  57                                          [connection].Error.PermissionDenied
  58                                          [connection].Error.NotSupported
  59
  60                 void ClearProperty(string name) [experimental]
  61
  62                         Clears the value of the specified property.
  63
  64                         Possible Errors: [connection].Error.InvalidArguments
  65                                          [connection].Error.InvalidProperty
  66                                          [connection].Error.PermissionDenied
  67
  68                 void Connect() [experimental]
  69
  70                         Connect this VPN connection. It will attempt to connect
  71                         to the VPN connection. The Connect() will wait until
  72                         the connection is created or there is an error. The
  73                         error description is returned in dbus error.
  74
  75                         Possible Errors: [connection].Error.InvalidArguments
  76                                         [connection].Error.InProgress
  77
  78                 void Connect2(string dbus_sender) [experimental]
  79
  80                         Connect this VPN connection. The Connect2() is a
  81                         wrapper for Connect() allowing to pass original D-Bus
  82                         sender when proxying the connection request. The
  83                         Connect2() will wait until the connection is created or
  84                         there is an error. The error description is returned in
  85                         dbus error.
  86
  87                         Possible Errors: [connection].Error.InvalidArguments
  88                                         [connection].Error.InProgress
  89
  90
  91                 void Disconnect() [experimental]
  92
  93                         Disconnect this VPN connection. If the connection is
  94                         not connected an error message will be generated.
  95
  96                         Possible Errors: [connection].Error.InvalidArguments
  97
  98 Signals         PropertyChanged(string name, variant value) [experimental]
  99
 100                         This signal indicates a changed value of the given
 101                         property.
 102
 103 Properties      string State [readonly]
 104
 105                         The connection state information.
 106
 107                         Valid states are "idle", "failure", "configuration",
 108                         "ready", "disconnect".
 109
 110                 string Type [readonly]
 111
 112                         The VPN type (for example "openvpn", "vpnc" etc.)
 113
 114                 string Name [readonly]
 115
 116                         The VPN name.
 117
 118                 string Domain [readonly]
 119
 120                         The domain name used behind the VPN connection.
 121                         This is optional for most VPN technologies.
 122
 123                 string Host [readonly]
 124
 125                        The VPN host (server) address.
 126
 127                 boolean Immutable [readonly]
 128
 129                         This value will be set to true if the connection is
 130                         configured externally via a configuration file.
 131
 132                         The only valid operation are Connect(), Disconnect()
 133                         and GetProperties()
 134
 135                 int Index [readonly]
 136
 137                         The index of the VPN network tunneling interface.
 138                         If there is no tunneling device, then this value
 139                         is not returned.
 140
 141                 dict IPv4 [readonly]
 142
 143                         string Address
 144
 145                                 The current configured IPv4 address.
 146
 147                         string Netmask
 148
 149                                The current configured IPv4 netmask.
 150
 151                         string Gateway
 152
 153                                The current configured IPv4 gateway.
 154
 155                         string Peer
 156
 157                                The current configured VPN tunnel endpoint
 158                                IPv4 address.
 159
 160                 dict IPv6 [readonly]
 161
 162                         string Address
 163
 164                                 The current configured IPv6 address.
 165
 166                         string PrefixLength
 167
 168                                The prefix length of the IPv6 address.
 169
 170                         string Gateway
 171
 172                                The current configured IPv6 gateway.
 173
 174                         string Peer
 175
 176                                The current configured VPN tunnel endpoint
 177                                IPv6 address.
 178
 179                 array{string} Nameservers [readonly]
 180
 181                         The list of nameservers set by VPN.
 182
 183                 array{dict} UserRoutes [readwrite]
 184
 185                         int ProtocolFamily
 186
 187                                 Protocol family of the route. Set to 4
 188                                 if IPv4 and 6 if IPv6 route. Set to 0
 189                                 (PF_UNSPEC) or omit, to have it assigned
 190                                 automatically.
 191
 192                         string Network
 193
 194                                 The network part of the route.
 195
 196                         string Netmask
 197
 198                                 The netmask of the route. For IPv6 routes,
 199                                 this is the prefix length.
 200
 201                         string Gateway
 202
 203                                 Gateway address of the route.
 204
 205                         The list of currently active user activated
 206                         routes.
 207
 208                 array{dict} ServerRoutes [readonly]
 209
 210                         int ProtocolFamily
 211
 212                                 Protocol family of the route. Set to 4
 213                                 if IPv4 and 6 if IPv6 route.
 214
 215                         string Network
 216
 217                                 The network part of the route.
 218
 219                         string Netmask
 220
 221                                 The netmask of the route. For IPv6 routes,
 222                                 this is the prefix length.
 223
 224                         string Gateway
 225
 226                                 Gateway address of the route.
 227
 228                         The VPN server activated route. These routes
 229                         are pushed to connman by VPN server.
 230
 231                 There can be other properties also but as the VPN
 232                 technologies are so different, they have different
 233                 kind of options that they need, so not all options
 234                 are mentioned in this document.