-
Notifications
You must be signed in to change notification settings - Fork 4
Expand file tree
/
Copy pathPshellControl.html
More file actions
377 lines (372 loc) · 31.4 KB
/
PshellControl.html
File metadata and controls
377 lines (372 loc) · 31.4 KB
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
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html><head><title>Python: module PshellControl</title>
<meta charset="utf-8">
</head><body bgcolor="#f0f0f8">
<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="heading">
<tr bgcolor="#7799ee">
<td valign=bottom> <br>
<font color="#ffffff" face="helvetica, arial"> <br><big><big><strong>PshellControl</strong></big></big></font></td
><td align=right valign=bottom
><font color="#ffffff" face="helvetica, arial"><a href=".">index</a><br><a href="file:/home/riovine/tools/pshell/python/src/PshellControl.py">/home/riovine/tools/pshell/python/src/PshellControl.py</a></font></td></tr></table>
<p><tt>A Python module to invoke pshell commands in another process<br>
<br>
This API provides the ability for a client program to invoke pshell commands<br>
that are registered in a remote program that is running a pshell UDP or UNIX<br>
server. The format of the command string that is sent to the pshell should<br>
be in the same usage format that the given command is expecting. This provides<br>
a very lightweight way to provide a control mechanism into a program that is<br>
running a PshellServer, this is analagous to a remote procedure call (RPC).<br>
<br>
This module provides the same functionality as the PshellControl.h API and<br>
the libpshell-control linkable 'C' library, but implemented as a Python<br>
module.<br>
<br>
A complete example of the usage of the API can be found in the included<br>
demo programs pshellControlDemo.py and pshellAggregatorDemo.py<br>
<br>
Functions:<br>
<br>
<a href="#-connectServer">connectServer</a>() -- connect to a remote pshell server<br>
<a href="#-disconnectServer">disconnectServer</a>() -- disconnect from a remote pshell server<br>
<a href="#-disconnectAllServers">disconnectAllServers</a>() -- disconnect from all connected remote pshell servers<br>
<a href="#-setDefaultTimeout">setDefaultTimeout</a>() -- set the default server response timeout<br>
<a href="#-extractCommands">extractCommands</a>() -- extract all commands from remote server<br>
<a href="#-addMulticast">addMulticast</a>() -- add a command keyword to a multicast group<br>
<a href="#-sendMulticast">sendMulticast</a>() -- send a command to a multicast group<br>
<a href="#-sendCommand1">sendCommand1</a>() -- send command to server using default timeout, no results extracted<br>
<a href="#-sendCommand2">sendCommand2</a>() -- send command to server using timeout override, no results extracted<br>
<a href="#-sendCommand3">sendCommand3</a>() -- send command to server using default timeout, results extracted<br>
<a href="#-sendCommand4">sendCommand4</a>() -- send command to server using timeout override, results extracted<br>
<a href="#-getResponseString">getResponseString</a>() -- return the human readable form of one of the command response return codes<br>
<a href="#-setLogLevel">setLogLevel</a>() -- set the internal log level for this module<br>
<a href="#-setLogFunction">setLogFunction</a>() -- register a user function to receive all logs<br>
<br>
Integer constants:<br>
<br>
Helpful items used for the server response timeout values<br>
<br>
NO_WAIT<br>
WAIT_FOREVER<br>
ONE_MSEC<br>
ONE_SEC<br>
ONE_MINUTE<br>
ONE_HOUR<br>
<br>
These are returned from the sendCommandN functions<br>
<br>
COMMAND_SUCCESS<br>
COMMAND_NOT_FOUND<br>
COMMAND_INVALID_ARG_COUNT<br>
SOCKET_SEND_FAILURE<br>
SOCKET_SELECT_FAILURE<br>
SOCKET_RECEIVE_FAILURE<br>
SOCKET_TIMEOUT<br>
SOCKET_NOT_CONNECTED<br>
<br>
Constants to let the host program set the internal debug log level,<br>
if the user of this API does not want to see any internal message<br>
printed out, set the debug log level to LOG_LEVEL_NONE, the default<br>
log level is LOG_LEVEL_ALL<br>
<br>
LOG_LEVEL_NONE<br>
LOG_LEVEL_ERROR<br>
LOG_LEVEL_WARNING<br>
LOG_LEVEL_INFO<br>
LOG_LEVEL_ALL<br>
LOG_LEVEL_DEFAULT<br>
<br>
String constants:<br>
<br>
This is used for the host when connecting to a server running at the<br>
loopback localhost address<br>
<br>
LOCALHOST<br>
<br>
Use this as the "port" identifier for the connectServer call when using<br>
a UNIX domain server<br>
<br>
UNIX<br>
<br>
Specifies if the addMulticast should add the given command to all specified<br>
multicast receivers or if all control destinations should receive the given<br>
multicast command<br>
<br>
MULTICAST_ALL</tt></p>
<p>
<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
<tr bgcolor="#aa55cc">
<td colspan=3 valign=bottom> <br>
<font color="#ffffff" face="helvetica, arial"><big><strong>Modules</strong></big></font></td></tr>
<tr><td bgcolor="#aa55cc"><tt> </tt></td><td> </td>
<td width="100%"><table width="100%" summary="list"><tr><td width="25%" valign=top><a href="fcntl.html">fcntl</a><br>
<a href="fnmatch.html">fnmatch</a><br>
<a href="os.html">os</a><br>
</td><td width="25%" valign=top><a href="random.html">random</a><br>
<a href="select.html">select</a><br>
<a href="socket.html">socket</a><br>
</td><td width="25%" valign=top><a href="struct.html">struct</a><br>
<a href="sys.html">sys</a><br>
<a href="time.html">time</a><br>
</td><td width="25%" valign=top></td></tr></table></td></tr></table><p>
<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
<tr bgcolor="#eeaa77">
<td colspan=3 valign=bottom> <br>
<font color="#ffffff" face="helvetica, arial"><big><strong>Functions</strong></big></font></td></tr>
<tr><td bgcolor="#eeaa77"><tt> </tt></td><td> </td>
<td width="100%"><dl><dt><a name="-addMulticast"><strong>addMulticast</strong></a>(command, controlList)</dt><dd><tt>This command will add a controlList of multicast receivers to a multicast<br>
group, multicast groups are based either on a specified command, or if the<br>
special argument PSHELL_MULTICAST_ALL is used, the given controlList will<br>
receive all multicast commands, the format of the controlList is a CSV formatted<br>
list of all the desired controlNames (as provided in the first argument of the<br>
PshellControl.connectServer command) that will receive this multicast command<br>
or if the PSHELL_MULTICAST_ALL is used then all control destinations will receive<br>
the given multicast command, see examples below<br>
<br>
ex 1: multicast command sent to receivers in CSV controlList<br>
<br>
PshellControl.<a href="#-addMulticast">addMulticast</a>("command", "control1,control2,control3")<br>
<br>
ex 2: all multicast commands sent to receivers in CSV controlList<br>
<br>
PshellControl.<a href="#-addMulticast">addMulticast</a>(PshellControl.MULTICAST_ALL, "control1,control2,control3")<br>
<br>
ex 3: multicast command sent to all receivers<br>
<br>
PshellControl.<a href="#-addMulticast">addMulticast</a>("command", PshellControl.MULTICAST_ALL)<br>
<br>
ex 4: all multicast commands sent to all receivers<br>
<br>
PshellControl.<a href="#-addMulticast">addMulticast</a>(PshellControl.MULTICAST_ALL, PshellControl.MULTICAST_ALL)<br>
<br>
Args:<br>
command (str) : The multicast command that will be distributed to the<br>
following controlList, if the special MULTICAST_ALL<br>
identifier is used, then the controlList will receive<br>
all multicast initiated commands<br>
controlList (str) : A CSV formatted list of all the desired controlNames<br>
(as provided in the first argument of the connectServer<br>
command) that will receive this multicast command, if<br>
the special MULTICAST_ALL identifier is used, then<br>
all control destinations will receive the command<br>
<br>
Returns:<br>
none</tt></dd></dl>
<dl><dt><a name="-connectServer"><strong>connectServer</strong></a>(controlName, remoteServer, port, defaultTimeout)</dt><dd><tt>Connect to a pshell server in another process, note that this does<br>
not do any handshaking to the remote pshell or maintain a connection<br>
state, it meerly sets the internal destination remote pshell server<br>
information to use when sending commands via the sendCommandN<br>
functions and sets up any resources necessary for the source socket,<br>
the timeout value is the number of milliseconds to wait for a response<br>
from the remote command in the sendCommandN functions, a timeout<br>
value of 0 will not wait for a response, in which case the function<br>
will return either SOCKET_NOT_CONNECTED, SOCKET_SEND_FAILURE, or<br>
COMMAND_SUCCESS, the timeout value entered in this function will<br>
be used as the default timeout for all calls to sendCommandN that<br>
do not provide an override timeout value, for a UDP server, the<br>
remoteServer must be either a valid hostname or IP address and a<br>
valid destination port must be provided, for a UNIX server, only<br>
a valid server name must be provided along with the identifier<br>
PshellControl.UNIX for the 'port' parameter<br>
<br>
Args:<br>
controlName (str) : The logical name of the control server<br>
remoteServer (str) : The server name (UNIX) or hostname/IP address (UDP) of the remote server<br>
port (str) : The UDP port of the remote server<br>
defaultTimeout (int) : The default timeout (in msec) for the remote server response<br>
<br>
Returns:<br>
bool: Indicates if the local source endpoint is successfully created</tt></dd></dl>
<dl><dt><a name="-disconnectAllServers"><strong>disconnectAllServers</strong></a>()</dt><dd><tt>Use this function to cleanup any resources for all connected servers, this<br>
function should be called upon program termination, either in a graceful<br>
termination or within an exception signal handler, it is especially important<br>
that this be called when a unix server is used since there are associated file<br>
handles that need to be cleaned up<br>
<br>
Args:<br>
none<br>
<br>
Returns:<br>
none</tt></dd></dl>
<dl><dt><a name="-disconnectServer"><strong>disconnectServer</strong></a>(controlName)</dt><dd><tt>Cleanup any resources associated with the server connection, including<br>
releasing any temp file handles, closing any local socket handles etc.<br>
<br>
Args:<br>
controlName (string) : The control name used in the ConnectServer call<br>
<br>
Returns:<br>
none</tt></dd></dl>
<dl><dt><a name="-extractCommands"><strong>extractCommands</strong></a>(controlName, includeName<font color="#909090">=True</font>)</dt><dd><tt>This function will extract all the commands of a remote pshell server and<br>
present them in a human readable form, this is useful when writing a multi<br>
server control aggregator, see the demo program pshellAggregatorDemo.py in<br>
the demo directory for examples<br>
<br>
Args:<br>
controlName (string) : The control name used in the ConnectServer call<br>
includeName (bool) : Include server name in banner<br>
<br>
Returns:<br>
str : The remote server's command list in human readable form</tt></dd></dl>
<dl><dt><a name="-getResponseString"><strong>getResponseString</strong></a>(retCode)</dt><dd><tt>Return the human readable form of one of the command response return codes<br>
<br>
Args:<br>
retCode (int) : One of the return codes from the above sendCommand<br>
functions<br>
<br>
Returns:<br>
str: The human readable results of the command response</tt></dd></dl>
<dl><dt><a name="-sendCommand1"><strong>sendCommand1</strong></a>(controlName, command)</dt><dd><tt>Send a command using the default timeout setup in the connectServer call,<br>
if the default timeout is 0, the server will not reply with a response and<br>
this function will not wait for one<br>
<br>
Args:<br>
controlName (string) : The control name used in the ConnectServer call<br>
command (str) : The command to send to the remote server<br>
<br>
Returns:<br>
int: Return code result of the command:<br>
COMMAND_SUCCESS<br>
COMMAND_NOT_FOUND<br>
COMMAND_INVALID_ARG_COUNT<br>
SOCKET_SEND_FAILURE<br>
SOCKET_SELECT_FAILURE<br>
SOCKET_RECEIVE_FAILURE<br>
SOCKET_TIMEOUT<br>
SOCKET_NOT_CONNECTED</tt></dd></dl>
<dl><dt><a name="-sendCommand2"><strong>sendCommand2</strong></a>(controlName, timeoutOverride, command)</dt><dd><tt>Send a command overriding the default timeout, if the override timeout is 0,<br>
the server will not reply with a response and this function will not wait for<br>
one<br>
<br>
Args:<br>
controlName (string) : The control name used in the ConnectServer call<br>
timeoutOverride (int) : The server timeout override (in msec) for this command<br>
command (str) : The command to send to the remote server<br>
<br>
Returns:<br>
int: Return code result of the command:<br>
COMMAND_SUCCESS<br>
COMMAND_NOT_FOUND<br>
COMMAND_INVALID_ARG_COUNT<br>
SOCKET_SEND_FAILURE<br>
SOCKET_SELECT_FAILURE<br>
SOCKET_RECEIVE_FAILURE<br>
SOCKET_TIMEOUT<br>
SOCKET_NOT_CONNECTED</tt></dd></dl>
<dl><dt><a name="-sendCommand3"><strong>sendCommand3</strong></a>(controlName, command)</dt><dd><tt>Send a command using the default timeout setup in the connectServer call and<br>
return any results received in the payload, if the default timeout is 0, the<br>
server will not reply with a response and this function will not wait for one,<br>
and no results will be extracted<br>
<br>
Args:<br>
controlName (string) : The control name used in the ConnectServer call<br>
command (str) : The command to send to the remote server<br>
<br>
Returns:<br>
str: The human readable results of the command response or NULL<br>
if no results or command failure<br>
int: Return code result of the command:<br>
COMMAND_SUCCESS<br>
COMMAND_NOT_FOUND<br>
COMMAND_INVALID_ARG_COUNT<br>
SOCKET_SEND_FAILURE<br>
SOCKET_SELECT_FAILURE<br>
SOCKET_RECEIVE_FAILURE<br>
SOCKET_TIMEOUT<br>
SOCKET_NOT_CONNECTED</tt></dd></dl>
<dl><dt><a name="-sendCommand4"><strong>sendCommand4</strong></a>(controlName, timeoutOverride, command)</dt><dd><tt>Send a command overriding the default timeout and return any results received<br>
in the payload, if the timeout override default timeout is 0, the server will<br>
not reply with a response and this function will not wait for one, and no<br>
results will be extracted<br>
<br>
Args:<br>
controlName (string) : The control name used in the ConnectServer call<br>
timeoutOverride (int) : The server timeout override (in msec) for this command<br>
command (str) : The command to send to the remote server<br>
<br>
Returns:<br>
str: The human readable results of the command response or NULL<br>
if no results or command failure<br>
int: Return code result of the command:<br>
COMMAND_SUCCESS<br>
COMMAND_NOT_FOUND<br>
COMMAND_INVALID_ARG_COUNT<br>
SOCKET_SEND_FAILURE<br>
SOCKET_SELECT_FAILURE<br>
SOCKET_RECEIVE_FAILURE<br>
SOCKET_TIMEOUT<br>
SOCKET_NOT_CONNECTED</tt></dd></dl>
<dl><dt><a name="-sendMulticast"><strong>sendMulticast</strong></a>(command)</dt><dd><tt>This command will send a given command to all the registered multicast<br>
receivers for this multicast group, multicast groups are based on the<br>
command's keyword, this function will issue the command as a best effort<br>
fire-and-forget command to each receiver in the multicast group, no<br>
results will be requested or expected, and no response will be requested<br>
or expected<br>
<br>
Args:<br>
command (str) : The command to send to the remote server<br>
<br>
Returns:<br>
none</tt></dd></dl>
<dl><dt><a name="-setDefaultTimeout"><strong>setDefaultTimeout</strong></a>(controlName, defaultTimeout)</dt><dd><tt>Set the default server response timeout that is used in the 'send' commands<br>
that don't take a timeout override<br>
<br>
Args:<br>
controlName (string) : The control name used in the ConnectServer call<br>
defaultTimeout (int) : The default timeout (in msec) for the remote server response<br>
<br>
Returns:<br>
none</tt></dd></dl>
<dl><dt><a name="-setLogFunction"><strong>setLogFunction</strong></a>(function)</dt><dd><tt>Provide a user callback function to send the logs to, this allows an<br>
application to get all the logs issued by this module to put in it's<br>
own logfile. If a log function is not set, all internal logs are just<br>
sent to the 'print' function.<br>
<br>
Args:<br>
function (ptr) : Log callback function<br>
<br>
Returns:<br>
None</tt></dd></dl>
<dl><dt><a name="-setLogLevel"><strong>setLogLevel</strong></a>(level)</dt><dd><tt>Set the internal log level, valid levels are:<br>
<br>
LOG_LEVEL_ERROR<br>
LOG_LEVEL_WARNING<br>
LOG_LEVEL_INFO<br>
LOG_LEVEL_ALL<br>
LOG_LEVEL_DEFAULT<br>
<br>
Where the default is LOG_LEVEL_ALL<br>
<br>
Args:<br>
level (int) : The desired log level to set<br>
<br>
Returns:<br>
None</tt></dd></dl>
</td></tr></table><p>
<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
<tr bgcolor="#55aa55">
<td colspan=3 valign=bottom> <br>
<font color="#ffffff" face="helvetica, arial"><big><strong>Data</strong></big></font></td></tr>
<tr><td bgcolor="#55aa55"><tt> </tt></td><td> </td>
<td width="100%"><strong>COMMAND_INVALID_ARG_COUNT</strong> = 2<br>
<strong>COMMAND_NOT_FOUND</strong> = 1<br>
<strong>COMMAND_SUCCESS</strong> = 0<br>
<strong>LOCALHOST</strong> = 'localhost'<br>
<strong>LOG_LEVEL_ALL</strong> = 3<br>
<strong>LOG_LEVEL_DEFAULT</strong> = 3<br>
<strong>LOG_LEVEL_ERROR</strong> = 1<br>
<strong>LOG_LEVEL_INFO</strong> = 3<br>
<strong>LOG_LEVEL_NONE</strong> = 0<br>
<strong>LOG_LEVEL_WARNING</strong> = 2<br>
<strong>MULTICAST_ALL</strong> = '__multicast_all__'<br>
<strong>NO_WAIT</strong> = 0<br>
<strong>ONE_HOUR</strong> = 3600000<br>
<strong>ONE_MINUTE</strong> = 60000<br>
<strong>ONE_MSEC</strong> = 1<br>
<strong>ONE_SEC</strong> = 1000<br>
<strong>SOCKET_NOT_CONNECTED</strong> = 7<br>
<strong>SOCKET_RECEIVE_FAILURE</strong> = 5<br>
<strong>SOCKET_SELECT_FAILURE</strong> = 4<br>
<strong>SOCKET_SEND_FAILURE</strong> = 3<br>
<strong>SOCKET_TIMEOUT</strong> = 6<br>
<strong>UNIX</strong> = 'unix'<br>
<strong>WAIT_FOREVER</strong> = -1</td></tr></table>
</body></html>