1 /* ------------------------------------------------------------------ 2 * Copyright (C) 1998-2009 PacketVideo 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either 13 * express or implied. 14 * See the License for the specific language governing permissions 15 * and limitations under the License. 16 * ------------------------------------------------------------------- 17 */ 18 /** 19 * @file pv_id3_parcom.h 20 * @brief ID3 tag parser-composer utility 21 */ 22 23 #ifndef PV_ID3_PARCOM_H_INCLUDED 24 #define PV_ID3_PARCOM_H_INCLUDED 25 26 #ifndef OSCL_BASE_H_INCLUDED 27 #include "oscl_base.h" 28 #endif 29 #ifndef OSCL_STRING_H_INCLUDED 30 #include "oscl_string.h" 31 #endif 32 #ifndef OSCL_MEM_H_INCLUDED 33 #include "oscl_mem.h" 34 #endif 35 #ifndef OSCL_STRING_CONTAINERS_H_INCLUDED 36 #include "oscl_string_containers.h" 37 #endif 38 #ifndef OSCL_VECTOR_H_INCLUDED 39 #include "oscl_vector.h" 40 #endif 41 #ifndef OSCL_REFCOUNTER_MEMFRAG_H_INCLUDED 42 #include "oscl_refcounter_memfrag.h" 43 #endif 44 #ifndef OSCL_SHARED_PTR_H_INCLUDED 45 #include "oscl_shared_ptr.h" 46 #endif 47 #ifndef PVMI_KVP_INCLUDED 48 #include "pvmi_kvp.h" 49 #endif 50 #ifndef PVMF_META_DATA_H_INCLUDED 51 #include "pvmf_meta_data_types.h" 52 #endif 53 #ifndef PVFILE_H_INCLUDED 54 #include "pvfile.h" 55 #endif 56 #ifndef PVMF_RETURN_CODES_H_INCLUDED 57 #include "pvmf_return_codes.h" 58 #endif 59 #ifndef PV_ID3_PARCOM_TYPES_H_INCLUDED 60 #include "pv_id3_parcom_types.h" 61 #endif 62 #ifndef OSCL_STRING_UTILS_H_INCLUDED 63 #include "oscl_string_utils.h" 64 #endif 65 #ifndef OSCL_UTF8CONV_H 66 #include "oscl_utf8conv.h" 67 #endif 68 #ifndef PV_ID3_PARCOM_CONSTANTS_H_INCLUDED 69 #include "pv_id3_parcom_constants.h" 70 #endif 71 72 /** Forward declaration */ 73 class PVLogger; 74 75 /** 76 * PVID3ParCom is an ID3 Tag parser-composer utility. This utiltiy allows user to parse an ID3 tag 77 * to retrieve tag information, modify an existing ID3 tag and compose a new ID3 tag. 78 */ 79 class PVID3ParCom 80 { 81 public: 82 /** Default constructor */ 83 OSCL_IMPORT_REF PVID3ParCom(); 84 85 /** Destructor */ 86 OSCL_IMPORT_REF ~PVID3ParCom(); 87 88 /** 89 * @brief Checks the file for the presence of ID3V2 Tags. 90 * 91 * This function checks the file for the presence of ID3V2 Tag 92 * This tag is denoted by the string "ID3" at the begining of file. 93 * This method also reads the Id3 tag size from the file and returns 94 * to the caller. 95 * 96 * @returns True if Id3V2 tag present otherwise False 97 * @ aTagSize: size of the ID3 tag, if present, else 0 98 */ 99 OSCL_IMPORT_REF bool IsID3V2Present(PVFile* aFile, uint32& aTagSize); 100 101 /** 102 * Gets size of ID3 tag in the specified file without parsing the entire tag for its data. 103 * 104 * @param aFile File handle of the file containing the ID3 tag 105 * @return Size of ID3 tag. Returns 0 if ID3 tag is not found. 106 */ 107 OSCL_IMPORT_REF uint32 GetID3TagSize(PVFile* aFile); 108 109 /** 110 * Gets size of ID3 tag in a memory fragment without parsing the entire tag for its data. 111 * 112 * @param aTag Memory fragment containing the ID3 tag 113 * @return Size of ID3 tag. Returns 0 if ID3 tag is not found. 114 */ 115 OSCL_IMPORT_REF uint32 GetID3TagSize(const OsclMemoryFragment& aTag); 116 /** 117 * Gets the size of a parsed ID3 tag. 118 * 119 * @return Size of ID3 tag. Returns 0 if called before an ID3 tag is parsed by ParseID3Tag() call. 120 */ 121 OSCL_IMPORT_REF uint32 GetID3TagSize(); 122 123 /** 124 * Sets the maximum size of a composed ID3 tag. It is an option to pad the composed ID3 tag 125 * to the specified maximum size. If the composed ID3 tag exceeds the maximum size, one 126 * or more ID3 frames data will be truncated. This API is applicable only for ID3V2 tags. 127 * 128 * @param aUseMaxSize When set to true, the composed ID3 tag will have a maximum size of 129 * aMaxSize. When set to false, the tag will not have a maximum size. 130 * By default, maximum tag size is disabled by this library. 131 * @param aMaxSize Maximum size of the composed ID3 tag in bytes 132 * @param aUsePadding When set to true, the composed ID3 tag will be padded to the 133 * specified maximum size. 134 * @return Completion status. Returns PVMFErrNotSupported if ID3V1 is used. 135 */ 136 OSCL_IMPORT_REF PVMFStatus SetMaxID3TagSize(bool aUseMaxSize, uint32 aMaxSize, bool aUsePadding); 137 138 /** 139 * Parse an ID3 tag from the specified file. 140 * 141 * @param aFile File handle of the file containing the ID3 tag to be parsed 142 * @return Completion status. If no ID3 tag is found in the file, PVMFFailure is returned. 143 */ 144 OSCL_IMPORT_REF PVMFStatus ParseID3Tag(PVFile* aFile, uint32 buffsize = 100); 145 146 /** 147 * Parse an ID3 tag from the specified memory fragment. 148 * 149 * @param aTag Memory fragment containing the ID3 tag to be parsed 150 * @return Completion status. If no ID3 tag is found in the memory fragment, PVMFFailure is returned. 151 */ 152 OSCL_IMPORT_REF PVMFStatus ParseID3Tag(const OsclMemoryFragment& aTag); 153 154 /** 155 * Query the version of ID3 used for this tag. 156 * 157 * @return ID3 version of the tag. 158 */ 159 OSCL_IMPORT_REF PVID3Version GetID3Version() const; 160 161 /** 162 * Query if id3v1 present in the clip. 163 * 164 * @return true if present 165 */ 166 OSCL_IMPORT_REF bool IsID3V1Present() const; 167 168 /** 169 * Query if id3v2 present in the clip. 170 * 171 * @return true if present 172 */ 173 OSCL_IMPORT_REF bool IsID3V2Present() const; 174 175 /** 176 * Retrieve a vector of key-value pairs containing data of all ID3 frames in the ID3 tag. 177 * 178 * @param aFrames Output parameter to store key-value pairs containing data of ID3 frames from the tag. 179 * @return Status of completion. 180 */ 181 OSCL_IMPORT_REF PVMFStatus GetID3Frames(PvmiKvpSharedPtrVector& aFrames); 182 183 /** 184 * Retrieve an ID3 frame of the specified type in the ID3 tag. 185 * 186 * @param aFrameType Type of ID3 frame to be retrieved 187 * @param aFrame Output parameter to store key-value pair containing data of requested ID3 frame. 188 * @return Status of completion. Returns PVMFFailure if a frame of the specified 189 * type is not found. 190 */ 191 OSCL_IMPORT_REF PVMFStatus GetID3Frame(const OSCL_String& aFrameType, PvmiKvpSharedPtrVector& aFrame); 192 193 /** 194 * Check if frame of aFrameType is available 195 * @param aFrameType Type of ID3 frame 196 * @return true if frame is available otherwise false 197 */ 198 OSCL_IMPORT_REF bool IsID3FrameAvailable(const OSCL_String& aFrameType); 199 200 /** 201 * Sets ID3 version to be used. 202 * 203 * When composing a new ID3 tag, the default ID3 version is v2.4. When modifying 204 * an existing ID3 tag, if it is ID3v2.x and is changed to ID3v1.x, ID3 frames 205 * that are not supported by ID3v1.x will be removed from the tag and data strings 206 * will be trimmed to the maximum lengths specified in ID3v1.x. 207 * 208 * @param aVersion ID3 version. 209 * @return Status of completion. 210 */ 211 OSCL_IMPORT_REF PVMFStatus SetID3Version(PVID3Version aVersion); 212 213 /** 214 * Sets an ID3 frame in the ID3 tag. 215 * 216 * If the frame does not already exist, a new frame will be created and added 217 * to the tag. If a frame of the same type already exists, the frame data will 218 * be updated and saved to the tag. 219 * 220 * @param aFrame ID3 frame to be set in the tag. 221 * @return Status of completion. 222 */ 223 OSCL_IMPORT_REF PVMFStatus SetID3Frame(const PvmiKvp& aFrame); 224 225 /** 226 * Removes an ID3 frame of the specified type in the ID3 tag. 227 * 228 * @param aFrameType Type of ID3 frame to be removed. 229 * @return Completion status. Returns PVMFFailure if ID3 frame of the specified type 230 * is not found in the tag. 231 */ 232 OSCL_IMPORT_REF PVMFStatus RemoveID3Frame(const OSCL_String& aFrameType); 233 234 /** 235 * Compose an ID3 tag and return a shared pointer to the formatted tag to user. 236 * 237 * ID3 tag is composed using ID3 frames that are set for the tag. Data strings in ID3 frames are 238 * converted from Unicode to the character set specified in the frame when composing the tag. 239 * The tag is formatted to the specified ID3 version and written to the memory fragment provided 240 * by user. This method will erase all data from the memory fragment before writing the ID3 tag. 241 * If the memory fragment does not contain allocated memory or the capacity of fragment is less 242 * than the size of ID3 tag to be written, this method would allocate memory before writing the ID3 243 * tag. There must be at least one valid ID3 frame assoicated to the tag to compose successfully. 244 * 245 * When composing a new ID3 tag (i.e. not editing an existing tag), if no ID3 version is specified 246 * through SetID3Version(), it is defaulted to ID3 v2.4. 247 * 248 * @param aTag Output parameter of memory fragment to which the formatted ID3 tag data will be written. 249 * @return Completion status. Returns PVMFFailure if no ID3 frame is associated with this tag. 250 */ 251 OSCL_IMPORT_REF PVMFStatus ComposeID3Tag(OsclRefCounterMemFrag& aTag); 252 253 /** 254 * Reset the parser-composer and remove all ID3 frames. 255 * 256 * @return Completion status. 257 */ 258 OSCL_IMPORT_REF PVMFStatus Reset(); 259 260 /** 261 * This function returns byte offset to the end of id3 tag. Audio frame follows ID3 tag. 262 * 263 * @return byte offset to end of id3 tag. 264 */ 265 266 OSCL_IMPORT_REF uint32 GetByteOffsetToStartOfAudioFrames() 267 { 268 return iByteOffsetToStartOfAudioFrames; 269 } 270 271 /** 272 * This function looks for ID3 V2.4 tag at the end of file. 273 * It will look for ID3 footer starting from the offset till buff_sz. If footer is found, it will get the 274 * id3 tag size from the footer header and parse ID3 tag. 275 * @param buff_sz size of the buffer to look for footer 276 * @param offset in file from the end of file. e.g An offset of 0 means end of file 277 * @return Comletion status. 278 */ 279 280 OSCL_IMPORT_REF PVMFStatus LookForV2_4Footer(uint32 buff_sz, uint32 offset); 281 /** 282 * This function will look for ID3 footer starting from the offset till buff_sz. 283 * @param buff_sz size of the buffer to look for footer 284 * @param offset in file from the end of file. e.g An offset of 0 means end of file 285 * @return footer location in file otherwise 0 if no footer is found 286 */ 287 288 uint32 SearchTagV2_4(uint32 buff_sz, uint32 offset); 289 290 291 public: 292 /** Enumerated list of supported character sets */ 293 typedef enum 294 { 295 PV_ID3_CHARSET_INVALID = -1, 296 PV_ID3_CHARSET_ISO88591 = 0, 297 PV_ID3_CHARSET_UTF16 = 1, 298 PV_ID3_CHARSET_UTF16BE = 2, 299 PV_ID3_CHARSET_UTF8 = 3, 300 PV_ID3_CHARSET_END = 4, 301 } PVID3CharacterSet; 302 303 private: 304 /** Enumerated list of ID3 Frame Types */ 305 typedef enum 306 { 307 PV_ID3_FRAME_INVALID = -3, 308 PV_ID3_FRAME_CANDIDATE, /**< Frame ID doesn't match with known frame IDs. 309 The frame ID made out of the characters capital A-Z and 0-9.*/ 310 PV_ID3_FRAME_UNRECOGNIZED, /** Valid frame ID, but ID3 parcom doesn't support. */ 311 PV_ID3_FRAME_TITLE, /**< Title. Supported by all ID3 versions. Maximum 30 characters for 312 ID3v1.x. There is no maximum length limit for ID3v2.x. */ 313 PV_ID3_FRAME_ARTIST, /**< Artist. Supported by all ID3 versions. Maximum 30 characters for 314 ID3v1.x. There is no maximum length limit for ID3v2.x*/ 315 PV_ID3_FRAME_ALBUM, /**< Album. Supported by all ID3 versions. Maximum 30 characters for 316 ID3v1.x. There is no maximum length limit for ID3v2.x */ 317 PV_ID3_FRAME_YEAR, /**< 4-character numeric string with the year of the recording. 318 Supported by all ID3 version. */ 319 PV_ID3_FRAME_COMMENT, /**< Comment. Supported by all ID3 versions. Maximum 30 characters for 320 ID3v1.x. There is no maximum length limit for ID3v2.x. */ 321 PV_ID3_FRAME_TRACK_NUMBER, /**< Numeric string of track number on Album. Supported by ID3v1.1 and later. */ 322 PV_ID3_FRAME_GENRE, /**< Genre of the music. For ID3v1.x, numeric string of genre type value 323 defined at http://www.id3.org/id3v2.3.0.html#secA should be used. 324 ID3v2.x should use the genre name, or refer to ID3v1.x genre type 325 using the format "(genre_number)" where genre_number is a numeric 326 string of ID3v1.x genre type value. */ 327 PV_ID3_FRAME_COPYRIGHT, /**< Copyright message. It must begin with a 4-character numeric string of 328 the year of copyright and a space character. Supported by ID3v2.x or later. */ 329 PV_ID3_FRAME_TRACK_LENGTH, /**< Track length. The duration in milliseconds.*/ 330 PV_ID3_FRAME_DATE, 331 PV_ID3_FRAME_PADDED, /**< Padding. A frame padded with zero.*/ 332 333 PV_ID3_FRAME_PIC, /**< PIC. */ 334 PV_ID3_FRAME_APIC, /**< APIC.*/ 335 PV_ID3_FRAME_LYRICS, /**< Unsynchronized Lyrics.*/ 336 PV_ID3_FRAME_SEEK, /* For SEEK frame */ 337 PV_ID3_FRAME_RECORDING_TIME, /* RECORDING TIME */ 338 PV_ID3_FRAME_AUTHOR, /* author or writer*/ 339 PV_ID3_FRAME_COMPOSER, /* music composer */ 340 PV_ID3_FRAME_DESCRIPTION, /* brief description of the content */ 341 PV_ID3_FRAME_VERSION, /* Software version of the authoring software */ 342 PV_ID3_FRAME_PART_OF_SET, /* Which part of a set this belongs to */ 343 344 PV_ID3_FRAME_EEND /**< End. Marks end of frames.*/ 345 } PVID3FrameType; 346 347 /** 348 * @brief The TID3TagInfo class acts as temporary storage for information 349 * extracted from the different types of ID3 tags to a given ID3tag file. This 350 * class is created to keep track of certain qualities of an ID3 tag that 351 * the caller of the ID3 library would not need to know. 352 */ 353 struct TID3TagInfo 354 { 355 uint32 iPositionInFile; 356 PVID3CharacterSet iTextType; 357 358 uint32 iID3V2FrameSize; 359 uint32 iID3V2SeekOffset; 360 uint8 iID3V2TagFlagsV2; 361 uint32 iID3V2ExtendedHeaderSize; 362 uint32 iID3V2TagSize; 363 uint8 iID3V2FrameID[5]; 364 uint8 iID3V2FrameFlag[2]; 365 bool iFooterPresent; 366 uint8 iID3V2LanguageID[4]; 367 368 }; 369 370 /** 371 * @brief Checks the ID3 Tag v2.4 frame size whether it is syncsafe or not. 372 * 373 * This function validates next ID3 frame to check whether frame size is 374 * syncsafe. 375 * 376 * @returns Validated frame size 377 */ 378 uint32 ValidateFrameLengthV2_4(uint32 aFrameSize); 379 380 /** 381 * @brief Checks the ID3 Tag v2.4 frame is valid or not. 382 * 383 * This function validates ID3 frame type and then, frame size and flags 384 * 385 * @params 386 * [IN] bUseSyncSafeFrameSize - validate syncsafe/non-syncsafe frame size 387 * [OUT] frameType - frame type for frame currently validated 388 * 389 * @returns validation status 390 */ 391 bool ValidateFrameV2_4(PVID3FrameType& frameType, bool bUseSyncSafeFrameSize = true); 392 393 /** 394 * @brief Checks the file for the presence of ID3V1 Tag. 395 * 396 * This function checks the file for the presence of ID3V1 Tag. This tag is 397 * denoted by the string "TAG" starting 128 bytes in from the end-of-file. 398 * 399 * @returns True if Id3V1 tag present otherwise False 400 */ 401 bool CheckForTagID3V1(); 402 403 /** 404 * @brief Checks the file for the presence of ID3V2 Tag attached to 405 * the beginning of the ID3tag file. 406 * 407 * This function checks the file for the presence of ID3V2 Tag attached to 408 * the beginning of the ID3 file. This tag is denoted by the string "ID3" 409 * at the very beginning of the ID3 file. 410 * 411 * @returns True if Id3V2 tag present otherwise False 412 */ 413 bool CheckForTagID3V2(); 414 415 /** 416 * @brief Parses the file and populates the frame vector when an ID3V1 417 * tag is found and no ID3V2 tag was found. 418 * 419 * This function parses the file and populates the frame vector when 420 * an ID3V1 tag is found to be attached to the ID3 file and no ID3V2 tag was 421 * found. The data in the ID3V1 tag can only be ASCII, so the ConvertToUnicode 422 * must be called for all fields read from the ID3V1 tag. 423 * 424 * @param None 425 * @returns None 426 */ 427 void ReadID3V1Tag(); 428 429 /** 430 * @brief reads id3 V2 tag header. 431 * @param aReadTags, read the id3 frames when true, else just reads the header 432 * @@returns true if tags were read successfully 433 */ 434 bool ReadHeaderID3V2(bool aReadTags = true); 435 436 /** 437 * @brief Parses the ID3V2 tag frames from the file and populates the 438 * frame vector when an ID3V2 tag is found 439 * @param version ID3 V2 sub version number (v2.2, v2.3 or v2.4) 440 * * @returns number of tags successfully parsed 441 */ 442 int ReadTagID3V2(PVID3Version version); 443 444 /** 445 * @brief Parses the frame and populates the iID3TagInfo structure 446 * when an ID3V2 tag is found. 447 * 448 * This function parses the ID3 tag frames from the file and populates the 449 * frame vector when an ID3V2 tag is found attached to the start 450 * of a ID3 file. 451 * 452 * @param version ID3 V2 sub version number (v2.2, v2.3 or v2.4) 453 * @returns None 454 */ 455 void ReadFrameHeaderID3V2(PVID3Version version); 456 457 /** 458 * @brief Parses the frame and populates the iID3TagInfo structure 459 * when an ID3V2_2 tag is found. 460 * 461 * This function parses the ID3 tag frames from the file and populates the 462 * frame vector when an ID3V2_2 tag is found attached to the start 463 * of a ID3 file. 464 * 465 * @param None 466 * @returns None 467 */ 468 void ReadFrameHeaderID3V2_2(); 469 470 /** 471 * @brief Receives a ID3V2 frame and handles it accordingly. All of the frames 472 * sent to this function have ASCII strings in them. 473 * 474 * This function receives a ID3V2 frame and handles it accordingly. Each 475 * frame header is composed of 10 bytes - 4 bytes for FrameID, 4 bytes for 476 * FrameSize, and 2 bytes for FrameFlags, respectively. Once we have a 477 * frame's unique FrameID, we can handle the frame accordingly. (eg. The 478 * frame with FrameID = "TIT2" contains data describing the title of an ID3 479 * file. Clearly, the data in that frame should be copied to it respective 480 * location in frame vector. The location for the data with FrameID = "TIT2" 481 * goes in the Title frame. 482 * 483 * @param aFrameType Enumerated TFrameTypeID3V2 type; used to determine if 484 * Frame is supported 485 * @param aPos Position in file where frame data begins 486 * @param aSize Size of the frame data 487 * @returns None 488 */ 489 void HandleID3V2FrameDataASCII(PVID3FrameType aframeType, 490 uint32 aPos, 491 uint32 aSize); 492 493 /** 494 * @brief Receives a ID3V2 frame and handles it accordingly. All of the frames 495 * sent to this function have unicode strings in them. 496 * 497 * This function receives a ID3V2 frame and handles it accordingly. Each 498 * frame header is composed of 10 bytes - 4 bytes for FrameID, 4 bytes for 499 * FrameSize, and 2 bytes for FrameFlags, respectively. Once we have a 500 * frame's unique FrameID, we can handle the frame accordingly. (eg. The 501 * frame with FrameID = "TIT2" contains data describing the title of an ID3 502 * file. Clearly, the data in that frame should be copied to it respective 503 * location in Frame vector. The location for the data with FrameID = "TIT2" 504 * goes in the Title frame.iTitle buffer. All of the frames 505 * sent to this function have unicode strings in them that will need to be 506 * read different than the ASCII strings. 507 * 508 * @param aFrameType Enumerated TFrameTypeID3V2 type; used to determine if 509 * Frame is supported 510 * @param aPos Position in file where frame data begins 511 * @param aSize Size of the frame data 512 * @param aEndianType Flag indicator regarding the text endian type 513 * @returns None 514 */ 515 void HandleID3V2FrameDataUnicode16(PVID3FrameType aframeType, 516 uint32 aPos, 517 uint32 aSize, 518 uint32 aEndienType); 519 520 /** 521 * @brief Receives a ID3V2 frame and handles it accordingly. All of the frames 522 * sent to this function have UTF8 strings in them. 523 * 524 * This function receives a ID3V2 frame and handles it accordingly. Each 525 * frame header is composed of 10 bytes - 4 bytes for FrameID, 4 bytes for 526 * FrameSize, and 2 bytes for FrameFlags, respectively. Once we have a 527 * frame's unique FrameID, we can handle the frame accordingly. (eg. The 528 * frame with FrameID = "TIT2" contains data describing the title of an ID3 529 * file. Clearly, the data in that frame should be copied to it respective 530 * location in Frame vector. The location for the data with FrameID = "TIT2" 531 * goes in the Title frame. All of the frames sent to this function have UTF8 532 * strings in them that will need to be read different than the ASCII strings. 533 * 534 * @param aFrameType Enumerated TFrameTypeID3V2 type; used to determine if 535 * Frame is supported 536 * @param aPos Position in file where frame data begins 537 * @param aSize Size of the frame data 538 * @returns None 539 */ 540 void HandleID3V2FrameDataUTF8(PVID3FrameType aframeType, 541 uint32 aPos, 542 uint32 aSize); 543 544 545 /** 546 * @brief This function handls id3 frames that are not currently supported by 547 * the id3parcom library. It stores the frame alongwith the header as it is read from the file. 548 * @param aFrameType Enumerated TFrameTypeID3V2 type; It will be PV_ID3_FRAME_UNSUPPORTED 549 * @param aPos Position in file where frame data begins 550 * @param aSize Size of the frame data 551 * @returns None 552 */ 553 554 void HandleID3V2FrameUnsupported(PVID3FrameType aframeType, 555 uint32 aPos, 556 uint32 aSize); 557 558 /** 559 * @brief Detects the ID3V2FrameType and returns the enum value that 560 * corresponds to the current frame. 561 * 562 * @param None 563 * @returns Value that describes the current frame of type PVID3FrameType 564 */ 565 PVID3FrameType FrameSupportedID3V2(PVID3Version version, uint8* aframeid = NULL); 566 567 /** 568 * @brief Detects the ID3V2FrameType and fine whether it us unsupported or 569 * invalid frame type. 570 * 571 * @param None 572 * @returns Value that describes the current frame of type PVID3FrameType 573 */ 574 PVID3FrameType FrameValidatedID3V2_4(uint8* aFrameID); 575 576 /** 577 * @brief Detects the ID3V 2.2 FrameType and returns the enum value that 578 * corresponds to the current frame. 579 * 580 * @param None 581 * @returns Value that describes the current frame of type PVID3FrameType 582 */ 583 PVID3FrameType FrameSupportedID3V2_2(void); 584 585 /** 586 * @brief Converts the data in the TBuf8 buffer and puts the data into the 587 * TBuf16 buffer 588 * 589 * @param aPtrFrameData8 Pointer to intput string format of either big 590 * or little endian. 591 * @param aSize Number of character elements in aPtrFrameData8 592 * @param aEndianType Indicates if the encoded Unicode text in the 593 * aPtrFrameData8 buffer is in big or little endian. 594 * @param aPtrFrameData16 Pointer to the output string in unicode format. 595 * @returns None 596 */ 597 uint32 EightBitToWideCharBufferTransfer(const uint8* aPtrFrameData, 598 uint32 aSize, 599 uint32 aEndianType, 600 oscl_wchar* aPtrFrameData16); 601 602 603 //convert an interger to Synchsafe integer 604 uint32 ConvertToSyncSafeInt(uint32 src); 605 uint32 SafeSynchIntToInt32(uint32 SafeSynchInteger); 606 607 /** 608 * @brief Read in byte data and take most significant byte first 609 * 610 * @param aInputFile File handle to input file 611 * @param data Reference to output data buffer where the data read from file will be stored 612 * @return true if the read is successful 613 */ 614 bool readByteData(PVFile* aInputFile, uint32 length, uint8 *data); 615 616 /** 617 * @brief Read in the 32 bits byte by byte and take most significant byte first 618 * 619 * @param aInputFile File handle to input file 620 * @param data Reference to output data buffer where the data read from file will be stored 621 * @return true if the read is successful 622 */ 623 bool read32(PVFile* aInputFile, uint32 &data); 624 625 /** 626 * @brief Read in the 24 bits byte by byte and take most significant byte first 627 * 628 * @param aInputFile File handle to input file 629 * @param data Reference to output data buffer where the data read from file will be stored 630 * @return true if the read is successful 631 */ 632 bool read24(PVFile* aInputFile, uint32 &data); 633 634 /** 635 * @brief Read in 8 bytes from specified input file 636 * 637 * @param aInputFile File handle to input file 638 * @param data Reference to output data buffer where the data read from file will be stored 639 * @return true if the read is successful 640 */ 641 bool read8(PVFile* aInputFile, uint8 &data); 642 643 /** 644 * @brief Read in 16 bytes from specified input file 645 * 646 * @param aInputFile File handle to input file 647 * @param data Reference to output data buffer where the data read from file will be stored 648 * @return true if the read is successful 649 */ 650 651 bool read16(PVFile* aInputFile, uint16 &data); 652 653 /** 654 * @breif reads information stored in id3 frame 655 * @param unicode tells if the data is unicode 656 * @param frameType type of frame 657 * @param pos position in file 658 * @param currFrameLength length of the frame 659 */ 660 bool ReadFrameData(uint8 unicode, PVID3FrameType frameType, uint32 pos, uint32 currFrameLength); 661 /** 662 * @brief reads extended header if present in id3 tag header 663 * @param none 664 * @return true if success. 665 */ 666 bool ReadExtendedHeader(); 667 668 /** 669 * @brief allocate memeory for key value pair structure. 670 * @param aKey key string 671 * @param aValueType type of key value 672 * @param aValueSize size of key value 673 * @param truncate bool type indicates if the frame was truncated. 674 * @return shared pointer to key value pair structure 675 */ 676 PvmiKvpSharedPtr AllocateKvp(OSCL_String& aKey, PvmiKvpValueType aValueType, uint32 aValueSize, bool &truncate); 677 678 /** 679 * @brief forms key string for id3 frames 680 * @param aKey key string 681 * @param aType frame type 682 * @param aCharSet text encoding type (unicode, ascii) 683 * @return Completion status 684 */ 685 PVMFStatus ConstructKvpKey(OSCL_String& aKey, PVID3FrameType aType, PVID3CharacterSet aCharSet); 686 687 /** 688 * @brief reads string data in frames 689 * @param aFrameType frame type 690 * @param aCharSet text encoding 691 * @param aValueSize size of the frame data 692 * @return Completion status 693 */ 694 PVMFStatus ReadStringValueFrame(PVID3FrameType aFrameType, PVID3CharacterSet aCharSet, uint32 aValueSize); 695 696 /** 697 * @brief reads frame of type track length 698 * @param aValueSize size of the frame 699 * @param aCharSet text encoding 700 * @return completion status 701 */ 702 PVMFStatus ReadTrackLengthFrame(uint32 aValueSize, PVID3CharacterSet aCharSet); 703 704 /** 705 * @brief reads ID3 frames 706 * @param aFrameType frame type 707 * @param aValueSize size of the frame data 708 * @return Completion status 709 */ 710 711 PVMFStatus ReadFrame(PVID3FrameType aFrameType, uint32 aValueSize); 712 713 714 /** 715 * @brief This function is costructing the key-value pair for AlbumArt(apic/pic) frame. It 716 * first converts the AlbumArt frame in to the PvmfApicStruct and then set the 717 * key_specific_value of the Pvmikvp struct. 718 * @param frame type 719 * @param unicode 720 * @param frame size 721 * @return Success if read successfull. 722 */ 723 PVMFStatus ReadAlbumArtFrame(PVID3FrameType aFrameType, uint8 unicode, uint32 aFrameSize); 724 725 /** 726 * @brief This function extracts the albumart information, for ascii data, based on frametype (apic/pic). 727 * @param frame type 728 * @param frame size 729 * @param Image format 730 * @param description 731 * @param picture type 732 * @param data length 733 * @return Success if conversion is successfull. 734 */ 735 PVMFStatus GetAlbumArtInfo(PVID3FrameType aFrameType, uint32 aFrameSize, OSCL_HeapString<OsclMemAllocator> &ImageFormat, 736 uint8 &PicType, OSCL_HeapString<OsclMemAllocator> &Description, uint32 &DataLen); 737 /** 738 * @brief This function extracts the albumart information, for unicode data, based on frametype (apic/pic). 739 * @param frame type 740 * @param frame size 741 * @param Image format 742 * @param description 743 * @param picture type 744 * @param data length 745 * @return Success if conversion is successfull. 746 */ 747 PVMFStatus GetAlbumArtInfo(PVID3FrameType aFrameType, uint32 aFrameSize, OSCL_HeapString<OsclMemAllocator> &ImageFormat, 748 uint8 &PicType, OSCL_wHeapString<OsclMemAllocator> &aDescription, uint32 &DataLen); 749 750 751 752 /** 753 * @brief This function does the actual conversion from the raw ascii data from the 754 * GetAlbumArtInfo function to the PvmfApicStruct. 755 * @param MimeType 756 * @param Description 757 * @param GraphicType 758 * @param GraphicDataLen 759 * @param pointer to memory allocated to store kvp information 760 * @return Success if conversion is successfull. 761 */ 762 PVMFStatus ConvertUnicodeDataToApic(char* aMimeTypeID3, oscl_wchar* aDescriptionID3, 763 uint8 aGraphicType, uint32 aGraphicDataLen, 764 void *key_specific_value, uint32 total_size); 765 766 /** 767 * @brief This function does the actual conversion from the raw unicode data from the 768 * ConvertPictureToAPIC function to the PvmfApicStruct. 769 * @param MimeType 770 * @param Description 771 * @param GraphicType 772 * @param GraphicOffset 773 * @param GraphicDataLen 774 * @param pointer to memory allocated to store kvp information 775 * @return Success if conversion is successfull. 776 */ 777 PVMFStatus ConvertAsciiDataToApic(char* aMimeTypeID3, char* aDescriptionID3, 778 uint8 aGraphicType, uint32 aGraphicDataLen, 779 void *key_specific_value, uint32 total_size); 780 781 /** 782 * @brief Read the information from the USLT/ULT frames. 783 * @param NULL 784 * @return Success if successfully read. 785 */ 786 PVMFStatus ReadLyricsCommFrame(uint8 unicodeCheck, uint32 aFramesize, PVID3FrameType aFrameType); 787 788 789 /** 790 * @brief Reads Null terminated ascii strings from file 791 * @param aInputFile file pointer 792 * @parm data heap string to store string 793 * @return true on success otherwise false 794 */ 795 bool readNullTerminatedAsciiString(PVFile* aInputFile, OSCL_HeapString<OsclMemAllocator> &data); 796 797 /** 798 * @brief Reads Null terminated unicode strings from file 799 * @param aInputFile file pointer 800 * @parm data heap string to store string 801 * @return completion status 802 */ 803 804 PVMFStatus readNullTerminatedUnicodeString(PVFile* aInputFile, OSCL_wHeapString<OsclMemAllocator> &aData, uint32 &bomSz); 805 806 /** 807 * @brief reads frame of type comment 808 * @param aValueSize size of the frame 809 * @return completion status 810 */ 811 812 PVMFStatus ReadCommentFrame(uint32 aValueSize); 813 814 /** 815 * @brief Gets value type and char set stored in kvp 816 * @param aKvp shared pointer to kvp 817 * @param aValueType value type 818 * @param aCharSet char set 819 * @return Completion status. 820 */ 821 PVMFStatus GetKvpValueType(PvmiKvpSharedPtr aKvp, PvmiKvpValueType& aValueType, PVID3CharacterSet& aCharSet); 822 823 /** 824 * @brief Gets frame ID and frame type from kvp 825 * @param aKvp shared pointer to key value pair structure 826 * @param aFrameID frame ID 827 * @param aFrameType frame type 828 * @return Completion status. 829 */ 830 PVMFStatus GetFrameTypeFromKvp(PvmiKvpSharedPtr aKvp, OSCL_String& aFrameID, PVID3FrameType& aFrameType); 831 832 /** 833 * @brief Gets frame ID and frame type from kvp 834 * @param aKvp key value pair structure 835 * @param aFrameID frame ID 836 * @param aFrameType frame type 837 * @return Completion status. 838 */ 839 PVMFStatus GetFrameTypeFromKvp(const PvmiKvp& aKvp, OSCL_String& aFrameID, PVID3FrameType& aFrameType); 840 841 /** 842 * @brief Get Size of ID3 frame stored in kvp. 843 * @param akvp shared pointer to kvp 844 * @param aValueType type of value stored in kvp 845 * @param aCharSet character set of value 846 * @param aSize size of the frame 847 * @return Completion Status 848 */ 849 PVMFStatus GetID3v2FrameDataSize(PvmiKvpSharedPtr aKvp, PvmiKvpValueType aValueType, 850 PVID3CharacterSet aCharSet, uint32& aSize); 851 852 /** 853 * @brief compose ID3 V2 tag 854 * @param aTag reference counter to memory fragment 855 * @return Completion Status 856 */ 857 PVMFStatus ComposeID3v2Tag(OsclRefCounterMemFrag& aTag); 858 859 /** 860 * @brief push frame to supplied frame vector 861 * @param aFrame Frame to be pushed 862 * @param aFrameVector vector in which frame is to be pushed 863 * @return Completion Status 864 */ 865 PVMFStatus PushFrameToFrameVector(PvmiKvpSharedPtr& aFrame, PvmiKvpSharedPtrVector& aFrameVector); 866 /** 867 * @brief Allocate array of specified size and type of elements 868 * @param aValueType, type of array elements 869 * @param aNumElements, size of required array 870 * @return aLeaveCode, err code 871 * @return buffer, pointer to allocated buffer 872 */ 873 OsclAny* AllocateValueArray(int32& aLeaveCode, PvmiKvpValueType aValueType, int32 aNumElements, OsclMemAllocator* aMemAllocator = NULL); 874 875 /** 876 * @brief Allocate kvp and handle leave 877 * @param aValueType, type of array elements 878 * @param aValueSize, value size of required kvp 879 * @return aStatus, err code 880 * @return truncate, returns false if specified memory is not allocated, else true 881 */ 882 PvmiKvpSharedPtr HandleErrorForKVPAllocation(OSCL_String& aKey, PvmiKvpValueType aValueType, uint32 aValueSize, bool &truncate, PVMFStatus &aStatus); 883 884 private: 885 886 // Variables for parsing 887 PVFile* iInputFile; 888 TID3TagInfo iID3TagInfo; 889 bool iTitleFoundFlag; 890 bool iArtistFoundFlag; 891 bool iAlbumFoundFlag; 892 bool iYearFoundFlag; 893 bool iCommentFoundFlag; 894 bool iTrackNumberFoundFlag; 895 bool iGenereFoundFlag; 896 int32 iFileSizeInBytes; 897 uint32 iByteOffsetToStartOfAudioFrames; 898 899 bool iID3V1Present; 900 bool iID3V2Present; 901 // Variables for composing 902 PVID3Version iVersion; 903 PvmiKvpSharedPtrVector iFrames; 904 bool iUseMaxTagSize; 905 uint32 iMaxTagSize; 906 bool iUsePadding; 907 bool iTagAtBof; 908 bool iSeekFrameFound; 909 910 OsclMemAllocator iAlloc; 911 PVLogger* iLogger; 912 }; 913 914 #endif // PV_ID3_PARCOM_H_INCLUDED 915 916 917
