~ubuntu-branches/ubuntu/precise/libmtp/precise-proposed : revision 1.1.12

93

The Examples

94

------------

95

96

In the subdirectory "examples" you find a number of

96

In the subdirectory "examples" you find a number of

97

command-line tools, illustrating the use of libmtp in very

98

simple terms.

99

105

called them "tools" not "examples".

106

107

2. The MTP usage paradigm is that a daemon should hook

108

the device upon connection, and that it should be

108

the device upon connection, and that it should be

109

released by unplugging. GUI tools utilizing HAL (hald)

110

and D-Bus do this much better than any commandline

111

program ever can. (See below on bugs.) Specificationwise

120

-----------

121

122

If you happen upon a device which libmtp claims it cannot

123

autodetect, please submit the vendor ID and device ID

123

autodetect, please submit the vendor ID and device ID

124

(these can be obtained from the "lsusb" and "lsusb -n"

125

commands run as root) as a bug, patch or feature request

126

on the Sourceforge bug tracker at our homepage. If it

127

gives a sensible output from "mtp-detect" then please attach

128

the result as well as it teach us some stuff about your

129

device. If you've done some additional hacking, join our

125

commands run as root) as a bug, patch or feature request

126

on the Sourceforge bug tracker at our homepage. If it

127

gives a sensible output from "mtp-detect" then please attach

128

the result as well as it teach us some stuff about your

129

device. If you've done some additional hacking, join our

130

mailinglist and post your experiences there.

131

132

If you want to be able to hack some more and you're not

133

afraid of C hacking, add an entry for your device's

134

vendor/product ID and a descriptive string to the database

133

afraid of C hacking, add an entry for your device's

134

vendor/product ID and a descriptive string to the database

135

in the file src/music-players.h.

136

137

If you want to poke around to see if your device has some

143

flag, chances are high that a new device will need it

144

too, typically from the same manufacturer.

145

146

The most common flag that needs to be set is the

146

The most common flag that needs to be set is the

147

DEVICE_FLAG_UNLOAD_DRIVER that detach any Linux kernel

148

drivers that may have attached to the device making

149

MTP access impossible. This is however not expected to

150

really work: this is a problem being tracked as of

151

now (2007-08-04). See the "last resort" solutions below

152

if you really need to get your dual-mode device to work

152

if you really need to get your dual-mode device to work

153

with MTP.

154

155

Another flag which is easy to identify is the

156

DEVICE_FLAG_NO_ZERO_READS, which remedies connection

157

timeouts when getting files, and some timeouts on e.g.

157

timeouts when getting files, and some timeouts on e.g.

158

successive "mtp-connect" calls.

159

160

If you are a device vendor, please consider assigning one

161

of your employees as a contact person for libmtp, have them

162

sign up to the libmtp development list and answer questions

163

and post new device ID:s as they are released to our

164

mailing list. By the way: do you have spare devices you

165

can give us? Send them to Richard (Mac support) or Linus

166

(Linux support). (So far nobody did that except for Microsoft

167

who sent us a Zune by proxy!)

168

169

160

If your device is very problematic we are curious of how it

170

161

works under Windows, so we enjoy reading USB packet sniffs

171

162

that reveal the low-level traffic carried out between

172

Windows Media Player and your device. This can be done

163

Windows Media Player and your device. This can be done

173

164

using e.g.:

174

165

175

166

* USBsnoop:

177

168

178

169

* The trial version of HHD Softwares software-only

179

170

USB monitor. You need to get a copy of version 2.37 since

180

the newer trial versions won't let you carry out the

171

the newer trial versions won't let you carry out the

181

172

needed packet sniffs. (As of 2007-03-10 a copy can be found

182

173

at: http://www.cobbleware.com/files/usb-monitor-237.exe)

183

174

184

175

There are other USB monitors as well, some more expensive

185

176

alternatives use hardware and even measure electronic

186

characteristics of the traffic (which is far too much

177

characteristics of the traffic (which is far too much

187

178

detail for us).

188

179

189

180

Device sniffs are an easy read since the PTP/MTP protocol

218

209

219

210

* One send (OUT to the device), two reads (IN from the device).

220

211

221

* All three byte chunks commands are

222

sent/recieved/recieeved by the function ptp_transaction()

212

* All three byte chunks commands are

213

sent/recieved/recieeved by the function ptp_transaction()

223

214

in the file ptp.c.

224

215

225

* It boils down to ptp_usb_sendreq(), optionally ptp_usb_senddata()

226

or ptp_usb_getdata() and finally ptp_usb_getresp() in the file

216

* It boils down to ptp_usb_sendreq(), optionally ptp_usb_senddata()

217

or ptp_usb_getdata() and finally ptp_usb_getresp() in the file

227

218

libusb-glue.c. Notice ptp_usb_sendreq() and ptp_usb_getresp()

228

219

are ALWAYS called. The TYPE field correspond to this, so the

229

TYPES in this case are "COMMAND" (0x0001), "DATA" (0x0002),

220

TYPES in this case are "COMMAND" (0x0001), "DATA" (0x0002),

230

221

and "RESPONSE" (0x0003).

231

222

232

223

* Notice that the byte order is little endian, so you need to read

255

246

* This RESPONSE has:

256

247

CMD 0x99805, we see in ptp.h that this is PTP_OC_MTP_GetObjPropList.

257

248

Return Code ("RC") = 0x2001, PTP_RC_OK, all went fine.

258

Transaction# 0x00000023.

249

Transaction# 0x00000023.

259

250

260

251

If you want to compare the Windows behaviour with a similar

261

operation using libmtp you can go into the src/libusb-glue.c

252

operation using libmtp you can go into the src/libusb-glue.c

262

253

file and uncomment the row that reads:

263

254

264

255

//#define ENABLE_USB_BULK_DEBUG

278

269

module hook them first, and refuse to release them, even

279

270

when we specify the DEVICE_FLAG_UNLOAD_DRIVER flag. (Maybe

280

271

it DOES release it but the device will immediately be probed

281

at the USB mass storage interface AGAIN because it

272

at the USB mass storage interface AGAIN because it

282

273

enumerates.)

283

274

284

275

Here is what some people do:

298

289

> rmmod usb_storage ; mtp-detect

299

290

300

291

You can run most any command or a client like gnomad2 or

301

Amarok immediately after the rmmod command. This works

292

Amarok immediately after the rmmod command. This works

302

293

sometimes. Another way:

303

294

304

295

* Edit /etc/modprobe.d/blacklist

307

298

308

299

* Reboot.

309

300

310

Now none of you USB disks, flash memory sticks etc will be

301

Now none of you USB disks, flash memory sticks etc will be

311

302

working (you just disabled them all). However you *can* try

312

303

your device, and it might have started working because there

313

304

is no longer a USB mass storage driver that tries to hook onto

314

305

the mass storage interface of your device.

315

306

316

If not even blacklisting works (check with

307

If not even blacklisting works (check with

317

308

"lsmod | grep usb-storage"), there is some problem with

318

something else and you may need to remove or rename the file

309

something else and you may need to remove or rename the file

319

310

/lib/modules/<VERSION>/kernel/drivers/usb/storage/usb-storage.ko

320

311

manually.

321

312

322

If you find the PerfectSolution(TM) to this dilemma, so you

313

If you find the PerfectSolution(TM) to this dilemma, so you

323

314

can properly switch for individual devices whether to use it

324

315

as USB mass storage or not, please tell us how you did it. We

325

316

know we cannot use udev, because udev is called after-the-fact:

351

342

352

343

The Creative Zen series can read VCALENDAR2 (.ics) files

353

344

and VCard (.vcf) files from programs like for example

354

Evolution with the following limitations/conditions:

345

Evolution with the following limitations/conditions:

355

346

356

347

- The file must be in DOS (CR/LF) format, use the unix2dos

357

348

program to convert if needed

358

349

359

- Repeat events in calendar files do not seem to be supported,

350

- Repeat events in calendar files do not seem to be supported,

360

351

entries will only appear once.

361

352

362

- Calendar (.ics) files should be stored in the folder "My Organizer"

353

- Calendar (.ics) files should be stored in the folder "My Organizer"

363

354

when sent to the device (this directory should be autodetected

364

for use with calendar files, otherwise use the option

355

for use with calendar files, otherwise use the option

365

356

-f "My Organizer" to sendfile for this) Apparently this file can

366

357

also contain tasklists.

367

358

388

379

-----------------

389

380

390

381

Some MTP devices have strange pecularities. We try to work around

391

these whenever we can, sometimes we cannot work around it or we

382

these whenever we can, sometimes we cannot work around it or we

392

383

cannot test your solution.

393

384

394

* Generic MTP/PTP disconnect misbehaviour: we have noticed that

385

* Generic MTP/PTP disconnect misbehaviour: we have noticed that

395

386

Windows Media Player apparently never close the session to an MTP

396

387

device. There is a daemon in Windows that "hooks" the device

397

by opening a PTP session to any MTP device, whenever it is

398

plugged in. This daemon proxies any subsequent transactions

388

by opening a PTP session to any MTP device, whenever it is

389

plugged in. This daemon proxies any subsequent transactions

399

390

to/from the device and will never close the session, thus

400

391

Windows simply does not close sessions at all.

401

392

421

412

the device when you plug it in, and "release" it if you unplug

422

413

it.

423

414

424

If this bug in your device annoys you, contact your device

425

manufacturer and ask them to test their product with some libmtp

415

If this bug in your device annoys you, contact your device

416

manufacturer and ask them to test their product with some libmtp

426

417

program.

427

418

419

* Generic certificate misbehaviour. All devices are actually

420

required to support a device certificate to be able to

421

encrypt Windows Media (WMA/WMV) files. However there are

422

obviously a lot of devices out there which doesn't support

423

this at all but instead crash. Typical printout:

424

425

Error 2: PTP Layer error 02ff: get_device_unicode_property(): failed

426

to get unicode property.

427

428

* Generic USB misbehaviour: some devices behave badly under MTP

429

and USB mass storage alike, even down to the lowest layers

430

of USB. You can always discuss such issues at the linux-usb

431

mailing list if you're using Linux:

431

mailing list if you're using Linux:

432

http://www.linux-usb.org/mailing.html

433

434

If you have a problem specific to USB mass storage mode, there

442

to use any MTP device under USB 2.0. This is because the EHCI

443

driver previously did not support zero-length writes to endpoints.

444

It should work in most cases however, or if you connect it

445

to an UHCI/OHCI port instead (yielding lower speed). But

445

to an UHCI/OHCI port instead (yielding lower speed). But

446

please just use a recent kernel.

447

448

* Zen models AVI file seeking problem: the Zens cannot parse the

453

the Zens need the metadata associated with tracks to play back

454

movies properly. Movies are considered "tracks" in the MTP world.

455

456

* Some devices that disregard the metadata sent with the MTP

456

* Some devices that disregard the metadata sent with the MTP

457

commands will parse the files for e.g. ID3 metadata. Some still

458

of these devices expect only ID3v2.3 metadata and will fail with

459

a modern ID3v2,4 tag writer, like many of those found in Linux

470

is 15000 files. For further Creative pecularities, see the

471

FAQ sections at www.nomadness.net.

472

473

* Sandisk sansa c150 and probably several other Sandisk devices

473

* Sandisk sansa c150 and probably several other Sandisk devices

474

(and possibly devices from other manufacturers) have a dual

475

mode with MTP and USB mass storage. The device will initially

476

claim to be mass storage so udev will capture is and make the

477

use of MTP mode impossible. One way of avoiding it could be to

478

be to blacklist the "usb-storage" module in

478

be to blacklist the "usb-storage" module in

479

/etc/modprobe.c/blacklist with a row like this:

480

"blacklist usb-storage". Some have even removed the

481

"usb-storage.ko" (kernel module file) to avoid loading.

483

* Sandisk Sansa Fuze has three modes: auto, MTP or mass storage

484

(MSC). Please set it to MTP to avoid problems with libmtp.

485

486

* The iriver devices (possibly all of them) cannot handle the

487

enhanced GetObjectPropList MTP command (0x9805) properly. So

486

* The iriver devices (possibly all of them) cannot handle the

487

enhanced GetObjectPropList MTP command (0x9805) properly. So

488

they have been banned from using it.

489

490

* iriver devices have problems with older versions of libmtp and

498

that we've managed to work around. (For example it will return

499

multiple PTP packages in a single transaction.)

500

501

* The early firmware for Philips HDD players is known to be

501

* The early firmware for Philips HDD players is known to be

502

problematic. Please upgrade to as new firmware as you can get.

503

(Yes this requires some kind of Windows Installation I think.)

504

514

0xffffffffu. (But they should.) So they may need the special

515

DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST_ALL.

516

517

* Some (smaller) subset of devices cannot even get all the

517

* Some (smaller) subset of devices cannot even get all the

518

properties for a single object in one go, these need the

519

DEVICE_FLAG_BROKEN_MTPGETOBJPROPLIST. Currently only the

520

iriver devices seem to have this bug.

521

522

* The Toshiba Gigabeat S (and probably its sibling the

522

* The Toshiba Gigabeat S (and probably its sibling the

523

Microsoft Zune and other Toshiba devices) will only display

524

album information tags for a song in case there is also

525

an abstract album (created with the album interface) with

537

off the device. This may be someone's idea of copy protection.

538

539

* The Samsung P2 assigns parent folder ID 0 to all unknown file

540

types.(i.e. moves them to the root folder)

540

types.(i.e. moves them to the root folder)

541

542

Lost symbols

543

------------

544

545

Shared libraries can be troublesome to users not experienced with

546

them. The following is a condensed version of a generic question

546

them. The following is a condensed version of a generic question

547

that has appeared on the libmtp mailing list from time to time.

548

549

> PTP: Opening session

553

> (...)

554

> Are these type of errors related to libmtp or something else?

555

556

The problem is of a generic nature, and related to dynamic library

556

The problem is of a generic nature, and related to dynamic library

557

loading. It is colloquially known as "dependency hell".

558

(http://en.wikipedia.org/wiki/Dependency_hell)

559

560

The gnomad2 application calls upon the dynamic linker in Linux to

561

resolve the symbol "LIBMTP_Get_Storageinfo" or any other symbol

562

(ELF symbol, or link point or whatever you want to call them, a

563

symbol is a label on a memory address that the linker shall

563

symbol is a label on a memory address that the linker shall

564

resolve from label to actual address.)

565

For generic information on this subject see the INSTALL file and

566

this Wikipedia page:

567

568

http://en.wikipedia.org/wiki/Library_(computing)

569

570

When Linux /lib/ld-linux.so.X is called to link the symbols compiled

571

into gnomad2 (or any other executable using libmtp), it examines the

572

ELF file for the libmtp.so.X file it finds first and cannot resolve

570

When Linux /lib/ld-linux.so.X is called to link the symbols compiled

571

into gnomad2 (or any other executable using libmtp), it examines the

572

ELF file for the libmtp.so.X file it finds first and cannot resolve

573

the symbol "LIBMTP_Get_Storageinfo" (or whichever symbol you have a

574

problem witj) from it, since it's probably not there. There are many

574

problem witj) from it, since it's probably not there. There are many

575

possible causes of this symbol breakage:

576

577

1) You installed precompiled libmtp and gnomad2 packages (RPMs, debs

625

objects. These objects have file names, but that is actually

626

just a name tag on the object.

627

628

Folders/directories aren't really such entities: they are just

628

Folders/directories aren't really such entities: they are just

629

objects too, albeit objects that can act as parent to other

630

objects. They are called "associations" and are created in atomic

631

fashion and even though there is an MTP command to get all the

632

associations of a certain association, this command is optional

633

so it is perfectly possible (and most common, actually) to create

634

devices where the "folders" (which are actually associations) have

635

no idea whatsoever of what files they are associated as parents to

635

no idea whatsoever of what files they are associated as parents to

636

(i.e. which files they contain). This is very easy for device

637

manufacturers to implement, all the association (i.e. finding out

638

which files are in a certain folder) has to be done by the MTP

654

handling that, so they become /Foo.mp3 and /Foo.mp3(1) or something

655

similar, but it's really a bit kludgy.

656

657

Playlists and albums aren't really files, thinking about

657

Playlists and albums aren't really files, thinking about

658

them as files like the hacks in libgphoto2 is really backwards. They are

659

called associations and are more like a symbolic link that links in a

660

star-shaped pattern to all the files that are part of the album/playlist.

661

Some devices (Samsung) thought that was too complicated and have a

662

different way of storing playlists in an UTF-16 encoded .spl-like file

663

instead! This is why playlists/albums must have their own structs and

663

instead! This is why playlists/albums must have their own structs and

664

functions.

665

666

Plain file access also assumes to be able to write files of an

675

LIBMTP_Get_File_To_File_Descriptor() (and a similar function for tracks)

676

wherever you want.

677

678

People have connected this to TCP sockets for streaming web servers

679

etc, works like a charm. Some devices will even survive if the callback

678

People have connected this to TCP sockets for streaming web servers

679

etc, works like a charm. Some devices will even survive if the callback

680

functions return non-zero and cancel the download. Some devices will

681

lock up and even require a reset if you do that. Devices are poorly

682

implemented so that's life. If you want to stream off a device, the

707

since the device rolls back all failed transactions.

708

709

So this is an inherent limitation of the PTP/MTP protocol.

710

711

712

I make MTP devices!

713

-------------------

714

715

If you are a device vendor there is a lot you can do for libmtp:

716

717

* Please consider assigning one of your employees as a contact person

718

for libmtp, have them sign up to the libmtp development list and answer

719

questions and post new device ID:s as they are released to our

720

mailing list.

721

722

* If you want to help even more, assign someone to look deeper into

723

error reports on your specific devices, understand why your firmware

724

may require some special device flags and what can be done about it.

725

726

* Do you have spare devices you can give us? Send them to Richard (Mac

727

support) or Linus (Linux support). (So far nobody did that except for

728

Microsoft who sent us a Zune by proxy!)

729

730

Vendors do need help from libmtp too, especially we want to help

731

vendors improve their MTP stacks, because they all suffer from the

732

same problem: the lack of a proper conformance test has made many devices

733

incompliant with the MTP specification as it is published today: most

734

devices are just compliant with the Windows MTP stack, and don't work

735

out-of-the-box with libmtp. We need someone on the inside to help in

736

bug reporting vendors MTP stacks internally so these issues are raised.

737

A good way to go toward better MTP compliance is to test with an

738

alternative implementation of the stack. In e.g. IETF standardization

739

it is compulsory for an RFC to have atleast two independent implementations

740

for it to reach the status as standard.

741

742

Being compliant with libmtp is also more and more important for

743

vendors: libmtp is being deployed in some embedded systems like

744

set-top-boxes etc. It will be very irritating for customers if a device

745

will not dock properly with some home entertainment equipment just because

746

it is based on Linux and libmtp and not the Windows MTP stack.