src/device-flags.h

   1 /**
   2  * \file device-flags.h
   3  * Special device flags to deal with bugs in specific devices.
   4  *
   5  * Copyright (C) 2005-2007 Richard A. Low <richard@wentnet.com>
   6  * Copyright (C) 2005-2012 Linus Walleij <triad@df.lth.se>
   7  * Copyright (C) 2006-2007 Marcus Meissner
   8  * Copyright (C) 2007 Ted Bullock
   9  *
  10  * This library is free software; you can redistribute it and/or
  11  * modify it under the terms of the GNU Lesser General Public
  12  * License as published by the Free Software Foundation; either
  13  * version 2 of the License, or (at your option) any later version.
  14  *
  15  * This library is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18  * Lesser General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU Lesser General Public
  21  * License along with this library; if not, write to the
  22  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  23  * Boston, MA 02111-1307, USA.
  24  *
  25  * This file is supposed to be included by both libmtp and libgphoto2.
  26  */
  27
  28 /**
  29  * These flags are used to indicate if some or other
  30  * device need special treatment. These should be possible
  31  * to concatenate using logical OR so please use one bit per
  32  * feature and lets pray we don't need more than 32 bits...
  33  */
  34 #define DEVICE_FLAG_NONE 0x00000000
  35 /**
  36  * This means that the PTP_OC_MTP_GetObjPropList is broken
  37  * in the sense that it won't return properly formatted metadata
  38  * for ALL files on the device when you request an object
  39  * property list for object 0xFFFFFFFF with parameter 3 likewise
  40  * set to 0xFFFFFFFF. Compare to
  41  * DEVICE_FLAG_BROKEN_MTPGETOBJECTPROPLIST which only signify
  42  * that it's broken when getting metadata for a SINGLE object.
  43  * A typical way the implementation may be broken is that it
  44  * may not return a proper count of the objects, and sometimes
  45  * (like on the ZENs) objects are simply missing from the list
  46  * if you use this. Sometimes it has been used incorrectly to
  47  * mask bugs in the code (like handling transactions of data
  48  * with size given to -1 (0xFFFFFFFFU), in that case please
  49  * help us remove it now the code is fixed. Sometimes this is
  50  * used because getting all the objects is just too slow and
  51  * the USB transaction will time out if you use this command.
  52  */
  53 #define DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST_ALL 0x00000001
  54 /**
  55  * This means that under Linux, another kernel module may
  56  * be using this device's USB interface, so we need to detach
  57  * it if it is. Typically this is on dual-mode devices that
  58  * will present both an MTP compliant interface and device
  59  * descriptor *and* a USB mass storage interface. If the USB
  60  * mass storage interface is in use, other apps (like our
  61  * userspace libmtp through libusb access path) cannot get in
  62  * and get cosy with it. So we can remove the offending
  63  * application. Typically this means you have to run the program
  64  * as root as well.
  65  */
  66 #define DEVICE_FLAG_UNLOAD_DRIVER 0x00000002
  67 /**
  68  * This means that the PTP_OC_MTP_GetObjPropList (9805)
  69  * is broken in some way, either it doesn't work at all
  70  * (as for Android devices) or it won't properly return all
  71  * object properties if parameter 3 is set to 0xFFFFFFFFU.
  72  */
  73 #define DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST 0x00000004
  74 /**
  75  * This means the device doesn't send zero packets to indicate
  76  * end of transfer when the transfer boundary occurs at a
  77  * multiple of 64 bytes (the USB 1.1 endpoint size). Instead,
  78  * exactly one extra byte is sent at the end of the transfer
  79  * if the size is an integer multiple of USB 1.1 endpoint size
  80  * (64 bytes).
  81  *
  82  * This behaviour is most probably a workaround due to the fact
  83  * that the hardware USB slave controller in the device cannot
  84  * handle zero writes at all, and the usage of the USB 1.1
  85  * endpoint size is due to the fact that the device will "gear
  86  * down" on a USB 1.1 hub, and since 64 bytes is a multiple of
  87  * 512 bytes, it will work with USB 1.1 and USB 2.0 alike.
  88  */
  89 #define DEVICE_FLAG_NO_ZERO_READS 0x00000008
  90 /**
  91  * This flag means that the device is prone to forgetting the
  92  * OGG container file type, so that libmtp must look at the
  93  * filename extensions in order to determine that a file is
  94  * actually OGG. This is a clear and present firmware bug, and
  95  * while firmware bugs should be fixed in firmware, we like
  96  * OGG so much that we back it by introducing this flag.
  97  * The error has only been seen on iriver devices. Turning this
  98  * flag on won't hurt anything, just that the check against
  99  * filename extension will be done for files of "unknown" type.
 100  * If the player does not even know (reports) that it supports
 101  * ogg even though it does, please use the stronger
 102  * OGG_IS_UNKNOWN flag, which will forcedly support ogg on
 103  * anything with the .ogg filename extension.
 104  */
 105 #define DEVICE_FLAG_IRIVER_OGG_ALZHEIMER 0x00000010
 106 /**
 107  * This flag indicates a limitation in the filenames a device
 108  * can accept - they must be 7 bit (all chars <= 127/0x7F).
 109  * It was found first on the Philips Shoqbox, and is a deviation
 110  * from the PTP standard which mandates that any unicode chars
 111  * may be used for filenames. I guess this is caused by a 7bit-only
 112  * filesystem being used intrinsically on the device.
 113  */
 114 #define DEVICE_FLAG_ONLY_7BIT_FILENAMES 0x00000020
 115 /**
 116  * This flag indicates that the device will lock up if you
 117  * try to get status of endpoints and/or release the interface
 118  * when closing the device. This fixes problems with SanDisk
 119  * Sansa devices especially. It may be a side-effect of a
 120  * Windows behaviour of never releasing interfaces.
 121  */
 122 #define DEVICE_FLAG_NO_RELEASE_INTERFACE 0x00000040
 123 /**
 124  * This flag was introduced with the advent of Creative ZEN
 125  * 8GB. The device sometimes return a broken PTP header
 126  * like this: < 1502 0000 0200 01d1 02d1 01d2 >
 127  * the latter 6 bytes (representing "code" and "transaction ID")
 128  * contain junk. This is breaking the PTP/MTP spec but works
 129  * on Windows anyway, probably because the Windows implementation
 130  * does not check that these bytes are valid. To interoperate
 131  * with devices like this, we need this flag to emulate the
 132  * Windows bug. Broken headers has also been found in the
 133  * Aricent MTP stack.
 134  */
 135 #define DEVICE_FLAG_IGNORE_HEADER_ERRORS 0x00000080
 136 /**
 137  * The Motorola RAZR2 V8 (others?) has broken set object
 138  * proplist causing the metadata setting to fail. (The
 139  * set object prop to set individual properties work on
 140  * this device, but the metadata is plain ignored on
 141  * tracks, though e.g. playlist names can be set.)
 142  */
 143 #define DEVICE_FLAG_BROKEN_SET_OBJECT_PROPLIST 0x00000100
 144 /**
 145  * The Samsung YP-T10 think Ogg files shall be sent with
 146  * the "unknown" (PTP_OFC_Undefined) file type, this gives a
 147  * side effect that is a combination of the iRiver Ogg Alzheimer
 148  * problem (have to recognized Ogg files on file extension)
 149  * and a need to report the Ogg support (the device itself does
 150  * not properly claim to support it) and need to set filetype
 151  * to unknown when storing Ogg files, even though they're not
 152  * actually unknown. Later iRivers seem to need this flag since
 153  * they do not report to support OGG even though they actually
 154  * do. Often the device supports OGG in USB mass storage mode,
 155  * then the firmware simply miss to declare metadata support
 156  * for OGG properly.
 157  */
 158 #define DEVICE_FLAG_OGG_IS_UNKNOWN 0x00000200
 159 /**
 160  * The Creative Zen is quite unstable in libmtp but seems to
 161  * be better with later firmware versions. However, it still
 162  * frequently crashes when setting album art dimensions. This
 163  * flag disables setting the dimensions (which seems to make
 164  * no difference to how the graphic is displayed).
 165  */
 166 #define DEVICE_FLAG_BROKEN_SET_SAMPLE_DIMENSIONS 0x00000400
 167 /**
 168  * Some devices, particularly SanDisk Sansas, need to always
 169  * have their "OS Descriptor" probed in order to work correctly.
 170  * This flag provides that extra massage.
 171  */
 172 #define DEVICE_FLAG_ALWAYS_PROBE_DESCRIPTOR 0x00000800
 173 /**
 174  * Samsung has implimented its own playlist format as a .spl file
 175  * stored in the normal file system, rather than a proper mtp
 176  * playlist. There are multiple versions of the .spl format
 177  * identified by a line in the file: VERSION X.XX
 178  * Version 1.00 is just a simple playlist.
 179  */
 180 #define DEVICE_FLAG_PLAYLIST_SPL_V1 0x00001000
 181 /**
 182  * Samsung has implimented its own playlist format as a .spl file
 183  * stored in the normal file system, rather than a proper mtp
 184  * playlist. There are multiple versions of the .spl format
 185  * identified by a line in the file: VERSION X.XX
 186  * Version 2.00 is playlist but allows DNSe sound settings
 187  * to be stored, per playlist.
 188  */
 189 #define DEVICE_FLAG_PLAYLIST_SPL_V2 0x00002000
 190 /**
 191  * The Sansa E250 is know to have this problem which is actually
 192  * that the device claims that property PTP_OPC_DateModified
 193  * is read/write but will still fail to update it. It can only
 194  * be set properly the first time a file is sent.
 195  */
 196 #define DEVICE_FLAG_CANNOT_HANDLE_DATEMODIFIED 0x00004000
 197 /**
 198  * This avoids use of the send object proplist which
 199  * is used when creating new objects (not just updating)
 200  * The DEVICE_FLAG_BROKEN_SET_OBJECT_PROPLIST is related
 201  * but only concerns the case where the object proplist
 202  * is sent in to update an existing object. The Toshiba
 203  * Gigabeat MEU202 for example has this problem.
 204  */
 205 #define DEVICE_FLAG_BROKEN_SEND_OBJECT_PROPLIST 0x00008000
 206 /**
 207  * Devices that cannot support reading out battery
 208  * level.
 209  */
 210 #define DEVICE_FLAG_BROKEN_BATTERY_LEVEL 0x00010000
 211
 212 /**
 213  * Devices that send "ObjectDeleted" events after deletion
 214  * of images. (libgphoto2)
 215  */
 216 #define DEVICE_FLAG_DELETE_SENDS_EVENT  0x00020000
 217
 218 /**
 219  * Cameras that can capture images. (libgphoto2)
 220  */
 221 #define DEVICE_FLAG_CAPTURE             0x00040000
 222
 223 /**
 224  * Cameras that can capture images. (libgphoto2)
 225  */
 226 #define DEVICE_FLAG_CAPTURE_PREVIEW     0x00080000
 227
 228 /**
 229  * Nikon broken capture support without proper ObjectAdded events.
 230  * (libgphoto2)
 231  */
 232 #define DEVICE_FLAG_NIKON_BROKEN_CAPTURE        0x00100000
 233
 234 /**
 235  * Broken capture support where cameras do not send CaptureComplete events.
 236  * (libgphoto2)
 237  */
 238 #define DEVICE_FLAG_NO_CAPTURE_COMPLETE         0x00400000
 239
 240 /**
 241  * Direct PTP match required.
 242  * (libgphoto2)
 243  */
 244 #define DEVICE_FLAG_OLYMPUS_XML_WRAPPED         0x00800000
 245 /**
 246  * This flag is like DEVICE_FLAG_OGG_IS_UNKNOWN but for FLAC
 247  * files instead. Using the unknown filetype for FLAC files.
 248  */
 249 #define DEVICE_FLAG_FLAC_IS_UNKNOWN             0x01000000
 250 /**
 251  * Device needs unique filenames, no two files can be
 252  * named the same string.
 253  */
 254 #define DEVICE_FLAG_UNIQUE_FILENAMES            0x02000000
 255 /**
 256  * This flag performs some random magic on the BlackBerry
 257  * device to switch from USB mass storage to MTP mode we think.
 258  */
 259 #define DEVICE_FLAG_SWITCH_MODE_BLACKBERRY      0x04000000
 260 /**
 261  * This flag indicates that the device need an extra long
 262  * timeout on some operations.
 263  */
 264 #define DEVICE_FLAG_LONG_TIMEOUT                0x08000000
 265 /**
 266  * This flag indicates that the device need an explicit
 267  * USB reset after each connection. Some devices don't
 268  * like this, so it's not done by default.
 269  */
 270 #define DEVICE_FLAG_FORCE_RESET_ON_CLOSE        0x10000000
 271 /**
 272  * Early Creative Zen (etc) models actually only support
 273  * command 9805 (Get object property list) and will hang
 274  * if you try to get individual properties of an object.
 275  * Or so it seemed. Later bug fixes to the library has made
 276  * this work flawlessly so the bug flag is moot.
 277  * NOT USED ANYMORE, THIS FLAG MAY BE RECYCLED.
 278  */
 279 #define DEVICE_FLAG_BROKEN_GET_OBJECT_PROPVAL   0x20000000
 280 /**
 281  * It seems that some devices return an bad data when
 282  * using the GetObjectInfo operation. So in these cases
 283  * we prefer to override the PTP-compatible object infos
 284  * with the MTP property list.
 285  *
 286  * For example Some Samsung Galaxy S devices contain an MTP
 287  * stack that present the ObjectInfo in 64 bit instead of
 288  * 32 bit.
 289  */
 290 #define DEVICE_FLAG_PROPLIST_OVERRIDES_OI       0x40000000
 291
 292 /**
 293  * All these bug flags need to be set on SONY NWZ Walkman
 294  * players, and will be autodetected on unknown devices
 295  * by detecting the vendor extension descriptor "sony.net"
 296  */
 297 #define DEVICE_FLAGS_SONY_NWZ_BUGS \
 298   (DEVICE_FLAG_UNLOAD_DRIVER | \
 299    DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST | \
 300    DEVICE_FLAG_UNIQUE_FILENAMES | \
 301    DEVICE_FLAG_FORCE_RESET_ON_CLOSE)
 302 /**
 303  * All these bug flags need to be set on Android devices,
 304  * they claim to support MTP operations they actually
 305  * cannot handle, especially 9805 (Get object property list).
 306  * These are auto-assigned to devices reporting
 307  * "android.com" in their device extension descriptor.
 308  */
 309 #define DEVICE_FLAGS_ANDROID_BUGS \
 310   (DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST | \
 311    DEVICE_FLAG_BROKEN_SET_OBJECT_PROPLIST | \
 312    DEVICE_FLAG_BROKEN_SEND_OBJECT_PROPLIST | \
 313    DEVICE_FLAG_UNLOAD_DRIVER | \
 314    DEVICE_FLAG_LONG_TIMEOUT | \
 315    DEVICE_FLAG_FORCE_RESET_ON_CLOSE)
 316 /**
 317  * All these bug flags appear on a number of SonyEricsson
 318  * devices including Android devices not using the stock
 319  * Android 4.0+ (Ice Cream Sandwich) MTP stack. It is highly
 320  * supected that these bugs comes from an MTP implementation
 321  * from Aricent, so it is called the Aricent bug flags as a
 322  * shorthand. Especially the header errors that need to be
 323  * ignored is typical for this stack.
 324  *
 325  * After some guesswork we auto-assign these bug flags to
 326  * devices that present the "microsoft.com/WPDNA", and
 327  * "sonyericsson.com/SE" but NOT the "android.com"
 328  * descriptor.
 329  */
 330 #define DEVICE_FLAGS_ARICENT_BUGS \
 331   (DEVICE_FLAG_IGNORE_HEADER_ERRORS | \
 332    DEVICE_FLAG_BROKEN_SEND_OBJECT_PROPLIST | \
 333    DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST)