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(KODI_HANDLE instance, const std::string& kodiVersion);
 
  // Add all your required functions, the most CInstanceVFS functions of
  // must be included to have addon working correctly.
  ...
};
 
CMyVFS::CMyVFS(KODI_HANDLE instance, const std::string& kodiVersion)
  : kodi::addon::CInstanceVFS(instance, kodiVersion)
{
  ...
}
 
...
 
//----------------------------------------------------------------------
 
class CMyAddon : public kodi::addon::CAddonBase
{
public:
  CMyAddon() { }
  ADDON_STATUS CreateInstance(int instanceType,
                              const std::string& instanceID,
                              KODI_HANDLE instance,
                              const std::string& version,
                              KODI_HANDLE& addonInstance) override;
};
 
// If you use only one instance in your add-on, can be instanceType and
// instanceID ignored
ADDON_STATUS CMyAddon::CreateInstance(int instanceType,
                                      const std::string& instanceID,
                                      KODI_HANDLE instance,
                                      const std::string& version,
                                      KODI_HANDLE& addonInstance)
{
  if (instanceType == ADDON_INSTANCE_VFS)
  {
    kodi::Log(ADDON_LOG_INFO, "Creating my VFS instance");
    addonInstance = new CMyVFS(instance, version);
    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.

Modules
	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	(	KODI_HANDLE	instance,
		const std::string &	kodiVersion = `""`
	)

inlineexplicit

VFS class constructor used to support multiple instance types.

Parameters

[in]	instance	The instance value given to `kodi::addon::CAddonBase::CreateInstance(...)`.
[in]	kodiVersion	[opt] given from Kodi by CAddonBase::CreateInstance to identify his instance API version

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 or CAddonBase::CreateInstance call.

◆ ~CInstanceVFS()

~CInstanceVFS ( )

overridedefault

Destructor.