VFS

Detailed Description

Class: kodi::addon::CInstanceVFS

Virtual Filesystem (VFS) add-on instance

This instance type is used to allow Kodi various additional file system types. Be it a special file system, a compressed package or a system available over the network, everything is possible with it.

This usage can be requested under various conditions, for example explicitly by another addon, by a Mimetype protocol defined in addon.xml or supported file extensions.

Include the header #include <kodi/addon-instance/VFS.h> to use this class.

---

Here is an example of what the addon.xml.in would look like for an VFS addon:

<?xml version="1.0" encoding="UTF-8"?>
<addon
  id="vfs.myspecialnamefor"
  version="1.0.0"
  name="My VFS addon"
  provider-name="Your Name">
  <requires>@ADDON_DEPENDS@</requires>
  <extension
    point="kodi.vfs"
    protocols="myprot"
    extensions=".abc|.def"
    files="true"
    filedirectories="true"
    directories="true"
    encodedhostname="true"
    supportDialog="true"
    supportPath="true"
    supportUsername="true"
    supportPassword="true"
    supportPort="true"
    supportBrowsing="true"
    supportWrite="true"
    defaultPort="1234"
    label="30000"
    zeroconf="your_special_zeroconf_allowed_identifier"
    library_@PLATFORM@="@LIBRARY_FILENAME@"/>
  <extension point="xbmc.addon.metadata">
    <summary lang="en_GB">My VFS addon summary</summary>
    <description lang="en_GB">My VFS description</description>
    <platform>@PLATFORM@</platform>
  </extension>
</addon>

Note

Regarding boolean values with "false", these can also be omitted, since this would be the default.

Standard values that can be declared for processing in addon.xml.

These values are used by Kodi to identify associated streams and file extensions and then to select the associated addon.

Labels	Type	Description
point	string	The identification of the addon instance to VFS is mandatory kodi.vfs. In addition, the instance declared in the first <extension ... /> is also the main type of addon.
defaultPort	integer	Default networking port to use for protocol.
directories	boolean	VFS entry can list directories.
extensions	string	Extensions for VFS entry. It is possible to declare several using |, e.g. .abc|.def|.ghi.
encodedhostname	boolean	URL protocol from add-ons use encoded hostnames.
filedirectories	boolean	VFS entry contains file directories.
files	boolean	Set to declare that VFS provides files.
protocols	boolean	Protocols for VFS entry. It is possible to declare several using |, e.g. myprot1|myprot2. Note This field also used to show on GUI, see supportBrowsing below about *2:. When used there, however, only a single protocol is possible!
supportWrite	boolean	Protocol supports write operations.
zeroconf	string	Zero conf announce string for VFS protocol.
library_@PLATFORM@	string	The runtime library used for the addon. This is usually declared by cmake and correctly displayed in the translated addon.xml.

User selectable parts of the addon.

The following table describes the values that can be defined by addon.xml and which part they relate to for user input.

Labels	Type	Description
supportBrowsing	boolean	Protocol supports server browsing. Used to open related sources by users in the window. Associated places in Kodi: *1: The entry in the menu represented by this option corresponds to the text given with label. When the button is pressed, CInstanceVFS::GetDirectory is called on the add-on to get its content. *2: Protocol name of the stream defined with protocols in xml. Remarks See also supportDialog about *3:.
supportDialog	boolean	To point out that Kodi assigns a dialog to this VFS in order to compare it with other values e.g. query supportPassword in it. This will be available when adding sources in Kodi under "Add network location...". Associated places in Kodi: *1: Field for selecting the VFS handler, the addon will be available if supportDialog is set to true. *2: To set the associated server address. Note: This field is always activated and cannot be changed by the addon. *3: If supportBrowsing is set to true, the button for opening a file selection dialog is given here too, as in the file window. *4: This field is available if supportPath is set to true. *5: To edit the connection port. This field is available if supportPort is set to true. *6: This sets the required username and is available when supportUsername is set to true. *7: This sets the required password and is available when supportPassword is set to true.
supportPath	boolean	Protocol has path in addition to server name (see supportDialog about *4:).
supportPort	boolean	Protocol supports port customization (see supportDialog about *5:).
supportUsername	boolean	Protocol uses logins (see supportDialog about *6:).
supportPassword	boolean	Protocol supports passwords (see supportDialog about *7:).
protocols	string	Protocols for VFS entry. Note This field is not editable and only used on GUI to show his name, see supportBrowsing about *2:
label	integer	The text identification number used in Kodi for display in the menu at supportDialog as a selection option and at supportBrowsing (see his image reference *1) as a menu entry. This can be a text identifier in Kodi or from addon. Remarks For addon within 30000-30999 or 32000-32999.

Remarks

For more detailed description of the addon.xml, see also https://kodi.wiki/view/Addon.xml.

---

Example:

#include <kodi/addon-instance/VFS.h>
 
class CMyVFS : public kodi::addon::CInstanceVFS
{
public:
  CMyVFS(const kodi::addon::IInstanceInfo& instance);
 
  // Add all your required functions, the most CInstanceVFS functions of
  // must be included to have addon working correctly.
  ...
};
 
CMyVFS::CMyVFS(const kodi::addon::IInstanceInfo& instance)
  : kodi::addon::CInstanceVFS(instance)
{
  ...
}
 
...
 
//----------------------------------------------------------------------
 
class CMyAddon : public kodi::addon::CAddonBase
{
public:
  CMyAddon() = default;
  ADDON_STATUS CreateInstance(const kodi::addon::IInstanceInfo& instance,
                              KODI_ADDON_INSTANCE_HDL& hdl) override;
};
 
// If you use only one instance in your add-on, can be instanceType and
// instanceID ignored
ADDON_STATUS CMyAddon::CreateInstance(const kodi::addon::IInstanceInfo& instance,
                                      KODI_ADDON_INSTANCE_HDL& hdl)
{
  if (instance.IsType(ADDON_INSTANCE_VFS))
  {
    kodi::Log(ADDON_LOG_INFO, "Creating my VFS instance");
    hdl = new CMyVFS(instance);
    return ADDON_STATUS_OK;
  }
  else if (...)
  {
    ...
  }
  return ADDON_STATUS_UNKNOWN;
}
 
ADDONCREATOR(CMyAddon)

The destruction of the example class CMyVFS is called from Kodi's header. Manually deleting the add-on instance is not required.

Topics
	Definitions, structures and enumerators
	VFS add-on general variables
	1. General access functions
	General access functions
	2. File editing functions
	File editing functions.

Function Documentation

CInstanceVFS()

CInstanceVFS ( const IInstanceInfo & instance )

inlineexplicit

VFS class constructor used to support multiple instance types.

Parameters

[in]

instance

The instance value given to kodi::addon::CAddonBase::CreateInstance(...).

Note

Instance path as a single is not supported by this type. It must ensure that it can be called up several times.

Warning

Only use instance from the CAddonBase::CreateInstance call.

~CInstanceVFS()

~CInstanceVFS ( )

overridedefault

Destructor.