-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Scrobbling server.
--   
--   A library providing server-side support for the Audioscrobbler
--   Realtime Submission protocol:
--   <a>http://www.audioscrobbler.net/development/protocol/</a>
@package scrobble
@version 0.2.1.0


-- | Scrobbling data types.
module Scrobble.Types

-- | Server configuration.
data Config
Config :: PortNumber -> String -> NominalDiffTime -> Config

-- | Port to listen on.
cfgPort :: Config -> PortNumber

-- | Host name used for server (probably just localhost).
cfgHost :: Config -> String

-- | Number of seconds of inactivity before a session expires.
cfgExpire :: Config -> NominalDiffTime

-- | Event handlers.
data Handlers
Handlers :: (Session -> IO ()) -> (Session -> IO ()) -> (Session -> NowPlaying -> IO ()) -> (Session -> [Submission] -> IO Bool) -> Handlers

-- | Initial connection hand-shake.
handleHandshake :: Handlers -> Session -> IO ()

-- | Session expiry.
handleExpire :: Handlers -> Session -> IO ()

-- | Now-playing notification.
handleNowPlaying :: Handlers -> Session -> NowPlaying -> IO ()

-- | Played tracks submission.
handleSubmissions :: Handlers -> Session -> [Submission] -> IO Bool

-- | A scrobbling session.
data Session
Session :: Bool -> String -> String -> String -> String -> UTCTime -> String -> Session

-- | Does the session require handshake?
sesHandshake :: Session -> Bool

-- | Version of the protocol.
sesVersion :: Session -> String

-- | Client (music player's) id.
sesClientId :: Session -> String

-- | Client version.
sesClientVer :: Session -> String

-- | Username.
sesUser :: Session -> String

-- | Timestamp of connection.
sesTimestamp :: Session -> UTCTime

-- | Session token.
sesToken :: Session -> String

-- | A now playing track.
data NowPlaying
NowPlaying :: String -> String -> Maybe String -> Maybe Integer -> Maybe Integer -> Maybe String -> NowPlaying

-- | Artist name.
npArtist :: NowPlaying -> String

-- | Track title.
npTrack :: NowPlaying -> String

-- | Album name (if any).
npAlbum :: NowPlaying -> Maybe String

-- | Track length in seconds (if known).
npLength :: NowPlaying -> Maybe Integer

-- | Track position (if known).
npPosition :: NowPlaying -> Maybe Integer

-- | MusicBrainz track id (if known).
npMusicBrainz :: NowPlaying -> Maybe String

-- | A track submission.
data Submission
Submission :: String -> String -> UTCTime -> Source -> Maybe Rating -> Maybe Integer -> Maybe String -> Maybe Integer -> Maybe String -> Submission

-- | Artist name.
subArtist :: Submission -> String

-- | Track title.
subTrack :: Submission -> String

-- | Track timestamp.
subTimestamp :: Submission -> UTCTime

-- | Source of track.
subSource :: Submission -> Source

-- | Rating (if any).
subRating :: Submission -> Maybe Rating

-- | Track length (if any).
subLength :: Submission -> Maybe Integer

-- | Album (if any).
subAlbum :: Submission -> Maybe String

-- | Track position in album (if any).
subPosition :: Submission -> Maybe Integer

-- | MusicBrainz track id (if any).
subMusicBrainz :: Submission -> Maybe String

-- | A rating of a track.
--   
--   Note: Currently, a web-service must also be called to set love/ban
--   status. We anticipate that this will be phased out soon, and the
--   submission service will handle the whole process.
data Rating

-- | Love (on any mode if the user has manually loved the track). This
--   implies a listen.
Love :: Rating

-- | Ban (only if source=L). This implies a skip, and the client should
--   skip to the next track when a ban happens.
Ban :: Rating

-- | Skip (only if source=L).
Skip :: Rating

-- | The source of the track. Required, must be one of the following codes:
--   
--   Please note, for the time being, sources other than P and L are not
--   supported.
data Source

-- | Chosen by the user
UserChosen :: Source

-- | Non-personalised broadcast (e.g. Shoutcast, BBC Radio 1)
NonPersonlizedBroadcast :: Source

-- | Personalised recommendation except Last.fm (e.g. Pandora, Launchcast)
Personalized :: Source

-- | Last.fm (any mode). In this case, the 5-digit Last.fm recommendation
--   key must be appended to this source ID to prove the validity of the
--   submission (for example, <a>o[0]=L1b48a</a>).
LastFm :: Source

-- | Source unknown.
Unknown :: Source

-- | Server response.
data Response
OK :: Response
BANNED :: Response
BADAUTH :: Response
FAILED :: String -> Response
BADSESSION :: Response

-- | A scrobbling client.
data Client
Client :: String -> URI -> URI -> Client

-- | Session token.
cliToken :: Client -> String

-- | Now playing URL to submit to.
cliNowPlaying :: Client -> URI

-- | URL to submit listened tracks to.
cliSubmit :: Client -> URI

-- | Details for creating a scrobbling client.
data Details
Details :: String -> String -> String -> String -> URI -> Details
detPassword :: Details -> String
detUsername :: Details -> String

-- | E.g. “qlb”.
detClient :: Details -> String

-- | E.g. “0.9.2”.
detVersion :: Details -> String

-- | See defaultServer in <a>Scrobble.Client</a>.
detServer :: Details -> URI

-- | Scrobble exception.
data ScrobblerError
ScrobblerBanned :: ScrobblerError
ScrobblerBadAuth :: ScrobblerError
ScrobblerBadTime :: ScrobblerError
ScrobblerFailed :: String -> ScrobblerError
ScrobblerHardFail :: ScrobblerError
ScrobblerSubmitFail :: String -> ScrobblerError
ScrobblerNowPlayingFail :: String -> ScrobblerError
instance Typeable ScrobblerError
instance Show Config
instance Show Session
instance Show NowPlaying
instance Enum Rating
instance Eq Rating
instance Show Rating
instance Read Rating
instance Show Source
instance Enum Source
instance Eq Source
instance Read Source
instance Show Submission
instance Show Response
instance Show Client
instance Show Details
instance Show ScrobblerError
instance Data ScrobblerError
instance Exception ScrobblerError


-- | A client for scrobbling, based upon the Audioscrobbler Realtime
--   Submission protocol v1.2
--   <a>http://www.audioscrobbler.net/development/protocol/</a>
--   
--   Example:
--   
--   <pre>
--    import Scrobble.Client
--    import Data.Time
--   
--   example = do
--      client &lt;- newClient Details
--        { detPassword = "YOURPASS"
--        , detUsername = "YOURUSER"
--        , detClient   = "qlb"
--        , detVersion  = "0.9.2"
--        , detServer   = defaultServer
--        }
--      nowPlaying client NowPlaying
--        { npArtist      = "Kasabian"
--        , npTrack       = "Ladies and Gentlemen"
--        , npAlbum       = Just "West Ryder Pauper Lunatic Asylum"
--        , npLength      = Just 288
--        , npPosition    = Nothing
--        , npMusicBrainz = Nothing
--        }
--      timestamp &lt;- getCurrentTime
--      submitTracks client
--                   [Submission { subArtist      = "Kasabian"
--                               , subTrack       = "Ladies and Gentlemen"
--                               , subTimestamp   = timestamp
--                               , subSource      = UserChosen
--                               , subRating      = Nothing
--                               , subLength      = Just 288
--                               , subAlbum       = Just "West Ryder Pauper Lunatic Asylum"
--                               , subPosition    = Nothing
--                               , subMusicBrainz = Nothing
--                               }]
--   </pre>
module Scrobble.Client

-- | Create a client session. Throws <a>ScrobblerError</a>.
newClient :: Details -> IO Client

-- | Send a now playing message. Throws <a>ScrobblerError</a>.
nowPlaying :: Client -> NowPlaying -> IO ()

-- | Submit track(s). Throws <a>ScrobblerError</a>.
submitTracks :: Client -> [Submission] -> IO ()

-- | Default Audioscrobbler server: http:<i></i>post.audioscrobbler.com/
defaultServer :: URI
instance Show CurlGrab


-- | A server for scrobbling, based upon the Audioscrobbler Realtime
--   Submission protocol v1.2
--   <a>http://www.audioscrobbler.net/development/protocol/</a>
module Scrobble.Server

-- | Start a scrobbling server.
startScrobbleServer :: Config -> Handlers -> IO ()