Requirements
============
  dbus-python
  telepathy-python
  pygobject

All of these requirements are supplied by rootstraps fremantle-2008-06-16.15-55
or newer.


Purpose
============

Telepathy-pinocchio is a connection manager meant for testing Telepathy
applications. Pinocchio interacts with settings files on the filesystem instead
of a remote server, thereby removing two of the biggest stumbling blocks for
testing a Telepathy-based application: the network and control over the back-end
server.

Telepathy-pinocchio was designed with maintainability as a primary goal (above
performance). In practice, it may be faster for some tasks than real connection
managers (which have to wait on network latency and potential server work
latency). Nonetheless, this is just a side effect, and could change if we add
significantly more instrumentation to telepathy-pinocchio for debugging
purposes.


Usage
============

Telepathy-pinocchio comes with the pinocchio-ctl tool. This tool is a
command-line based Telepathy client for issuing commands with (fairly) fast
results. 

The general syntax for pinocchio-ctl is:

    pinocchio-ctl [options] COMMAND [args]

Options
------------

-u USERNAME / --username=USERNAME
    connect via a non-default username

-p PASSWORD / --password=PASSWORD
    specify a non-default password

'list' command
-------------

This command simply prints unmodified contact list (including each contact's
attributes).


'reset' command
-------------

Returns the roster to its default state, reverting all changes to contacts,
groups, contact lists, etc.


'add-account' command
-------------

Create a new pinocchio "server-side" account (create the empty contacts file,
etc.). Note this does not create a corresponding Mission Control account.

The 'add-account' command arguments are structured as:

    ACCOUNT_NAME


'remove-account' command
-------------

Delete an existing pinocchio "server-side" account (remove the account
directory). This command only attempts to remove accounts in
$HOME/.telepathy-pinocchio/accounts, and not the global accounts in
/var/lib/telepathy-pinocchio/accounts.

The 'remove-account' command arguments are structured as:

    ACCOUNT_NAME


'add-contact' command
-------------

Add new contacts to any number of server-side contact lists (eg, 'subscribe',
'publish', 'deny').

The 'add-contact' command arguments are structured as:

    USERNAME:[lists=LIST_1][+LIST_2][+...] [...]

Valid keys include:
    lists       -- contact lists to add contact to (eg, 'subscribe')

Examples
.............

NOTE: within scratchbox, you will need to start the af-sb-init.sh environment
script and run these commands through the run-standalone.sh script for them to
work.

    pinocchio-ctl add-contact abcdef@example.com:lists=subscribe+publish+allow
 

'remove-contact' command
-------------

Remove contacts from any number of server-side contact lists (eg, 'subscribe',
'publish', 'deny').

The 'remove-contact' command arguments are structured as:

    USERNAME:[lists=LIST_1][+LIST_2][+...] [...]

Valid keys include:
    lists       -- contact lists to remove contact from (eg, 'subscribe')

Examples
.............

NOTE: within scratchbox, you will need to start the af-sb-init.sh environment
script and run these commands through the run-standalone.sh script for them to
work.

    pinocchio-ctl remove-contact abc@example.com:lists=subscribe+publish+allow


'add-group' command
-------------

Add any number of arbitrarily-named server-side contact groups (eg, 'friends',
'co-workers').

The 'add-group' command arguments are structured as:

    GROUP_1 [GROUP_2] [...]

Examples
.............

NOTE: within scratchbox, you will need to start the af-sb-init.sh environment
script and run these commands through the run-standalone.sh script for them to
work.

    pinocchio-ctl add-group friends co-workers 'group with spaces'

After the command completes, you may add an number of contacts to the group(s)
with the 'add-contact' command. For instance:

    pinocchio-ctl add-contact foo@example.org:lists=friends+'group with spaces'
 

'remove-group' command
-------------

Remove any number of arbitrarily-named server-side contact groups (eg,
'friends', 'co-workers'). Internally, this command removes all members from the
group before removing the group, but it does not remove the contacts themselves
from the server (even if they no longer belong to any groups).

The 'remove-group' command arguments are structured as:

    GROUP_1 [GROUP_2] [...]

Examples
.............

NOTE: within scratchbox, you will need to start the af-sb-init.sh environment
script and run these commands through the run-standalone.sh script for them to
work.

    pinocchio-ctl remove-group friends co-workers 'group with spaces'


'set' command
-------------

This command lets you change server-side contact properties. These changes
cause telepathy-pinocchio to change its internal state and emit signals which
clients (including pinocchio-ctl) will receive and may act upon.

The 'set' command arguments are structured as:

    USERNAME:KEY_1=VALUE_1[,KEY_2=VALUE_2[,...]]

Valid keys include:
    alias       -- server-side contact alias (eg, 'Jane Doe')
    avatar-file -- path to avatar image file (eg, '/tmp/face.png')
    message     -- presence status message (eg, 'I am out to lunch')
    status      -- presence status (eg, 'available', 'dnd', 'offline')

Examples
.............

NOTE: within scratchbox, you will need to start the af-sb-init.sh environment
script and run these commands through the run-standalone.sh script for them to
work.

    pinocchio-ctl set foo@barbaz.com:alias='Foo Bar Baz'

    pinocchio-ctl set alice:status='busy',message='at lunch'

    pinocchio-ctl set alice:alias='Ally Smith',status=busy,message='at lunch'

See the contacts.xml file for the valid contacts. You may also modify this file
to expand the contact list. By default, this is installed in
/var/lib/telepathy/accounts/default_40default/


Limitations
============

Telepathy-pinocchio currently only implements a small subset of the Telepathy
Specification (most notably ConnectionManager, Connection, and the Connection
interfaces Aliasing, Avatars (partially), and Presence).
