libSpiff Documentation

0.8.3

Introduction

Welcome to the short libSpiff integration tutorial. I recommend using this tutorial together with the code samples in the examples folder; one of these two sources is likely to answer your questions. Please drop me a line if you need further assistance and I will see what I can do for you. Good luck with libSpiff!

Reading a playlist

To read an XSPF playlist you first need a reader instance:

        SpiffReader reader;

You use the reader like this:

        reader.parseFile(_PT("playlist.xspf"), NULL);

That _PT() thing is a macro to support Unicode. More details on this later. The second parameter is the callback object that will receive playlist and track information as they are made available; it can be NULL if you just want to verify that the given file is valid XSPF version 0 or 1 but do not need any more specific information about it. In general it is a pointer to an instance of a class derived from SpiffReaderCallback. That means it has to implement two functions:

        void addTrack(SpiffTrack * track);
        void setProps(SpiffProps * props);

These functions are called by the reader when new information is made available; setProps() will be called once per playlist (if the reader has not stopped before due to an error) but addTrack() can be called multiple times.

Remarks:

The callback model was copied from Expat, the underlying XML parser; this model does not need the whole XML tree in memory at a time, thus it is more memory-friendly.

These two functions have to do very similar work: They are passed a data object which they can analyze (by calling methods starting with "get") or steal properties from (by calling methods starting with "steal").

Attention:

Both of these functions have to delete the track/props when they are done to prevent memory leakage or decide to keep them for later; the reader will not do this work for you! Furthermore when deleting the track/props instance all memory not previously stolen from it will also be deleted by the destructor. Stealing means transferring the memory's ownership and preventing it from getting deleted. To avoid memory leakage you should delete the stolen memory yourself later.

Remarks:

The whole steal-analyze-model was introduced to reduce the number of unnecessary copy operations and therefore speed up the parsing process.

When reading is finished the value returned from parseFile() will be either SPIFF_READER_SUCCESS or one of the error codes. In the latter case you can call getErrorLine() to find out in what line the error occurred and getErrorText() to get a short error information.

Attention:

Please note that the pointer returned from getErrorText() is only valid as long as the reader instance lives. Also note that even if parseFile() returns with an error addTrack() or setProps() might have been called already.

Writing a playlist

To write an XSPF playlist file you first need a writer instance:

        SpiffWriter writer(1, layout, propsWriter);

The first parameter is the XSPF version number which currently can be 0 or 1. The second parameter is an callback XML formatter (an instance of a class derived from SpiffXmlFormatter) which will mainly control the whitespace in the XML output. libSpiff already comes with two built-in formatters: SpiffIndentFormatter which creates well-indented XML output and SpiffSeamlessFormatter which does not create any whitespace at all. The third parameter - "propsWriter" here - is a writer whose job is to take care of the playlist property part. You can think of it as the counterpart to setProperties of the reader callback. A basic playlist property writer can be created like this:

        SpiffProps props;
        SpiffPropsWriter propsWriter(&props);

As you can see it wraps a SpiffProps instance. That instance can be modified before or after the wrapping to hold the information you want the output playlist to have. For example you set the playlist's creation time like this:

        SpiffDateTime dateTime(2006, 8, 28, 11, 30, 11, 1, 0);
        props.lendDate(&dateTime);

Similar to the steal/get duality introduced earlier you have to choose between the "lend" and "give" function family when setting information. The whole thing again is only about memory ownership: The lend functions do not transfer ownership, the give functions do. The give family also offers to copy the memory or to assign existing memory. To make this more clear calling

        props.giveTitle(_PT("Some title"), false); // false == do not copy

would be a bad idea since the memory would not be copied but deleted on destruction. You should use

        props.lendTitle(_PT("Some title"));

in this case.

Back to the writer: When you have created a SpiffWriter instance you can let it write its content to file:

        writer.writeFile(_PT("TEST.xspf"));

In this case that would make a valid playlist without any tracks. So before writing the playlist you should add your tracks:

        SpiffTrack track;
        SpiffTrackWriter trackWriter;
        trackWriter.setTrack(&track);
        track.lendCreator(_PT("Breaking Benjamin"));
        writer.addTrack(trackWriter);

When addTrack() is called the track information is appended to an internal buffer which is written when writeFile() is called eventually. You can add the same track several times, you can reuse the track writer, you can call writeFile() several times to write the same playlist to several files; what you cannot do is add more tracks after writing the playlist to a file: You have to call reset() to start over with an empty track list.

Good luck with your application! libSpiff integration questions are always welcome.