SipPayloadsApi
Version 17 (Adrian Georgescu, 08/07/2012 12:27 pm) → Version 18/31 (Adrian Georgescu, 08/07/2012 08:33 pm)
h1. SIP SIMPLE client Payloads API
These applications provide functionality that The following modules are required for implementing a feature-rich SIP SIMPLE client.
These applications are used for parsing and generating bodies carried using PUBLISH, SUBSCRIBE and NOTIFY SIP PUBLISH/SUBSCRIBE/NOTIFY methods that have been designed for asynchronous event notifications, notifications to convey in near real-time, real-time state and other information between SIP end-points.
An example of such state information is presence, which in its basic form it 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 the 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.
h2. addressbook.py
High-level implementation of an addressbook stored in XCAP documents. The
contacts, groups and their attributes These applications are stored in resource lists used by the SIP core [[SipCoreApiDocumentation#Publication|Publication]] and OMA
extensions described [[SipCoreApiDocumentation#Subscription|Subscription]] classes.
h2. Common Policy
Implemented in OMA-TS-Presence_SIMPLE_XDM are [browser:sipsimple/payloads/policy.py]
Generic data types to be used for describing
in policy and RLS services by references applications, according to resource lists. Multiple client "RFC 4745":http://tools.ietf.org/html/rfc4745.
h3. Example
<pre>
instances can synchronize this addressbook using XCAP-diff event package. >>> 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. watcherinfo.py
Described Pres-rules
Implemented in RFC3857 and RFC3858. [browser:sipsimple/payloads/presrules.py]
Parses NOTIFY body for presence.winfo event. Used for keeping track of
watchers that subscribed and produces Presence Authorization Rules documents according to our presentity. Based "RFC 5025":http://tools.ietf.org/html/rfc5025.
Authorization rules are stored on this information the
the XCAP server. The presence rules are generated either based on user can manage its presence policy. To retrieve this information initiative or as a response to a new subscription signaled by a change in the watcherinfo application.
h3. Example
<pre>
SIP client must subscribe to its own address for event presence.winfo. >>> 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 resourcelists.py
Described h2. Resource Lists
Implemented in RFC4826. [browser:sipsimple/payloads/resourcelists.py]
Parses This module provides convenient classes to parse and generates XML generate resource-lists documents for constructing 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.
rlsservices.py (RFC4826) 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 generates XML builds application/rls-services+xml documents for constructing rls-services 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 signalling signaling for subscription and collection of
notifications and provides consolidated answer answers to the sip SIP user agent.
rlmi.py, rlsnotify.py (RFC4482)
Document handling for NOTIFY body for Resource Lists Contact Information. h3. Generation
policy.py (RFC4745) <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>
Generic data types to be used in policy applications.
presrules.py (RFC5025) === Parsing ===
Parses and generates authorization rules in XML format for presence or other >>> rls = RLSServices.parse(example_from_section_4_3_rfc)
applications. Authorization rules are stored on the XCAP server. The >>> len(rls)
presence rules are generated either based on user initiative or as a 2
>>> rls[0].uri
response to a new subscription signaled by a change in the watcherinfo 'sip:mybuddies@example.com'
>>> print rls[0].list
application.
omapolicy.py (OMA-TS-Presence_SIMPLE_XDM-V1_1) http://xcap.example.com/xxx
Conditions extension handling according to OMA-TS-Presence_SIMPLE_XDM-V1_1.
This module provides an extension to common policy defined in RFC4745 to >>> print rls[0].packages[0]
support condition extensions defined by OMA. presence
prescontent.py (OMA-TS-Presence_SIMPLE_XDM-V1_1) >>> rls[1].uri
'sip:marketing@example.com'
Generates presence content application documents according to OMA TS
>>> assert len(rls[1].packages) == 1 and rls[1].packages[0] == 'presence'
</pre>
h2. Presence SIMPLE Content. Data Model
directory.py (OMA Core Specifications) Implemented in [browser:sipsimple/payloads/presdm.py]
Parses xcap-directory messages PIDF handling according to OMA TS XDM Core.
dialoginfo.py (RFC4235)
Parses "RFC 3863":http://tools.ietf.org/html/rfc3863 and produces dialog-info messages according to RFC4235.
dialogrules.py
Parses and produces Dialog Authorization Rules documents. As there is no RFC
for this, common-policy format from RFC 4745 is used. Subscription Handling
has been taken from RFC 5025.
pidf.py (RFC3863 and RFC3379)
"RFC 3379":http://tools.ietf.org/html/rfc3379. This module provides classes to parse and generate PIDF documents, and also
uses the XML Application extensibility API documents.
Used to allow extensions to PIDF. It
is used to parse NOTIFY body for presence event and generates rich presence
generate state information for use with PUBLISH. Used to generate own presence
information PUBLISH method and to parse the state of buddy lists entries we have subscribed
to. A SIP client typically instantiates a new pidf PIDF object for itself and for
each buddy it SUBSCRIBEs to and update updates each object when a NOTIFY is
received. The list of buddys buddies is maintained using resourcelists the resource-lists XCAP application.
rpid.py (RFC4480) 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>
presdm.py (RFC4479) h2. Watcher-info
Implemented in [browser:sipsimple/payloads/watcherinfo.py]
This module provides an extension 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 PIDF authorization rules can be managed using presrules.py. To retrieve this information the SIP client must subscribe to support 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 data module updated watchers as values.
>>> updated = winfo.update(winfo_doc)
defined >>> 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 RFC4479.
cipid.py (RFC4482)
This module provides an extension to PIDF to provide person related <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
caps.py (RFC5196) Implemented in [browser:sipsimple/payloads/xcapdiff.py]
This module provides capabilities application: displays OPTIONS request-like information
as an extension to the PIDF.
xcapcaps.py (RFC4825)
Support for allows parsing and building xcap-caps documents, as defined by RFC4825.
xcapdiff.py (RFC5874) xcap-diff documents according to RFC5874.
Parses 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>
iscomposing.py (RFC3994) h2. Is-composing
Implemented in [browser:sipsimple/payloads/iscomposing.py]
This module parses and generates produces isComposing messages according to RFC3994. It's used
<pre>
mainly __all__ = ['namespace',
'IsComposingApplication',
'State',
'LastActive',
'ContentType',
'Refresh',
'IsComposingMessage']
</pre>
h2. Message Summary
Implemented in chat environments [browser:sipsimple/payloads/messagesummary.py]
This module parses and produces message-summary messages according to indicate 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 other party that the user is actually PIDF documents.
<pre>
typing a message. __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>
conference.py (RFC4575) h2. CIPID
Implemented in [browser:sipsimple/payloads/cipid.py]
CIPID handling according to RFC4482. This module implements conference-info payload parsing and generating for
describing provides an extension to PIDF to provide additional contact information about conference participants a presentity.
<pre>
__all__ = ['cipid_namespace',
'Card',
'DisplayName',
'Homepage',
'Icon',
'Map',
'Sound']
</pre>
h2. Conference
Implemented in [browser:sipsimple/payloads/conference.py]
Parses and related resources. 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>
messagesummary.py (RFC3842) h2. Dialog Info
Implemented in [browser:sipsimple/payloads/dialoginfo.py]
This module implements a parser Parses and generator for message-summary payload,
which is used produces conference-info messages according to indicate missed calls or voice mail recordings. RFC4575.
<pre>
__all__ = ['namespace',
'DialogInfoApplication',
'DialogState',
'Replaces',
'ReferredBy',
'Identity',
'Param',
'Target',
'Local',
'Remote',
'Dialog',
'DialogInfo']
</pre>