DEV - Getting started

This guide describes how to get started with developing (for) MPExtended.

Setup your environment

The easy way: installing the service

The easiest way is to simply install the service. If you don't want to develop MPExtended itself or need the API from a development version, this is working fine and you can skip the next two steps (continue with Writing clients). If you need more, follow the two steps below.

Obtaining the source code

Visual Studio 2010 and .NET 4 are required (VS2012 and .NET4.5 might work, but aren't actively tested). If you want to build the installers you also need the WIX plugin (http://wix.sourceforge.net/, version 3.5 or newer) for Visual Studio. For WebMediaPortal you also need to have ASP.NET MVC3 and IIS Express installed. ILMerge is optional, but recommended.

We use GitHub as our hosting place, and can be found under the MPExtended project there. You can download the source as a zip archive from their site, or use git itself.

The main development branch is always master. It should be stable enough for developers to use, but occasionally things break. In other feature branches things break more frequently. Sometimes the interface between MPExtended and the plugins break, in this case you have to clean your solution and rebuild all projects.

Compiling

1. Open MPExtended.sln in Visual Studio, started as administrator.
2. Rebuild the MPExtended.ServiceHosts.ConsoleHost project. This is important to force Visual Studio to build the plugins.
3. You can now change the configuration if you want. All configuration files are located in the Config directory. The most relevant configuration file is probably MediaAccess.xml, though the defaults should be fine.
4. Start the ConsoleHost project. Visual Studio will restart now if you didn't start it as administrator.
5. After a few moments there should be a message that the host has been started.

Writing clients

Our services are based upon the Windows Communication Foundation (WCF). This provides us with different interfaces to our services: a local one, a SOAP one and a JSON one. Most developers for desktop applications will probably want to use the SOAP API, while most mobile clients would use the JSON API (because it is less verbose, which improves performance on slow connections), but you are of course free to choose whatever you like.

Besides the different interfaces we have, there are also different services. The four services are the MediaAccessService (abbreviated to MAS in documentation), TVAccessService (abbreviated to TAS), StreamingService (abbreviated to WSS, with the W being there for historic reasons) and the UserSessionService (abbreviated to USS). Each of these services can be accessed seperately.

The JSON API is reachable through the base URL of http://<ip>:4322/MPExtended/<service>/json/. When calling methods, the method name is appended to the base URL. You can find this in the API documentation for the services here, it's listed under URL. (The /json/ part is duplicated there as it's different for a few methods in the WSS API). Parameters for the method should be appended as the query string. The order is not important. Making nullable parameters null is possible by leaving them out or passing an empty value. For enumerations you should pass the integer value of the value, which you can also look up in the API documentation. The returned structure is also documented there, but usually trying it out helps a good deal too.

The WSDL for the SOAP API is available on http://<ip>:4322/MPExtended/<service>/?wsdl. For compiled languages there probably is a tool that converts the WSDL to a set of classes that you can use for easy integration. It uses the same API documentation as the JSON API, but the way you pass parameters differs per language. You also shouldn't change the base URL of the service for each method call.

Getting started with the MAS

The MAS API uses a provider-system, which allows multiple databases to be accessed simultaneously. A sensible provider is configured by default, but especially if you're developing a more advanced client you'll want to specify it by yourself. You can lookup all available providers with the GetServiceDescription method. Each provider (also called library in the API a few times) has a unique ID. You should pass this ID as the provider parameter to all methods that accept one. It is also returned again in each call, in the PID property. This allows to easily transfer objects in a multi-provider application.

See the seperate article about MAS for more details on this service.

Getting started with streams

See the separate howto for this.

Getting started with the TAS

The TAS API is fairly straightforward, and an almost 1:1 mapping of the MediaPortal TV Server API. Make sure to always specify a valid username when this is required.

Getting started with the USS

TODO: It's basically the same as the other services but it has a lot smaller API and isn't always available.