X-Tensions API Documentation
XWF_* functions that you may call

Disk and General I/O Functions

INT64 XWF_GetSize(
   HANDLE hVolumeOrItem,
   LPVOID lpOptional

Returns the size of the volume or physical size of the file to which you provide a handle. lpOptional is supported from v16.7 SR-8. This parameter must be NULL in earlier versions. (LPVOID) 1 will make this function retrieve the logical file size (which may be different from the size that was known of the file in the volume snapshot before it was opened), (LPVOID) 2 the valid data length (a.k.a. initialized size of the data stream, which may be available from NTFS, exFAT, XWFS, XWFS2).

VOID XWF_GetVolumeName(
   HANDLE hVolume,
   LPWSTR lpString,
   DWORD nType

Retrieves the name of the volume in UTF-16, 255 characters at most. 3 types of names are available (1, 2 or 3). For example, 3 can be more generic than 2 ("Hard disk 1" instead of "WD12345678").

VOID XWF_GetVolumeInformation(
   HANDLE hVolume,
   LPLONG lpFileSystem,
   LPDWORD lpBytesPerSector,
   LPDWORD lpSectorsPerCluster,
   PINT64 lpClusterCount,
   PINT64 lpFirstClusterSectorNo

Retrieves various information about the volume. All parameters are optional.

9=main memory
7=opened through OS
-15=NTFS Bitlocker
-16=physical disk, potentially partitioned
BOOL XWF_GetBlock(
   HANDLE hVolume,
   PINT64 lpStartOfs,
   PINT64 lpEndOfs

Available in v17.7 and later. Retrieves the boundaries of the currently selected block, if any. Returns FALSE if there no block is defined.

BOOL XWF_SetBlock(
   HANDLE hVolume,
   INT64 nStartOfs,
   INT64 nEndOfs

Available in v17.7 and later. Sets the boundaries of the currently selected block, if any. Returns FALSE if the boundaries that you specify exceed the size of the volume. Set nEndOfs to -1 to clear any currently defined block.

BOOL XWF_GetSectorContents(
   HANDLE hVolume,
   INT64 nSectorNo,
   LPWSTR lpDescr,
   LPLONG lpItemID

Retrieves information about a certain sector on a volume. Returns FALSE if the sector belongs to an unused/free cluster, otherwise TRUE.

lpDescr: Retrieves a textual description of what this sector is used for. Can be the name and path of a file or something like "FAT 1". May be language specific. Use a buffer that has space for 511 characters and a terminating null.

lpItemID: Optional. Retrieves the ID of the item in the volume snapshot that the sector is allocated to, if any, otherwise -1.

HANDLE XWF_OpenVolume(
   HANDLE hEvidence

Opens the volume that is represented by the specified evidence object. Although we use the term "volume" here, it might just as well be a partitioned disk or an image of a partitioned disk or an image of a volume or a memory dump or a directory. Depends on the nature of the evidence object. Note that from a remote network drive or from a disk opened without administrator rights or from a directory you cannot read any sectors. Not currently implemented.

   HANDLE hVolume,
   LONG nItemID,
   DWORD nFlags,

Available in v16.5 and later. Opens the file or directory that is contained in the specified volume and that has the specified ID for reading and returns a handle to it, or 0 if unsuccessful. nFlags supported by v17.5 SR-11, v17.6 SR-7, v17.7 and later:

0x01 = open the item including its file slack space, if it has any
0x02 = suppress error messages in the program in case of failure
0x08 = prefer alternative file data if available, e.g. a thumbnail created by X-Ways Forensics for a picture
0x10 = open alternative file data if available, and fail if not (v17.7 SR-3 and later)

   HANDLE hVolumeOrItem

Available in v16.5 and later. Closes a volume that was opened with the XWF_OpenVolume function or an item that was opened with the XWF_OpenItem function.

   HANDLE hVolumeOrItem,
   INT64 nOffset,
   LPVOID lpBuffer,
   DWORD nNumberOfBytesToRead,

Reads the specified number of bytes from the specified position in the specified volume or item into the specified buffer. Returns the number of bytes read.

INT64 XWF_Write(
   HANDLE hVolume,
   INT64 nOffset,
   LPVOID lpBuffer,
   DWORD nNumberOfBytesToWrite,

Writes the specified number of bytes in the specified buffer at the specified position to the specified volume. Works only in WinHex, not in X-Ways Forensics. Returns the number of bytes written, or -1 if a complete failure occurred. Not currently implemented.

   struct DriveInfo* pDInfo

#pragma pack(2)
struct DriveInfo {
   DWORD nSize,
   LONG nDrive,
   DWord nBytesPerSector,
   INT64 nSectorCount

Not currently implemented.
   LONG nDrive,
   INT64 nSector,
   DWORD nCount,
   LPVOID lpBuffer,
   LPDWORD nFlags

Reads or writes the specified sectors number from or to the specified disk or image or partition or volume or RAID. May be called when processing XT_SectorIO. Returns the number of sectors read/written/covered. nDrive is a device/disk/partition/volume/image/RAID identifier. nFlags may be NULL if you do not wish to specify or receive any flags. Available from v18.4.

0x01: write (not yet implemented, if not set, this function will read)
0x02: stop upon I/O error and return the number of successfully read sectors (if not set, X-Ways Forensics will try to continue and fill unreadable sectors with an ASCII pattern and return the total number of sectors tried)
0x04: output error messages in the GUI in case of I/O errors
0x08: do not trigger any pending skeleton image acquisition through a read operation
0x10: check whether the entire range of sectors is defined as sparse in a lower abstraction layer, for performance benefits
0x20 (returned): the entire range of sectors targeted is sparse, so you may ignore it, and the buffer was not filled

All other flags are reserved and must not be set.

Evidence Object/Case Management Functions

INT64 XWF_GetCaseProp(
   LPVOID pReserved,
   LONG nPropType,
   PVOID pBuffer,
   LONG nBufLen

Available in v17.2 and later. Depending on nPropType, either returns information about the current case as a 64-bit integer OR retrieves such information in a buffer that you supply. The buffer size for strings is to be specified in characters (UTF-16). pReserved must be NULL. Unless otherwise noted, returns the original length of the requested string in characters, or the number of bytes for other buffer types, or a negative number if an error occurred, for example if no case is active.

Much of the functionality of X-Ways Forensics and WinHex Lab Edition is available when not working with a case (when no case was created/opened in the program), after just having opened a disk or image or even an ordinary single file, including the ability to run X-Tensions. If the X-Tension specifically works with the evidence objects of a case, not just the snapshot of the volume represented by the active data window or the single file represented by the active data window, yet the user tries to run the X-Tension with no case / no evidence objects open, then the X-Tension should simply tell the user that it only works with a case and cannot do anything without (and it should not try do provide NULL pointers/handles where pointers/handles to evidence objects are expected). X-Ways Forensics itself also refuses to let the user do certain things when no case is active.

nPropType   pBuffer type   nBufLen   description
XWF_CASEPROP_ID (0)   n/a   n/a   returns a unique 64-bit ID of the case (v19.7 and later)
XWF_CASEPROP_TITLE (1)   LPWSTR   ~   case title
XWF_CASEPROP_CREATION (2)   n/a   n/a   returns the creation time as FILETIME (v19.7 and later)
...   ...   ...   ...
XWF_CASEPROP_FILE (5)   LPWSTR   ~   .xfc case file path
XWF_CASEPROP_DIR (6)   LPWSTR   ~   case directory
...   ...   ...   ...
   LPVOID pReserved

Retrieves a handle to the first evidence object in the case, or NULL if the active case has no evidence objects or (in releases from June 2016) if no case is active. In conjunction with XWF_GetNextEvObj this function allows to enumerate all evidence objects of the case. pReserved must be NULL. Available from v17.6.

   HANDLE hPrevEvidence,
   LPVOID pReserved

Retrieves the next evidence object in the chain if there is another, or otherwise NULL. pReserved must be NULL. Available from v17.6.

   HANDLE hEvidence

Removes the specified evidence object from the case. Not currently implemented.

   DWORD nType,
   LONG nDiskID,
   LPWSTR lpPath,
   PVOID pReserved

Available in v16.5 and later. Creates one or more evidence objects from one source (which can be a physical storage device, logical drive letter, disk or volume image, memory dump, or a directory/path) and returns the first evidence object created, or NULL in case of an error (for example if that particular disk or image had been added to that case already). A case must already be loaded. If more than 1 evidence object is created (for example for a physical disk that contains partitions, which count as evidence objects themselves), use XWF_GetNextEvObj to find them. Evidence objects should not be created during an ongoing volume snapshot refinement or search etc. Potentially time-consuming if the volume snapshot is taken by X-Ways Forensics immediately when the evidence object is added.

0: file
1: image
2: memory dump
3: directory/path
4: physical disk or drive letter

nDiskID: 3 for drive letter C:, 4 for drive letter D:, etc.; -3 for physical hard disk 0, -4 for physical hard disk 1, etc., currently must be 0 for an image, memory dump, directory or file

lpPath: Path in case of a file, image, memory dump, or directory, otherwise NULL. v19.3 and later: For an image or memory dump, the filename may contain an asterisk, for example to add all images in a directory to a case with a single function all, e.g. Z:\Images\*.e01. In such a case the function would return the handle to the evidence object that represents the last image that was added.

pReserved: Must be NULL.

   HANDLE hEvidence,
   DWORD nFlags

If not currently open, opens the specified evidence object in a data window (and at the operating system level opens the corresponding disk or image file), interprets the image file (if the evidence object is an image), and loads or takes the volume snapshot. Returns a handle to the volume that the evidence object represents. Use this function if you wish to read data from the disk/volume or deal with its volume snapshot. Opening an evidence object is potentially time-consuming if the volume snapshot has to be taken at that time. Returns 0 if unsuccessful or otherwise a handle to the disk/volume that you can use with the Disk and General I/O Functions. Available from v17.6.  nFlags must be 0 in v18.0 and older.

nFlags supported from v18.1:
0x01: open the evidence object without opening or even touching/looking for the underlying disk or image, just to deal with the volume snapshot, no disk I/O will be possible
0x02: open the volume snapshot as read-only

VOID XWF_CloseEvObj(
   HANDLE hEvidence

Closes the specified evidence object if it is open currently and unloads the volume snapshot, otherwise does nothing. Available from v17.6.

INT64 XWF_GetEvObjProp(
   HANDLE hEvidence,
   DWORD nPropType,
   PVOID pBuffer

Retrieves information about the specified evidence object, either through the buffer or the return value, depending on what kind of information you require (nPropType). If through the return value, you may need to cast it to the appropriate type in order to correctly interpret/understand it. This function does not require that the evidence object is open. General error return code is -1. Available from v17.6. 

nPropType actual result type pBuffer type description
0 WORD (unused) ev. obj. number (simply reflects the order of evidence objects in the case tree and thus may change)
1 DWORD (unused) ev. obj. ID (used to identify parent-child relationships between evidence objects)
2 DWORD (unused) parent ev. obj. ID (available for partitions, 0 if no parent)
3 WORD (unused) short ev. obj. ID (concatenated with the ID of items in the volume snapshot gives the so-called unique ID shown for items in the directory browser, available in v18.8 SR-14, v18.9 SR-12, v19.0 SR-11 and later)
4 DWORD (unused) volume snapshot ID (increments by 1 when a new volume snapshot is taken, available in v19.0 SR-11 and later)
6 LPWSTR (unused) evidence object title (e.g. "Partition 2")
7 LONG LPWSTR extended ev. obj. title (e.g. "HD123, Partition 2), buffer len: MAX_PATH, returns the string length
8 LONG LPWSTR abbreviated ext. ev. obj. title (e.g. "HD123, P2), buffer len: MAX_PATH, returns the string length
9 LPWSTR (unused) internal name
10 LPWSTR (unused) description
11 LPWSTR (unused) examiner comments
12 LONG LPWSTR internally used directory (buffer length: MAX_PATH), returns the string length
13 LONG LPWSTR output directory (buffer length: MAX_PATH), returns the string length
16 INT64 (unused) size in bytes
17 DWORD (unused) volume snapshot file count
18 INT64 (unused) flags*
19 INT64 (unused) file system identifier (see XWF_GetVolumeInformation for possible values)
20 DWORD (unused) hash type
21 DWORD LPVOID hash value (buffer size according to hash type), returns the hash size in bytes
32 FILETIME (unused) creation time (when the ev. obj. was added to the case)
33 FILETIME (unused) modification time
40 DWORD (unused) hash type #2
41 DWORD LPVOID hash value #2 (buffer size according to hash type), returns the hash size in bytes

0x01: Data window active yes/no
0x02: Data window open yes/no
0x04: Flagged yes/no
0x08: Selected for operations yes/no (in case of a physical, partitioned evidence object, the operation should be applied to the areas outside of explorable partitions only, as the partitions are their own evidence objects and selectable separately)

0x10: Selected for recursive view yes/no
0x20: Expanded in case tree yes/no
0x40: Has no children yes/no

0x0100: Is an evidence file container yes/no
0x0200: Is a deleted partition yes/no
0x0400: Optical disc icon yes/no
0x0800: RAM icon yes/no
0x1000: Is dynamic disk yes/no
0x2000: Evidence object is just a single file in the directory

0x010000: Index available yes/no
0x020000: Logging enabled yes/no
0x040000: Annotations highlighted yes/no
0x080000: Warned of weird image file size already yes/no
0x100000: Suppress "size of evidence object has changed" yes/no

LONG XWF_SetEvObjProp(
   HANDLE hEvidence,
   LONG nPropType,
   PVOID pBuffer,

Sets information about the specified evidence object. See above for possible values of nPropType. Only those marked * cannot be used with this function. Strings must be null-terminated. Not currently implemented.

   DWORD nEvObjID,

Retrieves a handle to the evidence object with the specified unique ID. Returns NULL if not found. The unique ID of an evidence object remains the same after closing and re-opening a case, whereas the handle will likely change. The evidence object number may also change. That happens if the user re-orders the evidence objects in the case. The unique ID, however, is guaranteed to never change and also guaranteed to be unique within the case (actually likely unique even across all the cases that the user will even deal with) and can be used to reliably recognize a known evidence object. Available from v18.7.

LPVOID XWF_GetReportTableInfo(
   LPVOID pReserved,
   LONG nReportTableID,
   PLONG lpOptional

Available in v17.7 and later. If nReportTableID designates an existing report table in the current case, returns a pointer to the null-terminated name of that report table, or otherwise NULL. nReportTableID may be set to -1 to retrieve the maximum number of report tables supported by the active version in the integer pointed to by lpOptional. Valid report table IDs range from 0 to (maximum number-1). pReserved must be NULL. lpOptional must point to a 0 when called.

In v18.1 and later, the variable pointed to by lpOptional will receive flags, among others the following ones:
0x0001: created internally by application
0x0002: created manually by the user
0x0004: represents a hash set
0x0010: selected for inclusion in the case report
0x0020: selected for the report table filter
0x0040: selected for new assocations
0x0080: represents a search term
0x4000: represents a group of duplicate files
0x8000: offered for selection in the report

LPVOID XWF_GetEvObjReportTableAssocs(
   HANDLE hEvidence,
   LONG nFlags,
   PLONG lpValue

Available in v17.7 and later. Returns a pointer to an internal list that describes all report table associations of the specified evidence object, or NULL if unsuccessful (for example if not available any more in a future version). Scanning this list is a much quicker way to find out which items are associated with a given report table than calling GetReportTableAssocs for all items in a volume snapshot, especially if the snapshot is huge. The list consists of 16-bit report table ID and 32-bit item ID pairs repeatedly, stored back to back. The integer pointed to by lpValue is set to the number of pairs in the data structure. You may set the flag 0x01 in nFlags to request a list sorted by item IDs. Other flags must not be set at this time. 

Volume Snapshot Management Functions

VOID XWF_SelectVolumeSnapshot(
   HANDLE hVolume

Defines to which volume's volume snapshot subsequent calls of the below functions apply should you wish to change that. 

INT64 XWF_GetVSProp(
   LONG nPropType,
   PVOID pBuffer

Available in v17.4 and later. Depending on nPropType, helps you to either retrieve information about the current volume snapshot or gets some settings of your choice over to the volume snapshot.

nPropType   description

Returns the ID of a special item in the volume snapshot, or -1 if the requested special item is not present in the volume snapshot. Useful for example when adding more items to the volume snapshot that need to have a parent. pBuffer must point to a byte (or larger integer variable) with one of the following values:
1 = root directory
2 = Path Unknown directory
4 = Carved Files directory
5 = Free Space file
11 = System Volume Information directory
12 = Windows.edb file

XWF_VSPROP_HASHTYPE (11)   Deprecated.

Retrieves the type of the primary hash values that have already been computed for files in the volume snapshot or the user's default hash type that might get used for future computation. pBuffer is not used. Returns one of these values:
0: undefined
1: CS8
2: CS16
3: CS32
4: CS64
5: CRC16
6: CRC32
7: MD5
8: SHA-1
9: SHA-256
10: RIPEMD-128
11: RIPEMD-160
12: MD4
13: ED2K
14: Adler32
15: Tiger Tree Hash (TTH, from v18.1)
16: Tiger128 (from v18.1)
17: Tiger160 (from v18.1)
18: Tiger192 (from v18.1)


Same, but retrieves the type of the secondary hash values.


Available from v19.7. Defines the type of the primary hash values that may be computed for files in the volume snapshot going forward, for example through RVS in the user interface or using the XWF_GetHashValue function. The hash value type constants are listed above. pBuffer must point to a byte with the desired hash type value. Warning: If hash values of a different type have been computed already, those will be discarded by this call. The return value indicates whether an error has occurred (-1) or the specified hash type was already set for the volume snapshot (0) or whether it was successfully newly set (1).


Same, but defines the type of the secondary hash values.

DWORD XWF_GetItemCount(
   LPVOID pReserved

Retrieves the number of items in the current volume snapshot (files and directories). Item IDs are consecutive 0-based. That means the ID of the first item has the ID 0 and the last item in a volume snapshot has the ID (GetItemCount-1). You address each and every item in that range, be it a file or directory, by specifying its ID. 

DWORD XWF_GetFileCount(
   Long nDirID

Available from v17.7. Retrieves the accumulated number of files in the directory with the specified ID and all its subdirectories. Also works for files that have child objects. Not currently supported for the root directory. You may specify -1 as the ID instead to get the total file count of the entire volume snapshot.

LONG XWF_GetSpecialItemID(
   DWORD nSpecialItem
LONG XWF_CreateItem(
   LPWSTR lpName,
   DWORD nCreationFlags

Creates a new item (file or directory) in the volume snapshot. May be called when refining the volume snapshot. Returns the ID of the newly created item, or -1 if an error occurred (e.g. out of memory). Should be followed by calls to XWF_SetItemParent, XWF_SetItemSize, XWF_SetItemInformation, and/or XWF_SetItemOfs. If via XWF_SetItemParent you make the new file a child object of a file (not directory), you are responsible for setting the parent's XWF_ITEM_INFO_FLAG_HASCHILDREN flag.  

For example, if you are creating a file carved from the sectors of the evidence object, you can specify the file size using XWF_SetItemSize and the start offset via the nDefOfs parameter (must be negative) using XWF_SetItemOfs.

0x00000001: For performance reasons, if set, it's a hint that many more items are expected to be created.

LONG XWF_CreateFile(
   LPWSTR pName,
   DWORD nCreationFlags,
   LONG nParentItemID,
   PVOID pSourceInfo

#pragma pack(2)
struct SrcInfo {
   DWord nStructSize,
   INT64 nBufSize,
   LPVOID pBuffer

Available from v16.7. Similar to XWF_CreateItem, but also allows to attach an external file to the volume snapshot or to define a file that is an excerpt of another file (its parent). Returns the ID of the newly created item, or -1 if an error occurred (e.g. out of memory). Should be followed by a call to XWF_SetItemSize (if carving a file in a file) or XWF_SetItemInformation (otherwise).

pName: The name that this file will have in the volume snapshot, which may be different from its source file name if you are attaching an external file.

0x00000001: For performance reasons, if set, it's a hint that many more items are expected to be created.
0x00000002: Create a file that is defined as an excerpt from its parent (i. e. a file carved within another file), where
pSourceInfo points to a 64-bit start offset within that parent file.
0x00000004: Attach an external file, and
pSourceInfo is an LPWSTR pointer to the path of that file. Can only be used with the volume snapshot of an evidence object.
0x00000008: Keep that external file that you designate if you still need it yourself after calling this function. 
0x00000010: The file contents is specified by a buffer that you provide.
pSourceInfo points to a SourceInfo structure, in which nStructSize is the size of the structure in bytes, nBufSize specifies the logical size of the buffer in bytes, and pBuffer points to the buffer. Available in v19.1 and later. The maximum value supported for nBufSize is currently 233-1 in x64.

Obviously, the flags 0x2 and 0x4 and 0x10 are mutually exclusive, and 0x8 can only be combined with 0x4. If neither of the flags 0x2, 0x4, or 0x10 is specified, pSourceInfo is ignored and XWF_CreateFile works exactly like XWF_CreateItem.

More information about the source of the file's data. Exact meaning depends on the flags.

LONG XWF_FindItem1(
   LONG nParentItemID,
   LPWSTR lpName,
   DWORD nFlags,
   LONG nSearchStartItemID

Available from v19.2. Searches for a file or directory with the specified name with the specified parent (e.g. directory or file with child objects) in the current volume snapshot. Returns the ID of the first matching item if -1 if no match was found. nSearchStartItemID should be 0 for a search from the start of the volume snapshot. If after receiving one match you wish to search for another match, for example because you are looking for an existing file, but the first match is for a previously existing file in that directory, you can call this function again with the previously returns item ID + 1.

0x00000001: match case, for performance reasons

Volume Snapshot Item Property Functions

   LONG nItemID

Retrieves a pointer to the null-terminated name of the specified item (file or directory) in UTF-16. You may call XWF_GetItemName and XWF_GetItemParent repeatedly until XWF_GetItemParent returns -1 and concatenate the item names to get the path of an item.

VOID XWF_SetItemName(
   LONG nItemID,
   LPWSTR lpName

Renames an item. Not currently implemented.

INT64 XWF_GetItemSize(
   LONG nItemID

Retrieves the size of the item (file or directory) in bytes. -1 means unknown size.

VOID XWF_SetItemSize(
   LONG nItemID,
   INT64 nSize

Sets the size of the item in bytes. -1 means unknown size.

VOID XWF_GetItemOfs(
   LONG nItemID,
   LPINT64 lpDefOfs,
   LPINT64 lpStartSector

Retrieves the offset of the file system data structure (e.g. NTFS FILE record) where the item is defined. If negative, the absolute value is the offset where a carved file starts on the volume. 0 if an error occurred. 0xFFFFFFFF if not available/not applicable.

Also retrieves the number of the sector from the point of the volume in which the data of the item starts.

VOID XWF_SetItemOfs(
   LONG nItemID,
   INT64 nDefOfs,
   INT64 nStartSector

Sets the above-mentioned offset and sector number.

INT64 XWF_GetItemInformation(
   LONG nItemID,
   LONG nInfoType,
   LPBOOL lpSuccess,

Returns information about an item (file or directory) as stored in the volume snapshot, such as the original ID or attributes that the item had in its defining file system. What information is actually returned depends on nInfoType. The function indicates success or failure via lpSuccess. This parameter may be NULL if not required. All timestamps are transferred in Windows FILETIME format.

#define XWF_ITEM_INFO_CLASSIFICATION 5 // e.g. extracted e-mail message, alternate data stream, etc.
#define XWF_ITEM_INFO_LINKCOUNT = 6 // hard-link count
#define XWF_ITEM_INFO_COLORANALYSIS* = 7 // v17.2 and later, skin color percentage, <0: n/a, -2: error, -3: b/w or grayscale, -4: irrelevant
#define XWF_ITEM_INFO_PIXELINDEX* = 8 // v18.9 and later, more information below
#define XWF_ITEM_INFO_FILECOUNT = 11 // how many child objects exist recursively that are files
#define XWF_ITEM_INFO_EMBEDDEDOFFSET = 16 // v17.7 and later, for a file linearly embedded (contiguously stored) within another file, offset in that file

Flags that are returned for XWF_ITEM_INFO_FLAGS:
0x00000001: is a directory
0x00000002: has child objects (for files only)
0x00000004: has subdirectories (for directories only)
0x00000008: is a virtual item
0x00000010: hidden by examiner
0x00000020: tagged
0x00000040: tagged partially
0x00000080: viewed by examiner

0x00000100: file system timestamps not in UTC
0x00000200: internal creation timestamp not in UTC
0x00000400: FAT timestamps
0x00000800: originates from NTFS
0x00001000: Unix permissions instead of Windows attributes
0x00002000: has examiner comment
0x00004000: has extracted metadata
0x00008000: file contents totally unknown

0x00010000: file contents partially unknown
0x00020000: reserved
0x00040000: hash 1 already computed
0x00080000: has duplicates
0x00100000: hash 2 already computed (since v18.0)
0x00200000: known good hash category
0x00400000: known bad hash category
0x00600000: known, either good or bad (both flags!, v18.9+)
0x00800000: found in volume shadow copy

0x01000000: deleted files with known original contents
0x02000000: file format consistency OK
0x04000000: file format consistency not OK
0x10000000: file archive already explored (v17.6+)
0x20000000: e-mail archive or video already processed (v17.6+)
0x40000000: embedded data already uncovered (v17.6+)
0x80000000: metadata extraction already applied (v17.6+)

0x100000000: file embedded in other file linearly (v17.7+)*
0x200000000: file whose contents is stored externally (v17.7+)*
0x400000000: alternative data /a via XWF_OpenItem (v18.9+)*

Deletion status returned for XWF_ITEM_INFO_DELETION:
0 = existing
>0 = not existing
1 = previously existing, possibly recoverable
2 = previously existing, first cluster overwritten or unknown
3 = renamed/moved, possibly recoverable
4 = renamed/moved, first cluster overwritten or unknown
5 = carved file (since v19.3 SR-3, used to be 1)

Classification values for XWF_ITEM_INFO_CLASSIFICATION:
0x00: normal file
0x04: HFS resource fork
0x08: NTFS alternate data stream
0x0A: NTFS non-directory index
0x0B: NTFS bitmap attribute
0x10: NTFS general logged utility stream
0x11: NTFS EFS logged utility stream
0xF5: e-mail related
0xF6: excerpt
0xF7: manually attached
0xF8: video still
0xF9: e-mail attachment
0xFA: e-mail message
0xFD: INDX record remnant
0xFE: session root directory in CDFS/UDF

Windows attributes or Unix-style permissions
and other flags, whose meaning is theoretically subject to change
0x00000001: Windows attribute read only
0x00000002: Windows attribute hidden
0x00000004: Windows attribute system
0x00000020: Windows attribute to be archived
0x00000040: is a process (in Windows memory dumps)
0x00000080: is on running list (in Windows memory dumps)
0x00000100: Windows attribute temporary
0x00000200: Windows attribute sparse
0x00000400: Windows attribute reparse point
0x00000800: Windows attribute compressed
0x00001000: Windows attribute offline
0x00002000: Windows attribute not indexed
0x00004000: Windows attribute encrypted
0x00010000: additional hard link
0x00020000: Windows attribute no scrub data
0x00020000: compressed in file archive
0x00040000: encryption suspected
0x00080000: encrypted in file archive
0x00100000: start sector only approximately correct
0x00200000: hardlink management flag
0x00400000: encrypted in file system
0x00800000: file format specific encryption
0x01000000: has object ID
0x02000000: compressed in file system
0x04000000: partially initialized
0x08000000: special storage, multi-purpose flag
0x10000000: e-mail message with attachment
0x20000000: multi-purpose flag
0x40000000: has a related item
0x80000000: PhotoDNA hash value buffered

XWF_ITEM_INFO_PIXELINDEX: This is in indicator of the pixel count of a raster image. It is the square root of width × height in pixels, divided by 20. 0: not yet computed or not a picture. 1: <= 0,02 KP. 254 = 16.5 MP. 255 (maximum) = even larger.
BOOL XWF_SetItemInformation(
   LONG nItemID,
   LONG nInfoType,
   INT64 nInfoValue

Sets information about an item (file or directory) in the volume snapshot. For possible values of nInfoType see above and for additional ones below:

v16.5 and later:
#define XWF_ITEM_INFO_FLAGS_SET = 64 // indicates only flags that should be set, others remain unchanged
#define XWF_ITEM_INFO_FLAGS_REMOVE = 65 // indicates flags that should be removed, others remain unchanged

Some XWF_ITEM_INFO_FLAGS  flags can only be retrieved (read), but must not be set or removed. Those are marked above with an asterisk. Some nInfoTypes can only be retrieved, not yet. Those are marked with an asterisk as well.

LONG XWF_GetItemType(
   LONG nItemID,
   LPWSTR lpTypeDescr,
   DWORD nBufferLenAndFlags

Retrieves a textual designation of the type of the specified file (e.g. “jpg” or “dll”) and returns information about the status of the type detection of the file: 0=not verified, 1=too small, 2=totally unknown, 3=confirmed, 4=not confirmed, 5=newly identified, 6 (v18.8 and later only)=mismatch detected. -1 means error. The pointer to the buffer that receives the type description may be NULL if no textual information is required. Otherwise it should have space for a few characters at least. If no textual designation is retrieved, the first character in the buffer is set to NULL.

nBufferLenAndFlags contains the length of the buffer that lpTypeDescr points to in the lower word, measured in characters, and in v18.9 and later may be optionally combined with one of the below flags.

0x20000000: receive a textual description of the file type instead (e.g. “JPEG” or “Dynamic-Link Library”)
0x40000000: receive a textual designation of the category that the file type belongs to instead (e.g. “Pictures” or “Programs”)
0x80000000: receive type status as usual in the lowest byte, but file format consistency in the second-lowest byte (0=unknown, 1=OK, 2=irregular), v19.3 and later

Deprecated: If in v18.8 and some later versions you specify the additive inverse of the buffer length as the third parameter, without any of the above flags, and then cast from a signed to an unsigned 32-bit integer, you will also receive a textual designation of the category that the file type belongs to instead of the file type designation.

VOID XWF_SetItemType(
   LONG nItemID,
   LPWSTR lpTypeDescr,
   LONG nTypeStatus

Sets textual type designation of the specified file (or specify NULL if not required) and information about the status of the type detection of the file (see above).

LONG XWF_GetItemParent(
   LONG nItemID

Returns the ID of the parent of the specified item, or -1 if the item is the root directory or if for some strange reason no parent object is assigned.

VOID XWF_SetItemParent(
   LONG nChildItemID,
   LONG nParentItemID

Sets the parent of the specified child item. You may specify -1 for the virtual "Path unknown" directory as the parent, or -2 for the "Carved files" directory. If the parent is a file that does not have child objects yet, you should use XWF_SetItemInformation to mark it has having child objects.

LONG XWF_GetHashSetAssocs(
   LONG nItemID,
   LPWSTR lpBuffer,
   LONG nBufferLen

Available in v19.3 SR-9, v19.4 SR-8, and later versions. Retrieves the names of the hash sets that the specified file is associated with. The names are delimited with comma and space. If the buffer was filled completely, that likely means that the specified buffer length was insufficient. Returns the total number of associations of that file that were resolved into hash set names, or a negative number in case of certain fundamental errors. This function can be expected to work successfully only if the original hash database(s) in which matches were found is/are still available and can be loaded.

DWORD XWF_GetReportTableAssocs(
   LONG nItemID,
   LPWSTR lpBuffer,
   LONG nBufferLen

Retrieves the names of the report tables that the specified item is associated with in the buffer provided by you. The names are delimited with comma and space. If the buffer was filled completely, that likely means that the specified buffer length (in Unicode characters) was insufficient. In v17.6 SR-7 and later, this function returns the total number of associations of that item, and lpBuffer may be NULL if you are only interested in that number.

LONG XWF_AddToReportTable(
   LONG nItemID,
   LPWSTR lpReportTableName,
   DWORD nFlags

Associates the specified file with the specified report table. If the report table does not exist yet in the currently active case, it will be created. Returns 1 if the file was successfully and newly associated with the report table, 2 if that association existed before, or 0 in case of failure, for example if no case is active or if the volume that the file is contained in is not an evidence object in the active case.

nFlags: Flags for the newly created report table. They have no effect if the report table already existed before.
0x01: show as created by application, not by examiner
0x02: select for inclusion in report
0x04: select for filtering
0x08: select for future manual report table associations

LPWSTR XWF_GetComment(
   LONG nItemID

Retrieves a pointer to the comment of an item, if any, otherwise NULL. This pointer is guaranteed to be valid only at the time when you retrieve it.

BOOL XWF_AddComment(
   LONG nItemID,
   LPWSTR lpComment,
   DWORD nFlagsHowToAdd

Adds the specified comment to the specified item and (in v19.5 SR-11, v19.6 SR-9, v19.7 SR-4 and later) returns true to signal success.

0x01: append to any existing comment, do not replace it
0x02: append to any existing comment, do not replace it, and insert a line break as a delimiter

LPWSTR XWF_GetExtractedMetadata(
   LONG nItemID

Available in v17.7 and later. Retrieves a pointer to a subset of the internal metadata of a file as stored in the volume snapshot (as extracted by volume snapshot refinement and as seen in the Metadata column), in plain text form, or returns NULL if no such metadata exists. The pointer is guaranteed to be valid only at the time when you retrieve it. If you wish to do something with the text that it points to after your X-Tension returns control to X-Ways Forensics, you need to copy it to your own buffer. Related functions: XWF_GetMetadata and XWF_GetMetadataEx.

BOOL XWF_AddExtractedMetadata(
   LONG nItemID,
   LPWSTR lpComment,
   DWORD nFlagsHowToAdd

Available in v17.7 and later. Adds the specified plain text to the extracted metadata of the specified item. It is suggested to mark an X-Tension's addition to the extracted metadata with a marker in square brackets, like [XT], with up to 4 arbitrary characters between the brackets.

0x01: append to any existing extracted metadata, do not replace it
0x02: append to any existing extracted metadata, do not replace it, and insert a line break as a delimiter

BOOL XWF_GetHashValue(
   LONG nItemID,
   LPVOID lpBuffer

Available in v16.8 and later. May be used to retrieve the hash value of a file if one has been computed or to get it computed if not. Whether or not a hash value has been computed previously can be checked separately by calling XWF_GetItemInformation if required (as prior to v19.7 this function did not check that and returned TRUE already if no I/O error occurred). To find out the type of hash value, call XWF_GetVSProp with XWF_VSPROP_HASHTYPE1 or XWF_VSPROP_HASHTYPE2.

When the function is called, the buffer is assumed to start with a DWORD value. That value determines what the function does. The same buffer will be used to accommodate the requested hash value when control is returned to the caller (if the function succeeds). The required buffer size depends on the hash type. The following DWORD values are currently defined:

• Case 1: < 0x00000100:
0x01: flag to retrieve the primary hash value
0x02: flag to retrieve the secondary hash value, requires v18.0 SR-12, v18.1 SR-7, v18.2 SR-5, v18.3 SR-4 or later
0x10: flag to make this function compute the requested value(s) during the call if the hash value is not stored in the volume snapshot yet, which requires v19.7 or later, and a handle to the file (hItem) must be stored in the buffer at offset 4, i.e. directly after the DWORD value

Note that only v19.7 and later can retrieve or compute two hash values at the same time. The buffer must be large enough to accommodate both hash values. If two hash values are requested and retrieved, the first hash value will be stored at the start of the buffer (buffer offset 0). The offset in the buffer where the second hash value starts depends on the size (and thus the type) of the first hash value. Prior to v19.7 you needed two separate calls to retrieve both hash values.

• Case 2: >= 0x00000100:
Subject to change at any time (yes, literally): In v18.8 and later, this function may also be used to retrieve pre-computed PhotoDNA hash values from the volume snapshot. For that purpose the buffer must be filled with a DWORD value of 0x00000100 or greater. 0x00000100 retrieves the 1st, 0x00000101 retrieves the 2nd, and 0x00000102 the 3rd PhotoDNA hash value (only 1 at a time). Note that for most items, if at all, X-Ways Forensics only computes 1 such hash value. Note that it depends on the user whether or not PhotoDNA hash values are permanently stored in the database, which is a precondition for this function to work. The buffer must have space for 144 bytes when retrieving PhotoDNA hash values. The function returns TRUE if a PhotoDNA hash value was available and actually copied into lpBuffer.

BOOL XWF_SetHashValue(
   LONG nItemID,
   LPVOID lpHash,
   DWORD nParam

Available in v19.0 and later. Sets the hash value of the specified item. Returns true if no I/O error occurred when taking the hash value over into the volume snapshot. To find out the expected type of hash value, call XWF_GetVSProp with XWF_VSPROP_HASHTYPE1 or XWF_VSPROP_HASHTYPE2. lpHash is expected to point to the hash value that you provide, in binary. The length is implicitly determined by the expected hash value type. 

1: Set the primary hash value of the item.
2: Set the secondary hash value of the item.

VOID XWF_SetItemDataRuns(
   LONG nItemID,
   LPVOID lpBuffer

Provides extents for an item so that X-Ways Forensics knows how to open it and read its data from the volume if it's neither a contiguous carved file nor defined by any file system data structure nor attached from an external source. Not currently implemented.

File Contents Functions

LPWSTR XWF_GetMetadata(
   LONG nItemID,
   HANDLE hItem

Available in v17.7 and later. Not thread-safe. Deprecated as of v18.9 and superseded by XWF_GetMetadataEx. Extracts a subset of the internal metadata of files of various types, as plain text, and returns a pointer to it if successful, or NULL otherwise. The pointer is guaranteed to be valid only at the time when you retrieve it. If you wish to do something with the text that it points to after your X-Tension returns control to X-Ways Forensics, you need to copy it to your own buffer. Unlike XWF_GetExtractedMetadata, the file must have been opened with XWF_OpenItem because this function reads from the file contents, not from data stored in the volume snapshot. The metadata is taken from the very file that contains it, for example in the case of zip-style Office documents from the XML files.

LPVOID XWF_GetMetadataEx(
   HANDLE hItem,
   PDWORD lpnFlags

Available in v18.9 and later. Can extract extensive internal metadata of files of various types, exactly as seen in Details mode in X-Ways Forensics, typically much more than GetMetadata. Fills a memory buffer with either null-terminated UTF-16 plain text or null-terminated ASCII HTML code, and returns a pointer to it. You may parse the buffer to retrieve specific metadata that you need. The format may theoretically change from one version to the other. You must release the allocated memory by passing that pointer to XWF_ReleaseMem when you do not need it any more. If no metadata is extracted, the return value is NULL instead.

Unlike XWF_GetMetadata, this function is thread-safe. Unlike XWF_GetExtractedMetadata, the file must have been opened with XWF_OpenItem because this function reads from the file contents, not from data stored in the volume snapshot. The metadata is taken from the very file that contains it, for example in the case of zip-style Office documents from the XML files.

lpnFlags points to flags for input and output. The only currently defined input flag is 0x01. It tells X-Ways Forensics to extract only a subset of the available metadata, as shown in the software in the Metadata column. The resulting buffer currently contains always UTF-16 plain text. If the flag is not set, the complete metadata as seen in Details mode is extracted. The resulting buffer can be of either above-mentioned formats.

The only currently defined output flag is 0x01 (indicating, if set, that the resulting buffer is HTML-formatted ASCII instead of UTF-16 plain text). If any of the 8 highest bits are set, you should not touch the resulting buffer, just release it with XWF_ReleaseMem. The output flags are valid only if the function was successful, i.e. if it has returned a pointer.

LPVOID XWF_GetRasterImage(
   struct RasterImageInfo* pRIInfo

#pragma pack(2)
struct RasterImageInfo {
   DWORD nSize,
   LONG nItemID,
   HANDLE hItem,
   DWORD nFlags,
   DWORD nWidth,
   DWORD nHeight,
   DWORD nResSize

Available in v18.0 and later. Provides a standardized true-color RGB raster image representation for any picture file type that is supported internally in X-Ways Forensics (e.g. JPEG, GIF, PNG, ...), with 24 bits per pixel. The result is a pointer to a memory buffer, or NULL if not successful (e.g. if not a supported file type variant or the file is too corrupt). The caller is responsible for releasing the allocated memory buffer when no longer needed, by calling the Windows API function VirtualFree, with parameters dwSize = 0 and dwFreeType = MEM_RELEASE.

nSize must be set to the size of the structure. nItemID and hItem must be provided as well. You may specify any combination of the below flags that makes sense for you. The dimensions of the picture in pixels (nWidth and nHeight) are returned, as well as the size in bytes (nResSize). If you specify a non-zero value for nWidth and/or nHeight for input, it will be interpreted as the maximum width or height that you would like for the resulting image, and the image will be shrunk accordingly (resized, not cropped), if its dimensions are not smaller than that anyway, while preserving the aspect ratio of the original picture.

0x01: get a memory buffer that starts with an appropriate Windows Bitmap header
0x02: align line offsets at 4-byte boundaries
0x04: vertically flip image, physically (reverse the order of pixel lines in the memory buffer)
0x07: create a standard Windows BMP image (suitable combination of flags 0x01, 0x02, and 0x04)
0x08: vertically flip image, logically (only in conjunction with 0x01, using a negative height in the BMP header)
0x10: horizontally flip image, physically (reverse the order of the pixels in each line in the memory buffer)

Search-Related Functions

LONG XWF_Search(
   struct SearchInfo* pSInfo
   struct CodePages* pCPages

#pragma pack(2)
struct SearchInfo {
   DWORD nSize,
   HANDLE hVolume,
   LPWSTR lpSearchTerms,
   DWORD nFlags,
   DWORD nSearchWindow

#pragma pack(2)
struct CodePages {
   DWORD nSize,
   WORD nCodePage1,
   WORD nCodePage2,
   WORD nCodePage3,
   WORD nCodePage4,
   WORD nCodePage5

Available in v16.5 and later. Must only be called from XT_Prepare or XT_Finalize. Runs a simultaneous search for multiple search terms in the specified volume. The volume must be associated with an evidence object. Note that if this function is called as part of volume snapshot refinement, it can be called automatically for all selected evidence objects if the user applies the X-Tension to all selected evidence objects. Returns a negative value in case of an error.

hVolume: Currently must be 0, function is always applied to the active volume

lpSearchTerms: Delimited by line breaks; will be added to the case if not yet existing. 

nFlags: Can be combined only as known from the user interface! For example, GREP and whole words are mutually exclusive. Otherwise the result is undefined.
#define XWF_SEARCH_LOGICAL 0x00000001 // logical search instead of physical search (only logical search currently available)
#define XWF_SEARCH_TAGGEDOBJ 0x00000004 // tagged objects in volume snapshot only
#define XWF_SEARCH_MATCHCASE 0x00000010 // match case
#define XWF_SEARCH_WHOLEWORDS 0x00000020 // whole words only
#define XWF_SEARCH_GREP 0x00000040 // GREP syntax
#define XWF_SEARCH_OVERLAPPED 0x00000080 // allow overlapping hits
#define XWF_SEARCH_COVERSLACK 0x00000100 // cover slack space, even for omitted files
#define XWF_SEARCH_COVERSLACKEX 0x00000200 // cover slack/free space transition
#define XWF_SEARCH_DECODETEXT 0x00000400 // decode text in standard file types
#define XWF_SEARCH_DECODETEXTEX 0x00000800 // decode text in specified file types // not yet supported
#define XWF_SEARCH_1HITPERFILE 0x00001000 // 1 hit per file needed only
#define XWF_SEARCH_COVERSLACK2 0x00002000 // cover slack space, but not for omitted files, v16.6 and later
#define XWF_SEARCH_WHOLEWORDS2 0x00004000 // whole words only for search terms specially marked, from v16.9
#define XWF_SEARCH_GREP2 0x00008000 // GREP syntax only search terms that start with "grep:", supported from v16.9
#define XWF_SEARCH_OMITIRRELEVANT 0x00010000 // omit files classified as irrelevant
#define XWF_SEARCH_OMITHIDDEN 0x00020000 // omit hidden files
#define XWF_SEARCH_OMITFILTERED 0x00040000 // omit files that are filtered out
#define XWF_SEARCH_DATAREDUCTION 0x00080000 // recommendable data reduction
#define XWF_SEARCH_OMITDIRS 0x00100000 // omit directories
#define XWF_SEARCH_CALLPSH 0x01000000 // see below, observed from v16.8 SR-5
#define XWF_SEARCH_IGNORECODEPAGES 0x02000000 // ignore the code pages, keep the previously used ones, v16.9
#define XWF_SEARCH_DISPLAYHITS 0x04000000 // display search hit list when the search completes

Only if the XWF_SEARCH_CALLPSH flag is specified, X-Ways Forensics will call XT_ProcessSearchHit, if exported, for each hit. You may use that function to monitor and filter the search hits that you get, for example to prevent the output of irrelevant search hits or to keep knowledge of all search hits to yourself. Other X-Tensions' XT_ProcessSearchHit function will not be called. Instead of using XT_ProcessSearchHit, in later versions of the API only, you can traverse the list of all search hits after completion and check which ones are for the search terms that you had created/searched for.

nSearchWindow: 0 for standard search window length

pCPages: See this web page for possible code page identifiers. Specify 0 for unused code page numbers.

LONG XWF_AddSearchTerm(
   LPWSTR lpSearchTermName,
   DWORD nFlags

Available in v18.5 and later. Creates a new search term and returns its ID or (if flag 0x01 is specified) alternatively returns the ID of an existing search term with the same name, if any. Returns -1 in case of an error. The maximum number of search terms in a case is currently 8,191 (in v18.5). Use this function if you wish to automatically categorize search hits (assign them to different search terms) while responding to calls of XT_ProcessSearchHit or using XWF_SetSearchHit.

0x01: allow re-use of existing search term of the same name
0x02: mark search term as a search term for user search hits

LPWSTR XWF_GetSearchTerm(
   LONG nSearchTermID,
   LPVOID pReserved

Available in v17.7 and later. Retrieves a pointer to the null-terminated name of the search term with the specified ID, or NULL if no search term with that ID exists. You may set nSearchTermID to -1 to get the total number of search terms back (cast the pointer returned to integer). All search terms have consecutive IDs starting with 0. pReserved must be set to NULL.

LONG XWF_AddSearchHit(
   struct SearchHitInfo* pInfo

Creates a new search hit. Not currently implemented.

LONG XWF_GetSearchHit(
   DWORD nSearchHitNo,
   struct SearchHitInfo* pInfo

Retrieves details about a search hit. Not currently implemented.

LONG XWF_SetSearchHit(
   DWORD nSearchHitNo,
   struct SearchHitInfo* pInfo

Changes details of a search hit. Not currently implemented.

... ...

Event-Related Functions

LONG XWF_AddEvent(
   struct EventInfo* pEvt

#pragma pack(2)
struct EventInfo {
   DWORD nSize,
   HANDLE hEvidence,
   DWORD nEvtType,
   DWORD nFlags,
   FILETIME TimeStamp,
   LONG nItemID,
   INT64 nOfs,
   LPSTR lpDescr

Available in v17.6 and later. Allows to add events to the internal event hit list of an evidence object. The internal event is loaded and accessible only if the evidence object is open. Returns 1 if the event was successfully added, 2 if deliberatedly ignored, or 0 in case of failure to signal that the caller should stop adding more events.

nSize: Size of this structure. Must be properly initialized.

nEvtType: 0 for unknown. File system events: 100+. File metadata events: 1000+. Internet events: 8000+. Messaging events: 10000+. Operating system events: 14000+. Windows event log events: 15000+. Windows registry events: 20000+.

0x04: low timestamp precision, only seconds
0x08: low timestamp precision, only even numbers of seconds
0x10: very low timestamp precision, only date
0x20: timestamp in local time, not UTC
0x40: designates an outdated timestamp

nItemID: If the event is related to a particular object in the volume snapshot (file or directory), that object's ID, otherwise -1.

nOfs: Offset where the timestamp was found in the volume or (if nItemID unequal to -1) within the object in the volume snapshot. -1 if unknown.

lpDescr: Optional null-terminated textual description of the event, preferably in 7-bit ASCII or else in UTF-8. Will be truncated internally after 255 bytes. NULL if not provided.

   DWORD nEventNo,
   struct EventInfo* pEvt

Available in v18.1 and later. Retrieves information about an event from the internal event hit list of an evidence object. The internal event is loaded and accessible only if the evidence object is open. The structure will be populated with values as described above, except where noted. Returns MAXDWORD if unsuccessful, or otherwise the length of the description copied into the lpDescr buffer, in bytes. 0 indicates success as well as a description is not necessarily available or desired by the caller.

nSize: Size of this structure. Must be properly initialized. If you specify a size that covers just nSize and hEvidence, the nEventNo parameter is ignored and you will get the total number of events in the event list of that evidence object returned and no other information. That total event count may include events that are internally considered deleted already. There mere event count is available even if the evidence object is not open.

hEvidence: A handle to the evidence object whose event hit list you wish to target.

nFlags: 0x01: event internally considered deleted already. For other values see XWF_AddEvent.

lpDescr: May be NULL or point to a buffer of 256 bytes that will be filled with a null-terminated textual description in 7-bit ASCII or UTF-8.

Evidence File Container Functions

HANDLE XWF_CreateContainer(
   LPWSTR lpFileName,
   DWORD nFlags,
   LPVOID pReserved

Available in v16.5 and later. Creates a new or opens an existing evidence file container (in its native, raw format) and returns a handle to it if successful (otherwise returns 0). Currently only 1 container can be open at a time for filling. If a container is open already when this function is called, that other container will be closed automatically.

#define XWF_CTR_OPEN 0x00000001 // opens an existing container, all other flags are ignored, works in v19.1 SR-10, v19.2 SR-8, v19.3 SR-8, v19.4 SR-4 and later
#define XWF_CTR_RESERVED 0x00000002 // do not use
#define XWF_CTR_SECURE 0x00000004 // mark this container as to be filled indirectly/secure
#define XWF_CTR_TOPLEVELDIR_COMPLETE 0x00000008 // include ev. object names as top directory level
#define XWF_CTR_INCLDIRDATA 0x00000010 // include original directory data structures
#define XWF_CTR_FILEPARENTS 0x00000020 // allow files as parents of files
#define XWF_CTR_USERREPORTTABLES 0x00000100 // export associations with user-created report table
#define XWF_CTR_SYSTEMREPORTTABLES 0x00000200 // export associations with system-created report tables (currently requires 0x100)
#define XWF_CTR_ALLCOMMENTS 0x00000800 // always pass on comments, v18.9 and earlier
#define XWF_CTR_TOPLEVELDIR_PARTIAL 0x00001000 // include direct ev. object name as top directory level

LONG XWF_CopyToContainer(
   HANDLE hContainer,
   HANDLE hItem,
   DWORD nFlags,
   DWORD nMode,
   INT64 nStartOfs,
   INT64 nEndOfs,
   LPVOID pReserved

Available in v16.5 and later. Copies a file to an evidence file container. Returns 0 if successful, otherwise an error code. If the error code is negative, you should not try to fill the container further. nStartOfs and nEndOfs should be -1 for any nMode where they are not used.

0x00000001: recreate full original path
0x00000002: include parent item data (requires flag 0x1)
0x00000004: store hash value in container
0x00000010: store comment, if existent, in container (v19.0 and later)
0x00000020: store extracted metadata, if available, in container (v19.0 and later)

0: copy logical file contents only
1: copy physical file contents (not supported)
2: logical contents and file slack separately
3: copy slack only
4: copy range only (from nStartOfs to nEndOfs)
5: copy metadata only

LONG XWF_CloseContainer(
   HANDLE hContainer,
   LPVOID pReserved

Available in v16.5 and later. Closes a container. Returns 1 if succesful.

Miscellaneous Functions

VOID XWF_OutputMessage(
   LPWSTR lpMessage,
   DWORD nFlags

Outputs the specified message in the Messages window. You may use this function for example to alert the user of errors or to output debug information.

0x00000001: append without line break (will be delimited from the previous message with a space instead)
0x00000002: don't log this error message in msglog.txt even if logging is active by default
0x00000004: lpMessage points to an ANSI string, not a Unicode string (v16.5 and later)
0x00000010: output the message as an entry in the case log, not in the Messages window (v19.4 and later), flag is ignored if no case is active, may be combined with the 0x4 flag

INT64 XWF_GetUserInput(
   LPWSTR lpMessage,
   LPWSTR lpBuffer,
   DWORD nBufferLen,
   DWORD nFlags

Available in v18.5 and later. Requests user input through a dialog window provided by X-Ways Forensics. This input can be text (e.g. a password) or can be directly interpreted as an integer number. lpMessage is presented to the user (truncated if too long) as an explanation for what is required, and the text entered by the user is filled into lpBuffer (not when requesting a positive integer number). nBufferLen is the length of the buffer in characters (including a terminating null character). You may suggest user input by filling lpBuffer already when calling this function. If you do not wish to suggest any input, lpBuffer must start with a NULL character. The function returns the number of characters filled into the buffer (excluding the terminating null character), or -1 if the user clicked Cancel or if the user supplied invalid input.

0x00000001: Requires the user to enter a positive integer number. That integer number is returned by this function. lpBuffer and nBufferLen must be NULL/zero. 
0x00000002: Empty user input allowed. Mutually exclusive with the previous flag.
0x00000010: Gives X-Ways Forensics a hint that the X-Tension is requesting a password, so that for example no screenshot of the dialog window is taken for the log.

VOID XWF_ShowProgress(
   LPWSTR lpCaption,
   DWORD nFlags

Creates a progress indicator window with the specified caption before a lengthy operation. You should call XWF_ShouldStop occasionally during the operation to allow for the GUI to stay responsive and to check whether the user wishes to stop whatever you are doing. You must not use any of the progress indicator functions when implementing XT_ProcessItem or XT_ProcessItemEx or when calling XWF_* functions that create a progress bar themselves.

0x00000001: show just the window, no actual progress bar
0x00000002: do not allow the user to interrupt the operation
0x00000004: show window immediately
0x00000008: double-confirm abort
0x00000010: prevent logging

VOID XWF_SetProgressPercentage(
   DWORD nPercent

Sets the progress in percent.

VOID XWF_SetProgressDescription(
   LPWSTR lpStr

Displays descriptive text about the progress.

BOOL XWF_ShouldStop(

Should be called regularly during lengthy operations conducted by your X-Tension. If a progress indicator window is on the screen (created by X-Ways Forensics itself or by your X-Tension with the XWF_ShowProgress function), this will tell you whether or not the user wants to abort the current operation (returns TRUE if so). And if that is the case, you should probably finish what you are doing some time soon.

Since v19.3 this function also helps to keep the GUI responsive and helps to convince the user that the application is not hanging. This is done if and required/helpful when the X-Tension is not executed in a separate worker thread. The effect is that mouse and keyboard input will be processed, windows in the GUI get a chance to redraw, and the user's attempt to close the progress indicator window will be noticed. So even if you ignore the result of this function call during lengthy operations conducted by your X-Tension, you are doing something good already by making the calls in the first place (except in v19.2 and earlier, where nothing will happen).

VOID XWF_HideProgress(

Closes the progress indicator window.

BOOL XWF_ReleaseMem(
   PVOID lpBuffer

Call this function to release a buffer allocated by X-Ways Forensics if instructed to do so in the description of another XWF_* function.

If you are missing certain functionality here that is available via the user interface of X-Ways Forensics, please contact us and describe in a few words for what function you suggest and for what reason if would be useful. Perhaps that functionality or something similar can be provided in a future version of X-Ways Forensics. Thank you.