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