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 stream_t *vlc_stream_CustomNew(vlc_object_t *parent,
  32                                void (*destroy)(stream_t *), size_t extra_size,
  33                                const char *type_name);
  34 void *vlc_stream_Private(stream_t *stream);
  35
  36 /* */
  37 void stream_CommonDelete( stream_t *s );
  38
  39 stream_t *vlc_stream_AttachmentNew(vlc_object_t *p_this,
  40                                    input_attachment_t *attachement);
  41
  42 /**
  43  * This function creates a raw stream_t from an URL.
  44  */
  45 stream_t *stream_AccessNew(vlc_object_t *, input_thread_t *, es_out_t *, bool,
  46                            const char *);
  47
  48 /**
  49  * Probes stream filters automatically.
  50  *
  51  * This function automatically and repeatedly probes for applicable stream
  52  * filters to append downstream of an existing stream. Any such filter will
  53  * convert the stream into another stream, e.g. decompressing it or extracting
  54  * the list of contained files (playlist).
  55  *
  56  * This function transfers ownership of the supplied stream to the following
  57  * stream filter, of the first stream filter to the second stream filter, and
  58  * so on. Any attempt to access the original stream filter directly is
  59  * explicitly undefined.
  60  *
  61  * If, and only if, no filters were probed succesfully, a pointer to the
  62  * unchanged source stream will be returned. Otherwise, this returns a stream
  63  * filter. The return value is thus guaranteed to be non-NULL.
  64  *
  65  * @param source input stream around which to build a filter chain
  66  *
  67  * @return the last, most downstream stream object.
  68  *
  69  * @note The return value must be freed with vlc_stream_Delete() after use.
  70  * This will automatically free the whole chain and the underlying stream.
  71  */
  72 stream_t *stream_FilterAutoNew( stream_t *source ) VLC_USED;
  73
  74 /**
  75  * Builds an explicit chain of stream filters.
  76  *
  77  * This function creates a chain of filters according to a supplied list.
  78  *
  79  * See also stream_FilterAutoNew(). Those two functions have identical
  80  * semantics; the only difference lies in how the list of probed filters is
  81  * determined (manually versus automatically).
  82  *
  83  * If the list is empty, or if probing each of the requested filters failed,
  84  * this function will return a pointer to the supplied source stream.
  85  *
  86  * @param source input stream around which to build a filter chain
  87  * @param list colon-separated list of stream filters (upstream first)
  88  *
  89  * @return The last stream (filter) in the chain.
  90  * The return value is always a valid (non-NULL) stream pointer.
  91  */
  92 stream_t *stream_FilterChainNew( stream_t *source, const char *list ) VLC_USED;
  93
  94 /**
  95  * Attach \ref stream_extractor%s according to specified data
  96  *
  97  * This function will parse the passed data, and try to attach a \ref
  98  * stream_extractor for each specified entity as per the fragment specification
  99  * associated with a \ref mrl,
 100  *
 101  * \warning The data in `*stream` can be modified even if this function only
 102  *          locates some of the entities specified in `psz_data`. It is up to
 103  *          the caller to free the resource referred to by `*stream`, no matter
 104  *          what this function returns.
 105  *
 106  * \warning Please see \ref vlc_stream_extractor_Attach for a function that
 107  *          will not modify the passed stream upon failure. \ref
 108  *          stream_extractor_AttachParsed shall only be used when the caller
 109  *          only cares about the stream on successful attachment of **all**
 110  *          stream-extractors referred to by `psz_data`, something which is not
 111  *          guaranteed.
 112  *
 113  * \param[out] source a pointer-to-pointer to stream where the attached
 114  *             stream-extractor will be applied. `*stream` will refer
 115  *             to the last successful attachment.
 116  * \param[out] out_extra `*out_extra` will point to any additional data
 117  *             in `psz_data` that does not specify an entity (if any).
 118  * \return VLC_SUCCESS on success, an error-code on failure
 119  **/
 120 int stream_extractor_AttachParsed( stream_t** stream, const char* psz_data,
 121                                    char const** out_extra );
 122
 123 char *get_path(const char *location);
 124
 125 #endif