Index of /xtras/shell_xtra/win
Name Last modified Size Description
![[PARENTDIR]](/icons/back.gif)
Parent Directory -
![[DIR]](/icons/folder.gif)
_old/ 2016-06-29 04:27 -
applications/ 2014-07-17 23:16 -
demos/ 2018-07-14 10:48 -
goodies/ 2010-02-19 18:54 -
![[TXT]](/icons/text.gif)
readme.txt 2016-06-29 04:27 14K
![[ ]](/icons/compressed.gif)
shell_xtra_v1.11-instance.zip 2016-06-29 04:26 1.6M
-- xtra Shell
-- Shell Xtra v1.11-instance (c) 2016 Valentin Schmidt
***************************************************************
INTERFACE (* = optional parameters, can be omitted)
***************************************************************
new object me
shell_cmd object me, any command, *props
shell_exec object me, string file, *props
shell_execex object me, string file, *props
shell_cmd_thread object me, any command, *props
shell_cmd_thread_input object me, any command
shell_cmd_thread_stop object me
-- UTILITIES
shell_getCurrentDir object me
shell_setCurrentDir object me, string directory
shell_getLongPathName object me, string path
-- BINARY STRING/BYTEARRAY CONVERSION (D11.5+ only)
shell_BinaryStringToByteArray object me, string binary_string
shell_ByteArrayToBinaryString object me, any bytearray, *offset, *size
***************************************************************
FUNCTIONS IN DETAIL
***************************************************************
---------------------------------------------------------------
xtraInstance.shell_cmd (any command, *props)
---------------------------------------------------------------
Description:
============
Executes a commandline programm or DOS command and returns the result.
Parameters:
===========
- command (required): command as string or bytearray
- props (optional): property list, were the following properties are understood:
"eol"
ignored when not #string, max. length = 255 chars
If specfied (and #string), all line endings (CRLF or CR or LF) will be replaced with string
line_ending. Reasonable values are e.g. RETURN or EMPTY.
"timeout"
integer, default=10, pass 0 for no timeout
Can be used to specify the timeout in seconds after which the process is automatically killed
and the function returns. (default timeout: 10 sec)
"return_bytearray"
bool, default=false
If true, the result is returned as bytearray (therefor only makes sense in Director 11.5 and newer)
"return_list"
bool, default=false, ignored if return_bytearray=true
Can be used to specify that the result is returned as lingo list of lines (handles pc, mac and
unix line endings).
"use_cmd"
bool, default=true, ignored if not #integer
Specifyies if the command is send to the system's command interpreter (cmd.exe for Win2k/WinXP,
command.com for Win 9x) (if use_cmd=true or omitted or not #integer) or if it's executed directly
(if use_cmd=false). Of course direct execution is only possible for commandline programms, not
for DOS commands.
"cb_stdout"
symbol, ignored if not #symbol
Specifies a callback handler (either in global scope or in the scope of object "cb_target", see below)
that is automatically called whenever some data is available at STDOUT.
The new chunk of data is passed as parameter to the this handler.
"cb_stderr"
symbol, ignored if not #symbol
Specifies a callback handler (either in global scope or in the scope of object "cb_target", see below)
that is automatically called whenever some data is available at STDERR.
The new chunk of data is passed as parameter to the this handler.
Notice:
These callbacks can be usefull e.g. for programms that give intermediary feedback (progress status, error feedback etc.)
during their execution (see use of curl in demo.dir).
"cb_target"
object (e.g. script or script instance or _movie...) that is used as callback target (default: _movie)
"buffer_size" -- NEW
integer, default=524288 (512 KB), ignored if not #integer
Specifies the size (number of bytes) of the buffer that holds the STDOUT which is returned to Director.
Returns:
========
#string or #bytearray or #list
Error Handling:
===============
Errors that occur while a command is executed usually give error information on STDERR. This info can be studied
by using a STDERR callback handler (see "cb_stderr" above) or by appending " 2>&1" to the command, which redirects
STDERR info to STDOUT so it will be added to the string returned by shell_cmd.
But if shell_cmd failes completely, e.g. because the specified command/tool wasn't found at all or for other reasons,
a new property "error" is appended to the proplist parameter (in case a proplist was specified) that contains an
error info string:
Example:
props = ["use_cmd":0]
xtraInstance.shell_cmd("foobar", props)
put props["error"]
-- "CreateProcess failed"
Example usage:
==============
res = xtraInstance.shell_cmd("dir /b", ["eol":RETURN])
res = xtraInstance.shell_cmd("del /S /Q tmp\*.*")
res = xtraInstance.shell_cmd("foo.bat myParam)
res = xtraInstance.shell_cmd("echo %ProgramFiles%", ["eol":EMPTY])
res = xtraInstance.shell_cmd("echo %NUMBER_OF_PROCESSORS%", ["eol":EMPTY])
tFolders = xtraInstance.shell_cmd("dir ""E&the moviepath"E&" /b /ad", ["return_list":1])
tFiles = xtraInstance.shell_cmd("dir ""E&the moviepath"E&" /b /a-d", ["return_list":1])
-- fetch a page with curl
res = xtraInstance.shell_cmd("curl -v http://macromedia.com/", ["timeout":20, "cb_stderr":#_stderr])
-- list files in rar archive
res = xtraInstance.shell_cmd("rar l files.rar", ["eol":RETURN])
-- fetch a page with curl, clean the result with tidy and return the cleaned html code to director
res = xtraInstance.shell_cmd("curl -v http://macromedia.com/ 2>nul | tidy -c -q", ["timeout":20, "cb_stdout":#_stdout])
-- convert html-representation of a text member to XHTML
xml = xtraInstance.shell_cmd("echo ""E&str_replace(chr(13)&chr(10),"",member(13).html) "E& "| tidy -c -asxhtml")
-- convert wav to mp3 with lame.exe (catch progress information with _stderr callback)
xtraInstance.shell_cmd("lame -b 160 test.wav test.mp3")
-- schedule a new task
ret = xtraInstance.shell_cmd("schtasks /create /tn MyApp /tr c:\myapp.exe /sc daily /mo 2 /st 13:00:00 /sd 6/30/2004")
-- start the local Apache Webserver as service
ret = xtraInstance.shell_cmd("sc start Apache")
-- execute php code with php interpreter (needs php.exe (cli) and php4ts.dll)
ret = xtraInstance.shell_cmd("php -r phpinfo();")
-- execute python code with python interpreter (needs python.exe, python23.dll and Lib)
ret = xtraInstance.shell_cmd("python -c " "E& "import sys; print sys.path" "E, ["eol":RETURN])
---------------------------------------------------------------
xtraInstance.shell_exec (string file, *props)
---------------------------------------------------------------
Description:
============
Wrapper for the Win API function 'ShellExecute', for details see
http://msdn.microsoft.com/en-us/library/windows/desktop/bb762153%28v=vs.85%29.aspx
Parameters:
===========
- file (required): file to be executed as string
- props (optional): property list, were the following properties are understood:
"operation"
ignored when not #string, default="open"
Specifies the action to be performed. Commonly used values are "edit", "explore", "find", "open", "print".
"parameters"
ignored when not #string, max. length = 260 chars
Specifies the parameters to be passed to the application.
"directory"
ignored when not #string, max. length = 260 chars, default = current working directory.
Specifies the default (working) directory for the action.
"show_cmd"
flags that specify how an application is to be displayed, default = SW_SHOWNORMAL = 1
Other example values are:
SW_HIDE = 0
SW_SHOWNORMAL = 1
SW_SHOWMINIMIZED = 2
SW_SHOWMAXIMIZED = 3
SW_SHOWNOACTIVATE = 4
SW_SHOW = 5
SW_MINIMIZE = 6
SW_SHOWMINNOACTIVE = 7
SW_SHOWNA = 8
SW_RESTORE = 9
SW_SHOWDEFAULT = 10
"hwnd"
ignored when not #integer, default = 0
A handle to the parent window used for displaying a UI or error messages. This value can be 0 if the operation is
not associated with a window.
---------------------------------------------------------------
xtraInstance.shell_execex (string file, *props)
---------------------------------------------------------------
Description:
============
Wrapper for the Win API function 'ShellExecuteEx', for details see
https://msdn.microsoft.com/en-us/library/windows/desktop/bb762154(v=vs.85).aspx
Parameters:
===========
- file (required): file to be executed as string
- props (optional): property list, were the following properties are understood:
"operation"
ignored when not #string, default="open"
Specifies the action to be performed. Commonly used values are "edit", "explore", "find", "open", "print", "runas".
"parameters"
ignored when not #string, max. length = 260 chars
Specifies the parameters to be passed to the application.
"directory"
ignored when not #string, max. length = 260 chars, default = current working directory.
Specifies the default (working) directory for the action.
"show_cmd"
flags that specify how an application is to be displayed, default = SW_SHOWNORMAL = 1
Other example values are:
SW_HIDE = 0
SW_SHOWNORMAL = 1
SW_SHOWMINIMIZED = 2
SW_SHOWMAXIMIZED = 3
SW_SHOWNOACTIVATE = 4
SW_SHOW = 5
SW_MINIMIZE = 6
SW_SHOWMINNOACTIVE = 7
SW_SHOWNA = 8
SW_RESTORE = 9
SW_SHOWDEFAULT = 10
"hwnd"
ignored when not #integer, default = 0
A handle to the parent window used for displaying a UI or error messages. This value can be 0 if the operation is
not associated with a window.
"wait"
ignored when not #integer, default = 0
if TRUE, the function waits for execution to be terminated, and then returns the exitCode (integer).
---------------------------------------------------------------
xtraInstance.shell_cmd_thread (any command, *props)
---------------------------------------------------------------
Description:
============
Like shell_cmd(), but as an asynchronous call, the lingo interpreter continues immediately with
the next line of lingo. The method doesn't return anything (VOID), to retrieve the stdout data,
you have to specify a lingo callback handler (as symbol, e.g. props["cb_stdout"] = #foo).
Parameters:
===========
- command (required): command as string or bytearray
- props (optional): property list, were the following properties are understood:
"eol"
ignored when not #string, max. length = 255 chars
If specfied (and #string), all line endings (CRLF or CR or LF) will be replaced with string
line_ending. Reasonable values are e.g. RETURN or EMPTY.
"timeout"
integer, default=10, pass 0 for no timeout
Can be used to specify the timeout in seconds after which the process is automatically killed
and the function returns. (default timeout: 10 sec)
"return_bytearray"
bool, default=false
If true, the result is returned as bytearray (therefor only makes sense in Director 11.5 and newer)
"use_cmd"
bool, default=true, ignored when not #integer
Specifyies if the command is send to the system's command interpreter (cmd.exe for Win2k/WinXP,
command.com for Win 9x) (if use_cmd=true or omitted or not #integer) or if it's executed directly
(if use_cmd=false). Of course direct execution is only possible for commandline programms, not
for DOS commands.
"cb_complete"
symbol, ignored when not #symbol
Specifies a callback handler (either in global scope or in the scope of object "cb_target", see below)
that is automatically called when the process is finished (or aborted because a timeout occured or it was
explicitly stopped with shell_cmd_thread_stop()).
"cb_stdout"
symbol, ignored when not #symbol
Specifies a callback handler (either in global scope or in the scope of object "cb_target", see below)
that is automatically called whenever some data is available at STDOUT.
The new chunk of data is passed as parameter to the this handler.
"cb_target"
object (e.g. script or script instance or _movie...) that is used as callback target (default: _movie)
"buffer_size" -- NEW
integer, default=524288 (512 KB), ignored if not #integer
Specifies the size (number of bytes) of the buffer that holds STDOUT data which is passed to the
cb_stdout callback function.
Returns:
========
void
Example usage:
==============
xtraInstance.shell_cmd_thread("ping 127.0.0.1", ["timeout":10, "cb_stdout":#put])
---------------------------------------------------------------
xtraInstance.shell_cmd_thread_input (any command)
---------------------------------------------------------------
Description:
============
Allows to send interactive input to the thread that was previously created with shell_cmd_thread().
Parameters:
===========
- command (required): command as string or bytearray
Returns:
========
void
Example usage:
==============
xtraInstance.shell_cmd_thread_input("Y")
---------------------------------------------------------------
xtraInstance.shell_cmd_thread_stop ()
---------------------------------------------------------------
Description:
============
Forces a thread that was previously created with shell_cmd_thread() to stop.
Returns:
========
void
Example usage:
==============
xtraInstance.shell_cmd_thread_stop ()
---------------------------------------------------------------
xtraInstance.shell_setCurrentDir (string directory)
---------------------------------------------------------------
Description:
============
Sets the current directory. If directory is an empty string, current directory will be set to the
directory in which the xtra file shell.x32 resides. This is useful for putting commandline tools
in the xtras folder. Or even better: you can rename your tools from *.exe to *.x32, and embed
them into your projector just like a real xtra! At runtime they will be extracted to the same
temporary folder as shell.x32, and after using shell_setCurrentDir("") you can call them just
by their file name!)
Parameters:
===========
string directory (required)
Returns:
========
void
Example usage:
==============
xtraInstance.shell_setCurrentDir(_movie.path)
xtraInstance.shell_setCurrentDir("")