jsCAB.dll Function Reference - v.1.07.224
jsCAB.dll is an ActiveX component that can be used to work with
CAB files. CAB files are a type of compressed storage file that was developed by Microsoft.
jsCAB.dll provides functionality to create CAB files, extract the content of CAB files,
and get information about CAB files.
If you just want to extract or create CAB files, you only
need to know how to use the functions in jsCAB.dll. Those are detailed below. If you want
to understand how all of this is working, there are 3 files here to know about:
jsCAB.dll is the script-accessible component that provides an object for dealing with CAB files.
jcabio.dll is a DLL embedded in jsCAB.dll. It cannot be used directly by script.
Rather, jcabio.dll acts as an intermediary between the script-friendly jsCAB.dll and the Windows
system CAB functions.
cabinet.dll is the Microsoft system file that provides functions related to CAB files.
Cabinet.dll cannot be used by VBScript, or even by VB. The C++ DLL embedded
in jsCAB.dll, jcabio.dll, "talks to" cabinet.dll and jsCAB.dll is the scripting-friendly
component that "talks to" jcabio.dll.
jsCAB.dll has a copy of jcabio.dll embedded in it. When jsCAB.dll needs jcabio.dll, it
writes a copy of that file to disk. For scripters that detail is irrelevant. However, anyone who wants
to use jcabio.dll directly, from VB, C++, etc., is free to do so. The jcabio.dll functions are documented here.
General Usage Information
jsCAB.dll needs to be registered before use. Just put the file
jsCAB.dll in a safe place, like the System folder, then drop it onto the RegSvr.vbs file
to register it.
There is one object available through jsCAB, created like so:
Set Obj = CreateObject("jsCAB.Ops")
The jsCAB.ops object provides functions to extract from CAB files,
create CAB files, get information about a CAB file, or convert a self-executing CAB file (EXE) to normal CAB.
Index
jsCAB.Ops Functions
Function ExtractCABFiles(vCABPath, vFolderPath)
Info: Extract all files from a CAB file.
Example:
Ret = Obj.ExtractCABFiles("C:\test.cab", "C:\Unpack folder")
vCABPath - Full path of CAB file.
vFolderPath - Full path of folder to extract to.
Notes: Both CAB file path and folder path must exist. Function will not create
the folder. All files are extracted. There is no option to only extract one specific file. (Use ExtractSingleFile for that.)
See the note about the
Solitary property of the CABInfo object for other considerations.
Return:
0 success.
-1 unsupported OS.
-2 invalid folder path.
-3 invalid CAB file path.
-4 (Not used for this function.)
> 0 - Cabinet.dll error. (
See Error Codes Table below. )
Back to Index
Function ExtractSingleFile(vCABPath, vFolderPath, vFileName)
Info: Extract one file from a CAB file.
Example:
Ret = Obj.ExtractSingleFile("C:\test.cab", "C:\Unpack folder", "file1.txt")
Notes: Both CAB file path and folder path must exist. Function will not create
the folder. See the note about the
Solitary property of the CABInfo object for other considerations.
Return:
0 success.
-1 unsupported OS.
-2 invalid folder path.
-3 invalid CAB file path.
-4 invalid file name for extraction.
> 0 - Cabinet.dll error. (
See Error Codes Table below. )
Back to Index
Function MakeCABFile(vCABPath, vFileList)
Info: Create a CAB file.
Example:
Ret = Obj.MakeCABFile("C:\newCAB.cab", "C:\file1.txt|C:\file2.bmp|C:\file3.gif|C:\Windows\Desktop\file4.txt|C:\file5.bmp")
vCABPath - Full path of CAB file to create.
vFileList - Pipe-delimited string of full file paths to be included in CAB file.
Notes: CAB file path must be valid. Parent folder will not be created. File list must be composed of valid, full
file paths. If one of the files does not exist, the method will fail.
Return:
0 success.
-1 unsupported OS.
-2 invalid folder path.
-3 invalid CAB file path.
-4 invalid file list.
> 0 - Cabinet.dll error. (
See Error Codes Table below. )
Back to Index
Function EXEtoCAB(vEXEPath, vCABPath)
Info: Convert a self-executing CAB (.exe) to CAB (.cab).
Example:
Ret = Obj.EXEtoCAB("C:\test.exe", "C:\text.cab")
vEXEPath - Full path of EXE file to convert.
vCABPath - Full path of CAB file to create.
Notes: Converts a standard self-executing CAB file (.exe) to a normal CAB file by stripping off
the EXE stub.
Return:
0 success.
-1 EXE path invalid.
-2 vEXEPath is not an EXE file.
-3 CAB file marker not found in file.
Back to Index
Function GetCABInfo(vCABPath)
Info: Get information about a CAB file.
Example:
Set CI = Obj.GetCABInfo("C:\test.cab")
vCABPath - Full path of CAB file.
Return: - Method returns a CABInfo object.
Back to Index
CABInfo Object
The CABInfo object is returned by GetCABInfo. A list of the CABInfo properties follows. Note that
all properties are returned as Variants in order to accomodate VBScript. The data types listed
below are the variant data "subtype".
IsValidCAB - Numeric - Must be 0. A return of 1 indicates CAB is an InstallShield CAB file
that requires a different unpacker. A return of 2 indicates file is not a CAB file.
If IsValidCAB returns other than 0, all other CABInfo properties will be blank.
Therefore, IsValidCAB should always be the first property checked before proceeding.
Solitary - Boolean - Is this a stand-alone CAB, rather than one in a series? When CABs are linked in
a series, as is the case with Windows OS installation CABs, files may span between 2 CABs. jsCAB.dll does
not handle extraction of spanning files. A CAB should return True for both IsValidCAB and Solitary
before you attempt extraction. If you try to extract from a linked CAB you will probably get most of the
files extracted, but then your script will hang.
Path - String - Returns full path of file that this CABInfo object represents.
FileCount - Numeric - Number of files in CAB.
FileList - Array - An array of file names in the CAB.
FileExists(Name) - Boolean - Does the CAB contain a file named [Name]?
FileName(index) - String - Returns name of file by index.
FileDate(index) - String - Returns date of file by index. Generally this will be LastModified date. It is in the format: m/d/y
FileSize(index) - Numeric - Returns size of file by index, in KB.
Notes: All files in the CAB can be documented by iterating via index:
For i = 0 to CI.FileCount - 1
sName - CI.FileName(i)
sDate = CI.FileDate(i)
nSize = CI.FileSize(i)
etc.
Accessing file information by index may seem like an odd way to
design the CABInfo object, but it is based on the structure of CAB files. Unlike
ZIP files, a CAB file is made by first stringing all of the files together, then
compressing the entire data stream. Each file has a specific position in the CAB.
The position index is also the file's index in the
FileList array. So, in
addition to the iteration method shown above, you can also access information about
specific files like so:
sName = "FileSought.bmp"
For i = 0 to UBound(CI.FileList)
If CI.FileList(i) = sName Then
sDate = CI.FileDate(i)
nSize = CI.FileSize(i)
Exit For
End If
Next
Back to Index
Using jcabio.dll (Not relevant for scripting)
jcabio.dll v. 1.0.7.219
jcabio.dll is free to use for any purpose.
Once jsCAB.dll has been used to create or extract from a CAB file, it will have written
a copy of jcabio.dll to disk in the same location. jcabio.dll is a standard C++ DLL. It exports
three functions, as detailed below:
MakeCAB
ExtractCAB
ExtractFile
The error codes for the returns on these functions are the same
as those in the error codes table (See next topic below.)
MakeCAB
C++ declare:
int WINAPI MakeCAB (LPSTR sCABFileName, LPSTR sDestFolder, int iNumFiles, LPSTR FileList);
VB declare:
Declare Function MakeCAB Lib "jcabio.dll" (ByVal sCABFileName As String, ByVal sDestFolder As String, ByVal iNumFiles As Long, ByVal sFileList As String) As Long
VB Example:
sFil = "test.cab"
sFol = "C:\windows\desktop\"
sFiles = "C:\windows\test1.txt|C:\windows\test2.txt|C:\windows\test3.txt|"
LNum = 3
LRet = MakeCAB(sfil, sfol, LNum, sFiles)
sDestFolder should be a folder path with a trailing backslash.
iNumFiles is number of files.
FileList must be pipe-delimited string of paths with pipe at end.
Unlike the COM object functions with jsCAB.Ops, jcabio.dll does not
check and correct incoming parameters. They must be correct or the method will fail.
Errors:
0 - success.
1 - invalid cab folder.
2 - invalid cab file name.
3 - no files to compress.
4 - no delimiter found in string of file paths. (happens if "|" at end is skipped.)
> 10 -
See Error Codes Table below.
ExtractCAB
C++ declare:
int WINAPI ExtractCAB (LPSTR sCABPath, LPSTR sDestFolder);
VB declare:
Declare Function ExtractCAB Lib "jcabio.dll" (ByVal sCABPath As String, ByVal sDestFolder As String) As Long
VB Example:
sfil = "C:\windows\test.cab"
sfol = "C:\Windows\unpackFolder\"
LRet = ExtractCAB(sfil, sfol)
As with the MakeCAB example, the sDestFolder parameter should be a folder
path with trailing backslash. In this example, files will be extracted to C:\Windows\unpackFolder.
(Ex.: C:\windows\unpackFolder\File1.txt) If the backslash is left off, files will be extracted
to C:\Windows. (Ex.: C:\windows\unpackFolderFile1.txt)
Errors:
1 - invalid cab path.
2 - invalid folder path.
3 - general failed CAB ops.
4 - failed to initialize cabinet.dll with FDICreate.
5 - failed to open file. probably invalid cab file.
6 - not a CAB file.
7 - failed extracting a file.
ExtractFile
C++ declare:
int WINAPI ExtractFile (LPSTR sCABPath, LPSTR sDestFolder, LPSTR sFileName)
VB declare:
Declare Function ExtractFile Lib "jcabio.dll" (ByVal sCABPath As String, ByVal sDestFolder As String, ByVal sFileName As String) As Long
ExtractFile is basically the same as
ExtractCAB. It extracts a single file. The extra,
third parameter is the name of the file to be extracted. The error codes are all the same as for
ExtractCAB, with one exception: There is an additional error 8 to indicate an empty file name parameter.
Errors:
1 - invalid cab path.
2 - invalid folder path.
3 - general failed CAB ops.
4 - failed to initialize cabinet.dll with FDICreate.
5 - failed to open file. probably invalid cab file.
6 - not a CAB file.
7 - failed extracting a file.
8 - file name missing.
Back to Index
Error Codes Table
In addition to the simple error codes returned by jsCAB (which are all negative numbers)
there are also positive-number error codes that represent errors returned by jcabio.dll or
cabinet.dll. These positive-number error codes are returned by the jcabio.dll functions, but they are
also forwarded through the jsCAB.dll functions when relevant. That is, if jsCAB's call to jcabio.dll
fails, jsCAB will return the jcabio.dll error.
Extended error information for MakeCABFile function (and MakeCAB function in jcabio.dll):
Note: The following error codes are returned from the
MakeCAB function in jcabio.dll. When
the jsCAB.dll function
MakeCABFile is used, it has its own error codes, which are negative numbers.
If the
MakeCABFile function fails internally, when calling jcabio.dll, the error code will
be some combination of the codes below. In other words, if a positive number is returned with
MakeCABFile,
it is a jcabio.dll error code being forwarded through jsCAB.dll.
General errors generated by jcabio.dll:
1 - invalid cab folder.
2 - invalid cab file name.
3 - invalid file list.
4 - no delimiter found in string of file paths. (happens if "|" at end is skipped.)
Errors returned from cabinet.dll functions:
10 - failed with create.
20 - failed with addfile.
30 - failed with flush.
40 - failed with destroy.
...plus...
1 "Failure opening file to be stored in cabinet"
2 "Failure reading file to be stored in cabinet"
3 "Insufficient memory in FCI"
4 "Could not create a temporary file"
5 "Unknown compression type"
6 "Could not create cabinet file"
7 "Client requested abort"
8 "Failure compressing data"
Example: If a file path is not valid it may return 21, which
means (20) error happened with cabinet.dll when trying to add file to cab and
(1) failed to open file to be stored in cab.
So possible errors are 1-4, 11-18, 21-28, 31-38 and 41-48.
Extended error information for ExtractCABFiles function (and ExtractCAB function in jcabio.dll):
Note: The functions in jsCAB.dll
ExtractCABFiles and
ExtractSingleFile, return negative
error codes when an error occurs in jsCAB.DLL. If a positive number error code is returned, that error
has been forwarded through from jcabio.dll. Those errors are listed below. This is also the error listing for
the
ExtractCAB and
ExtractFile functions in jcabio.dll.
1 - invalid cab path.
2 - invalid folder path.
3 - general failed CAB ops.
4 - failed to initialize cabinet.dll with FDICreate.
5 - failed to open file. probably invalid cab file.
6 - not a CAB file.
7 - failed extracting a file.
8 - file name for extraction missing. (ExtractFile or ExtractSingleFile only)
Back to Index
License:
You use all script code and components from JSWare at your own risk.
The components (compiled DLL and EXE files) may be used for personal or
commercial purposes. No payment or attribution is required for either use.
The components may be redistributed if they are required as support files
for scripts or software that you have written.
Also, the script code may be used freely, in part or as whole scripts,
for any purpose, personal or commercial, without payment or attribution.
I ask only that you not redistribute these scripts and components, except
as required for your direct use. Instead, please direct others to obtain copies
of JSWare scripts and components directly from www.jsware.net.
Also, none of the code here may be redistributed under another license. If a
work using code from JSWare is distributed with restrictions of any kind
the code from JSWare must be kept exempt from those restrictions.
This includes, but is not limited to, code sold for profit, code with usage restrictions
and code distributed as so-called "Open Source" with redistribution restrictions.
Joe Priestley