Permalink
Browse files

Moar(!) documentation

  • Loading branch information...
1 parent 4f86d15 commit fa1fa5d9bbf3790a3a7aad3f8b63bbe987f404eb @Alxandr committed Feb 10, 2013
@@ -240,7 +240,7 @@ value struct $session$create {
Task<Session ^> ^Session::Create(array<byte> ^applicationKey, String ^cacheLocation, String ^settingsLocation, String ^userAgent) {
logger->Trace("Create");
- $session$create^ create = gcnew $session$create();
+ $session$create ^create = gcnew $session$create();
create->applicationKey = applicationKey;
create->cacheLocation = cacheLocation;
create->settingsLocation = settingsLocation;
@@ -206,30 +206,53 @@ namespace SpotiFire {
///-------------------------------------------------------------------------------------------------
virtual property BitRate PrefferedBitrate { void set(BitRate bitRate) sealed; }
- /// <summary> Event queue for all listeners interested in ConnectionError events. </summary>
+ /// <summary> [Not implemented] Event queue for all listeners interested in ConnectionError events. </summary>
event SessionEventHandler ^ConnectionError;
+
+ ///-------------------------------------------------------------------------------------------------
/// <summary> Event queue for all listeners interested in EndOfTrack events. </summary>
+ ///
+ /// <remarks> The EndOfTrack event provides a way for applications to be notified whenever
+ /// a track has finished playing. Actions that can be taken after this are for
+ /// instance playing another track, or exiting the application. </remarks>
+ ///-------------------------------------------------------------------------------------------------
event SessionEventHandler ^EndOfTrack;
- /// <summary> Event queue for all listeners interested in Exception events. </summary>
+ /// <summary> [Not implemented] Event queue for all listeners interested in Exception events. </summary>
event SessionEventHandler ^Exception;
- /// <summary> Event queue for all listeners interested in LogMessage events. </summary>
+ /// <summary> [Not implemented] Event queue for all listeners interested in LogMessage events. </summary>
event SessionEventHandler ^LogMessage;
- /// <summary> Event queue for all listeners interested in MessageToUser events. </summary>
+ /// <summary> [Not implemented] Event queue for all listeners interested in MessageToUser events. </summary>
event SessionEventHandler ^MessageToUser;
- /// <summary> Event queue for all listeners interested in MetadataUpdated events. </summary>
+ /// <summary> [Not implemented] Event queue for all listeners interested in MetadataUpdated events. </summary>
event SessionEventHandler ^MetadataUpdated;
+
+ ///-------------------------------------------------------------------------------------------------
/// <summary> Event queue for all listeners interested in PlayTokenLost events. </summary>
+ ///
+ /// <remarks> The PlayTokenLost event provides a way for applications to be notified whenever
+ /// the spotify playtoken is lost. The spotify playtoken is a way for spotify
+ /// to make sure that the same account only plays music at one place at a time
+ /// (to prevent "sharing" of accounts). The playtoken is lost when the same user
+ /// starts to play music on another machine (or another application on the same machine). </remarks>
+ ///-------------------------------------------------------------------------------------------------
event SessionEventHandler ^PlayTokenLost;
- /// <summary> Event queue for all listeners interested in StartPlayback events. </summary>
+ /// <summary> [Not implemented] Event queue for all listeners interested in StartPlayback events. </summary>
event SessionEventHandler ^StartPlayback;
- /// <summary> Event queue for all listeners interested in StopPlayback events. </summary>
+ /// <summary> [Not implemented] Event queue for all listeners interested in StopPlayback events. </summary>
event SessionEventHandler ^StopPlayback;
- /// <summary> Event queue for all listeners interested in StreamingError events. </summary>
+ /// <summary> [Not implemented] Event queue for all listeners interested in StreamingError events. </summary>
event SessionEventHandler ^StreamingError;
- /// <summary> Event queue for all listeners interested in UserinfoUpdated events. </summary>
+ /// <summary> [Not implemented] Event queue for all listeners interested in UserinfoUpdated events. </summary>
event SessionEventHandler ^UserinfoUpdated;
+ ///-------------------------------------------------------------------------------------------------
/// <summary> Event queue for all listeners interested in MusicDelivered events. </summary>
+ ///
+ /// <remarks> Event-listeners on this MusicDelivered <strong>must not</strong> (ever) block.
+ /// They should simply take the samples delivered, and queue them for playback,
+ /// and then return the number of frames that were queued. SpotiFire (and libspotify)
+ /// will stop working if any listeners on the MusicDelivered event blocks. </remarks>
+ ///-------------------------------------------------------------------------------------------------
event MusicDeliveryEventHandler ^MusicDelivered;
};
}
@@ -3,12 +3,93 @@
namespace SpotiFire
{
+ ///-------------------------------------------------------------------------------------------------
+ /// <summary> The Spotify-class. </summary>
+ ///
+ /// <remarks> This class is the starting-point for all interaction with Spotify.
+ /// From here you can create a <see cref="SpotiFire.Session"/> object that
+ /// is used to fetch playlists and play tracks.</remarks>
+ /// <example> Create a new spotify-session:
+ /// <code>
+ /// <code lang="cs"><![CDATA[
+ /// using System;
+ /// using SpotiFire;
+ ///
+ /// public class SpotifyClient
+ /// {
+ /// const string CLIENT_NAME = "MyClient";
+ /// static byte[] key = new byte[] { /* insert key here */ };
+ /// static string cache = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData), CLIENT_NAME, "cache");
+ /// static string settings = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData), CLIENT_NAME, "settings");
+ /// static string userAgent = CLIENT_NAME;
+ ///
+ /// public static void Main()
+ /// {
+ /// Run().Wait();
+ /// }
+ ///
+ /// private static async Task Run()
+ /// {
+ /// var session = await Spotify.CreateSession(key, cache, settings, userAgent);
+ /// Console.WriteLine("Enter username and password (a line for each)");
+ /// await session.Login(Console.ReadLine(), Console.ReadLine(), false);
+ ///
+ /// // search playlists, play music etc
+ ///
+ /// await session.Logout();
+ /// }
+ /// }
+ /// ]]></code>
+ /// <code lang="vb"><![CDATA[
+ /// Imports System
+ /// Imports SpotiFire
+ ///
+ /// Public Class SpotifyClient
+ /// Const CLIENT_NAME As String = "MyClient"
+ /// ' insert key here
+ /// Shared key As Byte() = New Byte() {}
+ /// Shared cache As String = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData), CLIENT_NAME, "cache")
+ /// Shared settings As String = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData), CLIENT_NAME, "settings")
+ /// Shared userAgent As String = CLIENT_NAME
+ ///
+ /// Public Shared Sub Main()
+ /// Run().Wait()
+ /// End Sub
+ ///
+ /// Private Shared Function Run() As Task
+ /// Dim session = Await Spotify.CreateSession(key, cache, settings, userAgent)
+ /// Console.WriteLine("Enter username and password (a line for each)")
+ /// Await session.Login(Console.ReadLine(), Console.ReadLine(), False)
+ ///
+ /// ' search playlists, play music etc
+ ///
+ /// Await session.Logout()
+ /// End Function
+ /// End Class
+ /// ]]></code>
+ /// </code></example>
+ ///-------------------------------------------------------------------------------------------------
public static class Spotify
{
static readonly object _lock = new object();
static Session _session;
static Task<Session> _task;
+ ///-------------------------------------------------------------------------------------------------
+ /// <summary> Creates a session. </summary>
+ ///
+ /// <remarks> This method should only be called once per process. Also, the application should
+ /// make sure there never is more than one instance running at once. </remarks>
+ ///
+ /// <exception cref="InvalidOperationException"> Thrown when a session has already been created. </exception>
+ ///
+ /// <param name="applicationKey"> The application key. </param>
+ /// <param name="cacheLocation"> The cache location. </param>
+ /// <param name="settingsLocation"> The settings location. </param>
+ /// <param name="userAgent"> The user agent. </param>
+ ///
+ /// <returns> A new spotify-session. </returns>
+ ///-------------------------------------------------------------------------------------------------
public static Task<Session> CreateSession(byte[] applicationKey, string cacheLocation, string settingsLocation, string userAgent)
{
lock (_lock)
@@ -22,6 +103,11 @@ public static Task<Session> CreateSession(byte[] applicationKey, string cacheLoc
return _task;
}
+ ///-------------------------------------------------------------------------------------------------
+ /// <summary> Get's the pending task that represents the creation of a Session object. </summary>
+ ///
+ /// <value> The task. </value>
+ ///-------------------------------------------------------------------------------------------------
public static Task<Session> Task
{
get
@@ -30,6 +116,11 @@ public static Task<Session> Task
}
}
+ ///-------------------------------------------------------------------------------------------------
+ /// <summary> Gets the current session. </summary>
+ ///
+ /// <value> The session. </value>
+ ///-------------------------------------------------------------------------------------------------
public static Session Session
{
get
Oops, something went wrong. Retry.

0 comments on commit fa1fa5d

Please sign in to comment.