doc: VPN daemon API descriptions

3 files changed, 275 insertions, 0 deletions

diff --git a/doc/vpn-connection-api.txt b/doc/vpn-connection-api.txt
new file mode 100644
index 00000000..5fe39d34
--- /dev/null
+++ b/doc/vpn-connection-api.txt
@@ -0,0 +1,165 @@
+vpn connection
+==============
+
+Service		net.connman.vpn
+Interface	net.connman.vpn.Connection
+Object path	[variable prefix]/{connection0,connection1,...}
+
+Method		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.
+
+			Possible Errors: [connection].Error.InvalidArguments
+					 [connection].Error.InvalidProperty
+
+		void ClearProperty(string name) [experimental]
+
+			Clears the value of the specified property.
+
+			Possible Errors: [connection].Error.InvalidArguments
+					 [connection].Error.InvalidProperty
+
+		void Connect() [experimental]
+
+			Connect this VPN connection. It will attempt to connect
+			to the VPN connection. The Connect() will wait until
+			the connection is created or there is an error. The
+			error description is returned in dbus error.
+
+			Possible Errors: [connection].Error.InvalidArguments
+					[connection].Error.InProgress
+
+		void Disconnect() [experimental]
+
+			Disconnect this VPN connection. If the connection is
+			not connected an error message will be generated.
+
+			Possible Errors: [connection].Error.InvalidArguments
+
+Signals		PropertyChanged(string name, variant value) [experimental]
+
+			This signal indicates a changed value of the given
+			property.
+
+Properties	string State [readonly]
+
+			The connection state information.
+
+			Valid states are "idle", "failure", "configuration",
+			"ready", "disconnect".
+
+		string Type [readonly]
+
+			The VPN type (for example "openvpn", "vpnc" etc.)
+
+		string Name [readonly]
+
+			The VPN name.
+
+		string Domain [readonly]
+
+			The domain name used behind the VPN connection.
+			This is optional for most VPN technologies.
+
+		string Host [readonly]
+
+		       The VPN host (server) address.
+
+		int Index [readonly]
+
+			The index of the VPN network tunneling interface.
+			If there is no tunneling device, then this value
+			is not returned.
+
+		dict IPv4 [readonly]
+
+			string Address
+
+			        The current configured IPv4 address.
+
+			string Netmask
+
+			       The current configured IPv4 netmask.
+
+			string Gateway
+
+			       The current configured IPv4 gateway.
+
+			string Peer
+
+			       The current configured VPN tunnel endpoint
+			       IPv4 address.
+
+		dict IPv6 [readonly]
+
+			string Address
+
+			        The current configured IPv6 address.
+
+			string PrefixLength
+
+			       The prefix length of the IPv6 address.
+
+			string Gateway
+
+			       The current configured IPv6 gateway.
+
+			string Peer
+
+			       The current configured VPN tunnel endpoint
+			       IPv6 address.
+
+		array{string} Nameservers [readonly]
+
+			The list of nameservers set by VPN.
+
+		array{dict} UserRoutes
+
+			int ProtocolFamily
+
+				Protocol family of the route. Set to 4
+				if IPv4 and 6 if IPv6 route.
+
+			string Network
+
+				The network part of the route.
+
+			string Netmask
+
+				The netmask of the route.
+
+			string Gateway
+
+				Gateway address of the route.
+
+			The list of currently active user activated
+			routes.
+
+		array{dict} ServerRoutes [readonly]
+
+			int ProtocolFamily
+
+				Protocol family of the route. Set to 4
+				if IPv4 and 6 if IPv6 route.
+
+			string Network
+
+				The network part of the route.
+
+			string Netmask
+
+				The netmask of the route.
+
+			string Gateway
+
+				Gateway address of the route.
+
+			The VPN server activated route.
+
+		There can be other properties also but as the VPN
+		technologies are so different, they have different
+		kind of options that they need, so not all options
+		are mentioned in this document.
diff --git a/doc/vpn-manager-api.txt b/doc/vpn-manager-api.txt
new file mode 100644
index 00000000..66c5beef
--- /dev/null
+++ b/doc/vpn-manager-api.txt
@@ -0,0 +1,50 @@
+vpn manager
+===========
+
+Service		net.connman.vpn
+Interface	net.connman.vpn.Manager
+Object path	/
+
+Method		object Create(dict settings) [experimental]
+
+			Create a new VPN connection and configuration using
+			the supplied settings.
+
+		void Remove(object vpn)  [experimental]
+
+			Remove the previously created VPN configuration.
+
+		array{object,dict} GetConnections()  [experimental]
+
+			Returns a list of tuples with VPN connection object
+			path and dictionary of their properties.
+
+			Possible Errors: [manager].Error.InvalidArguments
+
+		void RegisterAgent(object path)  [experimental]
+
+			Register new agent for handling user requests.
+
+			Possible Errors: [manager].Error.InvalidArguments
+
+		void UnregisterAgent(object path)  [experimental]
+
+			Unregister an existing agent.
+
+			Possible Errors: [manager].Error.InvalidArguments
+
+Signals		ConnectionAdded(object path, dict properties)  [experimental]
+
+			Signal that is sent when a new VPN connection
+			is added.
+
+			It contains the object path of the VPN connection
+			and also its properties.
+
+		ConnectionRemoved(object path)  [experimental]
+
+			Signal that is sent when a VPN connection
+			has been removed.
+
+			The object path is no longer accessible after this
+			signal and only emitted for reference.
diff --git a/doc/vpn-overview.txt b/doc/vpn-overview.txt
new file mode 100644
index 00000000..42b6e94a
--- /dev/null
+++ b/doc/vpn-overview.txt
@@ -0,0 +1,60 @@
+VPN daemon overview
+*******************
+
+
+Manager interface
+=================
+
+Manager interface described in vpn-manager-api.txt is to be used
+by both the connectivity UI and by ConnMan. The Create(),
+Remove(), RegisterAgent() and UnregisterAgent() functions are for
+UI usage. The GetConnections() method and ConnectionAdded() and
+ConnectionRemoved() signals are for ConnMan VPN plugin to use.
+
+The UI should use the methods like this:
+- Ask VPN properties (like certs, usernames etc) from the user.
+- Call Manager.Create() to create a VPN connection (note that
+  the system does not yet try to connect to VPN at this point)
+- Register an agent to vpnd so that vpnd can ask any extra
+  parameters etc from the user if needed.
+- If the user wants to connect to VPN gateway, then the
+  connection attempt should be done in ConnMan side as
+  there will be a service created there.
+- If the user wishes to remove the VPN configuration, the UI
+  can call the Manager.Remove() which removes the VPN connection.
+  If the VPN was in use, the VPN connection is also disconnected.
+- When UI is terminated, the UI should call the UnregisterAgent()
+
+The ConnMan calls VPN daemon like this:
+- There is a VPN plugin which at startup starts to listen the
+  ConnectionAdded() and ConnectionRemoved() signals.
+- The VPN plugin will call GetConnections() in order to get
+  available VPN connections. It will then create a provider service
+  for each VPN connection that is returned.
+- User can then connect to the VPN by calling the service Connect()
+  method
+- The existing ConnMan Manager.ConnectProvider() interface can still
+  work by calling vpn.Manager.Create() and then call vpn.Connection.Connect()
+  but this ConnectProvider() interface will be deprecated at some
+  point.
+
+
+
+Connection interface
+====================
+
+The Manager.Create() will return the object path of the created
+vpn.Connection object and place it in idle state. Note that
+vpn.Connection.PropertyChanged signal is not called when Connection
+object is created because the same parameters are returned via
+vpn.Manager.ConnectionAdded() signal.
+The vpn.Connection object can be connected using the Connect() method
+and disconnected by calling Disconnect() method. When the connection
+is established (meaning VPN client has managed to create a connection
+to VPN server), then State property is set to "ready" and PropertyChanged
+signal is sent. If the connection cannot be established, then
+State property is set to "failure".
+After successfull connection, the relevant connection properties are sent
+by PropertyChanged signal; like IPv[4|6] information, the index of the
+VPN tunneling interface (if there is any), nameserver information,
+server specified routes etc.