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  *  - lists the logical entries within a stream:
  39  *    - type = \ref stream_directory_t
  40  *    - capability = "stream_directory"
  41  *
  42  *  - extract data associated with one specific entry within a stream:
  43  *    - type = \ref stream_extractor_t
  44  *    - capability = "stream_extractor"
  45  *
  46  * @{
  47  *
  48  **/
  49
  50 typedef struct stream_extractor_t {
  51     struct vlc_object_t obj;
  52
  53     /**
  54      * \name Callbacks for entity extraction
  55      *
  56      * The following members shall be populated as specified by the
  57      * documentation associated with \ref stream_t for the equivalent name.
  58      *
  59      * @{
  60      **/
  61     ssize_t  (*pf_read)(struct stream_extractor_t*, void* buf, size_t len);
  62     block_t* (*pf_block)(struct stream_extractor_t*, bool* eof);
  63     int      (*pf_seek)(struct stream_extractor_t*, uint64_t);
  64     int      (*pf_control)(struct stream_extractor_t*, int request, va_list args);
  65     /** @} */
  66
  67     char const* identifier; /**< the name of the entity to be extracted */
  68     stream_t* source; /**< the source stream to be consumed */
  69     void* p_sys;      /**< private opaque handle to be used by the module */
  70
  71 } stream_extractor_t;
  72
  73 typedef struct stream_directory_t {
  74     struct vlc_object_t obj;
  75
  76     /**
  77      * \name Callbacks for stream directories
  78      *
  79      * The following members shall be populated as specified by the
  80      * documentation associated with \ref stream_t for the equivalent name.
  81      *
  82      * @{
  83      **/
  84     int (*pf_readdir)(struct stream_directory_t*, input_item_node_t* );
  85     /** @} */
  86
  87     stream_t* source; /**< the source stream to be consumed */
  88     void* p_sys; /**< private opaque handle to be used by the module */
  89
  90 } stream_directory_t;
  91
  92 /**
  93  * Create a stream for the data referred to by a \ref mrl
  94  *
  95  * This function will create a \ref stream that reads from the specified \ref
  96  * mrl, potentially making use of \ref stream_extractor%s to access named
  97  * entities within the data read from the original source.
  98  *
  99  *  - See the \ref mrl specification for further information.
 100  *  - The returned resource shall be deleted through \ref vlc_stream_Delete.
 101  *
 102  * \warning This function is only to be used when \ref mrl functionality is
 103  *          explicitly needed. \ref vlc_stream_NewURL shall be used where
 104  *          applicable.
 105  *
 106  * \param obj the owner of the requested stream
 107  * \param mrl the mrl for which the stream_t should be created
 108  * \return `NULL` on error, a pointer to \ref stream_t on success.
 109  **/
 110 VLC_API stream_t * vlc_stream_NewMRL(vlc_object_t *obj, const char *mrl)
 111 VLC_USED;
 112 #define vlc_stream_NewMRL(a, b) vlc_stream_NewMRL(VLC_OBJECT(a), b)
 113
 114 /**
 115  * Create a relative MRL for the associated entity
 116  *
 117  * This function shall be used by stream_directory_t's in order to
 118  * generate an MRL that refers to an entity within the stream. Normally
 119  * this function will only be invoked within `pf_readdir` in order to
 120  * get the virtual path of the listed items.
 121  *
 122  * \warning the returned value is to be freed by the caller
 123  *
 124  * \param extractor the stream_directory_t for which the entity belongs
 125  * \param subentry the name of the entity in question
 126  *
 127  * \return a pointer to the resulting MRL on success, NULL on failure
 128  **/
 129 VLC_API char* vlc_stream_extractor_CreateMRL( stream_directory_t*,
 130                                               char const* subentry );
 131
 132 /**
 133  * \name Attach a stream-extractor to the passed stream
 134  *
 135  * These functions are used to attach a stream extractor to an already existing
 136  * stream. As hinted by their names, \ref vlc_stream_extractor_Attach will
 137  * attach an \em entity-extractor, whereas \ref vlc_stream_directory_Attach
 138  * will attach a \em stream-directory.
 139  *
 140  * \param[out] stream a pointer-to-pointer to stream, `*stream` will
 141  *             refer to the attached stream on success, and left
 142  *             untouched on failure.
 143  * \param identifier (if present) NULL or a c-style string referring to the
 144  *                   desired entity
 145  * \param module_name NULL or an explicit stream-extractor module name
 146  *
 147  * \return VLC_SUCCESS if a stream-extractor was successfully
 148  *         attached, an error-code on failure.
 149  *
 150  * @{
 151  **/
 152
 153 VLC_API int vlc_stream_extractor_Attach( stream_t** source,
 154                                          char const* identifier,
 155                                          char const* module_name );
 156
 157 VLC_API int vlc_stream_directory_Attach( stream_t** source,
 158                                          char const* module_name );
 159 /**
 160  * @}
 161  */
 162
 163 /**
 164  * @}
 165  */
 166
 167 #ifdef __cplusplus
 168 } /* extern "C" */
 169 #endif
 170 #endif /* include-guard */