xine-lib 1.2.13-20230125hg15249
input_plugin.h
Go to the documentation of this file.
1/*
2 * Copyright (C) 2000-2022 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
31struct plugin_node_s;
32
33#define INPUT_PLUGIN_IFACE_VERSION 18
34
37
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 */
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 * an empty mrl (buffer[0] == 0) means close connection now, and wait for a real new mrl later. */
386#define INPUT_OPTIONAL_DATA_NEW_MRL 14
387/* buffer is a xine_mfrag_list_t ** where input plugin will store a pointer to its media fragment
388 * list, if any (see <xine/mfrag.h>). demux may update it if fragment index is part of the
389 * container, like with some .mp4. */
390#define INPUT_OPTIONAL_DATA_FRAGLIST 15
391/* after a successful open () of a main input, this may supply possible side stream inputs.
392 * on call, buffer is an int * telling the side stream index 1..3.
393 * on return, buffer is a struct input_plugin_s ** where a pointer to a ready side input
394 * bound to xine_get_side_stream (main_stream, stream_index) will be stored if available.
395 * NOTE: this shall be an alternative get_instance (), not the result of an _x_find_input_plugin ().
396 * release by _x_free_input_plugin () or xine_dispose () of the side stream. */
397#define INPUT_OPTIONAL_DATA_SIDE 16
398/* returns a pts value (1/90000s) to add to all demux media pts, or INPUT_OPTIONAL_UNSUPPORTED == 0.
399 * some fragment streams need this to provide a/v sync over multiple side streams. */
400#define INPUT_OPTIONAL_DATA_PTSOFFS 17
401/* data is an int * telling how many seconds to go back into a live stream.
402 * yes this _does_ work sometimes, up to 24h ;-) */
403#define INPUT_OPTIONAL_DATA_REWIND 18
404/* ask plugin to generate a new preview from the current position,
405 * eg to skip a large ID3v2 tag. data is ignored. */
406#define INPUT_OPTIONAL_DATA_NEW_PREVIEW 19
407
408#define MAX_MRL_ENTRIES 255
409#define MAX_PREVIEW_SIZE 4096
410
411/* network buffering control */
412typedef struct xine_nbc_st xine_nbc_t;
414/* returns a combinwd demux pts position, starting with 0 at stream start. */
417
418
419/* Types of mrls returned by get_dir() */
420#define mrl_unknown (0 << 0)
421#define mrl_dvd (1 << 0)
422#define mrl_vcd (1 << 1)
423#define mrl_net (1 << 2)
424#define mrl_rtp (1 << 3)
425#define mrl_stdin (1 << 4)
426#define mrl_cda (1 << 5)
427#define mrl_file (1 << 6)
428#define mrl_file_fifo (1 << 7)
429#define mrl_file_chardev (1 << 8)
430#define mrl_file_directory (1 << 9)
431#define mrl_file_blockdev (1 << 10)
432#define mrl_file_normal (1 << 11)
433#define mrl_file_symlink (1 << 12)
434#define mrl_file_sock (1 << 13)
435#define mrl_file_exec (1 << 14)
436#define mrl_file_backup (1 << 15)
437#define mrl_file_hidden (1 << 16)
438
439/*
440 * Freeing/zeroing all of entries of given mrl.
441 */
442#define MRL_ZERO(m) { \
443 if((m)) { \
444 free((m)->origin); \
445 free((m)->mrl); \
446 free((m)->link); \
447 (m)->origin = NULL; \
448 (m)->mrl = NULL; \
449 (m)->link = NULL; \
450 (m)->type = 0; \
451 (m)->size = (off_t) 0; \
452 } \
453 }
454
455/*
456 * Duplicate two mrls entries (s = source, d = destination).
457 */
458#define MRL_DUPLICATE(s, d) { \
459 _x_assert((s) != NULL); \
460 _x_assert((d) != NULL); \
461 \
462 free((d)->origin); \
463 (d)->origin = (s)->origin ? strdup((s)->origin) : NULL; \
464 \
465 free((d)->mrl); \
466 (d)->mrl = (s)->mrl ? strdup((s)->mrl) : NULL; \
467 \
468 free((d)->link); \
469 (d)->link = (s)->link ? strdup((s)->link) : NULL; \
470 \
471 (d)->type = (s)->type; \
472 (d)->size = (s)->size; \
473 }
474
475/*
476 * Duplicate two arrays of mrls (s = source, d = destination).
477 */
478#define MRLS_DUPLICATE(s, d) { \
479 int i = 0; \
480 \
481 _x_assert((s) != NULL); \
482 _x_assert((d) != NULL); \
483 \
484 while((s) != NULL) { \
485 d[i] = (xine_mrl_t *) malloc(sizeof(xine_mrl_t)); \
486 MRL_DUPLICATE(s[i], d[i]); \
487 i++; \
488 } \
489}
490
491
492#endif
#define XINE_USED
Definition attributes.h:60
#define XINE_PROTECTED
Definition attributes.h:75
int64_t xine_nbc_get_pos_pts(xine_nbc_t *nbc)
Definition net_buf_ctrl.c:1080
xine_nbc_t * xine_nbc_init(xine_stream_t *stream)
Definition net_buf_ctrl.c:1090
void xine_nbc_close(xine_nbc_t *nbc)
Definition net_buf_ctrl.c:1183
Definition buffer.h:338
Definition buffer.h:593
Definition input_plugin.h:38
const char * text_domain
Optional non-standard catalog to use with dgettext() for description.
Definition input_plugin.h:61
const char * description
human readable (verbose = 1 line) description for this plugin class
Definition input_plugin.h:56
int(* eject_media)(input_class_t *this_gen)
Definition input_plugin.h:85
const char * identifier
short human readable identifier for this plugin class
Definition input_plugin.h:49
void(* dispose)(input_class_t *this_gen)
Definition input_plugin.h:78
Definition input_plugin.h:90
int(* open)(input_plugin_t *this_gen)
Definition input_plugin.h:96
input_class_t * input_class
Definition input_plugin.h:225
uint32_t(* get_capabilities)(input_plugin_t *this_gen)
Definition input_plugin.h:114
int(* get_current_time)(input_plugin_t *this_gen)
Definition input_plugin.h:165
off_t(* read)(input_plugin_t *this_gen, void *buf, off_t nlen) XINE_USED
Definition input_plugin.h:121
struct plugin_node_s *node XINE_PRIVATE_FIELD
Pointer to the loaded plugin node.
Definition input_plugin.h:233
off_t(* seek)(input_plugin_t *this_gen, off_t offset, int origin)
Definition input_plugin.h:137
off_t(* seek_time)(input_plugin_t *this_gen, int time_offset, int origin)
Definition input_plugin.h:150
void(* dispose)(input_plugin_t *this_gen)
Definition input_plugin.h:219
uint32_t(* get_blocksize)(input_plugin_t *this_gen)
Definition input_plugin.h:201
off_t(* get_current_pos)(input_plugin_t *this_gen)
Definition input_plugin.h:157
off_t(* get_length)(input_plugin_t *this_gen)
Definition input_plugin.h:185
int(* get_optional_data)(input_plugin_t *this_gen, void *data, int data_type)
Definition input_plugin.h:213
Definition plugin_catalog.h:44
Definition xine.h:1124
Definition net_buf_ctrl.c:83
xine_stream_t * stream
Definition net_buf_ctrl.c:85
Definition xine_internal.h:123