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 */ 30 enum { 31 kCompressStored = 0, // no compression 32 kCompressDeflated = 8, // standard deflate 33 }; 34 35 struct 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 */ 43 struct 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 76 typedef 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 */ 85 int32_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 */ 102 int32_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 */ 112 void 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 */ 127 int32_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 */ 143 int32_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 */ 152 int32_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 */ 162 int32_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 */ 172 int32_t ExtractToMemory(ZipArchiveHandle handle, ZipEntry* entry, 173 uint8_t* begin, uint32_t size); 174 175 int GetFileDescriptor(const ZipArchiveHandle handle); 176 177 const char* ErrorCodeString(int32_t error_code); 178 179 __END_DECLS 180 181 #endif // LIBZIPARCHIVE_ZIPARCHIVE_H_ 182