1 /** 2 * \file libmtp.h 3 * Interface to the Media Transfer Protocol library. 4 * 5 * Copyright (C) 2005-2008 Linus Walleij <triad@df.lth.se> 6 * Copyright (C) 2005-2008 Richard A. Low <richard@wentnet.com> 7 * Copyright (C) 2007 Ted Bullock <tbullock@canada.com> 8 * Copyright (C) 2008 Florent Mertens <flomertens@gmail.com> 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 * <code> 26 * #include <libmtp.h> 27 * </code> 28 */ 29 #ifndef LIBMTP_H_INCLUSION_GUARD 30 #define LIBMTP_H_INCLUSION_GUARD 31 32 #define LIBMTP_VERSION 1.0.1 33 #define LIBMTP_VERSION_STRING "1.0.1" 34 35 /* This handles MSVC pecularities */ 36 #ifdef _MSC_VER 37 #include <windows.h> 38 #define __WIN32__ 39 #define snprintf _snprintf 40 #define ssize_t SSIZE_T 41 /* 42 * Types that do not exist in Windows 43 * sys/types.h, but they exist in mingw32 44 * sys/types.h. 45 */ 46 typedef char int8_t; 47 typedef unsigned char uint8_t; 48 typedef __int16 int16_t; 49 typedef unsigned __int16 uint16_t; 50 typedef __int32 int32_t; 51 typedef unsigned __int32 uint32_t; 52 typedef unsigned __int64 uint64_t; 53 #endif 54 55 #include <stdio.h> 56 #include <usb.h> 57 #include <stdint.h> 58 #include <utime.h> 59 60 /** 61 * @defgroup types libmtp global type definitions 62 * @{ 63 * The filetypes defined here are the external types used 64 * by the libmtp library interface. The types used internally 65 * as PTP-defined enumerator types is something different. 66 */ 67 typedef enum { 68 LIBMTP_FILETYPE_FOLDER, 69 LIBMTP_FILETYPE_WAV, 70 LIBMTP_FILETYPE_MP3, 71 LIBMTP_FILETYPE_WMA, 72 LIBMTP_FILETYPE_OGG, 73 LIBMTP_FILETYPE_AUDIBLE, 74 LIBMTP_FILETYPE_MP4, 75 LIBMTP_FILETYPE_UNDEF_AUDIO, 76 LIBMTP_FILETYPE_WMV, 77 LIBMTP_FILETYPE_AVI, 78 LIBMTP_FILETYPE_MPEG, 79 LIBMTP_FILETYPE_ASF, 80 LIBMTP_FILETYPE_QT, 81 LIBMTP_FILETYPE_UNDEF_VIDEO, 82 LIBMTP_FILETYPE_JPEG, 83 LIBMTP_FILETYPE_JFIF, 84 LIBMTP_FILETYPE_TIFF, 85 LIBMTP_FILETYPE_BMP, 86 LIBMTP_FILETYPE_GIF, 87 LIBMTP_FILETYPE_PICT, 88 LIBMTP_FILETYPE_PNG, 89 LIBMTP_FILETYPE_VCALENDAR1, 90 LIBMTP_FILETYPE_VCALENDAR2, 91 LIBMTP_FILETYPE_VCARD2, 92 LIBMTP_FILETYPE_VCARD3, 93 LIBMTP_FILETYPE_WINDOWSIMAGEFORMAT, 94 LIBMTP_FILETYPE_WINEXEC, 95 LIBMTP_FILETYPE_TEXT, 96 LIBMTP_FILETYPE_HTML, 97 LIBMTP_FILETYPE_FIRMWARE, 98 LIBMTP_FILETYPE_AAC, 99 LIBMTP_FILETYPE_MEDIACARD, 100 LIBMTP_FILETYPE_FLAC, 101 LIBMTP_FILETYPE_MP2, 102 LIBMTP_FILETYPE_M4A, 103 LIBMTP_FILETYPE_DOC, 104 LIBMTP_FILETYPE_XML, 105 LIBMTP_FILETYPE_XLS, 106 LIBMTP_FILETYPE_PPT, 107 LIBMTP_FILETYPE_MHT, 108 LIBMTP_FILETYPE_JP2, 109 LIBMTP_FILETYPE_JPX, 110 LIBMTP_FILETYPE_ALBUM, 111 LIBMTP_FILETYPE_PLAYLIST, 112 LIBMTP_FILETYPE_UNKNOWN 113 } LIBMTP_filetype_t; 114 115 /** 116 * \def LIBMTP_FILETYPE_IS_AUDIO 117 * Audio filetype test. 118 * 119 * For filetypes that can be either audio 120 * or video, use LIBMTP_FILETYPE_IS_AUDIOVIDEO 121 */ 122 #define LIBMTP_FILETYPE_IS_AUDIO(a)\ 123 (a == LIBMTP_FILETYPE_WAV ||\ 124 a == LIBMTP_FILETYPE_MP3 ||\ 125 a == LIBMTP_FILETYPE_MP2 ||\ 126 a == LIBMTP_FILETYPE_WMA ||\ 127 a == LIBMTP_FILETYPE_OGG ||\ 128 a == LIBMTP_FILETYPE_FLAC ||\ 129 a == LIBMTP_FILETYPE_AAC ||\ 130 a == LIBMTP_FILETYPE_M4A ||\ 131 a == LIBMTP_FILETYPE_AUDIBLE ||\ 132 a == LIBMTP_FILETYPE_UNDEF_AUDIO) 133 134 /** 135 * \def LIBMTP_FILETYPE_IS_VIDEO 136 * Video filetype test. 137 * 138 * For filetypes that can be either audio 139 * or video, use LIBMTP_FILETYPE_IS_AUDIOVIDEO 140 */ 141 #define LIBMTP_FILETYPE_IS_VIDEO(a)\ 142 (a == LIBMTP_FILETYPE_WMV ||\ 143 a == LIBMTP_FILETYPE_AVI ||\ 144 a == LIBMTP_FILETYPE_MPEG ||\ 145 a == LIBMTP_FILETYPE_UNDEF_VIDEO) 146 147 /** 148 * \def LIBMTP_FILETYPE_IS_AUDIOVIDEO 149 * Audio and&slash;or video filetype test. 150 */ 151 #define LIBMTP_FILETYPE_IS_AUDIOVIDEO(a)\ 152 (a == LIBMTP_FILETYPE_MP4 ||\ 153 a == LIBMTP_FILETYPE_ASF ||\ 154 a == LIBMTP_FILETYPE_QT) 155 156 /** 157 * \def LIBMTP_FILETYPE_IS_TRACK 158 * Test if filetype is a track. 159 * Use this to determine if the File API or Track API 160 * should be used to upload or download an object. 161 */ 162 #define LIBMTP_FILETYPE_IS_TRACK(a)\ 163 (LIBMTP_FILETYPE_IS_AUDIO(a) ||\ 164 LIBMTP_FILETYPE_IS_VIDEO(a) ||\ 165 LIBMTP_FILETYPE_IS_AUDIOVIDEO(a)) 166 167 /** 168 * \def LIBMTP_FILETYPE_IS_IMAGE 169 * Image filetype test 170 */ 171 #define LIBMTP_FILETYPE_IS_IMAGE(a)\ 172 (a == LIBMTP_FILETYPE_JPEG ||\ 173 a == LIBMTP_FILETYPE_JFIF ||\ 174 a == LIBMTP_FILETYPE_TIFF ||\ 175 a == LIBMTP_FILETYPE_BMP ||\ 176 a == LIBMTP_FILETYPE_GIF ||\ 177 a == LIBMTP_FILETYPE_PICT ||\ 178 a == LIBMTP_FILETYPE_PNG ||\ 179 a == LIBMTP_FILETYPE_JP2 ||\ 180 a == LIBMTP_FILETYPE_JPX ||\ 181 a == LIBMTP_FILETYPE_WINDOWSIMAGEFORMAT) 182 183 /** 184 * \def LIBMTP_FILETYPE_IS_ADDRESSBOOK 185 * Addressbook and Business card filetype test 186 */ 187 #define LIBMTP_FILETYPE_IS_ADDRESSBOOK(a)\ 188 (a == LIBMTP_FILETYPE_VCARD2 ||\ 189 a == LIBMTP_FILETYPE_VCARD2) 190 191 /** 192 * \def LIBMTP_FILETYPE_IS_CALENDAR 193 * Calendar and Appointment filetype test 194 */ 195 #define LIBMTP_FILETYPE_IS_CALENDAR(a)\ 196 (a == LIBMTP_FILETYPE_VCALENDAR1 ||\ 197 a == LIBMTP_FILETYPE_VCALENDAR2) 198 199 /** 200 * The properties defined here are the external types used 201 * by the libmtp library interface. 202 */ 203 typedef enum { 204 LIBMTP_PROPERTY_StorageID, 205 LIBMTP_PROPERTY_ObjectFormat, 206 LIBMTP_PROPERTY_ProtectionStatus, 207 LIBMTP_PROPERTY_ObjectSize, 208 LIBMTP_PROPERTY_AssociationType, 209 LIBMTP_PROPERTY_AssociationDesc, 210 LIBMTP_PROPERTY_ObjectFileName, 211 LIBMTP_PROPERTY_DateCreated, 212 LIBMTP_PROPERTY_DateModified, 213 LIBMTP_PROPERTY_Keywords, 214 LIBMTP_PROPERTY_ParentObject, 215 LIBMTP_PROPERTY_AllowedFolderContents, 216 LIBMTP_PROPERTY_Hidden, 217 LIBMTP_PROPERTY_SystemObject, 218 LIBMTP_PROPERTY_PersistantUniqueObjectIdentifier, 219 LIBMTP_PROPERTY_SyncID, 220 LIBMTP_PROPERTY_PropertyBag, 221 LIBMTP_PROPERTY_Name, 222 LIBMTP_PROPERTY_CreatedBy, 223 LIBMTP_PROPERTY_Artist, 224 LIBMTP_PROPERTY_DateAuthored, 225 LIBMTP_PROPERTY_Description, 226 LIBMTP_PROPERTY_URLReference, 227 LIBMTP_PROPERTY_LanguageLocale, 228 LIBMTP_PROPERTY_CopyrightInformation, 229 LIBMTP_PROPERTY_Source, 230 LIBMTP_PROPERTY_OriginLocation, 231 LIBMTP_PROPERTY_DateAdded, 232 LIBMTP_PROPERTY_NonConsumable, 233 LIBMTP_PROPERTY_CorruptOrUnplayable, 234 LIBMTP_PROPERTY_ProducerSerialNumber, 235 LIBMTP_PROPERTY_RepresentativeSampleFormat, 236 LIBMTP_PROPERTY_RepresentativeSampleSize, 237 LIBMTP_PROPERTY_RepresentativeSampleHeight, 238 LIBMTP_PROPERTY_RepresentativeSampleWidth, 239 LIBMTP_PROPERTY_RepresentativeSampleDuration, 240 LIBMTP_PROPERTY_RepresentativeSampleData, 241 LIBMTP_PROPERTY_Width, 242 LIBMTP_PROPERTY_Height, 243 LIBMTP_PROPERTY_Duration, 244 LIBMTP_PROPERTY_Rating, 245 LIBMTP_PROPERTY_Track, 246 LIBMTP_PROPERTY_Genre, 247 LIBMTP_PROPERTY_Credits, 248 LIBMTP_PROPERTY_Lyrics, 249 LIBMTP_PROPERTY_SubscriptionContentID, 250 LIBMTP_PROPERTY_ProducedBy, 251 LIBMTP_PROPERTY_UseCount, 252 LIBMTP_PROPERTY_SkipCount, 253 LIBMTP_PROPERTY_LastAccessed, 254 LIBMTP_PROPERTY_ParentalRating, 255 LIBMTP_PROPERTY_MetaGenre, 256 LIBMTP_PROPERTY_Composer, 257 LIBMTP_PROPERTY_EffectiveRating, 258 LIBMTP_PROPERTY_Subtitle, 259 LIBMTP_PROPERTY_OriginalReleaseDate, 260 LIBMTP_PROPERTY_AlbumName, 261 LIBMTP_PROPERTY_AlbumArtist, 262 LIBMTP_PROPERTY_Mood, 263 LIBMTP_PROPERTY_DRMStatus, 264 LIBMTP_PROPERTY_SubDescription, 265 LIBMTP_PROPERTY_IsCropped, 266 LIBMTP_PROPERTY_IsColorCorrected, 267 LIBMTP_PROPERTY_ImageBitDepth, 268 LIBMTP_PROPERTY_Fnumber, 269 LIBMTP_PROPERTY_ExposureTime, 270 LIBMTP_PROPERTY_ExposureIndex, 271 LIBMTP_PROPERTY_DisplayName, 272 LIBMTP_PROPERTY_BodyText, 273 LIBMTP_PROPERTY_Subject, 274 LIBMTP_PROPERTY_Priority, 275 LIBMTP_PROPERTY_GivenName, 276 LIBMTP_PROPERTY_MiddleNames, 277 LIBMTP_PROPERTY_FamilyName, 278 LIBMTP_PROPERTY_Prefix, 279 LIBMTP_PROPERTY_Suffix, 280 LIBMTP_PROPERTY_PhoneticGivenName, 281 LIBMTP_PROPERTY_PhoneticFamilyName, 282 LIBMTP_PROPERTY_EmailPrimary, 283 LIBMTP_PROPERTY_EmailPersonal1, 284 LIBMTP_PROPERTY_EmailPersonal2, 285 LIBMTP_PROPERTY_EmailBusiness1, 286 LIBMTP_PROPERTY_EmailBusiness2, 287 LIBMTP_PROPERTY_EmailOthers, 288 LIBMTP_PROPERTY_PhoneNumberPrimary, 289 LIBMTP_PROPERTY_PhoneNumberPersonal, 290 LIBMTP_PROPERTY_PhoneNumberPersonal2, 291 LIBMTP_PROPERTY_PhoneNumberBusiness, 292 LIBMTP_PROPERTY_PhoneNumberBusiness2, 293 LIBMTP_PROPERTY_PhoneNumberMobile, 294 LIBMTP_PROPERTY_PhoneNumberMobile2, 295 LIBMTP_PROPERTY_FaxNumberPrimary, 296 LIBMTP_PROPERTY_FaxNumberPersonal, 297 LIBMTP_PROPERTY_FaxNumberBusiness, 298 LIBMTP_PROPERTY_PagerNumber, 299 LIBMTP_PROPERTY_PhoneNumberOthers, 300 LIBMTP_PROPERTY_PrimaryWebAddress, 301 LIBMTP_PROPERTY_PersonalWebAddress, 302 LIBMTP_PROPERTY_BusinessWebAddress, 303 LIBMTP_PROPERTY_InstantMessengerAddress, 304 LIBMTP_PROPERTY_InstantMessengerAddress2, 305 LIBMTP_PROPERTY_InstantMessengerAddress3, 306 LIBMTP_PROPERTY_PostalAddressPersonalFull, 307 LIBMTP_PROPERTY_PostalAddressPersonalFullLine1, 308 LIBMTP_PROPERTY_PostalAddressPersonalFullLine2, 309 LIBMTP_PROPERTY_PostalAddressPersonalFullCity, 310 LIBMTP_PROPERTY_PostalAddressPersonalFullRegion, 311 LIBMTP_PROPERTY_PostalAddressPersonalFullPostalCode, 312 LIBMTP_PROPERTY_PostalAddressPersonalFullCountry, 313 LIBMTP_PROPERTY_PostalAddressBusinessFull, 314 LIBMTP_PROPERTY_PostalAddressBusinessLine1, 315 LIBMTP_PROPERTY_PostalAddressBusinessLine2, 316 LIBMTP_PROPERTY_PostalAddressBusinessCity, 317 LIBMTP_PROPERTY_PostalAddressBusinessRegion, 318 LIBMTP_PROPERTY_PostalAddressBusinessPostalCode, 319 LIBMTP_PROPERTY_PostalAddressBusinessCountry, 320 LIBMTP_PROPERTY_PostalAddressOtherFull, 321 LIBMTP_PROPERTY_PostalAddressOtherLine1, 322 LIBMTP_PROPERTY_PostalAddressOtherLine2, 323 LIBMTP_PROPERTY_PostalAddressOtherCity, 324 LIBMTP_PROPERTY_PostalAddressOtherRegion, 325 LIBMTP_PROPERTY_PostalAddressOtherPostalCode, 326 LIBMTP_PROPERTY_PostalAddressOtherCountry, 327 LIBMTP_PROPERTY_OrganizationName, 328 LIBMTP_PROPERTY_PhoneticOrganizationName, 329 LIBMTP_PROPERTY_Role, 330 LIBMTP_PROPERTY_Birthdate, 331 LIBMTP_PROPERTY_MessageTo, 332 LIBMTP_PROPERTY_MessageCC, 333 LIBMTP_PROPERTY_MessageBCC, 334 LIBMTP_PROPERTY_MessageRead, 335 LIBMTP_PROPERTY_MessageReceivedTime, 336 LIBMTP_PROPERTY_MessageSender, 337 LIBMTP_PROPERTY_ActivityBeginTime, 338 LIBMTP_PROPERTY_ActivityEndTime, 339 LIBMTP_PROPERTY_ActivityLocation, 340 LIBMTP_PROPERTY_ActivityRequiredAttendees, 341 LIBMTP_PROPERTY_ActivityOptionalAttendees, 342 LIBMTP_PROPERTY_ActivityResources, 343 LIBMTP_PROPERTY_ActivityAccepted, 344 LIBMTP_PROPERTY_Owner, 345 LIBMTP_PROPERTY_Editor, 346 LIBMTP_PROPERTY_Webmaster, 347 LIBMTP_PROPERTY_URLSource, 348 LIBMTP_PROPERTY_URLDestination, 349 LIBMTP_PROPERTY_TimeBookmark, 350 LIBMTP_PROPERTY_ObjectBookmark, 351 LIBMTP_PROPERTY_ByteBookmark, 352 LIBMTP_PROPERTY_LastBuildDate, 353 LIBMTP_PROPERTY_TimetoLive, 354 LIBMTP_PROPERTY_MediaGUID, 355 LIBMTP_PROPERTY_TotalBitRate, 356 LIBMTP_PROPERTY_BitRateType, 357 LIBMTP_PROPERTY_SampleRate, 358 LIBMTP_PROPERTY_NumberOfChannels, 359 LIBMTP_PROPERTY_AudioBitDepth, 360 LIBMTP_PROPERTY_ScanDepth, 361 LIBMTP_PROPERTY_AudioWAVECodec, 362 LIBMTP_PROPERTY_AudioBitRate, 363 LIBMTP_PROPERTY_VideoFourCCCodec, 364 LIBMTP_PROPERTY_VideoBitRate, 365 LIBMTP_PROPERTY_FramesPerThousandSeconds, 366 LIBMTP_PROPERTY_KeyFrameDistance, 367 LIBMTP_PROPERTY_BufferSize, 368 LIBMTP_PROPERTY_EncodingQuality, 369 LIBMTP_PROPERTY_EncodingProfile, 370 LIBMTP_PROPERTY_BuyFlag, 371 LIBMTP_PROPERTY_UNKNOWN 372 } LIBMTP_property_t; 373 374 /** 375 * These are the data types 376 */ 377 typedef enum { 378 LIBMTP_DATATYPE_INT8, 379 LIBMTP_DATATYPE_UINT8, 380 LIBMTP_DATATYPE_INT16, 381 LIBMTP_DATATYPE_UINT16, 382 LIBMTP_DATATYPE_INT32, 383 LIBMTP_DATATYPE_UINT32, 384 LIBMTP_DATATYPE_INT64, 385 LIBMTP_DATATYPE_UINT64, 386 } LIBMTP_datatype_t; 387 388 /** 389 * These are the numbered error codes. You can also 390 * get string representations for errors. 391 */ 392 typedef enum { 393 LIBMTP_ERROR_NONE, 394 LIBMTP_ERROR_GENERAL, 395 LIBMTP_ERROR_PTP_LAYER, 396 LIBMTP_ERROR_USB_LAYER, 397 LIBMTP_ERROR_MEMORY_ALLOCATION, 398 LIBMTP_ERROR_NO_DEVICE_ATTACHED, 399 LIBMTP_ERROR_STORAGE_FULL, 400 LIBMTP_ERROR_CONNECTING, 401 LIBMTP_ERROR_CANCELLED 402 } LIBMTP_error_number_t; 403 typedef struct LIBMTP_device_entry_struct LIBMTP_device_entry_t; /**< @see LIBMTP_device_entry_struct */ 404 typedef struct LIBMTP_raw_device_struct LIBMTP_raw_device_t; /**< @see LIBMTP_raw_device_struct */ 405 typedef struct LIBMTP_error_struct LIBMTP_error_t; /**< @see LIBMTP_error_struct */ 406 typedef struct LIBMTP_allowed_values_struct LIBMTP_allowed_values_t; /**< @see LIBMTP_allowed_values_struct */ 407 typedef struct LIBMTP_mtpdevice_struct LIBMTP_mtpdevice_t; /**< @see LIBMTP_mtpdevice_struct */ 408 typedef struct LIBMTP_file_struct LIBMTP_file_t; /**< @see LIBMTP_file_struct */ 409 typedef struct LIBMTP_track_struct LIBMTP_track_t; /**< @see LIBMTP_track_struct */ 410 typedef struct LIBMTP_playlist_struct LIBMTP_playlist_t; /**< @see LIBMTP_playlist_struct */ 411 typedef struct LIBMTP_album_struct LIBMTP_album_t; /**< @see LIBMTP_album_struct */ 412 typedef struct LIBMTP_folder_struct LIBMTP_folder_t; /**< @see LIBMTP_folder_t */ 413 typedef struct LIBMTP_object_struct LIBMTP_object_t; /**< @see LIBMTP_object_t */ 414 typedef struct LIBMTP_filesampledata_struct LIBMTP_filesampledata_t; /**< @see LIBMTP_filesample_t */ 415 typedef struct LIBMTP_devicestorage_struct LIBMTP_devicestorage_t; /**< @see LIBMTP_devicestorage_t */ 416 417 /** 418 * The callback type definition. Notice that a progress percentage ratio 419 * is easy to calculate by dividing <code>sent</code> by 420 * <code>total</code>. 421 * @param sent the number of bytes sent so far 422 * @param total the total number of bytes to send 423 * @param data a user-defined dereferencable pointer 424 * @return if anything else than 0 is returned, the current transfer will be 425 * interrupted / cancelled. 426 */ 427 typedef int (* LIBMTP_progressfunc_t) (uint64_t const sent, uint64_t const total, 428 void const * const data); 429 430 /** 431 * Callback function for get by handler function 432 * @param params the device parameters 433 * @param priv a user-defined dereferencable pointer 434 * @param wantlen the number of bytes wanted 435 * @param data a buffer to write the data to 436 * @param gotlen pointer to the number of bytes actually written 437 * to data 438 * @return LIBMTP_HANDLER_RETURN_OK if successful, 439 * LIBMTP_HANDLER_RETURN_ERROR on error or 440 * LIBMTP_HANDLER_RETURN_CANCEL to cancel the transfer 441 */ 442 typedef uint16_t (* MTPDataGetFunc) (void* params, void* priv, 443 uint32_t wantlen, unsigned char *data, uint32_t *gotlen); 444 445 /** 446 * Callback function for put by handler function 447 * @param params the device parameters 448 * @param priv a user-defined dereferencable pointer 449 * @param sendlen the number of bytes available 450 * @param data a buffer to read the data from 451 * @param putlen pointer to the number of bytes actually read 452 * from data 453 * @return LIBMTP_HANDLER_RETURN_OK if successful, 454 * LIBMTP_HANDLER_RETURN_ERROR on error or 455 * LIBMTP_HANDLER_RETURN_CANCEL to cancel the transfer 456 */ 457 typedef uint16_t (* MTPDataPutFunc) (void* params, void* priv, 458 uint32_t sendlen, unsigned char *data, uint32_t *putlen); 459 460 /** 461 * The return codes for the get/put functions 462 */ 463 #define LIBMTP_HANDLER_RETURN_OK 0 464 #define LIBMTP_HANDLER_RETURN_ERROR 1 465 #define LIBMTP_HANDLER_RETURN_CANCEL 2 466 467 /** 468 * @} 469 * @defgroup structar libmtp data structures 470 * @{ 471 */ 472 473 /** 474 * A data structure to hold MTP device entries. 475 */ 476 struct LIBMTP_device_entry_struct { 477 char *vendor; /**< The vendor of this device */ 478 uint16_t vendor_id; /**< Vendor ID for this device */ 479 char *product; /**< The product name of this device */ 480 uint16_t product_id; /**< Product ID for this device */ 481 uint32_t device_flags; /**< Bugs, device specifics etc */ 482 }; 483 484 /** 485 * A data structure to hold a raw MTP device connected 486 * to the bus. 487 */ 488 struct LIBMTP_raw_device_struct { 489 LIBMTP_device_entry_t device_entry; /**< The device entry for this raw device */ 490 uint32_t bus_location; /**< Location of the bus, if device available */ 491 uint8_t devnum; /**< Device number on the bus, if device available */ 492 }; 493 494 /** 495 * A data structure to hold errors from the library. 496 */ 497 struct LIBMTP_error_struct { 498 LIBMTP_error_number_t errornumber; 499 char *error_text; 500 LIBMTP_error_t *next; 501 }; 502 503 /** 504 * A data structure to hold allowed ranges of values 505 */ 506 struct LIBMTP_allowed_values_struct { 507 uint8_t u8max; 508 uint8_t u8min; 509 uint8_t u8step; 510 uint8_t* u8vals; 511 int8_t i8max; 512 int8_t i8min; 513 int8_t i8step; 514 int8_t* i8vals; 515 uint16_t u16max; 516 uint16_t u16min; 517 uint16_t u16step; 518 uint16_t* u16vals; 519 int16_t i16max; 520 int16_t i16min; 521 int16_t i16step; 522 int16_t* i16vals; 523 uint32_t u32max; 524 uint32_t u32min; 525 uint32_t u32step; 526 uint32_t* u32vals; 527 int32_t i32max; 528 int32_t i32min; 529 int32_t i32step; 530 int32_t* i32vals; 531 uint64_t u64max; 532 uint64_t u64min; 533 uint64_t u64step; 534 uint64_t* u64vals; 535 int64_t i64max; 536 int64_t i64min; 537 int64_t i64step; 538 int64_t* i64vals; 539 /** 540 * Number of entries in the vals array 541 */ 542 uint16_t num_entries; 543 /** 544 * The datatype specifying which of the above is used 545 */ 546 LIBMTP_datatype_t datatype; 547 /** 548 * Non zero for range, 0 for enum 549 */ 550 int is_range; 551 }; 552 553 /** 554 * Main MTP device object struct 555 */ 556 struct LIBMTP_mtpdevice_struct { 557 /** 558 * Object bitsize, typically 32 or 64. 559 */ 560 uint8_t object_bitsize; 561 /** 562 * Parameters for this device, must be cast into 563 * \c (PTPParams*) before internal use. 564 */ 565 void *params; 566 /** 567 * USB device for this device, must be cast into 568 * \c (PTP_USB*) before internal use. 569 */ 570 void *usbinfo; 571 /** 572 * The storage for this device, do not use strings in here without 573 * copying them first, and beware that this list may be rebuilt at 574 * any time. 575 * @see LIBMTP_Get_Storage() 576 */ 577 LIBMTP_devicestorage_t *storage; 578 /** 579 * The error stack. This shall be handled using the error getting 580 * and clearing functions, not by dereferencing this list. 581 */ 582 LIBMTP_error_t *errorstack; 583 /** The maximum battery level for this device */ 584 uint8_t maximum_battery_level; 585 /** Default music folder */ 586 uint32_t default_music_folder; 587 /** Default playlist folder */ 588 uint32_t default_playlist_folder; 589 /** Default picture folder */ 590 uint32_t default_picture_folder; 591 /** Default video folder */ 592 uint32_t default_video_folder; 593 /** Default organizer folder */ 594 uint32_t default_organizer_folder; 595 /** Default ZENcast folder (only Creative devices...) */ 596 uint32_t default_zencast_folder; 597 /** Default Album folder */ 598 uint32_t default_album_folder; 599 /** Default Text folder */ 600 uint32_t default_text_folder; 601 /** Per device iconv() converters, only used internally */ 602 void *cd; 603 604 /** Pointer to next device in linked list; NULL if this is the last device */ 605 LIBMTP_mtpdevice_t *next; 606 }; 607 608 /** 609 * MTP file struct 610 */ 611 struct LIBMTP_file_struct { 612 uint32_t item_id; /**< Unique item ID */ 613 uint32_t parent_id; /**< ID of parent folder */ 614 uint32_t storage_id; /**< ID of storage holding this file */ 615 char *filename; /**< Filename of this file */ 616 uint64_t filesize; /**< Size of file in bytes */ 617 time_t modificationdate; /**< Date of last alteration of the file */ 618 LIBMTP_filetype_t filetype; /**< Filetype used for the current file */ 619 LIBMTP_file_t *next; /**< Next file in list or NULL if last file */ 620 }; 621 622 /** 623 * MTP track struct 624 */ 625 struct LIBMTP_track_struct { 626 uint32_t item_id; /**< Unique item ID */ 627 uint32_t parent_id; /**< ID of parent folder */ 628 uint32_t storage_id; /**< ID of storage holding this track */ 629 char *title; /**< Track title */ 630 char *artist; /**< Name of recording artist */ 631 char *composer; /**< Name of recording composer */ 632 char *genre; /**< Genre name for track */ 633 char *album; /**< Album name for track */ 634 char *date; /**< Date of original recording as a string */ 635 char *filename; /**< Original filename of this track */ 636 uint16_t tracknumber; /**< Track number (in sequence on recording) */ 637 uint32_t duration; /**< Duration in milliseconds */ 638 uint32_t samplerate; /**< Sample rate of original file, min 0x1f80 max 0xbb80 */ 639 uint16_t nochannels; /**< Number of channels in this recording 0 = unknown, 1 or 2 */ 640 uint32_t wavecodec; /**< FourCC wave codec name */ 641 uint32_t bitrate; /**< (Average) bitrate for this file min=1 max=0x16e360 */ 642 uint16_t bitratetype; /**< 0 = unused, 1 = constant, 2 = VBR, 3 = free */ 643 uint16_t rating; /**< User rating 0-100 (0x00-0x64) */ 644 uint32_t usecount; /**< Number of times used/played */ 645 uint64_t filesize; /**< Size of track file in bytes */ 646 time_t modificationdate; /**< Date of last alteration of the track */ 647 LIBMTP_filetype_t filetype; /**< Filetype used for the current track */ 648 LIBMTP_track_t *next; /**< Next track in list or NULL if last track */ 649 }; 650 651 /** 652 * MTP Playlist structure 653 */ 654 struct LIBMTP_playlist_struct { 655 uint32_t playlist_id; /**< Unique playlist ID */ 656 uint32_t parent_id; /**< ID of parent folder */ 657 uint32_t storage_id; /**< ID of storage holding this playlist */ 658 char *name; /**< Name of playlist */ 659 uint32_t *tracks; /**< The tracks in this playlist */ 660 uint32_t no_tracks; /**< The number of tracks in this playlist */ 661 LIBMTP_playlist_t *next; /**< Next playlist or NULL if last playlist */ 662 }; 663 664 /** 665 * MTP Album structure 666 */ 667 struct LIBMTP_album_struct { 668 uint32_t album_id; /**< Unique playlist ID */ 669 uint32_t parent_id; /**< ID of parent folder */ 670 uint32_t storage_id; /**< ID of storage holding this album */ 671 char *name; /**< Name of album */ 672 char *artist; /**< Name of album artist */ 673 char *composer; /**< Name of recording composer */ 674 char *genre; /**< Genre of album */ 675 uint32_t *tracks; /**< The tracks in this album */ 676 uint32_t no_tracks; /**< The number of tracks in this album */ 677 LIBMTP_album_t *next; /**< Next album or NULL if last album */ 678 }; 679 680 /** 681 * MTP Folder structure 682 */ 683 struct LIBMTP_folder_struct { 684 uint32_t folder_id; /**< Unique folder ID */ 685 uint32_t parent_id; /**< ID of parent folder */ 686 uint32_t storage_id; /**< ID of storage holding this folder */ 687 char *name; /**< Name of folder */ 688 LIBMTP_folder_t *sibling; /**< Next folder at same level or NULL if no more */ 689 LIBMTP_folder_t *child; /**< Child folder or NULL if no children */ 690 }; 691 692 /** 693 * LIBMTP Object RepresentativeSampleData Structure 694 */ 695 struct LIBMTP_filesampledata_struct { 696 uint32_t width; /**< Width of sample if it is an image */ 697 uint32_t height; /**< Height of sample if it is an image */ 698 uint32_t duration; /**< Duration in milliseconds if it is audio */ 699 LIBMTP_filetype_t filetype; /**< Filetype used for the sample */ 700 uint64_t size; /**< Size of sample data in bytes */ 701 char *data; /**< Sample data */ 702 }; 703 704 /** 705 * LIBMTP Device Storage structure 706 */ 707 struct LIBMTP_devicestorage_struct { 708 uint32_t id; /**< Unique ID for this storage */ 709 uint16_t StorageType; /**< Storage type */ 710 uint16_t FilesystemType; /**< Filesystem type */ 711 uint16_t AccessCapability; /**< Access capability */ 712 uint64_t MaxCapacity; /**< Maximum capability */ 713 uint64_t FreeSpaceInBytes; /**< Free space in bytes */ 714 uint64_t FreeSpaceInObjects; /**< Free space in objects */ 715 char *StorageDescription; /**< A brief description of this storage */ 716 char *VolumeIdentifier; /**< A volume identifier */ 717 LIBMTP_devicestorage_t *next; /**< Next storage, follow this link until NULL */ 718 LIBMTP_devicestorage_t *prev; /**< Previous storage */ 719 }; 720 721 722 /** @} */ 723 724 /* Make functions available for C++ */ 725 #ifdef __cplusplus 726 extern "C" { 727 #endif 728 729 /** 730 * @defgroup internals The libmtp internals API. 731 * @{ 732 */ 733 void LIBMTP_Init(void); 734 int LIBMTP_Get_Supported_Devices_List(LIBMTP_device_entry_t ** const, int * const); 735 /** 736 * @} 737 * @defgroup basic The basic device management API. 738 * @{ 739 */ 740 LIBMTP_error_number_t LIBMTP_Detect_Raw_Devices(LIBMTP_raw_device_t **, int *); 741 LIBMTP_mtpdevice_t *LIBMTP_Open_Raw_Device(LIBMTP_raw_device_t *); 742 /* Begin old, legacy interface */ 743 LIBMTP_mtpdevice_t *LIBMTP_Get_First_Device(void); 744 LIBMTP_error_number_t LIBMTP_Get_Connected_Devices(LIBMTP_mtpdevice_t **); 745 uint32_t LIBMTP_Number_Devices_In_List(LIBMTP_mtpdevice_t *); 746 void LIBMTP_Release_Device_List(LIBMTP_mtpdevice_t*); 747 /* End old, legacy interface */ 748 void LIBMTP_Release_Device(LIBMTP_mtpdevice_t*); 749 void LIBMTP_Dump_Device_Info(LIBMTP_mtpdevice_t*); 750 int LIBMTP_Reset_Device(LIBMTP_mtpdevice_t*); 751 char *LIBMTP_Get_Manufacturername(LIBMTP_mtpdevice_t*); 752 char *LIBMTP_Get_Modelname(LIBMTP_mtpdevice_t*); 753 char *LIBMTP_Get_Serialnumber(LIBMTP_mtpdevice_t*); 754 char *LIBMTP_Get_Deviceversion(LIBMTP_mtpdevice_t*); 755 char *LIBMTP_Get_Friendlyname(LIBMTP_mtpdevice_t*); 756 int LIBMTP_Set_Friendlyname(LIBMTP_mtpdevice_t*, char const * const); 757 char *LIBMTP_Get_Syncpartner(LIBMTP_mtpdevice_t*); 758 int LIBMTP_Set_Syncpartner(LIBMTP_mtpdevice_t*, char const * const); 759 int LIBMTP_Get_Batterylevel(LIBMTP_mtpdevice_t *, 760 uint8_t * const, 761 uint8_t * const); 762 int LIBMTP_Get_Secure_Time(LIBMTP_mtpdevice_t *, char ** const); 763 int LIBMTP_Get_Device_Certificate(LIBMTP_mtpdevice_t *, char ** const); 764 int LIBMTP_Get_Supported_Filetypes(LIBMTP_mtpdevice_t *, uint16_t ** const, uint16_t * const); 765 LIBMTP_error_t *LIBMTP_Get_Errorstack(LIBMTP_mtpdevice_t*); 766 void LIBMTP_Clear_Errorstack(LIBMTP_mtpdevice_t*); 767 void LIBMTP_Dump_Errorstack(LIBMTP_mtpdevice_t*); 768 769 void LIBMTP_Set_Device_Timeout(LIBMTP_mtpdevice_t *device, int milliseconds); 770 void LIBMTP_Get_Device_Timeout(LIBMTP_mtpdevice_t *device, int * milliseconds); 771 772 #define LIBMTP_STORAGE_SORTBY_NOTSORTED 0 773 #define LIBMTP_STORAGE_SORTBY_FREESPACE 1 774 #define LIBMTP_STORAGE_SORTBY_MAXSPACE 2 775 776 int LIBMTP_Get_Storage(LIBMTP_mtpdevice_t *, int const); 777 int LIBMTP_Format_Storage(LIBMTP_mtpdevice_t *, LIBMTP_devicestorage_t *); 778 779 /** 780 * Get/set arbitrary properties. These do not update the cache; should only be used on 781 * properties not stored in structs 782 */ 783 char *LIBMTP_Get_String_From_Object(LIBMTP_mtpdevice_t *, uint32_t const, LIBMTP_property_t const); 784 uint64_t LIBMTP_Get_u64_From_Object(LIBMTP_mtpdevice_t *, uint32_t const, 785 LIBMTP_property_t const, uint64_t const); 786 uint32_t LIBMTP_Get_u32_From_Object(LIBMTP_mtpdevice_t *, uint32_t const, 787 LIBMTP_property_t const, uint32_t const); 788 uint16_t LIBMTP_Get_u16_From_Object(LIBMTP_mtpdevice_t *, uint32_t const, 789 LIBMTP_property_t const, uint16_t const); 790 uint8_t LIBMTP_Get_u8_From_Object(LIBMTP_mtpdevice_t *, uint32_t const, 791 LIBMTP_property_t const, uint8_t const); 792 int LIBMTP_Set_Object_String(LIBMTP_mtpdevice_t *, uint32_t const, 793 LIBMTP_property_t const, char const * const); 794 int LIBMTP_Set_Object_u32(LIBMTP_mtpdevice_t *, uint32_t const, 795 LIBMTP_property_t const, uint32_t const); 796 int LIBMTP_Set_Object_u16(LIBMTP_mtpdevice_t *, uint32_t const, 797 LIBMTP_property_t const, uint16_t const); 798 int LIBMTP_Set_Object_u8(LIBMTP_mtpdevice_t *, uint32_t const, 799 LIBMTP_property_t const, uint8_t const); 800 char const * LIBMTP_Get_Property_Description(LIBMTP_property_t inproperty); 801 int LIBMTP_Is_Property_Supported(LIBMTP_mtpdevice_t*, LIBMTP_property_t const, 802 LIBMTP_filetype_t const); 803 int LIBMTP_Get_Allowed_Property_Values(LIBMTP_mtpdevice_t*, LIBMTP_property_t const, 804 LIBMTP_filetype_t const, LIBMTP_allowed_values_t*); 805 void LIBMTP_destroy_allowed_values_t(LIBMTP_allowed_values_t*); 806 807 /** 808 * @} 809 * @defgroup files The file management API. 810 * @{ 811 */ 812 LIBMTP_file_t *LIBMTP_new_file_t(void); 813 void LIBMTP_destroy_file_t(LIBMTP_file_t*); 814 char const * LIBMTP_Get_Filetype_Description(LIBMTP_filetype_t); 815 LIBMTP_file_t *LIBMTP_Get_Filelisting(LIBMTP_mtpdevice_t *); 816 LIBMTP_file_t *LIBMTP_Get_Filelisting_With_Callback(LIBMTP_mtpdevice_t *, 817 LIBMTP_progressfunc_t const, void const * const); 818 LIBMTP_file_t *LIBMTP_Get_Filemetadata(LIBMTP_mtpdevice_t *, uint32_t const); 819 int LIBMTP_Get_File_To_File(LIBMTP_mtpdevice_t*, uint32_t, char const * const, 820 LIBMTP_progressfunc_t const, void const * const); 821 int LIBMTP_Get_File_To_File_Descriptor(LIBMTP_mtpdevice_t*, uint32_t const, int const, 822 LIBMTP_progressfunc_t const, void const * const, struct utimbuf * mtime); 823 int LIBMTP_Get_File_To_Handler(LIBMTP_mtpdevice_t *, uint32_t const, MTPDataPutFunc, void *, 824 LIBMTP_progressfunc_t const, void const * const); 825 int LIBMTP_Send_File_From_File(LIBMTP_mtpdevice_t *, char const * const, 826 LIBMTP_file_t * const, LIBMTP_progressfunc_t const, 827 void const * const); 828 int LIBMTP_Send_File_From_File_Descriptor(LIBMTP_mtpdevice_t *, int const, 829 LIBMTP_file_t * const, LIBMTP_progressfunc_t const, 830 void const * const); 831 int LIBMTP_Send_File_From_Handler(LIBMTP_mtpdevice_t *, MTPDataGetFunc, void *, 832 LIBMTP_file_t * const, LIBMTP_progressfunc_t const, void const * const); 833 int LIBMTP_Set_File_Name(LIBMTP_mtpdevice_t *, LIBMTP_file_t *, const char *); 834 LIBMTP_filesampledata_t *LIBMTP_new_filesampledata_t(void); 835 void LIBMTP_destroy_filesampledata_t(LIBMTP_filesampledata_t *); 836 int LIBMTP_Get_Representative_Sample_Format(LIBMTP_mtpdevice_t *, 837 LIBMTP_filetype_t const, 838 LIBMTP_filesampledata_t **); 839 int LIBMTP_Send_Representative_Sample(LIBMTP_mtpdevice_t *, uint32_t const, 840 LIBMTP_filesampledata_t *); 841 int LIBMTP_Get_Representative_Sample(LIBMTP_mtpdevice_t *, uint32_t const, 842 LIBMTP_filesampledata_t *); 843 844 845 void LIBMTP_Set_Load_Cache_On_Demand(int flag); 846 847 LIBMTP_file_t * LIBMTP_Get_Files_And_Folders(LIBMTP_mtpdevice_t *device, 848 uint32_t storageId, uint32_t parentId); 849 850 /** 851 * @} 852 * @defgroup tracks The track management API. 853 * @{ 854 */ 855 LIBMTP_track_t *LIBMTP_new_track_t(void); 856 void LIBMTP_destroy_track_t(LIBMTP_track_t*); 857 LIBMTP_track_t *LIBMTP_Get_Tracklisting(LIBMTP_mtpdevice_t*); 858 LIBMTP_track_t *LIBMTP_Get_Tracklisting_With_Callback(LIBMTP_mtpdevice_t*, 859 LIBMTP_progressfunc_t const, void const * const); 860 LIBMTP_track_t *LIBMTP_Get_Trackmetadata(LIBMTP_mtpdevice_t*, uint32_t const); 861 int LIBMTP_Get_Track_To_File(LIBMTP_mtpdevice_t*, uint32_t, char const * const, 862 LIBMTP_progressfunc_t const, void const * const); 863 int LIBMTP_Get_Track_To_File_Descriptor(LIBMTP_mtpdevice_t*, uint32_t const, int const, 864 LIBMTP_progressfunc_t const, void const * const, struct utimbuf * mtime); 865 int LIBMTP_Get_Track_To_Handler(LIBMTP_mtpdevice_t *, uint32_t const, MTPDataPutFunc, 866 void *, LIBMTP_progressfunc_t const, void const * const); 867 int LIBMTP_Send_Track_From_File(LIBMTP_mtpdevice_t *, 868 char const * const, LIBMTP_track_t * const, 869 LIBMTP_progressfunc_t const, 870 void const * const); 871 int LIBMTP_Send_Track_From_File_Descriptor(LIBMTP_mtpdevice_t *, 872 int const, LIBMTP_track_t * const, 873 LIBMTP_progressfunc_t const, 874 void const * const); 875 int LIBMTP_Send_Track_From_Handler(LIBMTP_mtpdevice_t *, 876 MTPDataGetFunc, void *, LIBMTP_track_t * const, 877 LIBMTP_progressfunc_t const, 878 void const * const); 879 int LIBMTP_Update_Track_Metadata(LIBMTP_mtpdevice_t *, 880 LIBMTP_track_t const * const); 881 int LIBMTP_Track_Exists(LIBMTP_mtpdevice_t *, uint32_t); 882 int LIBMTP_Set_Track_Name(LIBMTP_mtpdevice_t *, LIBMTP_track_t *, const char *); 883 /** @} */ 884 885 /** 886 * @} 887 * @defgroup folders The folder management API. 888 * @{ 889 */ 890 LIBMTP_folder_t *LIBMTP_new_folder_t(void); 891 void LIBMTP_destroy_folder_t(LIBMTP_folder_t*); 892 LIBMTP_folder_t *LIBMTP_Get_Folder_List(LIBMTP_mtpdevice_t*); 893 LIBMTP_folder_t *LIBMTP_Find_Folder(LIBMTP_folder_t*, uint32_t const); 894 uint32_t LIBMTP_Create_Folder(LIBMTP_mtpdevice_t*, char *, uint32_t, uint32_t); 895 int LIBMTP_Set_Folder_Name(LIBMTP_mtpdevice_t *, LIBMTP_folder_t *, const char *); 896 /** @} */ 897 898 899 /** 900 * @} 901 * @defgroup playlists The audio/video playlist management API. 902 * @{ 903 */ 904 LIBMTP_playlist_t *LIBMTP_new_playlist_t(void); 905 void LIBMTP_destroy_playlist_t(LIBMTP_playlist_t *); 906 LIBMTP_playlist_t *LIBMTP_Get_Playlist_List(LIBMTP_mtpdevice_t *); 907 LIBMTP_playlist_t *LIBMTP_Get_Playlist(LIBMTP_mtpdevice_t *, uint32_t const); 908 int LIBMTP_Create_New_Playlist(LIBMTP_mtpdevice_t *, LIBMTP_playlist_t * const); 909 int LIBMTP_Update_Playlist(LIBMTP_mtpdevice_t *, LIBMTP_playlist_t * const); 910 int LIBMTP_Set_Playlist_Name(LIBMTP_mtpdevice_t *, LIBMTP_playlist_t *, const char *); 911 912 /** 913 * @} 914 * @defgroup albums The audio/video album management API. 915 * @{ 916 */ 917 LIBMTP_album_t *LIBMTP_new_album_t(void); 918 void LIBMTP_destroy_album_t(LIBMTP_album_t *); 919 LIBMTP_album_t *LIBMTP_Get_Album_List(LIBMTP_mtpdevice_t *); 920 LIBMTP_album_t *LIBMTP_Get_Album(LIBMTP_mtpdevice_t *, uint32_t const); 921 int LIBMTP_Create_New_Album(LIBMTP_mtpdevice_t *, LIBMTP_album_t * const); 922 int LIBMTP_Update_Album(LIBMTP_mtpdevice_t *, LIBMTP_album_t const * const); 923 int LIBMTP_Set_Album_Name(LIBMTP_mtpdevice_t *, LIBMTP_album_t *, const char *); 924 925 /** 926 * @} 927 * @defgroup objects The object management API. 928 * @{ 929 */ 930 int LIBMTP_Delete_Object(LIBMTP_mtpdevice_t *, uint32_t); 931 int LIBMTP_Set_Object_Filename(LIBMTP_mtpdevice_t *, uint32_t , char *); 932 933 /** @} */ 934 935 /* End of C++ exports */ 936 #ifdef __cplusplus 937 } 938 #endif 939 940 #endif /* LIBMTP_H_INCLUSION_GUARD */ 941 942