blob: 6bec67be626211be4530870f9a8ba93be395f721
1 | /* ***** BEGIN LICENSE BLOCK ***** |
2 | * Source last modified: $Id: rm_parse.h,v 1.1.1.1.2.1 2005/05/04 18:20:57 hubbe Exp $ |
3 | * |
4 | * REALNETWORKS CONFIDENTIAL--NOT FOR DISTRIBUTION IN SOURCE CODE FORM |
5 | * Portions Copyright (c) 1995-2005 RealNetworks, Inc. |
6 | * All Rights Reserved. |
7 | * |
8 | * The contents of this file, and the files included with this file, |
9 | * are subject to the current version of the Real Format Source Code |
10 | * Porting and Optimization License, available at |
11 | * https://helixcommunity.org/2005/license/realformatsource (unless |
12 | * RealNetworks otherwise expressly agrees in writing that you are |
13 | * subject to a different license). You may also obtain the license |
14 | * terms directly from RealNetworks. You may not use this file except |
15 | * in compliance with the Real Format Source Code Porting and |
16 | * Optimization License. There are no redistribution rights for the |
17 | * source code of this file. Please see the Real Format Source Code |
18 | * Porting and Optimization License for the rights, obligations and |
19 | * limitations governing use of the contents of the file. |
20 | * |
21 | * RealNetworks is the developer of the Original Code and owns the |
22 | * copyrights in the portions it created. |
23 | * |
24 | * This file, and the files included with this file, is distributed and |
25 | * made available on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, |
26 | * EITHER EXPRESS OR IMPLIED, AND REALNETWORKS HEREBY DISCLAIMS ALL |
27 | * SUCH WARRANTIES, INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF |
28 | * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT |
29 | * OR NON-INFRINGEMENT. |
30 | * |
31 | * Technology Compatibility Kit Test Suite(s) Location: |
32 | * https://rarvcode-tck.helixcommunity.org |
33 | * |
34 | * Contributor(s): |
35 | * |
36 | * ***** END LICENSE BLOCK ***** */ |
37 | |
38 | #ifndef RM_PARSE_H |
39 | #define RM_PARSE_H |
40 | |
41 | #include <stdio.h> |
42 | #include "helix_types.h" |
43 | #include "helix_result.h" |
44 | #include "rm_memory.h" |
45 | #include "rm_error.h" |
46 | #include "rm_property.h" |
47 | #include "rm_stream.h" |
48 | #include "rm_packet.h" |
49 | |
50 | #ifdef __cplusplus |
51 | extern "C" { |
52 | #endif /* #ifdef __cplusplus */ |
53 | |
54 | /* |
55 | * Seek origin definitions - these are |
56 | * exactly the same as the respective |
57 | * definitions in <stdio.h> |
58 | */ |
59 | #define HX_SEEK_ORIGIN_SET 0 |
60 | #define HX_SEEK_ORIGIN_CUR 1 |
61 | #define HX_SEEK_ORIGIN_END 2 |
62 | |
63 | /* Function pointer definitions */ |
64 | typedef UINT32(*rm_read_func_ptr)(void* pUserRead, |
65 | BYTE* pBuf, /* Must be at least ulBytesToRead long */ |
66 | UINT32 ulBytesToRead); |
67 | typedef void (*rm_seek_func_ptr)(void* pUserRead, |
68 | UINT32 ulOffset, |
69 | UINT32 ulOrigin); |
70 | |
71 | /* |
72 | * rm_parser definition. This is opaque to the user. |
73 | */ |
74 | typedef void rm_parser; |
75 | |
76 | /* |
77 | * rm_parser_is_rm_file() |
78 | * |
79 | * Function which examines pBuf[0] up through pBuf[ulSize-1] and |
80 | * tries to determine if the buffer contains the beginning of an .rm file |
81 | */ |
82 | HXBOOL rm_parser_is_rm_file(BYTE* pBuf, UINT32 ulSize); |
83 | |
84 | /* |
85 | * rm_parser_create |
86 | * |
87 | * This creates an rm_parser object. The user may provide an |
88 | * optional error reporting function as well as a void* |
89 | * which will be passed into fpError. If fpError is NULL, then |
90 | * the parser will not print out any error messages by default |
91 | * and the user will have to interpret the error by the |
92 | * return value. |
93 | */ |
94 | rm_parser* rm_parser_create(void* pError, |
95 | rm_error_func_ptr fpError); |
96 | |
97 | /* |
98 | * rm_parser_create2 |
99 | * |
100 | * This creates an rm_parser object, using custom memory |
101 | * allocation and free functions that the user provides. |
102 | * If fpMalloc or fpFree are NULL, then the default |
103 | * allocation and free functions will be used. |
104 | */ |
105 | rm_parser* rm_parser_create2(void* pError, |
106 | rm_error_func_ptr fpError, |
107 | void* pMem, |
108 | rm_malloc_func_ptr fpMalloc, |
109 | rm_free_func_ptr fpFree); |
110 | |
111 | /* |
112 | * rm_parser_init_stdio |
113 | * |
114 | * Users would call this is they wanted to use stdio. This file |
115 | * would need to already be fopen()'d and would need to be fclose()'d |
116 | * after the library was finished. The parsing library would only |
117 | * call fread(), fseek(), and perhaps ftell() on it. |
118 | */ |
119 | HX_RESULT rm_parser_init_stdio(rm_parser* pParser, |
120 | FILE* fp); |
121 | |
122 | /* |
123 | * rm_parser_init_io |
124 | * |
125 | * If the user didn't want to use stdio, they would call |
126 | * this function to set up their own I/O. |
127 | */ |
128 | HX_RESULT rm_parser_init_io(rm_parser* pParser, |
129 | void* pUserRead, |
130 | rm_read_func_ptr fpRead, |
131 | rm_seek_func_ptr fpSeek); |
132 | |
133 | /* |
134 | * rm_parser_read_headers |
135 | * |
136 | * This function reads all the headers at the beginning |
137 | * of an .rm file. After this function is called, |
138 | * then the rm_get_xxx accessor functions can be |
139 | * called to get information about the file as a whole. |
140 | */ |
141 | HX_RESULT rm_parser_read_headers(rm_parser* pParser); |
142 | |
143 | /* |
144 | * File Info Accessor functions |
145 | * |
146 | * The most commonly-used properties of an .rm file can |
147 | * be accessed via the rm_parser_get_xxx accessor functions |
148 | * below. These functions return information about the .rm file as |
149 | * a whole, as opposed to stream header properties, which give |
150 | * information about a particular stream (i.e. - audio stream |
151 | * or video stream). |
152 | * |
153 | * For the title meta-data, the user can determine if this information |
154 | * is present by calling rm_parser_get_title_length(). This length |
155 | * is the length in bytes of the string INCLUDING the null |
156 | * terminator. If the title meta-data IS present, then the user |
157 | * can get read-only access to the title by calling rm_parser_get_title(). |
158 | * The user must not alter the memory that is returned; otherwise undefined |
159 | * behavior will result. |
160 | * |
161 | * The same applies for author, copyright, and comment meta-data. |
162 | */ |
163 | UINT32 rm_parser_get_max_bit_rate(rm_parser* pParser); |
164 | UINT32 rm_parser_get_avg_bit_rate(rm_parser* pParser); |
165 | UINT32 rm_parser_get_max_packet_size(rm_parser* pParser); |
166 | UINT32 rm_parser_get_avg_packet_size(rm_parser* pParser); |
167 | UINT32 rm_parser_get_num_packets(rm_parser* pParser); |
168 | UINT32 rm_parser_get_duration(rm_parser* pParser); |
169 | UINT32 rm_parser_get_preroll(rm_parser* pParser); |
170 | const char* rm_parser_get_title(rm_parser* pParser); |
171 | const char* rm_parser_get_author(rm_parser* pParser); |
172 | const char* rm_parser_get_copyright(rm_parser* pParser); |
173 | const char* rm_parser_get_comment(rm_parser* pParser); |
174 | UINT32 rm_parser_get_num_streams(rm_parser* pParser); |
175 | UINT32 rm_parser_get_stream_number(rm_parser* pParser, UINT32 ulStreamNum); |
176 | |
177 | /* |
178 | * General file property accessors |
179 | * |
180 | * The most commonly-used properties of an .rm file |
181 | * can be obtained with the rm_parser_get_xxx accessors above. |
182 | * Alternatively, all of the file-level properties may |
183 | * be obtained as an array of rm_property structs. This |
184 | * array will include all of the common-used properties |
185 | * above as well as any other properties that may be |
186 | * present in the file. |
187 | */ |
188 | HX_RESULT rm_parser_get_file_properties(rm_parser* pParser, |
189 | rm_property** ppProp, |
190 | UINT32* pulNumProps); |
191 | |
192 | /* |
193 | * This function destroys an array of properties created |
194 | * by either rm_parser_get_file_properties or |
195 | * by rm_parser_get_stream_properties. |
196 | */ |
197 | void rm_parser_destroy_properties(rm_parser* pParser, |
198 | rm_property** ppProp, |
199 | UINT32* pulNumProps); |
200 | |
201 | /* |
202 | * rm_parser_get_stream_header |
203 | * |
204 | * This retrieves a stream header from the file. The number |
205 | * of stream headers in the file can be found by calling |
206 | * rm_get_num_streams(). Stream header properties may |
207 | * be obtained by using the accessor functions found |
208 | * in rm_stream.h. These accessors cover the most |
209 | * commonly used properties. The entire set of properties |
210 | * may be retrieved using rm_parser_get_stream_properties(). |
211 | */ |
212 | HX_RESULT rm_parser_get_stream_header(rm_parser* pParser, |
213 | UINT32 ulStreamNum, |
214 | rm_stream_header** ppHdr); |
215 | |
216 | /* |
217 | * rm_parser_destroy_stream_header |
218 | * |
219 | * This function frees any memory associated with |
220 | * a stream header obtained by calling rm_parser_get_stream_header(). |
221 | */ |
222 | void rm_parser_destroy_stream_header(rm_parser* pParser, |
223 | rm_stream_header** ppHdr); |
224 | |
225 | /* |
226 | * rm_parser_get_packet |
227 | * |
228 | * After the headers had been read, the user can repeatedly |
229 | * call this function to retrieve packets from the .rm file. |
230 | */ |
231 | HX_RESULT rm_parser_get_packet(rm_parser* pParser, |
232 | rm_packet** ppPacket); |
233 | |
234 | /* |
235 | * rm_parser_destroy_packet |
236 | * |
237 | * This is called to clean up packets created by |
238 | * calls to rm_parser_get_packet(). |
239 | */ |
240 | void rm_parser_destroy_packet(rm_parser* pParser, |
241 | rm_packet** ppPacket); |
242 | |
243 | /* |
244 | * rm_parser_seek |
245 | * |
246 | * The user can call this function to seek to a |
247 | * certain time in the .rm file |
248 | */ |
249 | HX_RESULT rm_parser_seek(rm_parser* pParser, |
250 | UINT32 ulTime); |
251 | |
252 | /* |
253 | * rm_parser_seek |
254 | * |
255 | * The user can call this function to seek to a |
256 | * certain offset in the .rm file |
257 | */ |
258 | void rm_parser_file_seek(rm_parser* pParser, UINT32 ulOffset); |
259 | |
260 | /* |
261 | * rm_parser_skip |
262 | * |
263 | * The user can call this function to skip to a |
264 | * certain offset from current position |
265 | */ |
266 | void rm_parser_file_skip(rm_parser* pParser, UINT32 ulOffset); |
267 | |
268 | /* |
269 | * rm_parser_build_seek_table |
270 | * |
271 | * The user can call this function to build a seek table |
272 | * by index in the .rm file |
273 | */ |
274 | HX_RESULT rm_parser_build_seek_table(rm_parser* pParser); |
275 | |
276 | /* |
277 | * rm_parser_seek_in_seek_table |
278 | * |
279 | * The user can call this function to seek in the seek table |
280 | * to find a certain time in the .rm file |
281 | */ |
282 | HX_RESULT rm_parser_seek_in_seek_table(rm_parser* pParser, INT32 lStreamNumber, UINT32 ulSeekTime, INT32 lDirection, UINT32* pulFoundTime, UINT32* pulDataOffset, UINT32* pulIndex); |
283 | |
284 | /* |
285 | * rm_parser_destroy |
286 | * |
287 | * The user calls this to clean up |
288 | */ |
289 | void rm_parser_destroy(rm_parser** ppParser); |
290 | |
291 | UINT32 rm_parser_get_data_size(rm_parser* pParser); |
292 | UINT32 rm_parser_get_data_offset(rm_parser* pParser); |
293 | UINT32 rm_parser_get_index_offset(rm_parser* pParser); |
294 | void rm_parser_set_index_offset(rm_parser* pParser, UINT32 offset); |
295 | void rm_parser_set_stream(rm_parser** ppParser, UINT32 ulStreamNum); |
296 | void rm_parser_set_stream_size(rm_parser* pParser, UINT32 ulStreamSize); |
297 | |
298 | #ifdef __cplusplus |
299 | } |
300 | #endif /* #ifdef __cplusplus */ |
301 | |
302 | #endif /* #ifndef RM_PARSE_H */ |
303 |