libxspf Documentation

1.2.0

Table of Contents

• Introduction
• Reading a playlist
• Writing a playlist
• Handling malicious XML

Introduction

Welcome to the short libxspf 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. Good luck with integrating libxspf.

Reading a playlist

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

        XspfReaer reader;

You use the reader like this:

        XML_Char const * const baseUri = _PT("http://example.org/");
        reader.parseFile(_PT("playlist.xspf"), NULL, baseUri);

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 XspfReaderCallback. That means it can override these functions:

        void addTrack(XspfTrack * track);
        void setProps(XspfProps * props);

        void notifyFatalError(..);
        bool handleError(..);
        bool handleWarning(..);
        void notifySuccess();

The first two of these 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 XSPF_READER_SUCCESS or one of the error codes. More details about the error occured are passed to the XspfReaderCallback in use.

Writing a playlist

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

        XML_Char const * const baseUri = _PT("http://example.org/");
        XspfWriter * const writer = XspfWriter::makeWriter(formatter, baseUri);

The first parameter is an XML formatter (an instance of a class derived from XspfXmlFormatter) which will mainly control the whitespace in the XML output. libxspf already comes with two built-in formatters: XspfIndentFormatter which creates well-indented XML output and XspfSeamlessFormatter which does not create any whitespace at all. The second parameter is the base URI used to shorten URIs where possible.

If our playlist itself has properties we have to set them before adding any tracks:

        XspfProps props;
        ...
        /* Fill in props */
        ...
        writer->setProps(props);

You could set the playlist's creation time like this:

        XspfDateTime 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"), XspfData::TRANSFER);

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

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

in this case.

Back to the writer: When you have created a XspfWriter 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:

        XspfTrack track;
        ...
        track.lendCreator(_PT("Breaking Benjamin"));
        ...
        writer.addTrack(track);

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 and 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 will have to call reset() to start over with an empty track list first.

Handling malicious XML

Let us assume you are using libxspf to power some kind of web service with XSPF reading cabilities. Let us further assume this service can accept XSPF input from a user. Due to the nature of XML your service would be vulnerable to an XML entity explosion attack. What this means is that a rather small malicious XML file can make the running XML processor a huge amount of memory or CPU time or both.

A popular example is billion laughs, of which an XSPF version could look like this:

        <?xml version="1.0"?>
        <!DOCTYPE billion [
        <!ELEMENT billion (#PCDATA)>
        <!ENTITY laugh0 "ha">
        <!ENTITY laugh1 "&laugh0;&laugh0;">
        <!ENTITY laugh2 "&laugh1;&laugh1;">
        <!ENTITY laugh3 "&laugh2;&laugh2;">
        <!ENTITY laugh4 "&laugh3;&laugh3;">
        ...
        <!ENTITY laugh30 "&laugh29;&laugh29;">
        ]>
        <playlist version="1" xmlns="http://xspf.org/ns/0/">
          <title>&laugh30;</title>
          <trackList />
        </playlist>

With malicious XML detection enabled, libxspf sets certain limits to the values of entities. Currently these limits are:

• Length of entity values
• Sum of lookups per entity value
• Lookup depth per entity value

The above billion laughs example has these metrics:

Entity	Length	Lookup Sum	Lookup Depth
laugh0	2	0	0
laugh1	4	2	1
laugh2	8	6	2
laugh3	16	14	3
laugh4	32	30	4
...	...	...	...
laugh30	2,147,483,648	2,147,483,646	30
laughn	2^(n+1)	2^(n+1)-2	n

Looking at laugh30 all three values are much higher than those of most peaceful XML files. Through calling

        reader.enableMaliciousXmlDetection(true);

you can make a XspfReader instance protocol these metrics in order to detect malicious XML. Also, all of these metrics can be limited and adjusted individually; for instance this is how to limit the lookup depth to a maximum of 2:

        reader.limitLookupDepthPerEntityValue(true);
        reader.setMaxLookupDepthPerEntityValue(2);

Attention:

Malicious XML detection can only work for you if you are clear about your software's use cases. Tune the detection parameters to what you have to allow and reject everything else.