apt: apt-pkg/edsp.h File Reference

apt 2.7.6 commandline package manager

Enumerations | Functions
edsp.h File Reference
`#include <apt-pkg/cacheset.h>`
`#include <apt-pkg/macros.h>`
`#include <apt-pkg/pkgcache.h>`
`#include <stdio.h>`
`#include <list>`
`#include <string>`
`#include <vector>`

Go to the source code of this file.

## Enumerations
enum | Flags { AUTOREMOVE = (1 << 0) , UPGRADE_ALL = (1 << 1) , FORBID_NEW_INSTALL = (1 << 2) , FORBID_REMOVE = (1 << 3) }
enum | Flags { IMMEDIATE_CONFIGURATION_ALL = (1 << 0) , NO_IMMEDIATE_CONFIGURATION = (1 << 1) , ALLOW_TEMPORARY_REMOVE_OF_ESSENTIALS = (1 << 2) }
enum class | PKG_ACTION { NOOP , INSTALL , REINSTALL , REMOVE }

## Functions
APT_PUBLIC bool | WriteRequest (pkgDepCache &Cache, FileFd &output, unsigned int const flags=0, OpProgress *Progress=NULL)
| creates the EDSP request stanza
APT_PUBLIC bool | WriteScenario (pkgDepCache &Cache, FileFd &output, OpProgress *Progress=NULL)
| creates the scenario representing the package universe
APT_PUBLIC bool | WriteLimitedScenario (pkgDepCache &Cache, FileFd &output, std::vector< bool > const &pkgset, OpProgress *Progress=NULL)
| creates a limited scenario representing the package universe
APT_PUBLIC bool | ReadResponse (int const input, pkgDepCache &Cache, OpProgress *Progress=NULL)
| waits and acts on the information returned from the solver
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
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
APT_PUBLIC bool | WriteSolutionStanza (FileFd &output, char const *const Type, pkgCache::VerIterator const &Ver)
| formats a solution stanza for the given version
APT_PUBLIC bool | WriteProgress (unsigned short const percent, const char *const message, FileFd &output)
| sends a progress report
APT_PUBLIC bool | WriteError (char const *const uuid, std::string const &message, FileFd &output)
| sends an error report
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
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
APT_HIDDEN bool | WriteRequest (pkgDepCache &Cache, FileFd &output, unsigned int const flags, OpProgress *const Progress)
APT_HIDDEN bool | WriteScenario (pkgDepCache &Cache, FileFd &output, OpProgress *const Progress)
APT_HIDDEN bool | OrderInstall (char const *const planner, pkgPackageManager *const PM, unsigned int const version, OpProgress *const Progress)
APT_HIDDEN bool | ReadResponse (int const input, pkgPackageManager *const PM, OpProgress *const Progress)
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)

## Detailed Description

Description {{{

######

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

######

## Enumeration Type Documentation

## ◆ Flags [1/2]

enum Flags

Enumerator
AUTOREMOVE | removal of unneeded packages should be performed
UPGRADE_ALL | upgrade all installed packages, like 'apt-get full-upgrade' without forbid flags
FORBID_NEW_INSTALL | forbid the resolver to install new packages
FORBID_REMOVE | forbid the resolver to remove packages

## ◆ Flags [2/2]

enum Flags

Enumerator
IMMEDIATE_CONFIGURATION_ALL | try to keep the least amount of packages unconfigured as possible at all times
NO_IMMEDIATE_CONFIGURATION | do not perform immediate configuration at all
ALLOW_TEMPORARY_REMOVE_OF_ESSENTIALS | just as the name suggests, very special case and dangerous!

## Function Documentation

## ◆ ApplyRequest()

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

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.

Parameters

  install | is a list of packages to mark for installation
  remove | is a list of packages to mark for removal
  Cache | is there the markers should be set

Returns
  false if the request couldn't be applied, true otherwise

References EDSP::ApplyRequest().

Referenced by EDSP::ApplyRequest().

## ◆ ExecuteSolver()

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

The given solver is executed if it can be found in one of the configured directories and setup for it is performed.

Parameters

  | solver | to execute
  [out] | solver_in | will be the stdin of the solver
  [out] | solver_out | will be the stdout of the solver

Returns
  PID of the started solver or 0 if failure occurred

References EDSP::ExecuteSolver().

Referenced by EDSP::ExecuteSolver(), and EDSP::ResolveExternal().

## ◆ ReadRequest()

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

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.

Parameters

  | input | file descriptor with the edsp input for the solver
  [out] | install | is a list which gets populated with requested installs
  [out] | remove | is a list which gets populated with requested removals
  [out] | upgrade | is true if it is a request like apt-get upgrade
  [out] | distUpgrade | is true if it is a request like apt-get dist-upgrade
  [out] | autoRemove | is true if removal of unneeded packages should be performed

Returns
  true if the request could be found and worked on, otherwise false

References EDSP::ReadRequest().

Referenced by EDSP::ReadRequest().

## ◆ ReadResponse()

bool ReadResponse | ( | int const | input,
|  | pkgDepCache & | Cache,
|  | OpProgress * | Progress = `NULL`
| ) |  |

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.

Parameters

  input | file descriptor with the response from the solver
  Cache | the solution should be applied on if any
  Progress | is an instance to report progress to

Returns
  true if a solution is found and applied correctly, otherwise false

References pkgTagSection::Count(), GlobalError::DEBUG, and EDSP::ReadResponse().

Referenced by EDSP::ReadResponse(), and EDSP::ResolveExternal().

## ◆ ResolveExternal()

bool ResolveExternal | ( | const char *const | solver,
|  | pkgDepCache & | Cache,
|  | unsigned int const | flags = `0`,
|  | OpProgress * | Progress = `NULL`
| ) |  |

call an external resolver to handle the request

This method wraps all the methods above to call an external solver

Parameters

  solver | to execute
  Cache | with the problem and as universe to work in
  flags | effecting the request documented in EDSP::Request::Flags
  Progress | is an instance to report progress to

Returns
  true if the solver has successfully solved the problem, otherwise false

References EDSP::ExecuteSolver(), EDSP::ReadResponse(), EDSP::ResolveExternal(), EDSP::WriteRequest(), and EDSP::WriteScenario().

Referenced by EDSP::ResolveExternal().

## ◆ WriteError()

bool WriteError | ( | char const *const | uuid,
|  | std::string const & | message,
|  | FileFd & | output
| ) |  |

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

Parameters

  uuid | of this error message
  message | is free form text to describe the error
  output | the front-end listens for error messages

References EDSP::WriteError().

Referenced by EDSP::WriteError().

## ◆ WriteLimitedScenario()

bool WriteLimitedScenario | ( | pkgDepCache & | Cache,
|  | FileFd & | output,
|  | std::vector< bool > const & | pkgset,
|  | OpProgress * | Progress = `NULL`
| ) |  |

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

Parameters

  Cache | is the known package universe
  output | is written to this "file"
  pkgset | is a set of packages the universe should be limited to
  Progress | is an instance to report progress to

Returns
  true if universe was composed successfully, otherwise false

References EDSP::WriteLimitedScenario().

Referenced by EDSP::WriteLimitedScenario().

## ◆ WriteProgress()

bool WriteProgress | ( | unsigned short const | percent,
|  | const char *const | message,
|  | FileFd & | output
| ) |  |

sends a progress report

Parameters

  percent | of the solving completed
  message | the solver wants the user to see
  output | the front-end listens for progress report

References EDSP::WriteProgress().

Referenced by EDSP::WriteProgress().

## ◆ WriteRequest()

bool WriteRequest | ( | pkgDepCache & | Cache,
|  | FileFd & | output,
|  | unsigned int const | flags = `0`,
|  | OpProgress * | Progress = `NULL`
| ) |  |

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).

Parameters

  Cache | in which the request is encoded
  output | is written to this "file"
  flags | effecting the request documented in EDSP::Request::Flags
  Progress | is an instance to report progress to

Returns
  true if request was composed successfully, otherwise false

References EDSP::WriteRequest().

Referenced by EDSP::ResolveExternal(), and EDSP::WriteRequest().

## ◆ WriteScenario()

bool WriteScenario | ( | pkgDepCache & | Cache,
|  | FileFd & | output,
|  | OpProgress * | Progress = `NULL`
| ) |  |

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 satisfy a request.

Parameters

  Cache | is the known package universe
  output | is written to this "file"
  Progress | is an instance to report progress to

Returns
  true if universe was composed successfully, otherwise false

References EDSP::WriteScenario().

Referenced by EDSP::ResolveExternal(), and EDSP::WriteScenario().

## ◆ WriteSolutionStanza()

bool WriteSolutionStanza | ( | FileFd & | output,
|  | char const *const | Type,
|  | pkgCache::VerIterator const & | Ver
| ) |  |

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.

Parameters

  output | to write the stanza forming the solution to
  Type | of the stanza, used as field name
  Ver | this stanza applies to

Returns
  true if stanza could be written, otherwise false

References EDSP::WriteSolutionStanza().

Referenced by EDSP::WriteSolutionStanza().