SIP SIMPLE Client SDK

== sip_subscribe_winfo ==

[[TOC(SipTesting*, sip_*,xcap*, depth=2)]]

To use this script you must to have a valid [wiki:SipSettingsAPI configuration].

=== Description ===

[[Image(http://www.openxcap.org/chrome/site/SIMPLE-Winfo.png, align=right)]]

Watchers are defined as entities that request (i.e., subscribe to)

information about a resource, using the SIP event framework, RFC 3265. There

is fairly complex state associated with these subscriptions.  This state

includes the identity of the subscriber, the state of the subscription, and 

so on. The union of the state for all subscriptions to a particular resource

is called the watcher information for that resource.  This state is dynamic,

changing as subscribers come and go.  As a result, it is possible, and

indeed useful, to subscribe to the watcher information for a particular

resource. An important application of this is the ability for a user to find

out the set of subscribers to their presentity. This would allow the user to

provide an authorization decision for the subscription.

This script implements SUBSCRIBE for the watcher info event package and

manipulation of the pres-rules document that holds the presence policy of

the subscribing user.

Source code: [source:scripts/sip_subscribe_winfo.py scripts/sip_subscribe_winfo.py]

{{{

adigeo@ag-imac3:~$sip_subscribe_winfo -h

Usage: sip_subscribe_winfo [options]

This example script will use the specified SIP account to SUBSCRIBE to the

presence.winfo event of itself and request action to be taken when a new

watcher is in 'pending'/'waiting' state. The program will un-SUBSCRIBE and

quit when CTRL+D is pressed.

Options:

  -h, --help            show this help message and exit

  -a NAME, --account-name=NAME

                        The account name from which to read account settings.

                        Corresponds to section Account_NAME in the

                        configuration file. If not supplied, the section

                        Account will be read.

  --sip-address=SIP_ADDRESS

                        SIP address of the user in the form user@domain

  -p PASSWORD, --password=PASSWORD

                        Password to use to authenticate the local account.

                        This overrides the setting from the config file.

  -n DISPLAY_NAME, --display-name=DISPLAY_NAME

                        Display name to use for the local account. This

                        overrides the setting from the config file.

  -e EXPIRES, --expires=EXPIRES

                        "Expires" value to set in SUBSCRIBE. Default is 300

                        seconds.

  -o IP[:PORT], --outbound-proxy=IP[:PORT]

                        Outbound SIP proxy to use. By default a lookup of the

                        domain is performed based on SRV and A records. This

                        overrides the setting from the config file.

  -x XCAP_ROOT, --xcap-root=XCAP_ROOT

                        The XCAP root to use to access the pres-rules document

                        for authorizing subscriptions to presence.

  -s, --trace-sip       Dump the raw contents of incoming and outgoing SIP

                        messages (disabled by default).

  -l, --log-pjsip       Print PJSIP logging output (disabled by default).

}}}

=== Example ===

{{{

adigeo@ag-imac3:~/work/pypjua$sip_subscribe_winfo

Accounts available: 'alice', 'bob', 'ew', 'mrg', 'pbx', 'tf', 'umts', 'unet', default

Using default account: 31208005169@ag-projects.com

Resolved DNS SRV record "_sip._udp.ag-projects.com" --> proxy.sipthor.net:5060

Resolved DNS A record "proxy.sipthor.net" --> 85.17.186.7, 81.23.228.150, 81.23.228.129

Retrieving current presence rules from https://xcap.sipthor.net/xcap-root/

Allowed list:

	sip:2233350608@sip2sip.info

	sip:31208005163@ag-projects.com

	sip:31208005166@ag-projects.com

	sip:31208005167@ag-projects.com

	sip:adi@umts.ro

	sip:alice@example.com

	sip:ruud@umts.ro

	sip:317105169@eurovoice.ro

Blocked list:

Polite-blocked list:

Subscribing to "31208005169@ag-projects.com" for the presence.winfo event, at 81.23.228.129:5060

Received NOTIFY:

----

Active watchers:

Terminated watchers:

Pending watchers:

  sip:bob@example.com

Waiting watchers:

----

pending watcher sip:bob@example.com wants to subscribe to your presence information. Press (a) to allow, (d) to deny, (p) to polite block:

Watcher sip:bob@example.com is now allowed

}}}