1 /* 2 * Copyright (C) 2000-2019 the xine project 3 * 4 * This file is part of xine, a free video player. 5 * 6 * xine is free software; you can redistribute it and/or modify 7 * it under the terms of the GNU General Public License as published by 8 * the Free Software Foundation; either version 2 of the License, or 9 * (at your option) any later version. 10 * 11 * xine is distributed in the hope that it will be useful, 12 * but WITHOUT ANY WARRANTY; without even the implied warranty of 13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 * GNU General Public License for more details. 15 * 16 * You should have received a copy of the GNU General Public License 17 * along with this program; if not, write to the Free Software 18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110, USA 19 */ 20 21 #ifndef HAVE_INPUT_PLUGIN_H 22 #define HAVE_INPUT_PLUGIN_H 23 24 #include <sys/types.h> /* off_t */ 25 26 #include <xine/attributes.h> 27 #include <xine/os_types.h> 28 #include <xine/xineutils.h> 29 #include <xine/buffer.h> 30 31 struct plugin_node_s; 32 33 #define INPUT_PLUGIN_IFACE_VERSION 18 34 35 typedef struct input_class_s input_class_t ; 36 typedef struct input_plugin_s input_plugin_t; 37 38 struct input_class_s { 39 40 /* 41 * create a new instance of this plugin class 42 * return NULL if the plugin does'nt handle the given mrl 43 */ 44 input_plugin_t* (*get_instance) (input_class_t *this_gen, xine_stream_t *stream, const char *mrl); 45 46 /** 47 * @brief short human readable identifier for this plugin class 48 */ 49 const char *identifier; 50 51 /** 52 * @brief human readable (verbose = 1 line) description for this plugin class 53 * 54 * The description is passed to gettext() to internationalise. 55 */ 56 const char *description; 57 58 /** 59 * @brief Optional non-standard catalog to use with dgettext() for description. 60 */ 61 const char *text_domain; 62 63 /* 64 * ls function, optional: may be NULL 65 * return value: NULL => filename is a file, **char=> filename is a dir 66 */ 67 xine_mrl_t ** (*get_dir) (input_class_t *this_gen, const char *filename, int *nFiles); 68 69 /* 70 * generate autoplay list, optional: may be NULL 71 * return value: list of MRLs 72 */ 73 const char * const * (*get_autoplay_list) (input_class_t *this_gen, int *num_files); 74 75 /* 76 * close down, free all resources 77 */ 78 void (*dispose) (input_class_t *this_gen); 79 80 /* 81 * eject/load the media (if possible), optional: may be NULL 82 * 83 * returns 0 for temporary failures 84 */ 85 int (*eject_media) (input_class_t *this_gen); 86 }; 87 88 #define default_input_class_dispose (void (*) (input_class_t *this_gen))free 89 90 struct input_plugin_s { 91 92 /* 93 * open the stream 94 * return 0 if an error occured 95 */ 96 int (*open) (input_plugin_t *this_gen); 97 98 /* 99 * return capabilities of the current playable entity. See 100 * get_current_pos below for a description of a "playable entity" 101 * Capabilities a created by "OR"ing a mask of constants listed 102 * below which start "INPUT_CAP". 103 * 104 * depending on the values set, some of the functions below 105 * will or will not get called or should (not) be able to 106 * do certain tasks. 107 * 108 * for example if INPUT_CAP_SEEKABLE is set, 109 * the seek() function is expected to work fully at any time. 110 * however, if the flag is not set, the seek() function should 111 * make a best-effort attempt to seek, e.g. at least 112 * relative forward seeking should work. 113 */ 114 uint32_t (*get_capabilities) (input_plugin_t *this_gen); 115 116 /* 117 * read nlen bytes, return number of bytes read 118 * Should block until some bytes available for read; 119 * a return value of 0 indicates no data available 120 */ 121 off_t (*read) (input_plugin_t *this_gen, void *buf, off_t nlen) XINE_USED; 122 123 124 /* 125 * read one block, return newly allocated block (or NULL on failure) 126 * for blocked input sources len must be == blocksize 127 * the fifo parameter is only used to get access to the buffer_pool_alloc function 128 */ 129 buf_element_t *(*read_block)(input_plugin_t *this_gen, fifo_buffer_t *fifo, off_t len); 130 131 132 /* 133 * seek position, return new position 134 * 135 * if seeking failed, -1 is returned 136 */ 137 off_t (*seek) (input_plugin_t *this_gen, off_t offset, int origin); 138 139 140 /* 141 * seek to time position, return new position 142 * time_offset is given in miliseconds 143 * 144 * if seeking failed, -1 is returned 145 * 146 * note: only SEEK_SET (0) is currently supported as origin, 147 * unless INPUT_CAP_TIME_SEEKABLE is set. 148 * note: may be NULL is not supported 149 */ 150 off_t (*seek_time) (input_plugin_t *this_gen, int time_offset, int origin); 151 152 153 /* 154 * get current position in stream. 155 * 156 */ 157 off_t (*get_current_pos) (input_plugin_t *this_gen); 158 159 160 /* 161 * get current time position in stream in miliseconds. 162 * 163 * note: may be NULL is not supported 164 */ 165 int (*get_current_time) (input_plugin_t *this_gen); 166 167 168 /* 169 * return number of bytes in the next playable entity or -1 if the 170 * input is unlimited, as would be the case in a network stream. 171 * 172 * A "playable entity" tends to be the entities listed in a playback 173 * list or the units on which playback control generally works on. 174 * It might be the number of bytes in a VCD "segment" or "track" (if 175 * the track has no "entry" subdivisions), or the number of bytes in 176 * a PS (Program Segment or "Chapter") of a DVD. If there are no 177 * subdivisions of the input medium and it is considered one 178 * indivisible entity, it would be the byte count of that entity; 179 * for example, the length in bytes of an MPEG file. 180 181 * This length information is used, for example when in setting the 182 * absolute or relative play position or possibly calculating the 183 * bit rate. 184 */ 185 off_t (*get_length) (input_plugin_t *this_gen); 186 187 188 /* 189 * return block size in bytes of next complete playable entity (if 190 * supported, 0 otherwise). See the description above under 191 * get_length for a description of a "complete playable entity". 192 * 193 * this block size is only used for mpeg streams stored on 194 * a block oriented storage media, e.g. DVDs and VCDs, to speed 195 * up the demuxing process. only set this (and the INPUT_CAP_BLOCK 196 * flag) if this is the case for your input plugin. 197 * 198 * make this function simply return 0 if unsure. 199 */ 200 201 uint32_t (*get_blocksize) (input_plugin_t *this_gen); 202 203 204 /* 205 * return current MRL 206 */ 207 const char * (*get_mrl) (input_plugin_t *this_gen); 208 209 210 /* 211 * request optional data from input plugin. 212 */ 213 int (*get_optional_data) (input_plugin_t *this_gen, void *data, int data_type); 214 215 216 /* 217 * close stream, free instance resources 218 */ 219 void (*dispose) (input_plugin_t *this_gen); 220 221 /* 222 * "backward" link to input plugin class struct 223 */ 224 225 input_class_t *input_class; 226 227 /** 228 * @brief Pointer to the loaded plugin node. 229 * 230 * Used by the plugins loader. It's an opaque type when using the 231 * structure outside of xine's build. 232 */ 233 struct plugin_node_s *node XINE_PRIVATE_FIELD; 234 }; 235 236 /* 237 * possible capabilites an input plugin can have: 238 */ 239 #define INPUT_CAP_NOCAP 0x00000000 240 241 /* 242 * INPUT_CAP_SEEKABLE: 243 * seek () works reliably. 244 * even for plugins that do not have this flag set 245 * it is a good idea to implement the seek() function 246 * in a "best effort" style anyway, so at least 247 * throw away data for network streams when seeking forward 248 */ 249 250 #define INPUT_CAP_SEEKABLE 0x00000001 251 252 /* 253 * INPUT_CAP_BLOCK: 254 * means more or less that a block device sits behind 255 * this input plugin. get_blocksize must be implemented. 256 * will be used for fast and efficient demuxing of 257 * mpeg streams (demux_mpeg_block). 258 */ 259 260 #define INPUT_CAP_BLOCK 0x00000002 261 262 /* 263 * INPUT_CAP_AUDIOLANG: 264 * INPUT_CAP_SPULANG: 265 * input plugin knows something about audio/spu languages, 266 * e.g. knows that audio stream #0 is english, 267 * audio stream #1 is german, ... 268 * *((int *)data) will provide the requested channel number 269 * and awaits the language back in (char *)data 270 */ 271 272 #define INPUT_CAP_AUDIOLANG 0x00000008 273 #define INPUT_CAP_SPULANG 0x00000010 274 275 /* 276 * INPUT_CAP_PREVIEW: 277 * get_optional_data can handle INPUT_OPTIONAL_DATA_PREVIEW 278 * so a non-seekable stream plugin can povide the first 279 * few bytes for demuxers to look at them and decide wheter 280 * they can handle the stream or not. the preview data must 281 * be buffered and delivered again through subsequent 282 * read() calls. 283 * caller must provide a buffer allocated with at least 284 * MAX_PREVIEW_SIZE bytes. 285 */ 286 287 #define INPUT_CAP_PREVIEW 0x00000040 288 289 /* 290 * INPUT_CAP_CHAPTERS: 291 * The media streams provided by this plugin have an internal 292 * structure dividing it into segments usable for navigation. 293 * For those plugins, the behaviour of the skip button in UIs 294 * should be changed from "next MRL" to "next chapter" by 295 * sending XINE_EVENT_INPUT_NEXT. 296 */ 297 298 #define INPUT_CAP_CHAPTERS 0x00000080 299 300 /* 301 * INPUT_CAP_RIP_FORBIDDEN: 302 * means that rip/disk saving must not be used. 303 * (probably at author's request) 304 */ 305 306 #define INPUT_CAP_RIP_FORBIDDEN 0x00000100 307 308 /* 309 * INPUT_CAP_NO_CACHE: 310 * do not use input cache plugin 311 */ 312 #define INPUT_CAP_NO_CACHE 0x00000200 313 314 /* 315 * INPUT_CAP_CLONE: 316 * open a second input plugin instance on the same source. 317 */ 318 #define INPUT_CAP_CLONE 0x00000400 319 320 /* 321 * INPUT_CAP_SLOW_SEEKABLE: 322 * Like INPUT_CAP_SEEKABLE, but seeking may be expensive. 323 * Short forward seeks are fast (ex. implemented by skipping data). 324 * Seeking back or far forward is expensive. 325 * 326 * This type of seeking should be used only when user issues seek request 327 * and the destination offset is known (no binary search etc. required). 328 * Another use case could be when header is located at the end of file. 329 * 330 */ 331 #define INPUT_CAP_SLOW_SEEKABLE 0x00000800 332 333 #define INPUT_IS_SEEKABLE(input) (((input)->get_capabilities(input) & INPUT_CAP_SEEKABLE) != 0) 334 #define INPUT_IS_SLOW_SEEKABLE(input) (((input)->get_capabilities(input) & (INPUT_CAP_SEEKABLE | INPUT_CAP_SLOW_SEEKABLE)) != 0) 335 336 /* 337 * INPUT_CAP_SIZED_PREVIEW: 338 * Like INPUT_CAP_PREVIEW, but the buffer shall contain an int telling 339 * the count of bytes to read before the call. 340 */ 341 #define INPUT_CAP_SIZED_PREVIEW 0x00001000 342 343 /* 344 * INPUT_CAP_TIME_SEEKABLE: 345 * Time based seek works reliably and should be preferred over size based seek. 346 */ 347 #define INPUT_CAP_TIME_SEEKABLE 0x00002000 348 349 /* 350 * INPUT_CAP_NEW_MRL: 351 * Plugin can try to switch to a new mrl on the fly. 352 * See INPUT_OPTIONAL_DATA_NEW_MRL below. 353 */ 354 #define INPUT_CAP_NEW_MRL 0x00004000 355 356 /* 357 * INPUT_CAP_LIVE: 358 * Plugin knows it has a real live stream. It runs at a fixed speed that is 359 * _roughly_ the same as XINE_FINE_SPEED_NORMAL. 360 */ 361 #define INPUT_CAP_LIVE 0x00008000 362 363 #define INPUT_OPTIONAL_UNSUPPORTED 0 364 #define INPUT_OPTIONAL_SUCCESS 1 365 366 #define INPUT_OPTIONAL_DATA_AUDIOLANG 2 367 #define INPUT_OPTIONAL_DATA_SPULANG 3 368 #define INPUT_OPTIONAL_DATA_PREVIEW 7 369 370 /* buffer is a const char **; the string is freed by the input plugin. */ 371 #define INPUT_OPTIONAL_DATA_MIME_TYPE 8 372 /* buffer is unused; true if the demuxer should be determined by the MIME type */ 373 #define INPUT_OPTIONAL_DATA_DEMUX_MIME_TYPE 9 374 /* buffer is a const char **; the string is static or freed by the input plugin. */ 375 #define INPUT_OPTIONAL_DATA_DEMUXER 10 376 /* buffer is a struct input_plugin_s **; release by calling ptr->dispose (ptr). */ 377 #define INPUT_OPTIONAL_DATA_CLONE 11 378 /* see INPUT_CAP_SIZED_PREVIEW above. */ 379 #define INPUT_OPTIONAL_DATA_SIZED_PREVIEW 12 380 /* buffer is an int32_t * where input plugin will store media duration in milliseconds. */ 381 #define INPUT_OPTIONAL_DATA_DURATION 13 382 /* buffer is a const char * holding the new mrl to try. 383 * fragment streams can avoid input_plugin->dispose () followed by input_class->get_instance (), 384 * or _x_free_input_plugin () followed by _x_find_input_plugin () on a lot of * similar mrls. */ 385 #define INPUT_OPTIONAL_DATA_NEW_MRL 14 386 387 #define MAX_MRL_ENTRIES 255 388 #define MAX_PREVIEW_SIZE 4096 389 390 /* network buffering control */ 391 typedef struct xine_nbc_st xine_nbc_t; 392 xine_nbc_t *xine_nbc_init (xine_stream_t *stream) XINE_PROTECTED; 393 void xine_nbc_close (xine_nbc_t *nbc) XINE_PROTECTED; 394 395 396 /* Types of mrls returned by get_dir() */ 397 #define mrl_unknown (0 << 0) 398 #define mrl_dvd (1 << 0) 399 #define mrl_vcd (1 << 1) 400 #define mrl_net (1 << 2) 401 #define mrl_rtp (1 << 3) 402 #define mrl_stdin (1 << 4) 403 #define mrl_cda (1 << 5) 404 #define mrl_file (1 << 6) 405 #define mrl_file_fifo (1 << 7) 406 #define mrl_file_chardev (1 << 8) 407 #define mrl_file_directory (1 << 9) 408 #define mrl_file_blockdev (1 << 10) 409 #define mrl_file_normal (1 << 11) 410 #define mrl_file_symlink (1 << 12) 411 #define mrl_file_sock (1 << 13) 412 #define mrl_file_exec (1 << 14) 413 #define mrl_file_backup (1 << 15) 414 #define mrl_file_hidden (1 << 16) 415 416 /* 417 * Freeing/zeroing all of entries of given mrl. 418 */ 419 #define MRL_ZERO(m) { \ 420 if((m)) { \ 421 free((m)->origin); \ 422 free((m)->mrl); \ 423 free((m)->link); \ 424 (m)->origin = NULL; \ 425 (m)->mrl = NULL; \ 426 (m)->link = NULL; \ 427 (m)->type = 0; \ 428 (m)->size = (off_t) 0; \ 429 } \ 430 } 431 432 /* 433 * Duplicate two mrls entries (s = source, d = destination). 434 */ 435 #define MRL_DUPLICATE(s, d) { \ 436 _x_assert((s) != NULL); \ 437 _x_assert((d) != NULL); \ 438 \ 439 free((d)->origin); \ 440 (d)->origin = (s)->origin ? strdup((s)->origin) : NULL; \ 441 \ 442 free((d)->mrl); \ 443 (d)->mrl = (s)->mrl ? strdup((s)->mrl) : NULL; \ 444 \ 445 free((d)->link); \ 446 (d)->link = (s)->link ? strdup((s)->link) : NULL; \ 447 \ 448 (d)->type = (s)->type; \ 449 (d)->size = (s)->size; \ 450 } 451 452 /* 453 * Duplicate two arrays of mrls (s = source, d = destination). 454 */ 455 #define MRLS_DUPLICATE(s, d) { \ 456 int i = 0; \ 457 \ 458 _x_assert((s) != NULL); \ 459 _x_assert((d) != NULL); \ 460 \ 461 while((s) != NULL) { \ 462 d[i] = (xine_mrl_t *) malloc(sizeof(xine_mrl_t)); \ 463 MRL_DUPLICATE(s[i], d[i]); \ 464 i++; \ 465 } \ 466 } 467 468 469 #endif 470