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_whitelist()
60  * or ffurl_connect() 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 /**
152  * Accept an URLContext c on an URLContext s
153  *
154  * @param s server context
155  * @param c client context, must be unallocated.
156  * @return >= 0 on success, ff_neterrno() on failure.
157  */
159 
160 /**
161  * Perform one step of the protocol handshake to accept a new client.
162  * See avio_handshake() for details.
163  * Implementations should try to return decreasing values.
164  * If the protocol uses an underlying protocol, the underlying handshake is
165  * usually the first step, and the return value can be:
166  * (largest value for this protocol) + (return value from other protocol)
167  *
168  * @param c the client context
169  * @return >= 0 on success or a negative value corresponding
170  * to an AVERROR code on failure
171  */
173 
174 /**
175  * Read up to size bytes from the resource accessed by h, and store
176  * the read bytes in buf.
177  *
178  * @return The number of bytes actually read, or a negative value
179  * corresponding to an AVERROR code in case of error. A value of zero
180  * indicates that it is not possible to read more from the accessed
181  * resource (except if the value of the size argument is also zero).
182  */
183 int ffurl_read(URLContext *h, unsigned char *buf, int size);
184 
185 /**
186  * Read as many bytes as possible (up to size), calling the
187  * read function multiple times if necessary.
188  * This makes special short-read handling in applications
189  * unnecessary, if the return value is < size then it is
190  * certain there was either an error or the end of file was reached.
191  */
192 int ffurl_read_complete(URLContext *h, unsigned char *buf, int size);
193 
194 /**
195  * Write size bytes from buf to the resource accessed by h.
196  *
197  * @return the number of bytes actually written, or a negative value
198  * corresponding to an AVERROR code in case of failure
199  */
200 int ffurl_write(URLContext *h, const unsigned char *buf, int size);
201 
202 /**
203  * Change the position that will be used by the next read/write
204  * operation on the resource accessed by h.
205  *
206  * @param pos specifies the new position to set
207  * @param whence specifies how pos should be interpreted, it must be
208  * one of SEEK_SET (seek from the beginning), SEEK_CUR (seek from the
209  * current position), SEEK_END (seek from the end), or AVSEEK_SIZE
210  * (return the filesize of the requested resource, pos is ignored).
211  * @return a negative value corresponding to an AVERROR code in case
212  * of failure, or the resulting file position, measured in bytes from
213  * the beginning of the file. You can use this feature together with
214  * SEEK_CUR to read the current file position.
215  */
216 int64_t ffurl_seek(URLContext *h, int64_t pos, int whence);
217 
218 /**
219  * Close the resource accessed by the URLContext h, and free the
220  * memory used by it. Also set the URLContext pointer to NULL.
221  *
222  * @return a negative value if an error condition occurred, 0
223  * otherwise
224  */
225 int ffurl_closep(URLContext **h);
226 int ffurl_close(URLContext *h);
227 
228 /**
229  * Return the filesize of the resource accessed by h, AVERROR(ENOSYS)
230  * if the operation is not supported by h, or another negative value
231  * corresponding to an AVERROR error code in case of failure.
232  */
233 int64_t ffurl_size(URLContext *h);
234 
235 /**
236  * Return the file descriptor associated with this URL. For RTP, this
237  * will return only the RTP file descriptor, not the RTCP file descriptor.
238  *
239  * @return the file descriptor associated with this URL, or <0 on error.
240  */
242 
243 /**
244  * Return the file descriptors associated with this URL.
245  *
246  * @return 0 on success or <0 on error.
247  */
248 int ffurl_get_multi_file_handle(URLContext *h, int **handles, int *numhandles);
249 
250 /**
251  * Return the current short seek threshold value for this URL.
252  *
253  * @return threshold (>0) on success or <=0 on error.
254  */
256 
257 /**
258  * Signal the URLContext that we are done reading or writing the stream.
259  *
260  * @param h pointer to the resource
261  * @param flags flags which control how the resource indicated by url
262  * is to be shutdown
263  *
264  * @return a negative value if an error condition occurred, 0
265  * otherwise
266  */
267 int ffurl_shutdown(URLContext *h, int flags);
268 
269 /**
270  * Check if the user has requested to interrupt a blocking function
271  * associated with cb.
272  */
274 
275 /* udp.c */
276 int ff_udp_set_remote_url(URLContext *h, const char *uri);
278 
279 /**
280  * Assemble a URL string from components. This is the reverse operation
281  * of av_url_split.
282  *
283  * Note, this requires networking to be initialized, so the caller must
284  * ensure ff_network_init has been called.
285  *
286  * @see av_url_split
287  *
288  * @param str the buffer to fill with the url
289  * @param size the size of the str buffer
290  * @param proto the protocol identifier, if null, the separator
291  * after the identifier is left out, too
292  * @param authorization an optional authorization string, may be null.
293  * An empty string is treated the same as a null string.
294  * @param hostname the host name string
295  * @param port the port number, left out from the string if negative
296  * @param fmt a generic format string for everything to add after the
297  * host/port, may be null
298  * @return the number of characters written to the destination buffer
299  */
300 int ff_url_join(char *str, int size, const char *proto,
301  const char *authorization, const char *hostname,
302  int port, const char *fmt, ...) av_printf_format(7, 8);
303 
304 /**
305  * Convert a relative url into an absolute url, given a base url.
306  *
307  * @param buf the buffer where output absolute url is written
308  * @param size the size of buf
309  * @param base the base url, may be equal to buf.
310  * @param rel the new url, which is interpreted relative to base
311  * @param handle_dos_paths handle DOS paths for file or unspecified protocol
312  */
313 int ff_make_absolute_url2(char *buf, int size, const char *base,
314  const char *rel, int handle_dos_paths);
315 
316 /**
317  * Convert a relative url into an absolute url, given a base url.
318  *
319  * Same as ff_make_absolute_url2 with handle_dos_paths being equal to
320  * HAVE_DOS_PATHS config variable.
321  */
322 int ff_make_absolute_url(char *buf, int size, const char *base,
323  const char *rel);
324 
325 /**
326  * Allocate directory entry with default values.
327  *
328  * @return entry or NULL on error
329  */
331 
332 #if FF_API_CHILD_CLASS_NEXT
333 const AVClass *ff_urlcontext_child_class_next(const AVClass *prev);
334 #endif
335 
336 const AVClass *ff_urlcontext_child_class_iterate(void **iter);
337 
338 /**
339  * Construct a list of protocols matching a given whitelist and/or blacklist.
340  *
341  * @param whitelist a comma-separated list of allowed protocol names or NULL. If
342  * this is a non-empty string, only protocols in this list will
343  * be included.
344  * @param blacklist a comma-separated list of forbidden protocol names or NULL.
345  * If this is a non-empty string, all protocols in this list
346  * will be excluded.
347  *
348  * @return a NULL-terminated array of matching protocols. The array must be
349  * freed by the caller.
350  */
351 const URLProtocol **ffurl_get_protocols(const char *whitelist,
352  const char *blacklist);
353 
354 typedef struct URLComponents {
355  const char *url; /**< whole URL, for reference */
356  const char *scheme; /**< possibly including lavf-specific options */
357  const char *authority; /**< "//" if it is a real URL */
358  const char *userinfo; /**< including final '@' if present */
359  const char *host;
360  const char *port; /**< including initial ':' if present */
361  const char *path;
362  const char *query; /**< including initial '?' if present */
363  const char *fragment; /**< including initial '#' if present */
364  const char *end;
365 } URLComponents;
366 
367 #define url_component_end_scheme authority
368 #define url_component_end_authority userinfo
369 #define url_component_end_userinfo host
370 #define url_component_end_host port
371 #define url_component_end_port path
372 #define url_component_end_path query
373 #define url_component_end_query fragment
374 #define url_component_end_fragment end
375 #define url_component_end_authority_full path
376 
377 #define URL_COMPONENT_HAVE(uc, component) \
378  ((uc).url_component_end_##component > (uc).component)
379 
380 /**
381  * Parse an URL to find the components.
382  *
383  * Each component runs until the start of the next component,
384  * possibly including a mandatory delimiter.
385  *
386  * @param uc structure to fill with pointers to the components.
387  * @param url URL to parse.
388  * @param end end of the URL, or NULL to parse to the end of string.
389  *
390  * @return >= 0 for success or an AVERROR code, especially if the URL is
391  * malformed.
392  */
393 int ff_url_decompose(URLComponents *uc, const char *url, const char *end);
394 
395 #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:651
Buffered I/O operations.
const char * url
whole URL, for reference
Definition: url.h:355
int flags
Definition: url.h:92
const AVClass ffurl_context_class
Definition: avio.c:64
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:605
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:139
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:627
uint8_t base
Definition: vp3data.h:141
const AVClass * priv_data_class
Definition: url.h:90
const char * end
Definition: url.h:364
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:415
Public dictionary API.
static double cb(void *priv, double x, double y)
Definition: vf_geq.c:215
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
const AVIOInterruptCB int_cb
Definition: ffmpeg.c:513
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:408
static const uint16_t mask[17]
Definition: lzw.c:38
const char * protocol_whitelist
Definition: url.h:49
unsigned int pos
Definition: spdifenc.c:412
int ff_check_interrupt(AVIOInterruptCB *cb)
Check if the user has requested to interrupt a blocking function associated with cb.
Definition: avio.c:658
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:406
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:401
const char * userinfo
including final &#39;@&#39; if present
Definition: url.h:358
#define av_printf_format(fmtpos, attrpos)
Definition: attributes.h:161
int 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:319
const char * authority
"//" if it is a real URL
Definition: url.h:357
const char * query
including initial &#39;?&#39; if present
Definition: url.h:362
AVIODirEntry * ff_alloc_dir_entry(void)
Allocate directory entry with default values.
Definition: url.c:325
int ffurl_connect(URLContext *uc, AVDictionary **options)
Connect an URLContext that has been allocated by ffurl_alloc.
Definition: avio.c:169
const AVClass * ff_urlcontext_child_class_iterate(void **iter)
Definition: protocols.c:99
#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:620
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:309
int ffurl_get_short_seek(URLContext *h)
Return the current short seek threshold value for this URL.
Definition: avio.c:644
int ff_udp_get_local_port(URLContext *h)
Return the local port used by the UDP connection.
Definition: udp.c:445
const char * protocol_blacklist
Definition: url.h:50
const char * default_whitelist
Definition: url.h:99
const char * host
Definition: url.h:359
Definition: url.h:38
Describe the class of an AVClass context structure.
Definition: log.h:67
void * priv_data
Definition: url.h:41
const char * port
including initial &#39;:&#39; if present
Definition: url.h:360
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:296
int ff_url_decompose(URLComponents *uc, const char *url, const char *end)
Parse an URL to find the components.
Definition: url.c:89
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:428
const AVClass * av_class
information for av_log().
Definition: url.h:39
const char * path
Definition: url.h:361
const char * scheme
possibly including lavf-specific options
Definition: url.h:356
int ffurl_close(URLContext *h)
Definition: avio.c:461
int
const OptionDef options[]
Definition: ffmpeg_opt.c:3427
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:237
int ffurl_accept(URLContext *s, URLContext **c)
Accept an URLContext c on an URLContext s.
Definition: avio.c:229
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:91
int ffurl_closep(URLContext **h)
Close the resource accessed by the URLContext h, and free the memory used by it.
Definition: avio.c:438
int int ff_make_absolute_url2(char *buf, int size, const char *base, const char *rel, int handle_dos_paths)
Convert a relative url into an absolute url, given a base url.
Definition: url.c:193
const char * fragment
including initial &#39;#&#39; if present
Definition: url.h:363