plugins.wcx
Class WCXPluginAdapter

java.lang.Object
  plugins.wcx.WCXPluginAdapter

All Implemented Interfaces:

WCXPluginInterface

public abstract class WCXPluginAdapter
extends java.lang.Object
implements WCXPluginInterface

Author:

Ken

Field Summary

Fields inherited from interface plugins.wcx.WCXPluginInterface

E_BAD_ARCHIVE, E_BAD_DATA, E_EABORTED, E_ECLOSE, E_ECREATE, E_END_ARCHIVE, E_EOPEN, E_EREAD, E_EWRITE, E_NO_FILES, E_NO_MEMORY, E_NOT_SUPPORTED, E_SMALL_BUF, E_TOO_MANY_FILES, E_UNKNOWN_FORMAT, MEM_OPTIONS_WANTHEADERS, MEMPACK_DONE, MEMPACK_OK, PK_CAPS_BY_CONTENT, PK_CAPS_DELETE, PK_CAPS_ENCRYPT, PK_CAPS_HIDE, PK_CAPS_MEMPACK, PK_CAPS_MODIFY, PK_CAPS_MULTIPLE, PK_CAPS_NEW, PK_CAPS_OPTIONS, PK_CAPS_SEARCHTEXT, PK_EXTRACT, PK_PACK_MOVE_FILES, PK_PACK_SAVE_PATHS, PK_SKIP, PK_TEST, PK_VOL_ASK, PK_VOL_NOTIFY, SUCCESS

Constructor Summary

WCXPluginAdapter()

Method Summary

boolean	canYouHandleThisFile(java.lang.String fileName) CanYouHandleThisFile allows the plugin to handle files with different extensions than the one defined in Total Commander.
abstract int	closeArchive(java.lang.Object archiveData) CloseArchive should perform all necessary operations when an archive is about to be closed.
int	configurePacker(int parentWin) ConfigurePacker gets called when the user clicks the Configure button from within "Pack files..." dialog box in Totalcmd.
int	deleteFiles(java.lang.String packedFile, java.lang.String deleteList) DeleteFiles should delete the specified files from the archive.
int	doneMemPack(java.lang.Object hMemPack) DoneMemPack ends packing into memory.
int	getPackerCaps() GetPackerCaps tells Totalcmd what features your packer plugin supports.
abstract java.lang.Object	openArchive(OpenArchiveData archiveData) OpenArchive should return a unique handle representing the archive.
int	packerSetChangeVol(java.lang.String arcName, int mode) When you want the user to be asked about changing volume, call this function with appropriate parameters.
int	packerSetProcessData(java.lang.String fileName, int size) The function that notifies the user about the progress when un/packing files.
int	packFiles(java.lang.String packedFile, java.lang.String subPath, java.lang.String srcPath, java.lang.String addList, int flags) PackFiles specifies what should happen when a user creates, or adds files to the archive.
void	packSetDefaultParams(DefaultParam dps) PackSetDefaultParams is called immediately after loading the DLL, before any other function.
int	packToMem(java.lang.Object hMemPack, java.lang.String bufIn, int inLen, java.lang.String bufOut, int outLen, int seekBy, PackToMem packToMem) PackToMem packs the next chunk of data passed to it and/or returns the compressed data to the calling program.
abstract int	processFile(java.lang.Object archiveData, int operation, java.lang.String destPath, java.lang.String destName) ProcessFile should unpack the specified file or test the integrity of the archive.
abstract int	readHeader(java.lang.Object archiveData, HeaderData headerData) Totalcmd calls ReadHeader to find out what files are in the archive.
int	readHeaderEx(java.lang.Object archiveData, HeaderDataEx headerDataEx) Totalcmd calls ReadHeaderEx to find out what files are in the archive.
java.lang.Object	startMemPack(int options, java.lang.String fileName) StartMemPack starts packing into memory.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

WCXPluginAdapter

public WCXPluginAdapter()

Method Detail

openArchive

public abstract java.lang.Object openArchive(OpenArchiveData archiveData)

OpenArchive should return a unique handle representing the archive. The handle should remain valid until CloseArchive is called. If an error occurs, you should return zero, and specify the error by setting OpenResult member of ArchiveData.
OpenArchive should perform all necessary operations when an archive is to be opened.
You can use the ArchiveData to query information about the archive being open, and store the information in ArchiveData to some location that can be accessed via the handle.

Specified by:

openArchive in interface WCXPluginInterface

Parameters:

archiveData - The archive data being open

Returns:

A unique handle representing the archive

readHeader

public abstract int readHeader(java.lang.Object archiveData,
                               HeaderData headerData)

Totalcmd calls ReadHeader to find out what files are in the archive.
ReadHeader is called as long as it returns zero (as long as the previous call to this function returned zero). Each time it is called, HeaderData is supposed to provide Totalcmd with information about the next file contained in the archive. When all files in the archive have been returned, ReadHeader should return E_END_ARCHIVE which will prevent ReaderHeader from being called again. If an error occurs, ReadHeader should return one of the error values or 0 for no error. In short, you are supposed to set at least PackSize, UnpSize, FileTime, and FileName members of tHeaderData. Totalcmd will use this information to display content of the archive when the archive is viewed as a directory.

Specified by:

readHeader in interface WCXPluginInterface

Parameters:

archiveData - Contains the handle returned by OpenArchive. The programmer is encouraged to store other information in the location that can be accessed via this handle. For example, you may want to store the position in the archive when returning files information in ReadHeader.

headerData - HeaderData is supposed to provide Totalcmd with information about the next file contained in the archive.

Returns:

SUCCESS or E_END_ARCHIVE or error codes E_...

processFile

public abstract int processFile(java.lang.Object archiveData,
                                int operation,
                                java.lang.String destPath,
                                java.lang.String destName)

ProcessFile should unpack the specified file or test the integrity of the archive. Unlike PackFiles, ProcessFile is passed only one filename. When Total Commander first opens an archive, it scans all file names with OpenMode==PK_OM_LIST, so ReadHeader() is called in a loop with calling ProcessFile(...,PK_SKIP,...). When the user has selected some files and started to decompress them, Total Commander again calls ReadHeader() in a loop. For each file which is to be extracted, Total Commander calls ProcessFile() with Operation==PK_EXTRACT immediately after the ReadHeader() call for this file. If the file needs to be skipped, it calls it with Operation==PK_SKIP.
Each time DestName is set to contain the filename to be extracted, tested, or skipped.

Specified by:

processFile in interface WCXPluginInterface

Parameters:

archiveData - contains the handle previously returned by you in OpenArchive. Using this, you should be able to find out information (such as the archive filename) that you need for extracting files from the archive.

operation - Operation is set to one of the following:

• PK_SKIP - Skip this file
• PK_TEST - Test file integrity
• PK_EXTRACT - Extract to disk

destPath - Either DestName contains the full path and file name and DestPath is NULL, or DestName contains only the file name and DestPath the file path. This is done for compatibility with unrar.dll.

destName - Either DestName contains the full path and file name and DestPath is NULL, or DestName contains only the file name and DestPath the file path. This is done for compatibility with unrar.dll.

Returns:

ProcessFile should return SUCCESS or one of the error values otherwise.

closeArchive

public abstract int closeArchive(java.lang.Object archiveData)

CloseArchive should perform all necessary operations when an archive is about to be closed.

Specified by:

closeArchive in interface WCXPluginInterface

Parameters:

archiveData - refers to the value returned by a programmer within a previous call to OpenArchive.

Returns:

CloseArchive should return SUCCESS or one of the error values otherwise. It should free all the resources associated with the open archive.

packFiles

public int packFiles(java.lang.String packedFile,
                     java.lang.String subPath,
                     java.lang.String srcPath,
                     java.lang.String addList,
                     int flags)

PackFiles specifies what should happen when a user creates, or adds files to the archive.

Specified by:

packFiles in interface WCXPluginInterface

Parameters:

packedFile - refers to the archive that is to be created or modified. The string contains the full path.

subPath - is either NULL, when the files should be packed with the paths given with the file names, or not NULL when they should be placed below the given subdirectory within the archive. Example:

• SubPath="subdirectory"
• Name in AddList="subdir2\filename.ext"

-> File should be packed as "subdirectory\subdir2\filename.ext"

srcPath - contains path to the files in AddList. SrcPath and AddList together specify files that are to be packed into PackedFile.

addList - Each string in AddList is zero-delimited (ends in zero), and the AddList string ends with an extra zero byte, i.e. there are two zero bytes at the end of AddList.

flags - can contain a combination of the following values reflecting the user choice from within Totalcmd:

• PK_PACK_MOVE_FILES
• PK_PACK_SAVE_PATHS

Returns:

PackFiles should return SUCCESS or one of the error values otherwise.

deleteFiles

public int deleteFiles(java.lang.String packedFile,
                       java.lang.String deleteList)

DeleteFiles should delete the specified files from the archive.

Specified by:

deleteFiles in interface WCXPluginInterface

Parameters:

packedFile - contains full path and name of the the archive.

deleteList - contains the list of files that should be deleted from the archive. The format of this string is the same as AddList within PackFiles.

Returns:

DeleteFiles should return SUCCESS or one of the error values otherwise.

getPackerCaps

public int getPackerCaps()

GetPackerCaps tells Totalcmd what features your packer plugin supports.
Important note:
If you change the return values of this function, e.g. add packing support, you need to reinstall the packer plugin in Total Commander, otherwise it will not detect the new capabilities.

Specified by:

getPackerCaps in interface WCXPluginInterface

Returns:

Implement GetPackerCaps to return a combination of the following values:

• PK_CAPS_NEW
• PK_CAPS_MODIFY
  
  Omitting PK_CAPS_NEW and PK_CAPS_MODIFY means PackFiles will never be called and so you don’t have to implement PackFiles.
  
  
• PK_CAPS_MULTIPLE
  
  Omitting PK_CAPS_MULTIPLE means PackFiles will be supplied with just one file.
  
  
• PK_CAPS_DELETE
  
  Leaving out PK_CAPS_DELETE means DeleteFiles will never be called.
  
  
• PK_CAPS_OPTIONS
  
  leaving out PK_CAPS_OPTIONS means ConfigurePacker will not be called.
  
  
• PK_CAPS_MEMPACK
  
  PK_CAPS_MEMPACK enables the functions StartMemPack, PackToMem and DoneMemPack.
  
  
• PK_CAPS_BY_CONTENT
  
  If PK_CAPS_BY_CONTENT is returned, Totalcmd calls the function CanYouHandleThisFile when the user presses Ctrl+PageDown on an unknown archive type.
  
  
• PK_CAPS_SEARCHTEXT
  
  If PK_CAPS_SEARCHTEXT is returned, Total Commander will search for text inside files packed with this plugin. This may not be a good idea for certain plugins like the diskdir plugin, where file contents may not be available.
  
  
• PK_CAPS_HIDE
  
  Finally, if PK_CAPS_HIDE is set, the plugin will not show the file type as a packer. This is useful for plugins which are mainly used for creating files, e.g. to create batch files, avi files etc. The file needs to be opened with Ctrl+PgDn in this case, because Enter will launch the associated application.
  
  

configurePacker

public int configurePacker(int parentWin)

ConfigurePacker gets called when the user clicks the Configure button from within "Pack files..." dialog box in Totalcmd. Usually, you provide a user with a dialog box specifying a method and/or its parameters that should be applied in the packing process. Or, you just want to display a message box about what your plugin is, just like Christian Ghisler’s DiskDir does.

You may decide not to implement this function. Then, make sure you omit PK_CAPS_OPTIONS from return values of GetPackerCaps.

Specified by:

configurePacker in interface WCXPluginInterface

Parameters:

parentWin - That is, you make your dialog box a child of Parent.

Returns:

Return a handle to your configuration window.

startMemPack

public java.lang.Object startMemPack(int options,
                                     java.lang.String fileName)

StartMemPack starts packing into memory. This function is only needed if you want to create archives in combination with TAR, e.g. TAR.BZ2. It allows Totalcmd to create a TAR.Plugin file in a single step.

Specified by:

startMemPack in interface WCXPluginInterface

Parameters:

options - Options can contain a combination of the following values:

• MEM_OPTIONS_WANTHEADERS

fileName - refers to the name of the file being packed - some packers store the name in the local header.

Returns:

StartMemPack should return a user-defined handle (e.g. pointer to a structure) on success, zero otherwise.

packToMem

public int packToMem(java.lang.Object hMemPack,
                     java.lang.String bufIn,
                     int inLen,
                     java.lang.String bufOut,
                     int outLen,
                     int seekBy,
                     PackToMem packToMem)

PackToMem packs the next chunk of data passed to it and/or returns the compressed data to the calling program. It is implemented together with StartMemPack and DoneMemPack. PackToMem is the most complex function of the packer plugin. It is called by Total Commander in a loop as long as there is data to be packed, and as there is data to retrieve. The plugin should do the following:

1. As long as there is data sent through BufIn, take it and add it to your internal buffers (if there is enough space).
2. As soon as there is enough data in the internal input buffers, start packing to the output buffers.
3. As soon as there is enough data in the internal output buffers, start sending data to BufOut.
4. When InLen is 0, there is no more data to be compressed, so finish sending data to BufOut until no more data is in the output buffer.
5. When there is no more data available, return 1.
6. There is no obligation to take any data through BufIn or send any through BufOut. Total Commander will call this function until it either returns 1, or an error.

Specified by:

packToMem in interface WCXPluginInterface

Parameters:

hMemPack - is the handle returned by StartMemPack()

bufIn - is a pointer to the data which needs to be packed

inLen - contains the number of bytes pointed to by BufIn

bufOut - is a pointer to a buffer which can receive packed data

outLen - contains the size of the buffer pointed to by BufOut

seekBy - May by set to the offset from the current output posisition by which the file pointer has to be moved BEFORE accepting the data in BufOut. This allows the plugin to modify a file header also AFTER packing, e.g. to write a CRC to the header.

packToMem - has to receive infos about the operation of this method.

Returns:

PackToMem should return MEMPACK_OK on success, MEMPACK_DONE when done, or one of the error values otherwise.

doneMemPack

public int doneMemPack(java.lang.Object hMemPack)

DoneMemPack ends packing into memory. This function is used together with StartMemPack and PackToMem.
It may be called in two different cases:

1. The packing functions have completed successfully, or
2. The user has aborted the packing operation.

The plugin should free all data allocated when packing.

Specified by:

doneMemPack in interface WCXPluginInterface

Parameters:

hMemPack - is the handle returned by StartMemPack.

Returns:

oneMemPack should return SUCCESS, or one of the error codes otherwise.

canYouHandleThisFile

public boolean canYouHandleThisFile(java.lang.String fileName)

CanYouHandleThisFile allows the plugin to handle files with different extensions than the one defined in Total Commander. It is called when the plugin defines PK_CAPS_BY_CONTENT, and the user tries to open an archive with Ctrl+PageDown.

Specified by:

canYouHandleThisFile in interface WCXPluginInterface

Parameters:

fileName - contains the fully qualified name (path+name) of the file to be checked.

Returns:

CanYouHandleThisFile should return true (nonzero) if the plugin recognizes the file as an archive which it can handle. The detection must be by contents, NOT by extension. If this function is not implemented, Totalcmd assumes that only files with a given extension can be handled by the plugin.

packSetDefaultParams

public void packSetDefaultParams(DefaultParam dps)

PackSetDefaultParams is called immediately after loading the DLL, before any other function. This function is new in version 2.1. It requires Total Commander >=5.51, but is ignored by older versions.
Important note:
This function is only called in Total Commander 5.51 and later. The plugin version will be >= 2.1.

Specified by:

packSetDefaultParams in interface WCXPluginInterface

Parameters:

dps - This object currently contains the version number of the plugin interface, and the suggested location for the settings file (ini file). It is recommended to store any plugin-specific information either directly in that file, or in that directory under a different name. Make sure to use a unique header when storing data in this file, because it is shared by other file system plugins! If your plugin needs more than 1kbyte of data, you should use your own ini file because ini files are limited to 64k.

readHeaderEx

public int readHeaderEx(java.lang.Object archiveData,
                        HeaderDataEx headerDataEx)

Totalcmd calls ReadHeaderEx to find out what files are in the archive. This function is always called instead of ReadHeader if it is present. It only needs to be implemented if the supported archive type may contain files >2 GB. You should implement both ReadHeader and ReadHeaderEx in this case, for compatibility with older versions of Total Commander.

ReadHeaderEx is called as long as it returns zero (as long as the previous call to this function returned zero). Each time it is called, HeaderDataEx is supposed to provide Totalcmd with information about the next file contained in the archive. When all files in the archive have been returned, ReadHeaderEx should return E_END_ARCHIVE which will prevent ReaderHeaderEx from being called again. If an error occurs, ReadHeaderEx should return one of the error values or 0 for no error.

In short, you are supposed to set at least PackSize, PackSizeHigh, UnpSize, UnpSizeHigh, FileTime, and FileName members of tHeaderDataEx. Totalcmd will use this information to display content of the archive when the archive is viewed as a directory.

Specified by:

readHeaderEx in interface WCXPluginInterface

Parameters:

archiveData - contains the handle returned by OpenArchive. The programmer is encouraged to store other information in the location that can be accessed via this handle. For example, you may want to store the position in the archive when returning files information in ReadHeaderEx.

headerDataEx - HeaderDataEx is supposed to provide Totalcmd with information about the next file contained in the archive.

Returns:

SUCCESS or E_END_ARCHIVE or error codes E_...

packerSetChangeVol

public final int packerSetChangeVol(java.lang.String arcName,
                                    int mode)

When you want the user to be asked about changing volume, call this function with appropriate parameters. The function itself is part of Totalcmd - you only specify the question. Totalcmd then asks the user, and you get the answer as the result of the call to this function.

Parameters:

arcName - specifies the filename of the archive that you are processing, and will receive the name of the next volume.

mode - Set Mode to one of the following values, according to what you want Totalcmd to ask the user:

• PK_VOL_ASK
• PK_VOL_NOTIFY

Returns:

If the user has aborted the operation, the function returns zero.

packerSetProcessData

public final int packerSetProcessData(java.lang.String fileName,
                                      int size)

The function that notifies the user about the progress when un/packing files. When you want to notify the user about the progress when un/packing files, call this function with appropriate parameters. The function itself is part of Totalcmd - you only specify what Totalcmd should display. In addition, Totalcmd displays the Cancel button that allows the user to abort the un/packing process.

Parameters:

fileName - can be used to pass a pointer to the currently processed filename, or NULL if it is not available.

size - Size to the number of bytes processed since the previous call to the function.

Returns:

If the user has clicked on Cancel, the function returns zero.