1 /*
2  * Copyright (C) 2007 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 /*
18  * Read-only access to Zip archives, with minimal heap allocation.
19  *
20  * This is similar to the more-complete ZipFile class, but no attempt
21  * has been made to make them interchangeable.  This class operates under
22  * a very different set of assumptions and constraints.
23  *
24  * One such assumption is that if you're getting file descriptors for
25  * use with this class as a child of a fork() operation, you must be on
26  * a pread() to guarantee correct operation. This is because pread() can
27  * atomically read at a file offset without worrying about a lock around an
28  * lseek() + read() pair.
29  */
30 #ifndef __LIBS_ZIPFILERO_H
31 #define __LIBS_ZIPFILERO_H
32 
33 #include <optional>
34 #include <stdint.h>
35 #include <stdio.h>
36 #include <stdlib.h>
37 #include <unistd.h>
38 #include <time.h>
39 
40 #include <android-base/expected.h>
41 
42 #include <util/map_ptr.h>
43 
44 #include <utils/Compat.h>
45 #include <utils/Errors.h>
46 #include <utils/FileMap.h>
47 #include <utils/threads.h>
48 
49 struct ZipArchive;
50 typedef ZipArchive* ZipArchiveHandle;
51 
52 namespace android {
53 
54 /*
55  * Trivial typedef to ensure that ZipEntryRO is not treated as a simple
56  * integer.  We use NULL to indicate an invalid value.
57  */
58 typedef void* ZipEntryRO;
59 
60 /*
61  * Open a Zip archive for reading.
62  *
63  * Implemented as a thin wrapper over system/core/libziparchive.
64  *
65  * "open" and "find entry by name" are fast operations and use as little
66  * memory as possible.
67  *
68  * We also support fast iteration over all entries in the file (with a
69  * stable, but unspecified iteration order).
70  *
71  * NOTE: If this is used on file descriptors inherited from a fork() operation,
72  * you must be on a platform that implements pread() to guarantee correctness
73  * on the shared file descriptors.
74  */
75 class ZipFileRO {
76 public:
77     /* Zip compression methods we support */
78     enum : uint16_t {
79         kCompressStored = 0,
80         kCompressDeflated = 8
81     };
82 
83     /*
84      * Open an archive.
85      */
86     static ZipFileRO* open(const char* zipFileName);
87 
88     /*
89      * Open an archive from an already open file descriptor.
90      */
91     static ZipFileRO* openFd(int fd, const char* debugFileName,
92         bool assume_ownership = true);
93 
94     /*
95      * Find an entry, by name.  Returns the entry identifier, or NULL if
96      * not found.
97      */
98     ZipEntryRO findEntryByName(const char* entryName) const;
99 
100 
101     /*
102      * Start iterating over the list of entries in the zip file. Requires
103      * a matching call to endIteration with the same cookie.
104      */
105     bool startIteration(void** cookie);
106     bool startIteration(void** cookie, const char* prefix, const char* suffix);
107     /*
108      * Same as above, but returns the error code in case of failure.
109      * #see libziparchive/zip_error.h.
110      */
111     base::expected<void*, int32_t> startIterationOrError(const char* prefix, const char* suffix);
112 
113     /**
114      * Return the next entry in iteration order, or NULL if there are no more
115      * entries in this archive.
116      */
117     ZipEntryRO nextEntry(void* cookie);
118 
119     /**
120      * Same as above, but returns the error code in case of failure.
121      * #see libziparchive/zip_error.h.
122      */
123     base::expected<ZipEntryRO, int32_t> nextEntryOrError(void* cookie);
124 
125     void endIteration(void* cookie);
126 
127     void releaseEntry(ZipEntryRO entry) const;
128 
129     /*
130      * Return the #of entries in the Zip archive.
131      */
132     int getNumEntries();
133 
134     /*
135      * Copy the filename into the supplied buffer.  Returns 0 on success,
136      * -1 if "entry" is invalid, or the filename length if it didn't fit. The
137      * length, and the returned string, include the null-termination.
138      */
139     int getEntryFileName(ZipEntryRO entry, char* buffer, size_t bufLen) const;
140 
141     /*
142      * Get the vital stats for an entry.  Pass in NULL pointers for anything
143      * you don't need.
144      *
145      * "*pOffset" holds the Zip file offset of the entry's data.
146      *
147      * Returns "false" if "entry" is bogus or if the data in the Zip file
148      * appears to be bad.
149      */
150     bool getEntryInfo(ZipEntryRO entry, uint16_t* pMethod,
151         uint32_t* pUncompLen, uint32_t* pCompLen, off64_t* pOffset,
152         uint32_t* pModWhen, uint32_t* pCrc32, uint16_t* pExtraFieldSize) const;
153 
154     /*
155      * Create a new FileMap object that maps a subset of the archive. For
156      * an uncompressed entry this effectively provides a pointer to the
157      * actual data, for a compressed entry this provides the input buffer
158      * for inflate().
159      *
160      * Use this function if the archive can never reside on IncFs.
161      */
162     FileMap* createEntryFileMap(ZipEntryRO entry) const;
163 
164     /*
165      * Create a new incfs::IncFsFileMap object that maps a subset of the archive. For
166      * an uncompressed entry this effectively provides a pointer to the
167      * actual data, for a compressed entry this provides the input buffer
168      * for inflate().
169      *
170      * Use this function if the archive can potentially reside on IncFs.
171      */
172     std::optional<incfs::IncFsFileMap> createEntryIncFsFileMap(ZipEntryRO entry) const;
173 
174     /*
175      * Uncompress the data into a buffer.  Depending on the compression
176      * format, this is either an "inflate" operation or a memcpy.
177      *
178      * Use "uncompLen" from getEntryInfo() to determine the required
179      * buffer size.
180      *
181      * Returns "true" on success.
182      */
183     bool uncompressEntry(ZipEntryRO entry, void* buffer, size_t size) const;
184 
185     /*
186      * Uncompress the data to an open file descriptor.
187      */
188     bool uncompressEntry(ZipEntryRO entry, int fd) const;
189 
190     const char* getZipFileName();
191 
192     ~ZipFileRO();
193 
194 private:
195     /* these are private and not defined */
196     ZipFileRO(const ZipFileRO& src);
197     ZipFileRO& operator=(const ZipFileRO& src);
198 
ZipFileRO(ZipArchiveHandle handle,char * fileName)199     ZipFileRO(ZipArchiveHandle handle, char* fileName) : mHandle(handle),
200         mFileName(fileName)
201     {
202     }
203 
204     const ZipArchiveHandle mHandle;
205     char* mFileName;
206 };
207 
208 }; // namespace android
209 
210 #endif /*__LIBS_ZIPFILERO_H*/
211