-
Notifications
You must be signed in to change notification settings - Fork 80
11. API
There is a limited API that can be used to interact with the add-on. It is accessible via the api.py script which (for LibreELEC type installs) is in /storage/.kodi/addons/service.vpn.manager/api.py.
I've tested this by calling the script via the setup menu (setup.xml) and the examples below reflect that. In order to run this via a remote button check out the connection cycling page or appropriate Kodi documentation. Briefly though these examples would add function to a keymap (for LE).
runscript(/storage/.kodi/addons/service.vpn.manager/api.py, Connect 1)
runscript(/storage/.kodi/addons/service.vpn.manager/api.py, Disconnect)
Call api.py with the parameter 'Connect' followed by a number from 1 to 10, representing one of the VPN connections that have been validated by the add-on.
RunScript(special://home/addons/service.vpn.manager/api.py, Connect 1)
Alternatively call api.py with the parameter 'Connect' followed by a fully qualified opvn filename.
RunScript(special://home/addons/service.vpn.manager/api.py, Connect /storage/.kodi/addons/service.vpn.manager/PIA/UK London (UDP).ovpn)
If the VPN is already connected to the requested location then nothing will happen. If the VPN is disconnected or connected to a different location then within a few seconds the disconnect/connecting/connected notification boxes will appear on the screen.
Call api.py with the parameter 'Disconnect'. If a VPN connection is present, then within a few seconds the disconnect notification should appear on the screen. If there is no VPN connection, then nothing will happen.
RunScript(special://home/addons/service.vpn.manager/api.py, Disconnect)
Call api.py with the parameter 'Cycle'. If there are multiple connections, it'll immediately cycle to the next connection with minimal delay. If there is one connection, a notification displaying the current connection will appear. If there are no VPN connections, then nothing will happen.
RunScript(special://home/addons/service.vpn.manager/api.py, Cycle)
Call api.py with the parameter 'Pause'. This pauses the VPN filtering function. The VPN connection will not be changed as a result of using any add-ons that are currently being filtered. No action will be taken if the filtering is already paused.
RunScript(special://home/addons/service.vpn.manager/api.py, Pause)
Call api.py with the parameter 'Restart'. Restarts the VPN filtering function. Usual filtering behaviour will resume. No action will be taken if the filtering is already in use.
RunScript(special://home/addons/service.vpn.manager/api.py, Restart)
Call api.py with the parameter 'Fake'. Fakes the connection and disconnection of a VPN. If a connection is already active, it will not be stopped. Notification icons will be blue on connection (rather than green) and some text will change to indicate that this function is active.
Used primarily for development purposes but can also be used to prevent the add-on from changing connections if another non-Kodi application is managing the VPN. Effectively disables the function of the add-on without having to disable the add-on entirely from within Kodi. This is different to pausing the filtering function as it will prevent any and all connections from being established, restarted and manually changed.
This setting will persist across restarts (It creates a 'FAKECONNECTION.txt' file in the add-on userdata directory, which if it exists will cause the faked connection behaviour. Alternatively this file can be created and deleted separately to adjust the fake behaviour.)
No action will be taken if the connection is already being faked.
RunScript(special://home/addons/service.vpn.manager/api.py, Fake)
Stops the add-on from faking connections. Using this API will not immediately cause a real connection to be attempted. Depending on the reconnect options, if the VPN task is not running then a real connection to the last faked connection will be established eventually. Alternatively a filter or manual connection will establish a real connection.
No action will be taken if the connection is already legitimate.
RunScript(special://home/addons/service.vpn.manager/api.py, Real)
Call api.py with the parameter 'Reconnect'. If a VPN connection is active, this will force the connection to stop and reconnect.
RunScript(special://home/addons/service.vpn.manager/api.py, Reconnect)
Call api.py with the parameter 'GetIP'. Will store information about the current active IP connection as properties attached to the Kodi home window (Window ID 10000). The properties are shown below, and can be accessed using the Kodi API, e.g xbmcgui.Window(10000).getProperty("VPN_Manager_API_State") with each returning a string.
- "VPN_Manager_API_State" - reports "True" if the VPN is connected, or "False" if it's not.
- "VPN_Manager_API_IP" - the current externally reported IP, determined by an IP location service.
- "VPN_Manager_API_Location" - the geographical location of the IP address.
- "VPN_Manager_API_Provider" - the ISP that's reported as hosting the IP address.
- "VPN_Manager_Last_Connection_Change" - time (seconds since epoch) of the last connection change (connect or disconnect).
RunScript(special://home/addons/service.vpn.manager/api.py, GetIP)
There's currently no return codes or feedback mechanism for the API, but any errors caused by invalid calls will be displayed in the error log.
The time (seconds since epoch) of the last API command is held in the home window value "VPN_Manager_API_Last_Command_Time".