Developer Area

root/apps/python/trunk/README @ 543

Revision 543, 6.4 kB (checked in by nadya, 5 years ago)

PyTel? - Python scripts for .tel

Line 
1PyTel v0.1
2==========
3by Andrew McDonald <admcd.tel>
4
5PyTel is a collection of python bits and bobs for using .tel domains.
6
7The two main applications provided here are:
8- E-mail lookup from .tel for the mutt mail client
9- Telephone number and SIP URI lookup for Snom SIP phones
10
11The contents of the collection are:
12pytel.py - main commandline tool
13telsnom.py - cgi script for snom minibrowser
14telsoap.py - library functions for telfriends SOAP services
15telquery.py - library functions for .tel DNS queries
16
17Dependencies that are not part of the standard python distribution
18are:
19dnspython (found on Debian Linux in the python-dnspython package)
20M2Crypto (found on Debian Linux in the python-m2crypto package)
21
22This file is the only documentation. Comments in the code are
23more-or-less non-existant.
24
25pytel.py
26--------
27
28pytel.py is the main command line tool, and supports five commands:
29init
30refresh
31query
32emailquery
33snomurl
34
35Configuration for telfriends access to private data
36---------------------------------------------------
37
38init initialises credentials and data for telfriends services. It
39prompts the user for the telfriends web username and password,
40displays the challenge and prompts for the response. (These pieces of
41information can alternatively be provided on the command line). init
42creates three files in ~/.pytel which are:
43soapuser - telfriends member soap username/password
44telkey.pem - RSA private key
45friendlist.csv - CSV file containing friend domains and labels for
46private data locations
47
48refresh uses the previously acquired credentials to refresh the
49friendlist.csv file.
50
51General lookups
52---------------
53
54The pytel.py query command performs a query for any records for a
55telname. If the .tel name is in the previously acquired friend list
56then private entries are also shown. The output is presented in a tab
57separated format.
58
59E-mail lookups for mutt
60-----------------------
61
62The pytel.py emailquery command queries for e-mail addresses for a
63telname. If the .tel name is in the previously acquired friend list
64then private entries are also shown. The output is in the format
65required for external address query tools for the mutt mail client,
66e.g.:
67  pytel.py emailquery henri.tel
68  henri.tel found 2 e-mail addresses:
69  henri@asseily.com     Henri Asseily   Main Contact
70  hasseily@telnic.org   Henri Asseily   Work (Telnic)
71To use it from mutt add a setting to your .muttrc file:
72set query_command="pytel.py emailquery %s"
73
74Snom SIP phone minibrowser
75--------------------------
76
77The Snom range of SIP phones contain a minibrowser capable of
78interacting with the user using XML files supplied by a web server.
79
80To use the snom minibrowser service for .tel lookup the telsnom.py and
81telquery.py scripts must be placed in the cgi-bin directory of the
82webserver, and telsnom.py must be executable.
83
84The pytel.py snomurl command provides a URL for a snom phone to use
85for the .tel search minibrowser service (telsnom.py). The hostname
86where the CGI script must be provided on the command-line. In its
87simplest form this URL will be of the form:
88http://example.com/cgi-bin/telsnom.py
89If credentials and friendlist have been previously acquired with the
90init command, then the RSA key and friendlist are also encoded into
91the URL:
92http://example.com/cgi-bin/telsnom.py?telkey=-----BEGIN%20RSA%20PRIVAT
93E%20KEY-----%0AMII ... %0A-----END%20RSA%20PRIVATE%20KEY-----%0A&frien
94ds=henri.tel%2Ca1 ...
95
96If the "-n" or "--nopriv" option is given on the commandline then the
97key and friendlist are omitted.
98
99To manually configure the phone:
100On the web interface for the phone, go to the function keys page. Pick
101a key (e.g. P12) and set the 'Type' to 'Action URL'. Paste the URL
102provided by snomurl in the text box. Save the settings.
103
104To automatically configure the phone:
105When running the snomurl command including the -u, -p, -t and -f
106options to provide the phone username, password, hostname and function
107key number respectively. The function key number from 1 to 12 will
108select one of the function keys on the phone to configure. If these
109options are provided then the action url is automtically set on that
110function key on the phone. Note that in order for this to work "Use
111hidden tags" must be set to "no" in the QoS/Security section of the
112Advanced configuration.
113
114To use the .tel search facility:
115On the phone, press the function key chosen. The ".tel Search" page
116will appear. Enter a .tel domain name (the .tel extension may be
117omitted) and press the OK (tick) key. Any voice:tel: or sip: URIs will
118be displayed and may be selected. If a friendlist was available and
119included in the action URL then pressing OK with an empty search will
120display the list of known friends.
121
122If the friendlist is updated with the pytel.py refresh command, the
123action URL should be regenerated with the snomurl command and
124reconfigured on the phone.
125
126NB: the supported length of the action URL (and hence maximum
127friendlist length is unknown).
128
129This has only been tested on a Snom 360.
130
131Changelog
132---------
133v0.1 2009-09-26 - Initial public release
134
135Copyright notice
136----------------
137
138Copyright (c) 2009, Andrew McDonald
139All rights reserved.
140
141Redistribution and use in source and binary forms, with or without
142modification, are permitted provided that the following conditions
143are met:
144
145   * Redistributions of source code must retain the above copyright
146     notice, this list of conditions and the following disclaimer.
147
148   * Redistributions in binary form must reproduce the above
149     copyright notice, this list of conditions and the following
150     disclaimer in the documentation and/or other materials provided
151     with the distribution.
152
153   * The name of the author may not be used to endorse or promote
154     products derived from this software without specific prior
155     written permission.
156
157THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
158"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
159LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
160FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
161COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
162INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
163BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
164LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
165CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
166LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
167ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
168POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the browser.
Telnic
Search This Site
Partners
Neustar
ICANN
Main site | WHOIS | Sell .tel | FAQ | Archived Site | About Telnic | Contact Us