url.h File Reference

unbuffered private I/O API More...

#include "avio.h"
#include "libavformat/version.h"
#include "libavutil/dict.h"
#include "libavutil/log.h"

Go to the source code of this file.

Data Structures
struct	URLContext
struct	URLProtocol

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 */

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_open (URLContext **puc, const char *filename, int flags, const AVIOInterruptCB *int_cb, AVDictionary **options)
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_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. 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_write (URLContext *h, const unsigned char *buf, int size)
	Write size bytes from buf to the resource accessed by h. More...
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 (URLContext *h)
	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 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. More...
AVIODirEntry *	ff_alloc_dir_entry (void)
	Allocate directory entry with default values. More...
const AVClass *	ff_urlcontext_child_class_next (const AVClass *prev)
const URLProtocol **	ffurl_get_protocols (const char *whitelist, const char *blacklist)
	Construct a list of protocols matching a given whitelist and/or blacklist. More...

Variables
const AVClass	ffurl_context_class

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 33 of file url.h.

Referenced by url_find_protocol().

URL_PROTOCOL_FLAG_NETWORK

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

Definition at line 34 of file url.h.

Referenced by ffurl_closep(), and url_alloc_for_protocol().

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

puc	pointer to the location where, in case of success, the function puts the pointer to the created URLContext
flags	flags which control how the resource indicated by url is to be opened
int_cb	interrupt 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 290 of file avio.c.

Referenced by avio_check(), avio_open_dir(), avpriv_io_delete(), avpriv_io_move(), ff_rtsp_open_transport_ctx(), 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

options

A 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 166 of file avio.c.

Referenced by avio_check(), ff_rtsp_open_transport_ctx(), 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

puc	pointer to the location where, in case of success, the function puts the pointer to the created URLContext
flags	flags which control how the resource indicated by url is to be opened
int_cb	interrupt callback to use for the URLContext, may be NULL
options	A 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.
parent	An 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 307 of file avio.c.

Referenced by async_open(), cache_open(), concat_open(), crypto_open2(), ff_rtsp_open_transport_ctx(), ff_tls_open_underlying(), ffio_open_whitelist(), ffurl_open(), 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(), and tee_open().

ffurl_open()

int ffurl_open	(	URLContext **	puc,
		const char *	filename,
		int	flags,
		const AVIOInterruptCB *	int_cb,
		AVDictionary **	options
	)

Definition at line 355 of file avio.c.

ffurl_accept()

int ffurl_accept	(	URLContext *	s,
		URLContext **	c
	)

Accept an URLContext c on an URLContext s.

Parameters

s	server context
c	client context, must be unallocated.

Returns

>= 0 on success, ff_neterrno() on failure.

Definition at line 226 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

c	the client context

Returns

>= 0 on success or a negative value corresponding to an AVERROR code on failure

Definition at line 234 of file avio.c.

Referenced by avio_handshake(), and http_handshake().

ffurl_read()

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.

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 407 of file avio.c.

Referenced by cache_read(), concat_read(), crypto_read(), ff_rtmp_packet_read(), ff_rtmp_packet_read_internal(), ff_rtsp_open_transport_ctx(), ftp_getc(), ftp_read(), ftp_read_dir(), gnutls_url_pull(), gopher_read(), hls_read(), http_buf_read(), http_getc(), io_read_packet(), 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 414 of file avio.c.

Referenced by ff_rtsp_open_transport_ctx(), 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_write()

int ffurl_write	(	URLContext *	h,
		const unsigned char *	buf,
		int	size
	)

Write size bytes from buf to the resource accessed by h.

Returns

the number of bytes actually written, or a negative value corresponding to an AVERROR code in case of failure

Definition at line 421 of file avio.c.

Referenced by crypto_close(), crypto_write(), ff_rtmp_packet_write(), ff_rtp_check_and_send_back_rr(), ff_rtp_send_punch_packets(), ff_rtp_send_rtcp_feedback(), ff_rtsp_open_transport_ctx(), ff_rtsp_tcp_write_packet(), ftp_send_command(), ftp_write(), gnutls_url_push(), gopher_write(), http_connect(), http_shutdown(), http_write(), http_write_reply(), icecast_write(), io_write_packet(), ism_write(), md5_close(), prompeg_write_fec(), rtmp_handshake(), rtmp_send_hs_packet(), rtmp_server_handshake(), rtmpe_write(), rtp_write(), rtsp_send_reply(), sap_write_close(), sap_write_packet(), send_command_packet(), srtp_write(), tee_write(), tls_client_handshake(), tls_client_handshake_loop(), tls_shutdown_client(), tls_write(), tls_write_callback(), tls_write_cb(), and url_bio_bwrite().

ffurl_seek()

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.

Parameters

pos	specifies the new position to set
whence	specifies 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 434 of file avio.c.

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

ffurl_closep()

int ffurl_closep

(

URLContext **

h

)

Close the resource accessed by the URLContext h, and free the memory used by it.

Also set the URLContext pointer to NULL.

Returns

a negative value if an error condition occurred, 0 otherwise

Definition at line 444 of file avio.c.

Referenced by ffurl_close(), ftp_abort(), ftp_close_both_connections(), ftp_close_data_connection(), ftp_close_dir(), ftp_open_dir(), http_accept(), http_buf_read(), http_close(), http_open_cnx(), mmsh_close(), prompeg_close(), prompeg_open(), rtp_close(), rtp_open(), and tee_close().

ffurl_close()

int ffurl_close

(

URLContext *

h

)

Definition at line 467 of file avio.c.

Referenced by async_close(), async_open(), avio_check(), avio_close(), avio_close_dir(), avio_open_dir(), avpriv_io_delete(), avpriv_io_move(), cache_close(), concat_close(), concat_open(), crypto_close(), ff_rtp_chain_mux_open(), ff_rtsp_open_transport_ctx(), ff_rtsp_undo_setup(), ff_tls_close(), ffio_open_whitelist(), ffurl_open_whitelist(), gopher_close(), hls_close(), hls_read(), http_seek_internal(), icecast_close(), ism_flush(), ism_free(), ism_seek(), md5_close(), mms_close(), mmsh_open_internal(), rtmp_calc_swfhash(), rtmp_close(), rtmp_http_close(), rtmp_open(), rtmpe_close(), rtp_close(), rtp_open(), rtsp_listen(), sap_read_close(), sap_write_close(), srtp_close(), subfile_close(), subfile_open(), and tls_close().

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 611 of file avio.c.

Referenced by async_open(), and concat_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 626 of file avio.c.

Referenced by ff_rtsp_open_transport_ctx(), 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 633 of file avio.c.

Referenced by ff_rtsp_open_transport_ctx(), and srtp_get_multi_file_handle().

ffurl_get_short_seek()

int ffurl_get_short_seek

(

URLContext *

h

)

Return the current short seek threshold value for this URL.

Returns

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

Definition at line 650 of file avio.c.

Referenced by http_get_short_seek(), and io_short_seek().

ffurl_shutdown()

int ffurl_shutdown	(	URLContext *	h,
		int	flags
	)

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

Parameters

h	pointer to the resource
flags	flags 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 657 of file avio.c.

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

ff_check_interrupt()

int ff_check_interrupt

(

AVIOInterruptCB *

cb

)

Check if the user has requested to interrupt a blocking function associated with cb.

Definition at line 664 of file avio.c.

Referenced by async_check_interrupt(), avformat_find_stream_info(), dash_read_packet(), failing_write_packet(), ff_listen_connect(), ff_network_sleep_interruptible(), ff_network_wait_fd_timeout(), ff_poll_interrupt(), ff_rtsp_open_transport_ctx(), get_current_fragment(), hls_read(), libsrt_listen_connect(), libsrt_network_wait_fd_timeout(), read_data(), retry_transfer_wrapper(), and rtp_read().

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

h	media file context
uri	of the remote server

Returns

zero if no error.

Definition at line 438 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

h	media file context

Returns

the local port number

Definition at line 477 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

str	the buffer to fill with the url
size	the size of the str buffer
proto	the protocol identifier, if null, the separator after the identifier is left out, too
authorization	an optional authorization string, may be null. An empty string is treated the same as a null string.
hostname	the host name string
port	the port number, left out from the string if negative
fmt	a 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_url()

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.

Parameters

buf	the buffer where output absolute url is written
size	the size of buf
base	the base url, may be equal to buf.
rel	the new url, which is interpreted relative to base

Definition at line 80 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 149 of file url.c.

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

ff_urlcontext_child_class_next()

const AVClass* ff_urlcontext_child_class_next

(

const AVClass *

prev

)

Definition at line 74 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

whitelist	a comma-separated list of allowed protocol names or NULL. If this is a non-empty string, only protocols in this list will be included.
blacklist	a 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 109 of file protocols.c.

Referenced by url_find_protocol().

Variable Documentation

ffurl_context_class

const AVClass ffurl_context_class

Definition at line 63 of file avio.c.

Referenced by ff_avio_child_class_next(), and url_alloc_for_protocol().