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