mirror of
https://github.com/kovidgoyal/calibre.git
synced 2025-12-16 10:05:03 -05:00
211 lines
8.3 KiB
Python
211 lines
8.3 KiB
Python
## Copyright (C) 2006 Kovid Goyal kovid@kovidgoyal.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.
|
|
"""
|
|
Define the minimum interface that a device backend must satisfy to be used in
|
|
the GUI. A device backend must subclass the L{Device} class. See prs500.py for
|
|
a backend that implement the Device interface for the SONY PRS500 Reader.
|
|
"""
|
|
|
|
|
|
class Device(object):
|
|
"""
|
|
Defines the interface that should be implemented by backends that
|
|
communicate with an ebook reader.
|
|
|
|
The C{end_session} variables are used for USB session management. Sometimes
|
|
the front-end needs to call several methods one after another, in which case
|
|
the USB session should not be closed after each method call.
|
|
"""
|
|
# Ordered list of supported formats
|
|
FORMATS = ["lrf", "rtf", "pdf", "txt"]
|
|
VENDOR_ID = 0x0000
|
|
PRODUCT_ID = 0x0000
|
|
THUMBNAIL_HEIGHT = 68 # Height for thumbnails on device
|
|
|
|
def __init__(self, key='-1', log_packets=False, report_progress=None) :
|
|
"""
|
|
@param key: The key to unlock the device
|
|
@param log_packets: If true the packet stream to/from the device is logged
|
|
@param report_progress: Function that is called with a % progress
|
|
(number between 0 and 100) for various tasks
|
|
If it is called with -1 that means that the
|
|
task does not have any progress information
|
|
"""
|
|
raise NotImplementedError()
|
|
|
|
@classmethod
|
|
def get_fdi(cls):
|
|
'''Return the FDI description of this device for HAL on linux.'''
|
|
return ''
|
|
|
|
@classmethod
|
|
def is_connected(cls, helper=None):
|
|
'''
|
|
Return True iff the device is physically connected to the computer
|
|
|
|
@param helper: Platform dependent helper object. For e.g. on windows
|
|
an instantiated WMI interface.
|
|
'''
|
|
raise NotImplementedError()
|
|
|
|
def set_progress_reporter(self, report_progress):
|
|
'''
|
|
@param report_progress: Function that is called with a % progress
|
|
(number between 0 and 100) for various tasks
|
|
If it is called with -1 that means that the
|
|
task does not have any progress information
|
|
'''
|
|
raise NotImplementedError()
|
|
|
|
def get_device_information(self, end_session=True):
|
|
"""
|
|
Ask device for device information. See L{DeviceInfoQuery}.
|
|
@return: (device name, device version, software version on device, mime type)
|
|
"""
|
|
raise NotImplementedError()
|
|
|
|
def card_prefix(self, end_session=True):
|
|
'''
|
|
Return prefix to paths on the card or None if no cards present.
|
|
'''
|
|
raise NotImplementedError()
|
|
|
|
def total_space(self, end_session=True):
|
|
"""
|
|
Get total space available on the mountpoints:
|
|
1. Main memory
|
|
2. Memory Stick
|
|
3. SD Card
|
|
|
|
@return: A 3 element list with total space in bytes of (1, 2, 3). If a
|
|
particular device doesn't have any of these locations it should return 0.
|
|
"""
|
|
raise NotImplementedError()
|
|
|
|
def free_space(self, end_session=True):
|
|
"""
|
|
Get free space available on the mountpoints:
|
|
1. Main memory
|
|
2. Card A
|
|
3. Card B
|
|
|
|
@return: A 3 element list with free space in bytes of (1, 2, 3). If a
|
|
particular device doesn't have any of these locations it should return -1.
|
|
"""
|
|
raise NotImplementedError()
|
|
|
|
def books(self, oncard=False, end_session=True):
|
|
"""
|
|
Return a list of ebooks on the device.
|
|
@param oncard: If True return a list of ebooks on the storage card,
|
|
otherwise return list of ebooks in main memory of device.
|
|
If True and no books on card return empty list.
|
|
@return: A BookList.
|
|
"""
|
|
raise NotImplementedError()
|
|
|
|
def upload_books(self, files, names, on_card=False, end_session=True):
|
|
'''
|
|
Upload a list of books to the device. If a file already
|
|
exists on the device, it should be replaced.
|
|
This method should raise a L{FreeSpaceError} if there is not enough
|
|
free space on the device. The text of the FreeSpaceError must contain the
|
|
word "card" if C{on_card} is True otherwise it must contain the word "memory".
|
|
@param files: A list of paths and/or file-like objects.
|
|
@param names: A list of file names that the books should have
|
|
once uploaded to the device. len(names) == len(files)
|
|
@return: A list of 3-element tuples. The list is meant to be passed
|
|
to L{add_books_to_metadata}.
|
|
'''
|
|
raise NotImplementedError()
|
|
|
|
@classmethod
|
|
def add_books_to_metadata(cls, locations, metadata, booklists):
|
|
'''
|
|
Add locations to the booklists. This function must not communicate with
|
|
the device.
|
|
@param locations: Result of a call to L{upload_books}
|
|
@param metadata: List of dictionaries. Each dictionary must have the
|
|
keys C{title}, C{authors}, C{cover}, C{tags}. The value of the C{cover}
|
|
element can be None or a three element tuple (width, height, data)
|
|
where data is the image data in JPEG format as a string. C{tags} must be
|
|
a possibly empty list of strings. C{authors} must be a string.
|
|
@param booklists: A tuple containing the result of calls to
|
|
(L{books}(oncard=False), L{books}(oncard=True)).
|
|
'''
|
|
raise NotImplementedError
|
|
|
|
def delete_books(self, paths, end_session=True):
|
|
'''
|
|
Delete books at paths on device.
|
|
'''
|
|
raise NotImplementedError()
|
|
|
|
@classmethod
|
|
def remove_books_from_metadata(cls, paths, booklists):
|
|
'''
|
|
Remove books from the metadata list. This function must not communicate
|
|
with the device.
|
|
@param paths: paths to books on the device.
|
|
@param booklists: A tuple containing the result of calls to
|
|
(L{books}(oncard=False), L{books}(oncard=True)).
|
|
'''
|
|
raise NotImplementedError()
|
|
|
|
def sync_booklists(self, booklists, end_session=True):
|
|
'''
|
|
Update metadata on device.
|
|
@param booklists: A tuple containing the result of calls to
|
|
(L{books}(oncard=False), L{books}(oncard=True)).
|
|
'''
|
|
raise NotImplementedError()
|
|
|
|
def get_file(self, path, outfile, end_session=True):
|
|
'''
|
|
Read the file at C{path} on the device and write it to outfile.
|
|
@param outfile: file object like C{sys.stdout} or the result of an C{open} call
|
|
'''
|
|
raise NotImplementedError()
|
|
|
|
|
|
|
|
class BookList(list):
|
|
'''
|
|
A list of books. Each Book object must have the fields:
|
|
1. title
|
|
2. authors
|
|
3. size (file size of the book)
|
|
4. datetime (a UTC time tuple)
|
|
5. path (path on the device to the book)
|
|
6. thumbnail (can be None)
|
|
7. tags (a list of strings, can be empty).
|
|
'''
|
|
|
|
def __init__(self):
|
|
list.__init__(self)
|
|
|
|
def supports_tags(self):
|
|
''' Return True if the the device supports tags (collections) for this book list. '''
|
|
raise NotImplementedError()
|
|
|
|
def set_tags(self, book, tags):
|
|
'''
|
|
Set the tags for C{book} to C{tags}.
|
|
@param tags: A list of strings. Can be empty.
|
|
@param book: A book object that is in this BookList.
|
|
'''
|
|
raise NotImplementedError()
|
|
|