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.

nFileSystem:
9=main memory
8=CDFS
7=opened through OS
6=XWFS
5=UDF
4=exFAT
3=FAT32
2=FAT16
1=FAT12
0=Unknown
-1=NTFS
-2=HPFS
-3=Ext2
-4=Ext3
-5=ReiserFS
-6=Reiser4
-7=Ext4
-9=JFS
-10=XFS
-11=UFS
-12=HFS
-13=HFSPlus
-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 XWF_OpenItem(
   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)

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

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

LPVOID XWF_GetDriveInfo
   struct DriveInfo* DInfo
);

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

Not currently implemented.
DWORD XWF_SectorIO(
   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.

nFlags:
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. Retrieves information about the current case. 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_TITLE (1)   LPWSTR   ~   case title
XWF_CASEPROP_EXAMINER (3)   LPWSTR   ~   examiner
XWF_CASEPROP_FILE (5)   LPWSTR   ~   .xfc case file path
XWF_CASEPROP_DIR (6)   LPWSTR   ~   case directory
...   ...   ...   ...
HANDLE XWF_GetFirstEvObj(
   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 XWF_GetNextEvObj(
   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 XWF_DeleteEvObj(
   HANDLE hEvidence
);

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

HANDLE XWF_CreateEvObj(
   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 medium, disk/volume image, memory dump, or a directory/path) andd returns the first evidence object created, or NULL in case of an error. 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.

nType:
0: file
1: image
2: memory dump
3: directory/path
4: disk

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.

HANDLE XWF_OpenEvObj(
   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), loads or takes the volume snapshot and 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 process the volume snapshot. Potentially time-consuming. 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
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. Does not require that the evidence object is open. General error return code is -1. Available from v17.6. 

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

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

HANDLE XWF_GetEvObj(
   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. Retrieves information about the current volume snapshot. 

nPropType   description
XWF_VSPROP_SPECIALITEMID (10)  

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.
XWF_VSPROP_HASHTYPE1 (20)  

Retrieves the type of the primary hash values that the files in the volume snapshot have (in v17.8 SR-17, v17.9 SR-10, v18.0 SR-4 or later) or if not defined yet the type that is going to be used if the user's current preferences remain unchanged (v19.0 SR-7, v19.1 SR-9, v19.2 SR-6 or later). 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)

XWF_VSPROP_HASHTYPE2 (21)  

Same, but retrieves 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.

nCreationFlags:
0x00000001: for performance reasons, set if 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.

nCreationFlags:
0x00000001: For performance reasons, if set, a 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.

pSourceInfo:
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.

nFlags:
0x00000001: match case, for performance reasons

Volume Snapshot Item Property Functions

LPWSTR XWF_GetItemName(
   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_ORIG_ID 1
#define XWF_ITEM_INFO_ATTR 2
#define XWF_ITEM_INFO_FLAGS 3
#define XWF_ITEM_INFO_DELETION 4
#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 within another file, offset in that file
#define XWF_ITEM_INFO_CREATIONTIME = 32
#define XWF_ITEM_INFO_MODIFICATIONTIME = 33
#define XWF_ITEM_INFO_LASTACCESSTIME = 34
#define XWF_ITEM_INFO_ENTRYMODIFICATIONTIME = 35
#define XWF_ITEM_INFO_DELETIONTIME = 36
#define XWF_ITEM_INFO_INTERNALCREATIONTIME = 37

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 world 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

 


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 and later. 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. The names are delimited with comma and space. If the buffer was filled completely, that likely means that the specified buffer length was insufficient. In v17.6 SR-7 and later, returns the total number of associations of that item, and lpBuffer may be NULL.

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.

nFlagsHowToAdd:
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.

nFlagsHowToAdd:
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. Retrieves the hash value of a a file if one has been computed. Whether or not that is the casecan be checked using XWF_GetItemInformation. Returns true in v17.4 and later if no I/O error occurred when copying the hash value into the buffer. To find out the type of hash value, call XWF_GetVSProp with XWF_VSPROP_HASHTYPE1 or XWF_VSPROP_HASHTYPE2. The buffer should be prepared and its start filled with a single DWORD value of 0x00000001. In v18.0 SR-12, v18.1 SR-7, v18.2 SR-5, v18.3 SR-4 and later versions you may fill the buffer with a DWORD 0x00000002 to request the secondary hash value of a file instead of the primary hash value. Deprecated: In v18.0 through v18.9 you may specify -nItemID as nItemID to retrieve the secondary hash value of nItemID, if any is available. 

Subject to change at any time (yes, really): 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 for the first PhotoDNA hash value, 0x00000101 for the 2nd, and 0x00000102 for the 3rd. 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 stored in 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. 

nParam:
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* RIInfo
);

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

nFlags:
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* SInfo
   struct CodePages* CPages
);

#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

CPages: 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.

nFlags:
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* Info
);

Creates a new search hit. Not currently implemented.

LONG XWF_GetSearchHit(
   DWORD nSearchHitNo,
   struct SearchHitInfo* Info
);

Retrieves details about a search hit. Not currently implemented.

LONG XWF_SetSearchHit(
   DWORD nSearchHitNo,
   struct SearchHitInfo* Info
);

Changes details of a search hit. Not currently implemented.

... ...

Event-Related Functions

LONG XWF_AddEvent(
   struct EventInfo* Evt
);

#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+.

nFlags:
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 XWF_GetEvent(
   DWORD nEventNo,
   struct EventInfo* Evt
);

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.

nFlags:
#define XWF_CTR_OPEN 0x00000001 // opens an existing container, all other flags are ignored
#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.

nFlags:
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)

nMode:
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.

nFlags:
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.

nFlags:
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.

nFlags:
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.