1 /* 2 2002, 2003, 2004, 2005, 2006 Bastien Nocera 3 Copyright (C) 2003 Colin Walters <walters@verbum.org> 4 5 The Gnome Library is free software; you can redistribute it and/or 6 modify it under the terms of the GNU Library General Public License as 7 published by the Free Software Foundation; either version 2 of the 8 License, or (at your option) any later version. 9 10 The Gnome Library is distributed in the hope that it will be useful, 11 but WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 Library General Public License for more details. 14 15 You should have received a copy of the GNU Library General Public 16 License along with the Gnome Library; see the file COPYING.LIB. If not, 17 write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 18 Boston, MA 02110-1301 USA. 19 20 Author: Bastien Nocera <hadess@hadess.net> 21 */ 22 23 #ifndef TOTEM_PL_PARSER_H 24 #define TOTEM_PL_PARSER_H 25 26 #include <glib.h> 27 #include <gio/gio.h> 28 29 #include "totem-pl-parser-features.h" 30 #include "totem-pl-parser-builtins.h" 31 #include "totem-pl-playlist.h" 32 33 G_BEGIN_DECLS 34 35 #define TOTEM_TYPE_PL_PARSER (totem_pl_parser_get_type ()) 36 #define TOTEM_PL_PARSER(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), TOTEM_TYPE_PL_PARSER, TotemPlParser)) 37 #define TOTEM_PL_PARSER_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), TOTEM_TYPE_PL_PARSER, TotemPlParserClass)) 38 #define TOTEM_PL_IS_PARSER(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), TOTEM_TYPE_PL_PARSER)) 39 #define TOTEM_PL_IS_PARSER_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), TOTEM_TYPE_PL_PARSER)) 40 41 /** 42 * TotemPlParserResult: 43 * @TOTEM_PL_PARSER_RESULT_UNHANDLED: The playlist could not be handled. 44 * @TOTEM_PL_PARSER_RESULT_ERROR: There was an error parsing the playlist. 45 * @TOTEM_PL_PARSER_RESULT_SUCCESS: The playlist was parsed successfully. 46 * @TOTEM_PL_PARSER_RESULT_IGNORED: The playlist was ignored due to its scheme or MIME type (see totem_pl_parser_add_ignored_scheme() 47 * and totem_pl_parser_add_ignored_mimetype()). 48 * @TOTEM_PL_PARSER_RESULT_CANCELLED: Parsing of the playlist was cancelled part-way through. 49 * 50 * Gives the result of parsing a playlist. 51 **/ 52 typedef enum { 53 TOTEM_PL_PARSER_RESULT_UNHANDLED, 54 TOTEM_PL_PARSER_RESULT_ERROR, 55 TOTEM_PL_PARSER_RESULT_SUCCESS, 56 TOTEM_PL_PARSER_RESULT_IGNORED, 57 TOTEM_PL_PARSER_RESULT_CANCELLED 58 } TotemPlParserResult; 59 60 typedef struct TotemPlParserPrivate TotemPlParserPrivate; 61 62 /** 63 * TotemPlParser: 64 * 65 * All the fields in the #TotemPlParser structure are private and should never be accessed directly. 66 **/ 67 typedef struct { 68 GObject parent; 69 TotemPlParserPrivate *priv; 70 } TotemPlParser; 71 72 G_DEFINE_AUTOPTR_CLEANUP_FUNC(TotemPlParser, g_object_unref) 73 74 /* Known metadata fields */ 75 76 /** 77 * TOTEM_PL_PARSER_FIELD_URI: 78 * 79 * Metadata field for an entry's URI. 80 * 81 * Since: 2.26 82 **/ 83 #define TOTEM_PL_PARSER_FIELD_URI "url" 84 /** 85 * TOTEM_PL_PARSER_FIELD_GENRE: 86 * 87 * Metadata field for an entry's genre. 88 **/ 89 #define TOTEM_PL_PARSER_FIELD_GENRE "genre" 90 /** 91 * TOTEM_PL_PARSER_FIELD_TITLE: 92 * 93 * Metadata field for an entry's displayable title. 94 **/ 95 #define TOTEM_PL_PARSER_FIELD_TITLE "title" 96 /** 97 * TOTEM_PL_PARSER_FIELD_AUTHOR: 98 * 99 * Metadata field for an entry's author/composer/director. 100 **/ 101 #define TOTEM_PL_PARSER_FIELD_AUTHOR "author" 102 /** 103 * TOTEM_PL_PARSER_FIELD_ALBUM: 104 * 105 * Metadata field for an entry's album. 106 **/ 107 #define TOTEM_PL_PARSER_FIELD_ALBUM "album" 108 /** 109 * TOTEM_PL_PARSER_FIELD_BASE: 110 * 111 * Metadata field for an entry's base path. 112 **/ 113 #define TOTEM_PL_PARSER_FIELD_BASE "base" 114 /** 115 * TOTEM_PL_PARSER_FIELD_SUBTITLE_URI: 116 * 117 * The URI of the entry's subtitle file. 118 **/ 119 #define TOTEM_PL_PARSER_FIELD_SUBTITLE_URI "subtitle-uri" 120 /** 121 * TOTEM_PL_PARSER_FIELD_VOLUME: 122 * 123 * Metadata field for an entry's playback volume. 124 **/ 125 #define TOTEM_PL_PARSER_FIELD_VOLUME "volume" 126 /** 127 * TOTEM_PL_PARSER_FIELD_AUTOPLAY: 128 * 129 * Metadata field for an entry's "autoplay" flag, which is %TRUE if the entry should play automatically. 130 **/ 131 #define TOTEM_PL_PARSER_FIELD_AUTOPLAY "autoplay" 132 /** 133 * TOTEM_PL_PARSER_FIELD_DURATION: 134 * 135 * Metadata field for an entry's playback duration, which should be parsed using totem_pl_parser_parse_duration(). 136 **/ 137 #define TOTEM_PL_PARSER_FIELD_DURATION "duration" 138 /** 139 * TOTEM_PL_PARSER_FIELD_DURATION_MS: 140 * 141 * Metadata field for an entry's playback duration, in milliseconds. It's only used when an entry's 142 * duration is available in that format, so one would get either the %TOTEM_PL_PARSER_FIELD_DURATION 143 * or %TOTEM_PL_PARSER_FIELD_DURATION_MS as metadata. 144 **/ 145 #define TOTEM_PL_PARSER_FIELD_DURATION_MS "duration-ms" 146 /** 147 * TOTEM_PL_PARSER_FIELD_STARTTIME: 148 * 149 * Metadata field for an entry's playback start time, which should be parsed using totem_pl_parser_parse_duration(). 150 **/ 151 #define TOTEM_PL_PARSER_FIELD_STARTTIME "starttime" 152 /** 153 * TOTEM_PL_PARSER_FIELD_ENDTIME: 154 * 155 * Metadata field for an entry's playback end time. 156 **/ 157 #define TOTEM_PL_PARSER_FIELD_ENDTIME "endtime" 158 /** 159 * TOTEM_PL_PARSER_FIELD_COPYRIGHT: 160 * 161 * Metadata field for an entry's copyright line. 162 **/ 163 #define TOTEM_PL_PARSER_FIELD_COPYRIGHT "copyright" 164 /** 165 * TOTEM_PL_PARSER_FIELD_ABSTRACT: 166 * 167 * Metadata field for an entry's abstract text. 168 **/ 169 #define TOTEM_PL_PARSER_FIELD_ABSTRACT "abstract" 170 /** 171 * TOTEM_PL_PARSER_FIELD_DESCRIPTION: 172 * 173 * Metadata field for an entry's description. 174 **/ 175 #define TOTEM_PL_PARSER_FIELD_DESCRIPTION "description" 176 /** 177 * TOTEM_PL_PARSER_FIELD_SUMMARY: 178 * 179 * Metadata field for an entry's summary. (In practice, identical to %TOTEM_PL_PARSER_FIELD_DESCRIPTION.) 180 **/ 181 #define TOTEM_PL_PARSER_FIELD_SUMMARY TOTEM_PL_PARSER_FIELD_DESCRIPTION 182 /** 183 * TOTEM_PL_PARSER_FIELD_MOREINFO: 184 * 185 * Metadata field for an entry's "more info" URI. 186 **/ 187 #define TOTEM_PL_PARSER_FIELD_MOREINFO "moreinfo" 188 /** 189 * TOTEM_PL_PARSER_FIELD_SCREENSIZE: 190 * 191 * Metadata field for an entry's preferred screen size. 192 **/ 193 #define TOTEM_PL_PARSER_FIELD_SCREENSIZE "screensize" 194 /** 195 * TOTEM_PL_PARSER_FIELD_UI_MODE: 196 * 197 * Metadata field for an entry's preferred UI mode. 198 **/ 199 #define TOTEM_PL_PARSER_FIELD_UI_MODE "ui-mode" 200 /** 201 * TOTEM_PL_PARSER_FIELD_PUB_DATE: 202 * 203 * Metadata field for an entry's publication date, which should be parsed using totem_pl_parser_parse_date(). 204 **/ 205 #define TOTEM_PL_PARSER_FIELD_PUB_DATE "publication-date" 206 /** 207 * TOTEM_PL_PARSER_FIELD_FILESIZE: 208 * 209 * Metadata field for an entry's filesize in bytes. This is only advisory, and can sometimes not match the actual filesize of the stream. 210 **/ 211 #define TOTEM_PL_PARSER_FIELD_FILESIZE "filesize" 212 /** 213 * TOTEM_PL_PARSER_FIELD_LANGUAGE: 214 * 215 * Metadata field for an entry's audio language. 216 **/ 217 #define TOTEM_PL_PARSER_FIELD_LANGUAGE "language" 218 /** 219 * TOTEM_PL_PARSER_FIELD_CONTACT: 220 * 221 * Metadata field for an entry's contact details for the webmaster. 222 **/ 223 #define TOTEM_PL_PARSER_FIELD_CONTACT "contact" 224 /** 225 * TOTEM_PL_PARSER_FIELD_IMAGE_URI: 226 * 227 * Metadata field for an entry's thumbnail image URI. 228 * 229 * Since: 2.26 230 **/ 231 #define TOTEM_PL_PARSER_FIELD_IMAGE_URI "image-url" 232 /** 233 * TOTEM_PL_PARSER_FIELD_DOWNLOAD_URI: 234 * 235 * Metadata field for an entry's download URI. Only used if an alternate download 236 * location is available for the entry. 237 * 238 * Since: 2.26 239 **/ 240 #define TOTEM_PL_PARSER_FIELD_DOWNLOAD_URI "download-url" 241 /** 242 * TOTEM_PL_PARSER_FIELD_ID: 243 * 244 * Metadata field for an entry's identifier. Its use is dependent on the format 245 * of the playlist parsed, and its origin. 246 **/ 247 #define TOTEM_PL_PARSER_FIELD_ID "id" 248 /** 249 * TOTEM_PL_PARSER_FIELD_IS_PLAYLIST: 250 * 251 * Metadata field used to tell the calling code that the parsing of a playlist 252 * started. It is only %TRUE for the metadata passed to #TotemPlParser::playlist-started or 253 * #TotemPlParser::playlist-ended signal handlers. 254 **/ 255 #define TOTEM_PL_PARSER_FIELD_IS_PLAYLIST "is-playlist" 256 /** 257 * TOTEM_PL_PARSER_FIELD_CONTENT_TYPE: 258 * 259 * Metadata field for an entry's content-type (usually a mime-type coming 260 * from a web server). 261 **/ 262 #define TOTEM_PL_PARSER_FIELD_CONTENT_TYPE "content-type" 263 /** 264 * TOTEM_PL_PARSER_FIELD_PLAYING: 265 * 266 * Metadata field for an entry's status in a playlist. This is usually 267 * used when saving the state of an on-going playlist. 268 **/ 269 #define TOTEM_PL_PARSER_FIELD_PLAYING "playing" 270 /** 271 * TOTEM_PL_PARSER_FIELD_AUDIO_TRACK: 272 * 273 * Metadata field for an entry's default audio-track selection. The default 274 * track is defined as NULL. Note that the value is sent as a string. 275 **/ 276 #define TOTEM_PL_PARSER_FIELD_AUDIO_TRACK "audio-track" 277 278 /** 279 * TotemPlParserClass: 280 * @parent_class: the parent class 281 * @entry_parsed: the generic signal handler for the #TotemPlParser::entry-parsed signal, 282 * which can be overridden by inheriting classes 283 * @playlist_started: the generic signal handler for the #TotemPlParser::playlist-started signal, 284 * which can be overridden by inheriting classes 285 * @playlist_ended: the generic signal handler for the #TotemPlParser::playlist-ended signal, 286 * which can be overridden by inheriting classes 287 * 288 * The class structure for the #TotemPlParser type. 289 **/ 290 typedef struct { 291 GObjectClass parent_class; 292 293 /* signals */ 294 void (*entry_parsed) (TotemPlParser *parser, 295 const char *uri, 296 GHashTable *metadata); 297 void (*playlist_started) (TotemPlParser *parser, 298 const char *uri, 299 GHashTable *metadata); 300 void (*playlist_ended) (TotemPlParser *parser, 301 const char *uri); 302 } TotemPlParserClass; 303 304 /** 305 * TotemPlParserType: 306 * @TOTEM_PL_PARSER_PLS: PLS parser 307 * @TOTEM_PL_PARSER_M3U: M3U parser 308 * @TOTEM_PL_PARSER_M3U_DOS: M3U (DOS linebreaks) parser 309 * @TOTEM_PL_PARSER_XSPF: XSPF parser 310 * @TOTEM_PL_PARSER_IRIVER_PLA: iRiver PLA parser 311 * 312 * The type of playlist a #TotemPlParser will parse. 313 **/ 314 typedef enum { 315 TOTEM_PL_PARSER_PLS, 316 TOTEM_PL_PARSER_M3U, 317 TOTEM_PL_PARSER_M3U_DOS, 318 TOTEM_PL_PARSER_XSPF, 319 TOTEM_PL_PARSER_IRIVER_PLA, 320 } TotemPlParserType; 321 322 /** 323 * TotemPlParserError: 324 * @TOTEM_PL_PARSER_ERROR_NO_DISC: Error attempting to open a disc device when no disc is present 325 * @TOTEM_PL_PARSER_ERROR_MOUNT_FAILED: An attempted mount operation failed 326 * @TOTEM_PL_PARSER_ERROR_EMPTY_PLAYLIST: Playlist to be saved is empty 327 * 328 * Allows you to differentiate between different 329 * errors occurring during file operations in a #TotemPlParser. 330 **/ 331 typedef enum { 332 TOTEM_PL_PARSER_ERROR_NO_DISC, 333 TOTEM_PL_PARSER_ERROR_MOUNT_FAILED, 334 TOTEM_PL_PARSER_ERROR_EMPTY_PLAYLIST 335 } TotemPlParserError; 336 337 #define TOTEM_PL_PARSER_ERROR (totem_pl_parser_error_quark ()) 338 339 GQuark totem_pl_parser_error_quark (void); 340 341 GType totem_pl_parser_get_type (void); 342 343 gint64 totem_pl_parser_parse_duration (const char *duration, gboolean debug); 344 guint64 totem_pl_parser_parse_date (const char *date_str, gboolean debug); 345 346 gboolean totem_pl_parser_save (TotemPlParser *parser, 347 TotemPlPlaylist *playlist, 348 GFile *dest, 349 const gchar *title, 350 TotemPlParserType type, 351 GError **error); 352 void totem_pl_parser_save_async (TotemPlParser *parser, 353 TotemPlPlaylist *playlist, 354 GFile *dest, 355 const gchar *title, 356 TotemPlParserType type, 357 GCancellable *cancellable, 358 GAsyncReadyCallback callback, 359 gpointer user_data); 360 gboolean totem_pl_parser_save_finish (TotemPlParser *parser, 361 GAsyncResult *result, 362 GError **error); 363 364 void totem_pl_parser_add_ignored_scheme (TotemPlParser *parser, 365 const char *scheme); 366 void totem_pl_parser_add_ignored_mimetype (TotemPlParser *parser, 367 const char *mimetype); 368 void totem_pl_parser_add_ignored_glob (TotemPlParser *parser, 369 const char *glob); 370 371 TotemPlParserResult totem_pl_parser_parse (TotemPlParser *parser, 372 const char *uri, gboolean fallback); 373 void totem_pl_parser_parse_async (TotemPlParser *parser, const char *uri, 374 gboolean fallback, GCancellable *cancellable, 375 GAsyncReadyCallback callback, 376 gpointer user_data); 377 TotemPlParserResult totem_pl_parser_parse_finish (TotemPlParser *parser, 378 GAsyncResult *async_result, 379 GError **error); 380 381 TotemPlParserResult totem_pl_parser_parse_with_base (TotemPlParser *parser, 382 const char *uri, 383 const char *base, 384 gboolean fallback); 385 void totem_pl_parser_parse_with_base_async (TotemPlParser *parser, 386 const char *uri, const char *base, 387 gboolean fallback, 388 GCancellable *cancellable, 389 GAsyncReadyCallback callback, 390 gpointer user_data); 391 392 TotemPlParser *totem_pl_parser_new (void); 393 394 /** 395 * TotemPlParserMetadata: (skip) 396 * 397 * An alias for #GHashTable, used in the #TotemPlParser::entry-parsed and 398 * #TotemPlParser::playlist-started signals due to #GHashTable not being a 399 * boxed type when totem-pl-parser was originally written. 400 * 401 * The hash table is a mapping from field names (such as 402 * %TOTEM_PL_PARSER_FIELD_ALBUM) to their associated values. 403 * 404 * It is safe to use #GHashTable instead of #TotemPlParserMetadata everywhere. 405 */ 406 typedef GHashTable TotemPlParserMetadata; 407 408 GType totem_pl_parser_metadata_get_type (void) G_GNUC_CONST; 409 #define TOTEM_TYPE_PL_PARSER_METADATA (totem_pl_parser_metadata_get_type()) 410 411 G_DEFINE_AUTOPTR_CLEANUP_FUNC(TotemPlParserMetadata, g_hash_table_destroy) 412 413 G_END_DECLS 414 415 #endif /* TOTEM_PL_PARSER_H */ 416