apt  2.2.4
About: Apt (Advanced Package Tool) is a management system for software packages (Debian/Ubuntu). Release series 2.2.
  Fossies Dox: apt-2.2.4.tar.gz  ("unofficial" and yet experimental doxygen-generated source code documentation)  

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