[apt.git] / apt-pkg / edsp.h

// -*- mode: cpp; mode: fold -*-
/** Description \file edsp.h						{{{
   ######################################################################
   Set of methods to help writing and reading everything needed for EDSP
   with the notable exception of reading a scenario for conversion into
   a Cache as this is handled by edsp interface for listparser and friends
   ##################################################################### */
									/*}}}*/
#ifndef PKGLIB_EDSP_H
#define PKGLIB_EDSP_H

#include <apt-pkg/cacheset.h>
#include <apt-pkg/pkgcache.h>
#include <apt-pkg/cacheiterators.h>
#include <apt-pkg/macros.h>

#include <stdio.h>

#include <list>
#include <string>
#include <vector>

#ifndef APT_8_CLEANER_HEADERS
#include <apt-pkg/depcache.h>
#include <apt-pkg/progress.h>
#endif

class pkgDepCache;
class OpProgress;

namespace EDSP								/*{{{*/
{
	namespace Request
	{
	   enum Flags
	   {
	      AUTOREMOVE = (1 << 0), /*!< removal of unneeded packages should be performed */
	      UPGRADE_ALL = (1 << 1), /*!< upgrade all installed packages, like 'apt-get full-upgrade' without forbid flags */
	      FORBID_NEW_INSTALL = (1 << 2), /*!< forbid the resolver to install new packages */
	      FORBID_REMOVE = (1 << 3), /*!< forbid the resolver to remove packages */
	   };
	}
	/** \brief creates the EDSP request stanza
	 *
	 *  In the EDSP protocol the first thing send to the resolver is a stanza
	 *  encoding the request. This method will write this stanza by looking at
	 *  the given Cache and requests the installation of all packages which were
	 *  marked for installation in it (equally for remove).
	 *
	 *  \param Cache in which the request is encoded
	 *  \param output is written to this "file"
	 *  \param flags effecting the request documented in #EDSP::Request::Flags
	 *  \param Progress is an instance to report progress to
	 *
	 *  \return true if request was composed successfully, otherwise false
	 */
	bool WriteRequest(pkgDepCache &Cache, FileFd &output,
				 unsigned int const flags = 0,
				OpProgress *Progress = NULL);
	bool WriteRequest(pkgDepCache &Cache, FILE* output,
				 bool const upgrade = false,
				 bool const distUpgrade = false,
				 bool const autoRemove = false,
				OpProgress *Progress = NULL) APT_DEPRECATED_MSG("Use FileFd-based interface instead");

	/** \brief creates the scenario representing the package universe
	 *
	 *  After the request all known information about a package are send
	 *  to the solver. The output looks similar to a Packages or status file
	 *
	 *  All packages and version included in this Cache are send, even if
	 *  it doesn't make sense from an APT resolver point of view like versions
	 *  with a negative pin to enable the solver to propose even that as a
	 *  solution or at least to be able to give a hint what can be done to
	 *  statisfy a request.
	 *
	 *  \param Cache is the known package universe
	 *  \param output is written to this "file"
	 *  \param Progress is an instance to report progress to
	 *
	 *  \return true if universe was composed successfully, otherwise false
	 */
	bool WriteScenario(pkgDepCache &Cache, FileFd &output, OpProgress *Progress = NULL);
	bool WriteScenario(pkgDepCache &Cache, FILE* output, OpProgress *Progress = NULL) APT_DEPRECATED_MSG("Use FileFd-based interface instead");

	/** \brief creates a limited scenario representing the package universe
	 *
	 *  This method works similar to #WriteScenario as it works in the same
	 *  way but doesn't send the complete universe to the solver but only
	 *  packages included in the pkgset which will have only dependencies
	 *  on packages which are in the given set. All other dependencies will
	 *  be removed, so that this method can be used to create testcases
	 *
	 *  \param Cache is the known package universe
	 *  \param output is written to this "file"
	 *  \param pkgset is a set of packages the universe should be limited to
	 *  \param Progress is an instance to report progress to
	 *
	 *  \return true if universe was composed successfully, otherwise false
	 */
	bool WriteLimitedScenario(pkgDepCache &Cache, FileFd &output,
					 std::vector<bool> const &pkgset,
					 OpProgress *Progress = NULL);
	bool WriteLimitedScenario(pkgDepCache &Cache, FILE* output,
					 APT::PackageSet const &pkgset,
					 OpProgress *Progress = NULL) APT_DEPRECATED_MSG("Use FileFd-based interface instead");

	/** \brief waits and acts on the information returned from the solver
	 *
	 *  This method takes care of interpreting whatever the solver sends
	 *  through the standard output like a solution, progress or an error.
	 *  The main thread should hand his control over to this method to
	 *  wait for the solver to finish the given task. The file descriptor
	 *  used as input is completely consumed and closed by the method.
	 *
	 *  \param input file descriptor with the response from the solver
	 *  \param Cache the solution should be applied on if any
	 *  \param Progress is an instance to report progress to
	 *
	 *  \return true if a solution is found and applied correctly, otherwise false
	 */
	bool ReadResponse(int const input, pkgDepCache &Cache, OpProgress *Progress = NULL);

	/** \brief search and read the request stanza for action later
	 *
	 *  This method while ignore the input up to the point it finds the
	 *  Request: line as an indicator for the Request stanza.
	 *  The request is stored in the parameters install and remove then,
	 *  as the cache isn't build yet as the scenario follows the request.
	 *
	 *  \param input file descriptor with the edsp input for the solver
	 *  \param[out] install is a list which gets populated with requested installs
	 *  \param[out] remove is a list which gets populated with requested removals
	 *  \param[out] upgrade is true if it is a request like apt-get upgrade
	 *  \param[out] distUpgrade is true if it is a request like apt-get dist-upgrade
	 *  \param[out] autoRemove is true if removal of uneeded packages should be performed
	 *
	 *  \return true if the request could be found and worked on, otherwise false
	 */
	bool ReadRequest(int const input, std::list<std::string> &install,
			std::list<std::string> &remove, unsigned int &flags);
	APT_DEPRECATED_MSG("use the flag-based version instead") bool ReadRequest(int const input, std::list<std::string> &install,
			std::list<std::string> &remove, bool &upgrade,
			bool &distUpgrade, bool &autoRemove);

	/** \brief takes the request lists and applies it on the cache
	 *
	 *  The lists as created by #ReadRequest will be used to find the
	 *  packages in question and mark them for install/remove.
	 *  No solving is done and no auto-install/-remove.
	 *
	 *  \param install is a list of packages to mark for installation
	 *  \param remove is a list of packages to mark for removal
	 *  \param Cache is there the markers should be set
	 *
	 *  \return false if the request couldn't be applied, true otherwise
	 */
	bool ApplyRequest(std::list<std::string> const &install,
				 std::list<std::string> const &remove,
				 pkgDepCache &Cache);

	/** \brief formats a solution stanza for the given version
	 *
	 *  EDSP uses a simple format for reporting solutions:
	 *  A single required field name with an ID as value.
	 *  Additional fields might appear as debug aids.
	 *
	 *  \param output to write the stanza forming the solution to
	 *  \param Type of the stanza, used as field name
	 *  \param Ver this stanza applies to
	 *
	 *  \return true if stanza could be written, otherwise false
	 */
	bool WriteSolutionStanza(FileFd &output, char const * const Type, pkgCache::VerIterator const &Ver);
	bool WriteSolution(pkgDepCache &Cache, FILE* output) APT_DEPRECATED_MSG("Use FileFd-based single-stanza interface instead");

	/** \brief sends a progress report
	 *
	 *  \param percent of the solving completed
	 *  \param message the solver wants the user to see
	 *  \param output the front-end listens for progress report
	 */
	bool WriteProgress(unsigned short const percent, const char* const message, FileFd &output);
	bool WriteProgress(unsigned short const percent, const char* const message, FILE* output) APT_DEPRECATED_MSG("Use FileFd-based interface instead");

	/** \brief sends an error report
	 *
	 *  Solvers are expected to execute successfully even if
	 *  they were unable to calculate a solution for a given task.
	 *  Obviously they can't send a solution through, so this
	 *  methods deals with formatting an error message correctly
	 *  so that the front-ends can receive and display it.
	 *
	 *  The first line of the message should be a short description
	 *  of the error so it can be used for dialog titles or alike
	 *
	 *  \param uuid of this error message
	 *  \param message is free form text to describe the error
	 *  \param output the front-end listens for error messages
	 */
	bool WriteError(char const * const uuid, std::string const &message, FileFd &output);
	bool WriteError(char const * const uuid, std::string const &message, FILE* output) APT_DEPRECATED_MSG("Use FileFd-based interface instead");


	/** \brief executes the given solver and returns the pipe ends
	 *
	 *  The given solver is executed if it can be found in one of the
	 *  configured directories and setup for it is performed.
	 *
	 *  \param solver to execute
	 *  \param[out] solver_in will be the stdin of the solver
	 *  \param[out] solver_out will be the stdout of the solver
	 *
	 *  \return PID of the started solver or 0 if failure occurred
	 */
	pid_t ExecuteSolver(const char* const solver, int * const solver_in, int * const solver_out, bool /*overload*/);
	APT_DEPRECATED_MSG("add a dummy bool parameter to use the overload returning a pid_t") bool ExecuteSolver(const char* const solver, int *solver_in, int *solver_out);

	/** \brief call an external resolver to handle the request
	 *
	 *  This method wraps all the methods above to call an external solver
	 *
	 *  \param solver to execute
	 *  \param Cache with the problem and as universe to work in
	 *  \param flags effecting the request documented in #EDSP::Request::Flags
	 *  \param Progress is an instance to report progress to
	 *
	 *  \return true if the solver has successfully solved the problem,
	 *  otherwise false
	 */
	bool ResolveExternal(const char* const solver, pkgDepCache &Cache,
				    unsigned int const flags = 0,
				    OpProgress *Progress = NULL);
	APT_DEPRECATED_MSG("use the flag-based version instead") bool ResolveExternal(const char* const solver, pkgDepCache &Cache,
				    bool const upgrade, bool const distUpgrade,
				    bool const autoRemove, OpProgress *Progress = NULL);
}
									/*}}}*/
#endif
Commit	Line	Data
6d38011b	1	// -- mode: cpp; mode: fold --
575e9b5c DK	2	/** Description \file edsp.h {{{
575e9b5c DK	3	######################################################################
6d38011b	4	Set of methods to help writing and reading everything needed for EDSP
1e3f4083	5	with the notable exception of reading a scenario for conversion into
575e9b5c	6	a Cache as this is handled by edsp interface for listparser and friends
6d38011b DK	7	##################################################################### */
6d38011b DK	8	/}}}/
c3b85126 DK	9	#ifndef PKGLIB_EDSP_H
c3b85126 DK	10	#define PKGLIB_EDSP_H
6d38011b	11
15fc8636	12	#include <apt-pkg/cacheset.h>
453b82a3 DK	13	#include <apt-pkg/pkgcache.h>
453b82a3 DK	14	#include <apt-pkg/cacheiterators.h>
ce62f1de	15	#include <apt-pkg/macros.h>
453b82a3 DK	16
453b82a3 DK	17	#include <stdio.h>
6d38011b	18
472ff00e	19	#include <list>
29099cb6	20	#include <string>
6dcae298	21	#include <vector>
29099cb6	22
b9dadc24 DK	23	#ifndef APT_8_CLEANER_HEADERS
	24	#include <apt-pkg/depcache.h>
	25	#include <apt-pkg/progress.h>
	26	#endif
	27
472ff00e DK	28	class pkgDepCache;
	29	class OpProgress;
	30
c8a4ce6c	31	namespace EDSP /{{{/
6d38011b	32	{
43c71fad DK	33	namespace Request
	34	{
	35	enum Flags
	36	{
	37	AUTOREMOVE = (1 << 0), /!< removal of unneeded packages should be performed /
	38	UPGRADE_ALL = (1 << 1), /!< upgrade all installed packages, like 'apt-get full-upgrade' without forbid flags /
	39	FORBID_NEW_INSTALL = (1 << 2), /!< forbid the resolver to install new packages /
	40	FORBID_REMOVE = (1 << 3), /!< forbid the resolver to remove packages /
	41	};
	42	}
575e9b5c DK	43	/** \brief creates the EDSP request stanza
	44	*
	45	* In the EDSP protocol the first thing send to the resolver is a stanza
	46	* encoding the request. This method will write this stanza by looking at
	47	* the given Cache and requests the installation of all packages which were
	48	* marked for installation in it (equally for remove).
	49	*
	50	* \param Cache in which the request is encoded
	51	* \param output is written to this "file"
43c71fad	52	* \param flags effecting the request documented in #EDSP::Request::Flags
b57c0e35	53	* \param Progress is an instance to report progress to
575e9b5c DK	54	*
	55	* \return true if request was composed successfully, otherwise false
	56	*/
ef00bd7a	57	bool WriteRequest(pkgDepCache &Cache, FileFd &output,
43c71fad	58	unsigned int const flags = 0,
b57c0e35	59	OpProgress *Progress = NULL);
ef00bd7a DK	60	bool WriteRequest(pkgDepCache &Cache, FILE* output,
	61	bool const upgrade = false,
	62	bool const distUpgrade = false,
	63	bool const autoRemove = false,
	64	OpProgress *Progress = NULL) APT_DEPRECATED_MSG("Use FileFd-based interface instead");
575e9b5c DK	65
	66	/** \brief creates the scenario representing the package universe
	67	*
	68	* After the request all known information about a package are send
	69	* to the solver. The output looks similar to a Packages or status file
	70	*
	71	* All packages and version included in this Cache are send, even if
	72	* it doesn't make sense from an APT resolver point of view like versions
	73	* with a negative pin to enable the solver to propose even that as a
	74	* solution or at least to be able to give a hint what can be done to
	75	* statisfy a request.
	76	*
	77	* \param Cache is the known package universe
	78	* \param output is written to this "file"
b57c0e35	79	* \param Progress is an instance to report progress to
575e9b5c DK	80	*
	81	* \return true if universe was composed successfully, otherwise false
	82	*/
ef00bd7a DK	83	bool WriteScenario(pkgDepCache &Cache, FileFd &output, OpProgress *Progress = NULL);
ef00bd7a DK	84	bool WriteScenario(pkgDepCache &Cache, FILE* output, OpProgress *Progress = NULL) APT_DEPRECATED_MSG("Use FileFd-based interface instead");
575e9b5c DK	85
	86	/** \brief creates a limited scenario representing the package universe
	87	*
	88	* This method works similar to #WriteScenario as it works in the same
	89	* way but doesn't send the complete universe to the solver but only
	90	* packages included in the pkgset which will have only dependencies
	91	* on packages which are in the given set. All other dependencies will
	92	* be removed, so that this method can be used to create testcases
	93	*
	94	* \param Cache is the known package universe
	95	* \param output is written to this "file"
	96	* \param pkgset is a set of packages the universe should be limited to
b57c0e35	97	* \param Progress is an instance to report progress to
575e9b5c DK	98	*
	99	* \return true if universe was composed successfully, otherwise false
	100	*/
ef00bd7a	101	bool WriteLimitedScenario(pkgDepCache &Cache, FileFd &output,
6dcae298	102	std::vector<bool> const &pkgset,
b57c0e35	103	OpProgress *Progress = NULL);
ef00bd7a DK	104	bool WriteLimitedScenario(pkgDepCache &Cache, FILE* output,
	105	APT::PackageSet const &pkgset,
	106	OpProgress *Progress = NULL) APT_DEPRECATED_MSG("Use FileFd-based interface instead");
575e9b5c DK	107
	108	/** \brief waits and acts on the information returned from the solver
	109	*
	110	* This method takes care of interpreting whatever the solver sends
	111	* through the standard output like a solution, progress or an error.
2202a8a0 DK	112	* The main thread should hand his control over to this method to
	113	* wait for the solver to finish the given task. The file descriptor
	114	* used as input is completely consumed and closed by the method.
575e9b5c DK	115	*
	116	* \param input file descriptor with the response from the solver
	117	* \param Cache the solution should be applied on if any
b57c0e35	118	* \param Progress is an instance to report progress to
575e9b5c DK	119	*
	120	* \return true if a solution is found and applied correctly, otherwise false
	121	*/
c8a4ce6c	122	bool ReadResponse(int const input, pkgDepCache &Cache, OpProgress *Progress = NULL);
29099cb6	123
575e9b5c DK	124	/** \brief search and read the request stanza for action later
	125	*
	126	* This method while ignore the input up to the point it finds the
	127	* Request: line as an indicator for the Request stanza.
	128	* The request is stored in the parameters install and remove then,
	129	* as the cache isn't build yet as the scenario follows the request.
	130	*
	131	* \param input file descriptor with the edsp input for the solver
	132	* \param[out] install is a list which gets populated with requested installs
	133	* \param[out] remove is a list which gets populated with requested removals
	134	* \param[out] upgrade is true if it is a request like apt-get upgrade
	135	* \param[out] distUpgrade is true if it is a request like apt-get dist-upgrade
	136	* \param[out] autoRemove is true if removal of uneeded packages should be performed
	137	*
	138	* \return true if the request could be found and worked on, otherwise false
	139	*/
c8a4ce6c	140	bool ReadRequest(int const input, std::list<std::string> &install,
43c71fad DK	141	std::list<std::string> &remove, unsigned int &flags);
43c71fad DK	142	APT_DEPRECATED_MSG("use the flag-based version instead") bool ReadRequest(int const input, std::list<std::string> &install,
40795fca DK	143	std::list<std::string> &remove, bool &upgrade,
40795fca DK	144	bool &distUpgrade, bool &autoRemove);
575e9b5c DK	145
	146	/** \brief takes the request lists and applies it on the cache
	147	*
	148	* The lists as created by #ReadRequest will be used to find the
	149	* packages in question and mark them for install/remove.
	150	* No solving is done and no auto-install/-remove.
	151	*
	152	* \param install is a list of packages to mark for installation
	153	* \param remove is a list of packages to mark for removal
	154	* \param Cache is there the markers should be set
	155	*
	156	* \return false if the request couldn't be applied, true otherwise
	157	*/
c8a4ce6c	158	bool ApplyRequest(std::list<std::string> const &install,
29099cb6 DK	159	std::list<std::string> const &remove,
29099cb6 DK	160	pkgDepCache &Cache);
575e9b5c	161
71608330	162	/** \brief formats a solution stanza for the given version
575e9b5c	163	*
71608330 DK	164	* EDSP uses a simple format for reporting solutions:
	165	* A single required field name with an ID as value.
	166	* Additional fields might appear as debug aids.
575e9b5c	167	*
71608330 DK	168	* \param output to write the stanza forming the solution to
	169	* \param Type of the stanza, used as field name
	170	* \param Ver this stanza applies to
575e9b5c	171	*
71608330	172	* \return true if stanza could be written, otherwise false
575e9b5c	173	*/
71608330 DK	174	bool WriteSolutionStanza(FileFd &output, char const * const Type, pkgCache::VerIterator const &Ver);
71608330 DK	175	bool WriteSolution(pkgDepCache &Cache, FILE* output) APT_DEPRECATED_MSG("Use FileFd-based single-stanza interface instead");
575e9b5c DK	176
	177	/** \brief sends a progress report
	178	*
	179	* \param percent of the solving completed
	180	* \param message the solver wants the user to see
	181	* \param output the front-end listens for progress report
	182	*/
ef00bd7a DK	183	bool WriteProgress(unsigned short const percent, const char* const message, FileFd &output);
ef00bd7a DK	184	bool WriteProgress(unsigned short const percent, const char* const message, FILE* output) APT_DEPRECATED_MSG("Use FileFd-based interface instead");
575e9b5c DK	185
	186	/** \brief sends an error report
	187	*
	188	* Solvers are expected to execute successfully even if
	189	* they were unable to calculate a solution for a given task.
	190	* Obviously they can't send a solution through, so this
	191	* methods deals with formatting an error message correctly
1e3f4083	192	* so that the front-ends can receive and display it.
575e9b5c DK	193	*
	194	* The first line of the message should be a short description
	195	* of the error so it can be used for dialog titles or alike
ebfeeaed DK	196	*
ebfeeaed DK	197	* \param uuid of this error message
1e3f4083	198	* \param message is free form text to describe the error
ebfeeaed	199	* \param output the front-end listens for error messages
575e9b5c	200	*/
ef00bd7a DK	201	bool WriteError(char const * const uuid, std::string const &message, FileFd &output);
ef00bd7a DK	202	bool WriteError(char const * const uuid, std::string const &message, FILE* output) APT_DEPRECATED_MSG("Use FileFd-based interface instead");
ebfeeaed	203
29099cb6	204
575e9b5c DK	205	/** \brief executes the given solver and returns the pipe ends
	206	*
	207	* The given solver is executed if it can be found in one of the
	208	* configured directories and setup for it is performed.
	209	*
	210	* \param solver to execute
	211	* \param[out] solver_in will be the stdin of the solver
	212	* \param[out] solver_out will be the stdout of the solver
	213	*
5681b3fc	214	* \return PID of the started solver or 0 if failure occurred
575e9b5c	215	*/
c8a4ce6c	216	pid_t ExecuteSolver(const char* const solver, int * const solver_in, int * const solver_out, bool /overload/);
5dd00edb	217	APT_DEPRECATED_MSG("add a dummy bool parameter to use the overload returning a pid_t") bool ExecuteSolver(const char* const solver, int solver_in, int solver_out);
575e9b5c DK	218
	219	/** \brief call an external resolver to handle the request
	220	*
	221	* This method wraps all the methods above to call an external solver
	222	*
	223	* \param solver to execute
	224	* \param Cache with the problem and as universe to work in
43c71fad	225	* \param flags effecting the request documented in #EDSP::Request::Flags
b57c0e35	226	* \param Progress is an instance to report progress to
575e9b5c DK	227	*
	228	* \return true if the solver has successfully solved the problem,
	229	* otherwise false
	230	*/
c8a4ce6c	231	bool ResolveExternal(const char* const solver, pkgDepCache &Cache,
43c71fad DK	232	unsigned int const flags = 0,
	233	OpProgress *Progress = NULL);
	234	APT_DEPRECATED_MSG("use the flag-based version instead") bool ResolveExternal(const char* const solver, pkgDepCache &Cache,
741b7da9	235	bool const upgrade, bool const distUpgrade,
b57c0e35	236	bool const autoRemove, OpProgress *Progress = NULL);
c3392a9f	237	}
6d38011b DK	238	/}}}/
6d38011b DK	239	#endif