High level interface to ignition fuel. More...

#include <FuelClient.hh>

Public Types
using	ModelResult = std::tuple< ModelIdentifier, Result >

Public Member Functions
	FuelClient ()
	Default constructor. More...

	FuelClient (const ClientConfig &_config, const Rest &_rest=Rest(), LocalCache *_cache=nullptr)
	Constructor accepts server and auth configuration. More...

	~FuelClient ()
	Destructor. More...

bool	CachedModel (const common::URI &_modelUrl)
	Check if a model exists in the cache. More...

Result	CachedModel (const common::URI &_modelUrl, std::string &_path)
	Check if a model is already present in the local cache. More...

Result	CachedModelFile (const common::URI &_fileUrl, std::string &_path)
	Check if a file belonging to a model is already present in the local cache. More...

bool	CachedWorld (const common::URI &_worldUrl)
	Check if a world exists in the cache. More...

Result	CachedWorld (const common::URI &_worldUrl, std::string &_path)
	Check if a world is already present in the local cache. More...

Result	CachedWorldFile (const common::URI &_fileUrl, std::string &_path)
	Check if a file belonging to a world is already present in the local cache. More...

ClientConfig &	Config ()
	Get a mutable reference to the client configuration. More...

Result	DeleteModel (const ModelIdentifier &_id)
	Remove a model from ignition fuel. More...

Result	DeleteUrl (const gz::common::URI &_uri, const std::vector< std::string > &_headers)
	Remove a resource, such as a model or world, from Ignition Fuel. More...

Result	DownloadModel (const common::URI &_modelUrl, std::string &_path)
	Download a model from ignition fuel. This will override an existing local copy of the model. More...

Result	DownloadModel (const ModelIdentifier &_id)
	Download a model from ignition fuel. This will override an existing local copy of the model. More...

Result	DownloadModel (const ModelIdentifier &_id, const std::vector< std::string > &_headers)
	Download a model from ignition fuel. This will override an existing local copy of the model. More...

Result	DownloadModel (const ModelIdentifier &_id, const std::vector< std::string > &_headers, std::vector< ModelIdentifier > &_dependencies)
	Download a model from ignition fuel. This will override an existing local copy of the model. More...

std::vector< ModelResult >	DownloadModels (const std::vector< ModelIdentifier > &_ids, size_t _jobs=2)
	Download a list of models from ignition fuel. More...

Result	DownloadWorld (const common::URI &_worldUrl, std::string &_path)
	Download a world from ignition fuel. This will override an existing local copy of the world. More...

Result	DownloadWorld (WorldIdentifier &_id)
	Download a world from Ignition Fuel. This will override an existing local copy of the world. More...

Result	DownloadWorlds (const std::vector< WorldIdentifier > &_ids, size_t _jobs=2)
	Download a list of mworlds from ignition fuel. More...

Result	ModelDependencies (const ModelIdentifier &_id, std::vector< ModelIdentifier > &_dependencies)
	Retrieve the list of dependencies for a model. More...

Result	ModelDependencies (const std::vector< ModelIdentifier > &_id, std::vector< ModelIdentifier > &_dependencies)
	Retrieve the list of dependencies for a list of models. More...

Result	ModelDetails (const ModelIdentifier &_id, ModelIdentifier &_model) const
	Fetch the details of a model. More...

Result	ModelDetails (const ModelIdentifier &_id, ModelIdentifier &_model, const std::vector< std::string > &_headers) const
	Fetch the details of a model. More...

ModelIter	Models (const CollectionIdentifier &_id) const
	Returns an iterator for the models found in a collection. More...

ModelIter	Models (const ModelIdentifier &_id)
	Returns models matching a given identifying criteria. More...

ModelIter	Models (const ModelIdentifier &_id) const
	Returns models matching a given identifying criteria. More...

ModelIter	Models (const ModelIdentifier &_id, bool _checkCache)
	Returns models matching a given identifying criteria. More...

ModelIter	Models (const ModelIdentifier &_id, bool _checkCache) const
	Returns models matching a given identifying criteria. More...

ModelIter	Models (const ServerConfig &_server)
	Returns an iterator that can return names of models. More...

ModelIter	Models (const ServerConfig &_server) const
	Returns an iterator that can return names of models. More...

bool	ParseCollectionUrl (const common::URI &_url, CollectionIdentifier &_id)
	Parse Collection identifer from URL. More...

bool	ParseModelFileUrl (const common::URI &_modelFileUrl, ModelIdentifier &_id, std::string &_filePath)
	Parse model file identifier from model file URL. More...

bool	ParseModelUrl (const common::URI &_modelUrl, ModelIdentifier &_id)
	Parse model identifier from model URL or unique name. More...

bool	ParseWorldFileUrl (const common::URI &_worldFileUrl, WorldIdentifier &_id, std::string &_filePath)
	Parse world file identifier from world file URL. More...

bool	ParseWorldUrl (const common::URI &_worldUrl, WorldIdentifier &_id)
	Parse world identifier from world URL or unique name. More...

Result	PatchModel (const ModelIdentifier &_model, const std::vector< std::string > &_headers)
	Update a model using a PATCH request. More...

Result	PatchModel (const ModelIdentifier &_model, const std::vector< std::string > &_headers, const std::string &_pathToModelDir)
	Update a model using a PATCH request. More...

void	PopulateLicenses (const ServerConfig &_server)
	This function requests the available licenses from the Fuel server and stores this information locally. More...

Result	UploadModel (const std::string &_pathToModelDir, const ModelIdentifier &_id, const std::vector< std::string > &_headers, bool _private=false)
	Upload a directory as a new model. More...

Result	WorldDetails (const WorldIdentifier &_id, WorldIdentifier &_world) const
	Fetch the details of a world. More...

WorldIter	Worlds (const CollectionIdentifier &_id) const
	Returns an iterator for the worlds found in a collection. More...

WorldIter	Worlds (const ServerConfig &_server) const
	Returns an iterator that can return information of worlds. More...

WorldIter	Worlds (const WorldIdentifier &_id) const
	Returns worlds matching a given identifying criteria. More...

Detailed Description

High level interface to ignition fuel.

Member Typedef Documentation

◆ ModelResult

using ModelResult = std::tuple<ModelIdentifier, Result>

Constructor & Destructor Documentation

◆ FuelClient() [1/2]

FuelClient ( )

Default constructor.

◆ FuelClient() [2/2]

FuelClient	(	const ClientConfig &	_config,
		const Rest &	_rest = `Rest()`,
		LocalCache *	_cache = `nullptr`
	)

Constructor accepts server and auth configuration.

Parameters

[in]	_config	configuration about servers to connect to
[in]	_rest	A REST request.
[in]	_cache	Test hook. Pointer to a local cache. The FuelClient will take ownership of the pointer and free it when destructed. If set to nullptr the client will instantiate it's own cache.

Remarks: the client saves a copy of the config passed into it

◆ ~FuelClient()

~FuelClient ( )

Destructor.

Member Function Documentation

◆ CachedModel() [1/2]

bool CachedModel ( const common::URI & _modelUrl )

Check if a model exists in the cache.

Parameters

[in] _modelUrl The unique URL of the world on a Fuel server. E.g.: https://fuel.gazebosim.org/1.0/caguero/models/Beer

Returns: True if the model exists in the cache, false otherwise.

◆ CachedModel() [2/2]

Result CachedModel	(	const common::URI &	_modelUrl,
		std::string &	_path
	)

Check if a model is already present in the local cache.

Parameters

[in]	_modelUrl	The unique URL of the model on a Fuel server. E.g.: https://fuel.gazebosim.org/1.0/caguero/models/Beer
[out]	_path	Local path where the model can be found.

Returns: FETCH_ERROR if not cached, FETCH_ALREADY_EXISTS if cached.

◆ CachedModelFile()

Result CachedModelFile	(	const common::URI &	_fileUrl,
		std::string &	_path
	)

Check if a file belonging to a model is already present in the local cache.

Parameters

[in]	_fileUrl	The unique URL of the file on a Fuel server. E.g.: https://server.org/1.0/owner/models/model/files/meshes/mesh.dae
[out]	_path	Local path where the file can be found.

Returns: FETCH_ERROR if not cached, FETCH_ALREADY_EXISTS if cached.

◆ CachedWorld() [1/2]

bool CachedWorld ( const common::URI & _worldUrl )

Check if a world exists in the cache.

Parameters

[in] _worldUrl The unique URL of the world on a Fuel server. E.g.: https://fuel.gazebosim.org/1.0/OpenRobotics/worlds/Empty

Returns: True if the world exists in the cache, false otherwise.

◆ CachedWorld() [2/2]

Result CachedWorld	(	const common::URI &	_worldUrl,
		std::string &	_path
	)

Check if a world is already present in the local cache.

Parameters

[in]	_worldUrl	The unique URL of the world on a Fuel server. E.g.: https://fuel.gazebosim.org/1.0/OpenRobotics/worlds/Empty
[out]	_path	Local path where the world can be found.

Returns: FETCH_ERROR if not cached, FETCH_ALREADY_EXISTS if cached.

◆ CachedWorldFile()

Result CachedWorldFile	(	const common::URI &	_fileUrl,
		std::string &	_path
	)

Check if a file belonging to a world is already present in the local cache.

Parameters

[in]	_fileUrl	The unique URL of the file on a Fuel server. E.g.: https://server.org/1.0/owner/worlds/world/files/name.world
[out]	_path	Local path where the file can be found.

Returns: FETCH_ERROR if not cached, FETCH_ALREADY_EXISTS if cached.

◆ Config()

ClientConfig& Config ( )

Get a mutable reference to the client configuration.

Returns: Mutable reference to the client configuration.

◆ DeleteModel()

Result DeleteModel ( const ModelIdentifier & _id )

Remove a model from ignition fuel.

Parameters

[in] _id The model identifier.

Returns: Result of the delete operation Deprecate this function in ign-fuel-tools5. DeleteUrl replaces this function.

◆ DeleteUrl()

Result DeleteUrl	(	const gz::common::URI &	_uri,
		const std::vector< std::string > &	_headers
	)

Remove a resource, such as a model or world, from Ignition Fuel.

Parameters

[in]	_uri	The full URI of the resource, e.g: https://fuel.gazebosim.org/1.0/openrobotcs/model/my_model
[in]	_headers	Headers to set on the HTTP request.

Returns: Result of the delete operation

◆ DownloadModel() [1/4]

Result DownloadModel	(	const common::URI &	_modelUrl,
		std::string &	_path
	)

Download a model from ignition fuel. This will override an existing local copy of the model.

Parameters

[in]	_modelUrl	The unique URL of the model to download. E.g.: https://fuel.gazebosim.org/1.0/caguero/models/Beer
[out]	_path	Path where the model was downloaded.

Returns: Result of the download operation.

◆ DownloadModel() [2/4]

Result DownloadModel ( const ModelIdentifier & _id )

Download a model from ignition fuel. This will override an existing local copy of the model.

Parameters

[in] _id The model identifier.

Returns: Result of the download operation

◆ DownloadModel() [3/4]

Result DownloadModel	(	const ModelIdentifier &	_id,
		const std::vector< std::string > &	_headers
	)

Download a model from ignition fuel. This will override an existing local copy of the model.

Parameters

[in]	_id	The model identifier.
[in]	_headers	Headers to set on the HTTP request.

Returns: Result of the download operation

◆ DownloadModel() [4/4]

Result DownloadModel	(	const ModelIdentifier &	_id,
		const std::vector< std::string > &	_headers,
		std::vector< ModelIdentifier > &	_dependencies
	)

Download a model from ignition fuel. This will override an existing local copy of the model.

Parameters

[in]	_id	The model identifier.
[in]	_headers	Headers to set on the HTTP request.
[out]	_dependencies	List of models that this model depends on.

Returns: Result of the download operation

◆ DownloadModels()

std::vector<ModelResult> DownloadModels	(	const std::vector< ModelIdentifier > &	_ids,
		size_t	_jobs = `2`
	)

Download a list of models from ignition fuel.

Parameters

[in]	_ids	The list of model ids to download. This will also find all recursive dependencies of the models
[in]	_jobs	Number of parallel jobs to use to download models

Returns: Result of the download operation.

◆ DownloadWorld() [1/2]

Result DownloadWorld	(	const common::URI &	_worldUrl,
		std::string &	_path
	)

Download a world from ignition fuel. This will override an existing local copy of the world.

Parameters

[in]	_worldUrl	The unique URL of the world to download. E.g.: https://fuel.gazebosim.org/1.0/OpenRobotics/worlds/Empty
[out]	_path	Path where the world was downloaded.

Returns: Result of the download operation.

◆ DownloadWorld() [2/2]

Result DownloadWorld ( WorldIdentifier & _id )

Download a world from Ignition Fuel. This will override an existing local copy of the world.

Parameters

[out] _id The world identifier, with local path updated.

Returns: Result of the download operation

◆ DownloadWorlds()

Result DownloadWorlds	(	const std::vector< WorldIdentifier > &	_ids,
		size_t	_jobs = `2`
	)

Download a list of mworlds from ignition fuel.

Parameters

[in]	_ids	The list of world ids to download.
[in]	_jobs	Number of parallel jobs to use to download worlds.

Returns: Result of the download operation.

◆ ModelDependencies() [1/2]

Result ModelDependencies	(	const ModelIdentifier &	_id,
		std::vector< ModelIdentifier > &	_dependencies
	)

Retrieve the list of dependencies for a model.

Parameters

[in]	_id	The model identifier.
[out]	_dependencies	The list of dependencies.

Returns: Result of the operation

◆ ModelDependencies() [2/2]

Result ModelDependencies	(	const std::vector< ModelIdentifier > &	_id,
		std::vector< ModelIdentifier > &	_dependencies
	)

Retrieve the list of dependencies for a list of models.

Parameters

[in]	_id	The list of model identifiers.
[out]	_dependencies	The list of dependencies.

Returns: Result of the operation

◆ ModelDetails() [1/2]

Result ModelDetails	(	const ModelIdentifier &	_id,
		ModelIdentifier &	_model
	)		const

Fetch the details of a model.

Parameters

[in] _id a partially filled out identifier used to fetch models

Remarks: Fulfills Get-One requirement

Parameters

[out] _model The requested model

Returns: Result of the fetch operation.

◆ ModelDetails() [2/2]

Result ModelDetails	(	const ModelIdentifier &	_id,
		ModelIdentifier &	_model,
		const std::vector< std::string > &	_headers
	)		const

Fetch the details of a model.

Parameters

[in] _id a partially filled out identifier used to fetch models

Remarks: Fulfills Get-One requirement

Parameters

[out] _model The requested model

Returns: Result of the fetch operation.

◆ Models() [1/7]

ModelIter Models ( const CollectionIdentifier & _id ) const

Returns an iterator for the models found in a collection.

Parameters

[in] _id a partially filled out identifier used to fetch a collection.

Returns: An iterator of models in the collection.

◆ Models() [2/7]

ModelIter Models ( const ModelIdentifier & _id )

Returns models matching a given identifying criteria.

Parameters

[in] _id a partially filled out identifier used to fetch models

Remarks: Fulfills Get-One requirement; Model names are unique to the owner, so this API allows the possibility of getting multiple models with the same name if the owner is not specified.

Returns: An iterator of models with names matching the criteria

◆ Models() [3/7]

ModelIter Models ( const ModelIdentifier & _id ) const

Returns models matching a given identifying criteria.

Parameters

[in] _id a partially filled out identifier used to fetch models

Remarks: Fulfills Get-One requirement; Model names are unique to the owner, so this API allows the possibility of getting multiple models with the same name if the owner is not specified.

Returns: An iterator of models with names matching the criteria

◆ Models() [4/7]

ModelIter Models	(	const ModelIdentifier &	_id,
		bool	_checkCache
	)

Returns models matching a given identifying criteria.

Parameters

[in]	_id	a partially filled out identifier used to fetch models
[in]	_checkCache	Whether to check the cache.

Remarks: Fulfills Get-One requirement; Model names are unique to the owner, so this API allows the possibility of getting multiple models with the same name if the owner is not specified.

Returns: An iterator of models with names matching the criteria

◆ Models() [5/7]

ModelIter Models	(	const ModelIdentifier &	_id,
		bool	_checkCache
	)		const

Returns models matching a given identifying criteria.

Parameters

[in]	_id	a partially filled out identifier used to fetch models
[in]	_checkCache	Whether to check the cache.

Remarks: Fulfills Get-One requirement; Model names are unique to the owner, so this API allows the possibility of getting multiple models with the same name if the owner is not specified.

Returns: An iterator of models with names matching the criteria

◆ Models() [6/7]

ModelIter Models ( const ServerConfig & _server )

Returns an iterator that can return names of models.

Remarks: Fulfills Get-All requirement; an iterator instead of a list of names is returned in case the model names api supports pagination in the future. The iterator may fetch more names if code continues to request it. The initial API appears to return all of the models, so right now this iterator stores a list of names internally.

Parameters

[in] _server The server to request the operation.

Returns: A model iterator

◆ Models() [7/7]

ModelIter Models ( const ServerConfig & _server ) const

Returns an iterator that can return names of models.

Remarks: Fulfills Get-All requirement; an iterator instead of a list of names is returned in case the model names api supports pagination in the future. The iterator may fetch more names if code continues to request it. The initial API appears to return all of the models, so right now this iterator stores a list of names internally.

Parameters

[in] _server The server to request the operation.

Returns: A model iterator

◆ ParseCollectionUrl()

bool ParseCollectionUrl	(	const common::URI &	_url,
		CollectionIdentifier &	_id
	)

Parse Collection identifer from URL.

Parameters

[in]	_url	The unique URL of a collection. It may also be a unique name, which is a URL without the server version.
[out]	_id	The collection identifier. It may contain incomplete information based on the passed URL and the current client config. The server version will be overridden if that server is in the config file.

Returns: True if parsed successfully.

◆ ParseModelFileUrl()

bool ParseModelFileUrl	(	const common::URI &	_modelFileUrl,
		ModelIdentifier &	_id,
		std::string &	_filePath
	)

Parse model file identifier from model file URL.

Parameters

[in]	_modelFileUrl	The unique URL of a model file. It may also be a unique name, which is a URL without the server version.
[out]	_id	The model identifier. It may contain incomplete information based on the passed URL and the current client config.
[out]	_filePath	Path to the file from the model's root directory, such as "meshes/mesh.dae" or "model.sdf".

Returns: True if parsed successfully.

◆ ParseModelUrl()

bool ParseModelUrl	(	const common::URI &	_modelUrl,
		ModelIdentifier &	_id
	)

Parse model identifier from model URL or unique name.

Parameters

[in]	_modelUrl	The unique URL of a model. It may also be a unique name, which is a URL without the server version.
[out]	_id	The model identifier. It may contain incomplete information based on the passed URL and the current client config. The server version will be overridden if that server is in the config file.

Returns: True if parsed successfully.

◆ ParseWorldFileUrl()

bool ParseWorldFileUrl	(	const common::URI &	_worldFileUrl,
		WorldIdentifier &	_id,
		std::string &	_filePath
	)

Parse world file identifier from world file URL.

Parameters

[in]	_worldFileUrl	The unique URL of a world file. It may also be a unique name, which is a URL without the server version.
[out]	_id	The world identifier. It may contain incomplete information based on the passed URL and the current client config.
[out]	_filePath	Path to the file from the world's root directory, such as "name.world"

Returns: True if parsed successfully.

◆ ParseWorldUrl()

bool ParseWorldUrl	(	const common::URI &	_worldUrl,
		WorldIdentifier &	_id
	)

Parse world identifier from world URL or unique name.

Parameters

[in]	_worldUrl	The unique URL of a world. It may also be a unique name, which is a URL without the server version.
[out]	_id	The world identifier. It may contain incomplete information based on the passed URL and the current client config. The server version will be overridden if that server is in the config file.

Returns: True if parsed successfully.

◆ PatchModel() [1/2]

Result PatchModel	(	const ModelIdentifier &	_model,
		const std::vector< std::string > &	_headers
	)

Update a model using a PATCH request.

Model fields that are patched by this function:

private

Parameters

[in]	_model	The model to patch. The contents of this model will be sent in the PATCH request.
[in]	_headers	Headers to set on the HTTP request.

Returns: Result of the patch operation.

◆ PatchModel() [2/2]

Result PatchModel	(	const ModelIdentifier &	_model,
		const std::vector< std::string > &	_headers,
		const std::string &	_pathToModelDir
	)

Update a model using a PATCH request.

Model fields that are patched by this function:

private
Model files contained in _pathToModelDir.
Description, tags, license, and other attributes found in the metadata.pbtxt or model.config file.

Parameters

[in]	_model	The model to patch. The contents of this model will be sent in the PATCH request.
[in]	_headers	Headers to set on the HTTP request.
[in]	_pathToModelDir	a path to a directory containing a model.

Returns: Result of the patch operation.

◆ PopulateLicenses()

void PopulateLicenses ( const ServerConfig & _server )

This function requests the available licenses from the Fuel server and stores this information locally.

The UploadModel function can use this information to set appropriate license information based on a model's metadata.pbtxt file. If license information is not available, then the UploadModel function will default to the "Creative Commons - Public Domain" license.

Parameters

[in] _server Information about the server that provides license information.

◆ UploadModel()

Result UploadModel	(	const std::string &	_pathToModelDir,
		const ModelIdentifier &	_id,
		const std::vector< std::string > &	_headers,
		bool	_private = `false`
	)

Upload a directory as a new model.

Parameters

[in]	_pathToModelDir	a path to a directory containing a model
[in]	_id	An identifier to assign to this new model
[in]	_headers	Headers to set on the HTTP request.
[in]	_private	True to make the model private.

Returns: Result of the upload operation

◆ WorldDetails()

Result WorldDetails	(	const WorldIdentifier &	_id,
		WorldIdentifier &	_world
	)		const

Fetch the details of a world.

Parameters

[in]	_id	a partially filled out identifier used to fetch worlds
[out]	_world	The requested world

Returns: Result of the fetch operation.

◆ Worlds() [1/3]

WorldIter Worlds ( const CollectionIdentifier & _id ) const

Returns an iterator for the worlds found in a collection.

Parameters

[in] _id a partially filled out identifier used to fetch a collection.

Returns: An iterator of words in the collection.

◆ Worlds() [2/3]

WorldIter Worlds ( const ServerConfig & _server ) const

Returns an iterator that can return information of worlds.

Remarks: An iterator instead of a list of names, to be able to handle pagination. The iterator may fetch more names if code continues to request it.

Parameters

[in] _server The server to request the operation.

Returns: A world iterator

◆ Worlds() [3/3]

WorldIter Worlds ( const WorldIdentifier & _id ) const

Returns worlds matching a given identifying criteria.

Parameters

[in] _id A partially filled out identifier used to fetch worlds

Returns: An iterator of worlds with names matching the criteria

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

gz/fuel_tools/FuelClient.hh

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ ModelResult

Constructor & Destructor Documentation

◆ FuelClient() [1/2]

◆ FuelClient() [2/2]

◆ ~FuelClient()

Member Function Documentation

◆ CachedModel() [1/2]

◆ CachedModel() [2/2]

◆ CachedModelFile()

◆ CachedWorld() [1/2]

◆ CachedWorld() [2/2]

◆ CachedWorldFile()

◆ Config()

◆ DeleteModel()

◆ DeleteUrl()

◆ DownloadModel() [1/4]

◆ DownloadModel() [2/4]

◆ DownloadModel() [3/4]

◆ DownloadModel() [4/4]

◆ DownloadModels()

◆ DownloadWorld() [1/2]

◆ DownloadWorld() [2/2]

◆ DownloadWorlds()

◆ ModelDependencies() [1/2]

◆ ModelDependencies() [2/2]

◆ ModelDetails() [1/2]

◆ ModelDetails() [2/2]

◆ Models() [1/7]

◆ Models() [2/7]

◆ Models() [3/7]

◆ Models() [4/7]

◆ Models() [5/7]

◆ Models() [6/7]

◆ Models() [7/7]

◆ ParseCollectionUrl()

◆ ParseModelFileUrl()

◆ ParseModelUrl()

◆ ParseWorldFileUrl()

◆ ParseWorldUrl()

◆ PatchModel() [1/2]

◆ PatchModel() [2/2]

◆ PopulateLicenses()

◆ UploadModel()

◆ WorldDetails()

◆ Worlds() [1/3]

◆ Worlds() [2/3]

◆ Worlds() [3/3]