#! /usr/bin/python
# -*- coding: iso-8859-15 -*-

##
## itsgotthevibezlib.py
##  - Core utility library for It'sGotTheVibez, an offline last.fm
##    scrobbler for Trekstor's "Vibez" portable music player.
## See http://www.ohrner.net/ for latest news and updates, please.
## 
## $Id$
## $URL$
## 
## Copyright (C) 2007-2008 Gunter Ohrner "gunter _(@)_ ohrner.net"
##
## 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 2 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, write to the Free Software
## Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
##

##
## Exception Hierachy
##
## Logical exceptions used by It'sGotTheVibez. These exceptions are fatal.
## Technical exceptions like timeouts and similar will be caught and masked
## if possible. If It'sGotTheVibez cannot recover, one of the following
## exceptions will be thrown.
##

class ItsGotTheVibezException( Exception ):
	"""Common base class for all It'sGotTheVibez related logical exceptions."""
	def __init__(self, text, errorcode):
		Exception.__init__(self, text)
		self.errorcode = errorcode

	def getErrorCode(self):
		return self.errorcode



class ItsGotTheVibezConfigurationException( ItsGotTheVibezException ):
	"""Misconfiguration"""
	def __init__(self, text):
		ItsGotTheVibezException.__init__(self, text, 2)


		
class ItsGotTheVibezRuntimeException( ItsGotTheVibezException ):
	"""General fatal runtime error."""
	def __init__(self, text):
		ItsGotTheVibezException.__init__(self, text, 1)


		
class ItsGotTheVibezLastfmSubmissionException( ItsGotTheVibezException ):
	"""Problem submitting something to last.fm"""
	def __init__(self, text, lastfm_exception):
		ItsGotTheVibezException.__init__(self,
																		 text + ': ' + str(lastfm_exception),
																		 10 + lastfm_exception.getErrorCode())


		
class ItsGotTheVibezInternalException( ItsGotTheVibezException ):
	"""Internal scrobbler failure"""
	def __init__(self, text, causing_exception = None):
		ItsGotTheVibezException.__init__(self, text, 9)
		self.cause = causing_exception

	def getCause(self):
		"""Return causing exception, if any, or "None" otherwise"""
		return self.cause



class AbstractImportModuleState( object ):
	def __init__(self, import_module_name):
		self.handling_module_id = import_module_name



class ScrobblerState( object ):
	"""The scrobblers state which is persisted in the "state file" while the
	scrobbler is not running. This object stores

	1) the submit queue, called "agenda", which is a list of track listen
	events which have not yet been
	submitted to the server.

	2) A dict mapping track ID keys to TrackPlayState records which remember
	the last known track play counter and the last time a track has been
	played. (Fixme: Local time or UTC?)
	"""

	def __init__(self):
		## State object version identifier
		self.version = 3
		## Dictionary carrying internal state required by the used import
		## modules.
		self.module_states = {}
		## list of yet unsubmitted TrackSubmitRecord objects
		self.agenda = []