Album browsing


Typedefs
typedef void	albumbrowse_complete_cb (sp_albumbrowse result, void userdata)
Functions
sp_albumbrowse *	sp_albumbrowse_create (sp_session session, sp_album album, albumbrowse_complete_cb callback, void userdata)
bool	sp_albumbrowse_is_loaded (sp_albumbrowse *alb)
sp_error	sp_albumbrowse_error (sp_albumbrowse *alb)
sp_album *	sp_albumbrowse_album (sp_albumbrowse *alb)
sp_artist *	sp_albumbrowse_artist (sp_albumbrowse *alb)
int	sp_albumbrowse_num_copyrights (sp_albumbrowse *alb)
const char *	sp_albumbrowse_copyright (sp_albumbrowse *alb, int index)
int	sp_albumbrowse_num_tracks (sp_albumbrowse *alb)
sp_track *	sp_albumbrowse_track (sp_albumbrowse *alb, int index)
const char *	sp_albumbrowse_review (sp_albumbrowse *alb)
void	sp_albumbrowse_add_ref (sp_albumbrowse *alb)
void	sp_albumbrowse_release (sp_albumbrowse *alb)

Detailed Description

Browsing adds additional information to what an sp_album holds. It retrieves copyrights, reviews and tracks of the album.

Typedef Documentation

typedef void albumbrowse_complete_cb(sp_albumbrowse *result, void *userdata)

The type of a callback used in sp_albumbrowse_create()

When the callback is called, the metadata of all tracks belonging to it will have been loaded, so sp_track_is_loaded() will return non-zero. The sp_artist of the album will also have been fully loaded.

Parameters:

`[in]`	result	The same pointer returned by sp_albumbrowse_create()
`[in]`	userdata	The opaque pointer given to sp_albumbrowse_create()

Function Documentation

void sp_albumbrowse_add_ref ( sp_albumbrowse * alb )

Increase the reference count of an album browse result

Parameters:

[in] alb The album browse result object

sp_album* sp_albumbrowse_album ( sp_albumbrowse * alb )

Given an album browse object, return the pointer to its album object

Parameters:

[in] alb Album browse object

Returns:: Album object

Examples:: browse.c.

sp_artist* sp_albumbrowse_artist ( sp_albumbrowse * alb )

Given an album browse object, return the pointer to its artist object

Parameters:

[in] alb Album browse object

Returns:: Artist object

const char* sp_albumbrowse_copyright	(	sp_albumbrowse *	alb,
		int	index
	)

Given an album browse object, return one of its copyright strings

Parameters:

`[in]`	alb	Album browse object
`[in]`	index	The index for the copyright string. Should be in the interval [0, sp_albumbrowse_num_copyrights() - 1]

Returns:: Copyright string in UTF-8 format, or NULL if the index is invalid. Returned string is valid as long as the album object stays allocated and no longer than the next call to sp_session_process_events()

Examples:: browse.c.

sp_albumbrowse* sp_albumbrowse_create	(	sp_session *	session,
		sp_album *	album,
		albumbrowse_complete_cb *	callback,
		void *	userdata
	)

Initiate a request for browsing an album

The user is responsible for freeing the returned album browse using sp_albumbrowse_release(). This can be done in the callback.

Here is a snippet from browse.c:

    g_albumbrowse = sp_albumbrowse_create(session, album, &album_complete, NULL);
    sp_link_release(link);

    if (!g_albumbrowse) {
        fprintf(stderr, "failed to start album browse\n");
        g_exit_code = 10;
        return;
    }

Parameters:

`[in]`	session	Session object
`[in]`	album	Album to be browsed. The album metadata does not have to be loaded
`[in]`	callback	Callback to be invoked when browsing has been completed. Pass NULL if you are not interested in this event.
`[in]`	userdata	Userdata passed to callback.

Returns:: Album browse object

See also:: albumbrowse_complete_cb

Examples:: browse.c.

sp_error sp_albumbrowse_error ( sp_albumbrowse * alb )

Check if browsing returned an error code.

Parameters:

[in] alb Album browse object

Returns:: Error code

Examples:: browse.c.

bool sp_albumbrowse_is_loaded ( sp_albumbrowse * alb )

Check if an album browse request is completed

Parameters:

[in] alb Album browse object

Returns:: True if browsing is completed, false if not

int sp_albumbrowse_num_copyrights ( sp_albumbrowse * alb )

Given an album browse object, return number of copyright strings

Parameters:

[in] alb Album browse object

Returns:: Number of copyright strings available, 0 if unknown

Examples:: browse.c.

int sp_albumbrowse_num_tracks ( sp_albumbrowse * alb )

Given an album browse object, return number of tracks

Parameters:

[in] alb Album browse object

Returns:: Number of tracks on album

Examples:: browse.c.

void sp_albumbrowse_release ( sp_albumbrowse * alb )

Decrease the reference count of an album browse result

Parameters:

[in] alb The album browse result object

Examples:: browse.c.

const char* sp_albumbrowse_review ( sp_albumbrowse * alb )

Given an album browse object, return its review

Parameters:

[in] alb Album browse object

Returns:: Review string in UTF-8 format. Returned string is valid as long as the album object stays allocated and no longer than the next call to sp_session_process_events()

Examples:: browse.c.

sp_track* sp_albumbrowse_track	(	sp_albumbrowse *	alb,
		int	index
	)

Given an album browse object, return a pointer to one of its tracks

Parameters:

`[in]`	alb	Album browse object
`[in]`	index	The index for the track. Should be in the interval [0, sp_albumbrowse_num_tracks() - 1]

Returns:: A track.

See also:: Track subsystem

Examples:: browse.c.

Album browsing

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation