SIP SIMPLE Client SDK

= Payloads API =

[[TOC(SipPayloadsApi*, depth=3)]]

The following modules are used for parsing and generating bodies carried using

SIP PUBLISH/SUBSCRIBE/NOTIFY methods that have been designed for

asynchronous event notifications to convey in real-time state and other

information between end-points. 

An example of state information is presence, which in its basic form provides user availability information based on end-user choice. In its

advanced form, presence can provide rich state information including but not

limited to user mood, geo-location, environment, noise level and type of

communication desired. The information can be disseminated based on a

granular policy which allows end-users to decide who has access to which

part of the published information.

These applications are used by the SIP core [wiki:SipCoreApiDocumentation#Publication Publication] and [wiki:SipCoreApiDocumentation#Subscription Subscription] classes.

== Common Policy ==

Implemented in [browser:sipsimple/payloads/policy.py]

Generic data types to be used in policy applications, according to [http://tools.ietf.org/html/rfc4745 RFC 4745].

=== Example ===

{{{

>>> alice = IdentityOne('sip:alice@example.com')

>>> carol = IdentityOne('tel:+1-212-555-1234')

>>> bob = IdentityOne('mailto:bob@example.net')

>>> print carol

tel:+1-212-555-1234

>>> id = Identity([alice, bob])

>>> print id

Identity([IdentityOne('sip:alice@example.com'), IdentityOne('mailto:bob@example.net')])

>>> id[1:1] = [carol]

>>> print id

Identity([IdentityOne('sip:alice@example.com'), IdentityOne('tel:+1-212-555-1234'), IdentityOne('mailto:bob@example.net')])

>>> conditions = Conditions([id])

>>> rule = Rule(id='f3g44r1', conditions=conditions, actions=Actions(), transformations=Transformations())

>>> ruleset = RuleSet()

>>> ruleset.append(rule)

>>> print ruleset.toxml(pretty_print=True)

<?xml version='1.0' encoding='UTF-8'?>

<cp:ruleset xmlns:cp="urn:ietf:params:xml:ns:common-policy">

  <cp:rule id="f3g44r1">

    <cp:conditions>

      <cp:identity>

        <cp:one id="sip:alice@example.com"/>

        <cp:one id="mailto:bob@example.net"/>

        <cp:one id="tel:+1-212-555-1234"/>

      </cp:identity>

    </cp:conditions>

    <cp:actions/>

    <cp:transformations/>

  </cp:rule>

</cp:ruleset>

<BLANKLINE>

}}}

== Pres-rules ==

Implemented in [browser:sipsimple/payloads/presrules.py]

Parses and produces Presence Authorization Rules documents according to [http://tools.ietf.org/html/rfc5025 RFC 5025].

Authorization rules are stored on the XCAP server. The presence rules are generated either based on user initiative or as a response to a new subscription signaled by a change in the watcherinfo application.

=== Example ===

{{{

>>> conditions = Conditions([Identity([IdentityOne('sip:user@example.com')])])

>>> actions = Actions([SubHandling('allow')])

>>> transformations = Transformations()

>>> psrv = ProvideServices(provides=[ServiceURIScheme('sip'), ServiceURIScheme('mailto')])

>>> ppers = ProvidePersons(all=True)

>>> transformations[0:0] = [psrv, ppers]

>>> transformations.append(ProvideActivities('true'))

>>> transformations.append(ProvideUserInput('bare'))

>>> transformations.append(ProvideUnknownAttribute(ns='urn:vendor-specific:foo-namespace', name='foo', value='true'))

>>> rule = Rule(id='a', conditions=conditions, actions=actions, transformations=transformations)

>>> prules = PresRules([rule])

>>> print prules.toxml(pretty_print=True)

<?xml version='1.0' encoding='UTF-8'?>

<cp:ruleset xmlns:pr="urn:ietf:params:xml:ns:pres-rules" xmlns:cp="urn:ietf:params:xml:ns:common-policy">

  <cp:rule id="a">

    <cp:conditions>

      <cp:identity>

        <cp:one id="sip:user@example.com"/>

      </cp:identity>

    </cp:conditions>

    <cp:actions>

      <pr:sub-handling>allow</pr:sub-handling>

    </cp:actions>

    <cp:transformations>

      <pr:provide-services>

        <pr:service-uri-scheme>sip</pr:service-uri-scheme>

        <pr:service-uri-scheme>mailto</pr:service-uri-scheme>

      </pr:provide-services>

      <pr:provide-persons>

        <pr:all-persons/>

      </pr:provide-persons>

      <pr:provide-activities>true</pr:provide-activities>

      <pr:provide-user-input>bare</pr:provide-user-input>

      <pr:provide-unknown-attribute ns="urn:vendor-specific:foo-namespace" name="foo">true</pr:provide-unknown-attribute>

    </cp:transformations>

  </cp:rule>

</cp:ruleset>

<BLANKLINE>

}}}

== Resource Lists ==

Implemented in [browser:sipsimple/payloads/resourcelists.py]

This module provides convenient classes to parse and generate resource-lists documents as described in [http://tools.ietf.org/html/rfc4826 RFC 4826].

Used for server side storage of presence related buddy lists using XCAP protocol. The SIP clients maintain the resource-lists on the XCAP server which provides persisten storage and aggregation point for multiple devices.

=== Generation ===

{{{

>>> bill = Entry('sip:bill@example.com', display_name = 'Bill Doe')

>>> petri = EntryRef('some/ref')

>>> friends = List([bill, petri])

>>> rl = ResourceLists([friends])

>>> print rl.toxml(pretty_print=True)

<?xml version='1.0' encoding='UTF-8'?>

<rl:resource-lists xmlns:rl="urn:ietf:params:xml:ns:resource-lists">

  <rl:list>

    <rl:entry uri="sip:bill@example.com">

      <rl:display-name>Bill Doe</rl:display-name>

    </rl:entry>

    <rl:entry-ref ref="some/ref"/>

  </rl:list>

</rl:resource-lists>

<BLANKLINE>

}}}

toxml() wraps etree.tostring() and accepts all its arguments (like pretty_print).

=== Parsing ===

{{{

>>> r = ResourceLists.parse(example_from_section_3_3_rfc)

>>> len(r)

1

>>> friends = r[0]

>>> friends.name

'friends'

>>> bill = friends[0]

>>> bill.uri

'sip:bill@example.com'

>>> print bill.display_name

Bill Doe

>>> close_friends = friends[2]

>>> print close_friends[0]

"Joe Smith" <sip:joe@example.com>

>>> print close_friends[2].display_name

Marketing

}}}

== RLS Services ==

Implemented in [browser:sipsimple/payloads/rlsservices.py]

Parses and builds application/rls-services+xml documents according to [http://tools.ietf.org/html/rfc4826  RFC 4826].

Used for delegating presence related works to the server. The client build rls-services lists with buddies and instructs the server to subscribe to the sip uris indicated in the lists. This way the client can save bandwidth as the server performs the signaling for subscription and collection of notifications and provides consolidated answers to the SIP user agent.

=== Generation ===

{{{

>>> buddies = Service('sip:mybuddies@example.com', 'http://xcap.example.com/xxx', ['presence'])

>>> marketing = Service('sip:marketing@example.com')

>>> marketing.list = RLSList([Entry('sip:joe@example.com'), Entry('sip:sudhir@example.com')])

>>> marketing.packages = ['presence']

>>> rls = RLSServices([buddies, marketing])

>>> print rls.toxml(pretty_print=True)

<?xml version='1.0' encoding='UTF-8'?>

<rls-services xmlns:rl="urn:ietf:params:xml:ns:resource-lists" xmlns="urn:ietf:params:xml:ns:rls-services">

  <service uri="sip:mybuddies@example.com">

    <resource-list>http://xcap.example.com/xxx</resource-list>

    <packages>

      <package>presence</package>

    </packages>

  </service>

  <service uri="sip:marketing@example.com">

    <list>

      <rl:entry uri="sip:joe@example.com"/>

      <rl:entry uri="sip:sudhir@example.com"/>

    </list>

    <packages>

      <package>presence</package>

    </packages>

  </service>

</rls-services>

<BLANKLINE>

=== Parsing ===

>>> rls = RLSServices.parse(example_from_section_4_3_rfc)

>>> len(rls)

2

>>> rls[0].uri

'sip:mybuddies@example.com'

>>> print rls[0].list

http://xcap.example.com/xxx

>>> print rls[0].packages[0]

presence

>>> rls[1].uri

'sip:marketing@example.com'

>>> assert len(rls[1].packages) == 1 and rls[1].packages[0] == 'presence'

}}}

== Presence Data Model ==

Implemented in [browser:sipsimple/payloads/presdm.py]

PIDF handling according to [http://tools.ietf.org/html/rfc3863 RFC 3863] and [http://tools.ietf.org/html/rfc3379 RFC 3379]. This module provides classes to parse and generate PIDF documents.

Used to parse NOTIFY body for presence event and generate state information for use with PUBLISH method and to parse the state of buddy lists entries we have subscribed to. A SIP client typically instantiates a new PIDF object for itself and for each buddy it SUBSCRIBEs to and updates each object when a NOTIFY is received. The list of buddies is maintained using the resource-lists XCAP application.

=== Example ===

{{{

>>> from datetime import datetime

>>> pidf = PIDF('pres:someone@example.com')

>>> status = Status(basic=Basic('open'))

>>> contact = Contact('im:someone@mobilecarrier.net')

>>> contact.priority = "0.8"

>>> tuple1 = Service('bs35r9', notes=[ServiceNote("Don't Disturb Please!"), ServiceNote("Ne derangez pas, s'il vous plait", lang="fr")], status=status)

>>> tuple1.contact = contact

>>> tuple1.timestamp = Timestamp(datetime(2008, 9, 11, 20, 42, 03))

>>> tuple2 = Service('eg92n8', status=Status(basic=Basic('open')), contact=Contact('mailto:someone@example.com'))

>>> tuple2.contact.priority = "1.0"

>>> pidf.notes.add(Note("I'll be in Tokyo next week"))

>>> pidf.append(tuple1)

>>> pidf.append(tuple2)

>>> print pidf.toxml(pretty_print=True)

<?xml version='1.0' encoding='UTF-8'?>

<presence xmlns:rpid="urn:ietf:params:xml:ns:pidf:rpid" xmlns:dm="urn:ietf:params:xml:ns:pidf:data-model" xmlns="urn:ietf:params:xml:ns:pidf" entity="pres:someone@example.com"

  <tuple id="bs35r9">

    <status>

      <basic>open</basic>

    </status>

    <contact priority="0.8">im:someone@mobilecarrier.net</contact>

    <note>Don't Disturb Please!</note>

    <note xml:lang="fr">Ne derangez pas, s'il vous plait</note>

    <timestamp>2008-09-11T20:42:03Z</timestamp>

  </tuple>

  <tuple id="eg92n8">

    <status>

      <basic>open</basic>

    </status>

    <contact priority="1.0">mailto:someone@example.com</contact>

  </tuple>

  <note>I'll be in Tokyo next week</note>

</presence>

<BLANKLINE>

}}}

== Rich Presence Extension ==

Implemented in [browser:sipsimple/payloads/rpid.py]

RPID handling according to [http://tools.ietf.org/html/rfc4480 RFC 4480]. This module provides an extension to PIDF (module sipsimple.applications.presdm) to support rich presence.

{{{

__all__ = ['_rpid_namespace_',

           'ActivityElement',

           'MoodElement',

           'PlaceTypeElement',

           'PrivacyElement',

           'SphereElement',

           'RPIDNote',

           'Activities',

           'Mood',

           'PlaceIs',

           'AudioPlaceInformation',

           'VideoPlaceInformation',

           'TextPlaceInformation',

           'PlaceType',

           'AudioPrivacy',

           'TextPrivacy',

           'VideoPrivacy',

           'Privacy',

           'Relationship',

           'ServiceClass',

           'Sphere',

           'StatusIcon',

           'TimeOffset',

           'UserInput',

           'Class',

           'Other']

}}}

== Watcher-info ==

Implemented in [browser:sipsimple/payloads/watcherinfo.py]

Parses application/watcherinfo+xml documents according to [http://tools.ietf.org/html/rfc3857 RFC 3857] and [http://tools.ietf.org/html/rfc3858 RFC3858].

Used for parsing of NOTIFY body for presence.winfo event. Used for keeping track of watchers that subscribed to our presentity. Based on this information the authorization rules can be managed using presrules.py. To retrieve this information the SIP client must subscribe to its own address for event presence.winfo.

=== Example ===

{{{

>>> winfo_doc='''<?xml version="1.0"?>

... <watcherinfo xmlns="urn:ietf:params:xml:ns:watcherinfo"

...              version="0" state="full">

...   <watcher-list resource="sip:professor@example.net" package="presence">

...     <watcher status="active"

...              id="8ajksjda7s"

...              duration-subscribed="509"

...              event="approved" >sip:userA@example.net</watcher>

...     <watcher status="pending"

...              id="hh8juja87s997-ass7"

...              display-name="Mr. Subscriber"

...              event="subscribe">sip:userB@example.org</watcher>

...   </watcher-list>

... </watcherinfo>'''

>>> winfo = WatcherInfo()

The return value of winfo.update() is a dictionary containing WatcherList objects

as keys and lists of the updated watchers as values.

>>> updated = winfo.update(winfo_doc)

>>> len(updated['sip:professor@example.net'])

2

winfo.pending, winfo.terminated and winfo.active are dictionaries indexed by

WatcherList objects as keys and lists of Wacher objects as values.

>>> print winfo.pending['sip:professor@example.net'][0]

"Mr. Subscriber" <sip:userB@example.org>

>>> print winfo.pending['sip:professor@example.net'][1]

Traceback (most recent call last):

  File "<stdin>", line 1, in <module>

IndexError: list index out of range

>>> print winfo.active['sip:professor@example.net'][0]

sip:userA@example.net

>>> len(winfo.terminated['sip:professor@example.net'])

0

winfo.wlists is the list of WatcherList objects

>>> list(winfo.wlists[0].active) == list(winfo.active['sip:professor@example.net'])

True

See the classes for more information.

}}}

== XCAP-diff ==

Implemented in [browser:sipsimple/payloads/xcapdiff.py]

This module allows parsing and building xcap-diff documents according to draft-ietf-simple-xcap-diff.

Used to parse NOTIFY body for xcap-diff event. Used to detect changes in XCAP documents changed by other device configured for the same presentity.

== Is-composing ==

Implemented in [browser:sipsimple/payloads/iscomposing.py]

This module parses and produces isComposing messages according to RFC3994.

== Message Summary ==

Implemented in [browser:sipsimple/payloads/messagesummary.py]

This module parses and produces message-summary messages according to RF3842.