Copyright: (c) November 2000, Robert Galle


Introduction
Where Is It? - Description API 2.10

Programmer's Reference

Welcome to the WhereIsIt's Description Application Programming Interface (Description API, or DescAPI), a special feature available to programmers to extend WhereIsIt's capabilities with automatic description importing. For all those new to programming, API is a standardized set of functions and procedures that allow both master program and extension library to communicate. With Description API, your end result will be a DLL library implementing functions described here, therefor allowing itself to integrate in WhereIsIt application.

This document covers both DescAPI 1.0, used in WhereIsIt 2.xx, as well as newer DescAPI 2.xx, used in WhereIsIt 3.xx.

DescAPI versions

DescAPI 1.0

The original DescAPI interface, first introduced in WhereIsIt 2.00 and supporting plugins for importing description information. Plugins written using DescAPI 1.00 can be used in all WhereIsIt 2.00 and later versions.

DescAPI 2.0

A major upgrade to the original DescAPI 1.00, introducing thumbnail plugins, formatting plugins, CDDB plugins, and alias names, among others. DescAPI 2.0 is supported in WhereIsIt 3.00 and newer - DescAPI 2.0 is backward compatible with DescAPI 1.0 (old plugins work with DescAPI 2.0, too), however plugins written using DescAPI 2.0 can not be used in older WhereIsIt 2.xx releases.

DescAPI 2.10

Introduced in WhereIsIt 3.20. Adds support for file name formatting and custom icons plugins. Plugins written for DescAPI 2.10 can be used in all WhereIsIt 3.xx and newer versions, however in older WhereIsIt 3.0x and 3.1x both new plugin types will not be available.


Basic Concepts

Description plugins in WhereIsIt are in form of 32-bit Dynamic Link Libraries (DLL files). You can write and compile a DLL with most Windows programming Languages available today. All of your DLL library functions that are either exported or sent as parameters to WhereIsIt must use the __stdcall calling convention for passing their own parameters.

There are two basic concepts involved while preparing a Description API compliant DLL:

Description Module

A description module is equal to single DLL file. Each module can include one or more description plugin, and WhereIsIt can accept multiple description modules to work with at the same time. All communications defined in Description API are between WhereIsIt and description module.

Description Plugin

A description plugin is a part of module that is capable of importing descriptions from one specific description source - for example, File_id.diz files. Each description module will handle its own plugins, and take care about their registration and communicating with WhereIsIt.

During description module initialization each module will be called to present itself and register available plugins with WhereIsIt. This way, program can manage list of available description plugins, presenting them to user in order to assign import priority, or to enable or disable them. Later, when a description source is found during disk scan that can be handled by one of registered plugins, its parent module is called with request to provide description from that plugin.


Description Plugin Types
Description Plugins Types

Because of there are different ways how to get a description from different sources, Description API includes definitions about different types of plugins. While all description plugins have a goal to eventually produce a description to be used in WhereIsIt, communication with the main program will differ based on how they can get those descriptions. Each plugin group has its own ID, as defined in Description API:

ptReserved

Plugins of type ptReserved are for WhereIsIt's internal use only. Do not use ptReserved plugin type in your own description modules.

ptSameFile

This is the simplest group of plugins. Plugins of this type can extract description from the same file or folder that will be described in catalog with this description. In other words, file contains description for itself, and plugin will extract it and report it back. Examples of such files could be graphics or audio files - a plugin could return their size, color depth, play length etc. as a description. Plugin will receive the file as a parameter, for which it is expected to return a suitable description.

Import function:	ImportDesc_SameFile (DescAPI 1.0)

ImportDesc_SameFileEx (DescAPI 2.xx)

ptParentItem

This group of plugins will return a description from given source file for a parent item, usually a folder where they are located, or an archive file, if source file is compressed inside. A typical example of this group are well known FILE_ID.DIZ files. When description is needed, a plugin of this type will receive a list of all files registered for importing description for their parent item. If more than one such file is available, it is up to the plugin to decide which one to use.

Import function:	ImportDesc_ParentItem (DescAPI 1.0)

ImportDesc_ParentItemEx (DescAPI 2.xx)

ptItemList

This group can provide multiple descriptions from the same source, and is targeted to such description files that hold a list of descriptions for files and folders on media, either in same folder as description file itself, or in subfolders as well. Examples of such description files are FILES.BBS, DESCRIPT.ION, 00INDEX.TXT etc., each holding descriptions for items in the same folder. When plugin of this type is called, it will receive a list of found description files of this type, and an address of function where it will report back each file-description pair it was able to get from the source file(s).

Import function: 	ImportDesc_ItemList (DescAPI 1.0)

ImportDesc_ItemListEx (DescAPI 2.xx)

ptDiskInfo

Plugins in this group can be used to describe media itself based on its properties, like type, size, serial number, etc. A plugin of this group will receive as a parameter a record off all known details about media. An example that comes to mind would be Audio CD recognition, perhaps even by using one of public Audio CD databases on the Internet.

Import function:	ImportDesc_DiskInfo (DescAPI 1.0)

ImportDesc_DiskInfoEx (DescAPI 2.xx)

ptCDDB  (DescAPI 2.xx only)

This is a bit special type of description plugin - unlike the ones described above, ptCDDB is quite specific in its purpose and is also has some additional capabilities. Basically, the ptCDDB group of plugins are used to retrieve information about audio CDs from CDDB database on the Internet. They act the same as plugins registered as both ptSameFile and ptDiskInfo, which is exactly how the CDDB plugin used to be implemented in DescAPI 1.0. In DescAPI 2.0, however, they were made to be a separate type as CDDB queries enjoy some special support in WhereIsIt 3.xx - it is the only type of plugin that can be run at times other than scanning the media, as CDDB info can be imported on request at any time, for any number of selected disks.

Import functions:	ImportDesc_DiskInfoEx, ImportDesc_SameFileEx

ptFormatting  (DescAPI 2.xx only)

These plugins are different from all other description plugins so far, and they serve a different purpose. Their task is not to retrieve a description, but rather to format one retrieved by one of the plugin types above. There may be many formatting plugins installed, and retrived description may go through many formatting plugins before it is included in catalog. A typical purpose of formatting plugin might be limiting the size of imported description, changing its appearance, or modifying the text inside, for example, performing OEM conversion to change the code page used in the original text.

Associated function:	FormatDescriptionEx

ptFileNameFormatting  (DescAPI 2.10 only)

Plugins of this type can change the character case (uppercase/lowercase) of scanned file and folder names, as stored in catalog. Note that this applies to actual file names, not alias names. Providing file name formatting plugins allows for customizable adjusting on how file and folder names are stored and displayed in catalog - for example, a common action is to change all uppercase names to sentence case for easier reading (i.e. "TEST" to "Test"). Plugins are only allowed to modify character case without changing the name itself.

Associated function:	FormatFileNameEx

ptThumbnails  (DescAPI 2.xx only)

Thumbnails plugins have a different role compared to other description plugins, as they import images rather than textual descriptions. In basics they are similar to the ptSameFile plugins, except their result is an image handle. Plugins are only expected to retrieve the image from the image file format they are handling, and return a standard bitmap handle - any kind of processing the image such as downsampling it to a thumbnail size is not necessary since WhereIsIt will handle that. ptThumbnails plugins are also used by image viewer to display images in full size.

Import functions:	ImportThumbnailProcEx

ptCustomIcons  (DescAPI 2.10 only)

These plugins allows importing of custom icons to be used with drives and folders instead of default system icons. Custom icons are stored in catalogs, just like thumbnails, however they can be shared if multiple drives/folders use the same icon. These plugins can, for example, assign a special icon for specific drive or media type, import a custom CD-ROM icon from its Autorun file, etc.

Import functions:	ImportCustomIconProcEx


Description API 1.0 Functions

This is the list of all available functions defined in Description API version 1.0 in order to provide a way for WhereIsIt and description module to communicate. Some of these functions are required to be present and exported in description module, while some are optional. Function set has been kept as minimal as possible, in order to simplify programming of plugins. Programmer should be able to keep focus on how to get description from required source while WhereIsIt will take care of the rest.

Please note:

Description API 1.0 is defined and used in WhereIsIt 2.xx - newer WhereIsIt 3.xx uses the enhanced Description API 2.0. All new plugins should be developed complying to DescAPI 2.0 if they are to be used in WhereIsIt 3.xx and newer. Plugins complying to DescAPI 1.0 will still work in both WhereIsIt 2.xx and WhereIsIt 3.xx, however their capabilities in WhereIsIt 3.xx will be limited compared to native DescAPI 2.0 plugins.

Description Module Initialization

ModuleInfo                 	( required )

RegisterDescPlugins 	( required )

ConfigPluginProc              	( optional )

Description Importing

InitDescImport	( optional )

DoneDescImport 	( optional )

ImportDesc_SameFile	( required if plugins of type ptSameFile are registered )

ImportDesc_ParentItem	( required if plugins of type ptParentItem are registered )

ImportDesc_ItemList	( required if plugins of type ptItemList are registered )

ImportDesc_DiskInfo	( required if plugins of type ptDiskInfo are registered )

Callback functions

RegisterPlugin	( callback )

RequireFile	( callback )

StoreDescProc	( callback )

Legend:

required functions must be present and exported in your DLL in order to be used in WhereIsIt. WhereIsIt will not accept DLL missing those functions as a valid description module.

optional functions are provided for your convenience and will be called from WhereIsIt if they are exported in your DLL. You can use them if you need them with description importing.

callback functions are defined in WhereIsIt, their addresses will be passed to one of your DLL-defined functions as parameters. Those functions are provided for description modules to pass back information to WhereIsIt, or to employ some of WhereIsIt's capabilities during description importing.


Description API 1.0 Structures

The following constants and structures are defined as a part of Description API v1.0:

Structures

DISKINFORECORD

Constants

PluginType

MaxDescLength

DriveTypes


ModuleInfo
 ModuleInfo()

REQUIRED - DescAPI version: 1.0

The ModuleInfo function is the first one called by WhereIsIt when collecting data about available plugins. This function will present your Description module's name, author, and version to WhereIsIt. A function with this name must be exported from your DLL file for WhereIsIt to accept it as a description module.

  VOID ModuleInfo(

    LPTCSTR lpszModuleName,	// address of buffer to store module name

    LPTCSTR lpszAuthor,	// address of buffer to store author's name

    LPTCSTR lpszVersion	// address of buffer to store version string

  );

Parameters

lpszModuleName

Points to the buffer to receive the null-terminated string containing the module's name. String may not exceed 1024 bytes in length. Example: 'WhereIsIt Description Module'.

lpszAuthor

Points to the buffer to receive the null-terminated string containing the author's name. String may not exceed 1024 bytes in length. Example: 'Robert Galle'.

lpszVersion

Points to the buffer to receive the null-terminated string containing the version number. String may not exceed 1024 bytes in length. Example: '0.90 beta'.

Return Values

None.

Remarks

If any of strings is returned empty, WhereIsIt will not register or use this module.

See Also

ModuleInfoEx


RegisterDescPlugins
 RegisterDescPlugins()

REQUIRED - DescAPI version: 1.0, 2.xx

The RegisterDescPlugins function is called during module initialization. Description module is expected to provide WhereIsIt with information about available description plugins in this module. The RegisterDescPlugins function receives as a parameter the address of callback function to be used for registering plugins. A function with this name must be exported from your DLL file for WhereIsIt to accept it as a description module.

  VOID RegisterDescPlugins(

    PROC lpRegisterPlugin	// pointer to a callback function

  );

Parameters

lpRegisterPlugin

Points to address of WhereIsIt-defined function to call when registering a new plugin. See the RegisterPlugin function description for details.

Return Values

None.

Remarks

You may want to store the address of lpRegisterPlugin callback procedure in case you will need it later, too. You can call again this procedure to re-register plugin in WhereIsIt in case some of data has changed - for example, plugin can have a configure dialog where user can change some details about the plugin.

See also:

RegisterPlugin


PluginDefaultStateProc
 PluginDefaultStateProc()

OPTIONAL - DescAPI version: 2.xx

The PluginDefaultStateProc is an optional function that a description module may export. If a function with this name is exported in your DLL module, WhereIsIt will use it for all registered plugins in order to find out the default state of each plugin - this defines whether user is allowed to set the plugin to be enabled or disabled by default, or can plugin enforce the state itself. In any case, user is still allowed to manually enable or disable the plugin before each scan.

  BYTE PluginDefaultStateProc(

    WORD wPluginID	// ID of plugin WhereIsIt is inquiring the default state for

  );

Parameters

wPluginID

Contains the plugin ID number for which WhereIsIt is inquireing the default state.

Return Values

The function should return one of the plugin default state constant.

See also:

RegisterPlugin, plugin default state values


PluginCapabilitiesProc
 PluginCapabilitiesProc()

OPTIONAL - DescAPI version: 2.xx

The PluginCapabilitiesProc is an optional function that gives feedback to WhereIsIt regarding plugin's importing capabilities. If available, this function will be called before each disk scanning operation begins, for each of active description plugins. Function is expected to return details on what kind of data will the plugin in question try to import during the following session - descriptions, alias names, or possibly both. Knowing this allows WhereIsIt to optimize plugins usage during disk updates, resulting in much faster scanning in most cases. This function only applies to description plugins, it is not used with formatting or thumbnail plugins.

It is highly recommended for all plugin modules to implement this function, although implementation is optional to preserve compatibility with older plugin modules. If this function is not available, WhereIsIt will assume that all description plugins will try to import descriptions only, without trying to provide alias names as well.

  INT PluginCapabilitiesProc(

    WORD wPluginID	// ID of plugin WhereIsIt is inquiring capabilities for

    LPPLUGINCAPABILITIESREC PluginCapabilities

// points to the PLUGINCAPABILITIESREC structure

  );

Parameters

wPluginID

Contains the plugin ID number for which WhereIsIt is inquireing its importing capabilities.

PluginCapabilities

Points to the PLUGINCAPABILITIESREC structure, containing a set of boolean variables this function is expected to set accordingly to plugin's capabilities.

Return Values

The function should return zero in case of success, or a negative value in case of error.

See also:

PLUGINCAPABILITIESREC


ConfigPluginProc
 ConfigPluginProc()

OPTIONAL - DescAPI version: 1.0, 2.xx

The ConfigPluginProc is a function provided inside description module, and provides everything necessary for user to configure specified plugin - create and show appropriate dialog, load and store settings etc. Each plugin in description module can have assigned its own config function, or some of them (or all) can share the same one. Config function for each plugin is specified as a part of plugin registration, using the RegisterPlugin function.

  VOID ConfigPluginProc(

    HINSTANCE hInstance,	// handle to application instance

    HWND hWndParent,	// handle to parent or owner window

    WORD wPluginID	// ID of plugin to configure

  );

Parameters

hInstance

Identifies the instance of the module to be associated with the window.

hWndParent

Identifies the parent or owner window of any window, created by config function.

wPluginID

Contains plugin ID number to be used as a reference to this plugin. When WhereIsIt will call one of description importing functions provided by your plugin, and request that specific plugin is used, this ID will be used to specify the plugin. Each plugin must have an unique ID code assigned inside your module, with valid values of 0 - 65535. Recommended is sequential numbering from 0 forward.

Return Values

None.

Remarks

If your config procedure(s) need place to store their settings, you can use a special key in  the registry. This key is reserved for all plugins used in WhereIsIt - each plugin should create its own key under Settings to store the data:

HKEY_CURRENT_USER\SOFTWARE\SearchSoft\Where Is It?\Plugins\Settings

See also:

RegisterPlugin


InitDescImport
 InitDescImport()

OPTIONAL - DescAPI version: 1.0, 2.xx

The InitDescImport is optional and only called if your description module exports a function by this name. It does not have any parameters, and does not return any result - this is just a way for WhereIsIt to notify all interested description modules that disc scan operation is just about to begin, or description plugin operations will begin for a given disk. If any of your plugins need to be initialized or prepared in some other way before they can start importing data, this is the place to do it.

  VOID InitDescImport(VOID);

Parameters

None.

Return Values

None.

Remarks

If there is an operation in progress that will involve importing descriptions from more than one media (for example, a CDDB query for multiple audio CDs), InitDescImport and DoneDescImport are called before and after each disk is processed.

See also:

DoneDescImport


DoneDescImport
 DoneDescImport()

OPTIONAL - DescAPI version: 1.0, 2.0

The DoneDescImport is optional and only called if your description module exports a function by this name. WhereIsIt will call this function when disk scanning has completed, or all description plugin operations on given disk are completed. This function provides a way to clean up after plugins have done their job.

  VOID DoneDescImport(VOID);

Parameters

None.

Return Values

None.

Remarks

If there is an operation in progress that will involve importing descriptions from more than one media (for example, a CDDB query for multiple audio CDs), InitDescImport and DoneDescImport are called before and after each disk is processed.

See also:

InitDescImport


ImportDesc_SameFile
 ImportDesc_SameFile()

OPTIONALLY REQUIRED - DescAPI version: 1.0

The ImportDesc_SameFile function is the main import function for plugins of type ptSameFile. WhereIsIt will call this function during disk scan every time when a file is found that matches the file mask of one of ptSameFile plugins in your module. WhereIsIt will expect from this function to do required processing on provided file (using requested description plugin), and return appropriate description.

  BOOL ImportDesc_SameFile(

    WORD wPluginID,	// ID of description plugin to be used with provided file

    LPTCSTR lpszFileName,	// points to a null-terminated string with full path to the file

    LPTSTR lpszDesc,	// address of buffer to receive description

    PROC lpRequireFileProc	// address of RequireFile callback function

  );

Parameters

wPluginID

Contains the ID number of plugin that must be used to extract description from given file. If there are more plugins of type ptSameFile registered in your description module, then the ImportDesc_SameFile function must check the wPluginID parameter and activate the proper plugin.

lpszFileName

Points to the null-terminated string, containing a full path to the file waiting to be described. Provide this parameter to the RequireFile function before your plugin attempts to open the file.

lpszDesc

Points to the buffer (reserved by WhereIsIt) to receive null-terminated string with the description.

WARNING: Make sure that length of your description copied to this buffer does not exceed maximum allowed size for descriptions (provided in MaxDescLength global constant, currently set to 4 kB). If description is longer, it is likely to cause severe errors in program!

lpRequireFileProc

This is the address of RequireFile callback function. Before your plugin may access the file provided with lpszFileName parameter, RequireFile function must be called, and path returned by this function used to access the file.

Return Values

Function should return TRUE if description was successfully retrieved and stored lpszDesc, or FALSE, if retrieving description was not successful.

Remarks

If this function returns FALSE, or returned description is empty, WhereIsIt will try to find another plugin of the same type that can also be used to get description for current item, but has lower priority set than the plugin just called.

See also:

Plugins types, RequireFile, ImportDesc_SameFileEx


ImportDesc_ParentItem
 ImportDesc_ParentItem()

OPTIONALLY REQUIRED - DescAPI version: 1.0

The ImportDesc_ParentItem function is called by WhereIsIt when program needs to import description from one of module's ptParentItem plugins, and some of found files are matching plugin's file mask. Plugin will receive a list of matching files, and is expected to extract description to be assigned to the parent item (usually a parent folder, or an archive file, where found files are compressed in).

  BOOL ImportDesc_ParentItem(

    WORD wPluginID,	// ID of description plugin to be used with provided file

    LPTCSTR lpszParentName,	// points to null-terminated string with parent item's path

    LPTCSTR lpszFileList,	// points to a double - null-terminated list of found files

    LPTSTR lpszDesc,	// address of buffer to receive description

    PROC lpRequireFileProc	// address of RequireFile callback function

  );

Parameters

wPluginID

Contains the ID number of plugin that must be used to extract description from given file. If there are more plugins of type ptParentItem registered in your description module, then the ImportDesc_ParentItem function must check the wPluginID parameter and activate the proper plugin.

lpszParentName

Points to the address of a null-terminated string, holding a full path to the parent item (item that will receive description provided by calling this function).

lpszFileList

Points to the address of a double - null-terminated list of file names. These are files that were found in current folder matching the file mask of requested plugin (for example, if plugin has a mask of "*.TXT", this is the list of all .TXT files found in current folder). List is in form of sequential null-terminated strings, with double NULL character after the last item, i.e.:

  FILE1.TXT#0FILE2.TXT#0FILE3.TXT#0#0

where "#0" represents a NULL character. It is up to plugin to choose which file will it use to import description from. Provide the name of chosen file(s) to the RequireFile function before your plugin attempts to open the file. Files in the list are sorted in the same order as are plugin's mask, preserving priorities. For example, if plugin is set to import "*.aaa,*.bbb" files, all aaa files will be listed first, followed by all bbb files.

lpszDesc

Points to the buffer (reserved by WhereIsIt) to receive null-terminated string with the description.

WARNING: Make sure that length of your description copied to this buffer does not exceed maximum allowed size for descriptions (provided in MaxDescLength global constant, currently set to 4 kB). If description is longer, it is likely to cause severe errors in program!

lpRequireFileProc

This is the address of RequireFile callback function. Before your plugin may access the file provided with lpszFileName parameter, RequireFile function must be called, and path returned by this function used to access the file.

Return Values

Function should return TRUE if description was successfully retrieved and stored lpszDesc, or FALSE, if retrieving description was not successful.

Remarks

If this function returns FALSE, or returned description is empty, WhereIsIt will try to find another plugin of the same type that can also be used to get description for current item, but has lower priority set than the plugin just called.

See also:

Plugins types, RequireFile, ImportDesc_ParentItemEx


ImportDesc_ItemList
 ImportDesc_ItemList()

OPTIONALLY REQUIRED - DescAPI version: 1.0

The ImportDesc_ItemList function is a front-end for ptItemList - typed plugins. This function will be called by WhereIsIt when some of files are found to match the plugin's file mask, and plugin is given a chance to import descriptions from them. Since plugins of this type can retrieve multiple description from the source, a callback function is provided for a plugin to report the extracted descriptions back to WhereIsIt.

  VOID ImportDesc_ItemList(

    WORD wPluginID,	// ID of description plugin to be used with provided file

    LPTCSTR lpszParentName,	// points to null-terminated string with parent item's path

    LPTCSTR lpszFileList,	// points to a double - null-terminated list of found files

    PROC lpRequireFileProc,	// address of RequireFile callback function

    PROC lpStoreDescProc	// address of StoreDescProc callback function

  );

Parameters

wPluginID

Contains the ID number of plugin that must be used to extract descriptions. If there are more plugins of type ptItemList registered in your description module, then the ImportDesc_ItemList function must check the wPluginID parameter and activate the proper plugin.

lpszParentName

Points to the address of a null-terminated string, holding the full path to parent item (parent folder or compressed archive file holding the found files).

lpszFileList

Points to the address of a double - null-terminated list of file names. These are files that were found in current folder matching the file mask of requested plugin (for example, if plugin has a mask of "*.TXT", this is the list of all .TXT files found in current folder). List is in form of sequential null-terminated strings, with double NULL character after the last item, i.e.:

  FILE1.TXT#0FILE2.TXT#0FILE3.TXT#0#0

where "#0" represents a NULL character. It is up to plugin to choose which file will it use to import description from. Provide the name of chosen file(s) to the RequireFile function before your plugin attempts to open the file.

lpRequireFileProc

This is the address of RequireFile callback function. Before your plugin may access the file provided with lpszFileName parameter, RequireFile function must be called, and path returned by this function used to access the file.

lpStoreDescProc

Holds the address of StoreDescProc callback function, used to report descriptions back to WhereIsIt. See the description of StoreDescProc for more details.

Return Values

None.

See also:

Plugins types, RequireFile, StoreDescProc, ImportDesc_ItemListEx


ImportDesc_DiskInfo
 ImportDesc_DiskInfo()

OPTIONALLY REQUIRED - DescAPI version: 1.0

The ImportDesc_DiskInfo function is called for plugins of ptDiskInfo type. Function receives as a parameter an address to DISKINFORECORD structure, containing many details about media, such as media type, size, volume label, serial number etc. The plugin may want to access some other source to retreive more detailed data about the media, such as network server, or even Internet based database.

  BOOL ImportDesc_DiskInfo(

    WORD wPluginID,	// ID of description plugin to be used for importing

    LPDISKINFOREC lpDiskInfo,	// points to the DISKINFORECORD structure

    LPTSTR lpszDesc	// address of buffer to receive description

  );

Parameters

wPluginID

Contains the ID number of plugin that must be used to retrieve description for given disk. If there are more plugins of type ptDiskInfo registered in your description module, then the ImportDesc_DiskInfo function must check the wPluginID parameter and activate the proper plugin.

lpDiskInfo

Points to the DISKINFORECORD structure, containing details about media that is being scanned.

lpszDesc

Points to the buffer (reserved by WhereIsIt) to receive null-terminated string with the description.

WARNING: Make sure that length of your description copied to this buffer does not exceed maximum allowed size for descriptions (provided in MaxDescLength global constant, currently set to 4 kB). If description is longer, it is likely to cause severe errors in program!

Return Values

Function should return TRUE if description was successfully retrieved and stored lpszDesc, or FALSE, if retrieving description was not successful.

Remarks

If this function returns FALSE, or returned description is empty, WhereIsIt will try to find another plugin of the same type that can also be used to get description for current item, but has lower priority set than the plugin just called.

See also:

Plugin types, DISKINFORECORD, ImportDesc_DiskInfoEx


RegisterPlugin
 RegisterPlugin()

CALLBACK - DescAPI version: 1.0, 2.xx

The RegisterPlugin function is provided by WhereIsIt, and is received as a parameter with the RegisterDescPlugins function. Your module will call RegisterPlugin from the RegisterDescPlugins function, once for each description plugin available in your module. Parameters to this function will provide everything WhereIsIt needs to know about the specified plugin.

  INT RegisterPlugin(

    WORD wPluginID,	// unique plugin's ID inside your description module

    BYTE byPluginType,	// specifies plugin type

    LPTCSTR lpszPluginName,	// specifies the name of the plugin, as visible to users

    LPTCSTR lpszPluginMask,	// address of buffer to store plugin's target file masks

    PROC lpConfigProc	// address of function used to configure plugin

  );

Parameters

wPluginID

Contains plugin's ID number to be used as a reference to this plugin. When WhereIsIt will call one of description-importing functions provided by your plugin, and request that specific plugin is used, this ID will be used to specify the plugin. Each plugin must have an unique ID code assigned inside your module, with valid values of 0 - 65535. Recommended is sequential numbering from 0 forward.

byPluginType

Specifies the type of plugin.

byPluginName

Specifies the name of the plugin, as users will see it in WhereIsIt.

lpszPluginMask

Points to the null-terminated string containing the list of file or file masks. This is the list of files that your plugin can extract description(s) from. For example, a plugin that can extract information from WAV files and use it to describe those file will provide "*.WAV" as a plugin mask. If during disk scan one or more files complying with specified mask are encountered, your plugin will be called to extract description from them. Files or file masks in string should be provided in UPPER-CASE and separated with commas. Example: "README.TXT, *.NFO". This parameter is required for all plugin types except ptDiskInfo, where you can set it as NULL.

lpConfigProc

Points to the function that can be used to setup your plugin. This function will be called if user will select your plugin in WhereIsIt, and click the Configure button. If your plugin does not provide users with ability to configure the plugin, you can specify NULL here as a parameter.

Return Values

If returned value is equal or greater to zero, plugin was successfully registered with WhereIsIt and return value is plugin's assigned serial number on WhereIsIt's plugin list. This value is informative only and will not be referenced later, you may safely discard it.

Negative return value is an error code, by the following table:

-1	Invalid plugin type

-2	Plugin with this ID already exists in your module

-3	The name of plugin is invalid

-4	File mask provided for plugin is invalid

-5	Module does not export required description function for this plugin type

Note that error code -2 only applies if trying to register a plugin of different type than the one already registered with the same ID. If both plugins have the same ID and are of the same type, WhereIsIt will adjust settings for existing plugin instead of registering a new one.

See also:

RegisterDescPlugins, PluginDefaultStateProc, plugin types


DriveTypes
 Drive Type Constants

This is the list of currently supported drive and media types in WhereIsIt:

#define DT_UNKNOWN           255   // unknown drive

#define DT_FLOPPY525_360     0     // floppy 5.25" 360 kB

#define DT_FLOPPY525_12      1     // floppy 5.25" 1.2 MB

#define DT_FLOPPY35_720      2     // floppy 3.5" 720 kB

#define DT_FLOPPY525_8SD     3     // floppy 8" Single Density

#define DT_FLOPPY525_8DD     4     // floppy 8" Double Density

#define DT_HARDDISK          5     // hard disk

#define DT_TAPEDRIVE         6     // tape drive

#define DT_FLOPPY35_144      7     // floppy 3.5" 1.44 MB

#define DT_OPTICAL           8     // optical drive

#define DT_FLOPPY35_288      9     // floppy 3.5" 2.88 MB

#define DT_CDROM             10    // CD-ROM

#define DT_NETWORK           11    // Network drive

#define DT_RAMDISK           12    // RAM disk

#define DT_REMOVABLE         13    // generic removable drive

#define DT_ZIPDRIVE          14    // iomega ZIP 100

#define DT_JAZDRIVE          15    // iomega JAZ 1GB

#define DT_ZIPDRIVEPLUS      16    // iomega ZIP 100 Plus

#define DT_SEAGATEDIRECTTAPE 17    // Seagate Direct Tape virtual drive

#define DT_LS120             18    // LS-120 floppy drive

#define DT_MOS320            19    // Deltis MOS320 removable drive

#define DT_MOS332            20    // Olympus MOS332 removable drive

#define DT_M2531A            21    // Fujitsu M2531A removable drive

#define DT_JAZ2DRIVE         22    // iomega JAZ 2GB

#define DT_Zip250            23    // iomega ZIP 250

// --- DescAPI 2.0 only ---

#define DT_AUDIOCD           24    // audio CD

See also:

DISKINFORECORD, ImportDesc_DiskInfo,

IMPORTDISKINFOREC, ImportDesc_DiskInfoEx


RequireFile
 RequireFile()

CALLBACK - DescAPI version: 1.0, 2.xx

The RequireFile function is provided by WhereIsIt, and is used by plugins whenever they need to access a specific file. The address of this function to call is provided as a parameter to each of description importing functions - ImportDesc_xxx. Function will return a new string, containing a full path to the requested file that plugin can now actually open and use.

The main purpose of this function is to unpack description files, if they are compressed inside archives. If such compressed file is requested by plugin via RequireFile function, WhereIsIt will first unpack it to temporary folder, and return the full path to the uncompressed file. Temporary files will be removed as soon as the plugin is finished with importing current description and returns control back to WhereIsIt.

  LPTSTR RequireFile(

    LPTCSTR lpszFileName	// path to file to access

  );

Parameters

lpszPluginMask

Points to the null-terminated string containing a path to file that plugin would like to use. Path to file should be the same one as provided by WhereIsIt to the ImportDesc_xxx function.

Return Values

Returns a pointer to null-terminated string, containing full path to the requested file that plugin can use. This path is not necessary the same as the one provided as parameter to this function.

Remarks

Make sure that you use this function to request access to any file used by the plugin during description importing.

See also:

ImportDesc_SameFile, ImportDesc_ParentItem, ImportDesc_ItemList

ImportDesc_SameFileEx, ImportDesc_ParentItemEx, ImportDesc_ItemListEx, ImportThumbnail


StoreDescProc
 StoreDescProc()

CALLBACK - DescAPI version: 1.0, 2.xx

The StoreDescProc function is provided by WhereIsIt, and its address is sent as a parameter to ImportDesc_ItemList and ImportDesc_ItemListEx functions. Those functions are used to import description using ptItemList plugins, meaning it will possibly return multiple descriptions from single description source. The purpose of StoreDescProc function is to provide a way for ImportDesc_ItemList function to send each retrieved "file name"-"description" pair back to WhereIsIt, where the description will be stored in the catalog by the specified file.

  BOOL StoreDescProc(

    LPTCSTR lpszFileName,	// points to retrieved file name

    LPTCSTR lpszDesc	// points to retrieved description string

  );

Parameters

lpszFileName

Points to the null-terminated string containing name and optional path to file or folder. WhereIsIt will try to find this item among catalogued data, and attach to it the description provided as the next parameter. See Remarks below for additional details.

lpszDesc

Points to the null-terminated string containing a description retrieved by plugin that belongs to the lpszFileName parameter.

WARNING: Length of provided description should not exceed the maximum allowed description size, limited by MaxDescLength global constant (currently set to 4 kB). If description is longer, it will be truncated.

Return Values

Returns TRUE if description was successfully stored in catalog, or FALSE, if provided file name was not found in the catalog.

Remarks

File or folder name can be provided in any of these three forms: name only, name with relative path from current folder, or file name with full path to item on the disk.

• If target item is located in the same folder as description file is, you should provide the lpszFileName parameter as plain file name only, for example "TEST.EXE". This is also the most optimal choice from performance point of view since program is optimized to quickly find items in current folder. Most of description file formats like INDEX.TXT or FILES.BBS include list of files for current folder only, so you should be able to use this mode as much as possible.

• If target is located in one of subfolders, relative to folder with the description file, you can use addressing with relative path, for example "FOLDER1\FOLDER2\...\TEXT.EXE". WhereIsIt will start in the current folder and look in catalog for subfolder named Folder1. If provided subfolder exist in catalog, WhereIsIt will look for file, too, and append description if file is found.

• If you would like to provide descriptions for items anywhere on the disk, you will have to provide full path to the target file, including the drive letter, for example "F:\CURRENT\FOLDER1\FOLDER2\TEST.EXE".

WARNING: This mode is only allowed when user is importing descriptions on demand, in already catalogued data, and will always fail when you try to use it during the disk scan.

Note: The last two modes can be considerably slower compared to the first one, especially if there are many subfolders in the disk you are scanning. If there are many items to import, end user may be experiencing considerable delays while your plugin is active.

See also:

ImportDesc_ItemList, ImportDesc_ItemListEx


StoreAliasProc
 StoreAliasProc()

CALLBACK - DescAPI version: 2.xx

The StoreAliasProc function is provided by WhereIsIt, and its address is sent as a parameter to the ImportDesc_ItemListEx function. The latter is used to import description using ptItemList plugins, meaning it will possibly return multiple alias names from single description source. The purpose of StoreAliasProc function is to provide a way for ImportDesc_ItemListEx function to send each retrieved "file name"-"alias" pair back to WhereIsIt, where the alias name will be stored in the catalog by the specified file.

  BOOL StoreAliasProc(

    LPTCSTR lpszFileName,	// points to retrieved file name

    LPTCSTR lpszAliasName	// points to retrieved alias name

  );

Parameters

lpszFileName

Points to the null-terminated string containing name and optional path to file or folder. WhereIsIt will try to find this item among catalogued data, and attach to it the description provided as the next parameter. See Remarks below for additional details.

lpszAliasName

Points to the null-terminated string containing an alias name retrieved by plugin that belongs to the lpszFileName parameter. Alias names may not contain line breaks.

WARNING: Length of provided alias name should not exceed the maximum allowed description size, limited by MaxAliasLength global constant. If alias name is longer, it will be truncated.

Return Values

Returns TRUE if alias name was successfully stored in catalog, or FALSE, if provided file name was not found in the catalog.

Remarks

File or folder name can be provided in any of these three forms: name only, name with relative path from current folder, or file name with full path to item on the disk.

• If target item is located in the same folder as description file is, you should provide the lpszFileName parameter as plain file name only, for example "TEST.EXE". This is also the most optimal choice from performance point of view since program is optimized to quickly find items in current folder. Most of description file formats like INDEX.TXT or FILES.BBS include list of files for current folder only, so you should be able to use this mode as much as possible.

• If target is located in one of subfolders, relative to folder with the description file, you can use addressing with relative path, for example "FOLDER1\FOLDER2\...\TEXT.EXE". WhereIsIt will start in the current folder and look in catalog for subfolder named Folder1. If provided subfolder exist in catalog, WhereIsIt will look for file, too, and append description if file is found.

• If you would like to provide descriptions for items anywhere on the disk, you will have to provide full path to the target file, including the drive letter, for example "F:\CURRENT\FOLDER1\FOLDER2\TEST.EXE".

WARNING: This mode is only allowed when user is importing descriptions on demand, in already catalogued data, and will always fail when you try to use it during the disk scan.

Note: The last two modes can be considerably slower compared to the first one, especially if there are many subfolders in the disk you are scanning. If there are many items to import, end user may be experiencing considerable delays while your plugin is active.

See also:

ImportDesc_ItemListEx


 MaxDescLength

The MaxDescLength constant defines the maximum allowed description length for items in WhereIsIt's catalogs. This constant contains a different value in DescAPI 1.0 and DescAPI 2.0:

Description API 1.0:

#define MAXDESCLENGTH  4096     // maximum allowed description length in bytes (4 KB)

Description API 2.xx:

#define MAXDESCLENGTH  32768    // maximum allowed description length in bytes (32 KB)

WARNING: Description plugins may not exceed description length when being copied to the result buffer, or they can cause severe errors in the program.

See also:

DescAPI version: 1.0

ImportDesc_SameFile, ImportDesc_ParentItem, ImportDesc_ItemList, ImportDesc_DiskInfo, StoreDescProc

DescAPI version: 2.xx

ImportDesc_SameFileEx, ImportDesc_ParentItemEx, ImportDesc_ItemListEx, ImportDesc_DiskInfoEx, FormatDescription, StoreDescProc


 MaxAliasLength

The MaxAliasLength constant defines the maximum allowed alias name length for items in WhereIsIt's catalogs. This constant is only defined in Description API 2.0.

Description API 2.0:

#define MAXALIASLENGTH  255    // maximum allowed alias name length in bytes

WARNING: Alias names may not exceed the above length when being copied to the result buffer, or they can cause severe errors in the program.

See also:

ImportDesc_SameFileEx, ImportDesc_ParentItemEx, ImportDesc_ItemListEx,  FormatDescription, StoreAliasProc


 DISKINFORECORD

DescAPI version: 1.0, 2.xx

The DISKINFORECORD structure is used with ImportDesc_DiskInfo and ImportDesc_DiskInfoEx functions.

typedef struct {

  LPCSTR	lpszRootPath;

  LPCSTR	lpszVirtualRoot;

  LPCSTR	lpszVolumeLabel;

  LPCSTR	lpszFSName;

  INT	iMaxNameLength;

  DWORD	dwSerialNumber;

  WORD	wDiskNum;

  WORD	wMediaType;

  INT	iBytesPerSector;

  INT	iSectorsPerCluster;

  INT	iTotalClusters;

  INT	iFreeClusters;

  INT	iNumberOfFiles;

  INT	iNumberOfCompressedFiles;

  WORD	wNumberOfDirs;

} DISKINFORECORD, FAR *LPDISKINFOREC;

Members

lpszRootPath

Points to a null-terminated string containing drive root path. This could be in either regular form (<drive>:\), or in UNC format (\\<servername>\<sharename>)

lpszVirtualRoot

Points to a null-terminated string containing drive's virtual root. Virtual root is a special feature in WhereIsIt's catalog where only a part of folder tree is catalogued, with one of the folders posing as a virtual root folder. This field will be NULL if drive does not have a virtual root, or will be in form of "\<virtual-root-path>\" (i.e. "\Virtual\Root\").

lpszVolumeLabel

Points to a null-terminated string containing drive volume label.

lpszFSName

Points to a null-terminated string containing file system name (for example: "FAT", "FAT32", "NTFS", "CDFS",...)

iMaxNameLength

Specifies the maximum length of file names allowed on this drive.

dwSerialNumber

Specifies disk's serial number.

wDiskNum

Specified user assigned disk number in the catalog.

wMediaType

Specifies media or disk type. See the Drive Types description for list of values.

iBytesPerSector

Specifies the number of bytes per sector.

iSectorsPerCluster

Specifies the number of sectors per cluster.

iTotalClusters

Specifies the number of all clusters on the media.

iFreeClusters

Specifies the number of free clusters on the media.

iNumberOfFiles

Specifies the number of files on the media, as found by the program during disk scan. If WhereIsIt was instructed to skip some files, this number may be lower than the actual number of files on disk. The content of compressed archive files is not included in this count.

iNumberOfCompressedFiles

Specifies the number of compressed files successfully retrieved from archive files during disk scan.

wNumberOfDirs

Specifies the number of folders on the media, as found by the program during disk scan. If WhereIsIt was instructed to skip some folders, this number may be lower than the actual number of folders on disk.

See also:

ImportDesc_DiskInfo, ImportDesc_DiskInfoEx, IMPORTDISKINFOREC


Description API 2.0 Functions
Description API 2.10 Functions

This is the list of all available functions defined in Description API version 2.10 in order to provide a way for WhereIsIt and description module to communicate. Some of these functions are required to be present and exported in description module, while some are optional. Function set has been kept as minimal as possible, in order to simplify programming of plugins. Programmer should be able to keep focus on how to get description from required source while WhereIsIt will take care of the rest.

Compared to the older Description API 1.0, DescAPI 2.0 adds additional functionality, such as ability to set disk names and new alias names, changes the way parameters are passed between WhereIsIt and plugins, includes additional support for error reporting, and more. Some of the functions from DescAPI 1.0 were replaced with advanced versions of those same functions, using the same function names with the Ex suffix. With DescAPI 2.xx, functions with the Ex suffix must be used.

DescAPI 2.10 was introduced later in WhereIsIt 3.20 as an extension to DescAPI 2.0, adding support for file name formatting plugins, and custom icons plugins.

Description Module Initialization

ModuleInfoEx             	( required )

RegisterDescPlugins	( required )

PluginDefaultStateProc	( optional )

PluginCapabilitiesProc	( optional )

ConfigPluginProc	( optional )

Description Importing

InitDescImport	( optional )

DoneDescImport 	( optional )

ImportDesc_SameFileEx	( required if plugins of type ptSameFile or ptCDDB are registered )

ImportDesc_ParentItemEx	( required if plugins of type ptParentItem are registered )

ImportDesc_ItemListEx	( required if plugins of type ptItemList are registered )

ImportDesc_DiskInfoEx	( required if plugins of type ptDiskInfo or ptCDDB are registered )

Description Formatting

FormatDescriptionEx	( required if plugins of type ptFormatting are registered )

FormatFileNameEx	( required if plugins of type ptFileNameFormatting are registered )

Thumbnails

ImportThumbnailProcEx	( required if plugins of type ptThumbnails are registered )

ImportCustomIconProcEx	( required if plugins of type ptCustomIcons are registered )

Callback functions

RegisterPlugin	( callback )

RequireFile	( callback )

StoreDescProc	( callback )

StoreAliasProc	( callback )

Legend:

required functions must be present and exported in your DLL in order to be used in WhereIsIt. WhereIsIt will not accept DLL missing those functions as a valid description module.

optional functions are provided for your convenience and will be called from WhereIsIt if they are exported in your DLL. You can use them if you need them with description importing.

callback functions are defined in WhereIsIt, their addresses will be passed to one of your DLL-defined functions as parameters. Those functions are provided for description modules to pass back information to WhereIsIt, or to employ some of WhereIsIt's capabilities during description importing.


Description API 2.0 Structures
Description API 2.10 Structures

The following constants and structures are defined as a part of Description API v2.0:

Structures

MODULEINFOREC

DISKINFORECORD

IMPORTSAMEFILEREC

IMPORTPARENTITEMREC

IMPORTITEMLISTREC

IMPORTDISKINFOREC

FORMATDESCREC

FORMATFILENAMEREC

IMPORTTHUMBNAILREC

IMPORTCUSTOMICONREC

Constants

PluginType

MaxDescLength

MaxAliasLength

DriveTypes


ModuleInfoEx
 ModuleInfoEx()

REQUIRED - DescAPI version: 2.xx

The ModuleInfoEx function is the first one called by WhereIsIt when collecting data about available plugins. This function will present your Description module's name, author, and version to WhereIsIt. A function with this name must be exported from your DLL file for WhereIsIt to accept it as a description module.

  VOID ModuleInfoEx(

    LPMODULEINFOREC lpModuleInfo	// points to the MODULEINFOREC structure that receives plugin details

  );

Parameters

lpModuleInfo

Pointer to a MODULEINFOREC structure that receives the information about the plugin.

Return Values

None.

Remarks

If any of the strings in the MODULEINFOREC is returned empty, WhereIsIt will not register or use this module.

See Also

MODULEINFOREC, ModuleInfo


ImportDesc_SameFileEx
 ImportDesc_SameFileEx()

OPTIONALLY REQUIRED - DescAPI version: 2.xx

The ImportDesc_SameFileEx function is the main import function for plugins of type ptSameFile. WhereIsIt will call this function during disk scan every time when a file is found that matches the file mask of one of ptSameFile plugins in your module. WhereIsIt will expect from this function to do required processing on provided file (using requested description plugin), and return appropriate description and/or file alias name, if one could be extracted. Description and alias name are attached to that same file in catalog.

The ImportDesc_SameFileEx function is also used with all ptCDDB plugins, as the second stage. It is expected to return description for the provided track file (usually named like Cdtrack01.cda), after the CDDB information has already been retrieved by the ImportDesc_DiskInfoEx function.

  INT ImportDesc_SameFileEx(

    WORD wPluginID,	// ID of description plugin to be used with provided file

    LPIMPORTSAMEFILEREC lpImportSameFileInfo

// points to the IMPORTSAMEFILEREC structure

  );

Parameters

wPluginID

Contains the ID number of plugin that must be used to extract description from given file. If there are more plugins of type ptSameFile registered in your description module, then the ImportDesc_SameFileEx function must check the wPluginID parameter and activate the proper plugin.

lpImportSameFileInfo

Points to the IMPORTSAMEFILEREC structure, containing a set of parameters to be used with this function.

Return Values

Function should return 0 if it has completed sucessfully, or a negative value (error code) if retrieving description or alias name was not successful.

Remarks

If this function returns an error code, or returned description or alias name is empty, WhereIsIt will try to find another plugin of the same type that can also be used to get description or alias name for current item, but has lower priority set than the plugin just called.

See also:

Plugins types,  IMPORTSAMEFILEREC, RequireFile, ImportDesc_SameFile


ImportDesc_ParentItemEx
 ImportDesc_ParentItemEx()

OPTIONALLY REQUIRED - DescAPI version: 2.xx

The ImportDesc_ParentItemEx function is called by WhereIsIt when program needs to import description from one of module's ptParentItem plugins, and some of found files are matching plugin's file mask. Plugin will receive a list of matching files, and is expected to extract description to be assigned to the parent item (usually a parent folder, or an archive file, where found files are compressed in).

  INT ImportDesc_ParentItemEx(

    WORD wPluginID,	// ID of description plugin to be used with provided file

    LPIMPORTPARENTITEMREC lpImportParentItemInfo

// points to the IMPORTPARENTITEMREC structure

  );

Parameters

wPluginID

Contains the ID number of plugin that must be used to extract description from given file. If there are more plugins of type ptParentItem registered in your description module, then the ImportDesc_ParentItemEx function must check the wPluginID parameter and activate the proper plugin.

lpImportParentItemInfo

Points to the IMPORTPARENTITEMREC structure, containing a set of parameters to be used with this function.

Return Values

Function should return 0 if it has completed sucessfully, or a negative value (error code) if retrieving description or alias name was not successful.

Remarks

If this function returns an error code, or returned description or alias name is empty, WhereIsIt will try to find another plugin of the same type that can also be used to get description or alias name for current item, but has lower priority set than the plugin just called.

See also:

Plugins types,  IMPORTPARENTITEMREC, RequireFile, ImportDesc_ParentItem


ImportDesc_ItemListEx
 ImportDesc_ItemListEx()

OPTIONALLY REQUIRED - DescAPI version: 2.xx

The ImportDesc_ItemList function is a front-end for ptItemList - typed plugins. This function will be called by WhereIsIt when some of files are found to match the plugin's file mask, and plugin is given a chance to import descriptions from them. Since plugins of this type can retrieve multiple description from the source, a callback function is provided for a plugin to report the extracted descriptions back to WhereIsIt.

  INT ImportDesc_ItemListEx(

    WORD wPluginID,	// ID of description plugin to be used with provided file

    LPIMPORTITEMLISTREC lpImportItemListInfo

// points to the IMPORTITEMLISTREC structure

  );

Parameters

wPluginID

Contains the ID number of plugin that must be used to extract descriptions. If there are more plugins of type ptItemList registered in your description module, then the ImportDesc_ItemListEx function must check the wPluginID parameter and activate the proper plugin.

lpImportItemListInfo

Points to the IMPORTITEMLISTREC structure, containing a set of parameters to be used with this function, such as file name,

Return Values

Function should return 0 if it has completed sucessfully, or a negative value (error code) if an error has occured.

See also:

Plugins types,  IMPORTITEMLISTREC, RequireFile, ImportDesc_ItemList


ImportDesc_DiskInfoEx
 ImportDesc_DiskInfoEx()

OPTIONALLY REQUIRED - DescAPI version: 2.xx

The ImportDesc_DiskInfoEx function is called for plugins of ptDiskInfo type. Function receives as a parameter an address to DISKINFORECORD structure, containing many details about media, such as media type, size, volume label, serial number etc. The plugin may want to access some other source to retreive more detailed data about the media, such as network server, or even Internet-based database.

The ImportDesc_DiskInfoEx function is also used with all ptCDDB plugins, as the first stage. Among parameters provided to this function there is also the CDDB query info, as retrieved during media scan and stored in catalog. If the plugin is a ptCDDB type, the ImportDesc_DiskInfoEx function should be used to connect to the CDDB server and retrieve the CD details. Description that applies to the media itself is returned through this function, while track information should be stored for subsequent ImportDesc_SameFileEx calls.

  INT ImportDesc_DiskInfoEx(

    WORD wPluginID,	// ID of description plugin to be used with provided file

    LPIMPORTDISKINFOREC lpImportDiskInfoRec

// points to the IMPORTDISKINFOREC structure

  );

Parameters

wPluginID

Contains the ID number of plugin that must be used to retrieve description for given disk. If there are more plugins of type ptDiskInfo registered in your description module, then the ImportDesc_DiskInfoEx function must check the wPluginID parameter and activate the proper plugin.

lpImportItemListInfo

Points to the IMPORTDISKINFOREC structure, containing a set of parameters to be used with this function.

Return Values

Function should return 0 if it has completed sucessfully, or a negative value (error code) if retrieving description or disk name was not successful.

See also:

Plugins types,  IMPORTDISKINFOREC, RequireFile, ImportDesc_DiskInfo


FormatDescription
 FormatDescriptionEx()

OPTIONALLY REQUIRED - DescAPI version: 2.xx

The FormatDescription function is called for plugins of ptFormatting type. Formatting plugins have a different role as they don't extract any descriptions on their own, but rather format extracted descriptions by other plugins. Typical task for formatting plugins are code page conversions, limiting the amount of text, etc.

  INT FormatDescription(

    WORD wPluginID,	// ID of formatting plugin to be used

    LPFORMATDESCREC lpFormatDescInfo

// points to the FORMATDESCREC structure

  );

Parameters

wPluginID

Contains the ID number of plugin that must be used to format given description. If there are more plugins of type ptFormatting registered in your plugins module, then the FormatDescription function must check the wPluginID parameter and activate the proper plugin.

lpFormatDescInfo

Points to the FORMATDESCREC structure, containing a set of parameters to be used with this function.

Return Values

Function should return 0 if it has completed sucessfully, or a negative value (error code) if retrieving description or disk name was not successful.

See also:

Plugins types, FORMATDESCREC


FormatFileName
 FormatFileNameEx()

OPTIONALLY REQUIRED - DescAPI version: 2.10

The FormatFileName function is called for plugins of ptFileNameFormatting type. File name formatting plugins are used to modify a visual appearance of file and folder names being cataloged, namely allowing to adjust their character case. The ptFileNameFormatting plugins are given a chance to adjust file names before they are cataloged, and can do that according to user's settings, through plugin's configuration dialog. Note that plugins can only adjust the character case of file or folder names, but they must not change them in any other way - you can not use these plugins to store files and folders in catalog under different names as they appear on the media. WhereIsIt will refuse adjustments to file names if they differ in any other detail than in character case used.

  INT FormatFileName(

    WORD wPluginID,	// ID of formatting plugin to be used

    LPFORMATFILENAMEREC lpFormatFileNameInfo

// points to the FORMATFILENAMEREC structure

  );

Parameters

wPluginID

Contains the ID number of plugin that must be used to format given description. If there are more plugins of type ptFileNameFormatting registered in your plugins module, then the FormatFileName function must check the wPluginID parameter and activate the proper plugin.

lpFormatFileNameInfo

Points to the FORMATFILENAMEREC structure, containing a set of parameters to be used with this function.

Return Values

Function should return 0 if it has completed sucessfully, or a negative value (error code) if retrieving description or disk name was not successful.

See also:

Plugins types, FORMATFILENAMEREC


ImportThumbnail
 ImportThumbnailProcEx()

OPTIONALLY REQUIRED - DescAPI version: 2.xx

The ImportThumbnail function is called for plugins of ptThumbnails type, which have the task of importing standard bitmap images from supported image files. Those images are used by WhereIsIt either to generate downsampled thumbnails to be stored in the catalog, or they may be displayed in the internal image viewer in their full size. Importing images is not necessarily limited to image files only, like BMP, GIF, JPG etc. - plugins may in fact return image representations of any kind of documents that may either have thumbnails stored in their own file format, or image representation can be generated from its contents. For example, the latest Explorer versions can generate thumbnail images of HTML files on the fly - your plugin may want to do the same.

  INT ImportThumbnailProcEx(

    WORD wPluginID,	// ID of formatting plugin to be used

    LPIMPORTTHUMBNAILREC lpImportThumbnailInfo

// points to the IMPORTTHUMBNAILREC structure

  );

Parameters

wPluginID

Contains the ID number of plugin that must be used to retrieve the image. If there are more plugins of type ptThumbnails registered in your plugins module, then the ImportThumbnailProcEx function must check the wPluginID parameter and activate the proper plugin.

lpImportThumbnailInfo

Points to the IMPORTTHUMBNAILREC structure, containing a set of parameters to be used with this function.

Return Values

Function should return 0 if it has completed sucessfully, or a negative value (error code) if retrieving image was not successful.

See also:

Plugins types, IMPORTTHUMBNAILREC


ImportCustomIcon
 ImportCustomIconProcEx()

OPTIONALLY REQUIRED - DescAPI version: 2.10

The ImportCustomIcon function is called for plugins of ptCustomIcons type, which can import custom icons to be used for disks or folders in catalog instead of the default system icons. Like thumbnails, custom icons are stored in catalogs. These plugins could be used to provide customized icons for drive or media of specific type, assign special icons to folders found to be holding certain kind of data, etc.

  INT ImportCustomIconProcEx(

    WORD wPluginID,	// ID of formatting plugin to be used

    LPIMPORTCUSTOMICONREC lpImportCustomIconInfo

// points to the IMPORTCUSTOMICONREC structure

  );

Parameters

wPluginID

Contains the ID number of plugin that must be used to retrieve the image. If there are more plugins of type ptCustomIcons registered in your plugins module, then the ImportCustomIconProcEx function must check the wPluginID parameter and activate the proper plugin.

lpImportCistomIconInfo

Points to the IMPORTCUSTOMICONREC structure, containing a set of parameters to be used with this function.

Return Values

Function should return 0 if it has completed sucessfully, or a negative value (error code) if retrieving image was not successful.

See also:

Plugins types, IMPORTCUSTOMICONREC


 MODULEINFOREC

DescAPI version: 2.xx

The MODULEINFOREC structure is used with the ModuleInfoEx function.

typedef struct {

    LPTCSTR   lpszModuleName;

  LPTCSTR   lpszAuthor;

  LPTCSTR   lpszVersion;

} MODULEINFOREC, FAR *LPMODULEINFOREC;

Members

lpszModuleName

Points to the buffer to receive the null-terminated string containing the module's name. String may not exceed 1024 bytes in length. Example: 'WhereIsIt Description Module'.

lpszAuthor

Points to the buffer to receive the null-terminated string containing the author's name. String may not exceed 1024 bytes in length. Example: 'Robert Galle'.

lpszVersion

Points to the buffer to receive the null-terminated string containing the version number. String may not exceed 1024 bytes in length. Example: '0.90 beta'.

See also:

ModuleInfoEx


 IMPORTSAMEFILEREC

DescAPI version: 2.xx

The IMPORTSAMEFILEREC structure is used as a parameter with the ImportDesc_SameFileEx function.

typedef struct {

    LPTCSTR   lpszFileName;

  LPTCSTR   lpszDesc;

  LPTCSTR   lpszAliasName;

  PROC      lpRequireFileProc;

  WORD      wMaxDescSize;

  BOOL      bSilentMode;

  HANDLE    hOwnerWnd;

} IMPORTSAMEFILEREC, FAR *LPIMPORTSAMEFILEREC;

Members

lpszFileName

Points to the null-terminated string, containing a full path to the file waiting to be described. Provide this parameter to the RequireFile function before your plugin attempts to open the file.

lpszDesc

Points to the buffer (reserved by WhereIsIt) to receive null-terminated string with the description.

WARNING: Make sure that length of your description copied to this buffer does not exceed maximum allowed size for descriptions (provided in MaxDescLength global constant). If description is set longer, it is likely to cause severe errors in program!

lpszAliasName

Points to the buffer (reserved by WhereIsIt) to receive null-terminated string with item's alias name. Alias names may not contain line breaks.

WARNING: Make sure that length of your alias name copied to this buffer does not exceed maximum allowed size for alias names (provided in MaxAliasLength global constant). If alias name is set longer, it is likely to cause severe errors in program!

lpRequireFileProc

This is the address of RequireFile callback function. Before your plugin may access the file provided with lpszFileName parameter, RequireFile function must be called, and path returned by this function used to access the file.

wMaxDescSize

Specifies the maximum allowed description length, as set by user-defined setting in WhereIsIt. This value can be between 4 KB and MaxDescLength. If a plugin returns description longer than this value, the description will be truncated.

bSilentMode

Specifies whether plugin should be operating in silent mode. When in silent mode, plugins are expected to function in a background only, and are not allowed to popup dialog boxes, or wait for user input.

hOwnerWnd

Handle of the owner window. You can use this value if your plugin displays a dialog or a message box.

See also:

ImportDesc_SameFileEx, RequireFile


 IMPORTPARENTITEMREC

DescAPI version: 2.xx

The IMPORTPARENTITEMREC structure is used as a parameter with the ImportDesc_ParentItemEx function.

typedef struct {

    LPTCSTR   lpszParentName;

  LPTCSTR   lpszFileList;

  LPTCSTR   lpszDesc;

  LPTCSTR   lpszAliasName;

  PROC      lpRequireFileProc;

  WORD      wMaxDescSize;

  BOOL      bSilentMode;

  HANDLE    hOwnerWnd;

} IMPORTPARENTITEMREC, FAR *LPIMPORTPARENTITEMREC;

Members

lpszParentName

Points to the address of a null-terminated string, holding a full path to the parent item (item that will receive description provided by calling this function).

lpszFileList

Points to the address of a double - null-terminated list of file names. These are files that were found in current folder matching the file mask of requested plugin (for example, if plugin has a mask of "*.TXT", this is the list of all .TXT files found in current folder). List is in form of sequential null-terminated strings, with double NULL character after the last item, i.e.:

  FILE1.TXT#0FILE2.TXT#0FILE3.TXT#0#0

where "#0" represents a NULL character. It is up to plugin to choose which file will it use to import description from. Provide the name of chosen file(s) to the RequireFile function before your plugin attempts to open the file. Files in the list are sorted in the same order as are plugin's mask, preserving priorities. For example, if plugin is set to import "*.aaa,*.bbb" files, all aaa files will be listed first, followed by all bbb files.

lpszDesc

Points to the buffer (reserved by WhereIsIt) to receive null-terminated string with the description.

WARNING: Make sure that length of your description copied to this buffer does not exceed maximum allowed size for descriptions (provided in MaxDescLength global constant). If description is set longer, it is likely to cause severe errors in program!

lpszAliasName

Points to the buffer (reserved by WhereIsIt) to receive null-terminated string with item's alias name. Alias names may not contain line breaks.

WARNING: Make sure that length of your alias name copied to this buffer does not exceed maximum allowed size for alias names (provided in MaxAliasLength global constant). If alias name is set longer, it is likely to cause severe errors in program!

lpRequireFileProc

This is the address of RequireFile callback function. Before your plugin may access the file provided with lpszFileName parameter, RequireFile function must be called, and path returned by this function used to access the file.

wMaxDescSize

Specifies the maximum allowed description length, as set by user-defined setting in WhereIsIt. This value can be between 4 KB and MaxDescLength. If a plugin returns description longer than this value, the description will be truncated.

bSilentMode

Specifies whether plugin should be operating in silent mode. When in silent mode, plugins are expected to function in a background only, and are not allowed to popup dialog boxes, or wait for user input.

hOwnerWnd

Handle of the owner window. You can use this value if your plugin displays a dialog or a message box.

See also:

ImportDesc_ParentItemEx, RequireFile


 IMPORTITEMLISTREC

DescAPI version: 2.xx

The IMPORTITEMLISTREC structure is used as a parameter with the ImportDesc_ItemListEx function.

typedef struct {

    LPTCSTR   lpszParentName;

  LPTCSTR   lpszFileList;

  PROC      lpRequireFileProc;

  PROC      lpStoreDescProc;

  PROC      lpStoreAliasProc;

  WORD      wMaxDescSize;

  BOOL      bSilentMode;

  HANDLE    hOwnerWnd;

} IMPORTITEMLISTREC, FAR *LPIMPORTITEMLISTREC;

Members

lpszParentName

Points to the address of a null-terminated string, holding the full path to parent item (item that will receive description provided by calling this function).

lpszFileList

Points to the address of a double - null-terminated list of file names. These are files that were found in current folder matching the file mask of requested plugin (for example, if plugin has a mask of "*.TXT", this is the list of all .TXT files found in current folder). List is in form of sequential null-terminated strings, with double NULL character after the last item, i.e.:

  FILE1.TXT#0FILE2.TXT#0FILE3.TXT#0#0

where "#0" represents a NULL character. It is up to plugin to choose which file will it use to import description from. Provide the name of chosen file(s) to the RequireFile function before your plugin attempts to open the file. Files in the list are sorted in the same order as are plugin's mask, preserving priorities. For example, if plugin is set to import "*.aaa,*.bbb" files, all aaa files will be listed first, followed by all bbb files.

lpRequireFileProc

This is the address of RequireFile callback function. Before your plugin may access the file provided with lpszFileName parameter, RequireFile function must be called, and path returned by this function used to access the file.

lpStoreDescProc

Holds the address of StoreDescProc callback function, used to report descriptions back to WhereIsIt. See the description of StoreDescProc for more details.

lpStoreAliasProc

Holds the address of StoreAliasProc callback function, used to report descriptions back to WhereIsIt. See the description of StoreAliasProc for more details.

wMaxDescSize

Specifies the maximum allowed description length, as set by user-defined setting in WhereIsIt. This value can be between 4 KB and MaxDescLength. If a plugin returns description longer than this value, the description will be truncated.

bSilentMode

Specifies whether plugin should be operating in silent mode. When in silent mode, plugins are expected to function in a background only, and are not allowed to popup dialog boxes, or wait for user input.

hOwnerWnd

Handle of the owner window. You can use this value if your plugin displays a dialog or a message box.

See also:

ImportDesc_ItemListEx, RequireFile


 IMPORTDISKINFOREC

DescAPI version: 2.xx

The IMPORTDISKINFOREC structure is used as a parameter with the ImportDesc_DiskInfoEx function.

typedef struct {

  LPDISKINFOREC lpDiskInfo;

  LPTCSTR   lpszDesc;

  LPTCSTR   lpszDiskName;

  LPTCSTR   lpszCDDBQueryID;

  WORD      wMaxDescSize;

  BOOL      bSilentMode;

  HANDLE    hOwnerWnd;

} IMPORTDISKINFOREC, FAR *LPIMPORTDISKINFOREC;

Members

lpDiskInfo

Points to the DISKINFORECORD structure, containing details about media that is being scanned.

lpszDesc

Points to the buffer (reserved by WhereIsIt) to receive null-terminated string with the description.

WARNING: Make sure that length of your description copied to this buffer does not exceed maximum allowed size for descriptions (provided in MaxDescLength global constant. If description is set longer, it is likely to cause severe errors in program!

lpszDiskName

Points to the buffer (reserved by WhereIsIt) to receive null-terminated string with disk's name. Disk names may not contain line breaks, and should be of a reasonable length, say max. 80 characters

WARNING: Make sure that length of your alias name copied to this buffer does not exceed maximum allowed size for alias names (provided in MaxAliasLength global constant). If disk name is set longer, it is likely to cause severe errors in program!

lpszCDDBQueryID

Specifies the CDDB query string for current media, if one is available. The CDDB query string is retrieved during media scan and stored in catalog. This data would usually only be used by ptCDDB type plugins.

wMaxDescSize

Specifies the maximum allowed description length, as set by user-defined setting in WhereIsIt. This value can be between 4 KB and MaxDescLength. If a plugin returns description longer than this value, the description will be truncated.

bSilentMode

Specifies whether plugin should be operating in silent mode. When in silent mode, plugins are expected to function in a background only, and are not allowed to popup dialog boxes, or wait for user input.

hOwnerWnd

Handle of the owner window. You can use this value if your plugin displays a dialog or a message box.

See also:

ImportDesc_DiskInfoEx, DISKINFORECORD, RequireFile


 FORMATDESCREC

DescAPI version: 2.xx

The FORMATDESCREC structure is used as a parameter with the FormatDescriptionEx function.

typedef struct {

  LPTCSTR   lpszDesc;

  WORD      wMaxDescSize;

  LPTCSTR   lpszSourceModuleFile;

  WORD      wSourcePluginID;

  HANDLE    hOwnerWnd;

} FORMATDESCREC, FAR *LPFORMATDESCREC;

Members

lpszDesc

Points to the buffer (reserved by WhereIsIt) when the existing description string is provided. The plugin is expected to provide the resulting string in that same buffer, replacing provided string with the new version.

WARNING: Make sure that length of your description copied to this buffer does not exceed maximum allowed size for descriptions (provided in MaxDescLength global constant. If description is set longer, it is likely to cause severe errors in program!

wMaxDescSize

Specifies the maximum allowed description length, as set by user-defined setting in WhereIsIt. This value can be between 4 KB and MaxDescLength. If a plugin returns description longer than this value, the description will be truncated.

lpszSourceModuleFile

Points to the address of a null-terminated string, holding the file name of the description module, containing the plugin that was used for extracting current description. This information can be used if formatting plugin is only intended to handle descriptions imported by specific plugins.

wSourcePluginID

Contains the ID of the plugin that was used for extracting current description. This information can be used if formatting plugin is only intended to handle descriptions imported by specific plugins.

hOwnerWnd

Handle of the owner window. You can use this value if your plugin displays a dialog or a message box.

See also:

FormatDescriptionEx


 FORMATFILENAMEREC

DescAPI version: 2.10

The FORMATFILENAMEREC structure is used as a parameter with the FormatFileNameEx function.

typedef struct {

  LPTSTR    lpszFileName;

  LPTSTR    lpszFullPath;

  BOOL      bIsDirectory;

  BOOL      bIsCompressed;

  HANDLE    hOwnerWnd;

} FORMATFILENAMEREC, FAR *LPFORMATFILENAMEREC;

Members

lpszFileName

Points to the buffer containing file or folder name. Plugin should modify the case of characters in this buffer as desired, but it must not change the contents in any other way. WhereIsIt checks the modified name and if the resulting buffer differs from the original in any detail other than character case, plugin's result will be discarded and original file name used instead.

lpszFullPath

Points to the buffer where the full path to file or folder is stored, including the drive and file/folder name. If lpszFileName is a file compressed inside archive file, this parameter specifies a full path to the archive file.

bIsDirectory

Set to TRUE if lpszFile name specifies a folder. If FALSE, lpszFile name specifies a regular or compressed (archive) file.

bIsCompressed

Set to TRUE if lpszFile is a file compressed inside an archive file.

hOwnerWnd

Handle of the owner window. You can use this value if your plugin displays a dialog or a message box.

See also:

FormatFileNameEx


 IMPORTTHUMBNAILREC

DescAPI version: 2.xx

The IMPORTTHUMBNAILREC structure is used as a parameter with the ImportThumbnailProcEx function.

typedef struct {

  LPTCSTR   lpszFileName;

  WORD      wXSize;

  WORD      wYSize;

  HANDLE    hBitmapHandle;

  PROC      lpRequireFileProc;

  BOOL      bSilentMode;

  HANDLE    hOwnerWnd;

} IMPORTTHUMBNAILREC, FAR *LPIMPORTTHUMBNAILREC;

Members

lpszFileName

Points to the null-terminated string, containing a full path to the image file. Provide this parameter to the RequireFile function before your plugin attempts to open the file.

wXSize, wYSize

Provide the target pixel size of imported image. Usually those values would indicate the size of thumbnails, as it is user-defined in WhereIsIt. Note that this values are informative only, plugins are not required to resample images to specified size as WhereIsIt can handle that. Usually, plugins will load images in their full size and let WhereIsIt to do any necessary processing to get a thumbnail out of it. Plugins may, however, do resampling or other image processing themselves, if they can do a better job that WhereIsIt's built-in capabilities. If the returned image is within specified size (or smaller), WhereIsIt will not process it any further.

Please note:

If wXSize and wYSize are reported as 0, plugin should always return the picture in its native size, even if it includes resampling capabilities on its own. 0 values indicate that imported picture will not be used for generating a thumbnail, but it will be displayed in the internal image viewer in its full size.

hBitmapHandle

Plugin is expected to store the bitmap handle of loaded image to this field. The handle should be allocated by the plugin, but will be released later by WhereIsIt, when the bitmap is no longer needed.

lpRequireFileProc

This is the address of RequireFile callback function. Before your plugin may access the file provided with lpszFileName parameter, RequireFile function must be called, and path returned by this function used to access the file.

bSilentMode

Specifies whether plugin should be operating in silent mode. When in silent mode, plugins are expected to function in a background only, and are not allowed to popup dialog boxes, or wait for user input.

hOwnerWnd

Handle of the owner window. You can use this value if your plugin displays a dialog or a message box.

See also:

ImportThumbnailProcEx, RequireFile


 IMPORTCUSTOMICONREC

DescAPI version: 2.10

The IMPORTCUSTOMICONREC structure is used as a parameter with the ImportCustomIconProcEx function.

typedef struct {

  LPTSTR    lpszItemPath;

  HANDLE    hIconHandle;

  BOOL      bSilentMode;

  HANDLE    hOwnerWnd;

} IMPORTCUSTOMICONREC, FAR *LPIMPORTCUSTOMICONREC;

Members

lpszItemPath

Points to the buffer holding the path of drive or folder custom icon is being imported for, for example "C:", "D:\Folder1\Folder", "\\SERVER\DRIVE\Folder", etc. The trailing backslash is not included.

hIconHandle

Plugin is expected to store the icon handle to this field. The handle should be allocated by the plugin, but will be released later by WhereIsIt, when the icon is no longer needed.

bSilentMode

Specifies whether plugin should be operating in silent mode. When in silent mode, plugins are expected to function in a background only, and are not allowed to popup dialog boxes, or wait for user input.

hOwnerWnd

Handle of the owner window. You can use this value if your plugin displays a dialog or a message box.

See also:

ImportCustomIconProcEx


 PLUGINCAPABILITIESREC

DescAPI version: 2.0

The PLUGINCAPABILITIESREC structure is used with the PluginCapabilitiesProc function.

typedef struct {

    BOOL      bImportingDesc;

  BOOL      bImportingAlias;

} PLUGINCAPABILITIESREC, FAR *LPPLUGINCAPABILITIESREC;

Members

bImportingDesc

Set to TRUE if plugin will attempt to import descriptions.

bImportingAlias

Set to TRUE if plugin will attempt to import alias names.

See also:

PluginCapabilitiesProc


 Plugin Default State Constants

This is the list of currently supported default states for plugins, used as return values with the optional PluginDefaultStateProc function. This states can be used to advise WhereIsIt on how specific plugin should be used - is it always enabled or disabled by default, or does it remember the last user's setting.

// --- DescAPI 2.0 only ---

#define pdsUserDefined_EnabledFirstTime    0

#define pdsUserDefined_DisabledFirstTime   1

#define pdsForceAlwaysEnabled              2

#define pdsForceAlwaysDisabled             3

pdsUserDefined_EnabledFirstTime

Plugin remembers the last global setting in WhereIsIt, user can select himself if plugin will be enabled or disabled by default. If plugin is new to WhereIsIt, it is set as enabled by default. This is the recommended setting for all normal plugins.

pdsUserDefined_DisabledFirstTime

Plugin remembers the last global setting in WhereIsIt, user can select himself if plugin will be enabled or disabled by default. If plugin is new to WhereIsIt, it is set as disabled by default. This setting should be used for plugins that are not likely or wanted to be used in normal circumstances - setting them as disabled by default allows new users who are not yet familiar with plugins not to be confused with the effects of such plugin.

pdsForceAlwaysEnabled

Forces the plugin to be always enabled by default, regardless of previous user's setting. User can still disable the plugin, but has to do so manually before each scan. Use with caution and only with a good reason.

pdsForceAlwaysDisabled

Forces the plugin to be always disabled by default, regardless of previous user's setting. User can still enable the plugin, but has to do so manually before each scan. Use this setting for plugins that are for very special purposes only and are only to be used in certain circumstances.

See also:

PluginDefaultStateProc


 Glossary

Alias name

A replacement name for files and folders, used only internally inside catalogs. Each file or folder can have its own alias name, in cases where the original file name is not very informative or friendly. Description plugins can import and set alias names as well as descriptions.

A common example of using alias names is replacing the Audio Track files (Tracknn.cda) with the Title and Author data, retrieved by the CDDB plugin.

Description

A textual, possibly multi-line description of an item in catalog. Every catalog item can have its own description, which is either imported automatically during media scan by description plugins, or edited manually by the user.

Description Module

Description module is a DLL file, used to expand WhereIsIt's description importing capabilities. Each description module can contain one or more description plugin.

Plugins

Description plugins are an add-ons for WhereIsIt that allow automated description importing from different sources. Mostly plugins are used for importing textual descriptions, however some plugins types also handle formatting of imported descriptions, or they import image thumbnails.

Thumbnail

A small graphical representation of a document, most commonly used on image file. WhereIsIt can import such small versions of image files and store them inside catalogs, making them available for preview even when files themselves are not available.