root / pykoticon / trunk / README @ 166

Revision 166, 7.0 kB (checked in by jerome, 18 years ago)

Fixed a typo and added something about the special variable name
'password', which is treated differently during input.

  • Property svn:keywords set to Id
Line 
1# $Id$
2
3PyKotIcon - Client side helper for PyKota and other applications
4
5(c) 2003, 2004, 2005, 2006 Jerome Alet <alet@librelogiciel.com>
6This program is free software; you can redistribute it and/or modify
7it under the terms of the GNU General Public License as published by
8the Free Software Foundation; either version 2 of the License, or
9(at your option) any later version.
10
11This program is distributed in the hope that it will be useful,
12but WITHOUT ANY WARRANTY; without even the implied warranty of
13MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14GNU General Public License for more details.
15
16You should have received a copy of the GNU General Public License
17along with this program; if not, write to the Free Software
18Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
19
20====================================================================
21
22PyKotIcon is a cross-platform client-side helper for PyKota.
23
24It is meant to be launched whenever the user logs in, and stay in
25the taskbar (depending on the client operating system) until the
26user closes his session.
27 
28Installation :
29
30  * GNU/Linux and similar :
31 
32    $ cd pykoticon
33    $ python setup.py install
34   
35    Then modify your .xsession file, or the appropriate file depending
36    on your desktop environment, to ensure that the pykoticon command
37    is launched in the background each time your X Window session
38    starts.
39   
40    You MUST pass the list of hostnames or IP addresses from which
41    PyKotIcon should accept incoming connexions on pykoticon's
42    command line. Connexions from localhost are always accepted.
43    If you use PyKotIcon with PyKota, you'll want to pass the
44    hostnames or IP addresses of ALL print servers on pykoticon's
45    command line.
46   
47    NB : `pykoticon --help` will give you hints about the expected
48    command line parameters.
49   
50  * MS Windows : 
51 
52    Download pykoticon-x.yy.zip from
53   
54        http://www.pykota.com/software/pykoticon/download/tarballs/
55       
56    Unzip it into a directory of its own. I usually unzip it into   
57    /var/lib/samba/netlogon/pykoticon/
58   
59    Modify the PYKOTICON.VBS file to include the list of authorized
60    print servers and change other parameters as needed, as explained
61    in the GNU/Linux section above.
62   
63    Ensure that PYKOTICON.VBS is executed each time an user logs
64    in. The easiest way to do this is in STARTUP.CMD :
65   
66      --- CUT ---
67      SET PATH=%PATH%;\\MYSERVER\NETLOGON\PYKOTICON\
68      \\MYSERVER\NETLOGON\PYKOTICON\PYKOTICON.VBS
69      --- CUT ---
70     
71    NB : if you launch PYKOTICON.EXE directly instead of from
72    PYKOTICON.VBS, a small but disturbing window may appear on
73    the screen.
74
75
76====================================================================
77
78
79Usage :
80
81  PyKotIcon is often used as a client side companion of the PyKota
82  print accounting solution, with PyKota's pknotify command line tool
83  acting as a PyKotIcon client. But in reality PyKotIcon is completely
84  independant of PyKota, and can be used from any application
85  which can do remote procedure calls over XML-RPC.
86 
87  PyKotIcon exposes 4 of its methods over XML-RPC, here they are :
88 
89    - nop :
90   
91      This methods does exactly nothing :)
92     
93      - Input : No argument.
94     
95      - Output : returns the True boolean value.
96     
97    - quitApplication : 
98   
99      This method causes the PyKotIcon application to exit.
100     
101      - Input : No argument.
102     
103      - Output : returns the True boolean value.
104         
105    - showDialog : 
106   
107      This methods displays an informational message, and returns
108      the choice the user made, if any.
109       
110      - Input :
111       
112        - message : a Binary XML-RPC object representing an UTF-8 encoded
113          character string which will be displayed to the end user.
114          This string can contain literal "\n" sequences which will
115          be automatically expanded into line breaks by PyKotIcon.
116         
117        - confirmation : a boolean value indicating if the user will 
118          be given the choice to valid or cancel (True), or only
119          to valid (False) the dialog box.
120           
121      - Output :     
122     
123        - the literal string "OK" if the user clicked on the OK button,
124          else the literal string "CANCEL". The latter is only possible
125          if the method was called with its second parameter set to
126          True.
127       
128    - askDatas :     
129   
130      This method can generate an input form and return what the user
131      entered in the different fields.
132     
133      - Input :
134     
135        - An array of labels, one label per input field in the
136          form to be created. Each label in the list is passed as
137          a Binary XML-RPC object representing an UTF-8 encoded
138          character string.
139         
140        - An array of variables names, one name per input field in
141          the form to be created. Each name in the list is passed
142          as an ASCII encoded character string.
143          IMPORTANT : if one of these names is 'password' then this
144          particular field's input box will be visually protected
145          with * in place of the characters typed during input.
146         
147        - An array of initial values, one possibly empty value per 
148          input field in the form to be created. Each initial value
149          in the list is passed as a Binary XML-RPC object representing
150          an UTF-8 encoded character string.
151     
152      - Output :
153     
154        - An associative array (e.g. Python mapping) containing the
155          variables names as keys and the variables' contents as
156          values in the following format :
157         
158          - Each key is an ASCII encoded character string representing
159            the name of a variable to ask which was passed from the
160            caller.
161           
162          - Each value is a Binary XML-RPC object representing an UTF-8 
163            encoded character string, itself being the result of user
164            input in the form's field for this particular variable.
165
166          - A special key named 'isValid' gives access to a boolean
167            value in the associative array. If the value is True,
168            then the input fields' contents are valid. If the value
169            is False, then what the user typed in the input fields
170            has to be discarded because, for example, the user
171            closed the form without validating his entries.
172            In this case, all the other values are empty strings
173            anyway.
174           
175           
176IMPORTANT : PyKotIcon doesn't currently support encrypted connexions,           
177so if you're afraid of sensitive information flying in the clear
178over the nework, you should probably install a transparent secure
179tunneling software like stunnel on both sides of each connection.
180
181====================================================================
182   
183Please e-mail bugs to the PyKota mailing list at : pykota@librelogiciel.com
184or to the main author at : alet@librelogiciel.com (Jerome Alet)
Note: See TracBrowser for help on using the browser.