src/input/stream.h

   1 /*****************************************************************************
   2  * stream.h: Input stream functions
   3  *****************************************************************************
   4  * Copyright (C) 1998-2008 VLC authors and VideoLAN
   5  * Copyright (C) 2008 Laurent Aimar
   6  * $Id$
   7  *
   8  * Authors: Laurent Aimar <fenrir@via.ecp.fr>
   9  *
  10  * This program is free software; you can redistribute it and/or modify it
  11  * under the terms of the GNU Lesser General Public License as published by
  12  * the Free Software Foundation; either version 2.1 of the License, or
  13  * (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  18  * GNU Lesser General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU Lesser General Public License
  21  * along with this program; if not, write to the Free Software Foundation,
  22  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  23  *****************************************************************************/
  24
  25 #ifndef LIBVLC_INPUT_STREAM_H
  26 #define LIBVLC_INPUT_STREAM_H 1
  27
  28 #include <vlc_common.h>
  29 #include <vlc_stream.h>
  30
  31 /* */
  32 void stream_CommonDelete( stream_t *s );
  33
  34 /**
  35  * This function creates a raw stream_t from an URL.
  36  */
  37 stream_t *stream_AccessNew(vlc_object_t *, input_thread_t *, bool, const char *);
  38
  39 /**
  40  * Probes stream filters automatically.
  41  *
  42  * This function automatically and repeatedly probes for applicable stream
  43  * filters to append downstream of an existing stream. Any such filter will
  44  * convert the stream into another stream, e.g. decompressing it or extracting
  45  * the list of contained files (playlist).
  46  *
  47  * This function transfers ownership of the supplied stream to the following
  48  * stream filter, of the first stream filter to the second stream filter, and
  49  * so on. Any attempt to access the original stream filter directly is
  50  * explicitly undefined.
  51  *
  52  * If, and only if, no filters were probed succesfully, a pointer to the
  53  * unchanged source stream will be returned. Otherwise, this returns a stream
  54  * filter. The return value is thus guaranteed to be non-NULL.
  55  *
  56  * @param source input stream around which to build a filter chain
  57  *
  58  * @return the last, most downstream stream object.
  59  *
  60  * @note The return value must be freed with vlc_stream_Delete() after use.
  61  * This will automatically free the whole chain and the underlying stream.
  62  */
  63 stream_t *stream_FilterAutoNew( stream_t *source ) VLC_USED;
  64
  65 /**
  66  * Builds an explicit chain of stream filters.
  67  *
  68  * This function creates a chain of filters according to a supplied list.
  69  *
  70  * See also stream_FilterAutoNew(). Those two functions have identical
  71  * semantics; the only difference lies in how the list of probed filters is
  72  * determined (manually versus automatically).
  73  *
  74  * If the list is empty, or if probing each of the requested filters failed,
  75  * this function will return a pointer to the supplied source stream.
  76  *
  77  * @param source input stream around which to build a filter chain
  78  * @param list colon-separated list of stream filters (upstream first)
  79  *
  80  * @return The last stream (filter) in the chain.
  81  * The return value is always a valid (non-NULL) stream pointer.
  82  */
  83 stream_t *stream_FilterChainNew( stream_t *source, const char *list ) VLC_USED;
  84
  85 /**
  86  * Attach \ref stream_extractor%s according to specified data
  87  *
  88  * This function will parse the passed data, and try to attach a \ref
  89  * stream_extractor for each specified entity as per the fragment specification
  90  * associated with a \ref mrl,
  91  *
  92  * \warning The data in `*stream` can be modified even if this function only
  93  *          locates some of the entities specified in `psz_data`. It is up to
  94  *          the caller to free the resource referred to by `*stream`, no matter
  95  *          what this function returns.
  96  *
  97  * \warning Please see \ref vlc_stream_extractor_Attach for a function that
  98  *          will not modify the passed stream upon failure. \ref
  99  *          stream_extractor_AttachParsed shall only be used when the caller
 100  *          only cares about the stream on successful attachment of **all**
 101  *          stream-extractors referred to by `psz_data`, something which is not
 102  *          guaranteed.
 103  *
 104  * \param[out] source a pointer-to-pointer to stream where the attached
 105  *             stream-extractor will be applied. `*stream` will refer
 106  *             to the last successful attachment.
 107  * \param[out] out_extra `*out_extra` will point to any additional data
 108  *             in `psz_data` that does not specify an entity (if any).
 109  * \return VLC_SUCCESS on success, an error-code on failure
 110  **/
 111 int stream_extractor_AttachParsed( stream_t** stream, const char* psz_data,
 112                                    char const** out_extra );
 113
 114 char *get_path(const char *location);
 115
 116 #endif