botsense  3.2.0
RoadNarrows Client-Server Proxied Services Framework
BotSenseServer.py
Go to the documentation of this file.
1 ## \package BotSense.BotSenseServer
2 #
3 # \file
4 #
5 # \brief \h_botsense client - server connection and request functions.
6 #
7 # \pkgsynopsis
8 # \h_bs_plain Python Interface
9 #
10 # \pkgcomponent{Module}
11 # \h_bs_plain.BotSenseServer
12 #
13 # \pkgfile{BotSense/BotSenseServer.py}
14 #
15 # \sa
16 # \htmlonly
17 # <a href="../pydoc/BotSense.BotSenseServer.html">PyDoc Generated Documentation</a>
18 # \endhtmlonly
19 #
20 # \author Robin Knight (robin.knight@roadnarrows.com)
21 #
22 # \license{MIT}
23 #
24 # \copyright
25 # \h_copy 2010-2017. RoadNarrows LLC.\n
26 # http://www.roadnarrows.com\n
27 # All Rights Reserved
28 #
29 # \EulaBegin
30 # Permission is hereby granted, without written agreement and without
31 # license or royalty fees, to use, copy, modify, and distribute this
32 # software and its documentation for any purpose, provided that
33 # (1) The above copyright notice and the following two paragraphs
34 # appear in all copies of the source code and (2) redistributions
35 # including binaries reproduces these notices in the supporting
36 # documentation. Substantial modifications to this software may be
37 # copyrighted by their authors and need not follow the licensing terms
38 # described here, provided that the new terms are clearly indicated in
39 # all files where they apply.
40 # \n\n
41 # IN NO EVENT SHALL THE AUTHOR, ROADNARROWS LLC, OR ANY MEMBERS/EMPLOYEES
42 # OF ROADNARROW LLC OR DISTRIBUTORS OF THIS SOFTWARE BE LIABLE TO ANY
43 # PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
44 # DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION,
45 # EVEN IF THE AUTHORS OR ANY OF THE ABOVE PARTIES HAVE BEEN ADVISED OF
46 # THE POSSIBILITY OF SUCH DAMAGE.
47 # \n\n
48 # THE AUTHOR AND ROADNARROWS LLC SPECIFICALLY DISCLAIM ANY WARRANTIES,
49 # INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
50 # FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN
51 # "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO
52 # PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
53 # \EulaEnd
54 
55 # //////////////////////////////////////////////////////////////////////////////
56 
57 import BotSenseCore as bsCore
58 import BotSenseError as bsError
59 import BotSenseTypes as bsTypes
60 
61 ## \brief Connect to the bsProxy server.
62 #
63 # Raises a BotSenseError exception on failure.
64 #
65 # \param client BotSenseTypes.BsClient instance.
66 # \param serverHostName Server's hostname in either a network or a
67 # dotted IP address.
68 # \param serverPort Server's listen port number.
69 #
70 def ServerConnect(client, serverHostName='localhost',
71  serverPort=bsCore.BSPROXY_LISTEN_PORT_DFT):
72  bsTypes.BsClient.ChkClient(client)
73  rc = bsCore.bsServerConnect(client.pClient, serverHostName, serverPort)
74  bsError.ChkReturnIsOk(rc,
75  "Client %s: Failed to connect to bsProxy server at %s:%d." % \
76  (client.AttrGetName(), serverHostName, serverPort))
77 
78 ## \brief Disconnect from the bsProxy server.
79 #
80 # Raises a BotSenseError exception on failure.
81 #
82 # \param client BotSenseTypes.BsClient instance.
83 #
84 def ServerDisconnect(client):
85  bsTypes.BsClient.ChkClient(client)
86  rc = bsCore.bsServerDisconnect(client.pClient)
87  bsError.ChkReturnIsOk(rc,
88  "Client %s: Failed to disconnect from server." % (client.AttrGetName()))
89 
90 ## \brief Proxy server request to get the bsProxy server's version string.
91 #
92 # Raises a BotSenseError exception on failure.
93 #
94 # \param client BotSenseTypes.BsClient instance.
95 #
96 # \return Version string response.
97 #
98 def ServerReqGetVersion(client):
99  verstr = '\x00' * 256
100  rc = bsCore.bsServerReqGetVersion(client.pClient, verstr, len(verstr))
101  bsError.ChkReturnIsOk(rc,
102  "Client %s: Server GetVersion request failed." % (client.AttrGetName()))
103  return verstr.rstrip('\x00')
104 
105 ## \brief Proxy server request to loopback the given message.
106 #
107 # Raises a BotSenseError exception on failure.
108 #
109 # \param client BotSenseTypes.BsClient instance.
110 # \param loopbackMsg Message string to loopback.
111 #
112 # \return Loopbacked message response.
113 #
114 def ServerReqLoopback(client, loopbackMsg):
115  bsTypes.BsClient.ChkClient(client)
116  txrxMsg = loopbackMsg
117  rc = bsCore.bsServerReqLoopback(client.pClient, txrxMsg)
118  bsError.ChkReturnIsOk(rc,
119  "Client %s: Server Loopback request failed." % (client.AttrGetName()))
120  return txrxMsg
121 
122 ## \brief Proxy server request to set the server's diagnostics logging level.
123 #
124 # Raises a BotSenseError exception on failure.
125 #
126 # \param client BotSenseTypes.BsClient instance.
127 # \param level Log level.
128 #
129 def ServerReqSetLogging(client, level):
130  bsTypes.BsClient.ChkClient(client)
131  rc = bsCore.bsServerReqSetLogging(client.pClient, level)
132  bsError.ChkReturnIsOk(rc,
133  "Client %s: Server SetLogging request failed." % (client.AttrGetName()))
134 
135 ## \brief Proxy server request to enable/disable message tracing on a virtual
136 # connection.
137 #
138 # Raises a BotSenseError exception on failure.
139 #
140 # \param client BotSenseTypes.BsClient instance.
141 # \param hndVConn Virtual connection handle.
142 # \param trace Enable(true) or disable(false) message tracing.
143 #
144 def ServerReqMsgTrace(client, hndVConn, trace):
145  bsTypes.BsClient.ChkClient(client)
146  if trace:
147  trace = True
148  else:
149  trace = False
150  rc = bsCore.bsServerReqMsgTrace(client.pClient, hndVConn, trace)
151  bsError.ChkReturnIsOk(rc,
152  "Client %s: Server MsgTrace request failed." % (client.AttrGetName()))
153 
154 ## \brief Proxy server request to establish a virtual connection to the device
155 # end point.
156 #
157 # The device is open if not already opened by another virtual connection.
158 # Otherwise it is attached to this vconn.
159 #
160 # The interface module is dynamically loaded into the server and provides
161 # the set of services for the client application communicating with the
162 # device.
163 #
164 # Raises a BotSenseError exception on failure.
165 #
166 # \param client BotSenseTypes.BsClient instance.
167 # \param devName Device path name string.
168 # \param modName Interface module path name string.
169 # \param argbuf Packed buffer of module-specific open parameters.
170 # \param appInfo Application-specific information and callbacks (optional).
171 # Set to None if no info. Set any member to None to ignore
172 # that value.
173 # \param trace Initial message tracing enable(true)/disable(false) state.
174 #
175 # \return New virtual connection handle.
176 #
177 def ServerReqOpenDev(client, devName, modName, argbuf, appInfo, trace=False):
178  bsTypes.BsClient.ChkClient(client)
179  if appInfo is not None:
180  bsError.ChkType(appInfo, bsTypes.BsClientAppInfo)
181  argByteBuf = bsTypes.ByteBuf.Clone(argbuf)
182  argByteBuf.copyToSwigObj(len(argByteBuf))
183  hndVConn = bsCore.bsServerReqOpenDev(client.pClient, devName, modName,
184  argByteBuf.getSwigObj(), len(argByteBuf), appInfo, trace)
185  bsError.ChkReturnIsNonNeg(hndVConn,
186  "Client %s: Server OpenDev request failed." % (client.AttrGetName()))
187  return hndVConn
188 
189 ## \brief Proxy server request to close a client's virtual connection.
190 #
191 # Raises a BotSenseError exception on failure.
192 #
193 # \param client BotSenseTypes.BsClient instance.
194 # \param hndVConn Virtual connection handle to close.
195 #
196 def ServerReqCloseDev(client, hndVConn):
197  bsTypes.BsClient.ChkClient(client)
198  rc = bsCore.bsServerReqCloseDev(client.pClient, hndVConn)
199  bsError.ChkReturnIsOk(rc,
200  "Client %s: Server CloseDev request failed." % (client.AttrGetName()))
201 
202 ## \brief Proxy server request to retrieve the server's list of virtual
203 # connection handles for this client.
204 #
205 # Raises a BotSenseError exception on failure.
206 #
207 # \param client BotSenseTypes.BsClient instance.
208 #
209 # \return List of handles.
210 #
211 def ServerReqGetVConnList(client):
212  bsTypes.BsClient.ChkClient(client)
213  vec = bsCore.BsVecHandles_T()
214  rc = bsCore.bsServerReqGetVConnList(client.pClient, vec)
215  bsError.ChkReturnIsOk(rc,
216  "Client %s: Server GetVConnList request failed." % (client.AttrGetName()))
217  listHnds = []
218  for i in xrange(vec.m_uCount):
219  listHnds += [bsCore.hndVConnArray_getitem(vec.m_vecHnd, i)]
220  return listHnds
221 
222 ## \brief Proxy server request to retrieve the servers's information for a
223 # given virtual connection.
224 #
225 # Raises a BotSenseError exception on failure.
226 #
227 # \param client BotSenseTypes.BsClient instance.
228 # \param hndVConn Virtual connection handle.
229 #
230 # \return Proxied device info.
231 #
232 def ServerReqGetVConnInfo(client, hndVConn):
233  bsTypes.BsClient.ChkClient(client)
234  info = bsTypes.BsVConnInfo()
235  rc = bsCore.bsServerReqGetVConnInfo(client.pClient, hndVConn, info)
236  bsError.ChkReturnIsOk(rc,
237  "Client %s: Server GetVConnInfo request failed." % (client.AttrGetName()))
238  return info