SCPM interface
1.0
|
Public Member Functions | |
SCPM (int options=0, std::ostream &info_out=cout, std::ostream &hash_out=cout, std::string root="") | |
Constructor. More... | |
~SCPM () | |
Destructor. More... | |
bool | Enable (bool force=false) |
Makes SCPM ready for use. More... | |
bool | Disable () |
Completely disables SCPM. More... | |
bool | Active (std::string &profile) |
query for active profile More... | |
bool | List (std::vector< std::string > &profiles) |
lists all profiles More... | |
bool | Add (std::string profile, bool auto_switch=true) |
Adds a new profile. More... | |
bool | Copy (std::string source_profile, std::string profile) |
Adds a new profile. More... | |
bool | Create (std::string profile, std::string source_profile) |
Adds a new profile. More... | |
bool | Delete (std::string profile) |
Deletes a profile. More... | |
bool | Rename (std::string profile, std::string newprofile) |
Renames a profile. More... | |
bool | Reload () |
Reloads the current profile. More... | |
bool | PrepareSwitch (std::string profile, switch_info_t &switch_info) |
Prepares the switch to profile profile More... | |
bool | Switch (switch_info_t &switch_info) |
Perform prepared switch. More... | |
bool | Save (switch_info_t &switch_info) |
Save modified resources. More... | |
bool | Modify (std::string profile, std::string action) |
Perform a profile modify action. More... | |
bool | Set (std::string command, std::string argument, std::string profile="") |
Set profile options. More... | |
bool | Get (std::string command, std::string &result, std::string profile="") |
Get profile options. More... | |
bool | Status (scpm_status_t &status) |
Query some status information. More... | |
bool | ShowChanges (std::ostream &output, std::string resource_type, std::string resource_name, bool backup=false, string version="") |
Shows changes of given resource. More... | |
bool | SetResourceSet (std::string set) |
Sets a resource set for use. More... | |
bool | GetResourceSet (std::string &set) |
Gets the active resource set. More... | |
bool | ListResourceSets (std::vector< std::string > &predefined, std::vector< std::string > &individual) |
Gets all defined resource sets. More... | |
bool | CopyResourceSet (std::string set, std::string newset) |
Copies a resource set. More... | |
bool | DeleteResourceSet (std::string set) |
Deletes an individual resource set. More... | |
bool | ListResourceGroups (std::vector< resource_group_t > &groups) |
Generates a list of all installed resource groups. More... | |
bool | GetResourceGroup (const std::string &name, std::vector< resource_entry_t > &group, bool nouser=false) |
bool | GetResourceGroup (const std::string &name, std::vector< resource_entry_t > &group, std::string &description, bool nouser=false) |
bool | SetResourceGroup (const std::string &name, const std::vector< resource_entry_t > &group, const std::string &description) |
Modifies or creates a resource group. More... | |
bool | DeleteResourceGroup (const std::string &group) |
Removes a resource group. More... | |
bool | RenameResourceGroup (const std::string &group, const std::string &newgroup) |
Renames a resource group. More... | |
bool | SetActiveResourceGroups (const std::vector< std::string > &groups) |
Sets active resource groups. More... | |
bool | GetActiveResourceGroups (std::vector< std::string > &groups) |
Lists active resource groups. More... | |
bool | ActivateResourceGroup (const std::string &group, bool auto_add=false) |
Activates a resource group. More... | |
bool | DeactivateResourceGroup (const std::string &group, bool auto_remove=false) |
Deactivates a resource group. More... | |
bool | ResetResourceGroup (const std::string &group) |
Resets defaults of a resource group. More... | |
bool | ResetAllGroups () |
Resets all resource groups. More... | |
bool | RebuildDB (rebuild_mode_t mode=REBUILD_MODE_QUICK) |
Performs a rebuild of the database. More... | |
bool | SetConfigOption (const std::string &option, const std::string &value) |
Sets a configuartion option. More... | |
bool | GetConfigOption (const std::string &option, std::string &value) |
Sets a configuartion option. More... | |
bool | Update (const std::string &scriptname, std::vector< pair< std::string, std::string > > resources) |
bool | UpdateResources () |
bool | RestoreBackup (const std::vector< pair< string, string > > &resources, const std::vector< std::string > &versions, const std::string &profile) |
bool | RemoveBackup (const std::vector< pair< string, string > > &resources, const std::vector< std::string > &versions, const std::string &profile) |
bool | ListBackups (const std::string &profile, std::vector< backup_info_t > *reslist) |
bool | AddBackup (const std::vector< pair< string, string > > &resources, const std::string &profile) |
bool | Recover (bool rollback=false) |
bool | Commit () |
The whole functionality of SCPM is located in a library called libscpm. The scpm binary you can call from the command line is only a small frontend for it. This document describes the interface of the SCPM library and shows how to use it. The library is written in C++, so you can actually use the library only from C++, although other bindings may be implemented some day.
Most of the member functions return a bool
variable. This indicates the success of the operation. In case anything went wrong you get back false. The global variable scpm_error
holds the apropriate error message.
SCPM | ( | int | options = 0 , |
std::ostream & | info_out = cout , |
||
std::ostream & | hash_out = cout , |
||
std::string | root = "" |
||
) |
options | Global SCPM options (optional) |
info_out | Optional ostream object used for action information output |
hash_out | Optional ostream object used for printing progress hash marks |
root | Optional string holding alternate root dir (maybe broken) |
The constructor takes three optional parameters. The options parameter is an ORed list of options flags. The info_out parameter has to be an existing ostream object on which strings describing the current action is written to (something like Checking for modified resources
). Some actions that may take a longer time have the possibility to print exactly 50 hash marks to the hash_out object.
~SCPM | ( | ) |
Destructor, it saves the SCDB and cleans up stuff. Make sure you don't suppress calling it (e.g. by using exit()
)
bool Enable | ( | bool | force = false | ) |
force | Force reenabling option |
Sets SCPM into enabled status. In case you call SCPM::Enable() the first time (that means, no database is there) the SCPM system gets initialized. This can take a while. You can force re-enabling by setting force to true
(using the global force flag will also work), in that case an existing database gets droppend and everything gets newly initialized.
bool Disable | ( | ) |
Disables SCPM, that means, you can not use it anymore. Nothing gets deleted by calling this function.
bool Active | ( | std::string & | profile | ) |
profile | string to which the profile name gets written to |
This determines the currently active profile.
bool List | ( | std::vector< std::string > & | profiles | ) |
profiles | string vector which gets filled with the profile names |
Generates a list of string with all defined profiles.
bool Add | ( | std::string | profile, |
bool | auto_switch = true |
||
) |
profile | Name of the new profile |
auto_switch | Bool indication whether to auto switch |
Creates a new profile from the current configuration. In case the optional auto_switch variable is set to true, the added profile gets automatically the active one. All possible changes to the old profile get dropped, but you have them in the new active one, of course. It returns true on success, false otherwise.
bool Copy | ( | std::string | source_profile, |
std::string | profile | ||
) |
profile | Name of the new profile |
source_profile | Name of the profile to be used as template |
Creates a new profile by using source_profile as template. It returns true on success, false otherwise.
bool Create | ( | std::string | profile, |
std::string | source_profile | ||
) |
profile | Name of the new profile |
source_profile | Name of the profile to be used as template |
Creates a new profile by using source_profile as template. It returns true on success, false otherwise.
bool Delete | ( | std::string | profile | ) |
profile | The doomed profile |
Erases the given profile from the database and removes its data from the harddisk.
bool Rename | ( | std::string | profile, |
std::string | newprofile | ||
) |
profile | Actual profile name |
newprofile | New Profile name |
Renames a profile. You cannot rename the active or the default profile.
bool Reload | ( | ) |
Does a reload of the active profile. This function is an alias for Switch( active_profile ). FIXME: This is actually broken. The cli frontend implements this actually by calling SCPM::PrepareSwitch and afterwards SCPM::Switch with the current profile as argument. This is basically the same.
bool PrepareSwitch | ( | std::string | profile, |
switch_info_t & | switch_info | ||
) |
profile | The name of profile to switch to |
switch_info | Struct to save switch info in |
This function performs the preparation of the switch to another profile. You need to give an initialized switch_info_t
object, in which the switch information (such as modified resources) gets stored. You have to give exactly that object to SCPM::Switch() (in case you want to perform the switch only, of course).
bool Switch | ( | switch_info_t & | switch_info | ) |
switch_info | The switch_info_t object you called SCPM::PrepareSwitch() with |
Performs the prepared switch to the new profile. That means, it stops services, restores resources from the new profile, and starts resources accordingly.
bool Save | ( | switch_info_t & | switch_info | ) |
switch_info | The switch_info_t object you called SCPM::PrepareSwitch() with |
Saves all modified resource listed in the switch_info_t struct that have the save flag set. In case the save_mode element of the struct is set to save_all
or patch_all
the respective resource does not only get saved to the modified profile but will be saved to all profiles or all profiles get patched so the have the latest change to that resource only. The latter action may fail due to conflicting changes.
bool Modify | ( | std::string | profile, |
std::string | action | ||
) |
profile | Profile that shall be modified |
action | Modify action that should be applied to profile |
NOT YET IMPLEMENTED
bool Set | ( | std::string | command, |
std::string | argument, | ||
std::string | profile = "" |
||
) |
command | Set command |
argument | apropriate parameter for the Set command |
profile | name of the affected profile (optional) |
Actually the Set command offers the possibility to set profile descriptions and profile switch scripts. The description is set by passing description
as command and the description itself as argument. The scripts are set by passing prestart, poststart, prestop, poststop
as command and the script including its path as argument. If you pass -d
as argument the named script gets deleted from the database. If you do not pass a profile name the current profile is asumed.
bool Get | ( | std::string | command, |
std::string & | result, | ||
std::string | profile = "" |
||
) |
command | Get command |
result | string containing the result of the Get command |
profile | name of the affected profile (optional) |
With the Get command you can query that stuff you can set using the SCPM::Set command. Look there to find out what you can set/get.
bool Status | ( | scpm_status_t & | status | ) |
status | Existing scpm_status_t object which gets filled out |
The Status function collects some status information and writes them in the passed scpm_status_t object. Look at the struct members for details.
bool ShowChanges | ( | std::ostream & | output, |
std::string | resource_type, | ||
std::string | resource_name, | ||
bool | backup = false , |
||
string | version = "" |
||
) |
output | Stream object on which the changes get written |
resource_type | Resource type of the resource to diff |
resource_name | Resource name of the resource to diff |
backup | Optional bool defining whether diff should be made using backup |
With ShowChanges you can let SCPM determine the changes of a Resource between its current state and its state saved in the active profile. The changes will be written on the passed stream object. If backup is set to true, the latest backup of the Resource is being used for diffing.
bool SetResourceSet | ( | std::string | set | ) |
set | Name of the resource set |
This function sets the resource set set
as the active one. Pass an empty string in case you want to switch to resource set less mode.
bool GetResourceSet | ( | std::string & | set | ) |
set | string to write set name into |
This function determines the active resource set (if any) and writes its name into the passed set
variable.
bool ListResourceSets | ( | std::vector< std::string > & | predefined, |
std::vector< std::string > & | individual | ||
) |
predefined | vector of string predefined sets get written to |
individual | vector of string user defined sets get written to |
ListResourceSets determines all defined resource sets and writes them into the passed string vectors. The predefined resource sets come from the SCPM package itself, the individual resource sets are user defined ones. It is possible to have predefined and individual resource sets with the same name. In that case the individual one is used.
bool CopyResourceSet | ( | std::string | set, |
std::string | newset | ||
) |
set | name of the source set |
newset | name of the set to be created |
This copies a resource set. The newly created resource set newset
is always an individual resource set. If set
is an existing individual set, that one gets copied, otherwise the predefined gets copied. It is also legitimate that set
and newset
are equal, it only means that an individual resource set with the same name as the predefined one gets created.
bool DeleteResourceSet | ( | std::string | set | ) |
set | name of the resource set |
Deletes the given resource set. This has to be an individual one, you cannot remove predefined resource sets.
bool ListResourceGroups | ( | std::vector< resource_group_t > & | groups | ) |
groups | Reference to a vector<resource_group_t> variable |
This function determines all installed resource groups and writes them into the group refernence vector.
bool SetResourceGroup | ( | const std::string & | name, |
const std::vector< resource_entry_t > & | group, | ||
const std::string & | description | ||
) |
name | String containing the group name |
group | vector of resource_entry_t variables representing the resources |
description | String containing a description for this group |
Using SetResourceGroup you can modify an existing group or create new ones. You need to create a vecor of resource_entry_t variables defining the resources the group should have. In case the resource group exists and you supply exactly the resources the original group that came with the SCPM installation, the group gets the user_modified
and user_defined
flags reset to false. The resource_group_t description.
bool DeleteResourceGroup | ( | const std::string & | group | ) |
group | String nameing the doomed group |
This removes a user defined or user modified resource group. Original resource groups won't get deleted from the system.
bool RenameResourceGroup | ( | const std::string & | group, |
const std::string & | newgroup | ||
) |
group | String containing the name of the group to be renamed |
newgroup | New name of the group |
This renames a user defined resource group. In case the group was active, the active group list gets updated, too.
bool SetActiveResourceGroups | ( | const std::vector< std::string > & | groups | ) |
groups | List of groups |
This function marks the groups listed in groups
as the active ones. That means, the resources of those groups define the resources handled by SCPM. It is useful to update the SCDB afterwards by calling SCPM::RebuildDB.
bool GetActiveResourceGroups | ( | std::vector< std::string > & | groups | ) |
groups | Reference of the destination string vector |
This generates a list of active resource groups and writes them into groups
.
bool ActivateResourceGroup | ( | const std::string & | group, |
bool | auto_add = false |
||
) |
group | Name of the group |
auto_add | Bool indicating whether auto add is wanted |
This adds the wanted resource group to the active groups list. The group must exists, of course, adding an already active group does not harm (it generates a warning, though). In case {auto_add} is set, the resources of this group get automatically added to the database and all profiles.
bool DeactivateResourceGroup | ( | const std::string & | group, |
bool | auto_remove = false |
||
) |
group | Name of the group |
auto_remove | Bool indicating whether auto remove is wanted |
This removes the given resource group from the active groups list. The group must exists, of course, deactivating an already deactive group does not harm (it generates a warning, though). In case {auto_add} is set, the resources of this group get automatically removed from the database and all profiles.
bool ResetResourceGroup | ( | const std::string & | group | ) |
group | Name of the group |
Resets a resource group to its factory defaults. This does not work with user defined groups.
bool ResetAllGroups | ( | ) |
Resets all resource groups to its defaults, removes user defined resource groups, and restores original active groups list.
bool RebuildDB | ( | rebuild_mode_t | mode = REBUILD_MODE_QUICK | ) |
mode | Optional rebuild mode specification (not ready yet) |
This brings your SCDB up to date. More detailed that means all resources, that do not exist in your system but in the database get removed, and new resources which are not listed in the database get added. The current state of all new resources get saved to all profiles. You may want to call this function after a resource set change, otherwise you will get a quite long list of modified resources on the next switch. Please note: this may daramtically modify your existing database! It may even remove data!
bool SetConfigOption | ( | const std::string & | option, |
const std::string & | value | ||
) |
option | Name of the option |
value | Value to set the option to |
SetConfigOption is a simple interface to the configuration file (usually /etc/scpm.conf). option
can be one of DEBUG VERBOSE BOOTMODE SWITCHMODE. Valid values are yes</am> or no for DEBUG and VERBOSE, and skip, force, or normal for BOOTMODE and SWITCHMODE.
bool GetConfigOption | ( | const std::string & | option, |
std::string & | value | ||
) |
option | Name of the option |
value | string to put the wanted value in |
GetConfigOption is a simple interface to the configuration file (usually /etc/scpm.conf). option
can be one of DEBUG VERBOSE BOOTMODE SWITCHMODE. Depending on the settings value
becomes yes</am> or no for DEBUG and VERBOSE, and skip, force, or normal for BOOTMODE and SWITCHMODE.