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