If you are setting decodeStrings to false, then this function can be used to decode the file name yourself.
This function is effectively used internally by yauzl to populate the entry.fileName field when decodeStrings is true.
WARNING: This method of getting the file name bypasses the security checks in validateFileName().
You should call that function yourself to be sure to guard against malicious file paths.
generalPurposeBitFlag can be found on an Entry or LocalFileHeader.
Only General Purpose Bit 11 is used, and only when an Info-ZIP Unicode Path Extra Field cannot be found in extraFields.
fileNameBuffer is a Buffer representing the file name field of the entry.
This is entry.fileNameRaw or localFileHeader.fileName.
extraFields is the parsed extra fields array from entry.extraFields or parseExtraFields().
strictFileNames is a boolean, the same as the option of the same name in open().
When false, backslash characters (\) will be replaced with forward slash characters (/).
This function always returns a string, although it may not be a valid file name.
See validateFileName().
extraFieldBuffer is a Buffer, such as localFileHeader.extraField.
Returns an Array with each item in the form {id: id, data: data},
where id is a Number and data is a Buffer.
Throws an Error if the data encodes an item with a size that exceeds the bounds of the buffer.
You may want to surround calls to this function with try { ... } catch (err) { ... } to handle the error.
readLocalFileHeader(entry, [options], callback)
This is a low-level function you probably don't need to call.
The intended use case is either preparing to call openReadStreamLowLevel()
or simply examining the content of the local file header out of curiosity or for debugging zip file structure issues.
entry is an entry obtained from Event: "entry".
An entry in this library is a file's metadata from a Central Directory Header,
and this function gives the corresponding redundant data in a Local File Header.
options may be omitted or null, and has the following defaults:
{
minimal: false,
}
If minimal is false (or omitted or null), the callback receives a full LocalFileHeader.
If minimal is true, the callback receives an object with a single property and no prototype {fileDataStart: fileDataStart}.
For typical zipfile reading usecases, this field is the only one you need,
and yauzl internally effectively uses the {minimal: true} option as part of openReadStream().
The callback receives (err, localFileHeaderOrAnObjectWithJustOneFieldDependingOnTheMinimalOption),
where the type of the second parameter is described in the above discussion of the minimal option.
This is a low-level function available for advanced use cases. You probably want openReadStream() instead.
The intended use case for this function is calling readEntry() and readLocalFileHeader() with {minimal: true} first,
and then opening the read stream at a later time, possibly after closing and reopening the entire zipfile,
possibly even in a different process.
The parameters are all integers and booleans, which are friendly to serialization.
fileDataStart - from localFileHeader.fileDataStart
compressedSize - from entry.compressedSize
relativeStart - the resolved value of options.start from openReadStream(). Must be a non-negative integer, not null. Typically 0 to start at the beginning of the data.
relativeEnd - the resolved value of options.end from openReadStream(). Must be a non-negative integer, not null. Typically entry.compressedSize to include all the data.
decompress - boolean indicating whether the data should be piped through a zlib inflate stream.
uncompressedSize - from entry.uncompressedSize. Only used when validateEntrySizes is true. If validateEntrySizes is false, this value is ignored, but must still be present, not omitted, in the arguments; you have to give it some value, even if it's null.
callback - receives (err, readStream), the same as for openReadStream()
This low-level function does not read any metadata from the underlying storage before opening the read stream.
This is both a performance feature and a safety hazard.
None of the integer parameters are bounds checked.
None of the validation from openReadStream() with respect to compression and encryption is done here either.
Only the bounds checks from validateEntrySizes are done, because that is part of processing the stream data.
Class: LocalFileHeader
This is a trivial class that has no methods and only the following properties.
The constructor is available to call, but it doesn't do anything.
See readLocalFileHeader().
See the zipfile spec for what these fields mean.
fileDataStart - Number: inferred from fileNameLength, extraFieldLength, and this struct's position in the zipfile.
versionNeededToExtract - Number
generalPurposeBitFlag - Number
compressionMethod - Number
lastModFileTime - Number
lastModFileDate - Number
crc32 - Number
compressedSize - Number
uncompressedSize - Number
fileNameLength - Number
extraFieldLength - Number
fileName - Buffer
extraField - Buffer
Note that unlike Class: Entry, the fileName and extraField are completely unprocessed.
This notably lacks Unicode and ZIP64 handling as well as any kind of safety validation on the file name.
See also parseExtraFields().
Also note that if your object is missing some of these fields,
make sure to read the docs on the minimal option in readLocalFileHeader().
readLocalFileHeader()andClass: LocalFileHeader.openReadStreamLowLevel().getFileNameLowLevel()andparseExtraFields(). Added fields toClass: Entry:fileNameRaw,extraFieldRaw,fileCommentRaw.examples/compareCentralAndLocalHeaders.jsthat demonstrate many of these low level APIs."engines"field ofpackage.json.openReadStream()with an explicitlynulloptions parameter (as opposed to omitted).Here's some of the readme additions copied into this PR for convenience:
getFileNameLowLevel(generalPurposeBitFlag, fileNameBuffer, extraFields, strictFileNames)
If you are setting
decodeStringstofalse, then this function can be used to decode the file name yourself. This function is effectively used internally by yauzl to populate theentry.fileNamefield whendecodeStringsistrue.WARNING: This method of getting the file name bypasses the security checks in
validateFileName(). You should call that function yourself to be sure to guard against malicious file paths.generalPurposeBitFlagcan be found on anEntryorLocalFileHeader. Only General Purpose Bit 11 is used, and only when an Info-ZIP Unicode Path Extra Field cannot be found inextraFields.fileNameBufferis aBufferrepresenting the file name field of the entry. This isentry.fileNameRaworlocalFileHeader.fileName.extraFieldsis the parsed extra fields array fromentry.extraFieldsorparseExtraFields().strictFileNamesis a boolean, the same as the option of the same name inopen(). Whenfalse, backslash characters (\) will be replaced with forward slash characters (/). This function always returns a string, although it may not be a valid file name. SeevalidateFileName().parseExtraFields(extraFieldBuffer)
This function is used internally by yauzl to compute
entry.extraFields. It is exported in case you want to call it onlocalFileHeader.extraField.extraFieldBufferis aBuffer, such aslocalFileHeader.extraField. Returns anArraywith each item in the form{id: id, data: data}, whereidis aNumberanddatais aBuffer. Throws anErrorif the data encodes an item with a size that exceeds the bounds of the buffer.You may want to surround calls to this function with
try { ... } catch (err) { ... }to handle the error.readLocalFileHeader(entry, [options], callback)
This is a low-level function you probably don't need to call. The intended use case is either preparing to call
openReadStreamLowLevel()or simply examining the content of the local file header out of curiosity or for debugging zip file structure issues.entryis an entry obtained fromEvent: "entry". Anentryin this library is a file's metadata from a Central Directory Header, and this function gives the corresponding redundant data in a Local File Header.optionsmay be omitted ornull, and has the following defaults:If
minimalisfalse(or omitted ornull), the callback receives a fullLocalFileHeader. Ifminimalistrue, the callback receives an object with a single property and no prototype{fileDataStart: fileDataStart}. For typical zipfile reading usecases, this field is the only one you need, and yauzl internally effectively uses the{minimal: true}option as part ofopenReadStream().The
callbackreceives(err, localFileHeaderOrAnObjectWithJustOneFieldDependingOnTheMinimalOption), where the type of the second parameter is described in the above discussion of theminimaloption.openReadStreamLowLevel(fileDataStart, compressedSize, relativeStart, relativeEnd, decompress, uncompressedSize, callback)
This is a low-level function available for advanced use cases. You probably want
openReadStream()instead.The intended use case for this function is calling
readEntry()andreadLocalFileHeader()with{minimal: true}first, and then opening the read stream at a later time, possibly after closing and reopening the entire zipfile, possibly even in a different process. The parameters are all integers and booleans, which are friendly to serialization.fileDataStart- fromlocalFileHeader.fileDataStartcompressedSize- fromentry.compressedSizerelativeStart- the resolved value ofoptions.startfromopenReadStream(). Must be a non-negative integer, notnull. Typically0to start at the beginning of the data.relativeEnd- the resolved value ofoptions.endfromopenReadStream(). Must be a non-negative integer, notnull. Typicallyentry.compressedSizeto include all the data.decompress- boolean indicating whether the data should be piped through a zlib inflate stream.uncompressedSize- fromentry.uncompressedSize. Only used whenvalidateEntrySizesistrue. IfvalidateEntrySizesisfalse, this value is ignored, but must still be present, not omitted, in the arguments; you have to give it some value, even if it'snull.callback- receives(err, readStream), the same as foropenReadStream()This low-level function does not read any metadata from the underlying storage before opening the read stream. This is both a performance feature and a safety hazard. None of the integer parameters are bounds checked. None of the validation from
openReadStream()with respect to compression and encryption is done here either. Only the bounds checks fromvalidateEntrySizesare done, because that is part of processing the stream data.Class: LocalFileHeader
This is a trivial class that has no methods and only the following properties. The constructor is available to call, but it doesn't do anything. See
readLocalFileHeader().See the zipfile spec for what these fields mean.
fileDataStart-Number: inferred fromfileNameLength,extraFieldLength, and this struct's position in the zipfile.versionNeededToExtract-NumbergeneralPurposeBitFlag-NumbercompressionMethod-NumberlastModFileTime-NumberlastModFileDate-Numbercrc32-NumbercompressedSize-NumberuncompressedSize-NumberfileNameLength-NumberextraFieldLength-NumberfileName-BufferextraField-BufferNote that unlike
Class: Entry, thefileNameandextraFieldare completely unprocessed. This notably lacks Unicode and ZIP64 handling as well as any kind of safety validation on the file name. See alsoparseExtraFields().Also note that if your object is missing some of these fields, make sure to read the docs on the
minimaloption inreadLocalFileHeader().