Xbuilder Zip Archive Function

This section describes the archive function added to Xbuilder. We will describe in detail
the new function and how to use it.

ZipNew()
Syntax
Zipnew() -> nZipHandle
Arguments
None
Returns
Handle of the new Zip object. If there was an error while initializing the object the
return value is NULL
Description
This is the first function that you have to call before using any other archive
function .You will use nZiphandle in other archive function to manage different
aspect of the archive file.

ZipSetCompressLevel()
Syntax
ZipSetCompressLevel(nZipHandle,nLevel) -> nError
Arguments
nZipHandle
nLevel

handle of the archive object obtained with Zipnew()

Level of compression you want.

Returns
0
-1

successful
bad zip handle

Description

This function set the compression level you want to use for the Zip object. The
value range are 0 to 9 (9 is the best compression level). Setting nLevel to -1 will
set compression level to the default value which is 6

ZipSetPassword()
Syntax
ZipSetPassword( nZipHandle, cPassword)
Arguments
nZipHandle
cPassword

handle of the archive object obtained with Zipnew()

password you want to use for the Zip object

Returns
None
Description
Set the password for the file to be add or read. Use this function BEFORE adding
file to your archive, but AFTER opening an archive. If you want to reset the
password just set cPassword to NULL.

ZipSetReadOnly()
Syntax
ZipSetReadOnly( nZipHandle, lReadOnly )
Arguments
nZipHandle
lReadonly
Returns
None
Description

handle of the archive object obtained with Zipnew()

logical value that will set the read only attribute for the Zip object.

This function control in witch mode the archive file will be open. When the
archive file is on a media without write access you MUST set the Zip object to
True. By not doing this the Zipopen() function will fail.

ZipSetExtractPath()
Syntax
ZipSetExtractPath( nZipHandle, cPath )
Arguments
nZipHandle
cPath

handle of the archive object obtained with Zipnew()

string value that will set the path of the Zip object

Returns
None
Description
This function will set the path where you want to extract the file(s) that are in
your archive file. If the archive file was created with ZipSetFilePath() set to .T.
The path of the file in the archive will be expand starting from cPath
******* Patrick dont document that function for now !

ZipSetRootPath()
Syntax
ZipSetExtractPath( nZipHandle, cPath )
Arguments
nZipHandle
cPath
Returns
None
Description

handle of the archive object obtained with Zipnew()

string value that will set the path of the Zip object

Use it if you don't want to set ZipSetFilePath to true and you don't want to strip
the whole path neither, but only a specific beginning. Use it AFTER opening the
archive and before using function to add or extract files from your archive.

************
ZipSetOnDisk()
Syntax
ZipSetOnDisk( nZipHandle, bBlock )
Arguments
nZipHandle
bBlock

handle of the archive object obtained with Zipnew()

Codeblock, the codeblock automatically receive the Disk
number as a Numeric

Returns
None
Description
This function set the codeblock that will be call when you compress or extract
file on removable media and there is a need for a new media. When compressing
file on a removable media and the media is full the codeblock will be call with the
media number as a paramater, by doing this youll be able to Alert the user to put
a blank media to continue the process. When extracting file from a removable
media this codeblock is call when the Zip object have finish with the current
media and need the next in the archive sequence.

ZipSetAct()
Syntax
ZipSetAct( nZipHandle, bBlock )
Arguments
nZipHandle
bBlock
to the
Returns

handle of the archive object obtained with Zipnew()

Codeblock, the codeblock automatically receive 2 numeric
parameters the first one is the file position that will be add
archive file the second on is the total of file to process

None
Description
This function set the codeblock that will be call when you compress file and it
will be call each time the Zip function add a file to your archive file.

ZipSetBuffer()
Syntax
ZipSetBuffer( nZipHandle, nWriteBufLen, nGenBufLen, nSeaBufLen )- >nError
Arguments
nZipHandle handle of the archive object obtained with Zipnew()
nWriteBufLen Len of the write cash buffer for the Zip object
nGenbufLen Len of the buffer used when extracting and compressing file
nSeaBufLen Len of the buffer used when searching for file in the archive file.
Returns
0
-1

Successful
bad zip handle

Description
Normally youll not use this function, but it can be useful to tune up the
extract/compress cycle. The default value in parameters order are 65536, 65536,
32768 . When you call this function if you omit one of the buffers setting the Zip
object will be reset to his default value. You cant set any of these buffer lower
than 1024. Be careful the buffer setting is directly related to the memory use
by the Zip object.

ZipSetGlobalComment()
Syntax
ZipSetGlobalComment( nZipHandle, cComment )
Arguments
nZipHandle
cComment

handle of the archive object obtained with Zipnew()

the comment that you want to add the the archive file.

Returns
None
Description
Set the comment that will be added to your archive file. Calling this function
without cComment will set the comment for the archive file to NULL

ZipSetFilePath()
Syntax
ZipSetFilePath( nZipHandle, lWithPath ) -> nError
Arguments
nZipHandle
lWithPath

handle of the archive object obtained with Zipnew()

Logical value that set the path option of the Zip object

Returns
0
-1

successful
bad zip handle

Description
For Compressing:
If you set lWithpath to true all the file added to your archive file will contain its
original path location. If you set lWithPath to false, all the path information will
be extract from the filename before storing the file in the archive file.
For Extracting:
If you set lWithpath to true and the file in your archive file contain their path
information all the file will be expand starting at GetExtractPath().If you set
lWithPath to false all the path information will be removed from the file name in
the archive and the file will be extracted to GetExtractPath().

ZipSetFiles()
Syntax
ZipSetFiles( nZipHandle, aFiles) -> nError
Arguments
nZipHandle
aFiles

is the handle of the archive object obtained with Zipnew()

is the array of files that you want to add to your archive file

Returns
0
-1

Successful
error

Description
This function will automatically delete ALL files in the archive file and add the
the new one specified in aFiles. If the value return is -1 use ZipGetLastError() to
retrieve the error number

ZipGetCompressLevel()
Syntax
ZipGetCompressLevel( nZipHandle ) -> nLevel
Arguments
nZipHandle

handle of the archive object obtained with Zipnew()

Returns
-2 Bad Zip handle
-1 invalid compress level
otherwise the compress level of the Zip object

ZipGetPassword()
Syntax

ZipGetPassword( nZipHandle ) -> cPassword

Arguments
nZipHandle

handle of the archive object obtained with Zipnew()

Returns
The password of the Zip object if there is no password it return NULL

ZipGetReadOnly()
Syntax
ZipGetReadOnly( nZipHandle) -> lReadOnly
Arguments
nZipHandle

handle of the archive object obtained with Zipnew()

Returns
If the Zip object will open the archive file in read only this function return True

ZipGetExtractPath()
Syntax
ZipGetExtractPath( nZipHandle ) -> cPath
Arguments
nZipHandle

handle of the archive object obtained with Zipnew()

Returns
The path where the file in the archive will be extract to.
Patrick those function are doing the same for now and will not be documented !
***********

ZipGetOnDisk()

Question : Same as ZipSetOnDisk() ??

ZipGetAct()

Question: Same as ZipSetAct() ??

*****************
ZipGetBuffer()
Syntax
ZipGetBuffer( nZipHandle, @nWritebuf, @nGenBuf, @nSeaBuf) -> nError
Arguments
nZipHandle
nWritebuf
nGenBuf
nSeaBuf

is the handle of the archive object obtained with Zipnew()

numeric value pass by reference
numeric value pass by reference
numeric value pass by reference

Returns
0
-1

successful
Bad zip Handle

Description
This Function will retrieve the actual buffer value, all 4 parameters are
mandatory.

ZipGetGlobalComment()
Syntax
ZipGetGlobalCoomment( nZipHandle ) -> cComment
Arguments
nZipHandle

is the handle of the archive object obtained with Zipnew()

Returns
The comment of the current open archive file or for the current Zip object.

ZipGetFilePath()

Syntax
ZipGetFilePath( nZipHandle ) -> lWithPath
Arguments
nZipHandle

is the handle of the archive object obtained with Zipnew()

Returns
A logical value
Description
This function will tell you if the current Zip object will expand the path for
the filename when extracting or compressing the file in/from your archive.
IF the return value is .T. and you are archiving the file the path information will
Be kept in the archive file, if you are extracting file the path will be expand
starting from the ZipGetExtractPath().

ZipCreate()
Syntax
ZipCreate( nZipHandle, cZipfilename, nMode) -> nError
Arguments
nZipHandle handle of the archive object obtained with Zipnew()
cZipFilename name of the Archive file to be create
nMode
Which mode to use default is 0
0 standard Zip file
1 PKZIP spanning compatible mode (removable media)
2 TDSPAN spanning compatible mode on HD
Returns
0
-1

successful
Bad zip handle or Error

Description
This function create the archive file .If you use PKZIP or TDSPAN mode dont
forget to set a codeblock with SetOnDisk() this codeblock is needed when

removable media must be change. Once the archive file is created you can add
files to your archive with ZipAddFiles(), ZipAddFile() or ZipSetFiles().

ZipOpen()
Syntax
ZipOpen( nZipHandle, cFilename, nMode ) -> nError
Arguments
nZipHandle
cFilename
nMode

handle of the archive object obtained with Zipnew()

Archive file to open
open mode default 0
0 standard Zip mode
1 PKZIP spanning compatible mode (removable media)
2 TDSPAN spanning compatible mode on HD

Returns
0
-1

successful
Bad zip handle or error

Description
Open an existing Archive file. After opening the archive file you can add or
replace file in the archive with ZipAddfiles(), ZipAddFile() or ZipSetFiles(). You
will also be able to extract files from the archive with ZipExtractFiles()

ZipAddFiles()
Syntax
ZipAddFiles( nZipHandle, aFiles ) -> nError
Arguments
nZipHandle
aFiles

handle of the archive object obtained with Zipnew()

array of files that you want to add to your archive file

Returns
0
-1

successful
Bad zip handle or error

Description
This function will automatically add all the files in aFiles to your archive file. If
the archive file contain the same filename it will be delete and the new one will be
add. . If the value return is -1 use ZipGetLastError() to retrieve the error number.

ZipAddFile()
Syntax
ZipAddFile( nZipHandle, cFile ) -> nError
Arguments
nZipHandle
cFile

handle of the archive object obtained with Zipnew()

name of the file to add to your archive file

Returns
0
-1

successful
bad zip handle or error

Description
This function will automatically add the file to your archive file. If the archive file
contain the same filename it will be delete and the new one will be add. . If the
value return is -1 use ZipGetLastError() to retrieve the error number.

ZipClose()
Syntax
ZipClose( nZipHandle ) -> lReturn
Arguments
nZipHandle
Returns
Always true

handle of the archive object obtained with Zipnew()

Description
This is the last function that youll call it close the Archive file and destroy the
Zip object.

ZipExtractFiles()
ZipExtractFiles( nZipHandle ) ->nError
Arguments
nZipHandle

handle of the archive object obtained with Zipnew()

Returns
0
-1

successful
bad zip handle or error

Description
This function will extract all files in the archive file opened with Zipopen().If the
value return is -1 use ZipGetLastError() to retrieve the error number.

ZipSetFiles()
Syntax
ZipSetFiles( nZipHandle, aFiles) -> nError
Arguments
nZipHandle
aFiles

is the handle of the archive object obtained with Zipnew()

is the array of files that you want to add to your archive file

Returns
0
-1

no error
bad zip handle or error

Description
This function will automatically delete ALL files in the archive file and add the
the new one specified in aFiles. If the value return is -1 use ZipGetLastError() to

Retrieve the error number.

ZipGetLastError()
Syntax
ZipGetLastError( nZipHandle) -> nError
Arguments
nZipHandle

is the handle of the archive object obtained with Zipnew()

Returns
100
101
102
103
104
105
106
damage in the
107
108
109
110
111
112
113
114
115
116
when
500
501
502
503
504

unknown error
damaged or not a zip file
crc mismatched
no disk-spanning callback function set
callback function returned false while disk change in the diskspanning archive
callback function returned false in ZipAddFile(),
ZipAddFiles(),ZipSetfiles(),ZipExtractFiles()
the same as above, you may be sure that the operation was
successfully completed before or it didn't cause any
archive
the disk selected for pkzipSpan archive is non removable
limit of the maximum volumes reached (999)
the filename of the file added to the archive is too long
incorrect password set for the file being decrypted
during testing: found the directory with the size greater than 0
internal error
error while removing a file (under Windows call GetLastError() to
find out more)
error while renaming a file (under Windows call GetLastError() to
find out more)
the platform that the zip file is being created for is not supported
the central directory was not found in the archive (it is thrown also
when the last disk of multi-disk archive is not in the drive
opening the archive)
zlib library error
zlib library error
zlib library error
zlib library error
zlib library error

505
506
507

zlib library memory error

zlib library buffer error
zlib library version error