device-flags.h(3)

📦 version 1.1.23, in arch rolling

💅 device-flags.h(3) — the ✨ Library Functions Manual ✨ bestie edition

Okay so picture this: you're deep in device-flags.h(3), the header that both libmtp and libgphoto2 share, and it's literally just a giant pile of "this specific camera is a lil broken in this specific way" flags. No cap, this file is iconic. 🎀

Let's get into it.

✨ SYNOPSIS ✨

Macros 🧚

#define DEVICE_FLAG_NONE   0x00000000
#define DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST_ALL   0x00000001
#define DEVICE_FLAG_UNLOAD_DRIVER   0x00000002
#define DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST   0x00000004
#define DEVICE_FLAG_NO_ZERO_READS   0x00000008
#define DEVICE_FLAG_IRIVER_OGG_ALZHEIMER   0x00000010
#define DEVICE_FLAG_ONLY_7BIT_FILENAMES   0x00000020
#define DEVICE_FLAG_NO_RELEASE_INTERFACE   0x00000040
#define DEVICE_FLAG_IGNORE_HEADER_ERRORS   0x00000080
#define DEVICE_FLAG_BROKEN_SET_OBJECT_PROPLIST   0x00000100
#define DEVICE_FLAG_OGG_IS_UNKNOWN   0x00000200
#define DEVICE_FLAG_BROKEN_SET_SAMPLE_DIMENSIONS   0x00000400
#define DEVICE_FLAG_ALWAYS_PROBE_DESCRIPTOR   0x00000800
#define DEVICE_FLAG_PLAYLIST_SPL_V1   0x00001000
#define DEVICE_FLAG_PLAYLIST_SPL_V2   0x00002000
#define DEVICE_FLAG_CANNOT_HANDLE_DATEMODIFIED   0x00004000
#define DEVICE_FLAG_BROKEN_SEND_OBJECT_PROPLIST   0x00008000
#define DEVICE_FLAG_BROKEN_BATTERY_LEVEL   0x00010000
#define DEVICE_FLAG_DELETE_SENDS_EVENT   0x00020000
#define DEVICE_FLAG_CAPTURE   0x00040000
#define DEVICE_FLAG_CAPTURE_PREVIEW   0x00080000
#define DEVICE_FLAG_NIKON_BROKEN_CAPTURE   0x00100000
#define DEVICE_FLAG_NIKON_1   0x00200000
#define DEVICE_FLAG_NO_CAPTURE_COMPLETE   0x00400000
#define DEVICE_FLAG_OLYMPUS_XML_WRAPPED   0x00800000
#define DEVICE_FLAG_FLAC_IS_UNKNOWN   0x01000000
#define DEVICE_FLAG_UNIQUE_FILENAMES   0x02000000
#define DEVICE_FLAG_SWITCH_MODE_BLACKBERRY   0x04000000
#define DEVICE_FLAG_LONG_TIMEOUT   0x08000000
#define DEVICE_FLAG_FORCE_RESET_ON_CLOSE   0x10000000
#define DEVICE_FLAG_DONT_CLOSE_SESSION   0x20000000
#define DEVICE_FLAG_PROPLIST_OVERRIDES_OI   0x40000000
#define DEVICE_FLAG_SAMSUNG_OFFSET_BUG   0x80000000
#define DEVICE_FLAGS_SONY_NWZ_BUGS
#define DEVICE_FLAGS_ANDROID_BUGS
#define DEVICE_FLAGS_ARICENT_BUGS

Slay, every single one is accounted for. 💅

🌸 Detailed Description 🌸

So what is this file? It's special device flags to deal with bugs in specific devices. That's it, that's the vibe. Somebody's gotta keep track of every camera that ate too many firmware bugs, and apparently that somebody is us. 😭

And now the legal part, bestie, don't skip it, it matters:

Copyright (C) 2005-2007 Richard A. Low richard@wentnet.com Copyright (C) 2005-2012 Linus Walleij triad@df.lth.se Copyright (C) 2006-2007 Marcus Meissner Copyright (C) 2007 Ted Bullock

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This library 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 Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

And the actual lore: This file is supposed to be included by both libmtp and libgphoto2. Two libraries, one header, one shared trauma. 🫶

🔥 Macro Definition Documentation 🔥

🌈 #define DEVICE_FLAG_ALWAYS_PROBE_DESCRIPTOR 0x00000800

Okay so some devices, particularly the SanDisk Sansas, absolutely need their "OS Descriptor" probed every single time or they just won't work right. This flag is the extra massage those lil guys need. Iconic behaviour, honestly.

💜 #define DEVICE_FLAG_BROKEN_BATTERY_LEVEL 0x00010000

For devices that literally cannot support reading out the battery level. Not "won't", cannot. They're doing their best. 😭

🦋 #define DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST 0x00000004

So PTP_OC_MTP_GetObjPropList (9805) is broken in some way on these devices — either it just doesn't work at all (looking at you, Android devices), or it won't properly return all object properties if parameter 3 is set to 0xFFFFFFFFU. Choices were made by these firmwares. 🙈

🎀 #define DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST_ALL 0x00000001

This one means PTP_OC_MTP_GetObjPropList is broken in a much more specific way: it won't return properly formatted metadata for ALL files on the device when you request an object property list for object 0xFFFFFFFF with parameter 3 likewise set to 0xFFFFFFFF. Compare that to DEVICE_FLAG_BROKEN_MTPGETOBJECTPROPLIST, which only signifies that it's broken when getting metadata for a SINGLE object. Huge difference, iykyk.

A typical way the implementation may be broken is that it may not return a proper count of the objects, and sometimes (like on the ZENs) objects are simply missing from the list if you use this. Sometimes it has been used incorrectly to mask bugs in the code (like handling transactions of data with size given to -1 (0xFFFFFFFFU) — in that case please help us remove it now the code is fixed. Sometimes this is used because getting all the objects is just too slow and the USB transaction will time out if you use this command. Genuinely a "it's complicated" flag. 💀

🌸 #define DEVICE_FLAG_BROKEN_SEND_OBJECT_PROPLIST 0x00008000

This avoids use of the send object proplist, which is used when creating new objects (not just updating). The DEVICE_FLAG_BROKEN_SET_OBJECT_PROPLIST is related but only concerns the case where the object proplist is sent in to update an existing object. The Toshiba Gigabeat MEU202 for example has this problem. Fr fr, named and shamed. 😤

Referenced by LIBMTP_Create_Folder().

🍓 #define DEVICE_FLAG_BROKEN_SET_OBJECT_PROPLIST 0x00000100

The Motorola RAZR2 V8 (others?) has broken set object proplist, which causes the metadata setting to fail. (The set object prop to set individual properties does work on this device, but the metadata is plain ignored on tracks, though e.g. playlist names can be set.) So like… half works. Which is somehow worse. 😭

✨ #define DEVICE_FLAG_BROKEN_SET_SAMPLE_DIMENSIONS 0x00000400

The Creative Zen is quite unstable in libmtp but seems to be better with later firmware versions. However, it still frequently crashes when setting album art dimensions. This flag disables setting the dimensions (which seems to make no difference to how the graphic is displayed). So we just… don't do that part. Problem solved, vibes restored. 💅

🧚 #define DEVICE_FLAG_CANNOT_HANDLE_DATEMODIFIED 0x00004000

The Sansa E250 is known to have this problem, which is actually that the device claims property PTP_OPC_DateModified is read/write but will still fail to update it. Rude. It can only be set properly the first time a file is sent. After that? Nothing. Silenced. 🙈

💖 #define DEVICE_FLAG_CAPTURE 0x00040000

Cameras that can capture images. (libgphoto2) Very demure, very mindful, very much able to take a picture. 📸

💖 #define DEVICE_FLAG_CAPTURE_PREVIEW 0x00080000

Cameras that can capture images. (libgphoto2) Yes, the description is the same as above. Yes, I'm keeping it exactly as written. Not my problem, not my flag. 🫶

👑 #define DEVICE_FLAG_DELETE_SENDS_EVENT 0x00020000

Devices that send "ObjectDeleted" events after deletion of images. (libgphoto2) They're just keeping you in the loop, honestly. Communication icon. ✨

🌙 #define DEVICE_FLAG_DONT_CLOSE_SESSION 0x20000000

On 2016 EOS cameras, do not close the session on exiting, as the device will only report ptp errors afterwards. So, like, hands off the session. Leave it. Walk away. 😌

🦄 #define DEVICE_FLAG_FLAC_IS_UNKNOWN 0x01000000

This flag is like DEVICE_FLAG_OGG_IS_UNKNOWN but for FLAC files instead. Using the unknown filetype for FLAC files. Same energy, different audio format. 🎧

Referenced by LIBMTP_Open_Raw_Device_Uncached().

🌈 #define DEVICE_FLAG_FORCE_RESET_ON_CLOSE 0x10000000

This flag indicates that the device needs an explicit USB reset after each connection. Some devices don't like this, so it's not done by default. Very "only if you ask nicely" of it. ⚡

🎀 #define DEVICE_FLAG_IGNORE_HEADER_ERRORS 0x00000080

This flag was introduced with the advent of the Creative ZEN 8GB. The device sometimes returns a broken PTP header like this: < 1502 0000 0200 01d1 02d1 01d2 > — the latter 6 bytes (representing "code" and "transaction ID") contain junk. This is breaking the PTP/MTP spec but works on Windows anyway, probably because the Windows implementation does not check that these bytes are valid. To interoperate with devices like this, we need this flag to emulate the Windows bug. Broken headers has also been found in the Aricent MTP stack. So basically: we're cosplaying Windows. On purpose. Bestie, the things we do for compatibility. 💀

💚 #define DEVICE_FLAG_IRIVER_OGG_ALZHEIMER 0x00000010

This flag means the device is prone to forgetting the OGG container file type, so libmtp must look at the filename extensions in order to determine that a file is actually OGG. This is a clear and present firmware bug, and while firmware bugs should be fixed in firmware, we like OGG so much that we back it by introducing this flag. The error has only been seen on iriver devices. Turning this flag on won't hurt anything, just that the check against filename extension will be done for files of "unknown" type. If the player does not even know (reports) that it supports ogg even though it does, please use the stronger OGG_IS_UNKNOWN flag, which will forcedly support ogg on anything with the .ogg filename extension. We love OGG and we will defend OGG. Periodt. 🎶

⭐ #define DEVICE_FLAG_LONG_TIMEOUT 0x08000000

This flag indicates that the device needs an extra long timeout on some operations. Slow and steady wins the race, apparently. ⏳

🦋 #define DEVICE_FLAG_NIKON_1 0x00200000

To distinguish the V1 series from the DSLRs and handle them (libgphoto2). Gotta know which one you're dealing with, bestie. 🔍

🌸 #define DEVICE_FLAG_NIKON_BROKEN_CAPTURE 0x00100000

Nikon broken capture support without proper ObjectAdded events. (libgphoto2) The events said no. 😭

🔥 #define DEVICE_FLAG_NO_CAPTURE_COMPLETE 0x00400000

Broken capture support where cameras do not send CaptureComplete events. (libgphoto2) Again with the missing events. Someone get these cameras a calendar. 💀

💜 #define DEVICE_FLAG_NO_RELEASE_INTERFACE 0x00000040

This flag indicates that the device will lock up if you try to get status of endpoints and/or release the interface when closing the device. This fixes problems with SanDisk Sansa devices especially. It may be a side-effect of a Windows behaviour of never releasing interfaces. So we're politely not touching anything. Look away, walk away. 🚶‍♀️

🫶 #define DEVICE_FLAG_NO_ZERO_READS 0x00000008

This means the device doesn't send zero packets to indicate end of transfer when the transfer boundary occurs at a multiple of 64 bytes (the USB 1.1 endpoint size). Instead, exactly one extra byte is sent at the end of the transfer if the size is an integer multiple of USB 1.1 endpoint size (64 bytes).

This behaviour is most probably a workaround due to the fact that the hardware USB slave controller in the device cannot handle zero writes at all, and the usage of the USB 1.1 endpoint size is due to the fact that the device will "geardown" on a USB 1.1 hub, and since 64 bytes is a multiple of 512 bytes, it will work with USB 1.1 and USB 2.0 alike. Ngl, this is the most real-hardware sentence I've ever read and I respect it so much. 🔧

👑 #define DEVICE_FLAG_NONE 0x00000000

Okay so these flags are used to indicate if some or other device needs special treatment. These should be possible to concatenate using logical OR, so please use one bit per feature — and let's pray we don't need more than 32 bits... 🙏 Not me manifesting that 0x00000000 stays enough forever.

🍓 #define DEVICE_FLAG_OGG_IS_UNKNOWN 0x00000200

The Samsung YP-T10 thinks Ogg files shall be sent with the "unknown" (PTP_OFC_Undefined) file type — which gives a side effect that is a combination of the iRiver Ogg Alzheimer problem (have to recognize Ogg files on file extension) and a need to report the Ogg support (the device itself does not properly claim to support it) and need to set filetype to unknown when storing Ogg files, even though they're not actually unknown. Later iRivers seem to need this flag since they do not report to support OGG even though they actually do. Often the device supports OGG in USB mass storage mode, then the firmware simply misses declaring metadata support for OGG properly. The firmware lied, OGG is forever, we code around it. 🎧💖

…and it's referenced by LIBMTP_Open_Raw_Device_Uncached().

  • #define DEVICE_FLAG_OLYMPUS_XML_WRAPPED 0x00800000 — direct PTP match required. (libgphoto2) no cap, that's the whole vibe 💅
  • #define DEVICE_FLAG_ONLY_7BIT_FILENAMES 0x00000020 — okay so this flag means the device is lowkey picky about filenames: they gotta be 7-bit only (all chars <= 127/0x7F). First spotted on the Philips Shoqbox, and it's a whole deviation from the PTP standard which says any unicode chars are fair game for filenames. The guess is that the device has a 7bit-only filesystem intrinsically, so… yeah, that's why 😭
  • #define DEVICE_FLAG_PLAYLIST_SPL_V1 0x00001000 — Samsung really said "not me making my own playlist format" — it's a .spl file stored in the normal file system instead of a proper mtp playlist. There are multiple versions of the .spl format, identified by a line in the file: VERSION X.XX. Version 1.00 is just a simple playlist. Slay for simplicity ✨
  • #define DEVICE_FLAG_PLAYLIST_SPL_V2 0x00002000 — same Samsung .spl situation, multiple versions identified by VERSION X.XX in the file. But Version 2.00 is a playlist that also allows DNSe sound settings to be stored, per playlist. Fancy 💖
  • #define DEVICE_FLAG_PROPLIST_OVERRIDES_OI 0x40000000 — so some devices return bad data when using the GetObjectInfo operation. In those cases we prefer to override the PTP-compatible object infos with the MTP property list. For example, some Samsung Galaxy S devices contain an MTP stack that presents the ObjectInfo in 64 bit instead of 32 bit. It's giving "we do a little trolling" 🙈
  • #define DEVICE_FLAG_SAMSUNG_OFFSET_BUG 0x80000000 — the MTP stack of Samsung Galaxy devices has a mysterious bug in GetPartialObject. When GetPartialObject is invoked to read the last bytes of a file and the amount of data to read is such that the last USB packet sent in the reply matches exactly the USB 2.0 packet size, then the Samsung Galaxy device hangs, resulting in a timeout error. Not iconic, just tragic 💀
  • #define DEVICE_FLAG_SWITCH_MODE_BLACKBERRY 0x04000000 — this flag performs some random magic on the BlackBerry device to switch from USB mass storage to MTP mode, we think. (Emphasis on "we think" 😭)
  • #define DEVICE_FLAG_UNIQUE_FILENAMES 0x02000000 — device needs unique filenames, no two files can be named the same string. Periodt.
  • #define DEVICE_FLAG_UNLOAD_DRIVER 0x00000002 — this means that under Linux, another kernel module may be using this device's USB interface, so we need to detach it if it is. Typically this is on dual-mode devices that will present both an MTP compliant interface and device descriptor and a USB mass storage interface. If the USB mass storage interface is in use, other apps (like our userspace libmtp through libusb access path) cannot get in and get cosy with it. So we can remove the offending application. Typically this means you have to run the program as root as well. Root energy 👑

#define DEVICE_FLAGS_ANDROID_BUGS

Value:

(DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST | \
 DEVICE_FLAG_BROKEN_SET_OBJECT_PROPLIST | \
 DEVICE_FLAG_BROKEN_SEND_OBJECT_PROPLIST | \
 DEVICE_FLAG_UNLOAD_DRIVER | \
 DEVICE_FLAG_LONG_TIMEOUT | \
 DEVICE_FLAG_FORCE_RESET_ON_CLOSE)

All these bug flags need to be set on Android devices — they claim to support MTP operations they actually cannot handle, especially 9805 (Get object property list). These are auto-assigned to devices reporting "android.com" in their device extension descriptor.

Referenced by LIBMTP_Open_Raw_Device_Uncached().

#define DEVICE_FLAGS_ARICENT_BUGS

Value:

(DEVICE_FLAG_IGNORE_HEADER_ERRORS | \
 DEVICE_FLAG_BROKEN_SEND_OBJECT_PROPLIST | \
 DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST)

All these bug flags appear on a number of SonyEricsson devices including Android devices not using the stock Android 4.0+ (Ice Cream Sandwich) MTP stack. It is highly suspected that these bugs come from an MTP implementation from Aricent, so it is called the Aricent bug flags as a shorthand. Especially the header errors that need to be ignored is typical for this stack.

After some guesswork we auto-assign these bug flags to devices that present the "microsoft.com/WPDNA", and "sonyericsson.com/SE" but NOT the "android.com" descriptor.

Referenced by LIBMTP_Open_Raw_Device_Uncached().

#define DEVICE_FLAGS_SONY_NWZ_BUGS

Value:

(DEVICE_FLAG_UNLOAD_DRIVER | \
 DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST | \
 DEVICE_FLAG_UNIQUE_FILENAMES | \
 DEVICE_FLAG_FORCE_RESET_ON_CLOSE)

All these bug flags need to be set on SONY NWZ Walkman players, and will be autodetected on unknown devices by detecting the vendor extension descriptor "sony.net".

Referenced by LIBMTP_Open_Raw_Device_Uncached().

Author 😌

Generated automatically by Doxygen for libmtp from the source code. (Yes, the robots wrote this one, we're just here to make it cute 💅)

That's the whole page, bestie 💖. This masterpiece is libmtp Version 1.1.23, page device-flags.h(3) — go forth and flag responsibly ✨🦋

📦 where this page comes from