wcxhead.rs

Definitions of error codes, flags and callbacks for Total Commander packer plugins

Documentation

Examples

A plugin using this crate can be found here.

Special thanks

To all who support further development on Patreon, in particular:

• ThePhD

lib.rs:

Contents of file wcxhead.h It contains definitions of error codes, flags and callbacks

Error Codes

Use the following values when you want to inform Totalcmd that an error ocurred.

Unicode Support

With Total Commander 7.5 (packer plugin interface 2.20), Unicode support has been added to all plugin types. In principle, you need to implement the same functions as for ANSI, with two differences: The function name is changed from FunctionName to FunctionNameW, and Ansi strings are changed to wide char names.

Total Commander will call the Unicode functions on all NT-based systems (Windows NT, 2000, XP) if they are present. If not, or on Windows 9x/ME, Total Commander will call the Ansi functions.

The following functions of the packer plugin interface support Unicode:

OpenArchiveW
ReadHeaderExW
ProcessFileW
SetChangeVolProcW
SetProcessDataProcW
PackFilesW
DeleteFilesW
StartMemPackW
CanYouHandleThisFileW

The following functions do not exist in a Unicode form and must be implemented as Ansi:

ReadHeader - use ReadHeaderEx
CloseArchive
GetPackerCaps
ConfigurePacker
PackToMem
DoneMemPack
PackSetDefaultParams
ReadHeaderEx

What's the easiest way to support Unicode in an existing plugin?

1. Get my sample plugin fsplugin (file system plugins section) even if you write a different type of plugin!

2. Add the files cunicode.h and cunicode.cpp to your project. They contain various functions to make Unicode support easier.

3. Convert your existing functions to Unicode and rename them to FunctionNameW. For all file functions like CreateFile, do not call their Unicode counterpart CreateFileW directly. Instead, call the functions from cunicode.cpp like CreateFileT. These functions automatically call the right Unicode or Ansi function, and even support file name lengths >259 characters!

4. For each converted function like FunctionNameW, recreate a function FunctionName which you call this way:

int __stdcall FunctionName(char* SomeString1,char* SomeString2)
{
    WCHAR SomeString1W[wdirtypemax],SomeString2W[wdirtypemax];
    return FunctionNameW(awfilenamecopy(SomeString1W,SomeString1),awfilenamecopy(SomeString2W,SomeString2));
}

The Macro awfilenamecopy will convert the Ansi string SomeString1 to Unicode and store it inSomeString1W. This variable must not be a pointer, because awfilenamecopy uses "countof" to get the target length.

64-bit support

With Total Commander 8, Total Commander is now also available in 64-bit. Since plugins are simple dlls, and 64-bit programs can only load 64-bit dlls, a plugin needs to be re-compiled with a 64-bit compiler to work with 64-bit Total Commander.

IMPORTANT: A 64-bit plugin must have the same name as the 32-bit plugin and be in the same directory, but '64' must be appended to the extension. Example: filesystem.wcx -> filesystem.wcx64. 64-bit-only plugins must also end with '64'.

Since all 64-bit Windows versions support Unicode, it's sufficient to write a 64-bit Unicode-only plugin. However, if your existing 32-bit plugin only supports ANSI functions, you can port it without modifications to 64 bit. Total Commander 64-bit also supports the ANSI functions if it cannot find the Unicode functions. 64-bit Unicode plugins do not have an extension starting with 'u', they have the normal 'wcx64' extension.

Some porting notes:

All integer parameters in plugin functions remain 32-bit (e.g. in C: int, long, DWORD; Delphi: integer, dword), only pointers and handles are 64-bit wide now. Recompiling a program or dll with a 64-bit compiler usually takes care of this automatically without needing many changes. Problems can arise when converting pointers to integer or vice versa. Make sure to use 64-bit integer variables (e.g. size_t in C, ptrint or ptruint in Lazarus) for such operations.

What's the easiest way to convert an existing plugin to 64-bit?

1. If the plugin was written in C or C++:

If you have Visual Studio Professional 2005 or later, a 64-bit compiler is already included. If you use the free Express version or Visual Studio 2003, you need to install the Windows Software Development Kit (SDK) in addition to Visual Studio Express.

Here is how to add 64-bit support to an existing plugin:

1. Check the toolbars in Visual Studio: There are comboboxes for the compile type (Debug or Release), and one which shows "Win32".

2. Open the one showing "Win32", and click on the "Configuration manager".

3. Click on "New" in the Active Solution Platform list (right side). A new dialog box "New Solution Platform" will be shown.

4. In the upper field, choose "x64"

5. In the lower field, "copy from", choose "Win32"

6. Make sure the checkbox "Create new project platform" is on

7. Click OK
   See also: http://msdn.microsoft.com/en-us/library/9yb4317s.aspx

8. Now you can switch in the same project between Win32 and x64. Switch to x64.

9. Open the settings of your project.

10. You should set the following options:
    C++ - Code generation - runtime library: Multi-threaded-Debug (/Mtd) <- not multithreaded debug dll !
    Linker - General - output file: wcx/pluginname.wcx64

Download links:

1. Visual Studio Express C++ edition:
   http://www.microsoft.com/visualstudio/en-us/products/2010-editions/visual-cpp-express
2. Windows Software Development Kit (SDK):
   http://msdn.microsoft.com/en-us/windows/bb980924.aspx

2. If the plugin was written in Delphi or Free Pascal:

There is a 64-bit Lazarus/Free Pascal available, which can be used to create 64-bit dlls. Total Commander itself was compiled with Lazarus as a 64-bit application. There are menu items in the "Tools" menu to convert Delphi projects and forms to Lazarus.

Lazarus/Free Pascal works a bit differently from Delphi, so some functions may need to be changed. Here are the problems encountered when porting Total Commander:

1. Free pascal is different -> Use {$MODE Delphi} in all *.pas files to handle functions the Delphi way
2. strnew creates a NIL pointer when the passed pchar is 0 bytes long. -> Use your own strnew function.
3. Windows messages below WM_USER are not passed to the windows procedure. -> Use SetWindowLongPtr to subclass the window
4. The calculation p-buffer is not working when p is a pwidechar, buffer an array of widechar -> use p-pwidechar(@bufffer)
5. INVALID_HANDLE_VALUE is incorrectly set to 0 instead of -1 in lcltype.pp! -> Put "windows" at end of "uses" command.

Download links:

You should download and install the 64-bit daily snapshot from
http://www.lazarus.freepascal.org/
Click on "Daily snapshots", then on e.g. Lazarus + fpc 2.4.4 win64
The final releases are very outdated, so the snapshots usually work much better.

Examples

A plugin using this crate can be found here.

Special thanks

To all who support further development on Patreon, in particular:

• ThePhD