UserSession

UserSession Methods

The UserSession class is one of the main access points to the API functionality.

A UserSession represents a user session. A new user session is started by calling TimetableManager::StartSession(), which returns a UserSession object. The UserSession object can be used to create course loads using the NewCourseLoad() and OpenCourseLoad() methods.

The user session ends when the returned UserSession object is destructed. Note that UserSession is moveable but not copyable; user code can move it around as desired.

Here is an outline of the UserSession class:

class UserSession
{
public:
    // API functions for creating course loads
    CourseLoad NewCourseLoad(function<void(FileSaveStatus)> file_save_status_observer = function<void(FileSaveStatus)>());
    CourseLoad OpenCourseLoad(const string& filename, function<void(FileSaveStatus)> file_save_status_observer = function<void(FileSaveStatus)>());
};

UserSession Methods

NewCourseLoad

CourseLoad UserSession::NewCourseLoad(function<void(FileSaveStatus)> file_save_status_observer = function<void(FileSaveStatus)>());

Create a new, empty course load.

The state of the created course load will be course_load_state::empty.

See OpenCourseLoad() for an explanation of the optional file_save_status_observer argument.

OpenCourseLoad

CourseLoad UserSession::OpenCourseLoad(const string& filename, function<void(FileSaveStatus)> file_save_status_observer = function<void(FileSaveStatus)>());

Create a new course load, loaded from the course load file at filename. filename should be a file created using CourseLoad::Save().

The state of the created course load will be course_load_state::courses_selected. The set of activity configurations available via GetConfigCount() and GetConfig() will be precisely those configurations which were specified in the file. Note that this is likely to be different from the set of activity configurations that would be available after selecting the courses specified in the file via SelectCourses(), which are the configurations generated by the configuration generation algorithm (see Activity Configuration Fine Points for details). If the set of configurations generated by the configuration generation algorithm is desired, call GenerateConfigurations() after opening the course load.

The optional file_save_status_observer argument (also present in NewCourseLoad()) is a callback function that will be called whenever the file save status of the created course load changes. The callback can be any function or function object callable with a FileSaveStatus argument.

The file save status consists of the values returned by GetFileName() and IsUpToDate(). Whenever one of these values changes, the callback function is called with a FileSaveStatus object representing the new values.

Actions that can cause these values to change include creating a course load with OpenCourseLoad() (sets the filename to the name of the file from which the course load was loaded), Save() (changes 'up to date' flag to true, sets filename if it was empty before), and any function that modifies the course load (changes 'up to date' flag to false).

Technically, this callback does not provide any extra functionality that cannot be obtained using other API functions - for example if the file save status changes because OpenCourseLoad() was called, the API client already knows that because they called OpenCourseLoad()! However, this function frees the API client from the burden of having to keep track of exactly which API functions change the file save status.