1/*
2Copyright (c) 2012, Broadcom Europe Ltd
3All rights reserved.
4
5Redistribution and use in source and binary forms, with or without
6modification, are permitted provided that the following conditions are met:
7 * Redistributions of source code must retain the above copyright
8 notice, this list of conditions and the following disclaimer.
9 * Redistributions in binary form must reproduce the above copyright
10 notice, this list of conditions and the following disclaimer in the
11 documentation and/or other materials provided with the distribution.
12 * Neither the name of the copyright holder nor the
13 names of its contributors may be used to endorse or promote products
14 derived from this software without specific prior written permission.
15
16THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
17ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY
20DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
23ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26*/
27#ifndef VC_CONTAINERS_IO_H
28#define VC_CONTAINERS_IO_H
29
30/** \file containers_io.h
31 * Interface definition for the input / output abstraction layer used by container
32 * readers and writers */
33#include "containers/containers.h"
34
35#ifdef __cplusplus
36extern "C" {
37#endif
38
39/** \defgroup VcContainerIoApi Container I/O API */
40/* @{ */
41
42/** Container io opening mode.
43 * This is used to specify whether a reader or writer is requested.
44 */
45typedef enum {
46 VC_CONTAINER_IO_MODE_READ = 0, /**< Container io opened in reading mode */
47 VC_CONTAINER_IO_MODE_WRITE = 1 /**< Container io opened in writing mode */
48} VC_CONTAINER_IO_MODE_T;
49
50/** \name Container I/O Capabilities
51 * The following flags are exported by container i/o modules to describe their capabilities */
52/* @{ */
53/** Type definition for container I/O capabilities */
54typedef uint32_t VC_CONTAINER_IO_CAPABILITIES_T;
55/** Seeking is not supported */
56#define VC_CONTAINER_IO_CAPS_CANT_SEEK 0x1
57/** Seeking is slow and should be avoided */
58#define VC_CONTAINER_IO_CAPS_SEEK_SLOW 0x2
59/** The I/O doesn't provide any caching of the data */
60#define VC_CONTAINER_IO_CAPS_NO_CACHING 0x4
61/* @} */
62
63/** Container Input / Output Context.
64 * This structure defines the context for a container io instance */
65struct VC_CONTAINER_IO_T
66{
67 /** Pointer to information private to the container io instance */
68 struct VC_CONTAINER_IO_PRIVATE_T *priv;
69
70 /** Pointer to information private to the container io module */
71 struct VC_CONTAINER_IO_MODULE_T *module;
72
73 /** Uniform Resource Identifier for the stream to open.
74 * This is a string encoded in UTF-8 which follows the syntax defined in
75 * RFC2396 (http://tools.ietf.org/html/rfc2396). */
76 char *uri;
77
78 /** Pre-parsed URI */
79 struct VC_URI_PARTS_T *uri_parts;
80
81 /** Current offset into the i/o stream */
82 int64_t offset;
83
84 /** Current size of the i/o stream (0 if unknown). This size might grow during the
85 * lifetime of the i/o instance (for instance when doing progressive download). */
86 int64_t size;
87
88 /** Capabilities of the i/o stream */
89 VC_CONTAINER_IO_CAPABILITIES_T capabilities;
90
91 /** Status of the i/o stream */
92 VC_CONTAINER_STATUS_T status;
93
94 /** Maximum size allowed for this i/o stream (0 if unknown). This is used during writing
95 * to limit the size of the stream to below this value. */
96 int64_t max_size;
97
98 /** \note the following list of function pointers should not be used directly.
99 * They defines the interface for implementing container io modules and are filled in
100 * by the container modules themselves. */
101
102 /** \private
103 * Function pointer to close and free all resources allocated by a
104 * container io module */
105 VC_CONTAINER_STATUS_T (*pf_close)(struct VC_CONTAINER_IO_T *io);
106
107 /** \private
108 * Function pointer to read or skip data from container io module */
109 size_t (*pf_read)(struct VC_CONTAINER_IO_T *io, void *buffer, size_t size);
110
111 /** \private
112 * Function pointer to write data to a container io module */
113 size_t (*pf_write)(struct VC_CONTAINER_IO_T *io, const void *buffer, size_t size);
114
115 /** \private
116 * Function pointer to seek into a container io module */
117 VC_CONTAINER_STATUS_T (*pf_seek)(struct VC_CONTAINER_IO_T *io, int64_t offset);
118
119 /** \private
120 * Function pointer to perform a control operation on a container io module */
121 VC_CONTAINER_STATUS_T (*pf_control)(struct VC_CONTAINER_IO_T *io,
122 VC_CONTAINER_CONTROL_T operation, va_list args);
123
124};
125
126/** Opens an i/o stream pointed to by a URI.
127 * This will create an instance of the container i/o module.
128 *
129 * \param uri Uniform Resource Identifier pointing to the multimedia container
130 * \param mode Mode in which the i/o stream will be opened
131 * \param status Returns the status of the operation
132 * \return If successful, this returns a pointer to the new instance
133 * of the i/o module. Returns NULL on failure.
134 */
135VC_CONTAINER_IO_T *vc_container_io_open( const char *uri, VC_CONTAINER_IO_MODE_T mode,
136 VC_CONTAINER_STATUS_T *status );
137
138/** Creates an empty i/o stream. The i/o function pointers will have to be set
139 * by the caller before the i/o gets used.
140 * This will create an instance of the container i/o module.
141 *
142 * \param uri Uniform Resource Identifier pointing to the multimedia container
143 * \param mode Mode in which the i/o stream will be opened
144 * \param capabilities Flags indicating the capabilities of the i/o
145 * \param status Returns the status of the operation
146 * \return If successful, this returns a pointer to the new instance
147 * of the i/o module. Returns NULL on failure.
148 */
149VC_CONTAINER_IO_T *vc_container_io_create( const char *uri, VC_CONTAINER_IO_MODE_T mode,
150 VC_CONTAINER_IO_CAPABILITIES_T capabilities,
151 VC_CONTAINER_STATUS_T *p_status );
152
153/** Closes an instance of a container i/o module.
154 * \param context Pointer to the VC_CONTAINER_IO_T context of the instance to close
155 * \return VC_CONTAINER_SUCCESS on success.
156 */
157VC_CONTAINER_STATUS_T vc_container_io_close( VC_CONTAINER_IO_T *context );
158
159/** Read data from an i/o stream without advancing the read position within the stream.
160 * \param context Pointer to the VC_CONTAINER_IO_T instance to use
161 * \param buffer Pointer to the buffer where the data will be read
162 * \param size Number of bytes to read
163 * \return The size of the data actually read.
164 */
165size_t vc_container_io_peek(VC_CONTAINER_IO_T *context, void *buffer, size_t size);
166
167/** Read data from an i/o stream.
168 * \param context Pointer to the VC_CONTAINER_IO_T instance to use
169 * \param buffer Pointer to the buffer where the data will be read
170 * \param size Number of bytes to read
171 * \return The size of the data actually read.
172 */
173size_t vc_container_io_read(VC_CONTAINER_IO_T *context, void *buffer, size_t size);
174
175/** Skip data in an i/o stream without reading it.
176 * \param context Pointer to the VC_CONTAINER_IO_T instance to use
177 * \param size Number of bytes to skip
178 * \return The size of the data actually skipped.
179 */
180size_t vc_container_io_skip(VC_CONTAINER_IO_T *context, size_t size);
181
182/** Write data to an i/o stream.
183 * \param context Pointer to the VC_CONTAINER_IO_T instance to use
184 * \param buffer Pointer to the buffer containing the data to write
185 * \param size Number of bytes to write
186 * \return The size of the data actually written.
187 */
188size_t vc_container_io_write(VC_CONTAINER_IO_T *context, const void *buffer, size_t size);
189
190/** Seek into an i/o stream.
191 * \param context Pointer to the VC_CONTAINER_IO_T instance to use
192 * \param offset Absolute file offset to seek to
193 * \return Status of the operation
194 */
195VC_CONTAINER_STATUS_T vc_container_io_seek(VC_CONTAINER_IO_T *context, int64_t offset);
196
197/** Perform control operation on an i/o stream (va_list).
198 * \param context Pointer to the VC_CONTAINER_IO_T instance to use
199 * \param operation Control operation to be performed
200 * \param args Additional arguments for the operation
201 * \return Status of the operation
202 */
203VC_CONTAINER_STATUS_T vc_container_io_control_list(VC_CONTAINER_IO_T *context,
204 VC_CONTAINER_CONTROL_T operation, va_list args);
205
206/** Perform control operation on an i/o stream (varargs).
207 * \param context Pointer to the VC_CONTAINER_IO_T instance to use
208 * \param operation Control operation to be performed
209 * \param ... Additional arguments for the operation
210 * \return Status of the operation
211 */
212VC_CONTAINER_STATUS_T vc_container_io_control(VC_CONTAINER_IO_T *context,
213 VC_CONTAINER_CONTROL_T operation, ...);
214
215/** Cache the pointed region of the i/o stream (from current position).
216 * This will allow future seeking into the specified region even on non-seekable streams.
217 * \param context Pointer to the VC_CONTAINER_IO_T instance to use
218 * \param size Size of the region to cache
219 * \return Status of the operation
220 */
221size_t vc_container_io_cache(VC_CONTAINER_IO_T *context, size_t size);
222
223/* @} */
224
225#ifdef __cplusplus
226}
227#endif
228
229#endif /* VC_CONTAINERS_HELPERS_H */
230