FsContentGetValue is called to retrieve the value of a specific field for a given file, e.g. the date field of a file.

 

 

int __stdcall FsContentGetValue(char* FileName,int FieldIndex,int UnitIndex,

                void* FieldValue,int maxlen,int flags);

 

 

FileName The name of the file (in plugin namespace) for which the plugin needs to return the field data.

 

FieldIndex The index of the field for which the content has to be returned. This is the same index as the FieldIndex value in FsContentGetSupportedField.

 

UnitIndex The index of the unit used. Example:

If the plugin returned the following unit string in FsContentGetSupportedField:

bytes|kbytes|Mbytes

Then a UnitIndex of 0 would mean bytes, 1 means kbytes and 2 means MBytes

If no unit string was returned, UnitIndex is 0.

For ft_fulltext, UnitIndex contains the offset of the data to be read.

 

FieldValue Here the plugin needs to return the requested data. The data format depends on the field type:

ft_numeric_32: FieldValue points to a 32-bit signed integer variable.

ft_numeric_64: FieldValue points to a 64-bit signed integer variable.

ft_numeric_floating: FieldValue points to a 64-bit floating point variable (ISO standard double precision)

See remark below about additional string field!

ft_date: FieldValue points to a structure containing year,month,day as 2 byte values.

ft_time: FieldValue points to a structure containing hour,minute,second as 2 byte values.

ft_boolean: FieldValue points to a 32-bit number. 0 neans false, anything else means true.

ft_string or ft_multiplechoice: FieldValue is a pointer to a 0-terminated string.

ft_fulltext: Read maxlen bytes of interpreted data starting at offset UnitIndex. The data must be a 0 terminated string.

ft_datetime: A timestamp of type FILETIME, as returned e.g. by FindFirstFile(). It is a 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601. The time MUST be relative to universal time (Greenwich mean time) as returned by the file system, not local time!

ft_delayed, ft_ondemand: You may return a zero-terminated string as in ft_string, which will be shown until the actual value has been extracted. Requires plugin version>=1.4.

 

 

maxlen The maximum number of bytes fitting into the FieldValue variable.

 

flags Currently only one flag is defined:

CONTENT_DELAYIFSLOW: If this flag is set, the plugin should return ft_delayed for fields which take a long time to extract, like file version information. Total Commander will then call the function again in a background thread without the CONTENT_DELAYIFSLOW flag. This means that your plugin must be implemented thread-safe if you plan to return ft_delayed.

The plugin may also reutrn ft_ondemand if CONTENT_DELAYIFSLOW is set. In this case, the field will only be retrieved when the user presses <SPACEBAR>. This is only recommended for fields which take a VERY long time, e.g. directory content size. You should offer the same field twice in this case, once as delayed, and once as on demand. The field will be retrieved in the background thread also in this case.

 

 

Return the field type in case of success, or one of the following error values otherwise:

ft_nosuchfield The given FieldIndex is invalid

ft_fileerror Error accessing the specified file FileName

ft_fieldempty The file does not contain the specified field

ft_delayed The extraction of the field would take a long time, so Total Commander should request it again in a background thread. This error may only be returned if the flag CONTENT_DELAYIFSLOW was set, and if the plugin is thread-safe.

ft_ondemand The extraction of the field would take a very long time, so it should only be retrieved when the user presses the space bar. This error may only be returned if the flag CONTENT_DELAYIFSLOW was set, and if the plugin is thread-safe.

 

 

ft_fulltext handling is a bit special. It is only used for searching in interpreted file contents, e.g. for finding text in binary files. For example, the ID3 plugin uses ft_fulltext to allow the user to search for a string in ALL header fields.

Calls work like this:

First, FsContentGetValue is called with UnitIndex set to 0. The plugin then parses the file data, and (if necessary) keeps it in a cache. It writes the first block of maxlen-1 bytes to FieldValue and returns ft_fulltext. The data written must be a 0-terminated string! Total Commander then searches in the block, and requests the next block with offset maxlen-1, etc. Once there is no more data, the plugin needs to retrun ft_fieldempty. If there is a match, TC signals the plugin that it can delete the cached data by calling FsContentGetValue with UnitIndex set to -1! The return value should be ft_fieldempty in this case. This call with UnitIndex=-1 does not happen when the plugin terminates the search with ft_fieldempty because it reached the end of the file.

 

Total Commander accepts that FsContentGetValue returns a different data type than FsContentGetSupportedField for the same field, e.g. a string "no value" instead of a numeric field.

 

ft_numeric_floating: You can now put a 0-terminated string immediately behind the 64bit floating point variable, which will then be shown instead in file lists. This is useful if the conversion precision used by TC isn't appropriate for your variables. The numeric variable will still be used for sorting and searching. If the string is empty, TC will ignore it (it is set to 0 before calling this function, so the function will remain backwards-compatible). Example: The numeric value is 0.000002. You can return this value as a 64-bit variable, and the string you find most appropriate, e.g. "2*10^-6" or "0.000002".

 

About caching the data: Total Commander will not call a mix FsContentGetValue for different files, it will only call it for the next file when the previous file can be closed. Therefore a single cache per running Total Commander would be sufficient. However, there may be other calls to FsContentGetValue with requests to other fields in the background, e.g. for displaying result lists. There may also be multiple instances of Total Commander at the same time, so if you use a TEMP file for storing the cached data, make sure to give it a unique name (e.g. via GetTempFileName).