1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
|
This file describes the TProcess object.
Important remark:
As of version 2.5.1 (April 2011) the CommandLine and ApplicationName
properties are deprecated in favour of properties Executable and Parameters.
If CommandLine or ApplicationName is set, it will automatically be converted
to Executable and Parameters. If you wish to use the latter 2 properties,
simply clear the CommandLine and ApplicationName properties.
The TProcess object provides an easy way to start and manipulate
the running of other programs (processes) by your application.
On top of that, it allows you to redirect the program's input, output
and standard error to streams that are readable/writeable by your
program.
It is a descendent class of TComponent.
Furthermore it is written in such a way that it is easily extensible,
although most of the properties that a Process has, are accessible and
can be controlled with this object.
In what follows, is a description of the object's methods and properties.
The following two types control the creation of the TProcess Object.
See The constructor description for a description on what they do.
TProcessOptions = (poExecuteOnCreate,poRunSuspended,poUsePipes,poNewConsole,
poNoConsole,poStderrToOutPut,poWaitOnExit);
TCreateOptions = Set of TPRocessOptions;
Options control the behaviour of the object. It can be a set of the
following constants:
poExecuteOnCreate
If you include this option, the constructor will immediatly
call the Execute method, using default settings for all parameters.
This has the effect that the program is run at once.
poRunSuspended
If you include this option, the Execute method will start the
program in a suspended state, and the program will start running
only after you have called the Resume method.
poUsePipes
If you include this option, the Execute method will redirect the
standard input,output and error descriptors to 3 pipes, which you
can read from or write to.
(see Input,OutPut and Error properties)
It makes little sense to use ths for GUI applications (i.e. non-
console applications)
poNoConsole
If you include this option, the application will not display a
console, untill it explicitly needs one or requests one using the
AllocConsole method. This is very convenient in combination with the
poUsePipes option, allowing you to run an application without getting
the Console window, and being able to read it's output at once.
poStderrToOutPut
If This option is included, then the error desciptor is redirected to
the standard output director, i.e. all output goes to the standard
output.
poWaitOnExit
If you specify this option, then the Execute method will wait for the
executed program to finish, before returning.
This option will be ignored if you also specified ExecuteOnCreate and
CreateSuspended.
poNewConsole
If you specify this option, then the Execute method will open a console to
execute the program in. On windows, the standard console is used.
On Unix, the console program is detected as follows:
- XTermProgram is used if it is set.
- the terminals in TryTerminals are tested
- the 'DESKTOP_SESSION' variable is examined and the corresponding
terminal is tested for availability.
- A set of standard terminals is tested:
('x-terminal-emulator','xterm','aterm','wterm','rxvt')
if none of these can be detected, an exception is raised.
Destructor Destroy; virtual;
Destroys the TProcess Object. Be careful NOT to close a TProcess
object when you use pipes, and the application is still running.
you may kill it.
Procedure Execute; virtual;
This actually runs the application. It will return immediatly, unless
you specified the poWaitOnExit option when creating the object.
Function Resume : Integer; virtual;
Resume lowers the suspend count of the application.
it returns the new suspend count of the application. As long as the
suspend count is larger than 0, the application will not run.
If the suspend count reaches 0, the application will continue
running.
Function Suspend : Integer; virtual;
Increases the suspend count of the application, and returns the
new suspend count of the application.
Function Terminate (AExitCode : Integer): Boolean; virtual;
Terminate terminates the main thread of the application, giving it
exitcode 'AExitCode'
It returns True on succes, False on failure.
Function WaitOnExit : Boolean;
This function returns true if the wait for the process exit was succesful,
false if some error occurded. It returns immediatly if the application is
not running, and waits for the application to finish if it was still running.
Property ApplicationName : String;
Sets the name of the application.
Property CommandLine : String; (Deprecated)
contains the commandline of the application. method of TProcess.
If Set, it overrides the Executable and Parameters properties
Property Executable : String;
The binary program to be executed. It will be searched in the PATH.
Property Parameters : TStrings
The command-line parameters to be passed to Executable. One parameter per
line must be specified. If 2 or more words, separated by a space, are detected
in an argument, they will be treated as 1 argument and quoted if the OS
requires it.
Property ConsoleTitle : String;
For console applications only :
Sets the title that appears in the title bar of the Console window.
Property CreateOptions : TCreateOptions;
Read-Only
Contains the options as set by the Create method of TProcess.
Property CreationFlags : Cardinal;
This contains the creation flags that are passed to the CreateProcess
call. These flags are modified by the Execute call to reflect any
settings tat you may have made.
Property CurrentDirectory : String;
When set, the process wil start in the directory that you have set
for it.
Property DeskTop : String;
NT only:
Contains the name of the desktop or window station that the process
will be run on. See STARTUPINFO in the win32 programmers manual.
Property Environment : Pointer;
A pointer to a null-terminated list of environment variable pointers.
Each pair is of the form 'Name=Value'.
If this is nil, the environment of your application is used.
Property ExitStatus : Integer;
Read-Only
This returns the exit status of the application, or STILL_ACTIVE
(defined in Windows.pas) if the application is still running.
Property FillAttribute : Integer;
For console processes only.
Sets the fill color for the console window.
Property Handle : THandle;
Read-Only;
Returns the handle of the process, which can be used to pass on to
calls that require a handle of a process.
Onl valid if the process is running.
Property Input : TOutPutPipeStream;
Read-Only
Returns the Input handle of the process.
Anything you write to this stream, will appear on the applications
input file descriptor.
Only valid if you used poUsePipes when you created the TProcess
object.
Property InheritHandles : LongBool;
If you set this to true, each inheritable handle of your application
is inherited by the new application.
Property OutPut : TInputPipeStream;
Read-Only
Returns the Output handle of the process. Anything the process writes
to its standard output can be read from this stream.
Only valid if you used poUsePipes when you created the TProcess
object.
Property ProcessAttributes : TSecurityAttributes;
Property ProcessInformation : TProcessInformation;
Read-Only
Gives access to the ProcessInformation returned by Windows
upon executing the program. This contains
hProcess : Process Handle (See Handle property)
hThread : Process' main thread handle (See ThreadHandle property)
dwProcessId : Process ID. (as seen in the task manager)
dwThreadId : Process' main thread ID
Property Running : Boolean;
Read-Only
Retruns True if the application is still running, False otherwise.
If the application is suspended or not doesn't affect the result.
Property ShowWindow : Word;
You can set the applications ShowWindow attribute here.
Property StartupInfo : TStartupInfo;
Read-Only
Gives access to the TStartupInfo that will be passed to the
application in the CreateProcess Call. You can manipulate its various
members through the properties of the TProcess object.
Property StdErr : TinputPipeStream;
Read-Only
Returns the Output handle of the process. Anything the process writes
to its error output can be read from this stream.
Only valid if you used poUsePipes when you created the TProcess
object.
If you specified poStderrToOutput then this is the same as the
'Output' stream.
Property ThreadAttributes : TSecurityAttributes;
Contains the security attributes that will be passed to the process'
main thread. By default, no security attributes are passed.
Property ThreadHandle : THandle;
Read-Only
Returns the Handle of the process' main thread.
Property WindowColumns : Integer;
For console applications:
This will set the number of screen columns that the console window
will have.
If you don't set this property nor the WindowRows property, Windows will
choose default values.
You can only set this PRIOR to calling the execute method, after
the application was executed, or while it is running, the setting
will be ignored until you run it again.
Property WindowHeight : Integer;
Set the height of the application's main window.
If you don't specify this, nor WindowWidth, Windows will choose
the height and Width of the applications window.
You can only set this PRIOR to calling the execute method, after
the application was executed, or while it is running, the setting
will be ignored until you run it again.
Property WindowLeft : Integer;
Set the applications main window position, in pixels from the left
side of the screen.
If you don't specify this, nor WindowTop, Windows will choose
the Left and Top of the applications window.
You can only set this PRIOR to calling the execute method, after
the application was executed, or while it is running, the setting
will be ignored until you run it again.
Property WindowRows : Integer;
For console applications:
This will set the number of screen rows (lines) that the console window
will have.
If you don't set this property nor the WindowColumns property, Windows will
choose default values.
You can only set this PRIOR to calling the execute method, after
the application was executed, or while it is running, the setting
will be ignored until you run it again.
Property WindowTop : Integer;
Set the applications main window position, in pixels from the Top
side of the screen.
If you don't specify this, nor WindowLeft, Windows will choose
the Left and Top of the applications window.
You can only set this PRIOR to calling the execute method, after
the application was executed, or while it is running, the setting
will be ignored until you run it again.
Property WindowWidth : Integer;
Set the Width of the application's main window.
If you don't specify this, nor WindowWidth, Windows will choose
the height and Width of the applications window.
You can only set this PRIOR to calling the execute method, after
the application was executed, or while it is running, the setting
will be ignored until you run it again.
Property WindowRect : Trect;
This sets the bounding rectangle of the application's main window.
It allows to set the WindowTop, WindowLeft, WindowHeight, WindowWidth
properties in 1 call.
|