X-Ways Forensics X-Tensions API Documentation

Repository of downloadable X-Tensions

The API information below applies to X-Ways Forensics 16.4 SR-3 and later unless otherwise noted.
Last updated on May 26, 2013.

The X-Ways Forensics X-Tensions API is a new application programming interface that allows you to use many of the advanced capabilities of the X-Ways Forensics computer software programmatically and extend them with your own functionality. For example, you could implement some specialized file carving for certain file types, automated triage functionality, alternative report generation, or automatically filter out unwanted search hits depending on your requirements etc.

Among other things, X-Tensions allow you to:

• read from a disk/partition/volume/image
• retrieve abundant information about each file and directory in the volume snapshot
• read from any file
• create new objects in the volume snapshot
• bookmark/classify/categorize files by assigning them to report tables
• add free text comments to files
• run searches
• process, validate and delete search hits
• create and fill evidence file containers
• and do practically everything else that is possible with a Windows program! (thanks to the Windows API)

You can use your compiler and programming language of choice, any one which can create Windows DLLs, for example Visual Studio Express (freeware, more information), Free Pascal (also free), lcc-win (free for non-commercial use) and generally languages such as C++, C, Delphi/Pascal, Visual Basic, so you do not have to learn any new scripting language. A C# port of the X-Tension API is available from here (also here) to make it easier to develop X-Tensions in .Net, thanks to Chad Gough.

Since an X-Tension is not an interpreted script, but regular compiled executable code that is running in the address space of the application itself, you can expect highest performance, the same as with internally implemented functionality in X-Ways Forensics. X-Tensions give you easy and direct access to crucial and powerful functions deep inside our software.

How/when X-Tensions functions can get called:

• when refining the volume snapshot
• when running a simultaneous search
• via the Tools | Run X-Tensions menu command
• via the directory browser context menu
• via the search hit context menu

You may distribute X-Tensions that you compile and/or their source code (ideally both) free of charge or even for a fee, under whatever license terms you see fit. X-Ways does not require any royalty payment. However, you have to accept that the terms, the functionality and the availability of the XWF X-Tensions API/engine may change in future versions of X-Ways Forensics. 

You are encouraged to submit your XWF extensions for download from the X-Ways web site. X-Ways does not check third party X-Tensions and will not be responsible for their quality or any damage caused by them. Please be advised that X-Tensions are executable files that run with the same rights as X-Ways Forensics and could be malware.

Your code needs to be compiled as a DLL, which will be loaded by X-Ways Forensics at run time. In each DLL you have to implement (and export) one or more out of the below-mentioned functions. Which function(s) you implement depends for example on when exactly you would like X-Ways Forensics to call them, such as either at the start or end of the volume snapshot refinement, dealing with the volume or the volume snapshot as a whole, or for each item in the volume snapshot separately when refining it. This part of the API (the XT_* functions) is like a framework based on the so-called Hollywood principle "don't call us, we call you". Unlike in Hollywood, you are actually get called, though.

All exported X-Tension functions and internal XWF API functions use stdcall calling conventions under 32 bit. The API is available only in v16.4 and later of X-Ways Forensics and in the WinHex add-on for X-Ways Forensics, both 32-bit and 64-bit. The name of the DLL should be descriptive. For use in v16.4 the name should start with "XT" and must be less than 32 ASCII characters long, and the DLL must be placed in the same directory where X-Ways Forensics is run from (or if a 64-bit DLL, in the \x64 subdirectory). The data types used are described here.

Up to 8 X-Tensions can be run simultaneously when refining the volume snapshot. Simultaneous instead of subsequent execution is not only convenient, but also saves time if each X-Tension opens and reads from all the files in the volume snapshot one after the other as caching is improved and no time is wasted on multiple identical open/close file operations.  

The X-Tensions DLL gets unloaded as soon as the overall operation has completed, so that when you are debugging your DLL, you can recompile it (overwrite the previous built) while X-Ways Forensics is still running.

C++ function definitions and sample projects (updated 2012-05-18)
Delphi function definitions and 4 sample projects (updated 2012-07-25)

Plug-in for Python with sample scripts (32-bit, updated 2012-08-14)
Select the scripts by clicking the ... button in the X-Tension window. Ideally use v16.5 SR-12 or v16.6 SR-3 or later. Note that interpreted Python code is much, much slower than native code. Not 100% of the functionality is available via the Python plug-in. Functions may be different in Python, refer to readme.txt instead of the below specifications when in doubt. Mini Python

Mandatory to export. Will be called before anything else happens, to inform the DLL of the version of X-Ways Forensics that is loading the DLL, already when the X-Tension is selected by the user in X-Ways Forensics. You may return -1 to prevent further use of the DLL, for example if certain functions that you require are not present (i.e. exported by a certain version of X-Ways Forensics). Otherwise you must return 1.

nVersion: The higher word specifies the version number. For example 1640 means v16.4. The third highest byte specified the service release number. The lowest byte indicates the current language of the user interface of the calling program.

nFlags:
#define XT_INIT_XWF 0x00000001 // X-Ways Forensics
#define XT_INIT_WHX 0x00000002 // WinHex
#define XT_INIT_XWI 0x00000004 // X-Ways Investigator
#define XT_INIT_BETA 0x00000008 // beta version
#define XT_INIT_QUICKCHECK 0x00000020 // called just to check whether the API accepts the calling application (used by v16.5 and later)
#define XT_INIT_ABOUTONLY 0x00000040 // called just to prepare for XT_About or XT_PrepareSearch (used by v16.5 and later)

hMainWnd: Handle of the main window.

lpReserved: Currently always NULL.

If exported (optional), will be called just before the DLL is unloaded to give you a chance to dispose any allocated memory, save certain data permanently etc. You should return 0.

nReserved: currently always NULL.

If exported (optional), will be called when the user requests to see information about the DLL. You can display copyright notices, a version number, a brief description of the exported functionality, extensive help on how to use it, from where in X-Ways Forensics to call it with what settings etc. etc. You could even display a dialog window where the user can change settings for this X-Tension, which you store in the Windows registry or in a permanent file. You should return 0.

nReserved: currently always NULL.

If exported (optional), will be called immediately for a volume when volume snapshot refinement or some other action starts before items or search hits are processed individually.

Possible negative return values:
-4 if you want X-Ways Forensics to stop the whole operation (e.g. volume snapshot refinement) altogether
-3 if you want to prevent further use of the X-Tension for the remainder of the whole operation, for example because your X-Tension is not supposed to do anything for that kind of operation as indicated by nOpType.
-2 if you want this particular volume excluded from the operation
-1 if you don't want other functions of this X-Tension to be called for this particular volume, not even XT_Finalize

Positive return values/combination of flags:
0x00 default, if you just want XT_Finalize to be called, will also be assumed if you do not export XT_Prepare
0x01 of you want X-Ways Forensics to call your implementation of XT_ProcessItem or XT_ProcessItemEx (whichever is exported) for each item this volume snapshot
0x02 in case of XT_ACTION_RVS, same, but to receive calls of XT_ProcessItem (if exported) after all other individual item refinement operations instead of before
0x04 in case of XT_ACTION_RVS, to signal XWF that you may create more items in the volume snapshot, so that for example the user will definitely be informed of how many item were added (v16.5 and later only)

Full return value evaluation only for XT_ACTION_RVS.

hEvidence, nReserved: currently always 0.

nOpType: How the X-Tension is executed within X-Ways Forensics.
#define XT_ACTION_RUN 0 // simply run directly from the main menu, not for any particular volume, since v16.6
#define XT_ACTION_RVS 1 // volume snapshot refinement starting
#define XT_ACTION_LSS 2 // logical simultaneous search starting
#define XT_ACTION_PSS 3 // physical simultaneous search starting
#define XT_ACTION_DBC 4 // directory browser context menu command invoked
#define XT_ACTION_SHC 5 // search hit context menu command invoked

If exported (optional), will be called when volume snapshot refinement or another operation has completed. Return 0.

nOpType: see above
hEvidence, nReserved: currently always 0.

If exported (optional) and if wanted by XT_Prepare, will be called for each file in the volume snapshot that is targeted for refinement or selected and targeted with the directory browser context menu. Implement and export this function if you merely need to retrieve information about the file and don't need to read its data. There is a slight performance benefit if the user does not select other refinement operations that do need to open the item and read its data, i.e. you save a little bit time if a file does not need to opened for reading. If XWF_OpenItem is implemented, you can still open the file to read its data if needed.

Return -1 if you want X-Ways Forensics to stop the current operation (e.g. volume snapshot refinement), -2 if you want have X-Ways Forensics skip all other volume snapshot refinement operations for this file, otherwise 0.

nReserved: currently always 0.

If exported (optional) and if wanted by XT_Prepare, will be called for each item (file or directory) in the volume snapshot that is targeted for refinement or selected and targeted with the directory browser context menu. The item will be opened for reading prior to the function call. Implement and export this function if you need to read the item's data, which you can do using the hItem parameter. Return -1 if you want X-Ways Forensics to stop the current operation (e.g. volume snapshot refinement), otherwise 0.

nReserved: currently always 0. 

For potential future use. If exported (optional), will be called for each file that is to be viewed in a separate window or in Preview mode. The X-Tension can provide a human-readable representation of a binary file for example as plain text or HTML, or any other file format understood by the viewer component.

Return 0 if you do not want to be responsible for providing a representation for this file, -1 if you want to indicate that an error occurred, 1 to signal success.

#pragma pack(2)
struct CodePages {
   LONG iSize,
   WORD nCodePage1,
   WORD nCodePage2,
   WORD nCodePage3,
   WORD nCodePage4,
   WORD nCodePage5
};

If exported (optional), will be called by v16.9 and later if an X-Tension is loaded for use with a simultaneous search, so that the X-Tension can enter predefined search terms into the dialog window for use with the search. The X-Tension can also learn about the current search settings (the active code pages and some other settings through the flags field) and could inform the user of necessary adjustments for the search to work as intended by the X-Tension. Return 1 if you have made adjustments to the search terms, or 0 if not, or -1 if you are not happy with the current settings at all and want the X-Tension to be unselected. Adjustments to the flags or the code pages are ignored.

lpSearchTerms: Null-terminated. Delimited by line breaks. Specifies the currently entered search terms, which you can freely manipulate, replace or complete.

nBufLen: Size of the buffer that lpSearchTerms points to in Unicode characters.

nFlags:
#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_WHOLEWORDS2 0x00004000 // whole words only for search terms that are specially marked
#define XWF_SEARCH_GREP2 0x00008000 // GREP syntax only search terms that start with "grep:"

CPages: Indicates code pages currently selected for the search. See this web page for possible code page identifiers. 0 means unused code page.

If exported (optional), will be called for each search hit, either when it is found or, in a future version of X-Ways Forensics, later if selected by the user in a search hit list. Return 0, except if you want X-Ways Forensics to abort the search (return -1) or if you want X-Ways Forensics to stop calling you (return -2). This function is not called if the search was initiated by the X-Tension itself (via XWF_Search).

iSize: Size of the record. The record is packed. Currently In future versions of the API the record may be larger if more fields are provided.
nRelOfs: Relative offset of the search hit in its respective file, if any, otherwise -1.
nAbsOfs: Absolute offset of the search hit from the point of the volume, if available, otherwise -1. You may change the offset, if that helps to improve the quality of the search hit.
lpFlags: you may change the flags, for example to mark a hit as notable or to discard it
0x0001: resides in the text that was extracted from the file, nRelOfs is not an offset in the file
0x0002: notable
0x0008: deleted, set to discard the search hit
0x0040: index search hit
0x0080: in slack space etc.
lpOptionalHitPtr: Pointer to the search hit in memory. Provided only if XT_ProcessSearchHit is called during a search, not when later applied to an existing search hit, and only for search hits of the simultaneous search, not for index searches. Do not make any assumption about how many bytes before or after the search hit can be read in memory.
nSearchTermID: you may assign a search hit to a different search term by changing this ID
nLength: Size of the search hit in bytes. You may change that size, if that helps to improve the quality of the search hit.
hItemOrVolume: Part of the structure in v16.5 and later. Specifies the item (for a logical search) or volume (for a physical search) in which a search hit was found. Useful if you wish to read more data from this item. Provided only if XT_ProcessSearchHit is called during a search, only for search hits of simultaneous search. 0 for index searches, 0 when later applied to an existing search hit. 

Returns the size of a volume or physical size of file. 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 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.

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.

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

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. Set the 0x01 flag to open the item including its file slack space, if it has any.

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.

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.

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 number of characters or bytes filled into the buffer, or a negative number if an error occurred.

Retrieves the first evidence object in the case. Not currently implemented.

Retrieves the next evidence object in the chain. Not currently implemented.

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 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 or directory, otherwise NULL.

Retrieves information about the specified evidence object. The buffer size for strings is to be specified in characters (UTF-16), otherwise in bytes. Not currently implemented.

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.

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

Retrieves the number of items in the 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. 

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 when adding more items to the volume snapshot that need to have a parent.

nSpecialItem:
1 = root directory
2 = Path Unknown directory
4 = Carved Files directory
5 = System Volume Information directory

Retrieves the type of the hash values that the items in the volume snapshot of the specified evidence objects have. Not currently implemented.

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

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). Can only be used with the volume snapshot of an evidence object. 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 (not necessary if attaching an external file) or XWF_SetItemInformation (not necessary when carving a file in a file).

lpName: 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:
0x00000002: Create a file that is defined as an excerpt from its parent, where pExtraInfo points to a 64-bit start offset within that parent file.
0x00000004: Attach an external file, and pExtraInfo is an LPWSTR pointer to the path of that file.
0x00000008: Keep that external file that you designate if you still need it yourself after calling this function. 

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

Retrieves a pointer to the null-terminated name of the specified item (file or directory) in UTF-16.

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.

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. Also retrieves the number of the sector in which the data of the item starts.

Sets the above-mentioned offset and sector number.

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.

#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, -1: n/a, -2: error, -3: b/w or grayscale, -4: irrelevant
#define XWF_ITEM_INFO_FILECOUNT = 11 // how many child objects exist recursively that are files
#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

Sets information about an item (file or directory). 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

Retrieves a description of the type of the specified file 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). -1 means error. The type description parameter can be NULL if not required.

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

Returns the ID of the parent of the specified item, or -1 if the item is the root directory.

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.

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. Returns the total number of associations of that file.

Associates the specified file with the specified report table. If the report table does not exist yet, 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.

nFlags: Flags for the report table, have an effect only if the report table did not exist yet at that time
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

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.

nHowToAdd:
0: replace any existing comment
1: append to any existing comment
2: append to any existing comment and use line break as delimiter

Retrieves the extracted metadata of an item, if any. Not yet implemented.

Sets the extracted metadata of an item. Not yet implemented.

Available in v16.8 and later. Retrieves the hash value of an item, if it has any.

Adds the specified hash value to the specified item. Not yet implemented.

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.

#pragma pack(2)
struct CodePages {
   LONG iSize,
   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.

Not currently implemented.

Not currently implemented.

Creates a new search term or (if flag 0x00000001 is specified) returns the ID of an existing search term if there is one with the same name. Not currently implemented.

Retrieves information about a search term. Not currently implemented.

Creates a new search hit. Not currently implemented.

Available in v16.5 and later. Creates a new or opens an existing evidence file container. Currently only 1 container can be open at a time for filling. If a container is open already when this function is called, it will be closed automatically.

nFlags:
#define XWF_CTR_OPEN 0x00000001 // opens an existing container, all other flags ignored
#define XWF_CTR_XWFS2 0x00000002 // use new XWFS2 file system
#define XWF_CTR_SECURE 0x00000004 // mark this container as to be filled indirectly/secure
#define XWF_CTR_TOPLEVEL 0x00000008 // include evidence object names as top directory level
#define XWF_CTR_INCLDIRDATA 0x00000010 // include directory data
#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 // pass on comments
#define XWF_CTR_OPTIMIZE1 0x00001000 // optimize for > 1,000 items
#define XWF_CTR_OPTIMIZE2 0x00002000 // optimize for > 50,000 items
#define XWF_CTR_OPTIMIZE3 0x00004000 // optimize for > 250,000 items
#define XWF_CTR_OPTIMIZE4 0x00008000 // optimize for > 1 million items

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.

nFlags:
0x00000001: recreate full original path
0x00000002: include parent item data (requires flag 0x1)
0x00000004: store hash value in container

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 (the last 2 parameters, which are otherwise ignored)
5: copy metadata only

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

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
0x00000002: don't log this error message
0x00000004: lpMessage points to an ANSI string, not a Unicode string (v16.5 and later)

Creates a progress indicator window with the specified caption. You should call PeekMessage, TranslateMessage, DispatchMessage occasionally to allow for the main window to remain responsive. 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.

When a progress indicator window is on the screen and you call PeekMessage etc. regularly, you can use this function to check whether the user wants to abort the operation .

Closes the progress indicator window.

Creates a new event. Not currently implemented.