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 <utils/Compat.h>
34#include <utils/Errors.h>
35#include <utils/FileMap.h>
36#include <utils/threads.h>
37
38#include <stdint.h>
39#include <stdio.h>
40#include <stdlib.h>
41#include <unistd.h>
42#include <time.h>
43
44typedef void* ZipArchiveHandle;
45
46namespace android {
47
48/*
49 * Trivial typedef to ensure that ZipEntryRO is not treated as a simple
50 * integer.  We use NULL to indicate an invalid value.
51 */
52typedef void* ZipEntryRO;
53
54/*
55 * Open a Zip archive for reading.
56 *
57 * Implemented as a thin wrapper over system/core/libziparchive.
58 *
59 * "open" and "find entry by name" are fast operations and use as little
60 * memory as possible.
61 *
62 * We also support fast iteration over all entries in the file (with a
63 * stable, but unspecified iteration order).
64 *
65 * NOTE: If this is used on file descriptors inherited from a fork() operation,
66 * you must be on a platform that implements pread() to guarantee correctness
67 * on the shared file descriptors.
68 */
69class ZipFileRO {
70public:
71    /* Zip compression methods we support */
72    enum : uint16_t {
73        kCompressStored = 0,
74        kCompressDeflated = 8
75    };
76
77    /*
78     * Open an archive.
79     */
80    static ZipFileRO* open(const char* zipFileName);
81
82    /*
83     * Find an entry, by name.  Returns the entry identifier, or NULL if
84     * not found.
85     */
86    ZipEntryRO findEntryByName(const char* entryName) const;
87
88
89    /*
90     * Start iterating over the list of entries in the zip file. Requires
91     * a matching call to endIteration with the same cookie.
92     */
93    bool startIteration(void** cookie);
94    bool startIteration(void** cookie, const char* prefix, const char* suffix);
95
96    /**
97     * Return the next entry in iteration order, or NULL if there are no more
98     * entries in this archive.
99     */
100    ZipEntryRO nextEntry(void* cookie);
101
102    void endIteration(void* cookie);
103
104    void releaseEntry(ZipEntryRO entry) const;
105
106    /*
107     * Return the #of entries in the Zip archive.
108     */
109    int getNumEntries();
110
111    /*
112     * Copy the filename into the supplied buffer.  Returns 0 on success,
113     * -1 if "entry" is invalid, or the filename length if it didn't fit. The
114     * length, and the returned string, include the null-termination.
115     */
116    int getEntryFileName(ZipEntryRO entry, char* buffer, size_t bufLen) const;
117
118    /*
119     * Get the vital stats for an entry.  Pass in NULL pointers for anything
120     * you don't need.
121     *
122     * "*pOffset" holds the Zip file offset of the entry's data.
123     *
124     * Returns "false" if "entry" is bogus or if the data in the Zip file
125     * appears to be bad.
126     */
127    bool getEntryInfo(ZipEntryRO entry, uint16_t* pMethod, uint32_t* pUncompLen,
128        uint32_t* pCompLen, off64_t* pOffset, uint32_t* pModWhen,
129        uint32_t* pCrc32) const;
130
131    /*
132     * Create a new FileMap object that maps a subset of the archive.  For
133     * an uncompressed entry this effectively provides a pointer to the
134     * actual data, for a compressed entry this provides the input buffer
135     * for inflate().
136     */
137    FileMap* createEntryFileMap(ZipEntryRO entry) const;
138
139    /*
140     * Uncompress the data into a buffer.  Depending on the compression
141     * format, this is either an "inflate" operation or a memcpy.
142     *
143     * Use "uncompLen" from getEntryInfo() to determine the required
144     * buffer size.
145     *
146     * Returns "true" on success.
147     */
148    bool uncompressEntry(ZipEntryRO entry, void* buffer, size_t size) const;
149
150    /*
151     * Uncompress the data to an open file descriptor.
152     */
153    bool uncompressEntry(ZipEntryRO entry, int fd) const;
154
155    ~ZipFileRO();
156
157private:
158    /* these are private and not defined */
159    ZipFileRO(const ZipFileRO& src);
160    ZipFileRO& operator=(const ZipFileRO& src);
161
162    ZipFileRO(ZipArchiveHandle handle, char* fileName) : mHandle(handle),
163        mFileName(fileName)
164    {
165    }
166
167    const ZipArchiveHandle mHandle;
168    char* mFileName;
169};
170
171}; // namespace android
172
173#endif /*__LIBS_ZIPFILERO_H*/
174