plugins.wcx
Interface WCXPluginInterface

All Known Implementing Classes:

WCXPluginAdapter

public interface WCXPluginInterface

This is the interface for Total Commander WCX plugins.

Author:

Ken

Field Summary

static int	E_BAD_ARCHIVE CRC error in archive data.
static int	E_BAD_DATA Data is bad.
static int	E_EABORTED Function aborted by user.
static int	E_ECLOSE Error closing file.
static int	E_ECREATE Cannot create file.
static int	E_END_ARCHIVE No more files in archive.
static int	E_EOPEN Cannot open existing file.
static int	E_EREAD Error reading from file.
static int	E_EWRITE Error writing to file.
static int	E_NO_FILES No files found.
static int	E_NO_MEMORY Not enough memory.
static int	E_NOT_SUPPORTED Function not supported.
static int	E_SMALL_BUF Buffer too small.
static int	E_TOO_MANY_FILES Too many files to pack.
static int	E_UNKNOWN_FORMAT Archive format unknown.
static int	MEM_OPTIONS_WANTHEADERS startMemPack(): The output stream should include the complete headers (beginning+end).
static int	MEMPACK_DONE packToMem(): DONE.
static int	MEMPACK_OK packToMem(): SUCCESS.
static int	PK_CAPS_BY_CONTENT getPackerCaps(): Detect archive type by content.
static int	PK_CAPS_DELETE getPackerCaps(): Can delete files.
static int	PK_CAPS_ENCRYPT getPackerCaps(): Plugin supports PK_PACK_ENCRYPT option.
static int	PK_CAPS_HIDE getPackerCaps(): Don't show packer icon, don't open with Enter but with Ctrl+PgDn.
static int	PK_CAPS_MEMPACK getPackerCaps(): Supports packing in memory.
static int	PK_CAPS_MODIFY getPackerCaps(): Can modify existing archives.
static int	PK_CAPS_MULTIPLE getPackerCaps(): Archive can contain multiple files.
static int	PK_CAPS_NEW getPackerCaps(): Can create new archives.
static int	PK_CAPS_OPTIONS getPackerCaps(): Has options dialog.
static int	PK_CAPS_SEARCHTEXT getPackerCaps(): Allow searching for text in archives created with this plugin.
static int	PK_EXTRACT processFile(): Extract to disk.
static int	PK_PACK_MOVE_FILES packFiles(): Delete original after packing.
static int	PK_PACK_SAVE_PATHS packFiles(): Save path names of files.
static int	PK_SKIP processFile(): Skip this file.
static int	PK_TEST processFile(): Test file integrity.
static int	PK_VOL_ASK setChangeVol(): Ask user for location of next volume.
static int	PK_VOL_NOTIFY setChangeVol(): Notify app that next volume will be unpacked.
static int	SUCCESS Success.

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.
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.
java.lang.Object	openArchive(OpenArchiveData archiveData) OpenArchive should return a unique handle representing the archive.
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.
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.
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.

Field Detail

SUCCESS

static final int SUCCESS

Success.

See Also:

Constant Field Values

E_END_ARCHIVE

static final int E_END_ARCHIVE

No more files in archive.

See Also:

Constant Field Values

E_NO_MEMORY

static final int E_NO_MEMORY

Not enough memory.

See Also:

Constant Field Values

E_BAD_DATA

static final int E_BAD_DATA

Data is bad.

See Also:

Constant Field Values

E_BAD_ARCHIVE

static final int E_BAD_ARCHIVE

CRC error in archive data.

See Also:

Constant Field Values

E_UNKNOWN_FORMAT

static final int E_UNKNOWN_FORMAT

Archive format unknown.

See Also:

Constant Field Values

E_EOPEN

static final int E_EOPEN

Cannot open existing file.

See Also:

Constant Field Values

E_ECREATE

static final int E_ECREATE

Cannot create file.

See Also:

Constant Field Values

E_ECLOSE

static final int E_ECLOSE

Error closing file.

See Also:

Constant Field Values

E_EREAD

static final int E_EREAD

Error reading from file.

See Also:

Constant Field Values

E_EWRITE

static final int E_EWRITE

Error writing to file.

See Also:

Constant Field Values

E_SMALL_BUF

static final int E_SMALL_BUF

Buffer too small.

See Also:

Constant Field Values

E_EABORTED

static final int E_EABORTED

Function aborted by user.

See Also:

Constant Field Values

E_NO_FILES

static final int E_NO_FILES

No files found.

See Also:

Constant Field Values

E_TOO_MANY_FILES

static final int E_TOO_MANY_FILES

Too many files to pack.

See Also:

Constant Field Values

E_NOT_SUPPORTED

static final int E_NOT_SUPPORTED

Function not supported.

See Also:

Constant Field Values

PK_SKIP

static final int PK_SKIP

processFile(): Skip this file.

See Also:

Constant Field Values

PK_TEST

static final int PK_TEST

processFile(): Test file integrity.

See Also:

Constant Field Values

PK_EXTRACT

static final int PK_EXTRACT

processFile(): Extract to disk.

See Also:

Constant Field Values

PK_PACK_MOVE_FILES

static final int PK_PACK_MOVE_FILES

packFiles(): Delete original after packing.

See Also:

Constant Field Values

PK_PACK_SAVE_PATHS

static final int PK_PACK_SAVE_PATHS

packFiles(): Save path names of files.

See Also:

Constant Field Values

PK_CAPS_NEW

static final int PK_CAPS_NEW

getPackerCaps(): Can create new archives.

See Also:

Constant Field Values

PK_CAPS_MODIFY

static final int PK_CAPS_MODIFY

getPackerCaps(): Can modify existing archives.

See Also:

Constant Field Values

PK_CAPS_MULTIPLE

static final int PK_CAPS_MULTIPLE

getPackerCaps(): Archive can contain multiple files.

See Also:

Constant Field Values

PK_CAPS_DELETE

static final int PK_CAPS_DELETE

getPackerCaps(): Can delete files.

See Also:

Constant Field Values

PK_CAPS_OPTIONS

static final int PK_CAPS_OPTIONS

getPackerCaps(): Has options dialog.

See Also:

Constant Field Values

PK_CAPS_MEMPACK

static final int PK_CAPS_MEMPACK

getPackerCaps(): Supports packing in memory.

See Also:

Constant Field Values

PK_CAPS_BY_CONTENT

static final int PK_CAPS_BY_CONTENT

getPackerCaps(): Detect archive type by content.

See Also:

Constant Field Values

PK_CAPS_SEARCHTEXT

static final int PK_CAPS_SEARCHTEXT

getPackerCaps(): Allow searching for text in archives created with this plugin.

See Also:

Constant Field Values

PK_CAPS_HIDE

static final int PK_CAPS_HIDE

getPackerCaps(): Don't show packer icon, don't open with Enter but with Ctrl+PgDn.

See Also:

Constant Field Values

PK_CAPS_ENCRYPT

static final int PK_CAPS_ENCRYPT

getPackerCaps(): Plugin supports PK_PACK_ENCRYPT option.

See Also:

Constant Field Values

MEM_OPTIONS_WANTHEADERS

static final int MEM_OPTIONS_WANTHEADERS

startMemPack(): The output stream should include the complete headers (beginning+end).

See Also:

Constant Field Values

MEMPACK_OK

static final int MEMPACK_OK

packToMem(): SUCCESS.

See Also:

Constant Field Values

MEMPACK_DONE

static final int MEMPACK_DONE

packToMem(): DONE.

See Also:

Constant Field Values

PK_VOL_ASK

static final int PK_VOL_ASK

setChangeVol(): Ask user for location of next volume.

See Also:

Constant Field Values

PK_VOL_NOTIFY

static final int PK_VOL_NOTIFY

setChangeVol(): Notify app that next volume will be unpacked.

See Also:

Constant Field Values

Method Detail

openArchive

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.

Parameters:

archiveData - The archive data being open

Returns:

A unique handle representing the archive

readHeader

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.

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

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.

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

int closeArchive(java.lang.Object archiveData)

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

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

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.

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

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

DeleteFiles should delete the specified files from the archive.

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

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.

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

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.

Parameters:

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

Returns:

Return a handle to your configuration window.

startMemPack

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.

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

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.

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

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.

Parameters:

hMemPack - is the handle returned by StartMemPack.

Returns:

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

canYouHandleThisFile

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.

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

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.

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

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.

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_...