# RLS and XCAP

## Used terms

###

RLS

  Resource List Server - server processing subscriptions to special URIs (RL-URIs) which represent more resources than only one like "normal URIs".

RL-URI

  Resource list URI. URI which represents a list of resources instead of a single user.

## Processing subscriptions

Specification says that each time a SUBSCRIBE request to a RL-URI comes, RLS has to ask XCAP server for coresponding <service> in default rls-services document. The XCAP query in this case is for document like <xcap-root>/rls-services/global/index/~~/rls-services/service[@uri=%22<AOR>%22]. Returned <service> is processed according to specification then and the result of it is flat list of URIs to subscribe to.

This processing has its weaknesses.

- In case of such processing is one <service> element in rls-services needed for every user who wants to have his buddies stored on XCAP server. Such <service> will (for user's records) mostly point into his resource-lists document and thus another XCAP query for result list is needed.

- Another problem is, that each user has to modify global rls-services document. This is security problem and there is no client software doing this itself. [Exists something?]

These reasons lead to separation of resource lists into "global lists" and "users lists".

Global lists are not stored/modified by regular users; they are managed by administrators and they are handled according the draft. Example of such lists may be "technical support", "human resources", ...

Resource lists for users are stored only in their resource-lists documents and the <service> element in global rls-services document is ommited (it is implicit). In this case RLS reads directly user's resource-lists document instead of trying to find it in global rls-services document.

## Global resource lists

As said above, resources described in rls-services documents are global resources accessible by all users. No regular user should have acces rights to modify global rls-services document on XCAP server.

### rls-services document URI

The construction of rls-services document URI is described in . Only in short: the AOR from SIP SUBSCRIBE request is combined with XCAP root given in configuration like this:

`<xcap-root>/rls-services/global/index/~~/rls-services/service[@uri=%22<AOR>%22]`.

This URI doesn't not specify namespaces as mentioned in definition, but this is due to problems with XCAP server used for tests (problems querying parts of documents with namespaces).

#### rls-services uri example

Let us assume

- `xcap-root` = `http://localhost/xcap-root`

- `AOR of SUBSCRIBE request` = `sip:technical-support@someorg.org`

Resulting document describing the list will be get from URI: `http://localhost/xcap-root/rls-services/global/index/~~/rls-services/service[@uri=%22<technical-support@someorg.org>%22]`, which means the `service` element with `uri` parameter value `technical-support@someorg.org` stored in rls-services document named index.

### rls-services document

There is example rls-services document describing resources technical-support@test-domain.com, hr@test-domain.com and work@test-domain.com which puts previous two into itself. This document should be stored on xcap server in file <xcap-root>/rls-services/global/index.

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

    	<service uri="sip:technical-support@test-domain.com">
    		<list name="Our technical support">
    			<entry uri="sip:smith@test-domain.com">
    				<display-name>Smith</display-name>
    			</entry>
    			<entry uri="sip:joe@test-domain.com">
    				<display-name>Joe</display-name>
    			</entry>
    			<entry uri="sip:agatha@test-domain.com">
    				<display-name>Agatha</display-name>
    			</entry>
    		</list>
    		<packages>
    			<package>presence</package>
    		</packages>
    	</service>

    	<service uri="sip:hr@test-domain.com">
    		<list name="Human resources">
    			<entry uri="sip:johny@test-domain.com">
    				<display-name>Johny V</display-name>
    			</entry>
    			<entry uri="sip:joe@test-domain.com">
    				<display-name>Joe</display-name>
    			</entry>
    		</list>
    		<packages>
    			<package>presence</package>
    		</packages>
    	</service>

    	<service uri="sip:work@test-domain.com">
    		<list name="Employee resources">
    			<entry uri="sip:technical-support@test-domain.com">
    				<display-name>Technical support</display-name>
    			</entry>
    			<entry uri="sip:hr@test-domain.com">
    				<display-name>Human resources</display-name>
    			</entry>
    		</list>
    		<packages>
    			<package>presence</package>
    		</packages>
    	</service>

    </rls-services>

### Disadvantages

Working with URIs presented in this section have one big disadvantage - it needs full XCAP server which is able to work with partial documents and able to process XPointer expressions in XCAP queries.

Due to unavailability of free XCAP servers is there a possibility to use SER's RLS server in mode of reduced XCAP server needs (see RLS module parameters). If operating in this mode, RLS requests full rls-service document from uri `<xcap-root>/rls-services/global/index`, inspects it and finds requested resource list according to URI and AOR by itself. (Only if possible! There can't be links to partial documents in rls-services document.)

## User's resource lists

Opposite to global resource lists are resource lists of standalone users. As was told above, these lists are stored as resource-lists documents under user's directories. These resource-lists documents are accessed directly without searching for them in rls-services document - they behave like if they have implicit link there.

### User's resource lists

Let us assume

- xcap root = http://localhost/xcap-root

- user smith (sends SUBSCRIBE with smith@... in From URI)

- Smith's UUID = smith

The document below for user Smith can be stored on XCAP server in http://localhost/xcap-root/resource-lists/users/smith/resource-lists.xml. It contains two resource lists: default and contacts.

    <?xml version="1.0" encoding="UTF-8"?>
    <resource-lists
       xmlns="urn:ietf:params:xml:ns:resource-lists"
    >
      <list name="default">
        <display-name>Buddy List</display-name>
        <entry uri="sip:joe@test-domain.com">
          <display-name>Joe</display-name>
        </entry>
        <entry uri="sip:jan@test-domain.com">
          <display-name>Jan</display-name>
        </entry>
      </list>

      <list name="contacts">
        <display-name>Contact List</display-name>
        <entry uri="sip:alois@test-domain.com">
          <display-name>Alois</display-name>
        </entry>
      </list>

    </resource-lists>

## Standard incompliances

SER's resource lists support is not finished yet, there are some standard incompliances now:

- uri canonicalization not done yet according to definition

- full status documents only