SipPayloadsApi » History » Revision 17
Revision 16 (Adrian Georgescu, 08/07/2012 12:27 PM) → Revision 17/31 (Adrian Georgescu, 08/07/2012 12:27 PM)
h1. Payloads API
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 [[SipCoreApiDocumentation#Publication|Publication]] and [[SipCoreApiDocumentation#Subscription|Subscription]] classes.
h2. Common Policy
Implemented in [browser:sipsimple/payloads/policy.py]
Generic data types to be used in policy applications, according to "RFC 4745":http://tools.ietf.org/html/rfc4745.
h3. Example
<pre>
>>> 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>
</pre>
h2. Pres-rules
Implemented in [browser:sipsimple/payloads/presrules.py]
Parses and produces Presence Authorization Rules documents according to "RFC 5025":http://tools.ietf.org/html/rfc5025.
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.
h3. Example
<pre>
>>> 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>
</pre>
h2. Resource Lists
Implemented in [browser:sipsimple/payloads/resourcelists.py]
This module provides convenient classes to parse and generate resource-lists documents as described in "RFC 4826":http://tools.ietf.org/html/rfc4826.
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.
h3. Generation
<pre>
>>> 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>
</pre>
toxml() wraps etree.tostring() and accepts all its arguments (like pretty_print).
h3. Parsing
<pre>
>>> 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
</pre>
h2. RLS Services
Implemented in [browser:sipsimple/payloads/rlsservices.py]
Parses and builds application/rls-services+xml documents according to "RFC 4826":http://tools.ietf.org/html/rfc4826.
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.
h3. Generation
<pre>
>>> 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'
</pre>
h2. Presence Data Model
Implemented in [browser:sipsimple/payloads/presdm.py]
PIDF handling according to "RFC 3863":http://tools.ietf.org/html/rfc3863 and "RFC 3379":http://tools.ietf.org/html/rfc3379. 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.
h3. Example
<pre>
>>> 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>
</pre>
h2. Rich Presence Extension
Implemented in [browser:sipsimple/payloads/rpid.py]
RPID handling according to "RFC 4480":http://tools.ietf.org/html/rfc4480. This module provides an extension to PIDF to support rich presence.
<pre>
__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']
</pre>
h2. Watcher-info
Implemented in [browser:sipsimple/payloads/watcherinfo.py]
Parses application/watcherinfo+xml documents according to "RFC 3857":http://tools.ietf.org/html/rfc3857 and "RFC3858":http://tools.ietf.org/html/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.
h3. Example
<pre>
>>> 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.
</pre>
h2. XCAP-diff
Implemented in [browser:sipsimple/payloads/xcapdiff.py]
This module allows parsing and building xcap-diff documents according to RFC5874.
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.
<pre>
__all__ = ['namespace',
'XCAPDiffApplication',
'BodyNotChanged',
'Document',
'Element',
'Attribute',
'XCAPDiff']
</pre>
h2. Is-composing
Implemented in [browser:sipsimple/payloads/iscomposing.py]
This module parses and produces isComposing messages according to RFC3994.
<pre>
__all__ = ['namespace',
'IsComposingApplication',
'State',
'LastActive',
'ContentType',
'Refresh',
'IsComposingMessage']
</pre>
h2. Message Summary
Implemented in [browser:sipsimple/payloads/messagesummary.py]
This module parses and produces message-summary messages according to RF3842.
h2. User Agent Capability
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.
<pre>
__all__ = ['caps_namespace',
'Audio',
'Application',
'Data',
'Control',
'Video',
'Video',
'Text',
'Message',
'Type',
'Automata',
'Class',
'ClassPersonal',
'ClassBusiness',
'Duplex',
'DuplexFull',
'DuplexHalf',
'DuplexReceiveOnly',
'DuplexSendOnly',
'Description',
'EventPackages',
'EventConference',
'EventDialog',
'EventKpml',
'EventMessageSummary',
'EventPocSettings',
'EventPresence',
'EventReg',
'EventRefer',
'EventSiemensRtpStats',
'EventSpiritsIndps',
'EventSpiritsUserProf',
'EventWinfo',
'Priority',
'PriorityLowerthan',
'PriorityHigherthan',
'PriorityEquals',
'PriorityRange',
'Methods',
'MethodAck',
'MethodBye',
'MethodCancel',
'MethodInfo',
'MethodInvite',
'MethodMessage',
'MethodNotify',
'MethodOptions',
'MethodPrack',
'MethodPublish',
'MethodRefer',
'MethodRegister',
'MethodSubscribe',
'MethodUpdate',
'Extensions',
'ExtensionRel100',
'ExtensionEarlySession',
'ExtensionEventList',
'ExtensionFromChange',
'ExtensionGruu',
'ExtensionHistinfo',
'ExtensionJoin',
'ExtensionNoRefSub',
'ExtensionPath',
'ExtensionPrecondition',
'ExtensionPref',
'ExtensionPrivacy',
'ExtensionRecipientListInvite',
'ExtensionRecipientListSubscribe',
'ExtensionReplaces',
'ExtensionResourcePriority',
'ExtensionSdpAnat',
'ExtensionSecAgree',
'ExtensionTdialog',
'ExtensionTimer',
'Schemes',
'Scheme',
'Actor',
'ActorPrincipal',
'ActorAttendant',
'ActorMsgTaker',
'ActorInformation',
'IsFocus',
'Languages',
'Language',
'Servcaps',
'Mobility',
'MobilityFixed',
'MobilityMobile',
'Devcaps',
'ServcapsExtension',
'EventPackagesExtension',
'PriorityExtension',
'MethodsExtension',
'ExtensionsExtension',
'DevcapsExtension',
'MobilityExtension']
</pre>
h2. 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.
<pre>
__all__ = ['cipid_namespace',
'Card',
'DisplayName',
'Homepage',
'Icon',
'Map',
'Sound']
</pre>
h2. Conference
Implemented in [browser:sipsimple/payloads/conference.py]
Parses and produces conference-info messages according to RFC4575.
<pre>
__all__ = ['namespace',
'ConferenceApplication',
'ConferenceDescription',
'ConfUris',
'ConfUrisEntry',
'ServiceUris',
'ServiceUrisEntry',
'UrisTypeModified',
'UrisTypeEntry',
'AvailableMedia',
'AvailableMediaEntry',
'Users',
'User',
'AssociatedAors',
'Roles',
'Role',
'Endpoint',
'CallInfo',
'Sip',
'Referred',
'JoiningInfo',
'DisconnectionInfo',
'HostInfo',
'HostInfoUris',
'ConferenceState',
'SidebarsByRef',
'SidebarsByVal',
'Conference',
'ConferenceDescriptionExtension']
</pre>
h2. Dialog Info
Implemented in [browser:sipsimple/payloads/dialoginfo.py]
Parses and produces conference-info messages according to RFC4575.
<pre>
__all__ = ['namespace',
'DialogInfoApplication',
'DialogState',
'Replaces',
'ReferredBy',
'Identity',
'Param',
'Target',
'Local',
'Remote',
'Dialog',
'DialogInfo']
</pre>