Merge commit '35c6ce76b107225a19eb33aea38857d2405882af'
[ffmpeg.git] / libavformat / url.h
1 /*
2  *
3  * This file is part of FFmpeg.
4  *
5  * FFmpeg is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU Lesser General Public
7  * License as published by the Free Software Foundation; either
8  * version 2.1 of the License, or (at your option) any later version.
9  *
10  * FFmpeg is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13  * Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public
16  * License along with FFmpeg; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
18  */
19
20 /**
21  * @file
22  * unbuffered private I/O API
23  */
24
25 #ifndef AVFORMAT_URL_H
26 #define AVFORMAT_URL_H
27
28 #include "avio.h"
29 #include "libavformat/version.h"
30
31 #include "libavutil/dict.h"
32 #include "libavutil/log.h"
33
34 #define URL_PROTOCOL_FLAG_NESTED_SCHEME 1 /*< The protocol name can be the first part of a nested protocol scheme */
35 #define URL_PROTOCOL_FLAG_NETWORK       2 /*< The protocol uses network */
36
37 extern const AVClass ffurl_context_class;
38
39 typedef struct URLContext {
40     const AVClass *av_class;    /**< information for av_log(). Set by url_open(). */
41     struct URLProtocol *prot;
42     void *priv_data;
43     char *filename;             /**< specified URL */
44     int flags;
45     int max_packet_size;        /**< if non zero, the stream is packetized with this max packet size */
46     int is_streamed;            /**< true if streamed (no seek possible), default = false */
47     int is_connected;
48     AVIOInterruptCB interrupt_callback;
49     int64_t rw_timeout;         /**< maximum time to wait for (network) read/write operation completion, in mcs */
50 } URLContext;
51
52 typedef struct URLProtocol {
53     const char *name;
54     int     (*url_open)( URLContext *h, const char *url, int flags);
55     /**
56      * This callback is to be used by protocols which open further nested
57      * protocols. options are then to be passed to ffurl_open()/ffurl_connect()
58      * for those nested protocols.
59      */
60     int     (*url_open2)(URLContext *h, const char *url, int flags, AVDictionary **options);
61
62     /**
63      * Read data from the protocol.
64      * If data is immediately available (even less than size), EOF is
65      * reached or an error occurs (including EINTR), return immediately.
66      * Otherwise:
67      * In non-blocking mode, return AVERROR(EAGAIN) immediately.
68      * In blocking mode, wait for data/EOF/error with a short timeout (0.1s),
69      * and return AVERROR(EAGAIN) on timeout.
70      * Checking interrupt_callback, looping on EINTR and EAGAIN and until
71      * enough data has been read is left to the calling function; see
72      * retry_transfer_wrapper in avio.c.
73      */
74     int     (*url_read)( URLContext *h, unsigned char *buf, int size);
75     int     (*url_write)(URLContext *h, const unsigned char *buf, int size);
76     int64_t (*url_seek)( URLContext *h, int64_t pos, int whence);
77     int     (*url_close)(URLContext *h);
78     struct URLProtocol *next;
79     int (*url_read_pause)(URLContext *h, int pause);
80     int64_t (*url_read_seek)(URLContext *h, int stream_index,
81                              int64_t timestamp, int flags);
82     int (*url_get_file_handle)(URLContext *h);
83     int (*url_get_multi_file_handle)(URLContext *h, int **handles,
84                                      int *numhandles);
85     int (*url_shutdown)(URLContext *h, int flags);
86     int priv_data_size;
87     const AVClass *priv_data_class;
88     int flags;
89     int (*url_check)(URLContext *h, int mask);
90 } URLProtocol;
91
92 /**
93  * Create a URLContext for accessing to the resource indicated by
94  * url, but do not initiate the connection yet.
95  *
96  * @param puc pointer to the location where, in case of success, the
97  * function puts the pointer to the created URLContext
98  * @param flags flags which control how the resource indicated by url
99  * is to be opened
100  * @param int_cb interrupt callback to use for the URLContext, may be
101  * NULL
102  * @return >= 0 in case of success, a negative value corresponding to an
103  * AVERROR code in case of failure
104  */
105 int ffurl_alloc(URLContext **puc, const char *filename, int flags,
106                 const AVIOInterruptCB *int_cb);
107
108 /**
109  * Connect an URLContext that has been allocated by ffurl_alloc
110  *
111  * @param options  A dictionary filled with options for nested protocols,
112  * i.e. it will be passed to url_open2() for protocols implementing it.
113  * This parameter will be destroyed and replaced with a dict containing options
114  * that were not found. May be NULL.
115  */
116 int ffurl_connect(URLContext *uc, AVDictionary **options);
117
118 /**
119  * Create an URLContext for accessing to the resource indicated by
120  * url, and open it.
121  *
122  * @param puc pointer to the location where, in case of success, the
123  * function puts the pointer to the created URLContext
124  * @param flags flags which control how the resource indicated by url
125  * is to be opened
126  * @param int_cb interrupt callback to use for the URLContext, may be
127  * NULL
128  * @param options  A dictionary filled with protocol-private options. On return
129  * this parameter will be destroyed and replaced with a dict containing options
130  * that were not found. May be NULL.
131  * @return >= 0 in case of success, a negative value corresponding to an
132  * AVERROR code in case of failure
133  */
134 int ffurl_open(URLContext **puc, const char *filename, int flags,
135                const AVIOInterruptCB *int_cb, AVDictionary **options);
136
137 /**
138  * Read up to size bytes from the resource accessed by h, and store
139  * the read bytes in buf.
140  *
141  * @return The number of bytes actually read, or a negative value
142  * corresponding to an AVERROR code in case of error. A value of zero
143  * indicates that it is not possible to read more from the accessed
144  * resource (except if the value of the size argument is also zero).
145  */
146 int ffurl_read(URLContext *h, unsigned char *buf, int size);
147
148 /**
149  * Read as many bytes as possible (up to size), calling the
150  * read function multiple times if necessary.
151  * This makes special short-read handling in applications
152  * unnecessary, if the return value is < size then it is
153  * certain there was either an error or the end of file was reached.
154  */
155 int ffurl_read_complete(URLContext *h, unsigned char *buf, int size);
156
157 /**
158  * Write size bytes from buf to the resource accessed by h.
159  *
160  * @return the number of bytes actually written, or a negative value
161  * corresponding to an AVERROR code in case of failure
162  */
163 int ffurl_write(URLContext *h, const unsigned char *buf, int size);
164
165 /**
166  * Change the position that will be used by the next read/write
167  * operation on the resource accessed by h.
168  *
169  * @param pos specifies the new position to set
170  * @param whence specifies how pos should be interpreted, it must be
171  * one of SEEK_SET (seek from the beginning), SEEK_CUR (seek from the
172  * current position), SEEK_END (seek from the end), or AVSEEK_SIZE
173  * (return the filesize of the requested resource, pos is ignored).
174  * @return a negative value corresponding to an AVERROR code in case
175  * of failure, or the resulting file position, measured in bytes from
176  * the beginning of the file. You can use this feature together with
177  * SEEK_CUR to read the current file position.
178  */
179 int64_t ffurl_seek(URLContext *h, int64_t pos, int whence);
180
181 /**
182  * Close the resource accessed by the URLContext h, and free the
183  * memory used by it. Also set the URLContext pointer to NULL.
184  *
185  * @return a negative value if an error condition occurred, 0
186  * otherwise
187  */
188 int ffurl_closep(URLContext **h);
189 int ffurl_close(URLContext *h);
190
191 /**
192  * Return the filesize of the resource accessed by h, AVERROR(ENOSYS)
193  * if the operation is not supported by h, or another negative value
194  * corresponding to an AVERROR error code in case of failure.
195  */
196 int64_t ffurl_size(URLContext *h);
197
198 /**
199  * Return the file descriptor associated with this URL. For RTP, this
200  * will return only the RTP file descriptor, not the RTCP file descriptor.
201  *
202  * @return the file descriptor associated with this URL, or <0 on error.
203  */
204 int ffurl_get_file_handle(URLContext *h);
205
206 /**
207  * Return the file descriptors associated with this URL.
208  *
209  * @return 0 on success or <0 on error.
210  */
211 int ffurl_get_multi_file_handle(URLContext *h, int **handles, int *numhandles);
212
213 /**
214  * Signal the URLContext that we are done reading or writing the stream.
215  *
216  * @param h pointer to the resource
217  * @param flags flags which control how the resource indicated by url
218  * is to be shutdown
219  *
220  * @return a negative value if an error condition occurred, 0
221  * otherwise
222  */
223 int ffurl_shutdown(URLContext *h, int flags);
224
225 /**
226  * Register the URLProtocol protocol.
227  */
228 int ffurl_register_protocol(URLProtocol *protocol);
229
230 /**
231  * Check if the user has requested to interrup a blocking function
232  * associated with cb.
233  */
234 int ff_check_interrupt(AVIOInterruptCB *cb);
235
236 /**
237  * Iterate over all available protocols.
238  *
239  * @param prev result of the previous call to this functions or NULL.
240  */
241 URLProtocol *ffurl_protocol_next(const URLProtocol *prev);
242
243 /* udp.c */
244 int ff_udp_set_remote_url(URLContext *h, const char *uri);
245 int ff_udp_get_local_port(URLContext *h);
246
247 /**
248  * Assemble a URL string from components. This is the reverse operation
249  * of av_url_split.
250  *
251  * Note, this requires networking to be initialized, so the caller must
252  * ensure ff_network_init has been called.
253  *
254  * @see av_url_split
255  *
256  * @param str the buffer to fill with the url
257  * @param size the size of the str buffer
258  * @param proto the protocol identifier, if null, the separator
259  *              after the identifier is left out, too
260  * @param authorization an optional authorization string, may be null.
261  *                      An empty string is treated the same as a null string.
262  * @param hostname the host name string
263  * @param port the port number, left out from the string if negative
264  * @param fmt a generic format string for everything to add after the
265  *            host/port, may be null
266  * @return the number of characters written to the destination buffer
267  */
268 int ff_url_join(char *str, int size, const char *proto,
269                 const char *authorization, const char *hostname,
270                 int port, const char *fmt, ...) av_printf_format(7, 8);
271
272 /**
273  * Convert a relative url into an absolute url, given a base url.
274  *
275  * @param buf the buffer where output absolute url is written
276  * @param size the size of buf
277  * @param base the base url, may be equal to buf.
278  * @param rel the new url, which is interpreted relative to base
279  */
280 void ff_make_absolute_url(char *buf, int size, const char *base,
281                           const char *rel);
282
283
284 #endif /* AVFORMAT_URL_H */