This is a pure virtual class that is used by libdar when interaction with the user is required. More...

#include <user_interaction5.hpp>

Inheritance diagram for libdar5::user_interaction:

Collaboration diagram for libdar5::user_interaction:

Public Member Functions
	user_interaction ()
	class constructor.

	user_interaction (const user_interaction &ref)=default

	user_interaction (user_interaction &&ref) noexcept=default

user_interaction &	operator= (const user_interaction &ref)=default

user_interaction &	operator= (user_interaction &&ref) noexcept=default

void	warning (const std::string &msg)
	method added for backward compatibility with API v5 More...

virtual void	pause (const std::string &message)
	method used to ask a boolean question to the user. More...

virtual bool	pause2 (const std::string &message)
	alternative method to the pause() method More...

virtual std::string	get_string (const std::string &message, bool echo)=0
	method used to ask a question that needs an arbitrary answer. More...

virtual secu_string	get_secu_string (const std::string &message, bool echo)=0
	same a get_string() but uses secu_string instead More...

virtual void	listing (const std::string &flag, const std::string &perm, const std::string &uid, const std::string &gid, const std::string &size, const std::string &date, const std::string &filename, bool is_dir, bool has_children)

virtual void	dar_manager_show_files (const std::string &filename, bool data_change, bool ea_change)

virtual void	dar_manager_contents (U_I number, const std::string &chemin, const std::string &archive_name)

virtual void	dar_manager_statistics (U_I number, const infinint &data_count, const infinint &total_data, const infinint &ea_count, const infinint &total_ea)

virtual void	dar_manager_show_version (U_I number, const std::string &data_date, const std::string &data_presence, const std::string &ea_date, const std::string &ea_presence)

bool	get_use_listing () const
	this is not a virtual method, it has not to be overwritten in inherited classes. More...

bool	get_use_dar_manager_show_files () const
	this is not a virtual method, it has not to be overwritten in inherited classes.

bool	get_use_dar_manager_contents () const
	this is not a virtual method, it has not to be overwritten in inherited classes.

bool	get_use_dar_manager_statistics () const
	this is not a virtual method, it has not to be overwritten in inherited classes.

bool	get_use_dar_manager_show_version () const
	this is not a virtual method, it has not to be overwritten in inherited classes.

virtual void	printf (const char *format,...) override
	libdar uses this call to format output before send to message() method. More...

virtual user_interaction *	clone () const =0
	make a newly allocated object which has the same properties as "this". More...

void	warning_with_more (U_I num)
	make a pause each N line of output when calling the warning method More...

Public Member Functions inherited from libdar::user_interaction
	user_interaction (const user_interaction &ref)=default

	user_interaction (user_interaction &&ref) noexcept=default

user_interaction &	operator= (const user_interaction &ref)=default

user_interaction &	operator= (user_interaction &&ref) noexcept=default

void	message (const std::string &message)

void	pause (const std::string &message)

std::string	get_string (const std::string &message, bool echo)

secu_string	get_secu_string (const std::string &message, bool echo)

Protected Member Functions
void	set_use_listing (bool val)
	method to be called with true as argument if you have defined a listing() method. More...

void	set_use_dar_manager_show_files (bool val)
	method to be called with true as argument if you have defined a dar_manager_show_files() method.

void	set_use_dar_manager_contents (bool val)
	method to be called with true as argument if you have defined a dar_manager_contents() method.

void	set_use_dar_manager_statistics (bool val)
	method to be called with true as argument if you have defined a dar_manager_statistics() method.

void	set_use_dar_manager_show_version (bool val)
	method to be called with true as argument if you have defined a dar_manager_show_version() method.

virtual void	inherited_message (const std::string &message) override
	need to be overwritten in place of the warning() method since API 3.1.x

virtual bool	inherited_pause (const std::string &message) override
	method used to ask a boolean question to the user. More...

virtual std::string	inherited_get_string (const std::string &message, bool echo) override
	method used to ask a question that needs an arbitrary answer. More...

virtual secu_string	inherited_get_secu_string (const std::string &message, bool echo) override
	same a get_string() but uses libdar::secu_string instead of std::string More...

virtual void	inherited_warning (const std::string &message)=0
	to be defined by inherited classes

Private Attributes
bool	use_listing

bool	use_dar_manager_show_files

bool	use_dar_manager_contents

bool	use_dar_manager_statistics

bool	use_dar_manager_show_version

U_I	at_once

U_I	count

Detailed Description

This is a pure virtual class that is used by libdar when interaction with the user is required.

You can base your own class on it using C++ inheritance or use the class user_interaction_callback which implements the interaction based on callback functions. The user_interaction class is used by libdar in the following circumpstances:

when is required a boolean answer to a question the pause() method is used
when a warning needs to be displayed to the user the warning() method is used
when a directory listing needs to be returned to the user the listing() method is used

the printf() method is built over the warning() methods to display a formated message it has not to be redefined in any inherited class. If you want to define you own class as inherited class of user_interaction you need to overwrite:

the clone() method. It is used to make local temporary copies of objets in libdar. It acts like the constructor copy but is virtual.
the pause() method
the warning() method
the listing() method (this is not mandatory). inherited classes can overwrite the listing() method, which will be used if the use_listing is set to true thanks to the set_use_listing() protected method. In that case the listing of archive contents is done thanks to this listing() method instead of the warning() method.
get_string() method
get_secu_string() method

WARNING ! if your own class has specific fields, you will probably need to redefine the copy constructor as well as operator = if you don't understand this and why, don't play trying making your own class, and/or read good C++ book about canonical form of a C++ class, as well as how to properly make an inherited class. And don't, complain if libdar segfault or core dumps. Libdar needs to make local copies of these objects, if the copy constructor is not properly defined in your inherited class this will crash the application.

Definition at line 87 of file user_interaction5.hpp.

Member Function Documentation

◆ clone()

virtual user_interaction* libdar5::user_interaction::clone ( ) const

pure virtual

make a newly allocated object which has the same properties as "this".

This is a virtual method, it must be overwritten in any inherited class copy constructor and = operator may have to be overwritten too if necessary Warning ! clone() must throw exception if necessary (Ememory), but never return a nullptr pointer !

Implemented in libdar5::user_interaction_callback.

◆ dar_manager_contents()

virtual void libdar5::user_interaction::dar_manager_contents	(	U_I	number,
		const std::string &	chemin,
		const std::string &	archive_name
	)

virtual

optional method to use if you want dar_manager database archive listing split in several fields if you want to use this feature, you have then to supply an implementation for this method in your inherited class, method that will be called by libdar in place of the warning method. You will also have to call the set_use_dar_manager_contents() protected method with true as argument from the constructor of your inherited class to tell libdar to use the dar_manager_contents() method in place of the warning() method.

Parameters

[in]	number	is the number of the archive in the database
[in]	chemin	recorded path where to find this archive
[in]	archive_name	basename of this archive

Note: this method can be set for database::show_contents() to call it

Reimplemented in libdar5::user_interaction_callback.

◆ dar_manager_show_files()

virtual void libdar5::user_interaction::dar_manager_show_files	(	const std::string &	filename,
		bool	data_change,
		bool	ea_change
	)

virtual

optional method to use if you want dar_manager database contents listing split in several fields. if you want to use this feature, you have then to supply an implementation for this method in your inherited class, method that will be called by libdar in place of the warning method. You will also have to call the set_use_dar_manager_show_files() protected method with true as argument from the constructor of your inherited class to tell libdar to use the dar_manager_show_files() method in place of the warning() method.

Parameters

[in]	filename	name of the file
[in]	data_change	whether the backup owns the most recent data for the file
[in]	ea_change	whether the backup owns the most recent Extended Attributes for the file

Note: this method can be set for database::show_files() method to call it

Reimplemented in libdar5::user_interaction_callback.

◆ dar_manager_show_version()

virtual void libdar5::user_interaction::dar_manager_show_version	(	U_I	number,
		const std::string &	data_date,
		const std::string &	data_presence,
		const std::string &	ea_date,
		const std::string &	ea_presence
	)

virtual

optional method to use if you want dar_manager statistics listing split in several fields if you want to use this feature, you have then to supply an implementation for this method in your inherited class, method that will be called by libdar in place of the warning method. You will also have to call the set_use_dar_manager_show_version() protected method with true as argument from the constructor of your inherited class to tell libdar to use the dar_manager_show_version() method in place of the warning() method.

Parameters

[in]	number	archive number
[in]	data_date	is the last modification date of the requested file in thie archive whose number is "number"
[in]	data_presence	is the nature of this modification, true if the data was saved, false if it was deleted
[in]	ea_date	is the date of the EA for the requested file in the archive whose number is "number"
[in]	ea_presence	is the nature of this modification, true if the EAs were saved, false if they were deleted

Note: this method can be set for database::show_version() method to call it

Reimplemented in libdar5::user_interaction_callback.

◆ dar_manager_statistics()

virtual void libdar5::user_interaction::dar_manager_statistics	(	U_I	number,
		const infinint &	data_count,
		const infinint &	total_data,
		const infinint &	ea_count,
		const infinint &	total_ea
	)

virtual

optional method to use if you want dar_manager statistics listing split in several fields if you want to use this feature, you have then to supply an implementation for this method in your inherited class, method that will be called by libdar in place of the warning method. You will also have to call the set_use_dar_manager_statistics() protected method with true as argument from the constructor of your inherited class to tell libdar to use the dar_manager_statistics() method in place of the warning() method.

Parameters

[in]	number	archive number
[in]	data_count	amount of file which last version is located in this archive
[in]	total_data	total number of file covered in this database
[in]	ea_count	amount of EA which last version is located in this archive
[in]	total_ea	total number of file that have EA covered by this database

Note: this method can be set for database::show_most_recent_stats() method to call it

Reimplemented in libdar5::user_interaction_callback.

◆ get_secu_string()

virtual secu_string libdar5::user_interaction::get_secu_string	(	const std::string &	message,
		bool	echo
	)

pure virtual

same a get_string() but uses secu_string instead

Parameters

[in]	message	is the question to display to the user.
[in]	echo	is set to false is the answer must not be shown while the user answers.

Returns: the user's answer.

Implemented in libdar5::user_interaction_callback.

◆ get_string()

virtual std::string libdar5::user_interaction::get_string	(	const std::string &	message,
		bool	echo
	)

pure virtual

method used to ask a question that needs an arbitrary answer.

Parameters

[in]	message	is the question to display to the user.
[in]	echo	is set to false is the answer must not be shown while the user answers.

Returns: the user's answer.

Implemented in libdar5::user_interaction_callback.

◆ get_use_listing()

bool libdar5::user_interaction::get_use_listing ( ) const

inline

this is not a virtual method, it has not to be overwritten in inherited classes.

for libdar to know if it is interesting to use listing(), dar_manager_show_files(), dar_manager_contents(), dar_manager_statistics() or to keep reporting listing thanks to the warning() method,

Definition at line 249 of file user_interaction5.hpp.

◆ inherited_get_secu_string()

virtual secu_string libdar5::user_interaction::inherited_get_secu_string	(	const std::string &	message,
		bool	echo
	)

overrideprotectedvirtual

same a get_string() but uses libdar::secu_string instead of std::string

Parameters

[in]	message	is the question to display to the user.
[in]	echo	is set to false is the answer must not be shown while the user answers.

Returns: the user's answer.

Note: messages passed by libdar are not ending with a newline by default its up to the implementation to separate messages by the adequate mean

Implements libdar::user_interaction.

◆ inherited_get_string()

virtual std::string libdar5::user_interaction::inherited_get_string	(	const std::string &	message,
		bool	echo
	)

overrideprotectedvirtual

method used to ask a question that needs an arbitrary answer.

Parameters

[in]	message	is the question to display to the user.
[in]	echo	is set to false is the answer must not be shown while the user answers.

Returns: the user's answer.

Note: messages passed by libdar are not ending with a newline by default its up to the implementation to separate messages by the adequate mean

Implements libdar::user_interaction.

◆ inherited_pause()

virtual bool libdar5::user_interaction::inherited_pause ( const std::string & message )

overrideprotectedvirtual

method used to ask a boolean question to the user.

Parameters

[in] message The boolean question to ask to the user

Returns: the answer of the user (true/yes or no/false)

Note: messages passed by libdar are not ending with a newline by default its up to the implementation to separate messages by the adequate mean

Implements libdar::user_interaction.

◆ listing()

virtual void libdar5::user_interaction::listing	(	const std::string &	flag,
		const std::string &	perm,
		const std::string &	uid,
		const std::string &	gid,
		const std::string &	size,
		const std::string &	date,
		const std::string &	filename,
		bool	is_dir,
		bool	has_children
	)

virtual

optional method to use if you want file listing splitted in several fields. If you need to use this feature, you have then to supply an implementation for this method, in your inherited class which will be called by libdar in place of the warning method You then also have to call the set_use_listing() method with true as parameter from the constructor of your inherited class (for example) to tell libdar that the listing() method is to be used in place of the warning() method for archive listing.

Parameters

[in]	flag	is the given information about the EA, compression, presence of saved data.
[in]	perm	is the access permission of the file.
[in]	uid	User ID of the file.
[in]	gid	Group ID of the file.
[in]	size	file size.
[in]	date	file modification date.
[in]	filename	file name.
[in]	is_dir	true if file is a directory.
[in]	has_children	true if file is a directory which is not empty.

Note: This is not a pure virtual method, this is normal, so your inherited class is not obliged to overwrite it.

Reimplemented in libdar5::user_interaction_callback.

◆ pause()

virtual void libdar5::user_interaction::pause ( const std::string & message )

inlinevirtual

method used to ask a boolean question to the user.

Parameters

[in] message is the message to be displayed, that is the question.

Exceptions

Euser_abort If the user answer "false" or "no" to the question the method must throw an exception of type "Euser_abort".

Reimplemented in libdar5::user_interaction_callback.

Definition at line 113 of file user_interaction5.hpp.

References pause2().

◆ pause2()

virtual bool libdar5::user_interaction::pause2 ( const std::string & message )

inlinevirtual

alternative method to the pause() method

Parameters

[in] message The boolean question to ask to the user

Returns: the answer of the user (true/yes or no/false)

Note: either pause2() or pause() must be overwritten, but not both. libdar always calls pause() which default implementation relies on pause2() where it converts negative return from pause2() by throwing the appropriated exception. As soon as you overwrite pause(), pause2() is no more used.

Definition at line 127 of file user_interaction5.hpp.

Referenced by pause().

◆ printf()

virtual void libdar5::user_interaction::printf	(	const char *	format,
			...
	)

overridevirtual

libdar uses this call to format output before send to message() method.

This is not a virtual method, it has not to be overwritten, it is just a sublayer over warning() Supported masks for the format string are:

%s %c %d %% (normal behavior)
%i (matches infinint *)
%S (matches std::string *)

Reimplemented from libdar::user_interaction.

◆ set_use_listing()

void libdar5::user_interaction::set_use_listing ( bool val )

inlineprotected

method to be called with true as argument if you have defined a listing() method.

in the constructor of any inherited class that define a listing() method it is advisable to call set_use_listing() with true as argument for libdar knows that the listing() call has to be used in place of the warning() call for file listing.

Definition at line 286 of file user_interaction5.hpp.

Referenced by libdar5::user_interaction_callback::set_listing_callback().

◆ warning()

void libdar5::user_interaction::warning ( const std::string & msg )

inline

method added for backward compatibility with API v5

Note: warning() has been renamed message() in libdar::user_interaction to let libdar5::user_interaction intercept the inherted_message() to inherited_warning() and keep implementing the warning_with_more() feature as warning() does not exist in the parent class and some API v5 program may call it we add a warning() methode here:

Definition at line 106 of file user_interaction5.hpp.

◆ warning_with_more()

void libdar5::user_interaction::warning_with_more ( U_I num )

inline

make a pause each N line of output when calling the warning method

Parameters

[in] num is the number of line to display at once, zero for unlimited display

Note: . Since API 3.1, the warning method is no more a pure virtual function you need to call the parent warning method in your method for this warning_with_more method works as expected.

Definition at line 276 of file user_interaction5.hpp.

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

user_interaction5.hpp

Public Member Functions

Protected Member Functions

Private Attributes

Detailed Description

Member Function Documentation

◆ clone()

◆ dar_manager_contents()

◆ dar_manager_show_files()

◆ dar_manager_show_version()

◆ dar_manager_statistics()

◆ get_secu_string()

◆ get_string()

◆ get_use_listing()

◆ inherited_get_secu_string()

◆ inherited_get_string()

◆ inherited_pause()

◆ listing()

◆ pause()

◆ pause2()

◆ printf()

◆ set_use_listing()

◆ warning()

◆ warning_with_more()