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
|
<?xml version="1.0" encoding="UTF-8"?>
<fpdoc-descriptions>
<package name="lcl">
<!--
====================================================================
AsyncProcess
====================================================================
-->
<module name="AsyncProcess">
<short>
Implements a process with asynchronous event notifications.
</short>
<descr>
<p>
<file>asyncprocess.pp</file> implements a process with asynchronous event notifications for data availability and process termination. The following components are added to the Lazarus IDE component palette:
</p>
<p>
<b>System</b> Tab
</p>
<ul>
<li>TAsyncProcess</li>
</ul>
</descr>
<!-- unresolved references -->
<element name="Classes"/>
<element name="Process"/>
<element name="FileUtil"/>
<element name="UTF8Process"/>
<element name="InterfaceBase"/>
<element name="LCLIntf"/>
<element name="TAsyncProcess">
<short>
Implements a process with asynchronous notifications for data and termination.
</short>
<descr>
<p>
<var>TAsyncProcess</var> is a <var>TProcessUTF8</var> descendant which implements support for asynchronous notifications when data is available for the process. Internally, TAsyncProcess uses pipe and process handlers to detect when data is written to the <var>Output</var> handle, and when the process is terminated. TAsyncProcess provides <var>OnReadData</var> and <var>OnTerminate</var> event handlers signalled for the corresponding asynchronous notifications.
</p>
</descr>
<seealso>
<link id="TAsyncProcess.OnReadData"/>
<link id="TAsyncProcess.OnTerminate"/>
<link id="#lazutils.utf8process.TProcessUTF8">TProcessUTF8</link>
<link id="#fcl.process.TProcess.Output">TProcess.Output</link>
</seealso>
</element>
<element name="TAsyncProcess.FPipeHandler"/>
<element name="TAsyncProcess.FProcessHandler"/>
<element name="TAsyncProcess.FOnReadData"/>
<element name="TAsyncProcess.FOnTerminate"/>
<element name="TAsyncProcess.GetNumBytesAvailable">
<short>
Gets the value for the NumBytesAvailable property.
</short>
<descr>
<p>
<var>GetNumBytesAvailable</var> is a <var>dword</var> function used to get the value for the <var>NumBytesAvailable</var> property. The return value contains the value from <var>Output.NumBytesAvailable</var>, or 0 (zero) when <var>Options</var> does not include the value <var>poUsePipes</var>.
</p>
<p>
Use <var>NumBytesAvailable</var> to access the value for the property.
</p>
<p>
Use <var>Options</var> to specify the process options enabled for the class instance.
</p>
</descr>
<seealso>
<link id="TAsyncProcess.NumBytesAvailable"/>
<link id="TAsyncProcess.GetNumBytesAvailable"/>
<link id="#fcl.process.TProcess.Options">TProcess.Options</link>
</seealso>
</element>
<element name="TAsyncProcess.GetNumBytesAvailable.Result">
<short>Value for the property.</short>
</element>
<element name="TAsyncProcess.HandlePipeInput">
<short>
Implements asynchronous notifications during execution of the process.
</short>
<descr>
<p>
<var>HandlePipeInput</var> is a procedure which implements support for asynchronous notifications which occur during execution of the process. HandlePipeInput is assigned using <var>AddPipeEventHandler</var> when <var>Execute</var> is called.
</p>
<p>
HandlePipeInput examines values in <var>AReasons</var> to determine the action for the notification. When AReasons includes the value <var>prBroken</var>, the pipe has been closed and <var>UnhookPipeHandle</var> is called. When <var>prDataAvailable</var> is included in AReasons, the <var>OnReadData</var> event handler is signalled (when assigned).
</p>
<p>
Use <var>OnReadData</var> to respond to arrival of data on the handle for the process. Use <var>NumBytesAvailable</var> is determine the number of bytes available.
</p>
</descr>
<seealso>
<link id="TAsyncProcess.OnReadData"/>
<link id="TAsyncProcess.NumBytesAvailable"/>
</seealso>
</element>
<element name="TAsyncProcess.HandlePipeInput.AData">
<short>Data available on the input handle.</short>
</element>
<element name="TAsyncProcess.HandlePipeInput.AReasons">
<short>Reason the data was written for the handler.</short>
</element>
<element name="TAsyncProcess.HandleProcessTermination">
<short>
Performs actions needed when the process is terminated.
</short>
<descr>
<p>
<var>HandleProcessTermination</var> is a procedure which performs actions needed when the process is terminated. HandleProcessTermination is assigned using <var>AddProcessEventHandler</var> when <var>Execute</var> is called.
</p>
<p>
HandleProcessTermination calls <var>UnhookProcessHandle</var> and <var>UnhookPipeHandle</var> to release the handlers in the class instance. HandleProcessTermination signals the <var>OnTerminate</var> event handler when it has been assigned.
</p>
</descr>
<seealso>
<link id="TAsyncProcess.Execute"/>
<link id="TAsyncProcess.UnhookProcessHandle"/>
<link id="TAsyncProcess.UnhookPipeHandle"/>
<link id="TAsyncProcess.OnTerminate"/>
</seealso>
</element>
<element name="TAsyncProcess.HandleProcessTermination.AData">
<short>Data for the process notification.</short>
</element>
<element name="TAsyncProcess.HandleProcessTermination.AReason">
<short>Reason(s) for the process notification.</short>
</element>
<element name="TAsyncProcess.HandleProcessTermination.AInfo">
<short>Process exit code.</short>
</element>
<element name="TAsyncProcess.UnhookPipeHandle">
<short>
Removes the pipe handler assigned for the process.
</short>
<descr>
<p>
<var>UnhookPipeHandle</var> is a procedure used to remove the pipe handler assigned for the process in the <var>Execute</var> method. UnhookPipeHandle calls <var>RemovePipeEventHandler</var> when a pipe handler has been assigned.
</p>
<p>
<var>UnhookPipeHandle</var> is called from the <var>Destroy</var> method, and from <var>HandlePipeInput</var> when the <var>prBroken</var> flag is found in the parameters passed to the method.
</p>
</descr>
<seealso>
<link id="TAsyncProcess.Execute"/>
<link id="#lcl.interfacebase.TPipeReason">TPipeReason</link>
</seealso>
</element>
<element name="TAsyncProcess.UnhookProcessHandle">
<short>
Removes the process handler assigned for the process.
</short>
<descr>
<p>
<var>UnhookProcessHandle</var> is a procedure used to remove the process handler assigned for the process in the <var>Execute</var> method. UnhookProcessHandle calls <var>RemoveProcessEventHandler</var> when a process handler has been assigned.
</p>
<p>
<var>UnhookProcessHandle</var> is called from the <var>HandleProcessTermination</var> and <var>Destroy</var> methods.
</p>
</descr>
<seealso>
<link id="TAsyncProcess.Execute"/>
<link id="TAsyncProcess.HandleProcessTermination"/>
<link id="TAsyncProcess.Destroy"/>
</seealso>
</element>
<element name="TAsyncProcess.Execute">
<short>
Executes the process.
</short>
<descr>
<p>
<var>Execute</var> is an overridden procedure used to execute the process. Execute calls the inherited Execute method on entry.
</p>
<p>
Execute uses values in <var>Options</var> to determine if a process or a pipe handler is needed for the class instance. When Options includes the value <var>poUsePipes</var>, <var>AddPipeEventHandler</var> is called using <var>HandlePipeInput</var> as the pipe handler routine. Set the values in Options prior to calling the Execute method.
</p>
<p>
Execute calls <var>AddProcessEventHandler</var> using <var>HandleProcessTermination</var> as the process handler routine.
</p>
</descr>
<seealso>
<link id="TAsyncProcess.HandlePipeInput"/>
<link id="TAsyncProcess.HandleProcessTermination"/>
<link id="#fcl.process.TProcess.Options">TProcess.Options</link>
</seealso>
</element>
<element name="TAsyncProcess.Destroy">
<short>
Destructor for the class instance.
</short>
<descr>
<p>
<var>Destroy</var> is the overridden destructor for the class instance. Destroy calls <var>UnhookProcessHandle</var> and <var>UnhookPipeHandle</var> to remove the handler(s) for the class instance. Destroy calls the inherited method to free resources allocated in the class instance and perform free notifications.
</p>
</descr>
<seealso>
<link id="TAsyncProcess.UnhookProcessHandle"/>
<link id="TAsyncProcess.UnhookPipeHandle"/>
<link id="#fcl.process.TProcess.Destroy">TProcess.Destroy</link>
</seealso>
</element>
<element name="TAsyncProcess.NumBytesAvailable">
<short>
Number of output bytes available from the process.
</short>
<descr>
<p>
<var>NumBytesAvailable</var> is a read-only <var>dword</var> property that indicates the number of bytes available on the <var>Output</var> handle for the process. <var>GetNumBytesAvailable</var> is the read access specifier for the property value. NumBytesAvailable contains the value in Output.NumBytesAvailable, or 0 (zero) when <var>Options</var> does not contain the value <var>poUsePipes</var>.
</p>
<p>
Set the values for the <var>Options</var> property prior to calling <var>Execute</var>.
</p>
<p>
Use <var>OnReadData</var> to respond to the process notification signalled when data is available.
</p>
</descr>
<seealso>
<link id="TAsyncProcess.Execute"/>
<link id="TAsyncProcess.OnReadData"/>
<link id="#fcl.process.TProcess.Options">TProcess.Options</link>
<link id="#fcl.process.TProcess.Output">TProcess.Output</link>
</seealso>
</element>
<element name="TAsyncProcess.OnReadData">
<short>
Event handler signalled when output data is available for the process.
</short>
<descr>
<p>
<var>OnReadData</var> is a <var>TNotifyEvent</var> property that implements the event handler signalled when data is available for the process. Applications should assign a procedure to the event handler that responds to the pipe notification. The procedure must handle all data available on the <var>Output</var> handle up to the number of bytes in <var>NumBytesAvailable</var>. All available data must be handled, or the procedure will be called repeatedly until no more data is available.
</p>
<p>
OnReadData is signalled (when assigned) from the <var>HandlePipeInput</var> method when the <var>prDataAvailable</var> flag is found in the parameters passed to the method.
</p>
</descr>
<seealso>
<link id="TAsyncProcess.NumBytesAvailable"/>
<link id="#lcl.interfacebase.TPipeReason">TPipeReason</link>
<link id="#fcl.process.TProcess.Output">TProcess.Output</link>
<link id="#rtl.classes.TNotifyEvent">TNotifyEvent</link>
</seealso>
</element>
<element name="TAsyncProcess.OnTerminate">
<short>
Event handler signalled when the process is terminated.
</short>
<descr>
<p>
<var>OnTerminate</var> is a <var>TNotifyEvent</var> property that implements the event handler signalled when the process is terminated. Applications can assign a procedure to the event handler to perform actions needed when the process is terminated.
</p>
<p>
OnTerminate is signalled (when assigned) from the <var>HandleProcessTermination</var> method, and occurs after the process and pipe handlers have been unhooked in the class instance.
</p>
</descr>
<seealso>
<link id="TAsyncProcess.HandleProcessTermination"/>
<link id="#rtl.classes.TNotifyEvent">TNotifyEvent</link>
</seealso>
</element>
<element name="Register">
<short>Registers components for use in the Lazarus IDE.</short>
<descr>
<p>
<var>Register</var> is the procedure used to register components for use in the Lazarus IDE.
The following components are added to the Lazarus IDE component palette:
</p>
<p>
<b>System</b> Tab
</p>
<ul>
<li>TAsyncProcess</li>
</ul>
</descr>
<seealso/>
</element>
</module>
<!-- AsyncProcess -->
</package>
</fpdoc-descriptions>
|
