Reference counting in the Noatun API was created for speed. Some playlists (SQL ones, particularly) might have tens of thousands of items. And instanciating an object for each of them will be SLOW, not to mention memory hoggish. Reference counting makes it possible to not have this issue.

The PlaylistItemData is the actual object, while PlaylistItem is the "pointer". It'd be a good idea to save creation of a PlaylistItemData to the absolute last chance possible, storing in a fast meta-structure. Don't ask me, I only wrote this api! an Example follows.

PlaylistItem next()
{
	// PluginsItemData is my plugin's inherited version
	// of PlaylistItemData
	PluginsItemData *d=new PluginsItemData;

	// you created a function called getNextNode()
	// which returns a meta-data version of the next
	// item to play.  Then you made a PluginsItemData::set()
	// function which converts a meta-data format to the actual
	// set of data in your PluginsItemData
	d->set(getNextNode());

	// There's a copy constructor: PlaylistItem(PlaylistItemData*)
	return d;
}

PlaylistItem current()
{
	if (mCurrent)
		return mCurrent;

	// well, I don't know the current item
	mCurrent=new PluginsItemData;
	mCurrent->set(=getCurrentNode();

	return mCurrent;
}

All data for a playlist is stored in the form of Properties. Unless the Properties arn't stored by your PlaylistItemData objects (but instead, say, are retrieved from the SQL db every time [slow]), you should make sure that two PlaylistItemDatas never represent the same item, but if its necessary, you should reimplement operator==() (by default, it just tests the address).

Obviously, as it is always the case with reference counting. Your PlaylistItemData will be deleteed by the PlaylistItem.

In Noatun 2, you store the Properties by your own means, in Noatun 1, a QDict was used internally. It tends to be memory inefficient to store all properties in memory, so in Noatun 2.1, there will be a simple, optional, disk-storing API.