1/*
2 *
3 * This file is part of Libav.
4 *
5 * Libav 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 * Libav 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 Libav; 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#if !FF_API_OLD_AVIO
35#define URL_PROTOCOL_FLAG_NESTED_SCHEME 1 /*< The protocol name can be the first part of a nested protocol scheme */
36#define URL_PROTOCOL_FLAG_NETWORK       2 /*< The protocol uses network */
37
38extern int (*url_interrupt_cb)(void);
39
40extern const AVClass ffurl_context_class;
41
42typedef struct URLContext {
43    const AVClass *av_class;    /**< information for av_log(). Set by url_open(). */
44    struct URLProtocol *prot;
45    void *priv_data;
46    char *filename;             /**< specified URL */
47    int flags;
48    int max_packet_size;        /**< if non zero, the stream is packetized with this max packet size */
49    int is_streamed;            /**< true if streamed (no seek possible), default = false */
50    int is_connected;
51    AVIOInterruptCB interrupt_callback;
52} URLContext;
53
54typedef 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_read)( URLContext *h, unsigned char *buf, int size);
64    int     (*url_write)(URLContext *h, const unsigned char *buf, int size);
65    int64_t (*url_seek)( URLContext *h, int64_t pos, int whence);
66    int     (*url_close)(URLContext *h);
67    struct URLProtocol *next;
68    int (*url_read_pause)(URLContext *h, int pause);
69    int64_t (*url_read_seek)(URLContext *h, int stream_index,
70                             int64_t timestamp, int flags);
71    int (*url_get_file_handle)(URLContext *h);
72    int priv_data_size;
73    const AVClass *priv_data_class;
74    int flags;
75    int (*url_check)(URLContext *h, int mask);
76} URLProtocol;
77#endif
78
79/**
80 * Create a URLContext for accessing to the resource indicated by
81 * url, but do not initiate the connection yet.
82 *
83 * @param puc pointer to the location where, in case of success, the
84 * function puts the pointer to the created URLContext
85 * @param flags flags which control how the resource indicated by url
86 * is to be opened
87 * @param int_cb interrupt callback to use for the URLContext, may be
88 * NULL
89 * @return 0 in case of success, a negative value corresponding to an
90 * AVERROR code in case of failure
91 */
92int ffurl_alloc(URLContext **puc, const char *filename, int flags,
93                const AVIOInterruptCB *int_cb);
94
95/**
96 * Connect an URLContext that has been allocated by ffurl_alloc
97 *
98 * @param options  A dictionary filled with options for nested protocols,
99 * i.e. it will be passed to url_open2() for protocols implementing it.
100 * This parameter will be destroyed and replaced with a dict containing options
101 * that were not found. May be NULL.
102 */
103int ffurl_connect(URLContext *uc, AVDictionary **options);
104
105/**
106 * Create an URLContext for accessing to the resource indicated by
107 * url, and open it.
108 *
109 * @param puc pointer to the location where, in case of success, the
110 * function puts the pointer to the created URLContext
111 * @param flags flags which control how the resource indicated by url
112 * is to be opened
113 * @param int_cb interrupt callback to use for the URLContext, may be
114 * NULL
115 * @param options  A dictionary filled with protocol-private options. On return
116 * this parameter will be destroyed and replaced with a dict containing options
117 * that were not found. May be NULL.
118 * @return 0 in case of success, a negative value corresponding to an
119 * AVERROR code in case of failure
120 */
121int ffurl_open(URLContext **puc, const char *filename, int flags,
122               const AVIOInterruptCB *int_cb, AVDictionary **options);
123
124/**
125 * Read up to size bytes from the resource accessed by h, and store
126 * the read bytes in buf.
127 *
128 * @return The number of bytes actually read, or a negative value
129 * corresponding to an AVERROR code in case of error. A value of zero
130 * indicates that it is not possible to read more from the accessed
131 * resource (except if the value of the size argument is also zero).
132 */
133int ffurl_read(URLContext *h, unsigned char *buf, int size);
134
135/**
136 * Read as many bytes as possible (up to size), calling the
137 * read function multiple times if necessary.
138 * This makes special short-read handling in applications
139 * unnecessary, if the return value is < size then it is
140 * certain there was either an error or the end of file was reached.
141 */
142int ffurl_read_complete(URLContext *h, unsigned char *buf, int size);
143
144/**
145 * Write size bytes from buf to the resource accessed by h.
146 *
147 * @return the number of bytes actually written, or a negative value
148 * corresponding to an AVERROR code in case of failure
149 */
150int ffurl_write(URLContext *h, const unsigned char *buf, int size);
151
152/**
153 * Change the position that will be used by the next read/write
154 * operation on the resource accessed by h.
155 *
156 * @param pos specifies the new position to set
157 * @param whence specifies how pos should be interpreted, it must be
158 * one of SEEK_SET (seek from the beginning), SEEK_CUR (seek from the
159 * current position), SEEK_END (seek from the end), or AVSEEK_SIZE
160 * (return the filesize of the requested resource, pos is ignored).
161 * @return a negative value corresponding to an AVERROR code in case
162 * of failure, or the resulting file position, measured in bytes from
163 * the beginning of the file. You can use this feature together with
164 * SEEK_CUR to read the current file position.
165 */
166int64_t ffurl_seek(URLContext *h, int64_t pos, int whence);
167
168/**
169 * Close the resource accessed by the URLContext h, and free the
170 * memory used by it.
171 *
172 * @return a negative value if an error condition occurred, 0
173 * otherwise
174 */
175int ffurl_close(URLContext *h);
176
177/**
178 * Return the filesize of the resource accessed by h, AVERROR(ENOSYS)
179 * if the operation is not supported by h, or another negative value
180 * corresponding to an AVERROR error code in case of failure.
181 */
182int64_t ffurl_size(URLContext *h);
183
184/**
185 * Return the file descriptor associated with this URL. For RTP, this
186 * will return only the RTP file descriptor, not the RTCP file descriptor.
187 *
188 * @return the file descriptor associated with this URL, or <0 on error.
189 */
190int ffurl_get_file_handle(URLContext *h);
191
192/**
193 * Register the URLProtocol protocol.
194 *
195 * @param size the size of the URLProtocol struct referenced
196 */
197int ffurl_register_protocol(URLProtocol *protocol, int size);
198
199/**
200 * Check if the user has requested to interrup a blocking function
201 * associated with cb.
202 */
203int ff_check_interrupt(AVIOInterruptCB *cb);
204
205/**
206 * Iterate over all available protocols.
207 *
208 * @param prev result of the previous call to this functions or NULL.
209 */
210URLProtocol *ffurl_protocol_next(URLProtocol *prev);
211
212/* udp.c */
213int ff_udp_set_remote_url(URLContext *h, const char *uri);
214int ff_udp_get_local_port(URLContext *h);
215
216#endif /* AVFORMAT_URL_H */
217