include/vlc_stream_extractor.h

   1 /*****************************************************************************
   2  * vlc_stream_extractor.h
   3  *****************************************************************************
   4  * Copyright (C) 2016 VLC authors and VideoLAN
   5  *
   6  * This program is free software; you can redistribute it and/or modify it
   7  * under the terms of the GNU Lesser General Public License as published by
   8  * the Free Software Foundation; either version 2.1 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program 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 Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public License
  17  * along with this program; if not, write to the Free Software Foundation,
  18  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  19  *****************************************************************************/
  20
  21 #ifndef VLC_STREAM_EXTRACTOR_H
  22 #define VLC_STREAM_EXTRACTOR_H
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 /**
  29  * \defgroup stream_extractor Stream Extractor
  30  * \ingroup input
  31  *
  32  * If a stream can be viewed as a directory, such as when opening a
  33  * compressed archive, a \em stream-extractor is used to get access to
  34  * the entities inside said stream.
  35  *
  36  * A \em stream-extractor can do one of two things;
  37  *
  38  *  - either it lists the logical entries within a stream, or;
  39  *  - it extracts the data associated with one of those entries based
  40  *    on a unique identifier.
  41  *
  42  * @{
  43  *
  44  **/
  45 struct stream_extractor_t {
  46     VLC_COMMON_MEMBERS
  47
  48     union {
  49         /**
  50          * Callbacks for entity extraction
  51          *
  52          * The following callbacks shall be populated if the stream_extractor is
  53          * used to extract a specific entity from the source-stream. Each
  54          * callback shall behave as those, with the same name, specified in \ref
  55          * stream_t.
  56          *
  57          **/
  58         struct {
  59             ssize_t  (*pf_read)(struct stream_extractor_t *, void *buf, size_t len);
  60             block_t* (*pf_block)(struct stream_extractor_t *, bool *eof);
  61             int      (*pf_seek)(struct stream_extractor_t *, uint64_t);
  62             int      (*pf_control)(struct stream_extractor_t *, int i_query, va_list);
  63
  64         } stream;
  65
  66         /**
  67          * Callbacks for stream directory listing
  68          *
  69          * These callbacks are used when a stream is to be treated as a
  70          * directory, it shall behave as those, with the same name, specified
  71          * in \ref stream_t.
  72          *
  73          **/
  74         struct {
  75             int (*pf_readdir)(struct stream_extractor_t *, input_item_node_t *);
  76
  77         } directory;
  78
  79     };
  80
  81     void* p_sys; /**< Private data pointer */
  82     stream_t* source; /**< The source stream */
  83     char* identifier; /**< name of requested entity to extract, or NULL
  84                        **  when requested to list directories */
  85 };
  86
  87 typedef struct stream_extractor_t stream_extractor_t;
  88
  89 /**
  90  * Create a relative MRL for the associated entity
  91  *
  92  * This function shall be used by stream_extractor_t's in order to
  93  * generate a MRL that refers to an entity within the stream. Normally
  94  * this function will only be invoked within `pf_readdir` in order to
  95  * get the virtual path of the listed items.
  96  *
  97  * \warning the returned value is to be freed by the caller
  98  *
  99  * \param extractor the stream_extractor_t in which the entity belongs
 100  * \param subentry the name of the entity in question
 101  *
 102  * \return a pointer to the resulting MRL on success, NULL on failure
 103  **/
 104 VLC_API char* vlc_stream_extractor_CreateMRL( stream_extractor_t*,
 105                                               char const* subentry );
 106
 107 /**
 108  * Construct a new stream_extractor-based stream
 109  *
 110  * This function is used to attach a stream extractor to an already
 111  * existing stream.
 112  *
 113  * If \p identifier is `NULL`, `*stream` is guaranteed to refer to a
 114  * directory, otherwise \p identifier denotes the specific subentry
 115  * that one would like to access within the stream.
 116  *
 117  * If \p identifier is not NULL, `*stream` will refer to data for the
 118  * entity in question.
 119  *
 120  * \param[out] stream a pointer-to-pointer to stream, `*stream` will
 121  *             refer to the attached stream on success, and left
 122  *             untouched on failure.
 123  * \param identifier NULL or a c-style string referring to the desired entity
 124  * \param module_name NULL or an explicit stream-extractor module name
 125  *
 126  * \return VLC_SUCCESS if a stream-extractor was successfully
 127  *         attached, an error-code on failure.
 128  **/
 129
 130 VLC_API int vlc_stream_extractor_Attach( stream_t** source,
 131                                          char const* identifier,
 132                                          char const* module_name );
 133 /**
 134  * @}
 135  */
 136
 137 #ifdef __cplusplus
 138 } /* extern "C" */
 139 #endif
 140 #endif /* include-guard */