Commit | Line | Data |
---|---|---|
5652bb94 | 1 | /* |
5652bb94 AK |
2 | * This file is part of Libav. |
3 | * | |
4 | * Libav 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 | * Libav 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 Libav; 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" | |
b8404847 AK |
28 | #include "libavformat/version.h" |
29 | ||
ddffc2fd | 30 | #include "libavutil/dict.h" |
1dee0aca | 31 | #include "libavutil/log.h" |
ddffc2fd | 32 | |
b8404847 | 33 | #define URL_PROTOCOL_FLAG_NESTED_SCHEME 1 /*< The protocol name can be the first part of a nested protocol scheme */ |
32b83aee | 34 | #define URL_PROTOCOL_FLAG_NETWORK 2 /*< The protocol uses network */ |
5cec8971 | 35 | |
1dee0aca MS |
36 | extern const AVClass ffurl_context_class; |
37 | ||
c486dade AK |
38 | typedef struct URLContext { |
39 | const AVClass *av_class; /**< information for av_log(). Set by url_open(). */ | |
2758cded | 40 | const struct URLProtocol *prot; |
c486dade AK |
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 */ | |
46 | int is_connected; | |
6aa0b98f | 47 | AVIOInterruptCB interrupt_callback; |
c486dade | 48 | } URLContext; |
5593f031 AK |
49 | |
50 | typedef struct URLProtocol { | |
51 | const char *name; | |
52 | int (*url_open)( URLContext *h, const char *url, int flags); | |
ddffc2fd AK |
53 | /** |
54 | * This callback is to be used by protocols which open further nested | |
55 | * protocols. options are then to be passed to ffurl_open()/ffurl_connect() | |
56 | * for those nested protocols. | |
57 | */ | |
58 | int (*url_open2)(URLContext *h, const char *url, int flags, AVDictionary **options); | |
01b0ade6 NG |
59 | |
60 | /** | |
61 | * Read data from the protocol. | |
62 | * If data is immediately available (even less than size), EOF is | |
63 | * reached or an error occurs (including EINTR), return immediately. | |
64 | * Otherwise: | |
65 | * In non-blocking mode, return AVERROR(EAGAIN) immediately. | |
66 | * In blocking mode, wait for data/EOF/error with a short timeout (0.1s), | |
67 | * and return AVERROR(EAGAIN) on timeout. | |
68 | * Checking interrupt_callback, looping on EINTR and EAGAIN and until | |
69 | * enough data has been read is left to the calling function; see | |
70 | * retry_transfer_wrapper in avio.c. | |
71 | */ | |
5593f031 AK |
72 | int (*url_read)( URLContext *h, unsigned char *buf, int size); |
73 | int (*url_write)(URLContext *h, const unsigned char *buf, int size); | |
74 | int64_t (*url_seek)( URLContext *h, int64_t pos, int whence); | |
75 | int (*url_close)(URLContext *h); | |
5593f031 AK |
76 | int (*url_read_pause)(URLContext *h, int pause); |
77 | int64_t (*url_read_seek)(URLContext *h, int stream_index, | |
78 | int64_t timestamp, int flags); | |
79 | int (*url_get_file_handle)(URLContext *h); | |
d6b9da11 JO |
80 | int (*url_get_multi_file_handle)(URLContext *h, int **handles, |
81 | int *numhandles); | |
32d545e0 | 82 | int (*url_shutdown)(URLContext *h, int flags); |
5593f031 AK |
83 | int priv_data_size; |
84 | const AVClass *priv_data_class; | |
85 | int flags; | |
175389c8 | 86 | int (*url_check)(URLContext *h, int mask); |
5593f031 | 87 | } URLProtocol; |
5652bb94 AK |
88 | |
89 | /** | |
90 | * Create a URLContext for accessing to the resource indicated by | |
91 | * url, but do not initiate the connection yet. | |
92 | * | |
93 | * @param puc pointer to the location where, in case of success, the | |
94 | * function puts the pointer to the created URLContext | |
95 | * @param flags flags which control how the resource indicated by url | |
96 | * is to be opened | |
6f1b7b39 MS |
97 | * @param int_cb interrupt callback to use for the URLContext, may be |
98 | * NULL | |
5652bb94 AK |
99 | * @return 0 in case of success, a negative value corresponding to an |
100 | * AVERROR code in case of failure | |
101 | */ | |
6f1b7b39 MS |
102 | int ffurl_alloc(URLContext **puc, const char *filename, int flags, |
103 | const AVIOInterruptCB *int_cb); | |
5652bb94 | 104 | |
62eaaeac AK |
105 | /** |
106 | * Connect an URLContext that has been allocated by ffurl_alloc | |
ddffc2fd AK |
107 | * |
108 | * @param options A dictionary filled with options for nested protocols, | |
109 | * i.e. it will be passed to url_open2() for protocols implementing it. | |
110 | * This parameter will be destroyed and replaced with a dict containing options | |
111 | * that were not found. May be NULL. | |
62eaaeac | 112 | */ |
ddffc2fd | 113 | int ffurl_connect(URLContext *uc, AVDictionary **options); |
62eaaeac | 114 | |
0589da0a AK |
115 | /** |
116 | * Create an URLContext for accessing to the resource indicated by | |
117 | * url, and open it. | |
118 | * | |
119 | * @param puc pointer to the location where, in case of success, the | |
120 | * function puts the pointer to the created URLContext | |
121 | * @param flags flags which control how the resource indicated by url | |
122 | * is to be opened | |
6f1b7b39 MS |
123 | * @param int_cb interrupt callback to use for the URLContext, may be |
124 | * NULL | |
ddffc2fd AK |
125 | * @param options A dictionary filled with protocol-private options. On return |
126 | * this parameter will be destroyed and replaced with a dict containing options | |
127 | * that were not found. May be NULL. | |
0589da0a AK |
128 | * @return 0 in case of success, a negative value corresponding to an |
129 | * AVERROR code in case of failure | |
130 | */ | |
6f1b7b39 | 131 | int ffurl_open(URLContext **puc, const char *filename, int flags, |
ddffc2fd | 132 | const AVIOInterruptCB *int_cb, AVDictionary **options); |
0589da0a | 133 | |
bc371aca AK |
134 | /** |
135 | * Read up to size bytes from the resource accessed by h, and store | |
136 | * the read bytes in buf. | |
137 | * | |
138 | * @return The number of bytes actually read, or a negative value | |
139 | * corresponding to an AVERROR code in case of error. A value of zero | |
140 | * indicates that it is not possible to read more from the accessed | |
141 | * resource (except if the value of the size argument is also zero). | |
142 | */ | |
143 | int ffurl_read(URLContext *h, unsigned char *buf, int size); | |
144 | ||
dce37564 AK |
145 | /** |
146 | * Read as many bytes as possible (up to size), calling the | |
147 | * read function multiple times if necessary. | |
148 | * This makes special short-read handling in applications | |
149 | * unnecessary, if the return value is < size then it is | |
150 | * certain there was either an error or the end of file was reached. | |
151 | */ | |
152 | int ffurl_read_complete(URLContext *h, unsigned char *buf, int size); | |
153 | ||
925e908b AK |
154 | /** |
155 | * Write size bytes from buf to the resource accessed by h. | |
156 | * | |
157 | * @return the number of bytes actually written, or a negative value | |
158 | * corresponding to an AVERROR code in case of failure | |
159 | */ | |
160 | int ffurl_write(URLContext *h, const unsigned char *buf, int size); | |
161 | ||
58a48c65 AK |
162 | /** |
163 | * Change the position that will be used by the next read/write | |
164 | * operation on the resource accessed by h. | |
165 | * | |
166 | * @param pos specifies the new position to set | |
167 | * @param whence specifies how pos should be interpreted, it must be | |
168 | * one of SEEK_SET (seek from the beginning), SEEK_CUR (seek from the | |
169 | * current position), SEEK_END (seek from the end), or AVSEEK_SIZE | |
170 | * (return the filesize of the requested resource, pos is ignored). | |
171 | * @return a negative value corresponding to an AVERROR code in case | |
172 | * of failure, or the resulting file position, measured in bytes from | |
173 | * the beginning of the file. You can use this feature together with | |
174 | * SEEK_CUR to read the current file position. | |
175 | */ | |
176 | int64_t ffurl_seek(URLContext *h, int64_t pos, int whence); | |
177 | ||
e52a9145 AK |
178 | /** |
179 | * Close the resource accessed by the URLContext h, and free the | |
180 | * memory used by it. | |
181 | * | |
182 | * @return a negative value if an error condition occurred, 0 | |
183 | * otherwise | |
184 | */ | |
185 | int ffurl_close(URLContext *h); | |
186 | ||
32a97d46 AK |
187 | /** |
188 | * Return the filesize of the resource accessed by h, AVERROR(ENOSYS) | |
189 | * if the operation is not supported by h, or another negative value | |
190 | * corresponding to an AVERROR error code in case of failure. | |
191 | */ | |
192 | int64_t ffurl_size(URLContext *h); | |
193 | ||
1869ea03 AK |
194 | /** |
195 | * Return the file descriptor associated with this URL. For RTP, this | |
196 | * will return only the RTP file descriptor, not the RTCP file descriptor. | |
197 | * | |
198 | * @return the file descriptor associated with this URL, or <0 on error. | |
199 | */ | |
200 | int ffurl_get_file_handle(URLContext *h); | |
201 | ||
8e76a19b | 202 | /** |
d6b9da11 JO |
203 | * Return the file descriptors associated with this URL. |
204 | * | |
205 | * @return 0 on success or <0 on error. | |
206 | */ | |
207 | int ffurl_get_multi_file_handle(URLContext *h, int **handles, int *numhandles); | |
208 | ||
209 | /** | |
32d545e0 SP |
210 | * Signal the URLContext that we are done reading or writing the stream. |
211 | * | |
212 | * @param h pointer to the resource | |
213 | * @param flags flags which control how the resource indicated by url | |
214 | * is to be shutdown | |
215 | * | |
216 | * @return a negative value if an error condition occurred, 0 | |
217 | * otherwise | |
218 | */ | |
219 | int ffurl_shutdown(URLContext *h, int flags); | |
220 | ||
221 | /** | |
c4a090dd MS |
222 | * Check if the user has requested to interrup a blocking function |
223 | * associated with cb. | |
224 | */ | |
225 | int ff_check_interrupt(AVIOInterruptCB *cb); | |
226 | ||
d6bbe761 AK |
227 | /* udp.c */ |
228 | int ff_udp_set_remote_url(URLContext *h, const char *uri); | |
229 | int ff_udp_get_local_port(URLContext *h); | |
230 | ||
df9f22d4 LB |
231 | /** |
232 | * Assemble a URL string from components. This is the reverse operation | |
233 | * of av_url_split. | |
234 | * | |
235 | * Note, this requires networking to be initialized, so the caller must | |
236 | * ensure ff_network_init has been called. | |
237 | * | |
238 | * @see av_url_split | |
239 | * | |
240 | * @param str the buffer to fill with the url | |
241 | * @param size the size of the str buffer | |
242 | * @param proto the protocol identifier, if null, the separator | |
243 | * after the identifier is left out, too | |
244 | * @param authorization an optional authorization string, may be null. | |
245 | * An empty string is treated the same as a null string. | |
246 | * @param hostname the host name string | |
247 | * @param port the port number, left out from the string if negative | |
248 | * @param fmt a generic format string for everything to add after the | |
249 | * host/port, may be null | |
250 | * @return the number of characters written to the destination buffer | |
251 | */ | |
252 | int ff_url_join(char *str, int size, const char *proto, | |
253 | const char *authorization, const char *hostname, | |
254 | int port, const char *fmt, ...) av_printf_format(7, 8); | |
255 | ||
256 | /* | |
257 | * Convert a relative url into an absolute url, given a base url. | |
258 | * | |
259 | * @param buf the buffer where output absolute url is written | |
260 | * @param size the size of buf | |
261 | * @param base the base url, may be equal to buf. | |
262 | * @param rel the new url, which is interpreted relative to base | |
263 | */ | |
264 | void ff_make_absolute_url(char *buf, int size, const char *base, | |
265 | const char *rel); | |
266 | ||
7d61dc95 AK |
267 | const AVClass *ff_urlcontext_child_class_next(const AVClass *prev); |
268 | ||
832a202c AK |
269 | /** |
270 | * Construct a list of protocols matching a given whitelist and/or blacklist. | |
271 | * | |
272 | * @param whitelist a comma-separated list of allowed protocol names or NULL. If | |
273 | * this is a non-empty string, only protocols in this list will | |
274 | * be included. | |
275 | * @param blacklist a comma-separated list of forbidden protocol names or NULL. | |
276 | * If this is a non-empty string, all protocols in this list | |
277 | * will be excluded. | |
278 | * | |
279 | * @return a NULL-terminated array of matching protocols. The array must be | |
280 | * freed by the caller. | |
281 | */ | |
282 | const URLProtocol **ffurl_get_protocols(const char *whitelist, | |
283 | const char *blacklist); | |
df9f22d4 | 284 | |
153382e1 | 285 | #endif /* AVFORMAT_URL_H */ |