Banshee RemoteListener Extension API Documentation

What is that / what will I find here?

This document will provide detailed information how the banshee RemoteListener extension works and how to communicate with it without having to read a single line of code. This API is designed to work with socket / bit operation technology and uses a SQLite database to supplement the communication efficiency. In fact it is so common and basic that every player which can provide a socket connection and a SQLite database which contains track data could realize that API. Therefore you'll find only some notes in this document when the RemoteListener extension of banshee has something special to mention.

This API is designed like that by myself since I'm the only person working on that right now. So there might be some design decision which are wrong or not really thought trough. Criticize, suggest, improve!

Any common information on the API / this documentation?

A common request looks like this: [request byte (required)]2[password ID (required)]?[parameter bytes (optional)]. This document will provide a complete wiki page for every request byte explanation. The password ID is a simple random number which user can choose on the server side and the requesting remote controller has to specify. This should prevent external misuse.

The server should (and will) always provide a response (at least one byte). A empty response indicates that you requested an invalid request code or the server failed to execute the requested command (critical and exceptional!). If the server is returning unexpected results then your request encoding or response decoding is just wrong (the extension is well tested with the corresponding android application since they are build at the same time and usually shouldn't fail!).

When this documents is mentioning short or integer data it is always meant to be unsigned and encoded big-endian.

• Short value (2 bytes) 0x63FA becomes [FA][63]
• Integer value (4 bytes) 0x63FAD87C becomes [7C][D8][FA][63]
• String (UTF-8) will be encoded as short value which represents the byte(!) length of the string followed by the raw bytes of the UTF-8 string

Why bit handling? That's so annoying and such a nasty overhead?

I know, dealing with bits is a pain (e.g. Javas byte is interpreted as complement of two). Sending message strings is more human and looks cleaner but it's also a waste of memory. When you actually want to push a number 0-100 you need a single byte, as UTF-8 string already 3. Even worse when you reporting states like playing as strings although a single byte is more than enough. I think every language which is able to use sockets can deal with bits and bytes.

Pushing data over the network was always the bottleneck of performance. In these days when smart-phone technology is rising the user will thank you for every saved byte (especially if he's using a mobile network connection). Encoding / decoding of the sent / received data on client / server side is cheap, pushing it raw through the network is not...