| 1 |
# License: GPLv3 Copyright: 2008, Kovid Goyal <kovid at kovidgoyal.net> |
| 2 |
|
| 3 |
import os |
| 4 |
from collections import namedtuple |
| 5 |
from typing import ClassVar, NamedTuple |
| 6 |
|
| 7 |
from calibre import prints |
| 8 |
from calibre.constants import iswindows |
| 9 |
from calibre.customize import Plugin |
| 10 |
from calibre.utils.localization import _ |
| 11 |
|
| 12 |
FAKE_DEVICE_SERIAL = '__fake_device_for_use_with_connect_to_folder__:' |
| 13 |
|
| 14 |
|
| 15 |
class ModelMetadata(NamedTuple): |
| 16 |
manufacturer_name: str |
| 17 |
model_name: str |
| 18 |
vendor_id: int |
| 19 |
product_id: int |
| 20 |
bcd: int |
| 21 |
driver_class: type |
| 22 |
|
| 23 |
@property |
| 24 |
def settings_key(self) -> str: |
| 25 |
return f'{self.manufacturer_name} - {self.model_name}' |
| 26 |
|
| 27 |
def detected_device(self, folder_path): |
| 28 |
from calibre.devices.scanner import USBDevice |
| 29 |
|
| 30 |
return USBDevice( |
| 31 |
self.vendor_id, |
| 32 |
self.product_id, |
| 33 |
self.bcd, |
| 34 |
self.manufacturer_name, |
| 35 |
self.model_name, |
| 36 |
FAKE_DEVICE_SERIAL + folder_path, |
| 37 |
) |
| 38 |
|
| 39 |
|
| 40 |
class OpenPopupMessage: |
| 41 |
def __init__(self, title='', message='', level='info', skip_dialog_skip_precheck=True): |
| 42 |
self.title = title |
| 43 |
self.message = message |
| 44 |
self.level = level |
| 45 |
self.skip_dialog_skip_precheck = skip_dialog_skip_precheck |
| 46 |
|
| 47 |
|
| 48 |
class DevicePlugin(Plugin): |
| 49 |
""" |
| 50 |
Defines the interface that should be implemented by backends that |
| 51 |
communicate with an e-book reader. |
| 52 |
""" |
| 53 |
|
| 54 |
type = _('Device interface') |
| 55 |
|
| 56 |
#: Ordered list of supported formats |
| 57 |
FORMATS = ['lrf', 'rtf', 'pdf', 'txt'] |
| 58 |
# If True, the config dialog will not show the formats box |
| 59 |
HIDE_FORMATS_CONFIG_BOX = False |
| 60 |
|
| 61 |
#: VENDOR_ID can be either an integer, a list of integers or a dictionary |
| 62 |
#: If it is a dictionary, it must be a dictionary of dictionaries, |
| 63 |
#: of the form:: |
| 64 |
#: |
| 65 |
#: { |
| 66 |
#: integer_vendor_id : { product_id : [list of BCDs], ... }, |
| 67 |
#: ... |
| 68 |
#: } |
| 69 |
#: |
| 70 |
VENDOR_ID: ClassVar[int | list[int] | dict[int, dict[int, list[int] | None]]] = 0x0000 |
| 71 |
|
| 72 |
#: An integer or a list of integers |
| 73 |
PRODUCT_ID: ClassVar[int | list[int]] = 0x0000 |
| 74 |
#: BCD can be either None to not distinguish between devices based on BCD, or |
| 75 |
#: it can be a list of the BCD numbers of all devices supported by this driver. |
| 76 |
BCD = None |
| 77 |
|
| 78 |
#: Height for thumbnails on the device |
| 79 |
THUMBNAIL_HEIGHT = 68 |
| 80 |
|
| 81 |
#: Compression quality for thumbnails. Set this closer to 100 to have better |
| 82 |
#: quality thumbnails with fewer compression artifacts. Of course, the |
| 83 |
#: thumbnails get larger as well. |
| 84 |
THUMBNAIL_COMPRESSION_QUALITY = 75 |
| 85 |
|
| 86 |
#: Set this to True if the device supports updating cover thumbnails during |
| 87 |
#: sync_booklists. Setting it to true will ask device.py to refresh the |
| 88 |
#: cover thumbnails during book matching |
| 89 |
WANTS_UPDATED_THUMBNAILS = False |
| 90 |
|
| 91 |
#: Whether the metadata on books can be set via the GUI. |
| 92 |
CAN_SET_METADATA = ['title', 'authors', 'collections'] |
| 93 |
|
| 94 |
#: Whether the device can handle device_db metadata plugboards |
| 95 |
CAN_DO_DEVICE_DB_PLUGBOARD = False |
| 96 |
|
| 97 |
# Set this to None if the books on the device are files that the GUI can |
| 98 |
# access in order to add the books from the device to the library |
| 99 |
BACKLOADING_ERROR_MESSAGE = _('Cannot get files from this device') |
| 100 |
|
| 101 |
#: Path separator for paths to books on device |
| 102 |
path_sep = os.sep |
| 103 |
|
| 104 |
#: Icon for this device |
| 105 |
icon = 'reader.png' |
| 106 |
|
| 107 |
# Encapsulates an annotation fetched from the device |
| 108 |
UserAnnotation = namedtuple('UserAnnotation', 'type, value') |
| 109 |
|
| 110 |
#: GUI displays this as a message if not None in the status bar. Useful if opening can take a |
| 111 |
#: long time |
| 112 |
OPEN_FEEDBACK_MESSAGE = None |
| 113 |
|
| 114 |
#: Set of extensions that are "virtual books" on the device |
| 115 |
#: and therefore cannot be viewed/saved/added to library. |
| 116 |
#: For example: ``frozenset(['kobo'])`` |
| 117 |
VIRTUAL_BOOK_EXTENSIONS = frozenset() |
| 118 |
|
| 119 |
#: Message to display to user for virtual book extensions. |
| 120 |
VIRTUAL_BOOK_EXTENSION_MESSAGE = None |
| 121 |
|
| 122 |
#: Whether to nuke comments in the copy of the book sent to the device. If |
| 123 |
#: not None this should be short string that the comments will be replaced |
| 124 |
#: by. |
| 125 |
NUKE_COMMENTS = None |
| 126 |
|
| 127 |
#: If True indicates that this driver completely manages device detection, |
| 128 |
#: ejecting and so forth. If you set this to True, you *must* implement the |
| 129 |
#: detect_managed_devices and debug_managed_device_detection methods. |
| 130 |
#: A driver with this set to true is responsible for detection of devices, |
| 131 |
#: managing a blacklist of devices, a list of ejected devices and so forth. |
| 132 |
#: calibre will periodically call the detect_managed_devices() method and |
| 133 |
#: if it returns a detected device, calibre will call open(). open() will |
| 134 |
#: be called every time a device is returned even if previous calls to open() |
| 135 |
#: failed, therefore the driver must maintain its own blacklist of failed |
| 136 |
#: devices. Similarly, when ejecting, calibre will call eject() and then |
| 137 |
#: assuming the next call to detect_managed_devices() returns None, it will |
| 138 |
#: call post_yank_cleanup(). |
| 139 |
MANAGES_DEVICE_PRESENCE = False |
| 140 |
|
| 141 |
#: If set the True, calibre will call the :meth:`get_driveinfo()` method |
| 142 |
#: after the books lists have been loaded to get the driveinfo. |
| 143 |
SLOW_DRIVEINFO = False |
| 144 |
|
| 145 |
#: If set to True, calibre will ask the user if they want to manage the |
| 146 |
#: device with calibre, the first time it is detected. If you set this to |
| 147 |
#: True you must implement :meth:`get_device_uid()` and |
| 148 |
#: :meth:`ignore_connected_device()` and |
| 149 |
#: :meth:`get_user_blacklisted_devices` and |
| 150 |
#: :meth:`set_user_blacklisted_devices` |
| 151 |
ASK_TO_ALLOW_CONNECT = False |
| 152 |
|
| 153 |
#: Set this to a dictionary of the form {'title':title, 'msg':msg, 'det_msg':detailed_msg} to have calibre popup |
| 154 |
#: a message to the user after some callbacks are run (currently only upload_books). |
| 155 |
#: Be careful to not spam the user with too many messages. This variable is checked after *every* callback, |
| 156 |
#: so only set it when you really need to. |
| 157 |
user_feedback_after_callback = None |
| 158 |
|
| 159 |
@classmethod |
| 160 |
def get_gui_name(cls): |
| 161 |
if hasattr(cls, 'gui_name'): |
| 162 |
return cls.gui_name |
| 163 |
if hasattr(cls, '__name__'): |
| 164 |
return cls.__name__ |
| 165 |
return cls.name |
| 166 |
|
| 167 |
@classmethod |
| 168 |
def get_open_popup_message(self): |
| 169 |
"GUI displays this as a non-modal popup. Should be an instance of OpenPopupMessage" |
| 170 |
return |
| 171 |
|
| 172 |
@classmethod |
| 173 |
def model_metadata(self) -> tuple[ModelMetadata, ...]: |
| 174 |
"Metadata about all the actual device models this driver supports" |
| 175 |
return () |
| 176 |
|
| 177 |
# Device detection {{{ |
| 178 |
def test_bcd(self, bcdDevice, bcd): |
| 179 |
if bcd is None or len(bcd) == 0: |
| 180 |
return True |
| 181 |
for c in bcd: |
| 182 |
if c == bcdDevice: |
| 183 |
return True |
| 184 |
return False |
| 185 |
|
| 186 |
def is_usb_connected(self, devices_on_system, debug=False, only_presence=False): |
| 187 |
""" |
| 188 |
Return True, device_info if a device handled by this plugin is currently connected. |
| 189 |
|
| 190 |
:param devices_on_system: List of devices currently connected |
| 191 |
|
| 192 |
""" |
| 193 |
vendors_on_system = {x[0] for x in devices_on_system} |
| 194 |
vendor_id = self.VENDOR_ID |
| 195 |
if isinstance(vendor_id, dict): |
| 196 |
vendors = set(vendor_id) |
| 197 |
products: list[int] = [] |
| 198 |
for ven in vendor_id: |
| 199 |
products.extend(vendor_id[ven].keys()) |
| 200 |
elif isinstance(vendor_id, list): |
| 201 |
vendors = set(vendor_id) |
| 202 |
products = self.PRODUCT_ID if isinstance(self.PRODUCT_ID, list) else [self.PRODUCT_ID] |
| 203 |
else: |
| 204 |
vendors = {vendor_id} |
| 205 |
products = self.PRODUCT_ID if isinstance(self.PRODUCT_ID, list) else [self.PRODUCT_ID] |
| 206 |
|
| 207 |
ch = self.can_handle_windows if iswindows else self.can_handle |
| 208 |
for vid in vendors_on_system.intersection(vendors): |
| 209 |
for dev in devices_on_system: |
| 210 |
cvid, pid, bcd = dev[:3] |
| 211 |
if cvid == vid: |
| 212 |
if pid in products: |
| 213 |
if isinstance(vendor_id, dict): |
| 214 |
try: |
| 215 |
cbcd = vendor_id[vid][pid] |
| 216 |
except KeyError: |
| 217 |
# Vendor vid does not have product pid, pid |
| 218 |
# exists for some other vendor in this |
| 219 |
# device |
| 220 |
continue |
| 221 |
else: |
| 222 |
cbcd = self.BCD |
| 223 |
if self.test_bcd(bcd, cbcd): |
| 224 |
if debug: |
| 225 |
prints(dev) |
| 226 |
if ch(dev, debug=debug): |
| 227 |
return True, dev |
| 228 |
return False, None |
| 229 |
|
| 230 |
def detect_managed_devices(self, devices_on_system, force_refresh=False): |
| 231 |
""" |
| 232 |
Called only if MANAGES_DEVICE_PRESENCE is True. |
| 233 |
|
| 234 |
Scan for devices that this driver can handle. Should return a device |
| 235 |
object if a device is found. This object will be passed to the open() |
| 236 |
method as the connected_device. If no device is found, return None. The |
| 237 |
returned object can be anything, calibre does not use it, it is only |
| 238 |
passed to open(). |
| 239 |
|
| 240 |
This method is called periodically by the GUI, so make sure it is not |
| 241 |
too resource intensive. Use a cache to avoid repeatedly scanning the |
| 242 |
system. |
| 243 |
|
| 244 |
:param devices_on_system: Set of USB devices found on the system. |
| 245 |
|
| 246 |
:param force_refresh: If True and the driver uses a cache to prevent |
| 247 |
repeated scanning, the cache must be flushed. |
| 248 |
|
| 249 |
""" |
| 250 |
raise NotImplementedError() |
| 251 |
|
| 252 |
def debug_managed_device_detection(self, devices_on_system, output): |
| 253 |
""" |
| 254 |
Called only if MANAGES_DEVICE_PRESENCE is True. |
| 255 |
|
| 256 |
Should write information about the devices detected on the system to |
| 257 |
output, which is a file like object. |
| 258 |
|
| 259 |
Should return True if a device was detected and successfully opened, |
| 260 |
otherwise False. |
| 261 |
""" |
| 262 |
raise NotImplementedError() |
| 263 |
|
| 264 |
# }}} |
| 265 |
|
| 266 |
def reset(self, key='-1', log_packets=False, report_progress=None, detected_device=None): |
| 267 |
""" |
| 268 |
:param key: The key to unlock the device |
| 269 |
:param log_packets: If true the packet stream to/from the device is logged |
| 270 |
:param report_progress: Function that is called with a % progress |
| 271 |
(number between 0 and 100) for various tasks. |
| 272 |
If it is called with -1 that means that the |
| 273 |
task does not have any progress information |
| 274 |
:param detected_device: Device information from the device scanner |
| 275 |
|
| 276 |
""" |
| 277 |
raise NotImplementedError() |
| 278 |
|
| 279 |
def can_handle_windows(self, usbdevice, debug=False): |
| 280 |
""" |
| 281 |
Optional method to perform further checks on a device to see if this driver |
| 282 |
is capable of handling it. If it is not it should return False. This method |
| 283 |
is only called after the vendor, product ids and the bcd have matched, so |
| 284 |
it can do some relatively time intensive checks. The default implementation |
| 285 |
returns True. This method is called only on Windows. See also |
| 286 |
:meth:`can_handle`. |
| 287 |
|
| 288 |
Note that for devices based on USBMS this method by default delegates |
| 289 |
to :meth:`can_handle`. So you only need to override :meth:`can_handle` |
| 290 |
in your subclass of USBMS. |
| 291 |
|
| 292 |
:param usbdevice: A usbdevice as returned by :func:`calibre.devices.winusb.scan_usb_devices` |
| 293 |
""" |
| 294 |
return True |
| 295 |
|
| 296 |
def can_handle(self, device_info, debug=False): |
| 297 |
""" |
| 298 |
Unix version of :meth:`can_handle_windows`. |
| 299 |
|
| 300 |
:param device_info: Is a tuple of (vid, pid, bcd, manufacturer, product, |
| 301 |
serial number) |
| 302 |
|
| 303 |
""" |
| 304 |
|
| 305 |
return True |
| 306 |
|
| 307 |
def open(self, connected_device, library_uuid): |
| 308 |
""" |
| 309 |
Perform any device specific initialization. Called after the device is |
| 310 |
detected but before any other functions that communicate with the device. |
| 311 |
For example: For devices that present themselves as USB Mass storage |
| 312 |
devices, this method would be responsible for mounting the device or |
| 313 |
if the device has been automounted, for finding out where it has been |
| 314 |
mounted. The method :meth:`calibre.devices.usbms.device.Device.open` has |
| 315 |
an implementation of |
| 316 |
this function that should serve as a good example for USB Mass storage |
| 317 |
devices. |
| 318 |
|
| 319 |
This method can raise an OpenFeedback exception to display a message to |
| 320 |
the user. |
| 321 |
|
| 322 |
:param connected_device: The device that we are trying to open. It is |
| 323 |
a tuple of (vendor id, product id, bcd, manufacturer name, product |
| 324 |
name, device serial number). However, some devices have no serial |
| 325 |
number and on Windows only the first three fields are present, the |
| 326 |
rest are None. |
| 327 |
|
| 328 |
:param library_uuid: The UUID of the current calibre library. Can be |
| 329 |
None if there is no library (for example when used from the command |
| 330 |
line). |
| 331 |
|
| 332 |
""" |
| 333 |
raise NotImplementedError() |
| 334 |
|
| 335 |
def eject(self): |
| 336 |
""" |
| 337 |
Un-mount / eject the device from the OS. This does not check if there |
| 338 |
are pending GUI jobs that need to communicate with the device. |
| 339 |
|
| 340 |
NOTE: That this method may not be called on the same thread as the rest |
| 341 |
of the device methods. |
| 342 |
""" |
| 343 |
raise NotImplementedError() |
| 344 |
|
| 345 |
def post_yank_cleanup(self): |
| 346 |
""" |
| 347 |
Called if the user yanks the device without ejecting it first. |
| 348 |
""" |
| 349 |
raise NotImplementedError() |
| 350 |
|
| 351 |
def set_progress_reporter(self, report_progress): |
| 352 |
""" |
| 353 |
Set a function to report progress information. |
| 354 |
|
| 355 |
:param report_progress: Function that is called with a % progress |
| 356 |
(number between 0 and 100) for various tasks. |
| 357 |
If it is called with -1 that means that the |
| 358 |
task does not have any progress information |
| 359 |
|
| 360 |
""" |
| 361 |
raise NotImplementedError() |
| 362 |
|
| 363 |
def get_device_information(self, end_session=True): |
| 364 |
""" |
| 365 |
Ask device for device information. See L{DeviceInfoQuery}. |
| 366 |
|
| 367 |
:return: (device name, device version, software version on device, MIME type) |
| 368 |
The tuple can optionally have a fifth element, which is a |
| 369 |
drive information dictionary. See usbms.driver for an example. |
| 370 |
|
| 371 |
""" |
| 372 |
raise NotImplementedError() |
| 373 |
|
| 374 |
def get_driveinfo(self): |
| 375 |
""" |
| 376 |
Return the driveinfo dictionary. Usually called from |
| 377 |
get_device_information(), but if loading the driveinfo is slow for this |
| 378 |
driver, then it should set SLOW_DRIVEINFO. In this case, this method |
| 379 |
will be called by calibre after the book lists have been loaded. Note |
| 380 |
that it is not called on the device thread, so the driver should cache |
| 381 |
the drive info in the books() method and this function should return |
| 382 |
the cached data. |
| 383 |
""" |
| 384 |
return {} |
| 385 |
|
| 386 |
def card_prefix(self, end_session=True): |
| 387 |
""" |
| 388 |
Return a 2 element list of the prefix to paths on the cards. |
| 389 |
If no card is present None is set for the card's prefix. |
| 390 |
E.G. |
| 391 |
('/place', '/place2') |
| 392 |
(None, 'place2') |
| 393 |
('place', None) |
| 394 |
(None, None) |
| 395 |
""" |
| 396 |
raise NotImplementedError() |
| 397 |
|
| 398 |
def total_space(self, end_session=True): |
| 399 |
""" |
| 400 |
Get total space available on the mountpoints: |
| 401 |
1. Main memory |
| 402 |
2. Memory Card A |
| 403 |
3. Memory Card B |
| 404 |
|
| 405 |
:return: A 3 element list with total space in bytes of (1, 2, 3). If a |
| 406 |
particular device doesn't have any of these locations it should return 0. |
| 407 |
|
| 408 |
""" |
| 409 |
raise NotImplementedError() |
| 410 |
|
| 411 |
def free_space(self, end_session=True): |
| 412 |
""" |
| 413 |
Get free space available on the mountpoints: |
| 414 |
1. Main memory |
| 415 |
2. Card A |
| 416 |
3. Card B |
| 417 |
|
| 418 |
:return: A 3 element list with free space in bytes of (1, 2, 3). If a |
| 419 |
particular device doesn't have any of these locations it should return -1. |
| 420 |
|
| 421 |
""" |
| 422 |
raise NotImplementedError() |
| 423 |
|
| 424 |
def books(self, oncard=None, end_session=True): |
| 425 |
""" |
| 426 |
Return a list of e-books on the device. |
| 427 |
|
| 428 |
:param oncard: If 'carda' or 'cardb' return a list of e-books on the |
| 429 |
specific storage card, otherwise return list of e-books |
| 430 |
in main memory of device. If a card is specified and no |
| 431 |
books are on the card return empty list. |
| 432 |
|
| 433 |
:return: A BookList. |
| 434 |
|
| 435 |
""" |
| 436 |
raise NotImplementedError() |
| 437 |
|
| 438 |
def upload_books(self, files, names, on_card=None, end_session=True, metadata=None): |
| 439 |
''' |
| 440 |
Upload a list of books to the device. If a file already |
| 441 |
exists on the device, it should be replaced. |
| 442 |
This method should raise a :class:`FreeSpaceError` if there is not enough |
| 443 |
free space on the device. The text of the FreeSpaceError must contain the |
| 444 |
word "card" if ``on_card`` is not None otherwise it must contain the word "memory". |
| 445 |
|
| 446 |
:param files: A list of paths |
| 447 |
:param names: A list of file names that the books should have |
| 448 |
once uploaded to the device. len(names) == len(files) |
| 449 |
:param metadata: If not None, it is a list of :class:`Metadata` objects. |
| 450 |
The idea is to use the metadata to determine where on the device to |
| 451 |
put the book. len(metadata) == len(files). Apart from the regular |
| 452 |
cover (path to cover), there may also be a thumbnail attribute, which should |
| 453 |
be used in preference. The thumbnail attribute is of the form |
| 454 |
(width, height, cover_data as jpeg). |
| 455 |
|
| 456 |
:return: A list of 3-element tuples. The list is meant to be passed |
| 457 |
to :meth:`add_books_to_metadata`. |
| 458 |
''' |
| 459 |
raise NotImplementedError() |
| 460 |
|
| 461 |
@classmethod |
| 462 |
def add_books_to_metadata(cls, locations, metadata, booklists): |
| 463 |
""" |
| 464 |
Add locations to the booklists. This function must not communicate with |
| 465 |
the device. |
| 466 |
|
| 467 |
:param locations: Result of a call to L{upload_books} |
| 468 |
:param metadata: List of :class:`Metadata` objects, same as for |
| 469 |
:meth:`upload_books`. |
| 470 |
:param booklists: A tuple containing the result of calls to |
| 471 |
(:meth:`books(oncard=None)`, |
| 472 |
:meth:`books(oncard='carda')`, |
| 473 |
:meth`books(oncard='cardb')`). |
| 474 |
|
| 475 |
""" |
| 476 |
raise NotImplementedError() |
| 477 |
|
| 478 |
def delete_books(self, paths, end_session=True): |
| 479 |
""" |
| 480 |
Delete books at paths on device. |
| 481 |
""" |
| 482 |
raise NotImplementedError() |
| 483 |
|
| 484 |
@classmethod |
| 485 |
def remove_books_from_metadata(cls, paths, booklists): |
| 486 |
""" |
| 487 |
Remove books from the metadata list. This function must not communicate |
| 488 |
with the device. |
| 489 |
|
| 490 |
:param paths: paths to books on the device. |
| 491 |
:param booklists: A tuple containing the result of calls to |
| 492 |
(:meth:`books(oncard=None)`, |
| 493 |
:meth:`books(oncard='carda')`, |
| 494 |
:meth`books(oncard='cardb')`). |
| 495 |
|
| 496 |
""" |
| 497 |
raise NotImplementedError() |
| 498 |
|
| 499 |
def sync_booklists(self, booklists, end_session=True): |
| 500 |
""" |
| 501 |
Update metadata on device. |
| 502 |
|
| 503 |
:param booklists: A tuple containing the result of calls to |
| 504 |
(:meth:`books(oncard=None)`, |
| 505 |
:meth:`books(oncard='carda')`, |
| 506 |
:meth`books(oncard='cardb')`). |
| 507 |
|
| 508 |
""" |
| 509 |
raise NotImplementedError() |
| 510 |
|
| 511 |
def get_file(self, path, outfile, end_session=True): |
| 512 |
""" |
| 513 |
Read the file at ``path`` on the device and write it to outfile. |
| 514 |
|
| 515 |
:param outfile: file object like ``sys.stdout`` or the result of an |
| 516 |
:func:`open` call. |
| 517 |
|
| 518 |
""" |
| 519 |
raise NotImplementedError() |
| 520 |
|
| 521 |
def config_widget(self): |
| 522 |
""" |
| 523 |
Should return a QWidget. The QWidget contains the settings for the |
| 524 |
device interface |
| 525 |
""" |
| 526 |
raise NotImplementedError() |
| 527 |
|
| 528 |
def save_settings(self, config_widget): |
| 529 |
""" |
| 530 |
Should save settings to disk. Takes the widget created in |
| 531 |
:meth:`config_widget` and saves all settings to disk. |
| 532 |
""" |
| 533 |
raise NotImplementedError() |
| 534 |
|
| 535 |
@classmethod |
| 536 |
def settings(cls): |
| 537 |
""" |
| 538 |
Should return an opts object. The opts object should have at least one |
| 539 |
attribute `format_map` which is an ordered list of formats for the |
| 540 |
device. |
| 541 |
""" |
| 542 |
raise NotImplementedError() |
| 543 |
|
| 544 |
def set_plugboards(self, plugboards, pb_func): |
| 545 |
""" |
| 546 |
provide the driver the current set of plugboards and a function to |
| 547 |
select a specific plugboard. This method is called immediately before |
| 548 |
add_books and sync_booklists. |
| 549 |
|
| 550 |
pb_func is a callable with the following signature:: |
| 551 |
def pb_func(device_name, format, plugboards) |
| 552 |
|
| 553 |
You give it the current device name (either the class name or |
| 554 |
DEVICE_PLUGBOARD_NAME), the format you are interested in (a 'real' |
| 555 |
format or 'device_db'), and the plugboards (you were given those by |
| 556 |
set_plugboards, the same place you got this method). |
| 557 |
|
| 558 |
:return: None or a single plugboard instance. |
| 559 |
|
| 560 |
""" |
| 561 |
pass |
| 562 |
|
| 563 |
def set_driveinfo_name(self, location_code, name): |
| 564 |
""" |
| 565 |
Set the device name in the driveinfo file to 'name'. This setting will |
| 566 |
persist until the file is re-created or the name is changed again. |
| 567 |
|
| 568 |
Non-disk devices should implement this method based on the location |
| 569 |
codes returned by the get_device_information() method. |
| 570 |
""" |
| 571 |
pass |
| 572 |
|
| 573 |
def prepare_addable_books(self, paths): |
| 574 |
""" |
| 575 |
Given a list of paths, returns another list of paths. These paths |
| 576 |
point to addable versions of the books. |
| 577 |
|
| 578 |
If there is an error preparing a book, then instead of a path, the |
| 579 |
position in the returned list for that book should be a three tuple: |
| 580 |
(original_path, the exception instance, traceback) |
| 581 |
""" |
| 582 |
return paths |
| 583 |
|
| 584 |
def startup(self): |
| 585 |
""" |
| 586 |
Called when calibre is starting the device. Do any initialization |
| 587 |
required. Note that multiple instances of the class can be instantiated, |
| 588 |
and thus __init__ can be called multiple times, but only one instance |
| 589 |
will have this method called. This method is called on the device |
| 590 |
thread, not the GUI thread. |
| 591 |
""" |
| 592 |
pass |
| 593 |
|
| 594 |
def shutdown(self): |
| 595 |
""" |
| 596 |
Called when calibre is shutting down, either for good or in preparation |
| 597 |
to restart. Do any cleanup required. This method is called on the |
| 598 |
device thread, not the GUI thread. |
| 599 |
""" |
| 600 |
pass |
| 601 |
|
| 602 |
def get_device_uid(self): |
| 603 |
""" |
| 604 |
Must return a unique id for the currently connected device (this is |
| 605 |
called immediately after a successful call to open()). You must |
| 606 |
implement this method if you set ASK_TO_ALLOW_CONNECT = True |
| 607 |
""" |
| 608 |
raise NotImplementedError() |
| 609 |
|
| 610 |
def ignore_connected_device(self, uid): |
| 611 |
""" |
| 612 |
Should ignore the device identified by uid (the result of a call to |
| 613 |
get_device_uid()) in the future. You must implement this method if you |
| 614 |
set ASK_TO_ALLOW_CONNECT = True. Note that this function is called |
| 615 |
immediately after open(), so if open() caches some state, the driver |
| 616 |
should reset that state. |
| 617 |
""" |
| 618 |
raise NotImplementedError() |
| 619 |
|
| 620 |
def get_user_blacklisted_devices(self): |
| 621 |
""" |
| 622 |
Return map of device uid to friendly name for all devices that the user |
| 623 |
has asked to be ignored. |
| 624 |
""" |
| 625 |
return {} |
| 626 |
|
| 627 |
def set_user_blacklisted_devices(self, devices): |
| 628 |
""" |
| 629 |
Set the list of device uids that should be ignored by this driver. |
| 630 |
""" |
| 631 |
pass |
| 632 |
|
| 633 |
def specialize_global_preferences(self, device_prefs): |
| 634 |
""" |
| 635 |
Implement this method if your device wants to override a particular |
| 636 |
preference. You must ensure that all call sites that want a preference |
| 637 |
that can be overridden use device_prefs['something'] instead |
| 638 |
of prefs['something']. Your |
| 639 |
method should call device_prefs.set_overrides(pref=val, pref=val, ...). |
| 640 |
Currently used for: |
| 641 |
metadata management (prefs['manage_device_metadata']) |
| 642 |
""" |
| 643 |
device_prefs.set_overrides() |
| 644 |
|
| 645 |
def set_library_info(self, library_name, library_uuid, field_metadata): |
| 646 |
""" |
| 647 |
Implement this method if you want information about the current calibre |
| 648 |
library. This method is called at startup and when the calibre library |
| 649 |
changes while connected. |
| 650 |
""" |
| 651 |
pass |
| 652 |
|
| 653 |
# Dynamic control interface. |
| 654 |
# The following methods are probably called on the GUI thread. Any driver |
| 655 |
# that implements these methods must take pains to be thread safe, because |
| 656 |
# the device_manager might be using the driver at the same time that one of |
| 657 |
# these methods is called. |
| 658 |
|
| 659 |
def is_dynamically_controllable(self): |
| 660 |
""" |
| 661 |
Called by the device manager when starting plugins. If this method returns |
| 662 |
a string, then a) it supports the device manager's dynamic control |
| 663 |
interface, and b) that name is to be used when talking to the plugin. |
| 664 |
|
| 665 |
This method can be called on the GUI thread. A driver that implements |
| 666 |
this method must be thread safe. |
| 667 |
""" |
| 668 |
return |
| 669 |
|
| 670 |
def start_plugin(self): |
| 671 |
""" |
| 672 |
This method is called to start the plugin. The plugin should begin |
| 673 |
to accept device connections however it does that. If the plugin is |
| 674 |
already accepting connections, then do nothing. |
| 675 |
|
| 676 |
This method can be called on the GUI thread. A driver that implements |
| 677 |
this method must be thread safe. |
| 678 |
""" |
| 679 |
pass |
| 680 |
|
| 681 |
def stop_plugin(self): |
| 682 |
""" |
| 683 |
This method is called to stop the plugin. The plugin should no longer |
| 684 |
accept connections, and should cleanup behind itself. It is likely that |
| 685 |
this method should call shutdown. If the plugin is already not accepting |
| 686 |
connections, then do nothing. |
| 687 |
|
| 688 |
This method can be called on the GUI thread. A driver that implements |
| 689 |
this method must be thread safe. |
| 690 |
""" |
| 691 |
pass |
| 692 |
|
| 693 |
def get_option(self, opt_string, default=None): |
| 694 |
""" |
| 695 |
Return the value of the option indicated by opt_string. This method can |
| 696 |
be called when the plugin is not started. Return None if the option does |
| 697 |
not exist. |
| 698 |
|
| 699 |
This method can be called on the GUI thread. A driver that implements |
| 700 |
this method must be thread safe. |
| 701 |
""" |
| 702 |
return default |
| 703 |
|
| 704 |
def set_option(self, opt_string, opt_value): |
| 705 |
""" |
| 706 |
Set the value of the option indicated by opt_string. This method can |
| 707 |
be called when the plugin is not started. |
| 708 |
|
| 709 |
This method can be called on the GUI thread. A driver that implements |
| 710 |
this method must be thread safe. |
| 711 |
""" |
| 712 |
pass |
| 713 |
|
| 714 |
def is_running(self): |
| 715 |
""" |
| 716 |
Return True if the plugin is started, otherwise false |
| 717 |
|
| 718 |
This method can be called on the GUI thread. A driver that implements |
| 719 |
this method must be thread safe. |
| 720 |
""" |
| 721 |
return False |
| 722 |
|
| 723 |
def synchronize_with_db(self, db, book_id, book_metadata, first_call): |
| 724 |
""" |
| 725 |
Called during book matching when a book on the device is matched with |
| 726 |
a book in calibre's db. The method is responsible for synchronizing |
| 727 |
data from the device to calibre's db (if needed). |
| 728 |
|
| 729 |
The method must return a two-value tuple. The first value is a set of |
| 730 |
calibre book ids changed if calibre's database was changed or None if the |
| 731 |
database was not changed. If the first value is an empty set then the |
| 732 |
metadata for the book on the device is updated with calibre's metadata |
| 733 |
and given back to the device, but no GUI refresh of that book is done. |
| 734 |
This is useful when the calibre data is correct but must be sent to the |
| 735 |
device. |
| 736 |
|
| 737 |
The second value is itself a 2-value tuple. The first value in the tuple |
| 738 |
specifies whether a book format should be sent to the device. The intent |
| 739 |
is to permit verifying that the book on the device is the same as the |
| 740 |
book in calibre. This value must be None if no book is to be sent, |
| 741 |
otherwise return the base file name on the device (a string like |
| 742 |
foobar.epub). Be sure to include the extension in the name. The device |
| 743 |
subsystem will construct a send_books job for all books with not- None |
| 744 |
returned values. Note: other than to later retrieve the extension, the |
| 745 |
name is ignored in cases where the device uses a template to generate |
| 746 |
the file name, which most do. The second value in the returned tuple |
| 747 |
indicated whether the format is future-dated. Return True if it is, |
| 748 |
otherwise return False. calibre will display a dialog to the user |
| 749 |
listing all future dated books. |
| 750 |
|
| 751 |
Extremely important: this method is called on the GUI thread. It must |
| 752 |
be threadsafe with respect to the device manager's thread. |
| 753 |
|
| 754 |
book_id: the calibre id for the book in the database. |
| 755 |
book_metadata: the Metadata object for the book coming from the device. |
| 756 |
first_call: True if this is the first call during a sync, False otherwise |
| 757 |
""" |
| 758 |
return (None, (None, False)) |
| 759 |
|
| 760 |
|
| 761 |
class BookList(list): |
| 762 |
""" |
| 763 |
A list of books. Each Book object must have the fields |
| 764 |
|
| 765 |
#. title |
| 766 |
#. authors |
| 767 |
#. size (file size of the book) |
| 768 |
#. datetime (a UTC time tuple) |
| 769 |
#. path (path on the device to the book) |
| 770 |
#. thumbnail (can be None) thumbnail is either a str/bytes object with the |
| 771 |
image data or it should have an attribute image_path that stores an |
| 772 |
absolute (platform native) path to the image |
| 773 |
#. tags (a list of strings, can be empty). |
| 774 |
|
| 775 |
""" |
| 776 |
|
| 777 |
__getslice__ = None |
| 778 |
__setslice__ = None |
| 779 |
|
| 780 |
def __init__(self, oncard=None, prefix=None, settings=None): |
| 781 |
pass |
| 782 |
|
| 783 |
def supports_collections(self): |
| 784 |
"""Return True if the device supports collections for this book list.""" |
| 785 |
raise NotImplementedError() |
| 786 |
|
| 787 |
def add_book(self, book, replace_metadata): |
| 788 |
""" |
| 789 |
Add the book to the booklist. Intent is to maintain any device-internal |
| 790 |
metadata. Return True if booklists must be sync'ed |
| 791 |
""" |
| 792 |
raise NotImplementedError() |
| 793 |
|
| 794 |
def remove_book(self, book): |
| 795 |
""" |
| 796 |
Remove a book from the booklist. Correct any device metadata at the |
| 797 |
same time |
| 798 |
""" |
| 799 |
raise NotImplementedError() |
| 800 |
|
| 801 |
def get_collections(self, collection_attributes): |
| 802 |
""" |
| 803 |
Return a dictionary of collections created from collection_attributes. |
| 804 |
Each entry in the dictionary is of the form collection name:[list of |
| 805 |
books] |
| 806 |
|
| 807 |
The list of books is sorted by book title, except for collections |
| 808 |
created from series, in which case series_index is used. |
| 809 |
|
| 810 |
:param collection_attributes: A list of attributes of the Book object |
| 811 |
|
| 812 |
""" |
| 813 |
raise NotImplementedError() |
| 814 |
|
| 815 |
|
| 816 |
class CurrentlyConnectedDevice: |
| 817 |
def __init__(self): |
| 818 |
self._device = None |
| 819 |
|
| 820 |
@property |
| 821 |
def device(self): |
| 822 |
return self._device |
| 823 |
|
| 824 |
|
| 825 |
# A device driver can check if a device is currently connected to calibre using |
| 826 |
# the following code:: |
| 827 |
# from calibre.device.interface import currently_connected_device |
| 828 |
# if currently_connected_device.device is None: |
| 829 |
# # no device connected |
| 830 |
# The device attribute will be either None or the device driver object |
| 831 |
# (DevicePlugin instance) for the currently connected device. |
| 832 |
currently_connected_device = CurrentlyConnectedDevice() |