1/*
2 * Copyright (C) 2013 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#ifndef LIBZIPARCHIVE_ZIPARCHIVE_H_
21#define LIBZIPARCHIVE_ZIPARCHIVE_H_
22
23#include <stdint.h>
24#include <sys/types.h>
25#include <utils/Compat.h>
26
27__BEGIN_DECLS
28
29/* Zip compression methods we support */
30enum {
31  kCompressStored     = 0,        // no compression
32  kCompressDeflated   = 8,        // standard deflate
33};
34
35struct ZipEntryName {
36  const char* name;
37  uint16_t name_length;
38};
39
40/*
41 * Represents information about a zip entry in a zip file.
42 */
43struct ZipEntry {
44  // Compression method: One of kCompressStored or
45  // kCompressDeflated.
46  uint16_t method;
47
48  // Modification time. The zipfile format specifies
49  // that the first two little endian bytes contain the time
50  // and the last two little endian bytes contain the date.
51  uint32_t mod_time;
52
53  // 1 if this entry contains a data descriptor segment, 0
54  // otherwise.
55  uint8_t has_data_descriptor;
56
57  // Crc32 value of this ZipEntry. This information might
58  // either be stored in the local file header or in a special
59  // Data descriptor footer at the end of the file entry.
60  uint32_t crc32;
61
62  // Compressed length of this ZipEntry. Might be present
63  // either in the local file header or in the data descriptor
64  // footer.
65  uint32_t compressed_length;
66
67  // Uncompressed length of this ZipEntry. Might be present
68  // either in the local file header or in the data descriptor
69  // footer.
70  uint32_t uncompressed_length;
71
72  // The offset to the start of data for this ZipEntry.
73  off64_t offset;
74};
75
76typedef void* ZipArchiveHandle;
77
78/*
79 * Open a Zip archive, and sets handle to the value of the opaque
80 * handle for the file. This handle must be released by calling
81 * CloseArchive with this handle.
82 *
83 * Returns 0 on success, and negative values on failure.
84 */
85int32_t OpenArchive(const char* fileName, ZipArchiveHandle* handle);
86
87/*
88 * Like OpenArchive, but takes a file descriptor open for reading
89 * at the start of the file.  The descriptor must be mappable (this does
90 * not allow access to a stream).
91 *
92 * Sets handle to the value of the opaque handle for this file descriptor.
93 * This handle must be released by calling CloseArchive with this handle.
94 *
95 * This function maps and scans the central directory and builds a table
96 * of entries for future lookups.
97 *
98 * "debugFileName" will appear in error messages, but is not otherwise used.
99 *
100 * Returns 0 on success, and negative values on failure.
101 */
102int32_t OpenArchiveFd(const int fd, const char* debugFileName,
103                      ZipArchiveHandle *handle);
104
105/*
106 * Close archive, releasing resources associated with it. This will
107 * unmap the central directory of the zipfile and free all internal
108 * data structures associated with the file. It is an error to use
109 * this handle for any further operations without an intervening
110 * call to one of the OpenArchive variants.
111 */
112void CloseArchive(ZipArchiveHandle handle);
113
114/*
115 * Find an entry in the Zip archive, by name. |entryName| must be a null
116 * terminated string, and |data| must point to a writeable memory location.
117 *
118 * Returns 0 if an entry is found, and populates |data| with information
119 * about this entry. Returns negative values otherwise.
120 *
121 * It's important to note that |data->crc32|, |data->compLen| and
122 * |data->uncompLen| might be set to values from the central directory
123 * if this file entry contains a data descriptor footer. To verify crc32s
124 * and length, a call to VerifyCrcAndLengths must be made after entry data
125 * has been processed.
126 */
127int32_t FindEntry(const ZipArchiveHandle handle, const char* entryName,
128                  ZipEntry* data);
129
130/*
131 * Start iterating over all entries of a zip file. The order of iteration
132 * is not guaranteed to be the same as the order of elements
133 * in the central directory but is stable for a given zip file. |cookie|
134 * must point to a writeable memory location, and will be set to the value
135 * of an opaque cookie which can be used to make one or more calls to
136 * Next.
137 *
138 * This method also accepts an optional prefix to restrict iteration to
139 * entry names that start with |prefix|.
140 *
141 * Returns 0 on success and negative values on failure.
142 */
143int32_t StartIteration(ZipArchiveHandle handle, void** cookie_ptr,
144                       const char* prefix);
145
146/*
147 * Advance to the next element in the zipfile in iteration order.
148 *
149 * Returns 0 on success, -1 if there are no more elements in this
150 * archive and lower negative values on failure.
151 */
152int32_t Next(void* cookie, ZipEntry* data, ZipEntryName *name);
153
154/*
155 * Uncompress and write an entry to an open file identified by |fd|.
156 * |entry->uncompressed_length| bytes will be written to the file at
157 * its current offset, and the file will be truncated at the end of
158 * the uncompressed data.
159 *
160 * Returns 0 on success and negative values on failure.
161 */
162int32_t ExtractEntryToFile(ZipArchiveHandle handle, ZipEntry* entry, int fd);
163
164/**
165 * Uncompress a given zip entry to the memory region at |begin| and of
166 * size |size|. This size is expected to be the same as the *declared*
167 * uncompressed length of the zip entry. It is an error if the *actual*
168 * number of uncompressed bytes differs from this number.
169 *
170 * Returns 0 on success and negative values on failure.
171 */
172int32_t ExtractToMemory(ZipArchiveHandle handle, ZipEntry* entry,
173                        uint8_t* begin, uint32_t size);
174
175int GetFileDescriptor(const ZipArchiveHandle handle);
176
177const char* ErrorCodeString(int32_t error_code);
178
179__END_DECLS
180
181#endif  // LIBZIPARCHIVE_ZIPARCHIVE_H_
182