xine-lib  1.2.10
input_plugin.h
Go to the documentation of this file.
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 ;
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 
49  const char *identifier;
50 
56  const char *description;
57 
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 
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 
226 
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;
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
input_class_s::text_domain
const char * text_domain
Optional non-standard catalog to use with dgettext() for description.
Definition: input_plugin.h:61
input_plugin_s::input_class
input_class_t * input_class
Definition: input_plugin.h:225
input_plugin_s::XINE_PRIVATE_FIELD
struct plugin_node_s *node XINE_PRIVATE_FIELD
Pointer to the loaded plugin node.
Definition: input_plugin.h:233
input_plugin_s::seek
off_t(* seek)(input_plugin_t *this_gen, off_t offset, int origin)
Definition: input_plugin.h:137
xine_stream_s
Definition: xine_internal.h:123
xineutils.h
input_plugin_s::get_current_pos
off_t(* get_current_pos)(input_plugin_t *this_gen)
Definition: input_plugin.h:157
input_plugin_s::open
int(* open)(input_plugin_t *this_gen)
Definition: input_plugin.h:96
input_class_s::eject_media
int(* eject_media)(input_class_t *this_gen)
Definition: input_plugin.h:85
input_class_s
Definition: input_plugin.h:38
input_plugin_s::seek_time
off_t(* seek_time)(input_plugin_t *this_gen, int time_offset, int origin)
Definition: input_plugin.h:150
attributes.h
xine_mrl_s
Definition: xine.h:1107
input_plugin_s::get_length
off_t(* get_length)(input_plugin_t *this_gen)
Definition: input_plugin.h:185
xine_nbc_st
Definition: net_buf_ctrl.c:72
fifo_buffer_s
Definition: buffer.h:581
input_plugin_s::get_blocksize
uint32_t(* get_blocksize)(input_plugin_t *this_gen)
Definition: input_plugin.h:201
input_plugin_s
Definition: input_plugin.h:90
input_class_s::description
const char * description
human readable (verbose = 1 line) description for this plugin class
Definition: input_plugin.h:56
xine_nbc_close
void xine_nbc_close(xine_nbc_t *nbc)
Definition: net_buf_ctrl.c:844
input_plugin_s::dispose
void(* dispose)(input_plugin_t *this_gen)
Definition: input_plugin.h:219
buf_element_s
Definition: buffer.h:337
input_plugin_s::get_optional_data
int(* get_optional_data)(input_plugin_t *this_gen, void *data, int data_type)
Definition: input_plugin.h:213
buffer.h
xine_nbc_init
xine_nbc_t * xine_nbc_init(xine_stream_t *stream)
Definition: net_buf_ctrl.c:768
input_class_s::identifier
const char * identifier
short human readable identifier for this plugin class
Definition: input_plugin.h:49
input_plugin_s::get_current_time
int(* get_current_time)(input_plugin_t *this_gen)
Definition: input_plugin.h:165
os_types.h
input_plugin_s::get_capabilities
uint32_t(* get_capabilities)(input_plugin_t *this_gen)
Definition: input_plugin.h:114
input_plugin_s::read
off_t(* read)(input_plugin_t *this_gen, void *buf, off_t nlen) XINE_USED
Definition: input_plugin.h:121
XINE_USED
#define XINE_USED
Definition: attributes.h:58
xine_nbc_st::stream
xine_stream_t * stream
Definition: net_buf_ctrl.c:74
XINE_PROTECTED
#define XINE_PROTECTED
Definition: attributes.h:73
plugin_node_s
Definition: plugin_catalog.h:44
input_class_s::dispose
void(* dispose)(input_class_t *this_gen)
Definition: input_plugin.h:78