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

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.

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.

To use the functions in your own programs, you need the dynamic link library whxapi.dll, import declarations files for Delphi (whxapi.pas), or Visual Basic (whxapi.bas or alternatively [recommended] whxapi2.bas), or the package for C/C++ (whxcapi.zip), and this documentation. Delphi sample project. Visual Basic sample (by Alexander Asyabrik).

All these files in one ZIP archive.

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:

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

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.

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:

*80h = BIOS disk 80h under Windows 9x/Me, physical disk no. 0 under Windows NT/2000/XP, 81h = BIOS disk 81h under Windows 9x/Me, physical disk no. 1 under Windows NT/2000/XP, etc. Physical removable media are accessed and enumerated just like physical hard disks.

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.

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

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

Switches cyclically to the next open file or disk and makes it the “active” file or disk.

Saves all changes to the active file or disk.

Save the active file under the specified name.

Saves all changes to all open files and disks.

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.

0x00000001: read-only instead of default edit mode
0x00000002: in-place instead of default edit mode
0x00000004: treat file like an image file (requires specialist or forensic license)

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. 

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.

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

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

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

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

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

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.

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.

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

Removes the currently defined block from the file.

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

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. 

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.

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.

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

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.

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.

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.

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.

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.

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

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. 

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.