Non session manager client implementation. More...

#include <NsmClient.h>

Inheritance diagram for NsmClient:

Public Member Functions
	~NsmClient ()
	Destructor.

void	createInitialClient ()
	Actual setup, initialization, and registration of the NSM client.

bool	getIsNewSession () const

QString	getSessionFolderPath () const

bool	getUnderSessionManagement () const

void	sendDirtyState (const bool isDirty)
	Informs the NSM server whether the current H2Core::Song is modified or not.

void	setIsNewSession (bool bNew)

void	setSessionFolderPath (const QString &sPath)

void	shutdown ()
	Causes the NSM client to not process events anymore.

Public Member Functions inherited from Object< NsmClient >
	Object ()

	Object (const Object< NsmClient > &other)

Public Member Functions inherited from Base
	Base ()

	Base (const Base &other)

virtual const char *	class_name () const

void	logBacktrace () const
	Print the current stack at point into the debug log.

void	Print (bool bShort=true) const
	Prints content of toQString() via DEBUGLOG.

virtual QString	toQString (const QString &sPrefix="", bool bShort=true) const
	Formatted string version for debugging purposes.

Static Public Member Functions
static void	create_instance ()
	If __instance equals nullptr, a new NsmClient singleton will be created and stored in it.

static int	dereferenceDrumkit (std::shared_ptr< H2Core::Song > pSong)
	Replaces a path in Song::m_sLastLoadedDrumkitPath pointing to the session folder with one pointing to the corresponding kit in the data folder.

static NsmClient *	get_instance ()

static void	linkDrumkit (std::shared_ptr< H2Core::Song > pSong)
	Responsible for linking a drumkit on user or system level into the session folder and updating all corresponding references in pSong.

static void	loadDrumkit ()
	Checks whether there is a drumkit present in the session folder and loads it into the H2Core::SoundLibraryDatabase.

static void	printError (const QString &msg)
	Custom function to print a colored error message.

static void	printMessage (const QString &msg)
	Custom function to print a colored message.

static void	replaceDrumkitPath (std::shared_ptr< H2Core::Song > pSong, const QString &sDrumkitPath)
	Replaces @H2Core::Song::m_sLastLoadedDrumkitPath as well as all @H2Core::Instrument::__drumkit_path bearing the same value in pSong with sDrumkitPath.

Static Public Member Functions inherited from Base
static const char *	_class_name ()
	return the class name

static QString	base_clock (const QString &sMsg)
	Measures the current time and stores it in __last_clock.

static QString	base_clock_in (const QString &sMsg)

static int	bootstrap (Logger *logger, bool count=false)
	must be called before any Object instantiation !

static bool	count_active ()

static int	getAliveObjectCount ()

static object_map_t	getObjectMap ()

static Logger *	logger ()
	return the logger instance

static int	objects_count ()

static void	printObjectMapDiff (object_map_t map)
	Creates the difference between a snapshot of the object map and its current state and prints it to std::cout.

static void	set_count (bool flag)
	enable/disable class instances counting

static void	write_objects_map_to (std::ostream &out, object_map_t *map=nullptr)
	output the full objects map to a given ostream

static void	write_objects_map_to_cerr ()
	output objects map to stderr

Data Fields
pthread_t	m_NsmThread
	Thread the NSM client will run in.

Static Public Attributes
static NsmClient *	__instance = nullptr
	Object holding the current NsmClient singleton.

Static Public Attributes inherited from Base
static QString	sPrintIndention = " "
	String used to format the debugging string output of some core classes.

Private Member Functions
	NsmClient ()
	Private constructor to allow construction only via create_instance().

Static Private Member Functions
static void	copyPreferences (const char *name)
	Part of OpenCallback() responsible for copying and loading the preferences.

static int	OpenCallback (const char name, const char displayName, const char clientID, char outMsg, void userData)
	Callback function for the NSM server to tell Hydrogen to open a H2Core::Song.

static void *	ProcessEvent (void *data)
	Event handling function of the NSM client.

static int	SaveCallback (char *outMsg, void userData)
	Callback function for the NSM server to tell Hydrogen to save the current session.

Private Attributes
bool	m_bIsNewSession
	Indicates whether a song file was already found in the session folder and successfully loaded or the session was initialized with an empty song.

bool	m_bUnderSessionManagement
	To determine whether Hydrogen is under NON session management, it is not sufficient to check whether the NSM_URL environmental variable is set but also whether the NSM server did respond to the announce message appropriately.

nsm_client_t *	m_pNsm
	Stores the current instance of the NSM client.

QString	m_sSessionFolderPath
	Folder all the content of the current session will be stored in.

Static Private Attributes
static bool	bNsmShutdown = false
	Indicates whether the NsmClient::NsmProcessEvent() function should continue processing events.

Additional Inherited Members
Protected Member Functions inherited from Object< NsmClient >
	~Object ()

Protected Member Functions inherited from Base
	~Base ()

Static Protected Member Functions inherited from Base
static void	registerClass (const char name, const atomic_obj_cpt_t counters)

Static Protected Attributes inherited from Base
static bool	__count = false
	should we count class instances

static timeval	__last_clock = { 0, 0 }

static Logger *	__logger = nullptr

static bool	bLogColors = true

Detailed Description

Non session manager client implementation.

Non session management (NSM) is the name for both a standard/API allowing for a reproducible, multi-application session handling in Linux systems as well as for the actual application - the non-session-manager - implementing it.

Hydrogen is compliant with the standard, sends dirty flag to the NSM server to indicate unsaved changes, and is able to switch between different sessions without restarting the entire application. However, Hydrogen does use several files to store all options the user is able to customize and not all of them are stored inside the folder provided by the NSM server. Both the song and a custom copy of the preferences will be stored in the session folder. But the drumkit used in the song will only be linked into it.

Author: Sebastian Moors

Definition at line 57 of file NsmClient.h.

Constructor & Destructor Documentation

◆ ~NsmClient()

~NsmClient ( )

Destructor.

Definition at line 58 of file NsmClient.cpp.

◆ NsmClient()

NsmClient ( )

private

Private constructor to allow construction only via create_instance().

Definition at line 49 of file NsmClient.cpp.

Member Function Documentation

◆ copyPreferences()

void copyPreferences ( const char * name )

staticprivate

Part of OpenCallback() responsible for copying and loading the preferences.

Then it uses H2Core::Preferences::loadPreferences() in combination with H2Core::Filesystem::setPreferencesOverwritePath() to load the configurations specific to the session. If none hydrogen.conf file (see USR_CONFIG) is present in the session folder, the one of the user is used to create one instead. Next, a H2Core::EVENT_UPDATE_PREFERENCES event is created to trigger to ensure the GUI reflects the changes in configuration.

Parameters

name	Absolute path to the session folder.

Definition at line 176 of file NsmClient.cpp.

◆ create_instance()

void create_instance ( )

static

If __instance equals nullptr, a new NsmClient singleton will be created and stored in it.

It is called in H2Core::Hydrogen::create_instance().

Definition at line 63 of file NsmClient.cpp.

◆ createInitialClient()

void createInitialClient ( )

Actual setup, initialization, and registration of the NSM client.

It create a new NSM client, sets the callback functions nsm_open_cb() and nsm_save_cb(), and registers the newly created client with the NSM server. It also indicates that Hydrogen does support the two NSM options "dirty" and "switch", allowing the server to notice whenever there are unsaved changes and to switch between Songs without restarting the whole application.

This function will performs action if a NSM server is already running. This will be indicated by a set environmental variable called "NSM_URL". However, this is condition is not sufficient and only after receiving a certain response - handled by the NSM API inside the nsm_free() function - to the announce message sent by Hydrogen, the client can truly be considered under session management. This particular state will be indicated by setting m_bUnderSessionManagement to true.

Definition at line 538 of file NsmClient.cpp.

◆ dereferenceDrumkit()

int dereferenceDrumkit ( std::shared_ptr< H2Core::Song > pSong )

static

Replaces a path in Song::m_sLastLoadedDrumkitPath pointing to the session folder with one pointing to the corresponding kit in the data folder.

In case the session drumkit does not exist at neither system nor user level, Song::m_sLastLoadedDrumkitPath will be replaced by an empty string.

Returns: 0 : success. -1 : general error, -2 : drumkit is present as directory in session folder. But a drumkit holding the same name couldn't be found on the system.

Definition at line 354 of file NsmClient.cpp.

◆ get_instance()

static NsmClient * get_instance ( )

inlinestatic

Returns: a pointer to the current NsmClient singleton stored in __instance.

Definition at line 84 of file NsmClient.h.

◆ getIsNewSession()

bool getIsNewSession ( ) const

inline

Definition at line 342 of file NsmClient.h.

◆ getSessionFolderPath()

QString getSessionFolderPath ( ) const

inline

Definition at line 335 of file NsmClient.h.

◆ getUnderSessionManagement()

bool getUnderSessionManagement ( ) const

inline

Returns: m_bUnderSessionManagement

Definition at line 331 of file NsmClient.h.

◆ linkDrumkit()

void linkDrumkit ( std::shared_ptr< H2Core::Song > pSong )

static

Responsible for linking a drumkit on user or system level into the session folder and updating all corresponding references in pSong.

If the session was archived, the symbolic link had been replaced by a folder containing the samples. In such an occasion the samples located in the folder will be loaded. This ensure portability of Hydrogen within a session regardless of the local drumkits present in the user's home.

Parameters

pSong @H2Core::Song containing references to global drumkit.

Definition at line 242 of file NsmClient.cpp.

◆ loadDrumkit()

void loadDrumkit ( )

static

Checks whether there is a drumkit present in the session folder and loads it into the H2Core::SoundLibraryDatabase.

Definition at line 219 of file NsmClient.cpp.

◆ OpenCallback()

int OpenCallback	(	const char *	name,
		const char *	displayName,
		const char *	clientID,
		char **	outMsg,
		void *	userData )

staticprivate

Callback function for the NSM server to tell Hydrogen to open a H2Core::Song.

It also handles the switching between sessions by loading the H2Core::Song, the H2Core::Preferences, and the H2Core::Drumkit of the new session without the need to restart the whole application.

It is important to know that the core part of H2Core::Hydrogen is already initialized when this function is called, but the GUI isn't.

All files and symbolic links will be stored in a folder created by this function and named according to name.

Parameters

name	Unique name corresponding to the current session. A folder using this particular name will be created, which will contain the H2Core::Song - using name appended by ".h2song" as file name -, the local H2Core::Preferences, and a symbolic link to the H2Core::Drumkit in use.
displayName	Name the application will be presented with by the NSM server. It is determined in NsmClient::createInitialClient() and set to "Hydrogen".
clientID	Unique prefix also present in name, "nJKUV". It will be stored in H2Core::Preferences::m_sNsmClientId to provide it as a suffix when creating a JACK client in H2Core::JackAudioDriver::init().
outMsg	Unused argument. Kept for API compatibility.
userData	Unused argument. Kept for API compatibility.

Returns

ERR_OK (0): indicating that everything worked fine.
ERR_LAUNCH_FAILED (-4): If no clientID provided, the H2Core::Song corresponding to the file path of a concatenation of name and ".h2song" could not be loaded, or the Action could not be provided to MidiActionManager::handleAction().
ERR_NOT_NOW (-8): If the H2Core::Preferences instance was not initialized.

See also: copyPreferences(); linkDrumkit()

Definition at line 70 of file NsmClient.cpp.

◆ printError()

void printError ( const QString & msg )

static

Custom function to print a colored error message.

Since the OpenCallback() and SaveCallback() functions will be invoked by the NSM server and not by Hydrogen itself, we can not use our usual log macros in there.

Parameters

msg	String to print to std::cerr.

Definition at line 469 of file NsmClient.cpp.

◆ printMessage()

void printMessage ( const QString & msg )

static

Custom function to print a colored message.

Since the OpenCallback() and SaveCallback() functions will be invoked by the NSM server and not by Hydrogen itself, we can not use our usual log macros in there.

Parameters

msg	String to print to std::cout.

Definition at line 487 of file NsmClient.cpp.

◆ ProcessEvent()

void * ProcessEvent ( void * data )

staticprivate

Event handling function of the NSM client.

The event handling can be deactivated by calling NsmClient::shutdown() which is setting bNsmShutdown to true.

Parameters

data	NSM client created in NsmClient::createInitialClient().

Definition at line 523 of file NsmClient.cpp.

◆ replaceDrumkitPath()

void replaceDrumkitPath	(	std::shared_ptr< H2Core::Song >	pSong,
		const QString &	sDrumkitPath )

static

Replaces @H2Core::Song::m_sLastLoadedDrumkitPath as well as all @H2Core::Instrument::__drumkit_path bearing the same value in pSong with sDrumkitPath.

This is required when telling a H2Core::Song to use the drumkit linked/found in the session folder instead of its counterpart in the user's or system's drumkit data folder or the over way around when exporting the song of the session.

Definition at line 429 of file NsmClient.cpp.

◆ SaveCallback()

int SaveCallback	(	char **	outMsg,
		void *	userData )

staticprivate

Callback function for the NSM server to tell Hydrogen to save the current session.

Parameters

outMsg	Unused argument. Kept for API compatibility.
userData	Unused argument. Kept for API compatibility.

Returns: 0 - actually ERR_OK defined in the NSM API - indicating that everything worked fine.

Definition at line 505 of file NsmClient.cpp.

◆ sendDirtyState()

void sendDirtyState ( const bool isDirty )

Informs the NSM server whether the current H2Core::Song is modified or not.

This function is triggered within H2Core::Song::setIsModified().

Parameters

isDirty true, if the current H2Core::Song was modified, and false if it wasn't

Definition at line 618 of file NsmClient.cpp.

◆ setIsNewSession()

void setIsNewSession ( bool bNew )

inline

Definition at line 345 of file NsmClient.h.

◆ setSessionFolderPath()

void setSessionFolderPath ( const QString & sPath )

inline

Definition at line 338 of file NsmClient.h.

◆ shutdown()

void shutdown ( )

Causes the NSM client to not process events anymore.

Sets bNsmShutdown to true.

Definition at line 533 of file NsmClient.cpp.

Field Documentation

◆ __instance

NsmClient * __instance = nullptr

static

Object holding the current NsmClient singleton.

It is initialized with nullptr, set with create_instance(), and accessed with get_instance().

Definition at line 67 of file NsmClient.h.

◆ bNsmShutdown

bool bNsmShutdown = false

staticprivate

Indicates whether the NsmClient::NsmProcessEvent() function should continue processing events.

Set to true in NsmClient::shutdown().

Definition at line 328 of file NsmClient.h.

◆ m_bIsNewSession

bool m_bIsNewSession

private

Indicates whether a song file was already found in the session folder and successfully loaded or the session was initialized with an empty song.

Definition at line 235 of file NsmClient.h.

◆ m_bUnderSessionManagement

bool m_bUnderSessionManagement

private

To determine whether Hydrogen is under NON session management, it is not sufficient to check whether the NSM_URL environmental variable is set but also whether the NSM server did respond to the announce message appropriately.

Therefore, createInitialClient() has to be called first.

Definition at line 220 of file NsmClient.h.

◆ m_NsmThread

pthread_t m_NsmThread

Thread the NSM client will run in.

Definition at line 71 of file NsmClient.h.

◆ m_pNsm

nsm_client_t* m_pNsm

private

Stores the current instance of the NSM client.

Definition at line 211 of file NsmClient.h.

◆ m_sSessionFolderPath

QString m_sSessionFolderPath

private

Folder all the content of the current session will be stored in.

Set at the beginning of each session in NsmClient::OpenCallback().

Definition at line 228 of file NsmClient.h.

Public Member Functions

Static Public Member Functions

Data Fields

Static Public Attributes

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ ~NsmClient()

◆ NsmClient()

Member Function Documentation

◆ copyPreferences()

◆ create_instance()

◆ createInitialClient()

◆ dereferenceDrumkit()

◆ get_instance()

◆ getIsNewSession()

◆ getSessionFolderPath()

◆ getUnderSessionManagement()

◆ linkDrumkit()

◆ loadDrumkit()

◆ OpenCallback()

◆ printError()

◆ printMessage()

◆ ProcessEvent()

◆ replaceDrumkitPath()

◆ SaveCallback()

◆ sendDirtyState()

◆ setIsNewSession()

◆ setSessionFolderPath()

◆ shutdown()

Field Documentation

◆ __instance

◆ bNsmShutdown

◆ m_bIsNewSession

◆ m_bUnderSessionManagement

◆ m_NsmThread

◆ m_pNsm

◆ m_sSessionFolderPath