WinHex API English

硬盘爱好者 · 发表于 2012-4-13 22:58:19

winhex API English(哈啊哈写个English还挺（36： )
这是英文原文，版本不是很新，但是API函数还是没有差异滴，不好别扔砖，好就添块瓦，请君慢慢阅读。

Index

Function

Description

1

int WHX_Init(
int APIVersion
);

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(
LPCSTR lpResName
);

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:

C:\My File.txt	file
D:	logical drive
E:	logical drive
00h	floppy disk
80h	hard disk 0*
81h	hard disk 1*
82h	removable medium 2*
83h	hard disk 3*
...	...
9Eh	1st optical disc
9Fh	2nd optical disc

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

4

BOOL WHX_Create(
LPCSTR lpPathName,
int Size
);

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(
LPCSTR lpNewFileName
);

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(
LPCSTR lpResName,
int Param
);

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)

21

BOOL WHX_Read(
LPVOID lpBuffer,
int Bytes
);

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(
LPVOID lpBuffer,
int Bytes
);

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(
LPLONGLONG lpSize
);

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(
LONGLONG Ofs
);

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

32

BOOL WHX_Move(
LONGLONG Distance
);

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

33

BOOL WHX_CurrentPos(
LPLONGLONG lpOfs
);

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

34

BOOL WHX_SetBlock(
LONGLONG Ofs1,
LONGLONG Ofs2
);

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(
LPCSTR lpNewFileName
);

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(
LPCSTR lpData,
LPCSTR lpOptions
);

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(
LPCSTR lpData1,
LPCSTR lpData2,
LPCSTR lpOptions
);

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(
LPCSTR lpSrcFormat,
LPCSTR lpDstFormat
);

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(
LPCSTR lpKey,
int Algorithm
);

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(
LPCSTR lpKey,
int Algorithm
);

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(
LPCSTR lpObjName
);

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(
int Level
); (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(
LPCSTR lpErrorMsg
);

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(
LPCSTR lpErrorMsg
);

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.

74

BOOL WHX_GetStatus(
LPCSTR lpInstPath
LPLONG lpWHXVersion
LPLONG lpWHXSubVersion
LPLONG lpReserved
);

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.