FFmpeg
url.h
Go to the documentation of this file.
1 /*
2  * This file is part of FFmpeg.
3  *
4  * FFmpeg is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Lesser General Public
6  * License as published by the Free Software Foundation; either
7  * version 2.1 of the License, or (at your option) any later version.
8  *
9  * FFmpeg is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12  * Lesser General Public License for more details.
13  *
14  * You should have received a copy of the GNU Lesser General Public
15  * License along with FFmpeg; if not, write to the Free Software
16  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17  */
18 
19 /**
20  * @file
21  * unbuffered private I/O API
22  */
23 
24 #ifndef AVFORMAT_URL_H
25 #define AVFORMAT_URL_H
26 
27 #include "avio.h"
28 #include "libavformat/version.h"
29 
30 #include "libavutil/dict.h"
31 #include "libavutil/log.h"
32 
33 #define URL_PROTOCOL_FLAG_NESTED_SCHEME 1 /*< The protocol name can be the first part of a nested protocol scheme */
34 #define URL_PROTOCOL_FLAG_NETWORK 2 /*< The protocol uses network */
35 
36 extern const AVClass ffurl_context_class;
37 
38 typedef struct URLContext {
39  const AVClass *av_class; /**< information for av_log(). Set by url_open(). */
40  const struct URLProtocol *prot;
41  void *priv_data;
42  char *filename; /**< specified URL */
43  int flags;
44  int max_packet_size; /**< if non zero, the stream is packetized with this max packet size */
45  int is_streamed; /**< true if streamed (no seek possible), default = false */
48  int64_t rw_timeout; /**< maximum time to wait for (network) read/write operation completion, in mcs */
49  const char *protocol_whitelist;
50  const char *protocol_blacklist;
51  int min_packet_size; /**< if non zero, the stream is packetized with this min packet size */
52 } URLContext;
53 
54 typedef struct URLProtocol {
55  const char *name;
56  int (*url_open)( URLContext *h, const char *url, int flags);
57  /**
58  * This callback is to be used by protocols which open further nested
59  * protocols. options are then to be passed to ffurl_open()/ffurl_connect()
60  * for those nested protocols.
61  */
62  int (*url_open2)(URLContext *h, const char *url, int flags, AVDictionary **options);
63  int (*url_accept)(URLContext *s, URLContext **c);
64  int (*url_handshake)(URLContext *c);
65 
66  /**
67  * Read data from the protocol.
68  * If data is immediately available (even less than size), EOF is
69  * reached or an error occurs (including EINTR), return immediately.
70  * Otherwise:
71  * In non-blocking mode, return AVERROR(EAGAIN) immediately.
72  * In blocking mode, wait for data/EOF/error with a short timeout (0.1s),
73  * and return AVERROR(EAGAIN) on timeout.
74  * Checking interrupt_callback, looping on EINTR and EAGAIN and until
75  * enough data has been read is left to the calling function; see
76  * retry_transfer_wrapper in avio.c.
77  */
78  int (*url_read)( URLContext *h, unsigned char *buf, int size);
79  int (*url_write)(URLContext *h, const unsigned char *buf, int size);
80  int64_t (*url_seek)( URLContext *h, int64_t pos, int whence);
81  int (*url_close)(URLContext *h);
82  int (*url_read_pause)(URLContext *h, int pause);
83  int64_t (*url_read_seek)(URLContext *h, int stream_index,
84  int64_t timestamp, int flags);
85  int (*url_get_file_handle)(URLContext *h);
86  int (*url_get_multi_file_handle)(URLContext *h, int **handles,
87  int *numhandles);
88  int (*url_get_short_seek)(URLContext *h);
89  int (*url_shutdown)(URLContext *h, int flags);
92  int flags;
93  int (*url_check)(URLContext *h, int mask);
94  int (*url_open_dir)(URLContext *h);
95  int (*url_read_dir)(URLContext *h, AVIODirEntry **next);
96  int (*url_close_dir)(URLContext *h);
97  int (*url_delete)(URLContext *h);
98  int (*url_move)(URLContext *h_src, URLContext *h_dst);
99  const char *default_whitelist;
100 } URLProtocol;
101 
102 /**
103  * Create a URLContext for accessing to the resource indicated by
104  * url, but do not initiate the connection yet.
105  *
106  * @param puc pointer to the location where, in case of success, the
107  * function puts the pointer to the created URLContext
108  * @param flags flags which control how the resource indicated by url
109  * is to be opened
110  * @param int_cb interrupt callback to use for the URLContext, may be
111  * NULL
112  * @return >= 0 in case of success, a negative value corresponding to an
113  * AVERROR code in case of failure
114  */
115 int ffurl_alloc(URLContext **puc, const char *filename, int flags,
116  const AVIOInterruptCB *int_cb);
117 
118 /**
119  * Connect an URLContext that has been allocated by ffurl_alloc
120  *
121  * @param options A dictionary filled with options for nested protocols,
122  * i.e. it will be passed to url_open2() for protocols implementing it.
123  * This parameter will be destroyed and replaced with a dict containing options
124  * that were not found. May be NULL.
125  */
127 
128 /**
129  * Create an URLContext for accessing to the resource indicated by
130  * url, and open it.
131  *
132  * @param puc pointer to the location where, in case of success, the
133  * function puts the pointer to the created URLContext
134  * @param flags flags which control how the resource indicated by url
135  * is to be opened
136  * @param int_cb interrupt callback to use for the URLContext, may be
137  * NULL
138  * @param options A dictionary filled with protocol-private options. On return
139  * this parameter will be destroyed and replaced with a dict containing options
140  * that were not found. May be NULL.
141  * @param parent An enclosing URLContext, whose generic options should
142  * be applied to this URLContext as well.
143  * @return >= 0 in case of success, a negative value corresponding to an
144  * AVERROR code in case of failure
145  */
146 int ffurl_open_whitelist(URLContext **puc, const char *filename, int flags,
148  const char *whitelist, const char* blacklist,
149  URLContext *parent);
150 
151 int ffurl_open(URLContext **puc, const char *filename, int flags,
153 
154 /**
155  * Accept an URLContext c on an URLContext s
156  *
157  * @param s server context
158  * @param c client context, must be unallocated.
159  * @return >= 0 on success, ff_neterrno() on failure.
160  */
162 
163 /**
164  * Perform one step of the protocol handshake to accept a new client.
165  * See avio_handshake() for details.
166  * Implementations should try to return decreasing values.
167  * If the protocol uses an underlying protocol, the underlying handshake is
168  * usually the first step, and the return value can be:
169  * (largest value for this protocol) + (return value from other protocol)
170  *
171  * @param c the client context
172  * @return >= 0 on success or a negative value corresponding
173  * to an AVERROR code on failure
174  */
176 
177 /**
178  * Read up to size bytes from the resource accessed by h, and store
179  * the read bytes in buf.
180  *
181  * @return The number of bytes actually read, or a negative value
182  * corresponding to an AVERROR code in case of error. A value of zero
183  * indicates that it is not possible to read more from the accessed
184  * resource (except if the value of the size argument is also zero).
185  */
186 int ffurl_read(URLContext *h, unsigned char *buf, int size);
187 
188 /**
189  * Read as many bytes as possible (up to size), calling the
190  * read function multiple times if necessary.
191  * This makes special short-read handling in applications
192  * unnecessary, if the return value is < size then it is
193  * certain there was either an error or the end of file was reached.
194  */
195 int ffurl_read_complete(URLContext *h, unsigned char *buf, int size);
196 
197 /**
198  * Write size bytes from buf to the resource accessed by h.
199  *
200  * @return the number of bytes actually written, or a negative value
201  * corresponding to an AVERROR code in case of failure
202  */
203 int ffurl_write(URLContext *h, const unsigned char *buf, int size);
204 
205 /**
206  * Change the position that will be used by the next read/write
207  * operation on the resource accessed by h.
208  *
209  * @param pos specifies the new position to set
210  * @param whence specifies how pos should be interpreted, it must be
211  * one of SEEK_SET (seek from the beginning), SEEK_CUR (seek from the
212  * current position), SEEK_END (seek from the end), or AVSEEK_SIZE
213  * (return the filesize of the requested resource, pos is ignored).
214  * @return a negative value corresponding to an AVERROR code in case
215  * of failure, or the resulting file position, measured in bytes from
216  * the beginning of the file. You can use this feature together with
217  * SEEK_CUR to read the current file position.
218  */
219 int64_t ffurl_seek(URLContext *h, int64_t pos, int whence);
220 
221 /**
222  * Close the resource accessed by the URLContext h, and free the
223  * memory used by it. Also set the URLContext pointer to NULL.
224  *
225  * @return a negative value if an error condition occurred, 0
226  * otherwise
227  */
228 int ffurl_closep(URLContext **h);
229 int ffurl_close(URLContext *h);
230 
231 /**
232  * Return the filesize of the resource accessed by h, AVERROR(ENOSYS)
233  * if the operation is not supported by h, or another negative value
234  * corresponding to an AVERROR error code in case of failure.
235  */
236 int64_t ffurl_size(URLContext *h);
237 
238 /**
239  * Return the file descriptor associated with this URL. For RTP, this
240  * will return only the RTP file descriptor, not the RTCP file descriptor.
241  *
242  * @return the file descriptor associated with this URL, or <0 on error.
243  */
245 
246 /**
247  * Return the file descriptors associated with this URL.
248  *
249  * @return 0 on success or <0 on error.
250  */
251 int ffurl_get_multi_file_handle(URLContext *h, int **handles, int *numhandles);
252 
253 /**
254  * Return the current short seek threshold value for this URL.
255  *
256  * @return threshold (>0) on success or <=0 on error.
257  */
259 
260 /**
261  * Signal the URLContext that we are done reading or writing the stream.
262  *
263  * @param h pointer to the resource
264  * @param flags flags which control how the resource indicated by url
265  * is to be shutdown
266  *
267  * @return a negative value if an error condition occurred, 0
268  * otherwise
269  */
270 int ffurl_shutdown(URLContext *h, int flags);
271 
272 /**
273  * Check if the user has requested to interrupt a blocking function
274  * associated with cb.
275  */
277 
278 /* udp.c */
279 int ff_udp_set_remote_url(URLContext *h, const char *uri);
281 
282 /**
283  * Assemble a URL string from components. This is the reverse operation
284  * of av_url_split.
285  *
286  * Note, this requires networking to be initialized, so the caller must
287  * ensure ff_network_init has been called.
288  *
289  * @see av_url_split
290  *
291  * @param str the buffer to fill with the url
292  * @param size the size of the str buffer
293  * @param proto the protocol identifier, if null, the separator
294  * after the identifier is left out, too
295  * @param authorization an optional authorization string, may be null.
296  * An empty string is treated the same as a null string.
297  * @param hostname the host name string
298  * @param port the port number, left out from the string if negative
299  * @param fmt a generic format string for everything to add after the
300  * host/port, may be null
301  * @return the number of characters written to the destination buffer
302  */
303 int ff_url_join(char *str, int size, const char *proto,
304  const char *authorization, const char *hostname,
305  int port, const char *fmt, ...) av_printf_format(7, 8);
306 
307 /**
308  * Convert a relative url into an absolute url, given a base url.
309  *
310  * @param buf the buffer where output absolute url is written
311  * @param size the size of buf
312  * @param base the base url, may be equal to buf.
313  * @param rel the new url, which is interpreted relative to base
314  */
315 void ff_make_absolute_url(char *buf, int size, const char *base,
316  const char *rel);
317 
318 /**
319  * Allocate directory entry with default values.
320  *
321  * @return entry or NULL on error
322  */
324 
326 
327 /**
328  * Construct a list of protocols matching a given whitelist and/or blacklist.
329  *
330  * @param whitelist a comma-separated list of allowed protocol names or NULL. If
331  * this is a non-empty string, only protocols in this list will
332  * be included.
333  * @param blacklist a comma-separated list of forbidden protocol names or NULL.
334  * If this is a non-empty string, all protocols in this list
335  * will be excluded.
336  *
337  * @return a NULL-terminated array of matching protocols. The array must be
338  * freed by the caller.
339  */
340 const URLProtocol **ffurl_get_protocols(const char *whitelist,
341  const char *blacklist);
342 
343 #endif /* AVFORMAT_URL_H */
int ffurl_shutdown(URLContext *h, int flags)
Signal the URLContext that we are done reading or writing the stream.
Definition: avio.c:657
Buffered I/O operations.
const char * fmt
Definition: avisynth_c.h:861
int flags
Definition: url.h:92
const AVClass ffurl_context_class
Definition: avio.c:63
int64_t ffurl_size(URLContext *h)
Return the filesize of the resource accessed by h, AVERROR(ENOSYS) if the operation is not supported ...
Definition: avio.c:611
int is_streamed
true if streamed (no seek possible), default = false
Definition: url.h:45
AVIOInterruptCB interrupt_callback
Definition: url.h:47
Describes single entry of the directory.
Definition: avio.h:86
int64_t rw_timeout
maximum time to wait for (network) read/write operation completion, in mcs
Definition: url.h:48
const URLProtocol ** ffurl_get_protocols(const char *whitelist, const char *blacklist)
Construct a list of protocols matching a given whitelist and/or blacklist.
Definition: protocols.c:110
int flags
Definition: url.h:43
int ffurl_get_multi_file_handle(URLContext *h, int **handles, int *numhandles)
Return the file descriptors associated with this URL.
Definition: avio.c:633
uint8_t base
Definition: vp3data.h:202
const AVClass * priv_data_class
Definition: url.h:91
int ffurl_write(URLContext *h, const unsigned char *buf, int size)
Write size bytes from buf to the resource accessed by h.
Definition: avio.c:421
Public dictionary API.
static double cb(void *priv, double x, double y)
Definition: vf_geq.c:112
Undefined Behavior In the C some operations are like signed integer dereferencing freed accessing outside allocated Undefined Behavior must not occur in a C it is not safe even if the output of undefined operations is unused The unsafety may seem nit picking but Optimizing compilers have in fact optimized code on the assumption that no undefined Behavior occurs Optimizing code based on wrong assumptions can and has in some cases lead to effects beyond the output of computations The signed integer overflow problem in speed critical code Code which is highly optimized and works with signed integers sometimes has the problem that often the output of the computation does not c
Definition: undefined.txt:32
int ff_url_join(char *str, int size, const char *proto, const char *authorization, const char *hostname, int port, const char *fmt,...) av_printf_format(7
Assemble a URL string from components.
ptrdiff_t size
Definition: opengl_enc.c:100
Callback for checking whether to abort blocking functions.
Definition: avio.h:58
int ffurl_open(URLContext **puc, const char *filename, int flags, const AVIOInterruptCB *int_cb, AVDictionary **options)
Definition: avio.c:355
const AVIOInterruptCB int_cb
Definition: ffmpeg.c:481
int ffurl_read_complete(URLContext *h, unsigned char *buf, int size)
Read as many bytes as possible (up to size), calling the read function multiple times if necessary...
Definition: avio.c:414
static const uint16_t mask[17]
Definition: lzw.c:38
const char * protocol_whitelist
Definition: url.h:49
int ff_check_interrupt(AVIOInterruptCB *cb)
Check if the user has requested to interrupt a blocking function associated with cb.
Definition: avio.c:664
int ff_udp_set_remote_url(URLContext *h, const char *uri)
If no filename is given to av_open_input_file because you want to get the local port first...
Definition: udp.c:400
int ffurl_read(URLContext *h, unsigned char *buf, int size)
Read up to size bytes from the resource accessed by h, and store the read bytes in buf...
Definition: avio.c:407
#define av_printf_format(fmtpos, attrpos)
Definition: attributes.h:155
AVIODirEntry * ff_alloc_dir_entry(void)
Allocate directory entry with default values.
Definition: url.c:149
int ffurl_connect(URLContext *uc, AVDictionary **options)
Connect an URLContext that has been allocated by ffurl_alloc.
Definition: avio.c:166
#define s(width, name)
Definition: cbs_vp9.c:257
Libavformat version macros.
int ffurl_get_file_handle(URLContext *h)
Return the file descriptor associated with this URL.
Definition: avio.c:626
int is_connected
Definition: url.h:46
int ffurl_open_whitelist(URLContext **puc, const char *filename, int flags, const AVIOInterruptCB *int_cb, AVDictionary **options, const char *whitelist, const char *blacklist, URLContext *parent)
Create an URLContext for accessing to the resource indicated by url, and open it. ...
Definition: avio.c:307
int ffurl_get_short_seek(URLContext *h)
Return the current short seek threshold value for this URL.
Definition: avio.c:650
int ff_udp_get_local_port(URLContext *h)
Return the local port used by the UDP connection.
Definition: udp.c:439
const char * protocol_blacklist
Definition: url.h:50
const char * default_whitelist
Definition: url.h:99
void * buf
Definition: avisynth_c.h:766
Definition: url.h:38
Describe the class of an AVClass context structure.
Definition: log.h:67
void * priv_data
Definition: url.h:41
int ffurl_alloc(URLContext **puc, const char *filename, int flags, const AVIOInterruptCB *int_cb)
Create a URLContext for accessing to the resource indicated by url, but do not initiate the connectio...
Definition: avio.c:290
const char * name
Definition: url.h:55
int64_t ffurl_seek(URLContext *h, int64_t pos, int whence)
Change the position that will be used by the next read/write operation on the resource accessed by h...
Definition: avio.c:434
const AVClass * av_class
information for av_log().
Definition: url.h:39
int ffurl_close(URLContext *h)
Definition: avio.c:467
int
const OptionDef options[]
Definition: ffmpeg_opt.c:3364
const struct URLProtocol * prot
Definition: url.h:40
char * filename
specified URL
Definition: url.h:42
int ffurl_handshake(URLContext *c)
Perform one step of the protocol handshake to accept a new client.
Definition: avio.c:234
int void ff_make_absolute_url(char *buf, int size, const char *base, const char *rel)
Convert a relative url into an absolute url, given a base url.
Definition: url.c:80
int ffurl_accept(URLContext *s, URLContext **c)
Accept an URLContext c on an URLContext s.
Definition: avio.c:226
int max_packet_size
if non zero, the stream is packetized with this max packet size
Definition: url.h:44
int min_packet_size
if non zero, the stream is packetized with this min packet size
Definition: url.h:51
int priv_data_size
Definition: url.h:90
int ffurl_closep(URLContext **h)
Close the resource accessed by the URLContext h, and free the memory used by it.
Definition: avio.c:444
const AVClass * ff_urlcontext_child_class_next(const AVClass *prev)
Definition: protocols.c:75