vlc_stream_extractor.h 4.97 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
/*****************************************************************************
 * vlc_stream_extractor.h
 *****************************************************************************
 * Copyright (C) 2016 VLC authors and VideoLAN
 *
 * This program is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
 *****************************************************************************/

#ifndef VLC_STREAM_EXTRACTOR_H
#define VLC_STREAM_EXTRACTOR_H

#ifdef __cplusplus
extern "C" {
#endif

/**
 * \defgroup stream_extractor Stream Extractor
 * \ingroup input
 *
 * If a stream can be viewed as a directory, such as when opening a
 * compressed archive, a \em stream-extractor is used to get access to
 * the entities inside said stream.
 *
 * A \em stream-extractor can do one of two things;
 *
38 39 40 41 42 43 44
 *  - lists the logical entries within a stream:
 *    - type = \ref stream_directory_t
 *    - capability = "stream_directory"
 *
 *  - extract data associated with one specific entry within a stream:
 *    - type = \ref stream_extractor_t
 *    - capability = "stream_extractor"
45 46 47 48
 *
 * @{
 *
 **/
49 50

typedef struct stream_extractor_t {
51
    VLC_COMMON_MEMBERS
52

53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73
    /**
     * \name Callbacks for entity extraction
     *
     * The following members shall be populated as specified by the
     * documentation associated with \ref stream_t for the equivalent name.
     *
     * @{
     **/
    ssize_t  (*pf_read)(struct stream_extractor_t*, void* buf, size_t len);
    block_t* (*pf_block)(struct stream_extractor_t*, bool* eof);
    int      (*pf_seek)(struct stream_extractor_t*, uint64_t);
    int      (*pf_control)(struct stream_extractor_t*, int request, va_list args);
    /** @} */

    char const* identifier; /**< the name of the entity to be extracted */
    stream_t* source; /**< the source stream to be consumed */
    void* p_sys;      /**< private opaque handle to be used by the module */

} stream_extractor_t;

typedef struct stream_directory_t {
74
    VLC_COMMON_MEMBERS
75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90

    /**
     * \name Callbacks for stream directories
     *
     * The following members shall be populated as specified by the
     * documentation associated with \ref stream_t for the equivalent name.
     *
     * @{
     **/
    int (*pf_readdir)(struct stream_directory_t*, input_item_node_t* );
    /** @} */

    stream_t* source; /**< the source stream to be consumed */
    void* p_sys; /**< private opaque handle to be used by the module */

} stream_directory_t;
91

92 93 94
/**
 * Create a relative MRL for the associated entity
 *
95 96
 * This function shall be used by stream_directory_t's in order to
 * generate an MRL that refers to an entity within the stream. Normally
97 98 99 100 101
 * this function will only be invoked within `pf_readdir` in order to
 * get the virtual path of the listed items.
 *
 * \warning the returned value is to be freed by the caller
 *
102
 * \param extractor the stream_directory_t for which the entity belongs
103 104 105 106
 * \param subentry the name of the entity in question
 *
 * \return a pointer to the resulting MRL on success, NULL on failure
 **/
107
VLC_API char* vlc_stream_extractor_CreateMRL( stream_directory_t*,
108 109
                                              char const* subentry );

110
/**
111
 * \name Attach a stream-extractor to the passed stream
112
 *
113 114 115 116
 * These functions are used to attach a stream extractor to an already existing
 * stream. As hinted by their names, \ref vlc_stream_extractor_Attach will
 * attach an \em entity-extractor, whereas \ref vlc_stream_directory_Attach
 * will attach a \em stream-directory.
117 118 119 120
 *
 * \param[out] stream a pointer-to-pointer to stream, `*stream` will
 *             refer to the attached stream on success, and left
 *             untouched on failure.
121 122
 * \param identifier (if present) NULL or a c-style string referring to the
 *                   desired entity
123 124 125 126
 * \param module_name NULL or an explicit stream-extractor module name
 *
 * \return VLC_SUCCESS if a stream-extractor was successfully
 *         attached, an error-code on failure.
127 128
 *
 * @{
129 130 131 132 133
 **/

VLC_API int vlc_stream_extractor_Attach( stream_t** source,
                                         char const* identifier,
                                         char const* module_name );
134 135 136 137 138 139 140

VLC_API int vlc_stream_directory_Attach( stream_t** source,
                                         char const* module_name );
/**
 * @}
 */

141 142 143 144 145 146 147 148
/**
 * @}
 */

#ifdef __cplusplus
} /* extern "C" */
#endif
#endif /* include-guard */