ContentGetValue

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

Declaration

int __stdcall ContentGetValue(char* FileName,int FieldIndex,int UnitIndex, void* FieldValue,int maxlen,int flags);

Description of parameters

FileName	The name of the file 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 ContentGetSupportedField.
UnitIndex	The index of the unit used. Example: If the plugin returned the following unit string in ContentGetSupportedField: 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: FieldValue is a pointer to a 0-terminated string. ft_stringw: FieldValue is a pointer to a 0-terminated wide string. ft_fulltext: Read maxlen bytes of interpreted data starting at offset UnitIndex. The data must be a 0 terminated string. ft_multiplechoice: FieldValue is a pointer to a 0-terminated ANSI 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. Note: When using Unicode strings, you need to divide this value by 2 to get the maximum number of characters!
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 return 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. CONTENT_PASSTHROUGH: If this flag is set, the FieldValue passes the file size to the plugin as ft_numeric_floating. This value is only set if you have returned the flag contflags_passthrough_size_float from the function ContentGetSupportedFieldFlags. No units have been applied yet, the size is passed to the plugin as bytes. You then need to apply the appropriate unit, and set the additional string field. This option is used to display the size even in locations where the plugin doesn't work, e.g. on ftp connections or inside archives.

Return value

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

Remarks

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, ContentGetValue 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 ContentGetValue 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 now accepts that ContentGetValue returns a different data type than ContentGetSupportedField for the same field, e.g. a string "no value" instead of a numeric field. Note that older versions of Total Commander crashed in the search function in this case, so if you want to do this, you MUST check that the plugin version is reported as >=1.3 (hi=1, low>=3 or hi>=2).

ft_numeric_floating (New with TC 6.52, plugin interface version >=1.4): 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".

Note about Unicode: ft_delayed and ft_ondemand fields and alternate text for ft_numeric_floating must be UTF-16 Unicode when using the wide function ContentGetValueW.

About caching the data: Total Commander will not call a mix ContentGetValue 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 ContentGetValue 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]).

---

Back to Content plugins developer guide