PUMP SEARCH PROTOCOL
The search engine protocol is used to provide several media contents requested by the user.
1. Request Software -> Server
a) Overview
The request is done by invoking a service URL with a search query parameter.
Users can add additional search services through the Pump search engine editor.
b) Sample
The software will execute the following request:
http://www.myfavoritesearchengine.com/search?q=query
The response is an XML file which can have different structures:
2. Response Server -> Software, XML structure
a) XML schema
| <?xml version="1.0" encoding="UTF-8"?> |
| <xs:schema id="SearchResults" |
| targetNamespace="http://tempuri.org/SearchResults.xsd" |
| elementFormDefault="qualified" |
| xmlns="http://tempuri.org/SearchResults.xsd" |
| xmlns:mstns="http://tempuri.org/SearchResults.xsd" |
| xmlns:xs="http://www.w3.org/2001/XMLSchema"> |
| <xs:element name="entries"> |
| <xs:complexType> |
| <xs:sequence> |
| <xs:element name="title" type="xs:string"/> |
| <xs:element name="description" type="xs:string"/> |
| <xs:element name="category" type="xs:string"/> |
| <xs:element name="image" type="xs:string"/> |
| <xs:element name="deeplinked" type="xs:string"/> |
| <xs:element name="entry" minOccurs="0" maxOccurs="unbounded"> |
| <xs:complexType> |
| <xs:sequence> |
| <xs:element name="title" type="xs:string"/> |
| <xs:element name="author" type="xs:string" minOccurs="0"/> |
| <xs:element name="size" type="xs:long" minOccurs="0"/> |
| <xs:element name="seed" type="xs:int" minOccurs="0"/> |
| <xs:element name="leech" type="xs:int" minOccurs="0"/> |
| <xs:element name="album" type="xs:string" minOccurs="0"/> |
| <xs:element name="link" type="xs:string"/> |
| <xs:element name="content" minOccurs="0"> |
| <xs:complexType> |
| <xs:attribute name="type" type="xs:string" use="required"/> |
| <xs:attribute name="src" type="xs:string" use="required"/> |
| </xs:complexType> |
| </xs:element> |
| </xs:sequence> |
| </xs:complexType> |
| </xs:element> |
| </xs:sequence> |
| </xs:complexType> |
| </xs:element> |
| </xs:schema> |
b) XML Response structure
| <entries> |
| <title>bt.etree.org</title> |
| <link>http://service.openkapow.com/zslide/btetreeorg.xml?query=VIPEERSQUERY</link> |
| <description/> |
| <category>torrent</category> |
| <image>http://bt.etree.org/favicon.ico</image> |
| <deeplinked>true</deeplinked> |
| <entry> |
| <title>Grateful Dead 1965-1967 Acid Tests</title> |
| <size>1592359125</size> |
| <link>http://bt.etree.org/details.php?id=520741</link> |
| <seed>42</seed> |
| <leech>9</leech> |
| <medialink>http://bt.etree.org/download.php/520741/acid%20tests.torrent</medialink> |
| <mimetype>application/x-bittorrent</mimetype> |
| <author>Grateful Dead</author> |
| </entry> |
| <entry> |
| <title>Orpheum Boston, MA (Earthworks > Portico) FIXED DATE</title> |
| <size>1115617755</size> |
| <link>http://bt.etree.org/details.php?id=519770</link> |
| <seed>23</seed> |
| <leech>0</leech> |
| <medialink>http://bt.etree.org/lac16f.torrent</medialink> |
| <mimetype>application/x-bittorrent</mimetype> |
| <author>Govt Muled</author> |
| </entry> |
| </entries> |
- Title element is the engine name displayed in Pump software.
- Link element is the service url providing contents.
- Description element defines additional informations about the provider
- Category element defines content types provided by the service
- “audio”: used for music content (all supported format by Pump)
- “video”: used for video content (all supported format by Pump)
- “torrent”: used for torrents (support torrent contents)
- Image element defines url for search engine icon, this resource is used by Pump to display a picto in the search engine tab (a size of 16 x 16 is recommended)
- Deeplinked: can be “true” or “false”, specify if the links for contents are provided by the service (“true”) or if contents are only available through a webpage.
For each entry, these elements have to be specified:
- Title: define media content name
- Size: define media content size
- MediaLink: define media content link, provided only if the tag Deeplinked = “true”
- Seed: provide additional information for torrents (seeding)
- Leech: provide additional information for torrents (leeching)
- Link: provide a web page associated with the content link, this page is displayed in Pump if the tag Deeplinked = “false”
- Mimetype : content type descriptor
- Author : information about the author or artist associated with
3. Response Server -> Software, RSS structure
RSS format as response is supported too.
a) RSS response schema
| <?xml version="1.0" encoding="UTF-8"?> |
| <xs:schema id="RssDataset" |
| elementFormDefault="qualified" |
| attributeFormDefault="qualified" |
| xmlns:xs="http://www.w3.org/2001/XMLSchema"> |
| xmlns:msdata="urn:schemas-microsoft-com:xml-msdata"> |
| <xs:element name="rss" msdata:IsDataSet="true"> |
| <xs:complexType> |
| <xs:sequence> |
| <xs:element name="channel" type="channel" /> |
| </xs:sequence> |
| </xs:complexType> |
| </xs:element> |
| <xs:complexType name="channel"> |
| </xs:sequence> |
| <xs:element name="title" minOccurs="1" maxOccurs="1"></xs:element> |
| <xs:element name="link" minOccurs="1" maxOccurs="1"></xs:element> |
| <xs:element name="description" minOccurs="1" maxOccurs="1"></xs:element> |
| <xs:element name="pubDate"></xs:element> |
| <xs:element name="category"></xs:element> |
| <xs:element name="rating"></xs:element> |
| <xs:element name="item" type="item" minOccurs="0" maxOccurs="unbounded"/> |
| </xs:sequence> |
| <xs:attribute name="version" default="2.0" /> |
| </xs:complexType> |
| <!-- End of Channel definition --> |
| <!-- Start Item definition --> |
| <xs:complexType name="item"> |
| <xs:sequence> |
| <xs:element name="title" /> |
| <xs:element name="link"></xs:element> |
| <xs:element name="description"></xs:element> |
| <xs:element name="author" minOccurs="0" maxOccurs="1"></xs:element> |
| <xs:element name="enclosure" minOccurs="0" maxOccurs="1"> |
| <xs:complexType> |
| <xs:attribute name="url" use ="required"></xs:attribute> |
| </xs:complexType> |
| </xs:element> |
| <xs:element name="guid" minOccurs="0" maxOccurs="1"></xs:element> |
| <xs:element name="pubDate" minOccurs="0" maxOccurs="1"></xs:element> |
| </xs:sequence> |
| </xs:complexType> |
| </xs:schema> |
b) RSS Response structure
| <channel> |
| <link>http://urlservice.com</link> |
| <description/> |
| <language>en-US</language> |
| <item> |
| <title>Grateful Dead 1965-1967 Acid Tests</title> |
| <size>1592359125</size> |
| <link>http://serviceurl.com?id=520741</link> |
| <enclosure |
| url=”http://serviceurl.com/154.torrent” |
| length=”454564” |
| type=”application/x-bittorrent”> |
| </enclosure> |
| </item> |
| <item> |
| <title>Orpheum Boston, MA (Earthworks > Portico) FIXED DATE</title> |
| <size>1115617755</size> |
| <link>http://bt.etree.org/details.php?id=519770</link> |
| <enclosure |
| url=”http://serviceurl.com/158.torrent” |
| length=”458569” |
| type=”application/x-bittorrent”> |
| </enclosure> |
| </item> |
| </channel> |
Additional information about torrent files (i.e. Number of seeders or leechers) can be defined in 2 different ways:
- In a different namespace xmlns:bittorrent, with additional tags for each item
i.e. :
<item> <title>Orpheum Boston, MA (Earthworks > Portico) FIXED DATE</title> <size>1115617755</size> <link>http://bt.etree.org/details.php?id=519770</link> <enclosure url=”http://serviceurl.com/158.torrent” length=”458569” type=”application/x-bittorrent”> </enclosure> <bittorrent:seeders>2</bittorrent:seeders> <bittorrent:leechers>1</bittorrent:leechers> </item> <bittorrent:seeders> : additional information for torrents (seeding)
<bittorrent:leechers> : additional information for torrents (leeching) - In the title tag, with a defined syntax
i.e.:
<title>title content (2S/1L)</title>
2S: Number of seeders (seeders = 2)
1L: Number of leechers (leechers = 1)
Check the tutorial about how to add a search tab for the integration with Pump
