X-Ways Forensics X-Tensions API Documentation

The information below applies to X-Ways Forensics 16.4 SR-3 and later, except where noted.
Last updated on May 16, 2012.

The X-Ways Forensics X-Tensions API (application programming interface) 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
• assign files to report tables
• add comments to files
• process, validate and delete search hits
• and do practically everything else that is possible with a Windows program! (thanks to the Windows API)

You can use your programming language of choice, e.g. C++, Delphi, Visual Basic, VB.NET, Python, and do not have to learn any new scripting language. You can use your compiler of choice, for example Visual Studio Express (freeware, more information).

Since an extension 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.

When X-Tensions functions can get called:

• when refining the volume snapshot
• when running a simultaneous search
• via the directory browser context menu
• in future versions of X-Ways Forensics 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 is like a framework based on the Hollywood principle "don't call us, we call you".

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. 32-bit X-Tension DLLs should be placed in the same directory where X-Ways Forensics is run from, 64-bit DLLs in the \x64 subdirectory. The name of the DLL should be descriptive. For use in v16.4 should start with "XT" and must be less than 32 ASCII characters long. 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
Delphi function definitions and 2 sample projects
Plug-in for Python with 2 sample scripts (select the scripts by clicking the ... button in the X-Tension window)

Sample X-Tension 1: 32-bit version, 64-bit version (outputs a few messages when refining the volume snapshot, filters out search hits, just for programmers of X-Tensions, not useful in the real world)

Sample X-Tension 2: 32-bit version (creates a virtual file in the volume snapshot as a child object of another file, just for programmers of X-Tensions, not useful in the real world)

Luhn credit card check (last updated April 13, 2012): 32-bit version, 64-bit version C++ source code
Can be used during searches for credit card numbers. Verifies all search hits using the Luhn algorithm and discards false hits, to reduce search hits with irrelevant numbers.

• purpose, what it does
• tested with what version(s) of X-Ways Forensics, special requirements
• author name and optionally/ideally contact e-mail address, organization if we may publish that information

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. 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:
0x00000001 = X-Ways Forensics
0x00000002 = WinHex
0x00000004 = X-Ways Investigator
0x00000008 = beta version
0x00000010 = reserved
0x00000020 = called just to check whether the API accepts the calling application (used by v16.5 and later)
0x00000040 = called just to prepare for XT_About (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 altogether
-3 if you want to prevent further use of the X-Tension for the remainder of the whole operation
-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:
#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), 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), 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. 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.

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 the newly detected full size of the item (which may be different from the size that was known of the item before) and optionally retrieves the initialized size of the data stream of an item (valid data length, which may be available from NTFS, exFAT, and XWFS). Not currently implemented.

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.

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:
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, or directory

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_SetItemInformation, and/or XWF_SetItemOfs.

nCreationFlags:
0x00000001: for performance reasons, set if many more items are expected to be created

Adds an external file to 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 a call to XWF_SetItemParent and XWF_SetItemInformation. Not currently implemented.

nCreationFlags:
0x00000001: for performance reasons, expect many more items to create

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

#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_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. Returns the 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.

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.

Retrieves the hash value of an item, if it has any. Not yet implemented.

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.
0x00000001: logical search instead of physical search (only logical search currently available)
0x00000004: tagged objects in volume snapshot only
0x00000010: match case
0x00000020: whole words only
0x00000040: GREP syntax
0x00000080: allow overlapping hits
0x00000100: cover slack space
0x00000200: cover slack/free space transition
0x00000400: decode text in standard file types
0x00000800: decode text in specified file types // not yet supported
0x00001000: 1 hit per file needed only
0x00010000: omit files classified as irrelevant
0x00020000: omit hidden files
0x00040000: omit files that are filtered out
0x00080000: recommendable data reduction
0x00100000: omit directories
0x01000000: 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. Alternatively, 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.
0x04000000: Display search hit list when the search completes.

nSearchWindow: 0 for standard search window length
 

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:
0x00000001: opens an existing container, all other flags ignored
0x00000002: use new XWFS2 file system
0x00000004: mark this container as to be filled indirectly/secure
0x00000008: include evidence object names as top directory level
0x00000010: include directory data
0x00000020: allow files as parents of files
0x00000040: export report table associations
0x00000080: pass on comments
0x00000100: optimize for > 1,000 items
0x00000200: optimize for > 50,000 items
0x00000400: optimize for > 250,000 items
0x00000800: 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.