vlc_stream.h 10 KB
Newer Older
1
/*****************************************************************************
2
 * vlc_stream.h: Stream (between access and demux) descriptor and methods
3
 *****************************************************************************
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
4
 * Copyright (C) 1999-2004 VLC authors and VideoLAN
5
 * $Id$
6 7 8
 *
 * Authors: Laurent Aimar <fenrir@via.ecp.fr>
 *
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
9 10 11
 * 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
12 13 14 15
 * (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
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
16 17
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
18
 *
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
19 20 21
 * 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.
22 23
 *****************************************************************************/

24 25
#ifndef VLC_STREAM_H
#define VLC_STREAM_H 1
26

Clément Stenac's avatar
Clément Stenac committed
27 28
#include <vlc_block.h>

29 30 31 32
# ifdef __cplusplus
extern "C" {
# endif

33 34
/**
 * \defgroup stream Stream
35 36
 * \ingroup input
 * Buffered input byte streams
37
 * @{
38 39
 * \file
 * Byte streams and byte stream filter modules interface
40 41
 */

Laurent Aimar's avatar
Laurent Aimar committed
42 43 44 45 46 47 48 49
/**
 * stream_t definition
 */

struct stream_t
{
    VLC_COMMON_MEMBERS

50
    /* Module properties for stream filter */
Laurent Aimar's avatar
Laurent Aimar committed
51 52
    module_t    *p_module;

53
    char        *psz_url;
54

55 56
    /* Stream source for stream filter */
    stream_t *p_source;
Laurent Aimar's avatar
Laurent Aimar committed
57 58

    /* */
59
    ssize_t     (*pf_read)(stream_t *, void *, size_t);
60
    int         (*pf_readdir)( stream_t *, input_item_node_t * );
61
    int         (*pf_seek)(stream_t *, uint64_t);
62
    int         (*pf_control)( stream_t *, int i_query, va_list );
63

Laurent Aimar's avatar
Laurent Aimar committed
64
    /* Private data for module */
65
    void *p_sys;
Laurent Aimar's avatar
Laurent Aimar committed
66

67 68
    /* Weak link to parent input */
    input_thread_t *p_input;
Laurent Aimar's avatar
Laurent Aimar committed
69 70
};

71 72 73 74 75 76
/**
 * Possible commands to send to stream_Control() and stream_vaControl()
 */
enum stream_query_e
{
    /* capabilities */
77 78
    STREAM_CAN_SEEK,            /**< arg1= bool *   res=cannot fail*/
    STREAM_CAN_FASTSEEK,        /**< arg1= bool *   res=cannot fail*/
79 80
    STREAM_CAN_PAUSE,           /**< arg1= bool *   res=cannot fail*/
    STREAM_CAN_CONTROL_PACE,    /**< arg1= bool *   res=cannot fail*/
81
    /* */
82
    STREAM_GET_SIZE=6,          /**< arg1= uint64_t *     res=can fail */
83
    STREAM_IS_DIRECTORY,        /**< arg1= bool *, res=can fail*/
84

85
    /* */
86 87
    STREAM_GET_PTS_DELAY = 0x101,/**< arg1= int64_t* res=cannot fail */
    STREAM_GET_TITLE_INFO, /**< arg1=input_title_t*** arg2=int* res=can fail */
88 89
    STREAM_GET_TITLE,       /**< arg1=unsigned * res=can fail */
    STREAM_GET_SEEKPOINT,   /**< arg1=unsigned * res=can fail */
90
    STREAM_GET_META,        /**< arg1= vlc_meta_t *       res=can fail */
91
    STREAM_GET_CONTENT_TYPE,    /**< arg1= char **         res=can fail */
92
    STREAM_GET_SIGNAL,      /**< arg1=double *pf_quality, arg2=double *pf_strength   res=can fail */
93

94
    STREAM_SET_PAUSE_STATE = 0x200, /**< arg1= bool        res=can fail */
95 96
    STREAM_SET_TITLE,       /**< arg1= int          res=can fail */
    STREAM_SET_SEEKPOINT,   /**< arg1= int          res=can fail */
97

98
    /* XXX only data read through stream_Read/Block will be recorded */
99
    STREAM_SET_RECORD_STATE,     /**< arg1=bool, arg2=const char *psz_ext (if arg1 is true)  res=can fail */
100 101 102 103

    STREAM_SET_PRIVATE_ID_STATE = 0x1000, /* arg1= int i_private_data, bool b_selected    res=can fail */
    STREAM_SET_PRIVATE_ID_CA,             /* arg1= int i_program_number, uint16_t i_vpid, uint16_t i_apid1, uint16_t i_apid2, uint16_t i_apid3, uint8_t i_length, uint8_t *p_data */
    STREAM_GET_PRIVATE_ID_STATE,          /* arg1=int i_private_data arg2=bool *          res=can fail */
104
    STREAM_GET_PRIVATE_BLOCK, /**< arg1= block_t **b, arg2=bool *eof */
105 106
};

107 108 109 110 111 112 113 114 115 116 117 118 119
/**
 * Reads data from a byte stream.
 *
 * This function always waits for the requested number of bytes, unless a fatal
 * error is encountered or the end-of-stream is reached first.
 *
 * If the buffer is NULL, data is skipped instead of read. This is effectively
 * a relative forward seek, but it works even on non-seekable streams.
 *
 * \param buf start of buffer to read data into [OUT]
 * \param len number of bytes to read
 * \return the number of bytes read or a negative value on error.
 */
120
VLC_API ssize_t stream_Read(stream_t *, void *, size_t) VLC_USED;
121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137

/**
 * Peeks at data from a byte stream.
 *
 * This function buffers for the requested number of bytes, waiting if
 * necessary. Then it stores a pointer to the buffer. Unlike stream_Read()
 * or stream_Block(), this function does not modify the stream read offset.
 *
 * \note
 * The buffer remains valid until the next read/peek or seek operation on the
 * same stream. In case of error, the buffer address is undefined.
 *
 * \param bufp storage space for the buffer address [OUT]
 * \param len number of bytes to peek
 * \return the number of bytes actually available (shorter than requested if
 * the end-of-stream is reached), or a negative value on error.
 */
138
VLC_API ssize_t stream_Peek(stream_t *, const uint8_t **, size_t) VLC_USED;
139

140 141 142 143 144 145 146
/**
 * Tells the current stream position.
 *
 * @return the byte offset from the beginning of the stream (cannot fail)
 */
VLC_API uint64_t stream_Tell(const stream_t *) VLC_USED;

147 148 149 150 151 152 153 154
/**
 * Sets the current stream position.
 *
 * @param offset byte offset from the beginning of the stream
 * @return zero on success, a negative value on error
 */
VLC_API int stream_Seek(stream_t *, uint64_t offset) VLC_USED;

155 156 157
VLC_API int stream_vaControl( stream_t *s, int i_query, va_list args );
VLC_API void stream_Delete( stream_t *s );
VLC_API int stream_Control( stream_t *s, int i_query, ... );
158
VLC_API block_t * stream_Block( stream_t *s, size_t );
159
VLC_API char * stream_ReadLine( stream_t * );
160
VLC_API int stream_ReadDir( stream_t *, input_item_node_t * );
161

François Cartegnie's avatar
François Cartegnie committed
162 163 164 165 166
/**
 * Low level custom stream creation.
 */
VLC_API stream_t *stream_CustomNew(vlc_object_t *, void (*)(stream_t *));

167 168 169
/**
 * Get the size of the stream.
 */
170 171 172 173 174
VLC_USED static inline int stream_GetSize( stream_t *s, uint64_t *size )
{
    return stream_Control( s, STREAM_GET_SIZE, size );
}

175 176
static inline int64_t stream_Size( stream_t *s )
{
177
    uint64_t i_pos;
178

179 180
    if( stream_GetSize( s, &i_pos ) )
        return 0;
181 182
    if( i_pos >> 62 )
        return (int64_t)1 << 62;
183 184
    return i_pos;
}
185 186 187 188 189 190 191 192 193 194 195 196 197

/**
 * Get the Content-Type of a stream, or NULL if unknown.
 * Result must be free()'d.
 */
static inline char *stream_ContentType( stream_t *s )
{
    char *res;
    if( stream_Control( s, STREAM_GET_CONTENT_TYPE, &res ) )
        return NULL;
    return res;
}

198
/**
199 200 201 202 203 204 205
 * Create a stream from a memory buffer.
 *
 * \param obj parent VLC object
 * \param base start address of the memory buffer to read from
 * \param size size in bytes of the memory buffer
 * \param preserve if false, free(base) will be called when the stream is
 *                 destroyed; if true, the memory buffer is preserved
206
 */
207 208 209 210
VLC_API stream_t *stream_MemoryNew(vlc_object_t *obj, uint8_t *base,
                                   size_t size, bool preserve) VLC_USED;
#define stream_MemoryNew(a, b, c, d) \
        stream_MemoryNew(VLC_OBJECT(a), b, c, d)
211 212

/**
Pierre Ynard's avatar
Pierre Ynard committed
213
 * Create a stream_t reading from a URL.
214 215
 * You must delete it using stream_Delete.
 */
216
VLC_API stream_t * stream_UrlNew(vlc_object_t *p_this, const char *psz_url );
217 218
#define stream_UrlNew( a, b ) stream_UrlNew( VLC_OBJECT(a), b )

219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279
/**
 * \defgroup stream_fifo FIFO stream
 * In-memory anonymous pipe
  @{
 */

/**
 * Creates a FIFO stream.
 *
 * Creates a non-seekable byte stream object whose byte stream is generated
 * by another thread in the process. This is the LibVLC equivalent of an
 * anonymous pipe/FIFO.
 *
 * On the reader side, the normal stream functions are used,
 * e.g. stream_Read() and stream_Delete().
 *
 * The created stream object is automatically destroyed when both the reader
 * and the writer sides have been closed, with stream_Delete() and
 * vlc_stream_fifo_Close() respectively.
 *
 * \param parent parent VLC object for the stream
 * \return a stream object or NULL on memory error.
 */
VLC_API stream_t *vlc_stream_fifo_New(vlc_object_t *parent);

/**
 * Writes a block to a FIFO stream.
 *
 * \param s FIFO stream created by vlc_stream_fifo_New()
 * \param block data block to write to the stream
 * \return 0 on success. -1 if the reader end has already been closed
 * (errno is then set to EPIPE, and the block is deleted).
 *
 * \bug No congestion control is performed. If the reader end is not keeping
 * up with the writer end, buffers will accumulate in memory.
 */
VLC_API int vlc_stream_fifo_Queue(stream_t *s, block_t *block);

/**
 * Writes data to a FIFO stream.
 *
 * This is a convenience helper for vlc_stream_fifo_Queue().
 * \param s FIFO stream created by vlc_stream_fifo_New()
 * \param buf start address of data to write
 * \param len length of data to write in bytes
 * \return len on success, or -1 on error (errno is set accordingly)
 */
VLC_API ssize_t vlc_stream_fifo_Write(stream_t *s, const void *buf,
                                      size_t len);

/**
 * Terminates a FIFO stream.
 *
 * Marks the end of the FIFO stream and releases any underlying resources.
 * \param s FIFO stream created by vlc_stream_fifo_New()
 */
VLC_API void vlc_stream_fifo_Close(stream_t *s);

/**
 * @}
 */
280

281 282 283 284
/**
 * Try to add a stream filter to an open stream.
 * @return New stream to use, or NULL if the filter could not be added.
 **/
285
VLC_API stream_t* stream_FilterNew( stream_t *p_source, const char *psz_stream_filter );
286 287 288 289 290

/**
 * Default ReadDir implementation for stream Filter. This implementation just
 * forward the pf_readdir call to the p_source stream.
 */
291
VLC_API int stream_FilterDefaultReadDir( stream_t *s, input_item_node_t *p_node );
292 293 294 295 296 297 298

/**
 * Sets stream_FilterDefaultReadDir as the pf_readdir callback for this stream filter
 */
#define stream_FilterSetDefaultReadDir(p_stream) \
    p_stream->pf_readdir = stream_FilterDefaultReadDir;

299 300 301 302
/**
 * @}
 */

303 304 305 306
# ifdef __cplusplus
}
# endif

307
#endif