Es stellt sich zuerst die Frage: Was wollen wir? Ich für meinen Teil würde z.B. gerne wissen, wo und wann Kasabian demnächst Konzerte geben (Nicht, dass die Chance bestünde, das München auf der Liste wäre, aber dennoch…), und somit böte sich der API-Aufruf artist.getEvents zur näheren Betrachtung an: Welche Parameter hat er, wie muss er ausgeführt werden und wie sieht die Antwort aus?

Wir sehen, dass es zwei Parameter gibt (“artist” und “api_key”, beide benötigt) und dass die Antwort ein XML-Dokument ist, dass die Wurzel “lfm” hat, anschließend den Knoten “events” und viele Kindknoten “event”, die die einzelnen Konzerte enthalten. Diese wiederum besitzen Werte für die auftretenden Künstler, den Ort, die Zeit, Ticketverkäufe, etc… Das Beispiel von der API-Seite:

<events artist="Cher" xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#" total="4">
<event>
    <id>599858</id>
  <title>Cher</title>
  <artists>
    <artist>Cher</artist>
    <headliner>Cher</headliner>
  </artists>
  <venue>
    <name>The Colosseum at Caesars Palace</name>
    <location>
      <city>Las Vegas</city>
      <country>United States</country>
      <street></street>
      <postalcode></postalcode>
      <geo:point>
         <geo:lat>36.2265501474709</geo:lat>
         <geo:long>-115.0048828125</geo:long>
      </geo:point>
      <timezone>PST</timezone>
     </location>
    <url>http://www.last.fm/venue/8841108</url>
  </venue>
  <startDate>Sat, 16 Aug 2008</startDate>
  <startTime>19:30</startTime>
  <description></description>
  <image size="small">...</image>
  <image size="medium">...</image>
  <image size="large">...</image>
  <attendance>42</attendance>
  <reviews>0</reviews>
  <tag>lastfm:event=669027</tag>
  <url>http://www.last.fm/event/599858</url>
  <website>http://...</website>
  <tickets>
    <ticket supplier="...">http://...</ticket>
    ...
  </tickets>
</event>
...
</events>

SharpConnect stellt die folgenden Klassen zur Verfügung:

• SharpConnect.Apitizer.Apitizer bzw. SharpConnect.Xml.XmlApitizer zur Verwaltung von Methoden
• SharpConnect.Apitizer.Method zur Darstellung von Methoden
• SharpConnect.Apitizer.Parameters zur Darstellung von Parametern
• SharpConnect.Apitizer.Accessor als Zugriffsklasse für Antworten
• SharpConnect.Apitizer.Rule bzw. SharpConnect.Xml.XmlRule zur Darstellung von Accessor-Regeln
• SharpConnect.Apitizer.Codec bzw. SharpConnect.Xml.XmlCodec zur Umwandlung von Anfragen und Antworten.

Mehr brauchen wir eigentlich nicht, und auch, wenn das keine wirklich kurze Liste ist, die Verwendung der einzelnen Klassen ist nicht besonders kritisch. Beginnen wir mit dem schwersten, dem Codec.

Wenn wir diesen auf Basis von XmlCodec aufbauen, haben wir die Hälfte schon geschafft:  die Antworten (Response) werden automatisch in einen Accessor für XML umgewandelt und können anschließend anhand der Regeln, die wir noch definieren werden, durchlaufen werden. Was wir noch machen müssen, ist, die Daten, die gesendet werden sollen (Request), vorzubereiten. LastFM erwartet die einzelnen Parameter als Query-String von Name-Wert-Paaren, also z.B.:

method=artist.getEvents&artist=Cher&api_key=b25b959554ed76058ac220b7b2e0a026

Der API-Key wird immer angehängt, bei Anfragen, die Daten verändern, sogar noch eine Session und ein API-Secret, diese lassen wir jedoch hier unter den Tisch fallen. Man muss es ja nicht gleich übertreiben. Unser Last.FM Codec könnte also folgendermaßen aussehen:

 public class LastFMCodec : XmlCodec
 {
   private string apiKey;

   public LastFMCodec(string key)
     : base("lfm", null)
   {
     this.apiKey = key;
   }

   public override Request Encode(Method m, Parameters p)
   {
     string method = m.Name;
     string query = "method=" + method + "&";
     query += p.QueryString("&", "=");
     query += "api_key=" + this.apiKey + "&";
     if (m.IsPOST) return new Request("", query);
     else return new Request(query, "");
   }
 }

Das wars auch schon. Das meiste wird ohnehin von SharpConnect erledigt, sodass wir uns nun auf den Apitizer konzentrieren können. Auch hier ist die Klasse XmlApitizer eine wunderbare Grundlage, die nicht viele Ergänzungen benötigt:

 public class LastFMApitizer : XmlApitizer
 {
   public LastFMApitizer(string key, WebProxy p)
     : base("http://ws.audioscrobbler.com/2.0/", new LastFMCodec(key), p)
   {
      AddMethods(this);
   }

   private static void AddMethods(XmlApitizer api) {
     // Methods here!
   }
 }

Wir haben nun also einen Apitizer erstellt, der alle Anfragen an “http://ws.audioscrobbler.com/2.0/” sendet und den soeben definierten Codec verwendet. Nun müssen wir dem Apitizer nur noch sagen, was er eigentlich kann.

Eine Methode wird definiert durch

• einen Namen,
• eine Liste von Parameter-Namen,
• eine Liste von boolschen Werten, die angibt, welche Parameter benötigt werden, sowie
• einen Wert der angibt, ob die Anfrage über HTTP-POST läuft oder nicht.

In unserem Fall sieht dies nun folgendermaßen aus (Der API-Key wird im Encoder automatisch hinzugefügt!):

 Method artistGetEvents = new Method(
   "artist.getEvents",
   new String[] { "artist" },
   new bool[] { true },
   false
 );

Was machen wir nun mit der Antwort dieses Aufrufs? Die Antwort: wir verwenden die Klasse XmlRule, um Zuordnungen zwischen Attributnamen und Knoten des Antwortdokuments herzustellen. Das Mittel der Wahl ist hierbei XPath.

 XmlRule Image = new XmlRule();
 Image.Set("URL", "self::node()");
 Image.Set("Size", "@size");

 XmlRule Event = new XmlRule();
 Event.Set("Name", "title");
 Event.Set("ID", "id");
 Event.Set("Artists", "artists/artist");
 Event.Set("Headliner", "artists/headliner");
 Event.Set("Date", "startDate");
 Event.Set("Time", "startTime");
 Event.Set("Description", "description");
 Event.Set("Images", "image", Image);             // !!!
 Event.Set("Attendance", "attendance");
 Event.Set("ReviewCount", "reviews");
 Event.Set("UniqueTag", "tag");
 Event.Set("Website", "website");

 XmlRule rule = new XmlRule();
 rule.Set("Count", "/lfm/events/@total");
 rule.Set("Events", "/lfm/events/event", Event); // !!!

Zuerst wird eine Bild-Regel definiert: das Attribut “URL” liefert den Wert des Knotens, “Size” den Wert des “size”-Attributs. Die beiden blauen Zeilen zeigen die Verwendung von bestehenden Regeln als Unterobjekte: die Regel “Image” ist auf alle Knoten anwendbar, die über das Attribut “Images” gefunden werden, d.h. jeder Knoten aus “Images” erlaubt wieder Zugriff auf “URL” und “Size”. Gleiches für “Events”: alle Knoten, die über den XPath-Ausdruck “/lfm/events/event” gefunden werden, haben Attribute “Name”, “ID”, “Artists”, …

Wir müssen nur noch dem Decoder sagen, dass er diese Regel verwenden soll, wenn er eine Antwort auf eine “artist.getEvents”-Anfrage erhält. Dies geschieht durch gleichzeitiges Registrieren der Methode im Apitizer und Codec mittels “Apitizer.Method” (Wir befinden uns wieder in der statischen Funktion “AddMethods” von oben):

api.Method(artistGetEvents, rule);

Und nun sind wir fertig.

Beispiel gefällig?

Das folgende Beispiel funktioniert mit meiner aktuellen Implementierung von SharpConnect. Neu im Vergleich zum eben besprochenen ist nur die Klasse “LastFMValue”, die den Accessor für XML-Dokumente darstellt:

 LastFMApitizer lfm = new LastFMApitizer("b25b959554ed76058ac220b7b2e0a026", "", null);

 LastFMValue resp = lfm.Execute("artist.getEvents", new Parameters(
   "artist", "Kasabian"
 ));
 if (resp != null)
 {
   Console.Write(resp.ToString()); // oder z.B. Console.Write(resp.All("Events")[2].Value("Date"));
 }
 Console.ReadLine();

Die Ausgabe sieht so oder  ähnlich aus (auf all diese Attribute und Array-Elemente könnte man mittels “resp.Get(attribut)”  und “resp.All(attribut)” zugreifen, vgl. den Concept-Artikel):

  Status : ok
  Count : 14
  Events[0] :
    Status : ok
    Name : Kasabian
    ID : 1408186
    URL : http://www.last.fm/event/1408186+Kasabian+at+Tivoli+Oudegracht+on+27+May+2010
    Artists : Kasabian
    Headliner : Kasabian
    Date : Thu, 27 May 2010 12:08:01
    Description : ...
    Images[0] :
      URL : http://userserve-ak.last.fm/serve/34/284053.jpg
      Size : small
    Images[1] :
      URL : http://userserve-ak.last.fm/serve/64/284053.jpg
      Size : medium
    Images[2] :
      URL : http://userserve-ak.last.fm/serve/126/284053.jpg
      Size : large
    Images[3] :
      URL : http://userserve-ak.last.fm/serve/252/284053.jpg
      Size : extralarge
    Attendance : 87
    ReviewCount : 0
    UniqueTag : lastfm:event=1408186
    Website : http://www.tivoli.nl/agenda/informatie/datum/do-27-mei-2010/titel/KASABIAN
  Events[1] :
    Status : ok
    Name : Pinkpop 2010
    ID : 932823
    URL : http://www.last.fm/event/932823+Pinkpop+2010
    Artists[0] : Green Day
    Artists[1] : Pixies
    Artists[2] : Kasabian
    Artists[3] : The Prodigy
    Artists[4] : Rammstein
    Artists[5] : John Mayer
    Artists[6] : Editors
    Artists[7] : Mika
    Artists[8] : Wolfmother
    Artists[9] : Kate Nash
    Artists[10] : Mando Diao
    Artists[11] : Paolo Nutini
    Artists[12] : P!nk
    Artists[13] : Florence + The Machine
    Artists[14] : Skunk Anansie
    Artists[15] : Gogol Bordello
    Artists[16] : Biffy Clyro
    Artists[17] : Yeasayer
    Artists[18] : The Temper Trap
    Artists[19] : Danko Jones
    Artists[20] : Gossip
    Artists[21] : 2 Many DJ's
    Artists[22] : Moke
    Artists[23] : Kitty, Daisy & Lewis
    Artists[24] : Caro Emerald
    Artists[25] : Triggerfinger
    Artists[26] : Destine
    Artists[27] : DeWolff
    Artists[28] : Sungrazer
    Headliner : Green Day
    Date : Fri, 28 May 2010 21:24:01
    Description : ...
    Images[0] :
      URL : http://userserve-ak.last.fm/serve/34/42600061.jpg
      Size : small
    Images[1] :
      URL : http://userserve-ak.last.fm/serve/64/42600061.jpg
      Size : medium
    Images[2] :
      URL : http://userserve-ak.last.fm/serve/126/42600061.jpg
      Size : large
    Images[3] :
      URL : http://userserve-ak.last.fm/serve/252/42600061.jpg
      Size : extralarge
    Attendance : 560
    ReviewCount : 1
    UniqueTag : lastfm:event=932823
    Website : http://www.pinkpop.nl
  Events[2] :
    Status : ok
    Name : Kasabian
  ...

Ich arbeite im Moment an einer vollständigen Abbildung des Last.FM-APIs, auch wenn ich nicht weiß, ob ich das nicht lieber jedem selbst überlassen sollte. In den Worten von Morpheus:

I can only show you the door, you have to walk through it!

Und heute war ich dann soweit, dass ich eine gar nicht so üble Version vor mir hatte, die ich nun (nicht detailliert, eher angeberischerweise ) präsentieren will. Vorhang auf für Scripe!

(Der Name hat mehrere Hintergründe: zum einen wäre da der Schreibfehler, der schonmal beim Wort “Scripte” auftaucht, zum anderen findet sich ein Ursprung im englischen “to scribe”, was soviel wie “vorzeichnen” bedeutet. Zuguterletzt sagt einem das allwissende Urban Dictionary, das “scripe” das Äquivalent von “a load of rubbish”, also etwas nicht ganz hochwertigem ist. Das ist auch in Ordnung so: Scripe ist der Weg, den ich einschlagen würde, wenn ich eine Scriptsprache zu entwickeln hätte. Zwar sind Grundkonzepte, die sich auch im professionelleren Einsatz finden, vorhanden, aber Scripe erhebt in dieser Hinsicht keinerlei Anspruch auf Vollständigkeit oder übermäßige Effizienz. “Quick and Dirty” wäre dennoch übertrieben, dann doch eher “Quick and Not-So-Clean“…)

Die Suppe im Titel lässt das Prinzip erahnen: Suppen brauchen Gewürze, um zu schmecken, und hierbei ist es wichtig auf die Mischung zu achten. Ebenso wird jeder seine Suppe anders würzen, je nach Vorlieben oder Vorhaben. Eine Scriptsprache ist da nicht anders: hier eine Prise Variablenverwaltung, dort ein Löffel Arithmetik. Voilà.

Dieses Suppenprinzip findet man heutzutage überall, hauptsächlich in der Unix/Linux-Welt, wo man je nach Bedarf auf einfachste Art und Weise ein Paket nachladen kann und das Gesamtsystem somit bis ins letzte Eck modifizierbar bleibt. Auch Scripe verwendet solche Pakete, allerdings eben für die Features der Programmiersprache!

Folgender C#-Code erzeugt einen Prozessor, der den Shunting-Yard-Algorithmus verwendet, um die Eingabe zu parsen. Anschließend erhält er vier Pakete: eines für arithmetische Operationen, eines für String-Operationen, eines für Ein- und Ausgabe, und eines für Variablendefinition und -verwaltung. Anschließend wird eine Eingabe-Auswertungs-Schleife gestartet.

// Create processor
Processor p = new Processor(
    new ShuntingYardAlgorithm()
);

// Add packages
p.AddPackage(new Scripe.Evaluators.Arithmetic.ArithmeticPackage(true));
p.AddPackage(new Scripe.Evaluators.Strings.StringPackage("&", "$"));
p.AddPackage(new Lapicon.Evaluators.InputOutput.InputOutputPackage());
p.AddPackage(new Lapicon.Evaluators.Variables.VariablePackage());

// Empty codebase
Codebase c = new Codebase(new Scripe.Env.Environment());

// Read-Eval-Print-Loop
string r = "";
while (true)
{
    try
    {
        Console.Write("Calc: ");
        if ((r = Console.ReadLine()) == "exit") break;
        c.Add(r);
        Console.WriteLine(" ==> " + c.Execute(p).ReturnValue);
    }
    catch (Exception ex)
    {
        Console.WriteLine(" ERROR: " + ex.Message);
    }
}

In nur 5 Zeilen haben wir hier (mithilfe der Scripe-internen und zweier für Lapicon geschriebenen Pakete) einen Prozessor geschaffen, der jede der folgenden Eingaben auswerten kann:

1+(4-6)*(3-4^5)+e
def variable = 7*8
def variableDurchZwei = <variable>/2
echo "(7*8)/2 = " & $(<variableDurchZwei>)

Und nun stelle man sich eine Internetseite vor, die eine gewisse Anzahl solcher Pakete anbietet. Scriptsprachen entwickeln einfach gemacht.

Soviel also von mir. Wann Scripe letztlich ganz fertig ist (und ich mich wieder den anderen Projekten wie LastSharp widmen kann), kann ich nur schätzen. Ist ein Monat in Ordnung?

Da im Moment anscheinend wieder Änderungen am Last.FM-Webservice gemacht werden, die dazu geführt haben, dass LastSharp höchstens noch mithilfe der “Modifizierten Verbindung” (unter “Erweiterte Einstellungen” >> “Verschiedenes”) funktioniert, habe ich mir mal das Radio-API angesehen, das ja anscheinend die Zukunft des Radiostreamings bei Last.FM ist. Was mich daran allerdings stört, ist die umständliche Anmeldeprozedur: Token holen, Browser öffnen, auf Authentifizierung warten, Session holen.

Der Umweg über den Browser ist einfach unschön, weshalb ich nach einer Lösung gesucht habe, die den Login sowie die anschließende Bestätigung eines Users im Hintergrund simuliert, sodass er das eigentliche Programm nicht verlassen muss.

Funktionen, die Authentication-Token und -Session holen, werden im folgenden als gegeben betrachetet, z.B. durch LastFmLib.Net.

Wir brauchen nun also zwei Funktionen, die das Abschicken des Login-Formulars und das Klicken auf den “Zulassen”-Button vortäuschen. Beide Operationen produzieren eine HTTP-POST-Anfrage, funktionieren aber nur, wenn auch die richtigen Cookies vorhanden sind. (Das hat mich einige Zeit gekostet und dabei war die Lösung so einfach…) Es bietet sich an, die POST-Anfrage in eine Hilfsfunktion ExecutePOST zu packen, hier z.B. in C#:
(Namespace System.Net muss eingebunden sein)

// Löst das Cookie Problem: Immer denselben Container verwenden!
private static CookieContainer GlobalCookies = new CookieContainer();

// Sendet eine POST-Anfrage
public static void ExecutePOST(string uri, string data) {
    try
    {
        // Bereite die Anfrage vor
        HttpWebRequest request = (HttpWebRequest)WebRequest.Create(uri);
        request.Method = "POST";
        request.CookieContainer = GlobalCookies; // !!
        request.ContentType = "application/x-www-form-urlencoded";
        request.ContentLength = data.Length;

        // Schreiben der Daten
        ASCIIEncoding enc = new ASCIIEncoding();
        byte[] bdata = enc.GetBytes(bodyData);
        Stream str = req.GetRequestStream();
        str.Write(bdata, 0, bdata.Length);
        str.Close();

        // Schicke Anfrage ab und verwirf die Antwort
        HttpWebResponse response = (HttpWebResponse)request.GetResponse();
        response.Close();
    }
    catch { }
}

Will man überprüfen, ob die gewünschte Operation erfolgreich war, würde es sich vermutlich anbieten, die Antwort auszuwerten, aber darauf verzichte ich jetzt aus Zeitgründen.

Nächster Schritt ist die Untersuchung der Formulare auf der Last.FM-Seite, damit man weiß, welche Daten an welche Adresse gesendet werden müssen:

• Login: https://www.last.fm/login/
  • refererKey (leer)
  • backto (“/”)
  • username (Benutzername)
  • password (Passwort)
• Zulassen: http://www.last.fm/api/grantAccess
  • api_key (Last.FM schickt den sogar zweimal, wir deshalb sicherheitshalber auch…)
  • token (Authentication-Token)
  • referer (“/”)

Also, die beiden verbleibenden Funktionen in C#:

    // Lasse ein Programm zu
    public static void GrantAccess(string token)
    {
        ExecutePOST(
            "http://www.last.fm/api/grantAccess",
            "api_key=" + apiKey + "&api_key=" + apiKey + "&token=" + token + "&referer=/"
        );
    }

    // Melde den User bei Last.FM an
    public static void Login(string username, string password)
    {
        ExecutePOST(
            "https://www.last.fm/login/",
            "refererKey=&backto=/&username=" + Uri.EscapeDataString(username) +
            "&password=" + Uri.EscapeDataString(password)
        );
    }

Um jetzt eine gesamte Anmeldung zu simulieren, müsste man nun folgendes machen:

public static void Authenticate(string username, string password)
{
    string token = GetToken(); // irgendeine externe Funktion
    Login(username, password);
    GrantAccess(token);
    string session = GetSession(); // irgendeine externe Funktion
    // Mache etwas...
}

Das war’s auch schon. Wie gesagt fehlt hier ein Test, ob die Anmeldung erfolgreich war, aber irgendwie lässt sich das bestimmt einfach überprüfen. (Vllt. liefert Last.FM ja im Hintergrund einen HTTP-Error, der im Browser nicht auffällt?)

Jedenfalls, wenn jemand die Authentifizierung für das Last.FM-API 2.0 im Hintergrund ablaufen lassen will, ist das hier der Weg. Ich hoffe, es hilft.

Die Verwendung des Radio-APIs in LastSharp werde ich übrigens so lang wie möglich hinauszögern, da hier wieder einmal diverse Standards (HTTP, XML, …) unsachgemäß ausgelegt werden…

Ein ganz klarer Vorteil hiervon ist der Schutz des Clients: ein Proxy-Server bietet aufgrund seines einfacheren Aufbaus viel weniger Angriffsfläche als der eigentlich anfragende Rechner – man denke nur an die regelmäßig auftretenden Sicherheitslücken in populären Betriebssystemen – und garantiert außerdem ein gewisses Maß an Anonymität, da nur die IP des Proxies nach außen hin sichtbar ist.

Nachteile wiederum sind, dass man sich nicht sicher sein kann, was der Server protokolliert und speichert, und ob die Daten, die bei einem selbst ankommen, nicht auf dem Weg (vom Proxy) modifiziert wurden. Des weiteren werden viele Proxies von einer großen Anzahl Anwendern genutzt, was einen Geschwindigkeitsverlust im Vergleich zu “normalen” Verbindungen bedeuten kann. Ein ebenso großes Problem kann es sein, wenn Funktionen fehlen (z.B. die Möglichkeit, Daten zu übertragen oder Dateien herunterzuladen) oder wenn der Server eine Inkompatibilität zum verwendeten Programm aufweist. (z.B. Server des CoDeeN-Networks zu .NET-Programmen)

Trotzdem, genug des Geplänkels, die Verwendung eines Proxies im eigenen Programm ist nicht sonderlich schwer.

Das WebProxy-Objekt

Erster Schritt hierbei ist die Erstellung eines Objektes der Klasse System.Net.WebProxy. Hierzu brauchen wir die Adresse des Servers (ggf. seine IP) und den Port, über den er erreicht werden kann:

System.Net.WebProxy proxy =
    new System.Net.WebProxy("http://<Adresse>:<Port>", true);

Der zweite Parameter des Konstruktors gibt an, ob der Proxy für lokale Verbindungen (z.B. zu Testzwecken auf “http://localhost/”) umgangen werden soll.

Authentifizierung

Für die Authentifizierung, also für alle nicht-anonymen Proxies, muss ein System.Net.NetworkCredential-Objekt mit den entsprechenden Zugangsdaten erstellt und dem Proxy-Objekt zugewiesen werden:

System.Net.NetworkCredential auth =
    new System.Net.NetworkCredential("<Benutzername>", "<Passwort>");
proxy.Credentials = auth;

Mithilfe eines so konfigurierten Proxy-Objektes kann man nun entweder mithilfe der HttpWebRequest-Klasse HTTP-Anfragen senden, oder mithilfe der WebClient-Klasse Dateien herunterladen – beides über die von uns gewählte Zwischenstation.

HTTP-Requests über einen Proxy

System.Net.HttpWebRequest request =
    (System.Net.HttpWebRequest) System.Net.WebRequest.Create("<URI>");
request.Proxy = proxy;
System.Net.HttpWebResponse response =
    (System.Net.HttpWebResponse) request.GetResponse();
...

Datei-Download mit Proxy

System.Net.WebClient client = new System.Net.WebClient();
client.Proxy = proxy;
client.DownloadFile("<URI>", "<lokaler Pfad>");
...

Aus.

Ich hoffe, ich habe mit diesem kurzen Beitrag all jenen geholfen, die ihre Programme um Proxy-Funktionalität erweitern wollen.

Ich habe mich in letzter Zeit viel mit Last.FM beschäftigt, nicht zuletzt wegen meinen beiden Programmen LastSharp und Lea. Aufgrund eines Problems mit letzterem (Tracks/Künstler mit Umlauten machen Schwierigkeiten) habe ich mich ein wenig umgesehen und bin auf eine (angeblich vollständige) Implementierung des Last.FM-APIs in .NET gestoßen: LastFmLib.Net.

Und weil diese Bibliothek wirklich einzigartig einfach zu verwenden ist (obwohl auch hier die Umlaute noch nicht extra betrachtet werden), möchte ich meine Erfahrungen gerne teilen und eine winzige, deutschsprachige Erklärung zu ihrer Verwendung bzw. Anwendung auf das API 2.0 schreiben.

Vorbereitung

Jeder, der den Last.FM-Webservice verwenden will, benötigt zuallererst einen öffentlichen und einen dazugehörigen geheimen API-Schlüssel, den man hier beantragen kann. Da LastFmLib.Net eine Klassenbibliothek für das .NET-Framework ist, wird eine entsprechende Entwicklungsumgebung (z.B. Visual C# Express Edition) benötigt, um damit arbeiten zu können.

Hat man einen öffentlichen und einen geheimen API-Schlüssel (Key und Secret) erhalten, so muss man LastFmLib.Net diese beiden mitteilen. Dies geschieht, indem man das LastFmLib.API20.Settings.AuthData-Objekt neu setzt, in C# beispielsweise:

LastFmLib.General.MD5Hash key
    = new LastFmLib.General.MD5Hash("APIKey", true, Encoding.UTF8);
LastFmLib.General.MD5Hash secret
    = new LastFmLib.General.MD5Hash("APISecret", true, Encoding.UTF8);
LastFmLib.API20.Settings20.AuthData
    = new LastFmLib.API20.Types.AuthData(key, secret, null);

Hat man das nun erledigt, kann man (nach der Authentifizierung) auf die einzelnen API-Methoden zugreifen.

Allgemein: Request schicken

In LastFmLib.Net sind alle Anfragen an das API in Klassen gekapselt. Für jede Art von Anfrage (Request) erstellt man also ein entsprechendes Objekt, startet die Verarbeitung, überprüft ob die Anfrage erfolgreich war und verarbeitet das Ergebnis. Alle Requests befinden sich im Namespace LastFmLib.API20.<Art>, wobei <Art> die entsprechende Obergruppe einer Anfrage ist, z.B. “Auth”, “User”, “Playlists”, etc… Diese Obergruppen sieht man auf der API-Seite fettgedruckt in der Spalte links.

In C# würde das also so aussehen:

LastFmLib.API20.<Art>.<Irgendeine Request> req
    = new LastFmLib.API20.<Art>.<Irgendeine Request>(<notwendige Parameter>);
req.Start();
if (req.Succeeded) {
    // Mach etwas mit dem Ergebnis
} else {
    // Mach etwas mit dem Fehler (req.ErrorMessage)
}

Authentifizierung

Alles beginnt mit der Anmeldung des Users. Bei Last.FM geht dies in drei Schritten vonstatten:

1. Holen des sog. “Tokens”, der sozusagen das Passwort für alle nun kommenden Anfragen darstellt und nur eine begrenzte Zeit gültig ist. Dies geschieht mit der API-Methode getToken():

   LastFmLib.API20.Auth.AuthGetToken req
       = new LastFmLib.API20.Auth.AuthGetToken();
   req.Start();
   if (req.Succeeded) {
       // Token speichern
       LastFmLib.API20.Settings20.AuthData.Token = req.Result;
   } else {
       // Mach etwas mit dem Fehler
   }

2. Zulassung des Programms für den eigenen Last.FM-Account. Hierfür wird der Browser geöffnet, sodass der User sich einloggen und die entsprechende Berechtigung vergeben kann. LastFmLib.Net stellt hierfür auch gleich eine Funktion bereit (1.Parameter: Anwendung unterbrechen, 2. Parameter: Timeout):

   LastFmLib.API20.Settings.AuthData.AskUserToGrantPermissions(false, 0);

3. Holen der Session-Informationen (Benutzername, Session-Key, Subscriber-Status) mit der Methode getSession(token). Achten Sie darauf, dass dieser Schritt auch wirklich erst nach der Bestätigung im Browser ausgeführt wird, ansonsten klappt das Holen der Informationen nämlich nicht.

   LastFmLib.API20.Auth.AuthGetSession sk =
       new LastFmLib.API20.Auth.AuthGetSession(LastFmLib.API20.Settings20.AuthData.Token, false);
   sk.Start();
   if (sk.Succeeded)
   {
       // Session speichern
       LastFmLib.API20.Settings20.AuthData.Session = sk.Result;
   }
   else {
       // Mach etwas mit dem Fehler
   }

Wenn diese drei Schritte erfolgreich ausgeführt wurden, kann man die eigentlichen Anfragen starten, immer nach dem oben genannten Muster.

Beispiel: Playlisten eines Users holen

LastFmLib.API20.User.UserGetPlaylists req =
    new LastFmLib.API20.User.UserGetPlaylists(LastFmLib.API20.Settings20.AuthData.Session.Username);
gp.Start();
if (gp.Succeeded)
{
    foreach (LastFmLib.API20.Types.SimplePlaylist pl in gp.Result) {
        // Playliste verarbeiten
    }
} else {
    // Mach etwas mit dem Fehler
}

Anmerkungen

Der Aktualität halber sollte man nicht die vorgefertigte DLL von der Website des Entwicklers laden, sondern die neuesten Quelldateien aus dem SVN-Verzeichnis, um daraus die letztendliche Bibliothek zu erstellen. Dies geht mithilfe von Subversion und dem Befehl:

svn co https://lastfmlibnet.svn.sourceforge.net/svnroot/lastfmlibnet lastfmlibnet

Eine entsprechende Dokumentation der Klassenbibliothek findet sich auch im SVN-Verzeichnis. Vor allem, wenn man keine Möglichkeit hat, über die Entwicklungsumgebung Informationen zu einzelnen Funktionen zu erhalten (Parametertypen/-anzahl, Rückgabetyp), sollte man sich darin vertiefen.

Mein Programm Lea (ab Version 1.2) ist dank LastFmLib.Net keine große Sache mehr, dafür (hoffentlich) um einiges stabiler und wartungsfreundlicher.

So, ich hoffe, dieses HowTo hat ein wenig geholfen. Weitere Informationen und natürlich auch Support gibt es auf der Website des Entwicklers.

Über dieses Tutorial bin ich der Sache näher gekommen: Man muss eine eigene Implementierung des Interfaces IFileFactory erstellen, und – falls nötig – eine eigene Stream-Klasse. Und letzteres war durchaus nötig, da mir keine bereitgestellte Stream-Klasse die entsprechenden Möglichkeit der Pufferung eines Audiostreams geboten hat. So ist die Klasse InternetStream geboren worden, die eine Verbindung zu einer Datei im Internet herstellt (mittels HttpWebRequest), und die empfangenen Daten in einer Datei auf der Festplatte speichern kann, auf die ebenso die Möglichkeit gleichzeitigen Zugriffs besteht:

using System;
using System.Collections.Generic;
using System.Text;
using System.IO;
using System.Net;
using System.Threading;
using System.Windows.Forms;
using System.Collections;
using IrrKlang;

public class InternetStream : Stream
{
    // =======================================================
    // Buffer-Daten
    private Stream resp = null;
    private string BufferFile = "streaming.mp3";
    private FileStream OutputStream = null;
    private FileStream BufferStream = null;
    private Thread BufferThread = null;
    // =======================================================
    // Konstruktor
    public InternetStream(string uri, string bfile)
    {
        // Dateiname des lokalen Files
        this.BufferFile = bfile;
        // FileStream zum Schreiben öffnen
        if (File.Exists(this.BufferFile)) { try { File.Delete(this.BufferFile); } catch { } }
        this.BufferStream = new FileStream(this.BufferFile, FileMode.OpenOrCreate, FileAccess.Write, FileShare.Read);
        // ResponseStream zum File im Internet
        this.resp = ((HttpWebRequest)WebRequest.Create(uri)).GetResponse().GetResponseStream();
        // Pufferung starten
        this.BufferThread = new Thread(new ThreadStart(this.FillBuffer));
        this.BufferThread.Start();
    }
    // =======================================================
    // Read: wenn zehn mal 0 zurückgegeben wird, werden alle
    // Streams geschlossen und der Thread beendet
    private int ReadTries = 0;
    public override int Read(byte[] array, int offset, int count)
    {
        // Ausgabe-Stream öffnen
        if (this.OutputStream == null) this.OutputStream = new FileStream(this.BufferFile, FileMode.Open, FileAccess.Read, FileShare.ReadWrite);
        try
        {
            // Dem Puffer Zeit geben, Daten zu holen
            while (this.OutputStream.Length == 0) Thread.Sleep(100);
            // Daten lesen
            int s = this.OutputStream.Read(array, offset, count);
            // Wenn 0: ein erfolgloser Versuch mehr
            if (s == 0) this.ReadTries++;
            if (this.ReadTries > 10)
            {
                this.Close();
            }
            //
            return s;
        }
        catch { return 0; }
    }
    // =======================================================
    // Seek
    public override long Seek(long offset, SeekOrigin loc)
    {
        return this.OutputStream.Seek(offset, loc);
    }
    // =======================================================
    // Puffer-Thread
    private void FillBuffer()
    {
        byte[] buffer = new byte[20 * 1024];
        int rd = 0;
        while ((rd = this.resp.Read(buffer, 0, buffer.Length)) > 0)
        {
            this.BufferStream.Write(buffer, 0, rd);
        }
    }
    // =======================================================
    // Schließen
    public override void Close()
    {
        this.OutputStream.Close();
        this.BufferStream.Close();
        this.BufferThread.Abort();
        if (File.Exists(this.BufferFile))
            try { File.Delete(this.BufferFile); }
            catch { }
        base.Close();
    }
    // =======================================================
    // Length
    public override long Length
    {
        get
        {
            if (this.OutputStream == null) return 0;
            else return this.OutputStream.Length;
        }
    }
    // =======================================================
    // Properties: CanRead, CanSeek, CanWrite
    public override bool CanRead
    {
        get { return true; }
    }

    public override bool CanSeek
    {
        get { return true; }
    }

    public override bool CanWrite
    {
        get { return false; }
    }
    // =======================================================
    // restliche Methoden, damit die Stream-Implementierung
    // komplett ist
    public override void Flush()
    {
        this.OutputStream.Flush();
    }

    public override long Position
    {
        get
        {
            return this.OutputStream.Position;
        }
        set
        {
            this.OutputStream.Position = value;
        }
    }

    public override void SetLength(long value)
    {
        this.OutputStream.SetLength(value);
    }

    public override void Write(byte[] buffer, int offset, int count)
    {
        return;
    }
}

Die entsprechende IFileFactory-Implementation:

public class StreamFileFactory : IFileFactory
{
    // =====================================
    // Öffne ein File (von Irrklang verwendete Methode)
    public Stream openFile(string filename)
    {
        if (filename.StartsWith("http://"))
        {
            // neuen Starten
            string fn = Application.StartupPath + "/streaming.mp3";
            try
            {
                InternetStream istream = new InternetStream(filename, fn);
                return istream;
            }
            catch { return null; }
        }
        else
        {
            // lokale Datei
            return new FileStream(filename, FileMode.Open, FileAccess.Read);
        }
    }
}

using System;
/*
 * [class] mp3Gain: Klasse zur Normalisierung von MP3-Dateien mithilfe von mp3Gain
 *
 * Copyright (C) 2008 Yannick Scherer
 * This program is free software; you can redistribute it and/or modify it under the terms of the GNU General
 * Public License as published by the Free Software Foundation; either version 3 of the License, or (at your
 * option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the
 * implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
 * for more details.
 *
 * You should have received a copy of the GNU General Public License along with this program;
 * if not, see http://www.gnu.org/licenses/.
 * */

using System.Diagnostics;
using System.Collections.Generic;
using System.Text;
using System.IO;

class mp3Gain
    {
        // mp3Gain-Daten
        private static Process          mp3GainProcess = null;
        private static ProcessStartInfo mp3GainProcessInfo = new ProcessStartInfo(mp3GainPath);
        private static string           mp3GainCurrentFile = "";
        public static bool              mp3GainIsRunning = false;
        public static string            mp3GainPath    { get { return System.Windows.Forms.Application.StartupPath+"/mp3gain/mp3gain.exe"; } }
        public static string            mp3GainParams { get { return "/r /d 20 /k /c /q"; } }
        // Lautstärke normalisieren
        public static void NormalizeVolume(string mp3File) {
            if (!mp3GainIsRunning && File.Exists(mp3GainPath) && File.Exists(mp3File)) {
                // Prozess läuft
                mp3GainIsRunning   = true;
                mp3GainCurrentFile = mp3File;
                // Datei, an der gearbeitet wird
                string mp3Work = mp3File+"_work.mp3";
                File.Copy(mp3File, mp3Work);
                // mp3GainProcessInfo initialisieren
                mp3GainProcessInfo.Arguments = mp3GainParams+" \""+mp3Work+"\"";
                mp3GainProcessInfo.WindowStyle = ProcessWindowStyle.Hidden;
                // mp3Gain aufrufen
                mp3GainProcess = new Process();
                mp3GainProcess.StartInfo = mp3GainProcessInfo;
                mp3GainProcess.EnableRaisingEvents = true;
                mp3GainProcess.Exited += new EventHandler(mp3GainExited);
                mp3GainProcess.Start();
            }
        }
        public static void mp3GainExited(object sender, EventArgs e)
        {
            // Daten rückkopieren
            string mp3Work = mp3GainCurrentFile + "_work.mp3";
            if (new FileInfo(mp3Work).Length > 0)
            {
                File.Copy(mp3Work, mp3GainCurrentFile, true);
                File.Delete(mp3Work);
            }
            // Reset
            mp3GainIsRunning = false;
            mp3GainCurrentFile = "";
            return;
        }

    }

Eine MP3-Datei wird normalisiert, durch den Aufruf mp3Gain.NormalizeVolume(<MP3-Datei>).

Innerhalb der Klasse müssen noch der Pfad zu mp3gain.exe (mp3GainPath) angepasst werden, sowie die gewünschten Parameter (mp3GainParams). Eine Übersicht über die Parameter von mp3Gain gibt es hier.

Batch

Ein BatchFile, das mp3Gain verwendet, könnte folgendermaßen aussehen (vorrausgesetzt, es befindet sich im selben Verzeichnis wie mp3gain.exe):

@rem // Ziehen Sie eine MP3-Datei auf dieses Batchfile, um sie zu normalisieren.

@rem // In aktuelles Verzeichnis wechseln
@cd /D %~d0%~p0

@echo --------------------------------------------------------------------
@echo Normalisieren von %1 ...
@echo --------------------------------------------------------------------
@ "%cd%/mp3gain.exe" <Parameter> %1
@echo --------------------------------------------------------------------
@echo Prozess abgeschlossen...
@echo --------------------------------------------------------------------
@pause

Dieser Code lässt sich natürlich erweitern, sodass ganze Ordner bearbeitet werden. Das überlasse ich aber jedem, der fleißig genug dafür ist…

using System;
using System.Xml;
using System.Net;
using System.IO;
using System.Text;
using System.Collections;

namespace LastFM
{
    // ====================================================
    // Klasse mit Hilfsfunktionen
    // ====================================================
    class Utilities
    {
        // MD5 erstellen
        public static string MD5(string password)
        {
            byte[] textBytes = System.Text.Encoding.Default.GetBytes(password);
            try
            {
                System.Security.Cryptography.MD5CryptoServiceProvider cryptHandler;
                cryptHandler = new System.Security.Cryptography.MD5CryptoServiceProvider();
                byte[] hash = cryptHandler.ComputeHash(textBytes);
                string ret = "";
                foreach (byte a in hash)
                {
                    if (a < 16)
                        ret += "0" + a.ToString("x");
                    else
                        ret += a.ToString("x");
                }
                return ret;
            }
            catch
            {
                throw;
            }
        }
        // Ruft eine URI auf und liefert sie als String zurück
        public static string ExecuteURI(string uri)
        {
            HttpWebRequest req = (HttpWebRequest)WebRequest.Create(uri);
            HttpWebResponse resp = (HttpWebResponse)req.GetResponse();
            StreamReader sr = new StreamReader(resp.GetResponseStream());
            string result = sr.ReadToEnd();
            sr.Close();
            return result;
        }
    }

    // ====================================================
    // Datenkapselung für Playlist und Tracks
    // ====================================================
    public class Playlist : ArrayList
    {
        public string PlaylistName = "";
        public DateTime Timestamp = new DateTime();
    }
    public class Track
    {
        public string Title="";
        public string Artist = "";
        public string Location = "";
        public string Album = "";
        public string Image = "";
        public int Duration = 0;
        // Gibt die Dauer des Tracks im Format MM:SS aus
        public string DurationString()
        {
            int sec = (this.Duration / 1000) % 60;
            int min = ((this.Duration / 1000) - sec) / 60;
            return ((min < 10) ? "0" : "") + min + ":" + ((sec < 10) ? "0" : "") + sec;
        }
    }

    // ====================================================
    // Handshake-Klasse für Bereitstellung der Handshake-Daten
    // ====================================================
    public class Handshake : Hashtable
    {
        /// Verarbeitet die Handshake-Rückgabe
        public Handshake(string HandshakeString)
        {
            string[] lines = HandshakeString.Split('\n');
            foreach (string line in lines)
            {
                string[] p = line.Split('=');
                this.Add(p[0], p[1]);
            }
            if (!this.ContainsKey("session") || !this.ContainsKey("base_path") ||
                !this.ContainsKey("base_url"))
            {
                throw new Exception("Ungültiger Handshake! (Passwort falsch?)");
            }
        }
        // Daten (nur die wichtigsten)
        public string SessionID  { get { return (string) this["session"]; } }
        public string BasePath   { get { return (string) this["base_path"]; } }
        public string BaseURL    { get { return (string) this["base_url"]; } }
        public string RequestURL { get { return "http://" + this.BaseURL + this.BasePath + "/"; } }
        // Der Hashtable ist nicht veränderbar
        public override bool IsReadOnly
        {
            get
            {
                return true;
            }
        }
    }

    // ====================================================
    // XMLProcessor-Klasse
    // ====================================================
    public class XMLProcessor
    {
        // ========================================
        // based on: http://code.google.com/p/thelastripper/wiki/LastFM12UnofficialDocumentation
        // ========================================
        // Login-Daten
        private string user;
        private string password;
        //aktuelle Radiostationsdaten
        private bool tuned_in = false;
        private string to_station = null;
        //
        public bool TunedIn { get { return tuned_in; } }
        public string Station { get { return to_station; } }
        public string Username { get { return user; } }
        // ========================================
        public XMLProcessor(string username, string password)
        {
            this.user        = username;
            this.password = Utilities.MD5(password);
        }
        ///
        /// Führt einen Handshake mit LastFM aus.
        ///
        public Handshake DoHandshake()
        {
            // Request ausführen
            string uri =
                "http://ws.audioscrobbler.com/radio/handshake.php?version=1.3.1.1" +
                "&platform=win32&username=" + this.username + "&passwordmd5="
                + this.password + "&language=de&player=lastsharp";
            string resp = Utilities.ExecuteURI(uri);
            // Daten verarbeiten (in Handshake-Klasse)
            return new Handshake(resp);
        }

        ///
        /// Setzt die Radiostation
        ///
        public bool TuneIn(Handshake hs, string station)
        {
            // Operation ausführen
            string uri = hs.RequestURL + "adjust.php?session=" + hs.SessionID + "&url=" + station + "〈=de";
            string resp = Utilities.ExecuteURI(uri);
            // Überprüfen + Status setzen
            if (resp.StartsWith("response=OK"))
            {
                this.tuned_in = true;
                this.to_station = station;
                return true;
            }
            else
            {
                this.tuned_in = false;
                this.to_station = null;
                return false;
            }
        }

        ///
        /// Ruft die Playlist ab
        ///
        public Playlist GetPlaylist(Handshake hs)
        {
            // Radiostation ausgewählt?
            if (!this.tuned_in) throw new Exception("Keine Radiostation angewählt.");
            // Playlist abrufen
            string uri =
                  hs.RequestURL + "xspf.php?sk=" + hs.SessionID +
                  "&discovery=0&desktop=1.3.1.1";
            string resp = Utilities.ExecuteURI(uri);
            XmlDocument doc = new XmlDocument();
            doc.LoadXml(resp);
            // =========================================
            // Verarbeiten
            // =========================================
            Playlist pl = new Playlist();
            XmlNode root = doc.FirstChild;
            if (root.Name != "playlist")
                throw new Exception("Ungültiges XML-Format der Playlist");
            // Titel der Playlist + Timestamp
            XmlNode pl_title = root.SelectSingleNode("title");
            if (pl_title != null) pl.PlaylistName = pl_title.InnerText;
            pl.Timestamp = DateTime.Now;
            // Tracklist
            XmlNode pl_tracks = root.SelectSingleNode("trackList");
            if (pl_tracks != null) for (int i = 0; i < pl_tracks.ChildNodes.Count; i++)
                {
                    {
                        XmlNode trn = pl_tracks.ChildNodes[i];
                        Track tr = new Track();
                        tr.Artist     = trn.SelectSingleNode("creator").InnerText;
                        tr.Album    = trn.SelectSingleNode("album").InnerText;
                        tr.Title      = trn.SelectSingleNode("title").InnerText;
                        tr.Location = trn.SelectSingleNode("location").InnerText;
                        tr.Image    = trn.SelectSingleNode("image").InnerText;
                        tr.Duration = Convert.ToInt32(trn.SelectSingleNode("duration").InnerText);
                        pl.Add(tr);
                    }
                }
            return pl;
        }
    }
}