1 /*
2 
3 Copyright (c) 2011, 2012, Simon Howard
4 
5 Permission to use, copy, modify, and/or distribute this software
6 for any purpose with or without fee is hereby granted, provided
7 that the above copyright notice and this permission notice appear
8 in all copies.
9 
10 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
11 WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
12 WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
13 AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR
14 CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
15 LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
16 NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
17 CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
18 
19  */
20 
21 
22 #ifndef LHASA_PUBLIC_LHA_INPUT_STREAM_H
23 #define LHASA_PUBLIC_LHA_INPUT_STREAM_H
24 
25 #include <stdio.h>
26 
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30 
31 /**
32  * @file lha_input_stream.h
33  *
34  * @brief LHA input stream structure.
35  *
36  * This file defines the functions relating to the @ref LHAInputStream
37  * structure, used to read data from an LZH file.
38  */
39 
40 /**
41  * Opaque structure, representing an input stream used to read data from
42  * an LZH file.
43  */
44 
45 typedef struct _LHAInputStream LHAInputStream;
46 
47 /**
48  * Structure containing pointers to callback functions to read data from
49  * the input stream.
50  */
51 
52 typedef struct {
53 
54 	/**
55 	 * Read a block of data into the specified buffer.
56 	 *
57 	 * @param handle       Handle pointer.
58 	 * @param buf          Pointer to buffer in which to store read data.
59 	 * @param buf_len      Size of buffer, in bytes.
60 	 * @return             Number of bytes read, or -1 for error.
61 	 */
62 
63 	int (*read)(void *handle, void *buf, size_t buf_len);
64 
65 
66 	/**
67 	 * Skip the specified number of bytes from the input stream.
68 	 * This is an optional function.
69 	 *
70 	 * @param handle       Handle pointer.
71 	 * @param bytes        Number of bytes to skip.
72 	 * @return             Non-zero for success, or zero for failure.
73 	 */
74 
75 	int (*skip)(void *handle, size_t bytes);
76 
77 	/**
78 	 * Close the input stream.
79 	 *
80 	 * @param handle       Handle pointer.
81 	 */
82 
83 	void (*close)(void *handle);
84 
85 } LHAInputStreamType;
86 
87 /**
88  * Create new @ref LHAInputStream structure, using a set of generic functions
89  * to provide LHA data.
90  *
91  * @param type         Pointer to a @ref LHAInputStreamType structure
92  *                     containing callback functions to read data.
93  * @param handle       Handle pointer to be passed to callback functions.
94  * @return             Pointer to a new @ref LHAInputStream or NULL for error.
95  */
96 
97 LHAInputStream *lha_input_stream_new(const LHAInputStreamType *type,
98                                      void *handle);
99 
100 /**
101  * Create new @ref LHAInputStream, reading from the specified filename.
102  * The file is automatically closed when the input stream is freed.
103  *
104  * @param filename     Name of the file to read from.
105  * @return             Pointer to a new @ref LHAInputStream or NULL for error.
106  */
107 
108 LHAInputStream *lha_input_stream_from(char *filename);
109 
110 /**
111  * Create new @ref LHAInputStream, to read from an already-open FILE pointer.
112  * The FILE is not closed when the input stream is freed; the calling code
113  * must close it.
114  *
115  * @param stream       The open FILE structure from which to read data.
116  * @return             Pointer to a new @ref LHAInputStream or NULL for error.
117  */
118 
119 LHAInputStream *lha_input_stream_from_FILE(FILE *stream);
120 
121 /**
122  * Free an @ref LHAInputStream structure.
123  *
124  * @param stream       The input stream.
125  */
126 
127 void lha_input_stream_free(LHAInputStream *stream);
128 
129 #ifdef __cplusplus
130 }
131 #endif
132 
133 #endif /* #ifndef LHASA_PUBLIC_LHA_INPUT_STREAM_H */
134 
135