The Media::Manager contains a collection of all sources. More...

#include <mediamanager.h>

Inheritance diagram for Media::Manager:

[legend]

Collaboration diagram for Media::Manager:

[legend]

Classes
class	Callbacks
	Notifications/Delegates provided by the media manager. More...

Public Types
using	base_container = std::unordered_map< Source::SerialNumber, Source *const >

Public Types inherited from Media::Source
typedef unsigned long	SerialNumber

Public Types inherited from Ownership
enum class	Type { DISOWNED , PRIVATE , SHARED , PUBLISHED , PUBLIC }
	Access levels for an object. More...

enum class	Action { SEE , USE , READ , ALTER }
	Access actions for an object. More...

Public Types inherited from PianodInterpreter
using	HelpList = PianodDispatcher::HelpList

Public Member Functions
virtual const Parsnip::Parser::Definitions &	getParserDefinitions () override
	Retrieve the parser definitions handled by the interpreter. More...

	Manager (void)

	~Manager (void)

Source *const	get (const SerialNumber serial) const
	Retrieve a source by serial number. More...

Source *const	get (const std::string &type, const std::string &ident) const
	Retrieve a source by type and ID. More...

Source *const	add (SourcePtr &&src)
	Add a source. More...

Media::Source *const	getSource (const Parsnip::Data &options)
	Get a source commands predicate (either by ID or type and name). More...

ResponseCollector	add (SourcePtr &&src, PianodConnection &conn)
	Interactively add a source. More...

bool	erase (Source *const source)
	Remove a source. More...

void	resetLockout ()
	Reset a temporary lockout so playback can be attempted immediately. More...

bool	areSourcesReady () const

bool	areSourcesPending () const

SourceList	getReadySources () const

virtual bool	canExpandToAllSongs (void) const override
	Indicate if arbitrary tracks can be requested from this source. More...

virtual bool	flush (void) override
	Ask all the sources to persist any data. More...

virtual float	periodic (void) override
	Perform periodic activities and remove sources that deferred removal. More...

virtual const char *	kind (void) const override
	A unique string identifying the type of source. More...

virtual PlaylistList	getPlaylists (const Filter &filter=Filter::All) override
	Retrieve the source's playlists. More...

virtual MusicThingie *	getAnythingById (const SplitId &id) override
	Retrieve a playlist, song, album or artist by ID. More...

MusicThingie *	getAnythingById (const std::string &id)
	Retrieve a playlist, song, album or artist by ID. More...

virtual PianodPlaylist *	getMixPlaylist (void) override

virtual PianodPlaylist *	getEverythingPlaylist (void) override

virtual PianodPlaylist *	getTransientPlaylist (const Filter &criteria) override
	If any source has the necessary capabilities, and some items match the criteria, then stash the criteria (needed when random songs are later requested) and return the transient playlist. More...

virtual Player *	getPlayer (const AudioSettings &audio, PianodSong *song) override
	Play a song, gathering statistics and substituting proxies if enabled. More...

virtual SongList	getRandomSongs (PianodPlaylist *playlist, const UserList &users, SelectionMethod selectionMethod) override

virtual ThingieList	getSuggestions (const Filter &filter, SearchRange where) override

virtual PianodPlaylist *	createPlaylist (const char name, MusicThingie::Type type, MusicThingie from) override
	Create a playlist using a thingie as an initial seed. More...

virtual PianodPlaylist *	createPlaylist (const char *name, const Filter &filter) override
	Create a playlist using a filter. More...

virtual MusicThingie *	getSuggestion (MusicThingie *thing, MusicThingie::Type type, SearchRange where) override
	Retrieve an equivalent or related album, artist, or song from a source. More...

Public Member Functions inherited from Media::Source
	Source (SourceParameters *params)
	Initialize the source. More...

virtual	~Source (void)
	Destroy a source. More...

void	persist (void) const
	Persist source parameters, attaching them to the owner's user data. More...

bool	isReady (void) const
	Check if the source is online. More...

SerialNumber	serialNumber (void) const
	Get the source's unique number assigned by the media manager. More...

const Statistics &	getStatistics () const
	Retrieve playback statistics about the source. More...

const bool	isLockedOut () const
	Check if source is temporarily locked out due to repeated failures. More...

Parsnip::Data	serializeIdentity () const

std::string	identify () const
	Identify the unique source. More...

void	alert (RESPONSE_CODE message) const
	Send an alert notification regarding this source. More...

void	alert (RESPONSE_CODE message, const char detail, const char reason=nullptr) const
	Send an alert notification regarding this source. More...

void	reportStatus (const char *detail) const
	Send a status notification regarding this source. More...

void	reportStatus (const std::string &detail) const

const std::string &	name (void) const
	Get the name of this source. More...

std::string	key (void) const
	Key is a combination of kind and name. More...

std::string	filename (void) const
	Provide a filename for persisting the source's data. More...

virtual bool	requireNameForCreatePlaylist (void) const
	Indicate if a name is required when creating a playlist. More...

PianodPlaylist *	getPlaylistByName (const char *name)
	Retrieve a playlist by name. More...

void	playbackComplete (bool played, bool successfully)
	Update playback statistics. More...

virtual void	playbackProblem (void)

MusicThingie *	getSuggestion (MusicThingie *thing, SearchRange where=SearchRange::SHALLOW)
	Retrieve an equivalent album, artist, or song from a source. More...

Public Member Functions inherited from PrimaryOwnership
	PrimaryOwnership (void)
	Default construct ownership: No owner, private access. More...

	PrimaryOwnership (Type rule, User *owner=nullptr)
	Construct ownership. More...

	~PrimaryOwnership (void)

void	abandon (void)
	Disassociate ownership from any owner, and mark as disowned. More...

void	abandon (const User *user)
	Conditionally dissociate ownership. More...

User *	getOwner (void) const

bool	isOwned (void) const

const std::string &	ownerName (void) const
	Retrieve the name of the owner. More...

virtual bool	isOwnedBy (const User *user) const override
	Check if we are owned by a user. More...

virtual bool	hasPermission (const User *user, Action action) const override
	Determine if a user has permission to use this item in some manner. More...

Public Member Functions inherited from Ownership
bool	isVisibleBy (const User *user) const

bool	isUsableBy (const User *user) const

bool	isDecendableBy (const User *user) const

bool	isReadableBy (const User *user) const

bool	isEditableBy (const User *user) const

Public Member Functions inherited from PianodInterpreter
virtual void	registerInterpreter (PianodDispatcher &dispatcher)
	Register the interpreter with a dispatcher. More...

const HelpList	getHelp (const std::vector< std::string > &search, std::set< std::string > *option_parsers)
	Search the interpreter's definitions for any definitions matching search criteria. More...

Static Public Member Functions
static const Parsnip::Parser::Definitions &	parser_definitions ()

static const Parsnip::OptionParser::Definitions &	source_id_parser_definitions ()

static const PianodSchema::CommandIds &	json_request_names (PianodSchema &schema)
	Retrieve names for our JSON requests, and make schema revisions. More...

Static Public Member Functions inherited from PianodInterpreter
static bool	optionIs (const Parsnip::Data &options, const char name, const char expected)
	Check if a string value exists and is case-blind equal to a particular value. More...

template<typename ValueType , typename LookupType >
static ValueType	optionalValue (const Parsnip::Data &options, const char *name, const LookupType &lookup, const ValueType default_value)
	Retrieve the ID of a string value. More...

Public Attributes
CallbackManager< Manager, Callbacks >	callback
	Callback manager provides API for registering and removing callbacks. More...

Private Types
using	SourceList = std::vector< Source * >

Private Member Functions
void	handleSourceStateChange (Source *const source)
	Respond to a source's state change. More...

void	redirectingStatusHandler (RESPONSE_CODE status, const char *detail)
	Handle an alert by passing it to callbacks. More...

SourceList	getRealSources () const
	Get all sources (excluding the manager itself). More...

SourceList	getRealSources (Source::State state) const
	Get sources (excluding the manager itself) in a given state. More...

bool	areSourcesInState (Source::State state) const
	Check if there are any sources in a given state. More...

virtual bool	authorizedCommand (Parsnip::Parser::CommandId command, PianodConnection &conn) override
	Check whether a command is authorized. More...

virtual ResponseCollector	handleCommand (Parsnip::Parser::CommandId command, const Parsnip::Data &options, PianodConnection &conn) override
	Command handler. More...

ResponseGroup	reportStatistics (Media::Source *const source)
	Send statistics data for a source. More...

bool	add (Source *const src)
	Add a source. More...

Private Attributes
Retainer< PianodPlaylist * >	mix_playlist

Retainer< PianodPlaylist * >	everything_playlist

Retainer< PianodPlaylist * >	transient_playlist

Filter	transient_criteria
	Criteria for selecting items into the transient playlist. More...

Friends
class	Tuner::Tuner

Additional Inherited Members
Protected Types inherited from Media::Source
enum class	State { INITIALIZING , VALID , READY , DEAD }

Protected Types inherited from PianodInterpreter
using	StringVector = std::vector< std::string >

Protected Member Functions inherited from Media::Source
MusicThingie *	getSuggestion (MusicThingie *thing, MusicThingie::Type type, SearchRange where, bool fully_confirm)
	Get a thing as a suggestion of a specific type. More...

Protected Attributes inherited from Media::Source
State	state = State::INITIALIZING

const SourceParameters *	parameters = nullptr
	Configuration details for this source, provided on source creation. More...

Static Protected Attributes inherited from PianodInterpreter
static const Parsnip::Data	EmptyDictionary {Parsnip::Data::Dictionary}
	An empty dictionary, often used as a default with Parsnip::Data::getOr. More...

static const StringVector	EmptyStringVector
	An empty string vector, often used as a default with Parsnip::Data::getOr. More...

Detailed Description

The Media::Manager contains a collection of all sources.

It manages their ownership and provides them to the engine when asked. It also implements the Source interface, in which case it amalgamates data from all the sources it knows into one dataset.

Member Typedef Documentation

◆ base_container

using Media::Manager::base_container = std::unordered_map<Source::SerialNumber, Source * const >

◆ SourceList

using Media::Manager::SourceList = std::vector<Source *>

private

Constructor & Destructor Documentation

◆ Manager()

Media::Manager::Manager ( void )

Here is the call graph for this function:

◆ ~Manager()

Media::Manager::~Manager ( void )

Here is the call graph for this function:

Member Function Documentation

◆ add() [1/3]

bool Media::Manager::add ( Source *const source )

private

Add a source.

No validation or messaging is done.

Parameters

source The new source. Caller is responsible for destruction on failure.

Returns: True on success, false on error (duplicate).

Here is the call graph for this function:

Here is the caller graph for this function:

◆ add() [2/3]

Source *const Media::Manager::add ( SourcePtr && source )

Add a source.

Parameters

source A managed pointer to the new source, ensuring that on failure, it is freed.

Returns: Non-managed pointer to the new source.

Here is the call graph for this function:

◆ add() [3/3]

ResponseCollector Media::Manager::add	(	SourcePtr &&	source,
		PianodConnection &	conn
	)

Interactively add a source.

Checks usability, handles events, announces change.

Parameters

source	The source to add. If there is a problem, this is freed.
conn	The connection attempting to add the source.

Returns: false on failure, true on success.

Here is the call graph for this function:

◆ areSourcesInState()

bool Media::Manager::areSourcesInState ( Source::State state ) const

private

Check if there are any sources in a given state.

Returns: state The state to search for.; true if any sources are in the state, false otherwise.

Here is the caller graph for this function:

◆ areSourcesPending()

bool Media::Manager::areSourcesPending ( ) const

inline

Here is the call graph for this function:

Here is the caller graph for this function:

◆ areSourcesReady()

bool Media::Manager::areSourcesReady ( ) const

inline

Here is the call graph for this function:

Here is the caller graph for this function:

◆ authorizedCommand()

bool Media::Manager::authorizedCommand	(	Parsnip::Parser::CommandId	command_id,
		PianodConnection &	context
	)

overrideprivatevirtual

Check whether a command is authorized.

Parameters

command_id	The command requesting execution.
context	Connection details, including authentication state and privileges.

Returns: True if allowed, false otherwise.

Implements PianodInterpreter.

Here is the call graph for this function:

◆ canExpandToAllSongs()

bool Media::Manager::canExpandToAllSongs ( void ) const

overridevirtual

Indicate if arbitrary tracks can be requested from this source.

Returns: True if requests are allowed, false otherwise.

Reimplemented from Media::Source.

◆ createPlaylist() [1/2]

PianodPlaylist * Media::Manager::createPlaylist	(	const char *	name,
		const Filter &	filter
	)

overridevirtual

Create a playlist using a filter.

Parameters

name	The name of the playlist
filter	The selection criteria.

Returns: The playlist created.

Exceptions

CommandError if a request is invalid.

Reimplemented from Media::Source.

◆ createPlaylist() [2/2]

PianodPlaylist * Media::Manager::createPlaylist	(	const char *	name,
		MusicThingie::Type	type,
		MusicThingie *	from
	)

overridevirtual

Create a playlist using a thingie as an initial seed.

Seed type allows, for example, to use a song's artist.

Parameters

name	The name of the playlist.
type	The type of seed to create.
from	The initial seed.

Returns: The playlist created.

Exceptions

CommandError if a request is invalid.

Reimplemented from Media::Source.

◆ erase()

bool Media::Manager::erase ( Source *const source )

Remove a source.

If a source is busy, its is moved out of "ready" state and removal deferred. The periodic() method subsequently checks if it is ready to be removed, and does so when possible.

Parameters

source The source to remove.

Returns: true if successful, false if source is busy (removal is deferred).

Here is the call graph for this function:

Here is the caller graph for this function:

◆ flush()

bool Media::Manager::flush ( void )

overridevirtual

Ask all the sources to persist any data.

Returns: True if all succeeded, false otherwise.

Reimplemented from Media::Source.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get() [1/2]

Source *const Media::Manager::get ( const SerialNumber serial ) const

Retrieve a source by serial number.

Parameters

serial The source serial number.

Returns: The source, or nullptr if not found.

Here is the caller graph for this function:

◆ get() [2/2]

Source *const Media::Manager::get	(	const std::string &	type,
		const std::string &	ident
	)		const

Retrieve a source by type and ID.

ID meaning varies by source.

Parameters

type	The source type name.
ident	The source ID.

Returns: The source, or nullptr if not found.

Here is the call graph for this function:

◆ getAnythingById() [1/2]

MusicThingie * Media::Manager::getAnythingById ( const SplitId & id )

overridevirtual

Retrieve a playlist, song, album or artist by ID.

Parameters

id	The item's ID.

Returns: The item, or nullptr if not found or source not ready.

Implements Media::Source.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getAnythingById() [2/2]

MusicThingie * Media::Manager::getAnythingById ( const std::string & id )

Retrieve a playlist, song, album or artist by ID.

Parameters

id	The item's ID.

Returns: The item, or nullptr if not found or source not ready.

Exceptions

CommandError if the ID is invalid.

Here is the call graph for this function:

◆ getEverythingPlaylist()

PianodPlaylist * Media::Manager::getEverythingPlaylist ( void )

overridevirtual

Implements Media::Source.

Here is the call graph for this function:

◆ getMixPlaylist()

PianodPlaylist * Media::Manager::getMixPlaylist ( void )

overridevirtual

Implements Media::Source.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getParserDefinitions()

const Parsnip::Parser::Definitions & Media::Manager::getParserDefinitions ( )

overridevirtual

Retrieve the parser definitions handled by the interpreter.

Returns: Parser definitions.

Implements PianodInterpreter.

Here is the call graph for this function:

◆ getPlayer()

Player * Media::Manager::getPlayer	(	const AudioSettings &	audio,
		PianodSong *	song
	)

overridevirtual

Play a song, gathering statistics and substituting proxies if enabled.

Implements Media::Source.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getPlaylists()

PlaylistList Media::Manager::getPlaylists ( const Filter & filter = Filter::All )

overridevirtual

Retrieve the source's playlists.

Parameters

filter Criteria specifying the subset of the playlists to retrieve.

Returns: Playlists matching the filter, or all playlists if omitted.

Implements Media::Source.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getRandomSongs()

SongList Media::Manager::getRandomSongs	(	PianodPlaylist *	playlist,
		const UserList &	users,
		Media::SelectionMethod	selectionMethod
	)

overridevirtual

Implements Media::Source.

Here is the call graph for this function:

◆ getReadySources()

SourceList Media::Manager::getReadySources ( ) const

inline

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getRealSources() [1/2]

Manager::SourceList Media::Manager::getRealSources ( ) const

private

Get all sources (excluding the manager itself).

Here is the caller graph for this function:

◆ getRealSources() [2/2]

Manager::SourceList Media::Manager::getRealSources ( Source::State state ) const

private

Get sources (excluding the manager itself) in a given state.

◆ getSource()

Media::Source *const Media::Manager::getSource ( const Parsnip::Data & options )

Get a source commands predicate (either by ID or type and name).

Parameters

options The options specifying source to retrieve.

Returns: The source specified.

Exceptions

CommandError if the specified source does not exist.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getSuggestion()

MusicThingie * Media::Manager::getSuggestion	(	MusicThingie *	thing,
		MusicThingie::Type	type,
		SearchRange	where
	)

overridevirtual

Retrieve an equivalent or related album, artist, or song from a source.

To support pianod's engine, this converts items between sources. The engine should not be asking for type conversions within a source.

Parameters

thing	The item to match.
type	The desired type to find.
where	Selects the depth/exhaustiveness of search.

Returns: The single, best-matching item.

Exceptions

CommandError

with:

E_INVALID (inadequate criteria)
E_AMBIGUOUS (multiple matches)
E_NOTFOUND.

Implements Media::Source.

◆ getSuggestions()

ThingieList Media::Manager::getSuggestions	(	const Filter &	filter,
		SearchRange	where
	)

overridevirtual

Implements Media::Source.

Here is the call graph for this function:

◆ getTransientPlaylist()

PianodPlaylist * Media::Manager::getTransientPlaylist ( const Filter & criteria )

overridevirtual

If any source has the necessary capabilities, and some items match the criteria, then stash the criteria (needed when random songs are later requested) and return the transient playlist.

Reimplemented from Media::Source.

Here is the call graph for this function:

◆ handleCommand()

ResponseCollector Media::Manager::handleCommand	(	Parsnip::Parser::CommandId	command_id,
		const Parsnip::Data &	parameters,
		PianodConnection &	context
	)

overrideprivatevirtual

Command handler.

Parameters

command_id	Command to execute.
parameters	Command parameters.
context	Connection details, including authentication state and privileges.

Returns: Data or success/failure indications.

Exceptions

CommandError or other exception if an error occurs.

Implements PianodInterpreter.

Here is the call graph for this function:

◆ handleSourceStateChange()

void Media::Manager::handleSourceStateChange ( Source *const source )

private

Respond to a source's state change.

Send any appropriate messages.
Invoke appropriate callbacks.
Parameters

source The source whose state has changed.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ json_request_names()

const PianodSchema::CommandIds & Media::Manager::json_request_names ( PianodSchema & schema )

static

Retrieve names for our JSON requests, and make schema revisions.

Parameters

schema The schemaset containing our requests.

Returns: Request name to command ID mappings.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ kind()

const char * Media::Manager::kind ( void ) const

overridevirtual

A unique string identifying the type of source.

Implements Media::Source.

◆ parser_definitions()

const Parsnip::Parser::Definitions & Media::Manager::parser_definitions ( void )

static

Here is the caller graph for this function:

◆ periodic()

float Media::Manager::periodic ( void )

overridevirtual

Perform periodic activities and remove sources that deferred removal.

This method dispatches to each registered source. Each source indicates when they want their next time slice.

Returns: Interval until next invokation (shortest interval requested by any children sources).

Reimplemented from Media::Source.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ redirectingStatusHandler()

void Media::Manager::redirectingStatusHandler	(	RESPONSE_CODE	status,
		const char *	detail
	)

private

Handle an alert by passing it to callbacks.

Parameters

status	The numeric status or alert.
detail	Description of alert details.

Here is the caller graph for this function:

◆ reportStatistics()

ResponseGroup Media::Manager::reportStatistics ( Media::Source *const source )

private

Send statistics data for a source.

Here is the call graph for this function:

◆ resetLockout()

void Media::Manager::resetLockout ( )

Reset a temporary lockout so playback can be attempted immediately.

Here is the caller graph for this function:

◆ source_id_parser_definitions()

const Parsnip::OptionParser::Definitions & Media::Manager::source_id_parser_definitions ( )

static

Here is the caller graph for this function:

Friends And Related Function Documentation

◆ Tuner::Tuner

friend class Tuner::Tuner

friend

Member Data Documentation

◆ callback

CallbackManager<Manager, Callbacks> Media::Manager::callback

Callback manager provides API for registering and removing callbacks.

◆ everything_playlist

Retainer<PianodPlaylist *> Media::Manager::everything_playlist

private

◆ mix_playlist

Retainer<PianodPlaylist *> Media::Manager::mix_playlist

private

◆ transient_criteria

Filter Media::Manager::transient_criteria

private

Criteria for selecting items into the transient playlist.

◆ transient_playlist

Retainer<PianodPlaylist *> Media::Manager::transient_playlist

private

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

mediaunits/mediamanager.h
mediaunits/manager/managercommand.cpp
mediaunits/manager/managersource.cpp
mediaunits/manager/mediamanager.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Private Types

Private Member Functions

Private Attributes

Friends

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ base_container

◆ SourceList

Constructor & Destructor Documentation

◆ Manager()

◆ ~Manager()

Member Function Documentation

◆ add() [1/3]

◆ add() [2/3]

◆ add() [3/3]

◆ areSourcesInState()

◆ areSourcesPending()

◆ areSourcesReady()

◆ authorizedCommand()

◆ canExpandToAllSongs()

◆ createPlaylist() [1/2]

◆ createPlaylist() [2/2]

◆ erase()

◆ flush()

◆ get() [1/2]

◆ get() [2/2]

◆ getAnythingById() [1/2]

◆ getAnythingById() [2/2]

◆ getEverythingPlaylist()

◆ getMixPlaylist()

◆ getParserDefinitions()

◆ getPlayer()

◆ getPlaylists()

◆ getRandomSongs()

◆ getReadySources()

◆ getRealSources() [1/2]

◆ getRealSources() [2/2]

◆ getSource()

◆ getSuggestion()

◆ getSuggestions()

◆ getTransientPlaylist()

◆ handleCommand()

◆ handleSourceStateChange()

◆ json_request_names()

◆ kind()

◆ parser_definitions()

◆ periodic()

◆ redirectingStatusHandler()

◆ reportStatistics()

◆ resetLockout()

◆ source_id_parser_definitions()

Friends And Related Function Documentation

◆ Tuner::Tuner

Member Data Documentation

◆ callback

◆ everything_playlist

◆ mix_playlist

◆ transient_criteria

◆ transient_playlist