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

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

Retrieves various information about the volume. All parameters are optional, and most are self-explanatory.

Available in v19.9 SR-7 and later. Retrieves information about the specified volume or item, 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.  

 

nPropType	actual result type	pBuffer type	description
0	INT64	(unused)	physical size of a file or volume or disk
1	INT64	(unused)	logical size of a file
2	INT64	(unused)	valid data length of a file (a.k.a. initialized size of the data stream, which may be available from NTFS, exFAT, XWFS, XWFS2)
4	DWORD	(unused)	attributes of a file
8	LPWSTR	(unused)	pointer to the file path, if available, or just name
9	LPWSTR	(unused)	pointer to the pure name
10	HANDLE	(unused)	parent volume of a file
16	WORD	(unused)	the 1-based number of the data window that shows the specified volume or file, can be 0 in unusual cases to indicate an error

Deprecated. If your X-Tension requires v19.9 SR-7 or later anyway, call XWF_GetProp() instead, please. 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).

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.

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 values are supported by v17.5 SR-11, v17.6 SR-7, v17.7 and later unless specified otherwise:

0x0001 = open for access including file slack
0x0002 = suppress error messages in the program in case of failure
0x0008 = prefer alternative file data if available, e.g. a thumbnail created by X-Ways Forensics for a picture
0x0010 = open alternative file data if available, and fail if not (v17.7 SR-3 and later)
0x0080 = open carved files in Ext2/3 volumes without applying Ext block logic (at least v19.8 and later)
0x0200 = convert to PDF format on the fly and open PDF data (v19.9 and later, not in WinHex Lab Edition useful for certain supported file formats)*
0x0400 = extract plain text on the fly as UTF-8 and open textual data (v20.0 and later, useful for certain supported file formats)*
0x0800 = extract plain text on the fly as UTF-16 and open textual data (v20.0 and later, useful for certain supported file formats)*
0x1000 = prepend byte-order mark (for 0x0400 and 0x0800)
*You can find out the size in bytes of the result by calling XWF_GetSize().

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

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.

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.

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

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.

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

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. If you wish to refresh the display, you can for example call the Windows API function InvalidateRect() for the current data window's hex window.

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.

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.

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

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

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, a directory/path, or single file) 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.

nType:
0: single file, e.g. archive file
1: image
2: memory dump
3: directory
4: physical disk or logical drive letter

The following flags can be ored to an nType of 0 or 3 if needed, i.e. for single files and directories. The flags will be understood by v21.1 and later and ignored by earlier versions.
0x00010000: do only include the creation timestamp of the file or directory in the volume snapshot
0x00020000: do only include the modification timestamp in the volume snapshot
0x00040000: do only include the record change timestamp in the volume snapshot (if available at all)
0x00080000: do only include the last access timestamp in the volume snapshot
0x00100000: if set, that means the above 4 flags/bits are valid (otherwise the user settings will decide)

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.

If not currently open, opens the specified evidence object in a data window. A handle to the evidence object is expected for that, which is returned by the functions XWF_GetFirstEvObj, XWF_GetNextEvObj, and XWF_CreateEvObj. Such a handle remains valid until a case is closed. Opening an evidence object at the operating system level also means opening the corresponding disk or image file or interpreting the image file (if the evidence object is an image). This will also load or take the volume snapshot. This function 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 looking for/touching 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

Closes the specified evidence object if it is currently open, also the volume that it represents, and unloads the volume snapshot. Does nothing if the evidence object is not currently open. Available from v17.6.

#pragma pack(2)
struct DaylightSavingsDefinition {
   WORD FlagsAndMore,
   BYTE DaylightSavingStartHour,
   BYTE DaylightSavingStartDayAndWeek,
   BYTE DaylightSavingStartMonth,
   BYTE DaylightSavingEndHour,
   BYTE DaylightSavingEndDayAndWeek,
   BYTE DaylightSavingEndMonth
};

Retrieves information about the specified evidence object, through the buffer and/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. 

*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, in v19.9 SR-11, v20.0 SR-6 and later
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

In the structure DaylightSavingsDefinition, FlagsAndMore in its highest bit tells you whether or not daylight saving is happening in that time zone. If not, you can ignore all the remaining bytes. If daylight saving is defined, then you learn the start hour and the end hour in two separate bytes. Two more bytes tell you the start and end day of the week in the higher nibble, where 0 means Sunday, and the number of that weekday in its respective month in the lower nibble, where 5 means it's the last such weekday in that month. Two more bytes tell you the start and the end of month of daylight saving, from 1 (January) to 12 (December).

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.

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 ever deal with) and can be used to reliably recognize a known evidence object. Available from v18.7.

Available in v17.7 and later. If nReportTableID designates an existing label or report table in the current case, returns a pointer to the null-terminated name of that label/report table, or otherwise NULL. nReportTableID may be set to -1 to retrieve the maximum number of labels/report tables supported by the active version in the integer pointed to by lpOptional. Valid label/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: hint for user 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 label/report table filter
0x0040: selected for new assocations
0x0080: represents a search term
0x2000: detected object in photo
0x4000: represents a group of duplicate files
0x8000: offered for selection in the report

Available in v17.7 and later. Returns a pointer to an internal list that describes all labels/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 labeled in what way 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. 

Defines to which volume's volume snapshot subsequent calls of the below functions apply should you wish to change that. For example if you open a particular evidence object yourself via XWF_OpenEvObj, which returns a volume handle, you can make your X-Tension address the volume snapshot of that evidence object.

This function has a return value since v20.9. If successful, it returns the total number of items in the specified volume snapshot: files plus directories, including a root directory that is potentially invisible in the user interface, just like when calling XWF_GetItemCount(NULL). If the return value is 0, that is suspicious because volume snapshots consist of at least a root directory, and might mean that no volume snapshot has been created yet or will ever be created for the designated volume. If the return value is negative, an error has occurred (e.g. hVolume is internally not considered to be a volume handle or not currently open or does not represent a data source that has a volume snapshot).

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.

If pTarget is NULL, this function retrieves the total number of items in the current volume snapshot (files and directories). This number may change from call to call if your X-Tension is applied to files of different volume snapshots in a single run (e.g. via volume snapshot refinement in multiple evidence objects or a selection in the Case Root window). Item IDs are consecutive and 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 may address each and every item in that range, be it a file or directory, by specifying its ID. 

If pTarget is (LPVOID) 1, then this function retrieves the total number of files that the X-Tension is applied to via the directory browser context menu [use only for XT_ACTION_DBC or higher as per XT_Prepare()]. This takes into account files that are targeted indirectly because they reside in a selected directory (or in a subdirectory of such a directory) as well as child objects of files that are selected (if the user chooses to include them in processing). Available in v20.3 SR-3 and later.

Available from v17.7. Retrieves the accumulated number of files in the directory with the specified ID and all its subdirectories, recursively. Also works for files that have child objects, and also for the root directory, i.e. the entire volume snapshot. For the latter you may alternatively specify -1 as the nDirID, but the number retrieved that way could be outdated in v20.9 and earlier, in v21.0 until SR-10, in v21.1 until SR-9 and in v21.2 until SR-8.

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, a hint that many more items are expected to be created.

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, 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 in x64 was 2³³-1 in v21.0 and earlier. In v21.1 and later in x64 there is no such limitation any more.

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.

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

Available from v21.1. Mounts the designated file or directory (with the internal ID provided as nDirID) in the volume snapshot, or the entire volume (nDirID = -1 or the internal ID of the root directory), as a drive letter in Windows. Mounting a file could be useful if that file has child objects that should become accessible, otherwise not. lpMountPath points to a buffer of at least MAX_PATH length that is either empty (starts with a NULL character), if you let X-Ways Forensics pick a drive letter, or that points to a NULL-terminated target path of your choice (however, currently only root directories of drive letters are supported). The function will fail if you supply a drive letter that is not available. lpReserved should be NULL. If mounting is successful, the function returns TRUE, and the buffer pointed to by lpMountPath will be filled with the actual mount path (currently always the root directory of a drive letter). Currently only one mount point can exist at a time (that might change in future versions), so this function may fail for example if a mount point already exists, whether it was created by the user through the user interface or by an X-Tension. It is strongly suggested to call XWF_Unmount() for any successful call to XWF_Mount() when a mount point is not longer needed.

Available from v21.1. Unmounts a previous mount point created by XWF_Mount(). lpMountPath should point to the same path returned by XWF_Mount(). In current versions lpMountPath may be NULL to simply unmount any mount point that may currently exist, which could be necessary for XWF_Mount() to succeed if a mount point was created by something other than your own X-Tension.

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. v19.9 and later: In order to retrieve a pointer to the alternative name of an item, you may or nItemID with 0x80000000. Please note that which of two potentially available filenames is considered to be the alternative filename depends on the user settings.

NULL is returned if the requested name cannot be retrieved.

Renames an item. Not currently implemented.

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

Sets the size of the item in bytes. -1 means unknown size. A return value is provided since v21.3 to indicate success or failure.

Retrieves the offset of the file system data structure (e.g. NTFS FILE record) where the item is defined by writing that value at the address given by lpDefOfs. If negative, the absolute value is the offset where a carved file starts on the volume. 0 if an error occurred while retrieving the offset. 0xFFFFFFFF (4294967295, lower 32 bits set) if not available/not applicable. Undefined for files in archives.

Also retrieves the number of the sector from the point of the volume in which the data of the item starts by writing it at the address given by lpStartSector. This number does not depend on whether the user chooses to see physical sector numbers within partitions. -1 in case the number is not available or if an error occurred while retrieving the sector number.

Sets the above-mentioned offset and sector number. A return value is provided since v21.3 to indicate success or failure.

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 provided in Windows FILETIME format, unadjusted (as found in the original metadata, not converted to any other time zone).

#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 (contiguously stored) 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
#define XWF_ITEM_INFO_CREATIONTIME_DISPLAY_OFS = 48 //v21.2 and later
#define XWF_ITEM_INFO_MODIFICATIONTIME_DISPLAY_OFS = 49 //v21.2 and later
#define XWF_ITEM_INFO_LASTACCESSTIME_DISPLAY_OFS = 50 //v21.2 and later
#define XWF_ITEM_INFO_ENTRYMODIFICATIONTIME_DISPLAY_OFS = 51 //v21.2 and later
#define XWF_ITEM_INFO_DELETIONTIME_DISPLAY_OFS = 52 //v21.2 and later
#define XWF_ITEM_INFO_INTERNALCREATIONTIME_DISPLAY_OFS = 53 //v21.2 and later

XWF_ITEM_INFO_*_DISPLAY_OFS: The return value indicates how the respective timestamp that is stored in the volume snapshot and that can be retrieved using the XWF_GetItemInformation function is converted by X-Ways Forensics to the preferred display time zone when needed. It is a positive or negative number of minutes that your X-Tension can add to achieve the same effect, if desired. It can depend on 1) the user's preferred display time zone (which can be the same for the entire case or individually set per evidence object), 2) the base time zone that the timestamp is known to be stored in or the user-set reference time zone that it is supposed to be stored in, 3) whether the timestamp falls into the daylight saving portion of the year according to the base or reference time zone, 4) whether the timestamp falls into the daylight saving portion of the year according to the display time zone. A special return value is -1. It indicates that the timestamp could not be converted to the preferred display time zone and instead is shown as is, in local time, based on whatever time zone that originally may have been, or that no valid timestamp exists. Available since v21.2.

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.

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.

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.

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). A return value is provided since v21.3 to indicate success or failure.

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.

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. A return value is provided since v21.3 to indicate success or failure.

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.

Retrieves a list of names of the labels (formerly known as report tables) that the specified item (usually file) is associated with. Does not receive or count labels that the user excluded from public display. The names are delimited in the list with comma and space. The list is null-terminated. If the buffer was filled completely, that likely means that the specified buffer length was insufficient to accommodate the entire list of labels.

lpBuffer points to a buffer for Unicode characters provided by you. It may be NULL if you are only interested in the return value.

The main purpose of the nBufLenAndMatchType parameter is to indicate the size of your buffer, measured in Unicode characters. That size must not be greater than 2²⁴-1. Since v21.3, if you set the highest byte in this value to one of the following numbers other than zero, you can retrieve only the count and list of labels of one particular label type that you are interested in:
1: user-created labels
2: hint labels
3: search term labels
4: hash sets labels
5: duplicate group labels
6: picture content labels
If you leave the highest byte at zero, you will match all label types, just like in previous versions.

In v17.6 SR-7 through v20.4, this function returned the total number of report table associations of the specified item (not necessarily equal to the number of names that were filled into your buffer) as a simple DWORD.

In versions from v20.5 through v21.2 the return value was (user label count + search term label count) in the lowest valued byte and (hint label count + hash set label count) in the second lowest byte. You can add those two sums to get a grand total.

Since v21.3 the return value is a more detailed byte-wise conglomerate of individual label counts:
(1) The lowest valued byte indicates the number of user-created labels.
(2) The next byte indicates the number of hint labels.
(3) The next byte indicates the number of labels representing search terms.
(4) The next byte indicates the number of labels representing hash sets.
(5) The next byte indicates the number of labels representing duplicate groups.
(6) The next byte indicates the number of labels representing picture content.
All of these counts are capped at 255. The highest 2 bytes are currently always zero. That may change in a future version. If the highest byte in nBufLenAndMatchType was zero (meaning you did not target a particular label type) and you sum up the values of the lower 6 bytes of the return value, you currently get the total number of visible labels associated with the specified item (assuming none of the individual counts are 255).

Associates the specified file with the specified label (formerly known as report table). If the label 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 label, 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. You must not use label names that contain a backslash or the delimiter ", " (comma followed by a space).

nFlags: Flags for the newly created label. In v20.4 and earlier, they had no effect if a label of that name already existed before. Since v20.5 an existing label's flags are updated by this function.
0x0001: treat as a label created by application, not by examiner
0x0002: treat as a label created by the examiner
0x0004: treat as a label that represents a hash set match
0x0010: selected for inclusion in report
0x0020: select for filtering
0x0040: select for future manual associations
0x0080: treat as a label that represents a search term
0x2000: treat as a label that represents picture content
0x8000: offered for inclusion in report

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.

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. If lpComment points to a NULL character and nFlagsHowToAdd is 0, an existing comment will be removed (in v20.3 SR-13, v20.4 SR-8, v20.5 SR-6, v20.6 SR-4 and later).

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

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.

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.

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

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). You can call XWF_GetVSProp with XWF_VSPROP_HASHTYPE1 or XWF_VSPROP_HASHTYPE2 etc. to find out the type of hash value defined in the volume snapshot or set it. (No hash value can be retrieved or computed if not even the hash type is defined.)

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 the 2nd, 0x00000102 the 3rd, and 0x00000103 the 4th PhotoDNA hash value (only 1 at a time). Note that for most files with graphical data, if at all, X-Ways Forensics computes only 1 such hash value. More than 1 hash value may be present if the user requested additional matching attempts with horizontal flipping and/or if X-Ways Forensics is uncertain about the vertical orientation of certain TIFF files. 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.

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.

Available in v20.3 and later. Retrieves cell text for a given item in the volume snapshot for a particular column, as known from the directory browser. This does not depend on whether that item is currently listed in the directory browser or which directory browser columns are visible. The text may be language-specific and may depend on notation options that are active for list exports. Returns 0 or a positive number to indicate success, negative numbers for errors, for example -1 if the specified column index is unknown.

lpPointer: Unused, must be set to NULL.

nFlags: Unused, must be set to 0.

nColIndex: Please see XWF_GetColumnTitle() for an explanation.

lpBuffer: Pointer to your buffer, which will be filled with a null-terminated string in UTF-16.

nBufferLen: The length of the buffer in UTF-16 characters, including space for a terminating NULL.

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.

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.

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 if you specify such an XML file as hItem.

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

Available in v20.3 and later. Prepares X-Ways Forensics for calls of XWF_GetText(), which may be necessary depending on whether similar functionality has already been used in the GUI during the current session or not. Does not override the user's decision to not use the viewer component or OCR in general. 

nFlags: 0x01 means that text decoding should be prepared. You don't need to specify this flag if you are interested in only OCR.

lpLangs: Optional. If not NULL, points to a null-terminated ANSI string that identifies the languages to optimize OCR for, and this will override the configuration in the installation. The language identifiers can be seen in the filenames of *.traineddata files of Tesseract (list). You may concatenate multiple language identifiers with a + sign as long as the length of the result does not exceed 15 characters, e.g. "eng+spa+ita" or "chi_sim+chi_tra". Perhaps later versions will accept longer strings. If lpLangs points to a buffer that starts with a 0x00 character, then your buffer will receive the current language settings. The buffer should be 64 bytes in size at least. It will be null-terminated.

This function returns flags. If no flag in the result is set, that means you did not request text decoding capability or text decoding capability is not available, and OCR is not active either.
0x01: text decoding capability was requested and is available
0x02: extended text decoding capability is available
0x04: dates and number stored in spreadsheets in binary are converted to text as part of text decoding
0x10: OCR capability is active

Available in v20.3 and later. Can extract pure text from files of various types, using means including OCR if OCR functionality is available in X-Ways Forensics (not WinHex Lab Edition), as known from the Text submode of Preview mode in the GUI. How spreadsheets are processed depends on the options in Options | Viewer Programs. If successful, the function returns a pointer to a buffer that you eventually need to release with XWF_ReleaseMem(). The buffer contains text usually in UTF-16 (for exceptions see below).

hItem identifies the file from which to extract text.

nFlags:
0x01: decode text in files that have textual contents
0x02: recognize text in files with graphical contents (OCR)
0x10: retrieve text as 8-bit ASCII or Latin 1 instead of UTF-16 if no contained characters require UTF-16
0x20: retrieve text as 8-bit ASCII or Latin 1 instead of UTF-16 even if characters are lost that way

0x10 and 0x20 have slightly different effects on different computers depending on which ANSI code page is active in the Windows system. If it's the 1252 Latin 1 code page, then Unicode characters from 0x81 to 0xFF are considered convertible. Otherwise such characters are considered not convertible, meaning no conversion from UTF-16 to ASCII takes place or - if forced - such characters are converted to a placeholder character, which is currenly an asterisk (*).

If neither the flag 0x01 nor 0x02 is specified, then no potentially time-consuming attempts will be made to extract text from the file, but if previously extracted text was stored (buffered) in the volume snapshot, that text is still retrieved, and very quickly so. If 0x01 and/or 0x02 are specified and if text was extracted and buffered previously, that "old" text is retrieved and no new extraction is attempted. If 0x01 and 0x02 are combined, that does not mean that both operations are attempted, e.g. in a PDF document. It means that depending on the file type at least one of the two operations are performed, and in currently available versions it means for example for PDF files that first decoding takes place, and if that no text is found that way, OCR will be attempted. In currently available versions the resulting text will never be a mix of both operations.

lpnResult must point to an integer variable ("nResult") which will receive information about the outcome of the function:
>0 = success, flags as defined below
0 = no buffer available, no textual content found
-1 = no buffer available, file seems encrypted
-2 = no buffer available, action aborted
-3 = no buffer available, error occurred

0x01 = pointer to buffer with UTF-16 returned
0x02 = pointer to buffer with 8-bit ASCII/Latin 1 returned
0x10 = text derived through OCR

lpnBufUsedSize may be NULL or point to a DWORD variable, if in case of a positive nResult you wish to know how many bytes in the buffer are considered in use.

lpnBufAllocSize may be NULL or point to a DWORD variable, if in case of a positive nResult you wish to know how many bytes in the buffer are allocated. 

#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, not in WinHex Lab Edition. 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)

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

nSize must be set to the size of the respective structure in bytes and should cover at least all member variables up to nSearchWindow.

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, the whole words options have no effect if GREP is selected. 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 // combined with XWF_SEARCH_WHOLEWORDS means only for indented search terms, from v16.9,
#define XWF_SEARCH_GREP2 0x00008000 // GREP syntax for search terms prepended with "grep:", from v16.9 (prior to v19.9 SR-8 had to be used alone, without  XWF_SEARCH_GREP)
#define XWF_SEARCH_OMITIRRELEVANT 0x00010000 // omit files classified as irrelevant by the hash database
#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_OMITKNOWN 0x00200000 // omit all files known from the hash database, includes XWF_SEARCH_OMITIRRELEVANT, supported from v19.9
#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
#define XWF_SEARCH_USENONLATIN1ALPHABET 0x08000000 // has an effect only if XWF_SEARCH_WHOLEWORDS is set

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

lpLatin1Alphabet: Optional. Supported as of v20.0. If not NULL, points to a null-terminated sequence of letters of Western European languages (in the Latin 1 code page with 1 byte per character) that you consider to be part of words, which defines word boundaries and will change the alphabet settings in X-Ways Forensics. Up to 159 characters are currently utilized. The previously used alphabet will be lost.

lpNonLatin1Alphabet: Optional. Supported as of v20.0. If not NULL, points to a null-terminated sequence of characters (in UTF-16) that you consider to be part of words, which defines word boundaries and will change the alphabet settings in X-Ways Forensics. Up to 99 characters are currently utilized. The previously used alphabet will be lost.

pCodePage* See this web page for possible code page identifiers. Specify 0 for unused code page numbers.

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.

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 search expression/keyword, if any. Returns -1 in case of an error. The maximum number of search terms in a case is currently 8,191 (since 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(). The null-terminated UTF-16 string pointed to by lpSearchTerm may be truncated. Currently, as of v20.3, up to 90 characters are supported.

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

Available in v20.0 and later.

Set nProperty to 0 to delete the specified search term and all its search hits in all evidence objects. That is more efficient than deleting the search hits one by one. If nSearchTermID is -1, that deletes all search terms and all their search hits. pFlags should be set to NULL and is currently unused. The return value of the function is 1 for presumed success, 0 for failure.

Set nProperty to 1 to manage the flags that define the properties of the search terms whose ID you specify. You can retrieve these flags through the function return value (if pValue is NULL) or set those flags (if pValue is not NULL, but please know what you are doing). If you set the flags, a return value of 1 indicates success, 0 indicates failure.

Some possible flag values:
0x0002: last used for a case-sensitive search
0x0004: based on a GREP expression, but got a "friendly" name
0x0010: forced in an AND combination
0x0040: selected in the search term list
0x0080: search hits are excluded
0x0100: GREP expression
0x0200: selected for filter
0x0400: created as a result of data comparison
0x0800: for user search hits (defined manually by the user)
0x1000: search hits are checked for a word boundary at the start
0x2000: search hits are checked for a word boundary at the end
0x4000: search hit represents a data area with a block hash match

Set nProperty to 2 to rename the search term, e.g. assign a more user-friendly name to a complicated regular expression. In that case pValue must point to a null-terminated UTF-16 string. Available in v20.3 and later. The null-terminated UTF-16 string pointed to by lpSearchTerm may be truncated in X-Ways Forensics. Currently, as of v20.3, up to 90 characters are supported. A return value of 1 indicates success, 0 indicates failure.

Creates a new search hit. Not currently implemented.

Retrieves details about a search hit. Not currently implemented.

Changes details of a search hit. Not currently implemented.

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.

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.

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, 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 label/report table
#define XWF_CTR_SYSTEMREPORTTABLES 0x00000200 // export associations with system-created labels/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

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

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

Available in v19.9 SR-7 and later. Retrieves the handle of a window related to a data window, so that you can use it as a parameter in Windows API functions. The possibilities are endless. You could send any kind of message to a window, redraw it, take a screenshot of it, simulate a mouse click, etc. For example, to refresh the contents of a window, you can call the Windows API function InvalidateRect(..., NULL, FALSE).

Not all related windows always exist. The function returns 0 for an unavailable window.

nWndNo: The 1-based number of the data window, for example as retrieved using XWF_GetEvObjProp(). In v20.3 SR-13, v20.4 SR-9, v20.5 SR-6, v20.6 SR-5 and later you may specify 0 to target the active data window (the one in the foreground).

nWndIndex: Identifies the exact window that you are interested in.
0: the data window itself
1: the hex window (may appear as the lower half of the data window)
2: directory browser (may appear as the upper half of the data window)
3: position manager window
4: cluster list window
5: Details mode window (v20.2 and later)
6: viewer component's preview window and (v20.1 and older) Details mode window
7: internal graphics library preview window
8: gallery window
9: calendar window
20-26: mode buttons (currently 7)
40-49: various other buttons

Available in v20.3 and later. Retrieves the title of a particular column in the directory browser. The title depends on the currently active language in the GUI of the application and other factors. Returns true if the requesteed column exist, false if not. You can call this function repeatedly, starting with nColIndex == 0, ideally with nWndNo == 65535, to determine whether the column that you need still exists in the active version or what column index it has.

nWndNo: The 1-based number of the data window for which you wish to retrieve a column title, for example as retrieved using XWF_GetEvObjProp(). Depending on whether the data window shows an event list or not, the first few columns have different names. Depending on the file system and depending on what kind of hash values have been computed, other columns may have variable names. You may specify 0 to retrieve a language-specific column title that just depends on the currently active volume snapshot, if one is active, or 65535 for a standardized column title in English that does not depend on any window or volume snapshot.

nColIndex: Identifies the exact column that you are interested in. These identifiers are constant within a given version of the software and usually constant over many versions, but might change in future versions. They are based on the order of columns that you see in the application by default, if you do not change it in the GUI. E.g. in v20.3:
4: Name
5: Existent
6: Description
7: Ext.
8: Type
...
27: Attr.
...
44: File count
...
57: Metadata
...

lpBuffer: Pointer to your buffer, which should be able to accommodate at least 127 Unicode characters plus a terminating null.

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)
0x00000008: output the message in the Output window instead of the Messages window (v20.6 and later), where no [XT] prefix is inserted
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

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 suitable user input by filling lpBuffer with text 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 the requested positive integer number or -1 if the user clicked Cancel.

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. Not yet implemented.

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

Sets the progress in percent.

Displays descriptive text about the progress.

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

Closes the progress indicator window.

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