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