root/apps/python/trunk/README @ 543

PyTel v0.1
==========
by Andrew McDonald <admcd.tel>

PyTel is a collection of python bits and bobs for using .tel domains.

The two main applications provided here are:
- E-mail lookup from .tel for the mutt mail client
- Telephone number and SIP URI lookup for Snom SIP phones

The contents of the collection are:
pytel.py - main commandline tool
telsnom.py - cgi script for snom minibrowser
telsoap.py - library functions for telfriends SOAP services
telquery.py - library functions for .tel DNS queries

Dependencies that are not part of the standard python distribution
are:
dnspython (found on Debian Linux in the python-dnspython package)
M2Crypto (found on Debian Linux in the python-m2crypto package)

This file is the only documentation. Comments in the code are
more-or-less non-existant.

pytel.py
--------

pytel.py is the main command line tool, and supports five commands:
init
refresh
query
emailquery
snomurl

Configuration for telfriends access to private data
---------------------------------------------------

init initialises credentials and data for telfriends services. It
prompts the user for the telfriends web username and password,
displays the challenge and prompts for the response. (These pieces of
information can alternatively be provided on the command line). init
creates three files in ~/.pytel which are:
soapuser - telfriends member soap username/password
telkey.pem - RSA private key
friendlist.csv - CSV file containing friend domains and labels for
private data locations

refresh uses the previously acquired credentials to refresh the
friendlist.csv file.

General lookups
---------------

The pytel.py query command performs a query for any records for a
telname. If the .tel name is in the previously acquired friend list
then private entries are also shown. The output is presented in a tab
separated format.

E-mail lookups for mutt
-----------------------

The pytel.py emailquery command queries for e-mail addresses for a
telname. If the .tel name is in the previously acquired friend list
then private entries are also shown. The output is in the format
required for external address query tools for the mutt mail client,
e.g.:
  pytel.py emailquery henri.tel
  henri.tel found 2 e-mail addresses:
  henri@asseily.com     Henri Asseily   Main Contact
  hasseily@telnic.org   Henri Asseily   Work (Telnic)
To use it from mutt add a setting to your .muttrc file:
set query_command="pytel.py emailquery %s"

Snom SIP phone minibrowser
--------------------------

The Snom range of SIP phones contain a minibrowser capable of
interacting with the user using XML files supplied by a web server.

To use the snom minibrowser service for .tel lookup the telsnom.py and
telquery.py scripts must be placed in the cgi-bin directory of the
webserver, and telsnom.py must be executable.

The pytel.py snomurl command provides a URL for a snom phone to use
for the .tel search minibrowser service (telsnom.py). The hostname
where the CGI script must be provided on the command-line. In its
simplest form this URL will be of the form:
http://example.com/cgi-bin/telsnom.py
If credentials and friendlist have been previously acquired with the
init command, then the RSA key and friendlist are also encoded into
the URL:
http://example.com/cgi-bin/telsnom.py?telkey=-----BEGIN%20RSA%20PRIVAT
E%20KEY-----%0AMII ... %0A-----END%20RSA%20PRIVATE%20KEY-----%0A&frien
ds=henri.tel%2Ca1 ...

If the "-n" or "--nopriv" option is given on the commandline then the
key and friendlist are omitted.

To manually configure the phone:
On the web interface for the phone, go to the function keys page. Pick
a key (e.g. P12) and set the 'Type' to 'Action URL'. Paste the URL
provided by snomurl in the text box. Save the settings.

To automatically configure the phone:
When running the snomurl command including the -u, -p, -t and -f
options to provide the phone username, password, hostname and function
key number respectively. The function key number from 1 to 12 will
select one of the function keys on the phone to configure. If these
options are provided then the action url is automtically set on that
function key on the phone. Note that in order for this to work "Use
hidden tags" must be set to "no" in the QoS/Security section of the
Advanced configuration.

To use the .tel search facility:
On the phone, press the function key chosen. The ".tel Search" page
will appear. Enter a .tel domain name (the .tel extension may be
omitted) and press the OK (tick) key. Any voice:tel: or sip: URIs will
be displayed and may be selected. If a friendlist was available and
included in the action URL then pressing OK with an empty search will
display the list of known friends.

If the friendlist is updated with the pytel.py refresh command, the
action URL should be regenerated with the snomurl command and
reconfigured on the phone.

NB: the supported length of the action URL (and hence maximum
friendlist length is unknown).

This has only been tested on a Snom 360.

Changelog
---------
v0.1 2009-09-26 - Initial public release

Copyright notice
----------------

Copyright (c) 2009, Andrew McDonald
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

   * Redistributions of source code must retain the above copyright
     notice, this list of conditions and the following disclaimer.

   * Redistributions in binary form must reproduce the above
     copyright notice, this list of conditions and the following
     disclaimer in the documentation and/or other materials provided
     with the distribution.

   * The name of the author may not be used to endorse or promote
     products derived from this software without specific prior
     written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.