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