SIP SIMPLE Client SDK

== xcapclient ==

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

=== Description ===

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

XCAP protocol, defined in RFC 4825, allows a client to read, write, and

modify application configuration data stored in XML format on a server. XCAP

maps XML document sub-trees and element attributes to HTTP URIs, so that

these components can be directly accessed by HTTP. An XCAP server used by

XCAP clients to store data like presence policy in combination with a SIP

Presence server that supports PUBLISH/SUBSCRIBE/NOTIFY SIP methods can

provide a complete SIP SIMPLE solution.

This XCAP  client is part of python-xcaplib package provided by [http://openxcap.org OpenXCAP] server. If you have installed bash_completion.d/xcapclient  you can use TAB completion to browse through the content of the XCAP server documents/nodes/atributes. For more information read the documentation that comes with the package.

{{{

adigeo@ag-imac3:~$xcapclient -h

  xcapclient: Client for managing full or partial XML documents on XCAP servers (RFC 4825)

  xcapclient [OPTIONS] --app AUID ACTION [NODE-SELECTOR]

  ACTION is an operation to perform: get, replace, insert, put or delete.

  Presence of NODE-SELECTOR indicates that action is to be performed on an

  element or an attribute.

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.

  --show-config          show options from the configuration file; use

                         together with --account-name

  --xcap-root=XCAP_ROOT  XCAP root, e.g. https://xcap.example.com/xcap-root

  --sip-address=SIP_ADDRESS

                         SIP address of the user in the form username@domain

  -p PASSWORD, --password=PASSWORD

                         password to use if authentication is required. If not

                         supplied will be asked interactively

  --app=AUID             Application Unique ID. There's no default value;

                         however, it may be guessed from NODE-SELECTOR or from

                         the input file. Known apps: watchers, pidf-

                         manipulation, rls-services, resource-lists, xcap-

                         caps, pres-rules, test-app

  --filename=FILENAME    

  -c CONTEXT, --context=CONTEXT

                         document context, users or global; default is users

                         for everything except xcap-caps

  --etag=ETAG            perform a conditional operation

  -i INPUT_FILENAME      source file for the PUT request; default is <stdin>

  -o OUTPUT_FILENAME     output file for the body of the server response

                         (successful or not); default is <stdout>

  -d, --dump             print HTTP traffic to stderr

}}}

=== Example for XCAP server capabilities (xcap-caps)  === 

{{{

adigeo@ag-imac3:~$xcapclient -a alice --app xcap-caps GET

get https://xcap.sipthor.net/xcap-root/xcap-caps/global/index

etag: "ab12efdd1aff88296deee1aa195b823e"

content-type: application/xcap-caps+xml

content-length: 826

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

<xcap-caps xmlns='urn:ietf:params:xml:ns:xcap-caps'>

<auids>

<auid>watchers</auid>

<auid>org.openmobilealliance.pres-rules</auid>

<auid>rls-services</auid>

<auid>pidf-manipulation</auid>

<auid>xcap-caps</auid>

<auid>test-app</auid>

<auid>resource-lists</auid>

<auid>pres-rules</auid>

</auids>

<extensions>

</extensions>

<namespaces>

<namespace>http://openxcap.org/ns/watchers</namespace>

<namespace>urn:ietf:params:xml:ns:pres-rules</namespace>

<namespace>urn:ietf:params:xml:ns:rls-services</namespace>

<namespace>urn:ietf:params:xml:ns:pidf</namespace>

<namespace>urn:ietf:params:xml:ns:xcap-caps</namespace>

<namespace>test-app</namespace>

<namespace>urn:ietf:params:xml:ns:resource-lists</namespace>

<namespace>urn:ietf:params:xml:ns:pres-rules</namespace>

</namespaces>

</xcap-caps>

}}}

=== Example for pres-rules XCAP document ===

==== PUT ====

{{{

adigeo@ag-imac3:~$xcapclient -a alice PUT -i work/python-xcaplib/examples/pres-rules.xml 

put https://xcap.sipthor.net/xcap-root/pres-rules/users/sip:alice@example.com/index

201 Created

etag: "345ba7c1ce125b2ff2438c19b25b4077"

content-type: application/auth-policy+xml

}}}

==== GET ====

{{{

adigeo@ag-imac3:~$xcapclient -a alice --app pres-rules get 

get https://xcap.sipthor.net/xcap-root/pres-rules/users/sip:alice@example.com/index

etag: "345ba7c1ce125b2ff2438c19b25b4077"

content-type: application/auth-policy+xml

content-length: 939

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

<ruleset xmlns="urn:ietf:params:xml:ns:common-policy" xmlns:pr="urn:ietf:params:xml:ns:pres-rules" xmlns:cp="www.counterpath.com/privacy-lists">

<rule id="pres_whitelist">

<conditions>

<identity>

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

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

<many domain="ag-projects.com">

</many>

</identity>

</conditions>

<actions>

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

</actions>

<transformations>

<pr:provide-services>

<pr:all-services/>

</pr:provide-services>

<pr:provide-persons>

<pr:all-persons/>

</pr:provide-persons>

<pr:provide-devices>

<pr:all-devices/>

</pr:provide-devices>

<pr:provide-all-attributes/>

</transformations>

</rule>

<rule id="pres_blacklist">

<conditions>

<identity>

<one id="sip:40316600024@abc.com"/>

</identity>

</conditions>

<actions>

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

</actions>

<transformations/>

</rule>

</ruleset>

}}}

==== DELETE ====

{{{

adigeo@ag-imac3:~$xcapclient -a alice --app pres-rules DELETE

delete https://xcap.sipthor.net/xcap-root/pres-rules/users/sip:alice@example.com/index

200 OK

content-type: application/auth-policy+xml

}}}

=== Example for resource-lists XCAP document ===

==== PUT ====

{{{

adigeo@ag-imac3:~$xcapclient -a alice PUT -i work/python-xcaplib/examples/resource-lists.xml 

put https://xcap.sipthor.net/xcap-root/resource-lists/users/sip:alice@example.com/index

201 Created

etag: "f8c47352d61b5b256ee80d964e03efd6"

content-type: application/resource-lists+xml

}}}

==== GET ====

{{{

adigeo@ag-imac3:~$xcapclient -a alice --app resource-lists GET

get https://xcap.sipthor.net/xcap-root/resource-lists/users/sip:alice@example.com/index

etag: "f8c47352d61b5b256ee80d964e03efd6"

content-type: application/resource-lists+xml

content-length: 991

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

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

    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <list name="friends">

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

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

     </entry>

     <entry-ref ref="resource-lists/users/sip:bill@example.com/index/~~/resource-lists/list%5b@name=%22list1%22%5d/entry%5b@uri=%22sip:petri@example.com%22%5d"/>

     <list name="close-friends">

      <display-name>Close Friends</display-name>

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

       <display-name>Joe Smith</display-name>

      </entry>

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

       <display-name>Nancy Gross</display-name>

      </entry>

      <external anchor="http://xcap.example.org/resource-lists/users/sip:a@example.org/index/~~/resource-lists/list%5b@name=%22mkting%22%5d">

        <display-name>Marketing</display-name>

       </external>

     </list>

    </list>

   </resource-lists>

}}}

==== DELETE ====

{{{

adigeo@ag-imac3:~$xcapclient -a alice --app resource-lists DELETE

delete https://xcap.sipthor.net/xcap-root/resource-lists/users/sip:alice@example.com/index

200 OK

content-type: application/resource-lists+xml

adigeo@ag-imac3:~$

}}}

=== Example for rls-services XCAP document ===

==== PUT ====

{{{

adigeo@ag-imac3:~$xcapclient -a alice PUT -i work/python-xcaplib/examples/rls-services.xml 

put https://xcap.sipthor.net/xcap-root/rls-services/users/sip:alice@example.com/index

201 Created

etag: "44f5fca1b08352815ee12f1a0c32d812"

content-type: application/rls-services+xml

}}}

==== GET ====

{{{

adigeo@ag-imac3:~$xcapclient -a alice --app rls-services GET

get https://xcap.sipthor.net/xcap-root/rls-services/users/sip:alice@example.com/index

etag: "44f5fca1b08352815ee12f1a0c32d812"

content-type: application/rls-services+xml

content-length: 797

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

   <rls-services xmlns="urn:ietf:params:xml:ns:rls-services"

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

      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

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

     <resource-list>https://xcap.example.com/xcap-root/resource-lists/users/sip:alice@example.com/index/~~/resource-lists/list%5b@name=%22l1%22%5d</resource-list>

     <packages>

      <package>presence</package>

     </packages>

    </service>

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

      <list name="marketing">

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

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

      </list>

      <packages>

        <package>presence</package>

      </packages>

    </service>

   </rls-services>

}}}

==== DELETE ====

{{{

adigeo@ag-imac3:~$xcapclient -a alice --app rls-services DELETE

delete https://xcap.sipthor.net/xcap-root/rls-services/users/sip:alice@example.com/index

200 OK

content-type: application/rls-services+xml

}}}