SIP SIMPLE Client SDK

= Payloads API =

<abbr title="SipPayloadsApi*, depth=3">TOC</abbr>

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)

<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)

<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)

<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⁰
friends.name

'friends'

bill = friends⁰
bill.uri

'sip:bill@example.com'

print bill.display_name

Bill Doe

close_friends = friends²
print close_friends⁰

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

print close_friends².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)

<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&lt;/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⁰.uri

'sip:mybuddies@example.com'

print rls⁰.list

http://xcap.example.com/xxx

print rls⁰.packages⁰

presence

rls¹.uri

'sip:marketing@example.com'

assert len(rls¹.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)

<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 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='''

... <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⁰.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.

User Agent Capability Extension

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

User Agent Capability Extension handling according to RFC5196

This module provides an extension to PIDF to describe a user-agent capabilities in the PIDF documents.

CIPID ==

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

CIPID handling according to RFC4482. This module provides an extension to PIDF to provide additional contact information about a presentity.