ioformat::ProtocolPlugin Class Reference

ProtocolPlugin is an interface for plugins that provide access to data using a specific protocol. More...

#include <ioformat/plugin/ProtocolPlugin.h>

Inherits ioformat::Plugin.

Public Member Functions
uint64_t	api () const final override
	Get the API version of the plugin.
virtual const StringSet &	supportedSchemes () const =0
	Get the URI schemes supported by the plugin.
virtual bool	exists (const std::string &uri)=0
	Check if the resource addressed by the URI exists.
virtual std::shared_ptr< iolink::RandomAccess >	openReader (const std::string &uri, const OptionMap &options)=0
	Open a handler to read data from a remote resource addressed by a URI.
virtual std::shared_ptr< iolink::StreamAccess >	openWriter (const std::string &uri, const OptionMap &options)=0
	Open a handler to write data to a remote resource addressed by a URI.
virtual StringSet	list (const std::string &host, const std::string &prefix, const OptionMap &options)=0
	List the resources on a specific host filtered with a prefix.
virtual void	addCredentials (const std::string &host, const std::string &user, const std::string &password)=0
	Add credentials to the plugin for a specific host.
Public Member Functions inherited from ioformat::Plugin
virtual const std::string &	name () const =0
	Get the name of the plugin.
virtual const PluginVersion &	version () const =0
	Get the version of the plugin.
virtual void	initLog (iolink::LogLevel level)=0
	Initialize the plugin's logger.

Static Public Attributes
static constexpr uint64_t	PLUGIN_API_VERSION = 2
	The actual API version of the plugin.

Additional Inherited Members
Public Types inherited from ioformat::Plugin
using	StringSet = std::unordered_set< std::string >
using	StringMap = std::unordered_map< std::string, std::string >

Detailed Description

ProtocolPlugin is an interface for plugins that provide access to data using a specific protocol.

In order to create a protocol plugin that will be used by ioformat to support a specific protocol through a URI scheme, the plugin must implement this interface.

Member Function Documentation

addCredentials()

virtual void ioformat::ProtocolPlugin::addCredentials ( const std::string &  host, const std::string &  user, const std::string &  password  )

pure virtual

Add credentials to the plugin for a specific host.

If credentials were already added for the host, they will be replaced by the new ones.

Parameters

host	The host to add credentials for.
user	The user to use for authentication.
password	The password to use for authentication.

Exceptions

UnsupportedOperation

if the protocol plugin does not support credentials

api()

uint64_t ioformat::ProtocolPlugin::api ( ) const

inlinefinaloverridevirtual

Get the API version of the plugin.

This is used internally to check compatibility between the plugin and the ioformat plugin loader.

Implements ioformat::Plugin.

exists()

virtual bool ioformat::ProtocolPlugin::exists ( const std::string &  uri )

pure virtual

Check if the resource addressed by the URI exists.

Parameters

uri	The URI to check.

Returns

True if the resource exists, false otherwise.

Exceptions

UnsupportedOperation	If the plugin does not support the operation.
Error	When a problem occurs inside the protocol layer.

list()

virtual StringSet ioformat::ProtocolPlugin::list ( const std::string &  host, const std::string &  prefix, const OptionMap &  options  )

pure virtual

List the resources on a specific host filtered with a prefix.

The root URI is the URI to the host itself, for example "http://example.com". This method lists all the resources available on the host, filtered with the given prefix. Meaning only resources whose paths begin with the prefix will be returned.

Example: When listing the resources from the host "https://somewhere.net", using the prefix "images/", the method will return the URIs of all the resources on the host, with a path beginning with "images/". Such as "https://somewhere.net/images/kitten.png", or "https://somewhere.net/images/landscape.jpg". URIs of resources like "https://somewhere.net/accounting/january.csv" will be filtered out.

Parameters

host	The URI to the root of the resources' host.
prefix	the prefix used to filter resources.
options	The options to use for the listing.

Returns

A set of URIs of the resource on the host, matching the prefix.

Exceptions

UnsupportedOperation	If the plugin does not support the operation.
Error	When a problem occurs inside the protocol layer.

openReader()

virtual std::shared_ptr< iolink::RandomAccess > ioformat::ProtocolPlugin::openReader ( const std::string &  uri, const OptionMap &  options  )

pure virtual

Open a handler to read data from a remote resource addressed by a URI.

This method will fail if the resource does not exist.

Parameters

uri	The URI to open.
options	The options to use for the read operation.

Returns

A random access instance, accessing the resource's data.

Exceptions

UnsupportedOperation	If the plugin does not support the operation.
Error	When a problem occurs inside the protocol layer.
Error	When the resource does not exist.

openWriter()

virtual std::shared_ptr< iolink::StreamAccess > ioformat::ProtocolPlugin::openWriter ( const std::string &  uri, const OptionMap &  options  )

pure virtual

Open a handler to write data to a remote resource addressed by a URI.

This method creates a new resource and will fail if the resource already exists.

Parameters

uri	The URI to open.
options	The options to use for the write operation.

Returns

A stream access instance, writing to the resource.

Exceptions

UnsupportedOperation	If the plugin does not support the operation.
Error	When a problem occurs inside the protocol layer.
Error	When the resource already exists.

---

The documentation for this class was generated from the following file:

• ioformat/public/include/ioformat/plugin/ProtocolPlugin.h