listfiles.dll v1.10 beta3 (aka 1.092) by Carpe Noctem / Misanthrop


(more or less IMPORTANT) NOTES:
-you should call the setoutput function with the non-threading version (do NOT use /dllCALL or $dllCALL())
-while you are seaching for files with the multithreaded /dllcall or $dllcall(), prevent yourself from calling
 setoutput before the search is done (you'll get an lf_return signal); maybe, it makes no trouble calling setoutput
 while you get an lf_file or lf_dir signal, but not sure, depends how Khaled implemented the stuff... )
-fname, dir, reldir changed to lfname, ldir, lreldir (l means always long names), afname, adir, areldir changed to
 fname, dir, reldir (always works in mIRC, they're garantueed to contain NO double spaces)
 lenf is know flen
-the tags created, modified and accessed should work with $asctime(), it may happen that the time is not converted
 to your localtime (notice me if this is the case which what the dll returns, what result you estimated, what mirc's function
 or explorer says, your timezone...), the old version seemed to had problems with non-NTFS filesystems, I hope the new method
 works on FAT too
-the listfiles flag 'm' for reading mpeg data has been removed, the dll detects itself depending on the output you
 set if it is needed to read mpeg info, id3v1 and/or id3v2 (only if filename ends with *.mp? and is not *.mpg)
-using the MPEG or ID3 tags will speed down the dll a lot (however, it is faster than using mirc's function I think,
 and faster than a scripted reader), think about using the multithreaded $dllcall() instead of $dll()
-the signals has been renamed, the new signals are
 lf_return: returns the same as $dll() in $1- but as signal.. needed cause $dllcall() returns the path + filename of the
 dll.. really useless
 lf_file: output for a file in $1-, formatted which what you gave to setoutput
 lf_dir: returns the directory that the dll enters for scanning in $1- (only if depth is < than scandepth)



Functions
---------

1.) setoutput

Sets the output for each file. The tags are replaced with the file information and written to a file and/or send
as a signal, depending on the output mode you set.
The default value is: <fname> <fsize>
the function always returns OK

HINT:
You may set it to 0 + 0 0 0 <fname> $+ $!chr(9) $+ <fsize> for example to work with an MDX'ed or DCX'ed controls


tags are always enclosed in <tag>
The supported tags are:

<size>		This is the size of the file in bytes.
		NOTE: This tag was named <fsize> in a prior version

<fsize>		This is the formatted and rounded size of the file in b, kb, mb or gb.
		Example: 12.34mb

<fname>		The name of the file found (without pathname)
		NOTE: if name contains double spaces, you'll get the short name

<dir>		The path to the file (with a \ at the end)
		NOTE: if name contains double spaces, you'll get the short name

<reldir>	This is the path to the file relative to the dir you searched in. For example, 
                if you searched in "C:\audio" and found "C:\audio\Metallica\Metallica - One.mp3", 
                <reldir> contains "Metallica\". If you found C:\audio\title.ogg, <reldir> is 
                empty.
		NOTE: if name contains double spaces, you'll get the short name


<lfname>
<ldir>		Similiar to <fname>, <dir> and <reldir>, but returns the long names always
<lreldir

<sfname>
<sdir>		Similiar to <fname>, <dir> and <reldir>, but returns the short names always
<sreldir>	


<type>		The number of the wildcard, that matched for this file, starting with 1.
		The value will be 0 if it didn't match, but the "list all files" flag was set

<attr>		for each attribute that is set, the depending char will be added
		a = archive attribute is set
		c = compressed attribute is set
		e = encrypted attribute is set
		h = hidden attribute is set
		r = readonly attribute is set
		s = system  attribute is set
		t = temprorary attribute is set

<created>	the creation time of the file
<accessed>	the time the file was last accessed
<modified>	the time the file was last modified



Audio info:
<len>		MPEG and Ogg Vorbis:	estimated length of the file in seconds, for vorbis, this value is calculated with the nominal bitrate
					which may differ from the real bitrate
<flen>		MPEG and Ogg Vorbis:	same as <len>, but formatted to hh:mm:ss (hh >= 10), h:mm:ss (h > 0), mm:ss (mm >= 10) m:ss else
<bitrate>	MPEG:		bitrate in kbps on mp1/2/3 files (this value is incorrect for VBR files for dll version 1.10)
		Ogg Vorbis:	the nominal bitrate in kbps

<minbitrate>	Ogg Vorbis:	the minimum bitrate in kbps
<maxbitrate>	Ogg Vorbis:	the maximum bitrate in kbps

<sample>	MPEG and Ogg Vorbis:	samplerate in Hz

<chans>		typ of channels
		MPEG:		"Mono", "Dual Channel", "Stereo" or "Joint Stereo"
		Ogg Vorbis:
			1 channel:		"Mono"
			2 channels:		"Stereo"
			3 channels:		"1D Surround" (
			4 channels:		"Quadraphonic Surround"
			5 channels:		"5 Channel Surround"
			6 channels:		"5.1 Surround"
			more than 6 channels:	"Application defined" (there seems to be no 7.1 in Ogg Vorbis I)

<layer>		MPEG:	layer of file: "Layer I", "Layer II", "Layer III" or "reserved" (in most cases, if layer is "reserved"
			the header of the mp? file was bad and all MPEG info is wrong)

<vendor>	Ogg Vorbis: vendor string, should be "Xiph.Org libVorbis I 20020717"

<ver>		MPEG: 1.0, 2.0, 2.5 or "reserved"
		Ogg Vorbis: "Vorbis 1" or "Unknown"

<vbr>		MPEG: if file has a variable bitrate: 1 for vbr, 0 for cbr (constant bitrate)
<priv>		MPEG: 1 if the private bit is set, else 0
<crc>		MPEG: 1 if the file is CRC protected, else 0
<copy>		MPEG: 1 if the copyright bit is set, else 0
<orig>		MPEG: 1 if the original bit is set, else 0

id3v1 info:
<title>		title or empty string
<artist>	artist or empty string
<album>		album or empty string
<year>		year or empty string
<comment>	comment or empty string
<track>		track number, for idv1.0 this is 0 (track number is only set in version 1.1)
<genre>		genre or "Unknown"

id3v2 info:
to read information about id3v2, use <v2_frame> (NOT <id3_frame> !!!), replacing "frame" with the name of the frame you're searching for
for example, to get the title, which is "TIT2", use the tag <v2_tit2>
you'll find a list of all frames here: http://www.id3.org/id3v2.3.0.html#sec4

Ogg Vorbis comments:
to read a comment, use <com_field>, replacing "field" with the name of the comment you're searching for
for example, to get the title, which is "TITLE", use the tag <COM_TITLE>
you'll find a list of all DEFAULT fields here: http://www.xiph.org/vorbis/doc/Vorbis_I_spec.html#id2561106
there may be non-default fields, but there is no method to get a list of all fields found yet


example:
$dll(listfiles.dll, setoutput, <fname> MPEG <version> <layer> <bitrate>kbps $!iif(<vbr>,[VBR]) <sample>Hz <chans> title:<title> $!iif($len(<v2_tit2>),tit2:<v2_tit2>) artist:<artist> album:<album> comment:<comment> year:<year> track:<track> genre:<genre>)

$!iif($len(<v2_tit2>),tit2: <v2_tit2>) isn't very nice, but using $!iif(<v2_tit2>,tit2: $ifmatch) isn't possible, cause a title like "Turn The Page" will be interpreted as using "Turn" as first parameter, "Page" as second, and "The" as operator (like $iif(%a >= %b))
anyone tested somethink like $!iif("<v2_tit2>", tit2: $ifmatch) yet?


2.) listfiles

NOTE1:	You MAY call the "setoutput" function before using the listfiles function.
NOTE2:	once called "setoutput", you've call "setoutput" ONLY if you want CHANGE the output or the dll has been
	unloaded by /dll -u
NOTE3:	To scan for all files, you SHOULD set the * mode instead of insert * as a wildcard.
NOTE4:	it is possible to search for *.mp?, but exclude *.mpg (exclude is more powerful than matching)
NOTE5:	it seems that windows (or NTFS?) caches file searches, this is the reason why the first search within the
	same directory is a lot slower
NOTE6:	if you use "filename" without a path, the file is/seems to be created in the directory the dll is in, NOT in the mircdir

Parameters:	mode > filename > dir > [wildcards] > [ex. wildcards] > [depth]

mode		the output modes, supported modes are:
		a = appends to file, this also sets the 'f' flag, filename has to be valid, if the file doesn't exist, it will be created
		f = writes output to file, the output is formatted by what you set with setoutput before, filename has to be valid, if the file exists, it will be truncated (cleaned) before
		h = skips files and directorys that have the attribute hidden set
		s = sends the signal "lf_file" for each file, the output is formatted by what you set with setoutput before
		d = sends the signal "lf_dir" for each directory that will be scanned

		* = adds all files (excluded files or hidden files when h is set still are skipped)
		it is possible to output to a file AND using the signals

filename	if a or f mode is set, this is the file where the dll writes to (a line for each file) (may be empty else)
dir		initial directory to scan
wildcards	a ; seperated list (up to 32 at the moment) of wildcards (* and ? should work)
ex. wildcards	a ; seperated list (up to 32 at the moment) of wildcards (* and ? should work), that are excluded always
		(useful combined with * mode or wildcard: *.mp? and exclude *.mpg to search for mp1, mp2, mp3, mpc but mpg)
depth		the directory depth to scan, 0 for no limit


wildmatches have only to be set if the * mode isn't set
ex. wildmatches may be set
depth defaults to 0

example:
$dll(listfiles.dll, setoutput, <fname> $!+(4",$asctime(<created>),") <<size>>)
$dllcall(listfiles.dll, echo -q, listfiles, fhs* > $mircdirbla.txt > $mircdir > *.mrc;*.ini > *.exe;*.bat;*.dll)

return value:
the first token informs if the call succeeded or failed
if it fails, the first token is ERROR, followed by a description
if it successed, the first token is OK, the second is the filename you gave in double quotes, param 3 is the number of files, param 4 the number of bytes of all files, param 5 the size of all files, converted to b, kb, mb or gb

this value is returned by $dll() and always send to mirc as lf_result signal, which makes it work with the multithreading $dllcall(), cause $dllcall() returns the path to the dll (useless in my option); cause this signal is send when the dll has finished its work, the callback alias (2. param in $dllcall()) isn't needed and may be .echo -q for example

3.) DllInfo

returns some useless information about the dll

4.) GetFileSystem

Usage: $dll(listfiles.dll, GetFileSystem, <drive>)
Example:  $dll(listfiles.dll, GetFileSystem, e)
Example2: $dll(listfiles.dll, GetFileSystem, E:\)

returns: "OK filesystem" or "ERROR"

as it seems that NTFS ordered files by name, you may compare the result of this function with NTFS first to find out
if it is needed to use sorting or not.

I do NOT know if windows makes a difference between FAT and FAT32 (I only have a USB Stick to test for non-NTFS volumes)
I also do NOT know if WinFS will return NTFS later, because it is based on NTFS, or if it will return somethink like WINFS
You've decide which what you will compare the result, the best will be somethink like: if ($left($gettok(%result, 2, 32), 3) == FAT)




TODO / IDEAS:
-------------
-html or somethink like that instead of txt help
-example.. a dialog listing all audio files in a (MDXed / DCXed list) using $dllcall() and on *:signal:lf_file: if ($dialog(mp3)) { did -a mp3 $mp3listID $1- } would be nice
 cause it will not freeze your mIRC :) ... this was the reason why I wrote the dll some time ago btw
-vbr support for mp3
-improve ogg vorbis reading?
-mpc reading?
-regular expression instead of wildcards? but i think no at the moment...
-instead of using a file or signals as output, make it possible to give a dialogname and ID of a treeview and building
 a file/dir tree?
-any good idea? message me :)

--------------------
Contact Information:
--------------------

English and German

EMail: Carpe@bexcrew.de
pmsg on www.mircscripts.org to: Carpe Noctem
www.mircscripts.org's forum


----------
Changelog:
----------
V1.10 BETA3 aka V1.092
+   added the GetFileSystem function which allows you to find out if a volume is FAT or NTFS, this may help you to decide
    if you have to sort the files or if they are already sorted (on NTFS, they should be sorted)
V1.10 BETA2 aka V1.091
f   fixed bug reading ID3V2 tags from MPEG files
+   experimental support for Ogg Vorbis files, the length is only estimated by nominal bitrate, not the real bitrate,
    the UTF8 text of comments are converted to extended ASCII, which means no support for multibyte chars
+   filenames and dirnames containing ,  and  are now compared correctly (// uppercase of //)
f   fixed some docu errors, e.g. reading id3v2 title you've to use v2_tit2 and not id3_tit2


V1.10 BETA aka V1.09
+   the dll uses 3 signals now (return, file, directory)
c   changed the method how the output is generated, the output data is only interpreted once (while calling setoutput)
    instead of for each file to like in version < 1.09, this also allows the dll to autodetect if it needs to read
    mpeg data, id3v1 data and/or id3v2 data (for example, if you don't use the <v2_*> tag, id3v2 reading will be disabled)
c   some internal changes which makes the dll a bit faster (optimized, making use of C++ classes where useful)
c   a few tags were renamed
f   the method how file times (created, last accessed, modified) were changed, the old method seems to have problems
    with non-NTFS drives (and maybe Win95)

V1.00
?   never released

V1.00 BETA
+   added scan mode 'm', which activates reading of audio specific data for mpeg files (vbr isn't completed yet)
+   added 20 tags (only activated if 'm' mode set) to get information about mpeg files, id3v1 and id3v2 data
f   fixed a bug, where the signal output was not null terminated if the output string wasn't ended by a tag

V0.99 BETA
+   sends a signal when the scan is finished to make the script get information about number of files and total size with multithreaded $dllcall()
c   the dll now uses wildcards to search (idea by hybcoder)
c   output mode param changed from bitmask to list of chars for easier use
c   the dll now will not be unloaded after 10mins, to free resources, use /dll -u
-   the functions for common dialogs has been removed, if you still need the function, maybe you'll find a dll on mircscripts.org
    or mail me and I'll think about making a seperate dll for that

V0.95, V0.98 (never released)
c   parts of the dll are rewritten (about the half)
c   memory management has changed, the dll doesn't allocate dynamic memory
c   64bit handling optimized (used for total filesize)
+   added the output mode param as bitmask
+   new tags <created>, <modified>, <modified> and <attr>


V0.92
f   fixed a bug, where the last char (the ">") of an unsupported tags like <unknown> was cutted off
f   fixed a small memory leak
c   some code changes
c   changed typo in Changelog of V0.9 ;) the tag <fsize> had be renamed to <size> and a new <fsize> was included
    (and NOT a new <fname>)
+   exclude param for listfiles (idea by First Last)

V0.9
c  changed the tag name of <fsize> to <size>
+  added a new <fsize>, the new tag stands for "formatted size" and returns the size converted to b, kb, mb or gb
+  added <afname>, <adir> and <areldir> tag, automatically switching between long and short filenames, to
   prevent, that mIRC can't access a file, cause it contains a space followed by a second like "ab   cd.txt"
+  an empty output string now means, that the files and their size should only be counted, but the results are not
   printed to the output file. the second parameter of setoutput returns if the dll will write to file.
+  added a DllInfo function


V0.8
?  first public release, don't use 1.0 cause it may happen that someone will find a bug and there 
   are problems on other OS's and don't want to be at version 5.32123324 if dll is final.

... (lots of changes, bug fixes, bleh...)

V0.1
?  got back to 0.1 Version cause of complete recoding (know using C instead of delphi)
