SCPM interface  1.0
Classes | Public Member Functions | List of all members
SCPM Class Reference

SCPM interface class. More...

Public Member Functions

 SCPM (int options=0, std::ostream &info_out=std::cout, std::ostream &hash_out=std::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, std::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< std::pair< std::string, std::string > > resources)
 
bool UpdateResources ()
 
bool RestoreBackup (const std::vector< std::pair< std::string, std::string > > &resources, const std::vector< std::string > &versions, const std::string &profile)
 
bool RemoveBackup (const std::vector< std::pair< std::string, std::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< std::pair< std::string, std::string > > &resources, const std::string &profile)
 
bool Recover (bool rollback=false)
 
bool Commit ()
 

Detailed Description

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.

Constructor & Destructor Documentation

SCPM ( int  options = 0,
std::ostream &  info_out = std::cout,
std::ostream &  hash_out = std::cout,
std::string  root = "" 
)
Parameters
optionsGlobal SCPM options (optional)
info_outOptional ostream object used for action information output
hash_outOptional ostream object used for printing progress hash marks
rootOptional 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() )

Member Function Documentation

bool Enable ( bool  force = false)
Parameters
forceForce reenabling option
Returns
success

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 ( )
Returns
success

Disables SCPM, that means, you can not use it anymore. Nothing gets deleted by calling this function.

bool Active ( std::string &  profile)
Parameters
profilestring to which the profile name gets written to
Returns
success

This determines the currently active profile.

bool List ( std::vector< std::string > &  profiles)
Parameters
profilesstring vector which gets filled with the profile names
Returns
success

Generates a list of string with all defined profiles.

bool Add ( std::string  profile,
bool  auto_switch = true 
)
Parameters
profileName of the new profile
auto_switchBool indication whether to auto switch
Returns
success

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 
)
Parameters
profileName of the new profile
source_profileName of the profile to be used as template
Returns
success

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 
)
Parameters
profileName of the new profile
source_profileName of the profile to be used as template
Returns
success

Creates a new profile by using source_profile as template. It returns true on success, false otherwise.

bool Delete ( std::string  profile)
Parameters
profileThe doomed profile
Returns
success

Erases the given profile from the database and removes its data from the harddisk.

bool Rename ( std::string  profile,
std::string  newprofile 
)
Parameters
profileActual profile name
newprofileNew Profile name
Returns
success

Renames a profile. You cannot rename the active or the default profile.

bool Reload ( )
Returns
success

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 
)
Parameters
profileThe name of profile to switch to
switch_infoStruct to save switch info in
Returns
success

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)
Parameters
switch_infoThe switch_info_t object you called SCPM::PrepareSwitch() with
Returns
success

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)
Parameters
switch_infoThe switch_info_t object you called SCPM::PrepareSwitch() with
Returns
success

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 
)
Parameters
profileProfile that shall be modified
actionModify action that should be applied to profile
Returns
success

NOT YET IMPLEMENTED

bool Set ( std::string  command,
std::string  argument,
std::string  profile = "" 
)
Parameters
commandSet command
argumentapropriate parameter for the Set command
profilename of the affected profile (optional)
Returns
success

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 = "" 
)
Parameters
commandGet command
resultstring containing the result of the Get command
profilename of the affected profile (optional)
Returns
success

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)
Parameters
statusExisting scpm_status_t object which gets filled out
Returns
success

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,
std::string  version = "" 
)
Parameters
outputStream object on which the changes get written
resource_typeResource type of the resource to diff
resource_nameResource name of the resource to diff
backupOptional bool defining whether diff should be made using backup
Returns
success

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)
Parameters
setName of the resource set
Returns
success

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)
Parameters
setstring to write set name into
Returns
success

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 
)
Parameters
predefinedvector of string predefined sets get written to
individualvector of string user defined sets get written to
Returns
success

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 
)
Parameters
setname of the source set
newsetname of the set to be created
Returns
success

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)
Parameters
setname of the resource set
Returns
success

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)
Parameters
groupsReference to a vector<resource_group_t> variable
Returns
success

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 
)
Parameters
nameString containing the group name
groupvector of resource_entry_t variables representing the resources
descriptionString containing a description for this group
Returns
success

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)
Parameters
groupString nameing the doomed group
Returns
success

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 
)
Parameters
groupString containing the name of the group to be renamed
newgroupNew name of the group
Returns
success

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)
Parameters
groupsList of groups
Returns
success

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)
Parameters
groupsReference of the destination string vector
Returns
success

This generates a list of active resource groups and writes them into groups.

bool ActivateResourceGroup ( const std::string &  group,
bool  auto_add = false 
)
Parameters
groupName of the group
auto_addBool indicating whether auto add is wanted
Returns
success

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 
)
Parameters
groupName of the group
auto_removeBool indicating whether auto remove is wanted
Returns
success

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)
Parameters
groupName of the group
Returns
success

Resets a resource group to its factory defaults. This does not work with user defined groups.

bool ResetAllGroups ( )
Returns
success

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)
Parameters
modeOptional rebuild mode specification (not ready yet)
Returns
success

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 
)
Parameters
optionName of the option
valueValue to set the option to
Returns
success

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 
)
Parameters
optionName of the option
valuestring to put the wanted value in
Returns
success

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.


The documentation for this class was generated from the following files:

SCPM interface description - 2002,2003 SuSE Linux AG