/thirdparty/liblastfm2/src/ws/ws.h

  1/*
  2   Copyright 2009 Last.fm Ltd. 
  3      - Primarily authored by Max Howell, Jono Cole and Doug Mansell
  4
  5   This file is part of liblastfm.
  6
  7   liblastfm is free software: you can redistribute it and/or modify
  8   it under the terms of the GNU General Public License as published by
  9   the Free Software Foundation, either version 3 of the License, or
 10   (at your option) any later version.
 11
 12   liblastfm is distributed in the hope that it will be useful,
 13   but WITHOUT ANY WARRANTY; without even the implied warranty of
 14   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 15   GNU General Public License for more details.
 16
 17   You should have received a copy of the GNU General Public License
 18   along with liblastfm.  If not, see <http://www.gnu.org/licenses/>.
 19*/
 20#ifndef LASTFM_WS_H
 21#define LASTFM_WS_H
 22
 23#include <lastfm/global.h>
 24#include <QDateTime>
 25#include <QMap>
 26#include <QNetworkReply>
 27#include <stdexcept>
 28
 29#ifdef Q_CC_MSVC
 30// ms admits its lousy compiler doesn't care about throw declarations
 31#pragma warning( disable : 4290 )
 32#endif
 33
 34
 35namespace lastfm
 36{
 37    /** if you don't set one, we create our own, our own is pretty good
 38      * for instance, it auto detects proxy settings on windows and mac
 39      * We take ownership of the NAM, do not delete it out from underneath us!
 40      * So don't keep any other pointers to this around in case you accidently
 41      * call delete on them :P */
 42    LASTFM_DLLEXPORT void setNetworkAccessManager( QNetworkAccessManager* nam );
 43    LASTFM_DLLEXPORT QNetworkAccessManager* nam();
 44
 45    namespace ws
 46    {
 47        /** both of these are provided when you register at http://last.fm/api */
 48        LASTFM_DLLEXPORT extern const char* SharedSecret;
 49        LASTFM_DLLEXPORT extern const char* ApiKey;
 50    
 51        /** you need to set this for scrobbling to work (for now)
 52          * Also the AuthenticatedUser class uses it */
 53        LASTFM_DLLEXPORT extern QString Username;
 54
 55        /** Some webservices require authentication. See the following
 56          * documentation:
 57          * http://www.last.fm/api/authentication
 58          * http://www.last.fm/api/desktopauth
 59          * You have to authenticate and then assign to SessionKey, liblastfm does
 60          * not do that for you. Also we do not store this. You should store this!
 61          * You only need to authenticate once, and that key lasts forever!
 62          */
 63        LASTFM_DLLEXPORT extern QString SessionKey;      
 64        
 65        enum Error
 66        {
 67            NoError = 1, // because last.fm error numbers start at 2
 68
 69            /** numbers follow those at http://last.fm/api/ */
 70            InvalidService = 2,
 71            InvalidMethod,
 72            AuthenticationFailed,
 73            InvalidFormat,
 74            InvalidParameters,
 75            InvalidResourceSpecified,
 76            OperationFailed,
 77            InvalidSessionKey,
 78            InvalidApiKey,
 79            ServiceOffline,
 80            SubscribersOnly,
 81
 82            Reserved13,
 83            Reserved14,
 84            Reserved15,
 85
 86            /** Last.fm sucks. 
 87              * There may be an error in networkError(), or this may just be some
 88              * internal error completing your request.
 89              * Advise the user to try again in a _few_minutes_.
 90              * For some cases, you may want to try again yourself, at this point
 91              * in the API you will have to. Eventually we will discourage this and
 92              * do it for you, as we don't want to strain Last.fm's servers
 93              */
 94            TryAgainLater = 16,
 95
 96            Reserved17,
 97            Reserved18,
 98            Reserved19,
 99       
100            NotEnoughContent = 20,
101            NotEnoughMembers,
102            NotEnoughFans,
103            NotEnoughNeighbours,
104
105            /** Last.fm fucked up, or something mangled the response on its way */
106            MalformedResponse = 100,
107
108            /** call QNetworkReply::error() as it's nothing to do with us */
109            UnknownError
110        };
111        
112        LASTFM_DLLEXPORT QString host();
113
114        /** the map needs a method entry, as per http://last.fm/api */
115        LASTFM_DLLEXPORT QUrl url( QMap<QString, QString> );
116        LASTFM_DLLEXPORT QNetworkReply* get( QMap<QString, QString> );
117        /** generates api sig, includes api key, and posts, don't add the api
118          * key yourself as well--it'll break */
119        LASTFM_DLLEXPORT QNetworkReply* post( QMap<QString, QString>, bool sessionKey = true );
120
121
122        class ParseError : public std::runtime_error
123        {
124            Error e;
125            QString m_message;
126        public:
127            explicit ParseError( Error e, QString message )
128                :std::runtime_error("lastfm::ws::Error"), e(e), m_message(message)
129            {}
130            Error enumValue() const { return e; }
131            QString message() const { return m_message; }
132
133            ~ParseError() throw() {;}
134        };
135        
136        /** returns the expiry date of this HTTP response */
137        LASTFM_DLLEXPORT QDateTime expires( QNetworkReply* );
138    }
139}
140
141
142inline QDebug operator<<( QDebug d, QNetworkReply::NetworkError e )
143{
144    return d << lastfm::qMetaEnumString<QNetworkReply>( e, "NetworkError" );
145}
146
147#define LASTFM_WS_HOSTNAME "ws.audioscrobbler.com"
148
149#endif