apt-pkg/edsp.h

   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 noteable 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/depcache.h>
  13 #include <apt-pkg/cacheset.h>
  14
  15 #include <string>
  16
  17 class EDSP                                                              /*{{{*/
  18 {
  19         // we could use pkgCache::DepType and ::Priority, but these would be localized strings…
  20         static const char * const PrioMap[];
  21         static const char * const DepMap[];
  22
  23         bool static ReadLine(int const input, std::string &line);
  24         bool static StringToBool(char const *answer, bool const defValue);
  25
  26         void static WriteScenarioVersion(pkgDepCache &Cache, FILE* output,
  27                                          pkgCache::PkgIterator const &Pkg,
  28                                          pkgCache::VerIterator const &Ver);
  29         void static WriteScenarioDependency(pkgDepCache &Cache, FILE* output,
  30                                             pkgCache::PkgIterator const &Pkg,
  31                                             pkgCache::VerIterator const &Ver);
  32         void static WriteScenarioLimitedDependency(pkgDepCache &Cache, FILE* output,
  33                                                    pkgCache::PkgIterator const &Pkg,
  34                                                    pkgCache::VerIterator const &Ver,
  35                                                    APT::PackageSet const &pkgset);
  36 public:
  37         /** \brief creates the EDSP request stanza
  38          *
  39          *  In the EDSP protocol the first thing send to the resolver is a stanza
  40          *  encoding the request. This method will write this stanza by looking at
  41          *  the given Cache and requests the installation of all packages which were
  42          *  marked for installation in it (equally for remove).
  43          *
  44          *  \param Cache in which the request is encoded
  45          *  \param output is written to this "file"
  46          *  \param upgrade is true if it is an request like apt-get upgrade
  47          *  \param distUpgrade is true if it is a request like apt-get dist-upgrade
  48          *  \param autoRemove is true if removal of unneeded packages should be performed
  49          *
  50          *  \return true if request was composed successfully, otherwise false
  51          */
  52         bool static WriteRequest(pkgDepCache &Cache, FILE* output,
  53                                  bool const upgrade = false,
  54                                  bool const distUpgrade = false,
  55                                  bool const autoRemove = false);
  56
  57         /** \brief creates the scenario representing the package universe
  58          *
  59          *  After the request all known information about a package are send
  60          *  to the solver. The output looks similar to a Packages or status file
  61          *
  62          *  All packages and version included in this Cache are send, even if
  63          *  it doesn't make sense from an APT resolver point of view like versions
  64          *  with a negative pin to enable the solver to propose even that as a
  65          *  solution or at least to be able to give a hint what can be done to
  66          *  statisfy a request.
  67          *
  68          *  \param Cache is the known package universe
  69          *  \param output is written to this "file"
  70          *
  71          *  \return true if universe was composed successfully, otherwise false
  72          */
  73         bool static WriteScenario(pkgDepCache &Cache, FILE* output);
  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          *
  87          *  \return true if universe was composed successfully, otherwise false
  88          */
  89         bool static WriteLimitedScenario(pkgDepCache &Cache, FILE* output,
  90                                          APT::PackageSet const &pkgset);
  91
  92         /** \brief waits and acts on the information returned from the solver
  93          *
  94          *  This method takes care of interpreting whatever the solver sends
  95          *  through the standard output like a solution, progress or an error.
  96          *  The main thread should handle his control over to this method to
  97          *  wait for the solver to finish the given task
  98          *
  99          *  \param input file descriptor with the response from the solver
 100          *  \param Cache the solution should be applied on if any
 101          *
 102          *  \return true if a solution is found and applied correctly, otherwise false
 103          */
 104         bool static ReadResponse(int const input, pkgDepCache &Cache);
 105
 106         /** \brief search and read the request stanza for action later
 107          *
 108          *  This method while ignore the input up to the point it finds the
 109          *  Request: line as an indicator for the Request stanza.
 110          *  The request is stored in the parameters install and remove then,
 111          *  as the cache isn't build yet as the scenario follows the request.
 112          *
 113          *  \param input file descriptor with the edsp input for the solver
 114          *  \param[out] install is a list which gets populated with requested installs
 115          *  \param[out] remove is a list which gets populated with requested removals
 116          *  \param[out] upgrade is true if it is a request like apt-get upgrade
 117          *  \param[out] distUpgrade is true if it is a request like apt-get dist-upgrade
 118          *  \param[out] autoRemove is true if removal of uneeded packages should be performed
 119          *
 120          *  \return true if the request could be found and worked on, otherwise false
 121          */
 122         bool static ReadRequest(int const input, std::list<std::string> &install,
 123                         std::list<std::string> &remove, bool &upgrade,
 124                         bool &distUpgrade, bool &autoRemove);
 125
 126         /** \brief takes the request lists and applies it on the cache
 127          *
 128          *  The lists as created by #ReadRequest will be used to find the
 129          *  packages in question and mark them for install/remove.
 130          *  No solving is done and no auto-install/-remove.
 131          *
 132          *  \param install is a list of packages to mark for installation
 133          *  \param remove is a list of packages to mark for removal
 134          *  \param Cache is there the markers should be set
 135          *
 136          *  \return false if the request couldn't be applied, true otherwise
 137          */
 138         bool static ApplyRequest(std::list<std::string> const &install,
 139                                  std::list<std::string> const &remove,
 140                                  pkgDepCache &Cache);
 141
 142         /** \brief encodes the changes in the Cache as a EDSP solution
 143          *
 144          *  The markers in the Cache are observed and send to given
 145          *  file. The solution isn't checked for consistency or alike,
 146          *  so even broken solutions can be written successfully,
 147          *  but the front-end revicing it will properly fail then.
 148          *
 149          *  \param Cache which represents the solution
 150          *  \param output to write the stanzas forming the solution to
 151          *
 152          *  \return true if solution could be written, otherwise false
 153          */
 154         bool static WriteSolution(pkgDepCache &Cache, FILE* output);
 155
 156         /** \brief sends a progress report
 157          *
 158          *  \param percent of the solving completed
 159          *  \param message the solver wants the user to see
 160          *  \param output the front-end listens for progress report
 161          */
 162         bool static WriteProgress(unsigned short const percent, const char* const message, FILE* output);
 163
 164         /** \brief sends an error report
 165          *
 166          *  Solvers are expected to execute successfully even if
 167          *  they were unable to calculate a solution for a given task.
 168          *  Obviously they can't send a solution through, so this
 169          *  methods deals with formatting an error message correctly
 170          *  so that the front-ends can recieve and display it.
 171          *
 172          *  The first line of the message should be a short description
 173          *  of the error so it can be used for dialog titles or alike
 174          */
 175         bool static WriteError(std::string const &message, FILE* output);
 176
 177         /** \brief executes the given solver and returns the pipe ends
 178          *
 179          *  The given solver is executed if it can be found in one of the
 180          *  configured directories and setup for it is performed.
 181          *
 182          *  \param solver to execute
 183          *  \param[out] solver_in will be the stdin of the solver
 184          *  \param[out] solver_out will be the stdout of the solver
 185          *
 186          *  \return true if the solver could be started and the pipes
 187          *  are set up correctly, otherwise false and the pipes are invalid
 188          */
 189         bool static ExecuteSolver(const char* const solver, int *solver_in, int *solver_out);
 190
 191         /** \brief call an external resolver to handle the request
 192          *
 193          *  This method wraps all the methods above to call an external solver
 194          *
 195          *  \param solver to execute
 196          *  \param Cache with the problem and as universe to work in
 197          *  \param upgrade is true if it is a request like apt-get upgrade
 198          *  \param distUpgrade is true if it is a request like apt-get dist-upgrade
 199          *  \param autoRemove is true if unneeded packages should be removed
 200          *
 201          *  \return true if the solver has successfully solved the problem,
 202          *  otherwise false
 203          */
 204         bool static ResolveExternal(const char* const solver, pkgDepCache &Cache,
 205                                     bool const upgrade, bool const distUpgrade,
 206                                     bool const autoRemove);
 207 };
 208                                                                         /*}}}*/
 209 #endif