WinHex API 1.1 Documentation

The information below applies to WinHex
10.54 and later, except where noted.Last updated in 2006. No longer maintained/offered, sorry.

Purpose

The WinHex API (application
programming interface) allows to use the advanced capabilities of the WinHex hex &
disk editor programmatically from your own C++, Delphi, or Visual Basic programs. In
particular, it provides a convenient and simple interface for random access to files and
disks at the sector level. It will work with any media that WinHex itself is able to access. Also see Scripting

General requirements

It is possible to try the
WinHex API with the evaluation version of WinHex (as of WinHex 10.8 SR-1 only). See
WHX_Init below for details.

Actually developing software that uses the
WinHex API requires a valid professional, specialist, or forensic
WinHex license. You may also distribute both any software that makes use of the
WinHex API and WinHex itself. There are two ways how to distribute WinHex:

1. You may distribute the unlicensed WinHex version
available from http://www.winhex.com/winhex.zip. For the API to work, your customers have
to purchase professional, specialist, or API licenses
according to the number of WinHex installations needed themselves.

-or-

2. You may purchase API licenses
and distribute the licensed version of WinHex yourself. One WinHex API license needed per
end user computer. The product will be licensed to you, you will be the
actual owner of the licenses, but any of your customers may use them. The end
user does not have to take care of anything related to WinHex if you also take care of an
automatic installation of WinHex (see below).

Unlocked with an API license, WinHex is configured to
only provide the API functionality and cannot be run with the normal user interface. This
is why API licenses are available at a reduced price. Volume discount available on request (10+ licenses,
please specify the number of licenses you are interested in). For both the WinHex API and
the WinHex user interface to work, a professional license or higher is needed.

Technical details

The WinHex API
functions are mostly identical to and work similar as the corresponding WinHex script commands.
Unless otherwise stated, they always apply to the currently open and active file or disk.
They usually return a boolean value that indicates whether or not the function succeeded.
All functions must be called with the WINAPI/stdcall calling convention (which means the
parameter order is from right to left, and they are removed from the stack by the API
functions themselves). They are exported by name as well as by ordinals (see Index
column). Your software must call WHX_Done before terminating. If it does not, the
copy of WinHex in memory must be terminated using the Task Manager before using the WinHex
API again.

The file whxapi.dll must be located in the same folder
as the calling application, or in the Windows \system32 directory (\system in Windows
9x/Me). It does not need to be registered in Windows. On the end user's computer, WinHex
itself must be installed (e.g. by the accompanying setup
program or by your own installation procedure) anywhere on the system. You could also just
add the required WinHex files to your own software's installation folder. The installation
path where the WinHex files are located (e.g. C:\WinHex) must be stored in the registry
branch HKEY_CURRENT_USER\Software\X-Ways AG\WinHex\Path\ for the API to work, or (as of
v12.05) alternatively these files must be located in current directory of the calling
process.

Must be called first to
initialize the WinHex API. APIVersion currently must be 1. WinHex must not be
running. If initialization fails, the WinHex API must not and cannot be used. Possible
return values:

2

Success (limited)*

1

Success

0

General error

-1

WinHex installation not ready

-2

APIVersion incorrect

-3

Invalid or insufficient license

*A return value of 2 indicates that the WinHex API may
only be used for evaluation purposes (possible as of WinHex 10.8).
This is the case if the evaluation version of WinHex or only a personal license is
available. All the commands the WinHex API offers can be used then except WHX_Save,
WHX_SaveAs, WHX_SaveAll, and WHX_Write, which will always fail. The return value of -3 is
no longer in use since WinHex 10.8.

2

BOOL WHX_Done();

Must be called when the
WinHex API is no longer needed, to properly free all allocated resources and to terminate
the active part of WinHex.

3

BOOL WHX_Open(LPCSTRlpResName);

Opens the specified file,
logical drive or physical disk in default edit mode. Under Windows NT/2000/XP,
administrator privileges are required to open drives or disks. Examples for lpResName:

Creates the specified file
with the specified initial files size in the specified directory. If the file exists, it
is overwritten. The newly created file is also opened. WinHex cannot create a file of 0 or
more than 2^31-1 bytes.

5

BOOL WHX_Close();

Closes the active file or
disk. Any unsaved changes are lost.

6

BOOL WHX_CloseAll();

Closes all open files or
disks. Any unsaved changes are lost.

7

BOOL WHX_NextObj();

Switches cyclically to the
next open file or disk and makes it the active file or disk.

8

BOOL WHX_Save();

Saves all changes to the
active file or disk.

9

BOOL WHX_SaveAs(LPCSTRlpNewFileName);

Save the active file under
the specified name.

10

BOOL WHX_SaveAll();

Saves all changes to all
open files and disks.

11

BOOL WHX_OpenEx(LPCSTRlpResName,intParam);

Works the same as WHXOpen,
but passes an additional integer parameter Param that consists of flags. There
are two mutually exclusive flags that determine in which edit mode the file or disk is to
be opened. Using in-place edit mode accelerates writing (because data is written directly
and immediately, without the use of temporary files) and renders calling WHX_Save
obsolete. Read-only mode (view mode, write protection) ensures that nothing will be
accidentally written. Available since WinHex 10.92
SR-2. There is another flag that causes files to be opened and
treated like image files (applicable to raw images, Encase images, and evidence files). Available since WinHex 11.9.

Reads Bytes bytes
from the current position in the active file or disk into the specified buffer. Also moves
the current position forward by Bytes bytes, provided the file or disk is
sufficient in size.

22

BOOL WHX_Write(LPVOIDlpBuffer,intBytes);

Writes Bytes bytes
from the specified buffer at the current position into the active file or disk (in
overwrite mode). Also moves the current position forward by Bytes bytes. Expands
the file size if necessary to do this.

30

BOOL WHX_GetSize(LPLONGLONGlpSize);

Returns the total size of
the file or disk in bytes as a 64-bit integer at the address specified by lpSize.

31

BOOL WHX_Goto(LONGLONGOfs);

Moves the current position
to the specified 64-bit offset.

32

BOOL WHX_Move(LONGLONGDistance);

Moves the current position
by the specified 64-bit distance, forward (>0) or backward (<0).

33

BOOL WHX_CurrentPos(LPLONGLONGlpOfs);

Returns the current
position as a 64-bit offset at the address specified by lpOfs.

34

BOOL WHX_SetBlock(LONGLONGOfs1,LONGLONGOfs2);

Sets the block borders to
the specified offsets. To clear the currently selected block, Ofs1 and Ofs2
must both be -1 (new since WinHex 10.55 SR-4).

41

BOOL WHX_Copy();

Copies the currently
defined block into the clipboard. If no block is defined, this function works as known
from the Copy command in the Edit menu.

42

BOOL WHX_CopyIntoNewFile(LPCSTRlpNewFileName);

Copies the currently
defined block into the specified new file, without using the clipboard. If no block is
defined, it works as known from the Copy command in the Edit menu. Can copy files as well
as disk sectors (an easy way to create a disk image). The new file will not be opened
automatically.

43

BOOL WHX_Cut();

Cuts the currently defined
block from the file and puts it into the clipboard.

44

BOOL WHX_Remove();

Removes the currently
defined block from the file.

45

BOOL WHX_Paste();

Pastes the current
clipboard contents at the current position in a file, without changing the current
position.

46

BOOL WHX_WriteClipboard();

Writes the current
clipboard contents at the current position in a file or disk, without changing the current
position and by overwriting the data at the current position.

51

BOOL WHX_Find(LPCSTRlpData,LPCSTRlpOptions);

Searches for the data given
by lpData. This may either be null-terminated raw data or a null-terminated
string in hexadecimal ASCII notation (like 0x123456). The function moves the
current position to the first occurrence, if any.

lpOptions points to a string that consists of
any combination (concatenation) of search options. Supported options are
MatchCase, MatchWord, Down, Up,
BlockOnly, SaveAllPos, Wildcards, and
Unicode. For example, a valid string would be Down MatchCase
BlockOnly. By default, if the string is empty or the pointer is null, the
entire file or disk is searched, top down, and wildcards, whole words only, match case,
Unicode, and SaveAllPos are not enabled. If you enable wildcards, the
character chosen in WinHex (by default "?" or 0x3F, respectively) can be used as
a placeholder for one byte.

The result is TRUE if the search could be completed and
if no error occurred.

52

BOOL WHX_Replace(LPCSTRlpData1,LPCSTRlpData2,LPCSTRlpOptions);

Replaces all occurrences of
the data given by lpData1 with that given by lpData2. Can replace text
strings as well as hexadecimal values. Supported options are MatchCase,
MatchWord, Down, Up, BlockOnly,
Wildcards, and Unicode. See WHX_Find for details. The result is
TRUE if the replacement could be completed and if no error occurred.

53

BOOL WHX_WasFound();

Returns TRUE if the last
executed WHX_Find or WHX_Replace function actually found the specified data.

54

int WHX_WasFoundEx();

Returns the number of
occurrences found by WHX_Find (0 or 1, because WHX_Finds stops at the first occurrence, if
any) or replaced by WHX_Replace (0, 1, or any other positive number). Available as of WinHex 11.4.

61

BOOL WHX_Convert(LPCSTRlpSrcFormat,LPCSTRlpDstFormat);

Converts the data in the
active file from one format into another. Valid format strings are ANSI,
IBM, EBCDIC, Binary, HexASCII,
IntelHex, MotorolaS, Base64, UUCode, in
combinations as known from the Convert menu command in WinHex.

62

BOOL WHX_Encrypt(LPCSTRlpKey,intAlgorithm);

Encrypts the active file,
disk, or block selected therein with the PC1 algorithm (Algorithm must be 1) and a hash of the key
pointed to by lpKey (16 bytes long at max.) as the encryption key. You are
responsable for zeroing the key pointed to by lpKey afterwards to maximize
security.

63

BOOL WHX_Decrypt(LPCSTRlpKey,intAlgorithm);

Decrypts the active file,
disk, or block selected therein with the PC1 algorithm (Algorithm must be 1) and a hash of the key
pointed to by lpKey (16 bytes long at max.) as the decryption key. You are
responsable for zeroing the key pointed to by lpKey afterwards to maximize
security.

70

BOOL WHX_GetCurObjName(LPCSTRlpObjName);

Retrieves the name of the
currently active file (including the path) or description of the currently active disk,
respectively, in the buffer that lpObjName points to. The provided buffer must be
at least 256 bytes in size. Disk descriptions are returned in the language selected in
WinHex. Available since WinHex
10.55. Description may vary with different WinHex versions.

71

BOOL WHX_SetFeedbackLevel(intLevel);

(named WHX_SetErrorMode
until v11.0 and for compatibility reasons still available under this name)

The lowest bit in the
integer parameter controls whether or not WinHex displays errors to the user by way of a
message box. To retrieve the error message programmatically, use WHX_GetLastError. If you
select not to let the user see the message box, WinHex will assume the user pressed
Cancel or No, if he would have been given the option to choose
between two buttons.

The second-lowest bit controls whether or not WinHex
displays the small progress window during lengthy operations, which often allow the user
to abort by pressing Esc or closing the window or to pause by pressing the Pause key. Available since WinHex 11.1.

0

Display message boxes and progress windows

1

Suppress message boxes only

2

Suppress progress windows only

3

Suppress message boxes and progress windows

72

BOOL WHX_GetLastError(LPCSTRlpErrorMsg);

Retrieves the description
of the last error that WinHex has displayed to the user (or would have displayed to the
user, depending on the feedback level). The provided buffer must be at least 256 bytes in
size. The description is undefined if no error has occurred since the last use of
WHX_Init.

73

BOOL WHX_SetLastError(LPCSTRlpErrorMsg);

Specifies an error
description to be retrieved by WHX_GetLastError, or clears it if lpErrorMsg
points to an empty string or is null. Available
since WinHex 10.55 SR-4.

Retrieves the full path of
the WinHex installation currently used by the API DLL in lpInstPath (e.g.
D:\Program Files\WinHex\winhex.exe, up to 255 characters), the WinHex version
in the lower WORD of the LONG value at the address specified by lpWHxVersion
(e.g. 1100 means v11.00), and the WinHex service release number in the lower WORD of the
LONG value at the address specified by lpWHxSubVersion (e.g. 1 means SR-1, 0
means no SR). All parameters are optional, so the pointers may be set to NULL. The pointer
lpReserved is currently unused and must be set to NULL. Available since WinHex 11.0 SR-2.

Known error: In WinHex
10.92 SR-2 through 11.0 SR-1, WHX_Write did not move the current position when applied to
a disk that was opened in in-place mode.