Base class that wraps any audio source, such as Pandora, Spotify, or local music. More...

#include <mediaunit.h>

Inheritance diagram for Media::Source:

[legend]

Collaboration diagram for Media::Source:

[legend]

Public Types
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 Member Functions
	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...

virtual bool	flush (void)
	Persist data for a source. 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

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

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	canExpandToAllSongs (void) const
	Indicate if arbitrary tracks can be requested from this source. 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...

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

virtual PianodPlaylist *	getMixPlaylist (void)=0

virtual PianodPlaylist *	getEverythingPlaylist (void)=0

virtual PianodPlaylist *	getTransientPlaylist (const Filter &criteria)
	Create a temporary playlist based on a filter. More...

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

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

virtual MusicThingie *	getAnythingById (const SplitId &id)=0

virtual Player *	getPlayer (const AudioSettings &audio, PianodSong *song)=0

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

virtual ThingieList	getSuggestions (const Filter &filter, SearchRange what=SearchRange::EXHAUSTIVE)=0

virtual float	periodic (void)
	Do intermittent or background tasks. More...

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

virtual void	playbackProblem (void)

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

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

Protected Types
enum class	State { INITIALIZING , VALID , READY , DEAD }

Protected Member Functions
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
State	state = State::INITIALIZING

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

Static Private Member Functions
static void	defaultStatusHandler (RESPONSE_CODE status, const char *detail)
	Log status and alert messages by sending them to stdout. More...

Private Attributes
SerialNumber	serialNum = 0
	Assigned by media manager when registered. More...

State	announced_state = State::INITIALIZING
	Used by media manager for managing callbacks. More...

Statistics	statistics
	Source playback statistics. More...

time_t	lockout_until = 0

std::function< void(RESPONSE_CODE status, const char *detail)>	statusHandler = defaultStatusHandler
	Hook for the status handler, allowing status messages to be rerouted. More...

Friends
class	Manager

Detailed Description

Base class that wraps any audio source, such as Pandora, Spotify, or local music.

Provides a standard interface that pianod can work with. Players can extend their interface with custom commands by deriving from both this and PianodInterpreter, and providing their specialized commands. Care should be used to avoid polluting command space with potentially generic commands.

Member Typedef Documentation

◆ SerialNumber

typedef unsigned long Media::Source::SerialNumber

Member Enumeration Documentation

◆ State

enum Media::Source::State

strongprotected

Enumerator
INITIALIZING	Nothing known yet.
VALID	Credentials valid/data exists, but still initializing or offline.
READY	Fully initialized and ready to play music.
DEAD	Waiting for disposal.

Constructor & Destructor Documentation

◆ Source()

Media::Source::Source ( SourceParameters * params )

Initialize the source.

Parameters

params Source parameters.

◆ ~Source()

ToneGenerator::Source::~Source ( void )

virtual

Destroy a source.

Reimplemented in ToneGenerator::Source, Filesystem::Source, and Pandora::Source.

Member Function Documentation

◆ alert() [1/2]

void Media::Source::alert ( RESPONSE_CODE message ) const

Send an alert notification regarding this source.

The source's identity is appended and the message routed through the status handler, which is usually routed to the media manager.

Parameters

message The numeric status code for the alert.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ alert() [2/2]

void Media::Source::alert	(	RESPONSE_CODE	message,
		const char *	detail,
		const char *	reason = `nullptr`
	)		const

Send an alert notification regarding this source.

The source's identity is appended and the message routed through the status handler, which is usually routed to the media manager.

Parameters

message	The numeric status code for the alert.
detail	Additional text pertaining to the alert.
reason	Optional text describing the reason for the alert.

Here is the call graph for this function:

◆ canExpandToAllSongs()

bool ToneGenerator::Source::canExpandToAllSongs ( void ) const

virtual

Indicate if arbitrary tracks can be requested from this source.

Returns: True if requests are allowed, false otherwise.

Reimplemented in ToneGenerator::Source, Media::Manager, and Filesystem::Source.

Here is the caller graph for this function:

◆ createPlaylist() [1/2]

PianodPlaylist * ToneGenerator::Source::createPlaylist	(	const char *	name,
		const Filter &	filter
	)

virtual

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 in ToneGenerator::Source, Media::Manager, and Filesystem::Source.

Here is the call graph for this function:

◆ createPlaylist() [2/2]

PianodPlaylist * ToneGenerator::Source::createPlaylist	(	const char *	name,
		MusicThingie::Type	type,
		MusicThingie *	from
	)

virtual

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 in ToneGenerator::Source, Pandora::Source, Media::Manager, and Filesystem::Source.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ defaultStatusHandler()

void Media::Source::defaultStatusHandler	(	RESPONSE_CODE	status,
		const char *	detail
	)

staticprivate

Log status and alert messages by sending them to stdout.

This function is invoked indirectly so that it may be replaced by the media manager, which then posts the status notifications to its subscribers. .

◆ filename()

std::string Media::Source::filename ( void ) const

inline

Provide a filename for persisting the source's data.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ flush()

bool ToneGenerator::Source::flush ( void )

virtual

Persist data for a source.

Returns: True on success, false on error.

Reimplemented in ToneGenerator::Source, Pandora::Source, Media::Manager, and Filesystem::Source.

◆ getAnythingById()

MusicThingie * ToneGenerator::Source::getAnythingById ( const SplitId & id )

pure virtual

Implemented in Media::Manager, ToneGenerator::Source, Pandora::Source, and Filesystem::Source.

Here is the caller graph for this function:

◆ getEverythingPlaylist()

PianodPlaylist * ToneGenerator::Source::getEverythingPlaylist ( void )

pure virtual

Implemented in ToneGenerator::Source, Pandora::Source, Media::Manager, and Filesystem::Source.

Here is the caller graph for this function:

◆ getMixPlaylist()

PianodPlaylist * ToneGenerator::Source::getMixPlaylist ( void )

pure virtual

Implemented in ToneGenerator::Source, Pandora::Source, Media::Manager, and Filesystem::Source.

Here is the caller graph for this function:

◆ getPlayer()

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

pure virtual

Implemented in ToneGenerator::Source, Pandora::Source, Media::Manager, and Filesystem::Source.

◆ getPlaylistByName()

PianodPlaylist * Media::Source::getPlaylistByName ( const char * name )

Retrieve a playlist by name.

Parameters

name	The name of the playlist to retrieve.

Returns: The playlist found, or a nullptr if not found.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getPlaylists()

PlaylistList ToneGenerator::Source::getPlaylists ( const Filter & filter = Filter::All )

pure virtual

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.

Implemented in Pandora::Source, Media::Manager, Filesystem::Source, and ToneGenerator::Source.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getRandomSongs()

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

pure virtual

Implemented in Media::Manager, ToneGenerator::Source, Filesystem::Source, and Pandora::Source.

Here is the caller graph for this function:

◆ getStatistics()

const Statistics& Media::Source::getStatistics ( ) const

inline

Retrieve playback statistics about the source.

Here is the caller graph for this function:

◆ getSuggestion() [1/3]

MusicThingie * Media::Source::getSuggestion	(	MusicThingie *	thing,
		MusicThingie::Type	type,
		SearchRange	where,
		bool	fully_confirm
	)

protected

Get a thing as a suggestion of a specific type.

Parameters

thing	The thing to transform.
type	The type of suggestion to retrieve.
where	Where to search: KNOWN searches cache/local indexes only SHALLOW will also query music services. Other SearchRange values are invalid for this method.
fully_confirm	If false, album and title are enough for a song match. If true, either album name or duration must also match.

Returns: A single thingie with a matching description.

Exceptions

CommandError if not found or ambiguous results.

Here is the call graph for this function:

◆ getSuggestion() [2/3]

MusicThingie * ToneGenerator::Source::getSuggestion	(	MusicThingie *	thing,
		MusicThingie::Type	type,
		SearchRange	where = `SearchRange::SHALLOW`
	)

pure virtual

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.

Implemented in ToneGenerator::Source, Pandora::Source, Media::Manager, and Filesystem::Source.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getSuggestion() [3/3]

MusicThingie* Media::Source::getSuggestion	(	MusicThingie *	thing,
		SearchRange	where = `SearchRange::SHALLOW`
	)

inline

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

See also: getSuggestion, 3-parameter version.

Here is the call graph for this function:

◆ getSuggestions()

ThingieList ToneGenerator::Source::getSuggestions	(	const Filter &	filter,
		SearchRange	what = `SearchRange::EXHAUSTIVE`
	)

pure virtual

Implemented in ToneGenerator::Source, Pandora::Source, Media::Manager, and Filesystem::Source.

Here is the caller graph for this function:

◆ getTransientPlaylist()

PianodPlaylist * ToneGenerator::Source::getTransientPlaylist ( const Filter & criteria )

virtual

Create a temporary playlist based on a filter.

Parameters

criteria A filter specifying the song selection algorithm.

Returns: A temporary playlist, or nullptr if not viable for some reaon.

Exceptions

E_MEDIA_ACTION if a non-request source.

Reimplemented in ToneGenerator::Source, Media::Manager, and Filesystem::Source.

Here is the caller graph for this function:

◆ identify()

std::string Media::Source::identify ( ) const

Identify the unique source.

Returns: A string containing the source's serial number, kind, and name.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ isLockedOut()

const bool Media::Source::isLockedOut ( ) const

inline

Check if source is temporarily locked out due to repeated failures.

Here is the caller graph for this function:

◆ isReady()

bool Media::Source::isReady ( void ) const

inline

Check if the source is online.

Here is the caller graph for this function:

◆ key()

std::string Media::Source::key ( void ) const

inline

Key is a combination of kind and name.

Key must be consistent between invokations, as it is user preferences related to the source are identified.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ kind()

const char * ToneGenerator::Source::kind ( void ) const

pure virtual

A unique string identifying the type of source.

Implemented in ToneGenerator::Source, Pandora::Source, Media::Manager, and Filesystem::Source.

Here is the caller graph for this function:

◆ name()

const std::string & Media::Source::name ( void ) const

Get the name of this source.

The kind/name combination is used by the media manager to identify individual sources.

Returns: The name of the source.

Here is the caller graph for this function:

◆ periodic()

float ToneGenerator::Source::periodic ( void )

virtual

Do intermittent or background tasks.

Returns: Suggested time before periodic() be invoked again. No guarantees are offered about actual behavior.

Reimplemented in ToneGenerator::Source, Pandora::Source, Media::Manager, and Filesystem::Source.

◆ persist()

void Media::Source::persist ( void ) const

Persist source parameters, attaching them to the owner's user data.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ playbackComplete()

void Media::Source::playbackComplete	(	bool	played,
		bool	successfully
	)

Update playback statistics.

Warning: If we cared that much, this would have a mutex. We don't.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ playbackProblem()

virtual void Media::Source::playbackProblem ( void )

inlinevirtual

Reimplemented in Filesystem::Source.

◆ reportStatus() [1/2]

void Media::Source::reportStatus ( const char * detail ) const

Send a status notification regarding this source.

The status is routed through alert.

Parameters

detail The status message.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ reportStatus() [2/2]

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

inline

Here is the call graph for this function:

◆ requireNameForCreatePlaylist()

bool Media::Source::requireNameForCreatePlaylist ( void ) const

virtual

Indicate if a name is required when creating a playlist.

Returns: True if a name is required, false otherwise.

Reimplemented in Pandora::Source.

Here is the caller graph for this function:

◆ serializeIdentity()

Parsnip::Data Media::Source::serializeIdentity ( ) const

Here is the call graph for this function:

Here is the caller graph for this function:

◆ serialNumber()

SerialNumber Media::Source::serialNumber ( void ) const

inline

Get the source's unique number assigned by the media manager.

Here is the caller graph for this function:

Friends And Related Function Documentation

◆ Manager

friend class Manager ( void )

friend

Member Data Documentation

◆ announced_state

State Media::Source::announced_state = State::INITIALIZING

private

Used by media manager for managing callbacks.

◆ lockout_until

time_t Media::Source::lockout_until = 0

private

◆ parameters

const SourceParameters* Media::Source::parameters = nullptr

protected

Configuration details for this source, provided on source creation.

◆ serialNum

SerialNumber Media::Source::serialNum = 0

private

Assigned by media manager when registered.

◆ state

State Media::Source::state = State::INITIALIZING

protected

◆ statistics

Statistics Media::Source::statistics

private

Source playback statistics.

◆ statusHandler

std::function<void (RESPONSE_CODE status, const char *detail)> Media::Source::statusHandler = defaultStatusHandler

private

Hook for the status handler, allowing status messages to be rerouted.

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

mediaunits/mediaunit.h
mediaunits/mediasource.cpp
mediaunits/mediaunit.cpp
mediaunits/tonegenerator/tonegensource.cpp

Public Types

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Static Private Member Functions

Private Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ SerialNumber

Member Enumeration Documentation

◆ State

Constructor & Destructor Documentation

◆ Source()

◆ ~Source()

Member Function Documentation

◆ alert() [1/2]

◆ alert() [2/2]

◆ canExpandToAllSongs()

◆ createPlaylist() [1/2]

◆ createPlaylist() [2/2]

◆ defaultStatusHandler()

◆ filename()

◆ flush()

◆ getAnythingById()

◆ getEverythingPlaylist()

◆ getMixPlaylist()

◆ getPlayer()

◆ getPlaylistByName()

◆ getPlaylists()

◆ getRandomSongs()

◆ getStatistics()

◆ getSuggestion() [1/3]

◆ getSuggestion() [2/3]

◆ getSuggestion() [3/3]

◆ getSuggestions()

◆ getTransientPlaylist()

◆ identify()

◆ isLockedOut()

◆ isReady()

◆ key()

◆ kind()

◆ name()

◆ periodic()

◆ persist()

◆ playbackComplete()

◆ playbackProblem()

◆ reportStatus() [1/2]

◆ reportStatus() [2/2]

◆ requireNameForCreatePlaylist()

◆ serializeIdentity()

◆ serialNumber()

Friends And Related Function Documentation

◆ Manager

Member Data Documentation

◆ announced_state

◆ lockout_until

◆ parameters

◆ serialNum

◆ state

◆ statistics

◆ statusHandler