Move avio.h's url_get_max_packet_size() comment from source to header file.
[ffmpeg.git] / libavformat / avio.h
1 /*
2  * unbuffered io for ffmpeg system
3  * copyright (c) 2001 Fabrice Bellard
4  *
5  * This file is part of FFmpeg.
6  *
7  * FFmpeg is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public
9  * License as published by the Free Software Foundation; either
10  * version 2.1 of the License, or (at your option) any later version.
11  *
12  * FFmpeg is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15  * Lesser General Public License for more details.
16  *
17  * You should have received a copy of the GNU Lesser General Public
18  * License along with FFmpeg; if not, write to the Free Software
19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
20  */
21 #ifndef AVIO_H
22 #define AVIO_H
23
24 /* output byte stream handling */
25
26 typedef int64_t offset_t;
27
28 /* unbuffered I/O */
29
30 struct URLContext {
31     struct URLProtocol *prot;
32     int flags;
33     int is_streamed;  /* true if streamed (no seek possible), default = false */
34     int max_packet_size;  /* if non zero, the stream is packetized with this max packet size */
35     void *priv_data;
36 #if LIBAVFORMAT_VERSION_INT >= (52<<16)
37     char *filename; /* specified filename */
38 #else
39     char filename[1]; /* specified filename */
40 #endif
41 };
42
43 typedef struct URLContext URLContext;
44
45 typedef struct URLPollEntry {
46     URLContext *handle;
47     int events;
48     int revents;
49 } URLPollEntry;
50
51 #define URL_RDONLY 0
52 #define URL_WRONLY 1
53 #define URL_RDWR   2
54
55 typedef int URLInterruptCB(void);
56
57 int url_open(URLContext **h, const char *filename, int flags);
58 int url_read(URLContext *h, unsigned char *buf, int size);
59 int url_write(URLContext *h, unsigned char *buf, int size);
60 offset_t url_seek(URLContext *h, offset_t pos, int whence);
61 int url_close(URLContext *h);
62 int url_exist(const char *filename);
63 offset_t url_filesize(URLContext *h);
64
65 /*
66  * Return the maximum packet size associated to packetized file
67  * handle. If the file is not packetized (stream like http or file on
68  * disk), then 0 is returned.
69  *
70  * @param h file handle
71  * @return maximum packet size in bytes
72  */
73 int url_get_max_packet_size(URLContext *h);
74 void url_get_filename(URLContext *h, char *buf, int buf_size);
75
76 /* the callback is called in blocking functions to test regulary if
77    asynchronous interruption is needed. AVERROR(EINTR) is returned
78    in this case by the interrupted function. 'NULL' means no interrupt
79    callback is given. */
80 void url_set_interrupt_cb(URLInterruptCB *interrupt_cb);
81
82 /* not implemented */
83 int url_poll(URLPollEntry *poll_table, int n, int timeout);
84
85 /**
86  * passing this as the "whence" parameter to a seek function causes it to
87  * return the filesize without seeking anywhere, supporting this is optional
88  * if its not supprted then the seek function will return <0
89  */
90 #define AVSEEK_SIZE 0x10000
91
92 typedef struct URLProtocol {
93     const char *name;
94     int (*url_open)(URLContext *h, const char *filename, int flags);
95     int (*url_read)(URLContext *h, unsigned char *buf, int size);
96     int (*url_write)(URLContext *h, unsigned char *buf, int size);
97     offset_t (*url_seek)(URLContext *h, offset_t pos, int whence);
98     int (*url_close)(URLContext *h);
99     struct URLProtocol *next;
100 } URLProtocol;
101
102 extern URLProtocol *first_protocol;
103 extern URLInterruptCB *url_interrupt_cb;
104
105 int register_protocol(URLProtocol *protocol);
106
107 typedef struct {
108     unsigned char *buffer;
109     int buffer_size;
110     unsigned char *buf_ptr, *buf_end;
111     void *opaque;
112     int (*read_packet)(void *opaque, uint8_t *buf, int buf_size);
113     int (*write_packet)(void *opaque, uint8_t *buf, int buf_size);
114     offset_t (*seek)(void *opaque, offset_t offset, int whence);
115     offset_t pos; /* position in the file of the current buffer */
116     int must_flush; /* true if the next seek should flush */
117     int eof_reached; /* true if eof reached */
118     int write_flag;  /* true if open for writing */
119     int is_streamed;
120     int max_packet_size;
121     unsigned long checksum;
122     unsigned char *checksum_ptr;
123     unsigned long (*update_checksum)(unsigned long checksum, const uint8_t *buf, unsigned int size);
124     int error;         ///< contains the error code or 0 if no error happened
125 } ByteIOContext;
126
127 int init_put_byte(ByteIOContext *s,
128                   unsigned char *buffer,
129                   int buffer_size,
130                   int write_flag,
131                   void *opaque,
132                   int (*read_packet)(void *opaque, uint8_t *buf, int buf_size),
133                   int (*write_packet)(void *opaque, uint8_t *buf, int buf_size),
134                   offset_t (*seek)(void *opaque, offset_t offset, int whence));
135
136 void put_byte(ByteIOContext *s, int b);
137 void put_buffer(ByteIOContext *s, const unsigned char *buf, int size);
138 void put_le64(ByteIOContext *s, uint64_t val);
139 void put_be64(ByteIOContext *s, uint64_t val);
140 void put_le32(ByteIOContext *s, unsigned int val);
141 void put_be32(ByteIOContext *s, unsigned int val);
142 void put_le24(ByteIOContext *s, unsigned int val);
143 void put_be24(ByteIOContext *s, unsigned int val);
144 void put_le16(ByteIOContext *s, unsigned int val);
145 void put_be16(ByteIOContext *s, unsigned int val);
146 void put_tag(ByteIOContext *s, const char *tag);
147
148 void put_strz(ByteIOContext *s, const char *buf);
149
150 offset_t url_fseek(ByteIOContext *s, offset_t offset, int whence);
151 void url_fskip(ByteIOContext *s, offset_t offset);
152 offset_t url_ftell(ByteIOContext *s);
153 offset_t url_fsize(ByteIOContext *s);
154 int url_feof(ByteIOContext *s);
155 int url_ferror(ByteIOContext *s);
156
157 #define URL_EOF (-1)
158 /* NOTE: return URL_EOF (-1) if EOF */
159 int url_fgetc(ByteIOContext *s);
160
161 /* XXX: currently size is limited */
162 #ifdef __GNUC__
163 int url_fprintf(ByteIOContext *s, const char *fmt, ...) __attribute__ ((__format__ (__printf__, 2, 3)));
164 #else
165 int url_fprintf(ByteIOContext *s, const char *fmt, ...);
166 #endif
167
168 /* note: unlike fgets, the EOL character is not returned and a whole
169    line is parsed. return NULL if first char read was EOF */
170 char *url_fgets(ByteIOContext *s, char *buf, int buf_size);
171
172 void put_flush_packet(ByteIOContext *s);
173
174 int get_buffer(ByteIOContext *s, unsigned char *buf, int size);
175 int get_partial_buffer(ByteIOContext *s, unsigned char *buf, int size);
176
177 /* NOTE: return 0 if EOF, so you cannot use it if EOF handling is
178    necessary */
179 int get_byte(ByteIOContext *s);
180 unsigned int get_le24(ByteIOContext *s);
181 unsigned int get_le32(ByteIOContext *s);
182 uint64_t get_le64(ByteIOContext *s);
183 unsigned int get_le16(ByteIOContext *s);
184
185 char *get_strz(ByteIOContext *s, char *buf, int maxlen);
186 unsigned int get_be16(ByteIOContext *s);
187 unsigned int get_be24(ByteIOContext *s);
188 unsigned int get_be32(ByteIOContext *s);
189 uint64_t get_be64(ByteIOContext *s);
190
191 static inline int url_is_streamed(ByteIOContext *s)
192 {
193     return s->is_streamed;
194 }
195
196 int url_fdopen(ByteIOContext *s, URLContext *h);
197
198 /* XXX: must be called before any I/O */
199 int url_setbufsize(ByteIOContext *s, int buf_size);
200
201 /* NOTE: when opened as read/write, the buffers are only used for
202    reading */
203 int url_fopen(ByteIOContext *s, const char *filename, int flags);
204 int url_fclose(ByteIOContext *s);
205 URLContext *url_fileno(ByteIOContext *s);
206
207 /*
208  * Return the maximum packet size associated to packetized buffered file
209  * handle. If the file is not packetized (stream like http or file on
210  * disk), then 0 is returned.
211  *
212  * @param h buffered file handle
213  * @return maximum packet size in bytes
214  */
215 int url_fget_max_packet_size(ByteIOContext *s);
216
217 int url_open_buf(ByteIOContext *s, uint8_t *buf, int buf_size, int flags);
218
219 /* return the written or read size */
220 int url_close_buf(ByteIOContext *s);
221
222 /*
223  * Open a write only memory stream.
224  *
225  * @param s new IO context
226  * @return zero if no error.
227  */
228 int url_open_dyn_buf(ByteIOContext *s);
229
230 /*
231  * Open a write only packetized memory stream with a maximum packet
232  * size of 'max_packet_size'.  The stream is stored in a memory buffer
233  * with a big endian 4 byte header giving the packet size in bytes.
234  *
235  * @param s new IO context
236  * @param max_packet_size maximum packet size (must be > 0)
237  * @return zero if no error.
238  */
239 int url_open_dyn_packet_buf(ByteIOContext *s, int max_packet_size);
240
241 /*
242  * Return the written size and a pointer to the buffer. The buffer
243  *  must be freed with av_free().
244  * @param s IO context
245  * @param pointer to a byte buffer
246  * @return the length of the byte buffer
247  */
248 int url_close_dyn_buf(ByteIOContext *s, uint8_t **pbuffer);
249
250 unsigned long get_checksum(ByteIOContext *s);
251 void init_checksum(ByteIOContext *s, unsigned long (*update_checksum)(unsigned long c, const uint8_t *p, unsigned int len), unsigned long checksum);
252
253 /* file.c */
254 extern URLProtocol file_protocol;
255 extern URLProtocol pipe_protocol;
256
257 /* udp.c */
258 extern URLProtocol udp_protocol;
259 int udp_set_remote_url(URLContext *h, const char *uri);
260 int udp_get_local_port(URLContext *h);
261 int udp_get_file_handle(URLContext *h);
262
263 /* tcp.c  */
264 extern URLProtocol tcp_protocol;
265
266 /* http.c */
267 extern URLProtocol http_protocol;
268
269 #endif
270