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                 boolean SplitRouting
 136
 137                         This value reflects the split routing setting on
 138                         connmand side. By default, this value is omitted and
 139                         defaults to false. The value needs to be explicitly
 140                         set to true for VPN to be split routed.
 141
 142                 int Index [readonly]
 143
 144                         The index of the VPN network tunneling interface.
 145                         If there is no tunneling device, then this value
 146                         is not returned.
 147
 148                 dict IPv4 [readonly]
 149
 150                         string Address
 151
 152                                 The current configured IPv4 address.
 153
 154                         string Netmask
 155
 156                                The current configured IPv4 netmask.
 157
 158                         string Gateway
 159
 160                                The current configured IPv4 gateway.
 161
 162                         string Peer
 163
 164                                The current configured VPN tunnel endpoint
 165                                IPv4 address.
 166
 167                 dict IPv6 [readonly]
 168
 169                         string Address
 170
 171                                 The current configured IPv6 address.
 172
 173                         string PrefixLength
 174
 175                                The prefix length of the IPv6 address.
 176
 177                         string Gateway
 178
 179                                The current configured IPv6 gateway.
 180
 181                         string Peer
 182
 183                                The current configured VPN tunnel endpoint
 184                                IPv6 address.
 185
 186                 array{string} Nameservers [readonly]
 187
 188                         The list of nameservers set by VPN.
 189
 190                 array{dict} UserRoutes [readwrite]
 191
 192                         int ProtocolFamily
 193
 194                                 Protocol family of the route. Set to 4
 195                                 if IPv4 and 6 if IPv6 route. Set to 0
 196                                 (PF_UNSPEC) or omit, to have it assigned
 197                                 automatically.
 198
 199                         string Network
 200
 201                                 The network part of the route.
 202
 203                         string Netmask
 204
 205                                 The netmask of the route. For IPv6 routes,
 206                                 this is the prefix length.
 207
 208                         string Gateway
 209
 210                                 Gateway address of the route.
 211
 212                         The list of currently active user activated
 213                         routes.
 214
 215                 array{dict} ServerRoutes [readonly]
 216
 217                         int ProtocolFamily
 218
 219                                 Protocol family of the route. Set to 4
 220                                 if IPv4 and 6 if IPv6 route.
 221
 222                         string Network
 223
 224                                 The network part of the route.
 225
 226                         string Netmask
 227
 228                                 The netmask of the route. For IPv6 routes,
 229                                 this is the prefix length.
 230
 231                         string Gateway
 232
 233                                 Gateway address of the route.
 234
 235                         The VPN server activated route. These routes
 236                         are pushed to connman by VPN server.
 237
 238                 There can be other properties also but as the VPN
 239                 technologies are so different, they have different
 240                 kind of options that they need, so not all options
 241                 are mentioned in this document.