1 /* 2 * libxspf - XSPF playlist handling library 3 * 4 * Copyright (C) 2006-2008, Sebastian Pipping / Xiph.Org Foundation 5 * All rights reserved. 6 * 7 * Redistribution and use in source and binary forms, with or without 8 * modification, are permitted provided that the following conditions 9 * are met: 10 * 11 * * Redistributions of source code must retain the above 12 * copyright notice, this list of conditions and the following 13 * disclaimer. 14 * 15 * * Redistributions in binary form must reproduce the above 16 * copyright notice, this list of conditions and the following 17 * disclaimer in the documentation and/or other materials 18 * provided with the distribution. 19 * 20 * * Neither the name of the Xiph.Org Foundation nor the names of 21 * its contributors may be used to endorse or promote products 22 * derived from this software without specific prior written 23 * permission. 24 * 25 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 26 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 27 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 28 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 29 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 30 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 31 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 32 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 33 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 34 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 35 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 36 * OF THE POSSIBILITY OF SUCH DAMAGE. 37 * 38 * Sebastian Pipping, sping@xiph.org 39 */ 40 41 /** 42 * @file XspfData.h 43 * Interface of XspfData. 44 */ 45 46 #ifndef XSPF_DATA_H 47 #define XSPF_DATA_H 48 49 #include "XspfDefines.h" 50 #include <deque> 51 52 namespace Xspf { 53 54 55 class XspfExtension; 56 class XspfDataPrivate; 57 58 59 /** 60 * Provides shared functionality for XspfTrack and XspfProps. 61 */ 62 class XspfData { 63 64 friend class XspfDataPrivate; 65 66 private: 67 /// @cond DOXYGEN_NON_API 68 XspfDataPrivate * const d; ///< D pointer 69 /// @endcond 70 71 protected: 72 /** 73 * Creates a new XspfData object. 74 */ 75 XspfData(); 76 77 /** 78 * Copy constructor. 79 * 80 * @param source Source to copy from 81 */ 82 XspfData(XspfData const & source); 83 84 /** 85 * Assignment operator. 86 * 87 * @param source Source to copy from 88 */ 89 XspfData & operator=(XspfData const & source); 90 91 /** 92 * Destroys this XspfData object and deletes all 93 * memory associated with it that has not been stolen before. 94 */ 95 virtual ~XspfData(); 96 97 public: 98 /** 99 * Overwrites the image property. If <c>copy</c> is true 100 * the string will be copied, otherwise just assigned. 101 * In both cases the associated memory will be deleted on 102 * object destruction. 103 * 104 * @param image Image string to set 105 * @param copy Copy flag 106 */ 107 void giveImage(XML_Char const * image, bool copy); 108 109 /** 110 * Overwrites the info property. If <c>copy</c> is true 111 * the string will be copied, otherwise just assigned. 112 * In both cases the associated memory will be deleted on 113 * object destruction. 114 * 115 * @param info Info string to set 116 * @param copy Copy flag 117 */ 118 void giveInfo(XML_Char const * info, bool copy); 119 120 /** 121 * Overwrites the annotation property. If <c>copy</c> is true 122 * the string will be copied, otherwise just assigned. 123 * In both cases the associated memory will be deleted on 124 * object destruction. 125 * 126 * @param annotation Annotation string to set 127 * @param copy Copy flag 128 */ 129 void giveAnnotation(XML_Char const * annotation, bool copy); 130 131 /** 132 * Overwrites the creator property. If <c>copy</c> is true 133 * the string will be copied, otherwise just assigned. 134 * In both cases the associated memory will be deleted on 135 * object destruction. 136 * 137 * @param creator Creator string to set 138 * @param copy Copy flag 139 */ 140 void giveCreator(XML_Char const * creator, bool copy); 141 142 /** 143 * Overwrites the title property. If <c>copy</c> is true 144 * the string will be copied, otherwise just assigned. 145 * In both cases the associated memory will be deleted on 146 * object destruction. 147 * 148 * @param title Title string to set 149 * @param copy Copy flag 150 */ 151 void giveTitle(XML_Char const * title, bool copy); 152 153 /** 154 * Appends a link to the link list. 155 * 156 * @param rel Link rel to append 157 * @param copyRel Rel copy flag 158 * @param content Link content to append 159 * @param copyContent Content copy flag 160 */ 161 void giveAppendLink(XML_Char const * rel, bool copyRel, XML_Char const * content, bool copyContent); 162 163 /** 164 * Appends a meta to the meta list. 165 * 166 * @param rel Meta rel to append 167 * @param copyRel Rel copy flag 168 * @param content Meta content to append 169 * @param copyContent Content copy flag 170 */ 171 void giveAppendMeta(XML_Char const * rel, bool copyRel, XML_Char const * content, bool copyContent); 172 173 /** 174 * Appends an extension to the extension list. 175 * 176 * @param extension Extension to append 177 * @param copy Copy flag 178 */ 179 void giveAppendExtension(XspfExtension const * extension, bool copy); 180 181 /** 182 * Overwrites the image property. The string is 183 * only assigned not copied. The ownership is 184 * not transferred. 185 * 186 * @param image Image string to set 187 */ 188 void lendImage(XML_Char const * image); 189 190 /** 191 * Overwrites the info property. The string is 192 * only assigned not copied. The ownership is 193 * not transferred. 194 * 195 * @param info Info string to set 196 */ 197 void lendInfo(XML_Char const * info); 198 199 /** 200 * Overwrites the annotation property. The string is 201 * only assigned not copied. The ownership is 202 * not transferred. 203 * 204 * @param annotation Annotation string to set 205 */ 206 void lendAnnotation(XML_Char const * annotation); 207 208 /** 209 * Overwrites the creator property. The string is 210 * only assigned not copied. The ownership is 211 * not transferred. 212 * 213 * @param creator Creator string to set 214 */ 215 void lendCreator(XML_Char const * creator); 216 217 /** 218 * Overwrites the title property. The string is 219 * only assigned not copied. The ownership is 220 * not transferred. 221 * 222 * @param title Title string to set 223 */ 224 void lendTitle(XML_Char const * title); 225 226 /** 227 * Appends a link pair to the link list. 228 * The associated memory is neither copied nor 229 * deleted on onject destruction. 230 * 231 * @param rel Link rel to append 232 * @param content Link content to append 233 */ 234 void lendAppendLink(XML_Char const * rel, XML_Char const * content); 235 236 /** 237 * Appends a meta pair to the meta list. 238 * The associated memory is neither copied nor 239 * deleted on onject destruction. 240 * 241 * @param rel Meta rel to append 242 * @param content Meta content to append 243 */ 244 void lendAppendMeta(XML_Char const * rel, XML_Char const * content); 245 246 /** 247 * Appends an extension to the extension list. 248 * The associated memory is neither copied nor 249 * deleted on onject destruction. 250 * 251 * @param extension Extension to append 252 */ 253 void lendAppendExtension(XspfExtension * extension); 254 255 /** 256 * Steals the image property. 257 * 258 * @return Image URI, can be NULL 259 */ 260 XML_Char * stealImage(); 261 262 /** 263 * Steals the info property. 264 * 265 * @return Info URI, can be NULL 266 */ 267 XML_Char * stealInfo(); 268 269 /** 270 * Steals the annotation property. 271 * 272 * @return Annotation, can be NULL 273 */ 274 XML_Char * stealAnnotation(); 275 276 /** 277 * Steals the creator property. 278 * 279 * @return Creator, can be NULL 280 */ 281 XML_Char * stealCreator(); 282 283 /** 284 * Steals the title property. 285 * 286 * @return Title, can be NULL 287 */ 288 XML_Char * stealTitle(); 289 290 /** 291 * Steals the first link pair from the list. 292 * If the list is empty <c>NULL</c> is returned. 293 * 294 * NOTE: Do not forget to delete the pair! 295 * 296 * @return First link pair, can be NULL 297 */ 298 std::pair<XML_Char *, XML_Char *> * stealFirstLink(); 299 300 /** 301 * Steals the first meta pair from the list. 302 * If the list is empty <c>NULL</c> is returned. 303 * 304 * NOTE: Do not forget to delete the pair! 305 * 306 * @return First meta pair, can be NULL 307 */ 308 std::pair<XML_Char *, XML_Char *> * stealFirstMeta(); 309 310 /** 311 * Steals the extension from the list. 312 * If the list is empty <c>NULL</c> is returned. 313 * 314 * NOTE: Do not forget to delete the extension! 315 * 316 * @return First extension, can be NULL 317 */ 318 XspfExtension * stealFirstExtension(); 319 320 /** 321 * Returns the image property. 322 * 323 * @return Image URI, can be NULL 324 */ 325 XML_Char const * getImage() const; 326 327 /** 328 * Returns the info property. 329 * 330 * @return Info URI, can be NULL 331 */ 332 XML_Char const * getInfo() const; 333 334 /** 335 * Returns the annotation property. 336 * 337 * @return Annotation, can be NULL 338 */ 339 XML_Char const * getAnnotation() const; 340 341 /** 342 * Returns the creator property. 343 * 344 * @return Creator, can be NULL 345 */ 346 XML_Char const * getCreator() const; 347 348 /** 349 * Returns the title property. 350 * 351 * @return Title, can be NULL 352 */ 353 XML_Char const * getTitle() const; 354 355 /** 356 * Gets a specific link pair from the list. 357 * If the list is empty <c>NULL</c> is returned. 358 * 359 * NOTE: The returned pair has to be deleted manually! 360 * 361 * @return Specified link pair, can be NULL 362 */ 363 std::pair<XML_Char const *, XML_Char const *> * getLink(int index) const; 364 365 /** 366 * Gets a specific meta pair from the list. 367 * If the list is empty <c>NULL</c> is returned. 368 * 369 * NOTE: The returned pair has to be deleted manually! 370 * 371 * @return Specified meta pair, can be NULL 372 */ 373 std::pair<XML_Char const *, XML_Char const *> * getMeta(int index) const; 374 375 /** 376 * Gets a specific extension from the list. 377 * If the list is empty <c>NULL</c> is returned. 378 * 379 * NOTE: The returned extension has to be deleted manually! 380 * 381 * @return Specified extension, can be NULL 382 */ 383 XspfExtension const * getExtension(int index) const; 384 385 /** 386 * Returns the number of link pairs. 387 * 388 * @return Number of link pairs 389 */ 390 int getLinkCount() const; 391 392 /** 393 * Returns the number of meta pairs. 394 * 395 * @return Number of meta pairs 396 */ 397 int getMetaCount() const; 398 399 /** 400 * Returns the number of extensions. 401 * 402 * @return Number of extensions 403 */ 404 int getExtensionCount() const; 405 406 private: 407 /** 408 * Appends a meta or link pair to a container. 409 * 410 * @param container Container to work with 411 * @param rel Rel to append 412 * @param ownRel Rel ownership flag 413 * @param content Content to append 414 * @param ownContent Content ownership flag 415 */ 416 static void appendHelper(std::deque<std::pair< 417 std::pair<XML_Char const *, bool> *, 418 std::pair<XML_Char const *, bool> *> *> * & container, 419 XML_Char const * rel, 420 bool ownRel, 421 XML_Char const * content, 422 bool ownContent); 423 424 /** 425 * Appends an extension to a container. 426 * 427 * @param container Container to work with 428 * @param extenstion Extenstion to append 429 * @param own Ownership flag 430 */ 431 static void appendHelper(std::deque< 432 std::pair<XspfExtension const *, bool> *> * & container, 433 XspfExtension const * extenstion, 434 bool own); 435 436 protected: 437 /** 438 * Steals a property. If the property's memory is not owned 439 * a clone is returned. In any case you own the memory 440 * return and have to delete it. 441 * 442 * @param property Property to steal 443 * @param own Owner flag 444 * @return Stolen property value, can be NULL 445 */ 446 static XML_Char * stealHelper(XML_Char const * & property, bool own); 447 448 private: 449 /** 450 * Steals the first entry from a container. 451 * 452 * @param container Container to steal from 453 * @return First entry, can be NULL 454 */ 455 static std::pair<XML_Char *, XML_Char *> * stealFirstHelper( 456 std::deque<std::pair<std::pair<XML_Char const *, bool> *, 457 std::pair<XML_Char const *, bool> *> *> * & container); 458 459 /** 460 * Steals the first entry from a container. 461 * 462 * @param container Container to steal from 463 * @return First entry, can be NULL 464 */ 465 static XspfExtension * stealFirstHelper(std::deque< 466 std::pair<XspfExtension const *, bool> *> * & container); 467 468 /** 469 * Returns a specific entry from a container 470 * or <c>NULL</c> if the entry does not exist. 471 * 472 * NOTE: The returned pair has to be deleted manually! 473 * 474 * @param container Container to work with 475 * @param index Index of the entry to return 476 * @return Entry content, can be NULL 477 */ 478 static std::pair<XML_Char const *, XML_Char const *> * getHelper( 479 std::deque<std::pair<std::pair<XML_Char const *, bool> *, 480 std::pair<XML_Char const *, bool> *> *> * & container, 481 int index); 482 483 /** 484 * Returns a specific entry from a container 485 * or <c>NULL</c> if the entry does not exist. 486 * 487 * NOTE: The returned pair has to be deleted manually! 488 * 489 * @param container Container to work with 490 * @param index Index of the entry to return 491 * @return Entry content, can be NULL 492 */ 493 static XspfExtension const * getHelper( 494 std::deque<std::pair<XspfExtension const *, bool> *> * & container, 495 int index); 496 497 protected: 498 /// @cond DOXYGEN_NON_API 499 void virtualHook(int methodId, void * parameters); 500 /// @endcond 501 502 public: 503 static bool const COPY; ///< Memory is copied 504 static bool const TRANSFER; ///< Memory ownership is transfered 505 506 }; 507 508 509 } 510 511 #endif // XSPF_DATA_H 512