lib/libUPnP/Platinum/README.md

   1 #PLATINUM UPNP SDK [![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage) [![Build Status](https://travis-ci.org/plutinosoft/Platinum.svg?branch=master)](https://travis-ci.org/plutinosoft/Platinum)
   2
   3 This toolkit consists of 2 modules:
   4 * Neptune : a C++ Runtime Library
   5 * Platinum: a modular UPnP Framework [Platinum depends on Neptune]
   6
   7 Unless you intend to use Neptune independently from Platinum, it is recommended that you build binaries directly from the Platinum root directory. All the dependent binaries will be rebuilt automatically (including Neptune).
   8
   9 #Building SDK and Sample Applications
  10
  11 ## Windows:
  12 Open the Visual Studio 2010 solution located @ Build\Targets\x86-microsoft-win32-vs2010\Platinum.sln
  13
  14 ## Mac, iOS:
  15 First install carthage (https://github.com/Carthage/Carthage)
  16 ```
  17 > brew update || brew install carthage
  18 ```
  19 Build Neptune & Platinum frameworks
  20 ```
  21 > carthage bootstrap
  22 > carthage build --no-skip-current
  23 ```
  24
  25 Both Neptune and Platinum frameworks binaries can be found under Carthage/Build folders which you can link with your applications.
  26 Follow the instructions on the [carthage page](https://github.com/Carthage/Carthage).
  27 If you are building for iOS, special [instructions here](https://github.com/Carthage/Carthage#if-youre-building-for-ios).
  28
  29 If you are interested in building sample apps or tests, you can also open the XCode project file located @ Build/Targets/universal-apple-macosx/Platinum.xcodeproj.
  30
  31 ## Linux, Cygwin, etc ...
  32 Open a shell, go to the Platinum root directory and type 'scons' (http://scons.org).
  33 ```
  34 > brew update || brew install scons
  35 > git submodule update --init
  36 > scons target={TARGET} build_config={Debug|Release}
  37 ```
  38 The output of the scons build will be found under Build/Targets/{TARGET}/{Debug|Release}.
  39 Additionally, the output is copied under Targets/{TARGET}/{Debug|Release} for convenience when applicable.
  40
  41 #Running Sample Applications
  42
  43 ## FileMediaServerTest
  44 This is an example of a UPnP MediaServer. Given a path, it allows a UPnP ControlPoint to browse the content of the directory and its sub-directories. Additionally, files can be streamed (Note that only files with known mimetypes are advertised).
  45
  46 ```
  47 FileMediaServerTest [-f <friendly_name>] <path>
  48     -f : optional upnp server friendly name
  49     <path> : local path to serve
  50 ```
  51
  52 Once started, type 'q' to quit.
  53
  54 ## MediaRendererTest
  55 This is an example shell of a UPnP MediaRenderer. It is to be contolled by a UPnP ControlPoint. This is just a SHELL, this won't play anything yet. You need to hook up the playback functionality yourself.
  56
  57 ```
  58 MediaRendererTest [-f <friendly_name>]
  59     -f : optional upnp server friendly name
  60 ```
  61
  62 Once started, type 'q' to quit.
  63
  64 ## MediaCrawler
  65 This is a combo UPnP MediaServer + ControlPoint. It browses content from other MediaServers it finds on the network and present them under one single aggregated view. This is useful for some devices that need to select one single MediaServer at boot time (i.e. Roku).
  66
  67 Once started, type 'q' to quit.
  68
  69 ## MicroMediaController
  70 This is a ControlPoint (synchronous) that lets you browse any MediaServer using a shell-like interface. Once started, a command prompt lets you enter commands such as:
  71 ```
  72      quit    -   shutdown
  73      exit    -   same as quit
  74      setms   -   select a media server to become the active media server
  75      getms   -   print the friendly name of the active media server
  76      ls      -   list the contents of the current directory on the active
  77                  media server
  78      cd      -   traverse down one level in the content tree on the active
  79                  media server
  80      cd ..   -   traverse up one level in the content tree on the active
  81                  media server
  82      pwd     -   print the path from the root to your current position in the
  83                  content tree on the active media server
  84 ```
  85
  86 Experimental MediaRenderer commands (not yet full implemented):
  87 ```
  88      setmr   -   select a media renderer to become the active media renderer
  89      getmr   -   print the friendly name of the active media renderer
  90      open    -   set the uri on the active media renderer
  91      play    -   play the active uri on the active media renderer
  92      stop    -   stop the active uri on the active media renderer
  93 ```
  94
  95 ## MediaConnect
  96 This is a derived implementation of the FileMediaServerTest with the only difference that it makes it visible to a XBox 360.
  97
  98 ## MediaServerCocoaTest
  99 A basic cocoa test server app showing how to use the Platinum framework on Mac OSX.
 100
 101 #Language Bindings
 102
 103 ## Objective-C
 104 Under Source/Extras/ObjectiveC
 105
 106 ## C++/CLR
 107 Under Source/Extras/Managed
 108
 109 ## Android Java/JNI
 110 To build the JNI shared library, you will need to install the Android NDK and set up the proper environment variables such as ANDROID_NDK_ROOT.
 111 ```
 112 > scons target=arm-android-linux build_config=Release
 113 > cd Source/Platform/Android/module/platinum
 114 > ndk-build NDK_DEBUG=0
 115 ```
 116
 117 This will create the libplatinum-jni.so files under the Source/Platform/Android/module/platinum/libs folder.
 118 You can then import eclipse Android .project located @ Source/Platform/Android/modules/platinum to create the jar file @ Source/Platform/Android/modules/platinum/bin/platinum.jar
 119
 120 To Test the Platinum jni layer, import into eclipse both Android projects located @ Source/Platform/Android/samples/sample-upnp & Source/Platform/Android/modules/platinum.
 121
 122 #Contributing
 123
 124 We're glad you're interested in Platinum, and we'd love to see where you take it.
 125
 126 Any contributors to the master Platinum repository must sign the [Individual Contributor License Agreement (CLA)](https://docs.google.com/forms/d/1-SuyEu0LfYuhY3kKDDdfdYn5cmTU2lrQRSQSDHau4PI/viewform).
 127 It's a short form that covers our bases and makes sure you're eligible to contribute.
 128
 129 When you have a change you'd like to see in the master repository, [send a pull request](https://github.com/plutinosoft/Platinum/pulls). Before we merge your request, we'll make sure you're in the list of people who have signed a CLA.
 130
 131 Thanks!