FFmpeg
Data Structures | Macros | Functions
url.h File Reference
#include "avio.h"
#include "libavutil/dict.h"
#include "libavutil/log.h"

Go to the source code of this file.

Data Structures

struct  URLContext
 
struct  URLProtocol
 
struct  URLComponents
 

Macros

#define URL_PROTOCOL_FLAG_NESTED_SCHEME   1 /*< The protocol name can be the first part of a nested protocol scheme */
 
#define URL_PROTOCOL_FLAG_NETWORK   2 /*< The protocol uses network */
 
#define url_component_end_scheme   authority
 
#define url_component_end_authority   userinfo
 
#define url_component_end_userinfo   host
 
#define url_component_end_host   port
 
#define url_component_end_port   path
 
#define url_component_end_path   query
 
#define url_component_end_query   fragment
 
#define url_component_end_fragment   end
 
#define url_component_end_authority_full   path
 
#define URL_COMPONENT_HAVE(uc, component)   ((uc).url_component_end_##component > (uc).component)
 

Functions

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 connection yet. More...
 
int ffurl_connect (URLContext *uc, AVDictionary **options)
 Connect an URLContext that has been allocated by ffurl_alloc. More...
 
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. More...
 
int ffurl_accept (URLContext *s, URLContext **c)
 Accept an URLContext c on an URLContext s. More...
 
int ffurl_handshake (URLContext *c)
 Perform one step of the protocol handshake to accept a new client. More...
 
int ffurl_read2 (void *urlcontext, uint8_t *buf, int size)
 
static int ffurl_read (URLContext *h, uint8_t *buf, int size)
 Read up to size bytes from the resource accessed by h, and store the read bytes in buf. More...
 
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. More...
 
int ffurl_write2 (void *urlcontext, const uint8_t *buf, int size)
 
static int ffurl_write (URLContext *h, const uint8_t *buf, int size)
 Write size bytes from buf to the resource accessed by h. More...
 
int64_t ffurl_seek2 (void *urlcontext, int64_t pos, int whence)
 
static 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. More...
 
int ffurl_closep (URLContext **h)
 Close the resource accessed by the URLContext h, and free the memory used by it. More...
 
int ffurl_close (URLContext *h)
 
int64_t ffurl_size (URLContext *h)
 Return the filesize of the resource accessed by h, AVERROR(ENOSYS) if the operation is not supported by h, or another negative value corresponding to an AVERROR error code in case of failure. More...
 
int ffurl_get_file_handle (URLContext *h)
 Return the file descriptor associated with this URL. More...
 
int ffurl_get_multi_file_handle (URLContext *h, int **handles, int *numhandles)
 Return the file descriptors associated with this URL. More...
 
int ffurl_get_short_seek (void *urlcontext)
 Return the current short seek threshold value for this URL. More...
 
int ffurl_shutdown (URLContext *h, int flags)
 Signal the URLContext that we are done reading or writing the stream. More...
 
int ff_check_interrupt (AVIOInterruptCB *cb)
 Check if the user has requested to interrupt a blocking function associated with cb. More...
 
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, then you must call this function to set the remote server address. More...
 
int ff_udp_get_local_port (URLContext *h)
 Return the local port used by the UDP connection. More...
 
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. More...
 
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. More...
 
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. More...
 
AVIODirEntryff_alloc_dir_entry (void)
 Allocate directory entry with default values. More...
 
const AVClassff_urlcontext_child_class_iterate (void **iter)
 
const URLProtocol ** ffurl_get_protocols (const char *whitelist, const char *blacklist)
 Construct a list of protocols matching a given whitelist and/or blacklist. More...
 
int ff_url_decompose (URLComponents *uc, const char *url, const char *end)
 Parse an URL to find the components. More...
 
int ffurl_move (const char *url_src, const char *url_dst)
 Move or rename a resource. More...
 
int ffurl_delete (const char *url)
 Delete a resource. More...
 

Detailed Description

unbuffered private I/O API

Definition in file url.h.

Macro Definition Documentation

◆ URL_PROTOCOL_FLAG_NESTED_SCHEME

#define URL_PROTOCOL_FLAG_NESTED_SCHEME   1 /*< The protocol name can be the first part of a nested protocol scheme */

Definition at line 32 of file url.h.

◆ URL_PROTOCOL_FLAG_NETWORK

#define URL_PROTOCOL_FLAG_NETWORK   2 /*< The protocol uses network */

Definition at line 33 of file url.h.

◆ url_component_end_scheme

#define url_component_end_scheme   authority

Definition at line 372 of file url.h.

◆ url_component_end_authority

#define url_component_end_authority   userinfo

Definition at line 373 of file url.h.

◆ url_component_end_userinfo

#define url_component_end_userinfo   host

Definition at line 374 of file url.h.

◆ url_component_end_host

#define url_component_end_host   port

Definition at line 375 of file url.h.

◆ url_component_end_port

#define url_component_end_port   path

Definition at line 376 of file url.h.

◆ url_component_end_path

#define url_component_end_path   query

Definition at line 377 of file url.h.

◆ url_component_end_query

#define url_component_end_query   fragment

Definition at line 378 of file url.h.

◆ url_component_end_fragment

#define url_component_end_fragment   end

Definition at line 379 of file url.h.

◆ url_component_end_authority_full

#define url_component_end_authority_full   path

Definition at line 380 of file url.h.

◆ URL_COMPONENT_HAVE

#define URL_COMPONENT_HAVE (   uc,
  component 
)    ((uc).url_component_end_##component > (uc).component)

Definition at line 382 of file url.h.

Function Documentation

◆ ffurl_alloc()

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 connection yet.

Parameters
pucpointer to the location where, in case of success, the function puts the pointer to the created URLContext
flagsflags which control how the resource indicated by url is to be opened
int_cbinterrupt callback to use for the URLContext, may be NULL
Returns
>= 0 in case of success, a negative value corresponding to an AVERROR code in case of failure

Definition at line 348 of file avio.c.

Referenced by avio_check(), avio_open_dir(), ffurl_delete(), ffurl_move(), ffurl_open_whitelist(), http_accept(), mmsh_open_internal(), rtmp_http_open(), and tcp_accept().

◆ ffurl_connect()

int ffurl_connect ( URLContext uc,
AVDictionary **  options 
)

Connect an URLContext that has been allocated by ffurl_alloc.

Parameters
optionsA dictionary filled with options for nested protocols, i.e. it will be passed to url_open2() for protocols implementing it. This parameter will be destroyed and replaced with a dict containing options that were not found. May be NULL.

Definition at line 204 of file avio.c.

Referenced by avio_check(), ffurl_open_whitelist(), mmsh_open_internal(), and rtmp_http_open().

◆ ffurl_open_whitelist()

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.

Parameters
pucpointer to the location where, in case of success, the function puts the pointer to the created URLContext
flagsflags which control how the resource indicated by url is to be opened
int_cbinterrupt callback to use for the URLContext, may be NULL
optionsA dictionary filled with protocol-private options. On return this parameter will be destroyed and replaced with a dict containing options that were not found. May be NULL.
parentAn enclosing URLContext, whose generic options should be applied to this URLContext as well.
Returns
>= 0 in case of success, a negative value corresponding to an AVERROR code in case of failure

Definition at line 361 of file avio.c.

Referenced by async_open(), cache_open(), crypto_open2(), ff_tls_open_underlying(), ffio_open_whitelist(), ftp_connect_control_connection(), ftp_connect_data_connection(), gopher_open(), hls_read(), http_listen(), http_open_cnx_internal(), icecast_open(), ism_flush(), ism_seek(), md5_close(), mms_open(), prompeg_open(), rtmp_calc_swfhash(), rtmp_open(), rtmpe_open(), rtp_open(), rtsp_listen(), rtsp_read_setup(), sap_read_header(), sap_write_header(), srtp_open(), subfile_open(), tee_open(), and translate_ipfs_to_http().

◆ ffurl_accept()

int ffurl_accept ( URLContext s,
URLContext **  c 
)

Accept an URLContext c on an URLContext s.

Parameters
sserver context
cclient context, must be unallocated.
Returns
>= 0 on success, ff_neterrno() on failure.

Definition at line 264 of file avio.c.

Referenced by avio_accept(), and http_accept().

◆ ffurl_handshake()

int ffurl_handshake ( URLContext c)

Perform one step of the protocol handshake to accept a new client.

See avio_handshake() for details. Implementations should try to return decreasing values. If the protocol uses an underlying protocol, the underlying handshake is usually the first step, and the return value can be: (largest value for this protocol) + (return value from other protocol)

Parameters
cthe client context
Returns
>= 0 on success or a negative value corresponding to an AVERROR code on failure

Definition at line 283 of file avio.c.

Referenced by avio_handshake(), and http_handshake().

◆ ffurl_read2()

int ffurl_read2 ( void *  urlcontext,
uint8_t *  buf,
int  size 
)

Definition at line 547 of file avio.c.

Referenced by ffio_fdopen(), ffio_geturlcontext(), and ffurl_read().

◆ ffurl_read()

static int ffurl_read ( URLContext h,
uint8_t *  buf,
int  size 
)
inlinestatic

Read up to size bytes from the resource accessed by h, and store the read bytes in buf.

Returns
The number of bytes actually read, or a negative value corresponding to an AVERROR code in case of error. A value of zero indicates that it is not possible to read more from the accessed resource (except if the value of the size argument is also zero).

Definition at line 181 of file url.h.

Referenced by cache_read(), concat_read(), crypto_read(), ff_rtmp_packet_read(), ff_rtmp_packet_read_internal(), ftp_getc(), ftp_read(), ftp_read_dir(), gnutls_url_pull(), gopher_read(), hls_read(), http_buf_read(), http_getc(), http_shutdown(), ipfs_read(), mbedtls_recv(), rtmp_http_open(), rtmp_http_read(), rtmp_http_send_cmd(), rtmp_write(), rtmpe_read(), sap_fetch_packet(), sap_read_header(), srtp_read(), subfile_read(), tls_client_handshake_loop(), tls_read(), tls_read_callback(), tls_read_cb(), url_bio_bread(), and wrapped_url_read().

◆ ffurl_read_complete()

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.

This makes special short-read handling in applications unnecessary, if the return value is < size then it is certain there was either an error or the end of file was reached.

Definition at line 556 of file avio.c.

Referenced by ff_rtsp_tcp_read_packet(), get_chunk_header(), get_http_header_data(), get_tcp_server_response(), read_data_packet(), read_line(), rtmp_calc_swfhash(), rtmp_handshake(), rtmp_packet_read_one_chunk(), rtmp_receive_hs_packet(), rtmp_server_handshake(), and rtsp_read_announce().

◆ ffurl_write2()

int ffurl_write2 ( void *  urlcontext,
const uint8_t *  buf,
int  size 
)

Definition at line 563 of file avio.c.

Referenced by ffio_fdopen(), and ffurl_write().

◆ ffurl_write()

static int ffurl_write ( URLContext h,
const uint8_t *  buf,
int  size 
)
inlinestatic

◆ ffurl_seek2()

int64_t ffurl_seek2 ( void *  urlcontext,
int64_t  pos,
int  whence 
)

Definition at line 576 of file avio.c.

Referenced by ffio_fdopen(), and ffurl_seek().

◆ ffurl_seek()

static int64_t ffurl_seek ( URLContext h,
int64_t  pos,
int  whence 
)
inlinestatic

Change the position that will be used by the next read/write operation on the resource accessed by h.

Parameters
posspecifies the new position to set
whencespecifies how pos should be interpreted, it must be one of SEEK_SET (seek from the beginning), SEEK_CUR (seek from the current position), SEEK_END (seek from the end), or AVSEEK_SIZE (return the filesize of the requested resource, pos is ignored).
Returns
a negative value corresponding to an AVERROR code in case of failure, or the resulting file position, measured in bytes from the beginning of the file. You can use this feature together with SEEK_CUR to read the current file position.

Definition at line 222 of file url.h.

Referenced by async_buffer_task(), cache_read(), cache_seek(), concat_read(), concat_seek(), crypto_seek(), ffurl_connect(), ffurl_size(), ipfs_seek(), ism_seek(), rtmp_calc_swfhash(), slave_seek(), and subfile_seek().

◆ ffurl_closep()

int ffurl_closep ( URLContext **  h)

◆ ffurl_close()

int ffurl_close ( URLContext h)

◆ ffurl_size()

int64_t ffurl_size ( URLContext h)

Return the filesize of the resource accessed by h, AVERROR(ENOSYS) if the operation is not supported by h, or another negative value corresponding to an AVERROR error code in case of failure.

Definition at line 798 of file avio.c.

Referenced by async_open().

◆ ffurl_get_file_handle()

int ffurl_get_file_handle ( URLContext h)

Return the file descriptor associated with this URL.

For RTP, this will return only the RTP file descriptor, not the RTCP file descriptor.

Returns
the file descriptor associated with this URL, or <0 on error.

Definition at line 813 of file avio.c.

Referenced by ftp_get_file_handle(), http_get_file_handle(), rtp_open(), rtsp_write_packet(), sap_fetch_packet(), sap_write_header(), srtp_get_file_handle(), and tls_get_file_handle().

◆ ffurl_get_multi_file_handle()

int ffurl_get_multi_file_handle ( URLContext h,
int **  handles,
int numhandles 
)

Return the file descriptors associated with this URL.

Returns
0 on success or <0 on error.

Definition at line 820 of file avio.c.

Referenced by srtp_get_multi_file_handle().

◆ ffurl_get_short_seek()

int ffurl_get_short_seek ( void *  urlcontext)

Return the current short seek threshold value for this URL.

Returns
threshold (>0) on success or <=0 on error.

Definition at line 837 of file avio.c.

Referenced by ffio_fdopen(), http_get_short_seek(), and tls_get_short_seek().

◆ ffurl_shutdown()

int ffurl_shutdown ( URLContext h,
int  flags 
)

Signal the URLContext that we are done reading or writing the stream.

Parameters
hpointer to the resource
flagsflags which control how the resource indicated by url is to be shutdown
Returns
a negative value if an error condition occurred, 0 otherwise

Definition at line 846 of file avio.c.

Referenced by dashenc_io_close(), ftp_shutdown(), and hlsenc_io_close().

◆ ff_check_interrupt()

int ff_check_interrupt ( AVIOInterruptCB cb)

◆ ff_udp_set_remote_url()

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, then you must call this function to set the remote server address.

url syntax: udp://host:port[?option=val...] option: 'ttl=n' : set the ttl value (for multicast only) 'localport=n' : set the local port 'pkt_size=n' : set max packet size 'reuse=1' : enable reusing the socket 'overrun_nonfatal=1': survive in case of circular buffer overrun

Parameters
hmedia file context
uriof the remote server
Returns
zero if no error.

Definition at line 425 of file udp.c.

Referenced by ff_rtp_set_remote_url(), and udp_open().

◆ ff_udp_get_local_port()

int ff_udp_get_local_port ( URLContext h)

Return the local port used by the UDP connection.

Parameters
hmedia file context
Returns
the local port number

Definition at line 464 of file udp.c.

Referenced by ff_rtp_get_local_rtp_port(), and rtp_open().

◆ ff_url_join()

int ff_url_join ( char *  str,
int  size,
const char *  proto,
const char *  authorization,
const char *  hostname,
int  port,
const char *  fmt,
  ... 
)

Assemble a URL string from components.

This is the reverse operation of av_url_split.

Note, this requires networking to be initialized, so the caller must ensure ff_network_init has been called.

See also
av_url_split
Parameters
strthe buffer to fill with the url
sizethe size of the str buffer
protothe protocol identifier, if null, the separator after the identifier is left out, too
authorizationan optional authorization string, may be null. An empty string is treated the same as a null string.
hostnamethe host name string
portthe port number, left out from the string if negative
fmta generic format string for everything to add after the host/port, may be null
Returns
the number of characters written to the destination buffer

◆ ff_make_absolute_url2()

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.

Parameters
bufthe buffer where output absolute url is written
sizethe size of buf
basethe base url, may be equal to buf.
relthe new url, which is interpreted relative to base
handle_dos_pathshandle DOS paths for file or unspecified protocol

Definition at line 195 of file url.c.

Referenced by ff_make_absolute_url(), and test().

◆ ff_make_absolute_url()

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.

Same as ff_make_absolute_url2 with handle_dos_paths being equal to HAVE_DOS_PATHS config variable.

Definition at line 321 of file url.c.

Referenced by add_file(), get_content_url(), new_init_section(), new_playlist(), open_input(), parse_location(), parse_playlist(), and test().

◆ ff_alloc_dir_entry()

AVIODirEntry* ff_alloc_dir_entry ( void  )

Allocate directory entry with default values.

Returns
entry or NULL on error

Definition at line 327 of file url.c.

Referenced by ftp_read_dir(), libsmbc_read_dir(), and libssh_read_dir().

◆ ff_urlcontext_child_class_iterate()

const AVClass* ff_urlcontext_child_class_iterate ( void **  iter)

Definition at line 84 of file protocols.c.

◆ ffurl_get_protocols()

const URLProtocol** ffurl_get_protocols ( const char *  whitelist,
const char *  blacklist 
)

Construct a list of protocols matching a given whitelist and/or blacklist.

Parameters
whitelista comma-separated list of allowed protocol names or NULL. If this is a non-empty string, only protocols in this list will be included.
blacklista comma-separated list of forbidden protocol names or NULL. If this is a non-empty string, all protocols in this list will be excluded.
Returns
a NULL-terminated array of matching protocols. The array must be freed by the caller.

Definition at line 124 of file protocols.c.

Referenced by url_find_protocol().

◆ ff_url_decompose()

int ff_url_decompose ( URLComponents uc,
const char *  url,
const char *  end 
)

Parse an URL to find the components.

Each component runs until the start of the next component, possibly including a mandatory delimiter.

Parameters
ucstructure to fill with pointers to the components.
urlURL to parse.
endend of the URL, or NULL to parse to the end of string.
Returns
>= 0 for success or an AVERROR code, especially if the URL is malformed.

Definition at line 91 of file url.c.

Referenced by ff_make_absolute_url2(), ff_match_url_ext(), and test_decompose().

◆ ffurl_move()

int ffurl_move ( const char *  url_src,
const char *  url_dst 
)

Move or rename a resource.

Note
url_src and url_dst should share the same protocol and authority.
Parameters
url_srcurl to resource to be moved
url_dstnew url to resource if the operation succeeded
Returns
>=0 on success or negative on error.

Definition at line 682 of file avio.c.

Referenced by ff_rename().

◆ ffurl_delete()

int ffurl_delete ( const char *  url)

Delete a resource.

Parameters
urlresource to be deleted.
Returns
>=0 on success or negative on error.

Definition at line 704 of file avio.c.

Referenced by dashenc_delete_file().