tinyXCAP API Overview

1.0

16 XCAP

The XCAP Framework is mainly based on RFC 4825 and uses tinyHTTP project. The framework can be used to implements advanced OMA functionalities such Enhanced Address Book, Presence Authorization Rules, Service Configuration … At startup the stack will load all supported AUIDs with their default values.

16.1 Initialization

As the XCAP stack depends on the HTTP/HTTPS stack (tinyHTTP) which uses the network library (<a href="http://www.doubango.org/API/tinyNET/"tinyNET), you MUST call tnet_startup() before using any XCAP function (txcap_*).
tnet_cleanup() is used to terminate use of network functions.
The example below demonstrates how to create and start a XCAP stack. In this example, the xcap-root URI is http://doubango.org:8080/services and the SIP AOR (used as XUI) is sip:bob@doubango.org.

txcap_stack_handle_t* stack = tsk_null;
int ret;

tnet_startup();

stack = txcap_stack_create(test_stack_callback, "sip:bob@doubango.org", "mysecret", "http://doubango.org:8080/services",
        
        // options
        TXCAP_STACK_SET_OPTION(TXCAP_STACK_OPTION_TIMEOUT, "6000"),

        // stack-level headers (not mandatory)
        TXCAP_STACK_SET_HEADER("Pragma", "No-Cache"),
        TXCAP_STACK_SET_HEADER("Connection", "Keep-Alive"),
        TXCAP_STACK_SET_HEADER("X-3GPP-Intended-Identity", "sip:bob@doubango.org"),
        TXCAP_STACK_SET_HEADER("User-Agent", "XDM-client/OMA1.1"),
        TXCAP_STACK_SET_NULL());

if((ret = txcap_stack_start(stack))){
        goto bail;
}

// …………

bail:
        TSK_OBJECT_SAFE_FREE(stack);
tnet_cleanup();

The stack-level headers will be added in all outgoing requests. A stack is a well-defined object and must be destroyed by using TSK_OBJECT_SAFE_FREE() macro. The stack will be automatically stopped when destroyed.

16.2 Application Unique ID (AUID) object

An AUID object is defined by:

An id (e.g. “xcap-caps”),
A MIME-Type (e.g. “application/xcap-caps+xml”),
A namespace (e.g. “urn:ietf:params:xml:ns:xcap-caps”),
A document name (e.g. “index”), which defines the name of the default document associated with this AUID
A scope (“global” or “users”)

At startup, the stack will load all supported AUIDs with their default values. You can at any time change these values or register your own AUID object. The list of default AUIDs with their default values are shown in the next sections. When you are about to send a request, it’s not mandatory to use a registered AUID but it’s easier to generate the selector as all parameters are pre-configured.

16.2.1 Default AUIDs

The table below shows the default AUIDs as they are defined by the stack at startup.

MIME-Type

Namespace

Document

Scope

Reference

xcap-caps

application/xcap-caps+xml

urn:ietf:params:xml:ns:xcap-caps

index

global

RFC 4825 section 12.1

resource-lists

application/resource-lists+xml

urn:ietf:params:xml:ns:resource-lists

index

users

RFC 4826 section 3.4.1

rls-services

application/rls-services+xml

urn:ietf:params:xml:ns:rls-services"

index

users

RFC 4826 section 4.4.1

pres-rules

application/auth-policy+xml

urn:ietf:params:xml:ns:pres-rules

index

users

RFC 5025 section 9.1

org.openmobilealliance.pres-rules

application/auth-policy+xml

urn:ietf:params:xml:ns:common-policy

pres-rules

users

[OMA-TS-Presence_SIMPLE_XDM-V1_1-20080627-A] section 5.1.1.2

16.2.2 AUID registration

=== The code below shows how to register two AUIDs. If the AUID object already exist (case-insensitive comparison on the id), then it will be updated. All fields are mandatory (id, mime-type, namespace, document and scope).

txcap_stack_set(stack,
        TXCAP_STACK_SET_AUID("my-xcap-caps", "application/my-xcap-caps+xml", "urn:ietf:params:xml:ns:my-xcap-caps", "my-document", tsk_true),
        TXCAP_STACK_SET_AUID("my-resource-lists", "application/my-resource-lists+xml", "urn:ietf:params:xml:ns:my-resource-lists", "my-document", tsk_false),
        
        TXCAP_STACK_SET_NULL()); // mandatory

The stack should be created as shown at section 16.1. Only AUIDs which don’t appear in the table above should be registered using this method

16.3 Selector

The selector is a helper function which could be used to construct XCAP URIs. XCAP URI is constructed as per RFC 4825 section 6. TXCAP_SELECTOR_NODE_SET*() macros are used to build a complete and well-formed URI (already percent encoded). All examples below assume that our AOR (used as XUI) is sip:bob@doubango.com, we are using the ‘rcs’list and the xcap-root URI is http://doubango.org:8080/services. All these parameters should be set when the stack is created. You will also notice that TXCAP_SELECTOR_NODE_SET_NULL() macro is used to ends the node selection parameters passed to txcap_selector_get_url(), it’s mandatory and should always be the last one.

Select XDMS capabilities:

char* urlstring = txcap_selector_get_url(stack, "xcap-caps",
                TXCAP_SELECTOR_NODE_SET_NULL());
        TSK_DEBUG_INFO("%s\n", urlstring);
        TSK_FREE(urlstring);

Console Output: http://doubango.org:8080/services/xcap-caps/global/index

Select 'resource-lists' document

char* urlstring = txcap_selector_get_url(stack, "resource-lists",
                TXCAP_SELECTOR_NODE_SET_NULL());
TSK_DEBUG_INFO("%s\n", urlstring);
TSK_FREE(urlstring);

Console Output: http://doubango.org:8080/services/resource-lists/users/sip:bob@doubango.org/index

Select 'rcs' list

char* urlstring = txcap_selector_get_url(stack, "resource-lists",
                TXCAP_SELECTOR_NODE_SET_ATTRIBUTE("list", "name", "rcs"),
                TXCAP_SELECTOR_NODE_SET_NULL());
TSK_DEBUG_INFO("%s\n", urlstring);

Console Output: http://doubango.org:8080/services/resource-lists/users/sip:bob@doubango.org/index/~~/resource-lists/list%5B@name=%22rcs%22%5D

Select the 2nd list

char* urlstring = txcap_selector_get_url(stack, "resource-lists",
                TXCAP_SELECTOR_NODE_SET_POS("list", 2),
                TXCAP_SELECTOR_NODE_SET_NULL());
TSK_DEBUG_INFO("%s\n", urlstring);
TSK_FREE(urlstring);

Console Output: http://doubango.org:8080/services/resource-lists/users/sip:bob@doubango.org/index/~~/resource-lists/list%5B2%5D

Select the 4th list using wildcard

urlstring = txcap_selector_get_url(stack, "resource-lists",
                TXCAP_SELECTOR_NODE_SET_POS("*", 4),
                TXCAP_SELECTOR_NODE_SET_NULL());
TSK_DEBUG_INFO("%s\n", urlstring);
TSK_FREE(urlstring);

Console Output: http://doubango.org:8080/services/resource-lists/users/sip:bob@doubango.org/index/~~/resource-lists/*%5B4%5D

Select bob's entry

char* urlstring = txcap_selector_get_url(stack, "resource-lists",
                TXCAP_SELECTOR_NODE_SET_ATTRIBUTE("list", "name", "rcs"),
                TXCAP_SELECTOR_NODE_SET_ATTRIBUTE("entry", "uri", "sip:bob@doubango.com"),
                TXCAP_SELECTOR_NODE_SET_NULL());
TSK_DEBUG_INFO("%s\n", urlstring);
TSK_FREE(urlstring);

Console Output: http://doubango.org:8080/services/resource-lists/users/sip:bob@doubango.org/index/~~/resource-lists/list%5B@name=%22rcs%22%5D/entry%5B@uri=%22sip:bob@doubango.org%22%5D

Select bob’s display-name

char* urlstring = txcap_selector_get_url(stack, "resource-lists",
                TXCAP_SELECTOR_NODE_SET_ATTRIBUTE("list", "name", "rcs"),
                TXCAP_SELECTOR_NODE_SET_ATTRIBUTE("entry", "uri", "sip:bob@doubango.org"),
                TXCAP_SELECTOR_NODE_SET_NAME("display-name"),
                TXCAP_SELECTOR_NODE_SET_NULL());
TSK_DEBUG_INFO("%s\n", urlstring);
TSK_FREE(urlstring);

Console Output: http://doubango.org:8080/services/resource-lists/users/sip:bob@doubango.org/index/~~/resource-lists/list%5B@name=%22rcs%22%5D/entry%5B@uri=%22sip:bob@doubango.org%22%5D/display-name

Select the display-name of the 1st entry

char* urlstring = txcap_selector_get_url(stack, "resource-lists",
                TXCAP_SELECTOR_NODE_SET_ATTRIBUTE("list", "name", "rcs"),
                TXCAP_SELECTOR_NODE_SET_POS("entry", 1),
                TXCAP_SELECTOR_NODE_SET_NAME("display-name"),
                TXCAP_SELECTOR_NODE_SET_NULL());
TSK_DEBUG_INFO("%s\n", urlstring);
TSK_FREE(urlstring);

Console Output: http://doubango.org:8080/services/resource-lists/users/sip:bob@doubango.org/index/~~/resource-lists/list%5B@name=%22rcs%22%5D/entry%5B1%5D/display-name

Select bob from position 23

char* urlstring = txcap_selector_get_url(stack, "resource-lists",
                TXCAP_SELECTOR_NODE_SET_ATTRIBUTE("list", "name", "rcs"),
                TXCAP_SELECTOR_NODE_SET_POS_ATTRIBUTE("entry", 23, "uri", "sip:bob@doubango.org"),
                TXCAP_SELECTOR_NODE_SET_NULL());
TSK_DEBUG_INFO("%s\n", urlstring);
TSK_FREE(urlstring);

Console Output: http://doubango.org:8080/services/resource-lists/users/sip:bob@doubango.org/index/~~/resource-lists/list%5B@name=%22rcs%22%5D/entry%5B23%5D%5B@uri=%22sip:bob@doubango.org%22%5D

Namespaces test

char* urlstring = txcap_selector_get_url(stack, "resource-lists",
                TXCAP_SELECTOR_NODE_SET_NAME("foo"),
                TXCAP_SELECTOR_NODE_SET_NAME("a:bar"),
                TXCAP_SELECTOR_NODE_SET_NAME("b:baz"),
                TXCAP_SELECTOR_NODE_SET_NAMESPACE("a", "urn:namespace1-uri"),
                TXCAP_SELECTOR_NODE_SET_NAMESPACE("b", "urn:namespace2-uri"),
                TXCAP_SELECTOR_NODE_SET_NULL());
TSK_DEBUG_INFO("%s\n", urlstring);
TSK_FREE(urlstring);

Console Output: http://doubango.org:8080/services/resource-lists/users/sip:bob@doubango.org/index/~~/resource-lists/foo/a:bar/b:baz%3Fxmlns(a=%22urn:namespace1-uri%22)xmlns(b=%22urn:namespace2-uri%22)

16.4 XDMC Usage

It is assumed that the address of the XDMS (or aggregation Proxy) is “doubango.org:8080/services” and thus the XCAP Root URI is “doubango.org:8080/services”. “sip:bob@doubango.org” will be used as the XUI. An XDMC can perform twelve actions:

txcap_action_create_element(): Creates new element by sending a HTTP/HTTPS PUT request. The default Content-Type will be “application/xcap-el+xml”, unless you provide your own Content-Type by using TXCAP_ACTION_SET_HEADER().
txcap_action_create_document(): Creates new document by sending a HTTP/HTTPS PUT request. The default Content-Type will be the one associated with the AUID of the document, unless you provide your own Content-Type by using TXCAP_ACTION_SET_HEADER().
txcap_action_create_attribute(): Creates new attribute by sending a HTTP/HTTPS PUT request. The default Content-Type will be “application/xcap-att+xml”, unless you provide your own Content-Type by using TXCAP_ACTION_SET_HEADER().
txcap_action_replace_element(): Replaces an element by sending a HTTP/HTTPS PUT request. The default Content-Type will be “application/xcap-el+xml”, unless you provide your own Content-Type by using TXCAP_ACTION_SET_HEADER().
txcap_action_replace_document(): Replaces a document by sending a HTTP/HTTPS PUT request. The default Content-Type will be the one associated with the AUID of the document, unless you provide your own Content-Type by using TXCAP_ACTION_SET_HEADER().
txcap_action_replace_attribute(): Replaces an attribute by sending a HTTP/HTTPS PUT request. The default Content-Type will be “application/xcap-att+xml”, unless you provide your own Content-Type by using TXCAP_ACTION_SET_HEADER().
txcap_action_fetch_element(): Retrieves an element from the XDMS by sending a HTTP/HTTPS GET request. The default Content-Type will be “application/xcap-el+xml”, unless you provide your own Content-Type by using TXCAP_ACTION_SET_HEADER().
txcap_action_fetch_document(): Retrieves a document from the XDMS by sending a HTTP/HTTPS GET request. The default Content-Type will be the one associated with the AUID of the document, unless you provide your own Content-Type by using TXCAP_ACTION_SET_HEADER().
txcap_action_fetch_attribute(): Retrieves an attribute from the XDMS by sending a HTTP/HTTPS GET request. The default Content-Type will be “application/xcap-att+xml”, unless you provide your own Content-Type by using TXCAP_ACTION_SET_HEADER().
txcap_action_delete_element(): Deletes an element from the XDMS by sending a HTTP/HTTPS DELETE request.
txcap_action_delete_document(): Deletes a document from the XDMS by sending a HTTP/HTTPS DELETE request.
txcap_action_delete_attribute(): Deletes an attribute from the XDMS by sending a HTTP/HTTPS DELETE request.

To understand how the stack is created, please refer to section 16.1.

16.4.1 Retrieving XDMS capabilities

=== The code below shows how an XDMC obtains the XDMS capabilities document.

int ret = txcap_action_fetch_document(stack,
                // selector
                TXCAP_ACTION_SET_SELECTOR("xcap-caps",
                        TXCAP_SELECTOR_NODE_SET_NULL()),
                // ends parameters
                TXCAP_ACTION_SET_NULL()
                );

The XDMC will send:

GET /services/xcap-caps/global/index HTTP/1.1
Host: doubango.org:8080
Connection: Keep-Alive
User-Agent: XDM-client/OMA1.1
X-3GPP-Intended-Identity: sip:bob@doubango.org
Content-Type: application/xcap-caps+xml

16.4.2 Address Book

=== The code below shows how an XDMC obtains URI Lists (Address Book).

int ret = txcap_action_fetch_document(stack,
                // action-level options
                TXCAP_ACTION_SET_OPTION(TXCAP_ACTION_OPTION_TIMEOUT, "6000"),
                //action-level headers
                TXCAP_ACTION_SET_HEADER("Pragma", "No-Cache"),
                // selector
                TXCAP_ACTION_SET_SELECTOR("resource-lists",
                        TXCAP_SELECTOR_NODE_SET_NULL()),
                // ends parameters
                TXCAP_ACTION_SET_NULL()
                );

The XDMC will send:

GET /services/resource-lists/users/sip:bob@doubango.org/index HTTP/1.1
Host: doubango.org:8080
Connection: Keep-Alive
User-Agent: XDM-client/OMA1.1
X-3GPP-Intended-Identity: sip:bob@doubango.org
Pragma: No-Cache
Content-Type: application/resource-lists+xml

=== The code below shows how to add a new list to the address book

int ret = txcap_action_create_element(stack,
                // selector
                TXCAP_ACTION_SET_SELECTOR("resource-lists",
                        TXCAP_SELECTOR_NODE_SET_ATTRIBUTE("list", "name", "newlist"),
                        TXCAP_SELECTOR_NODE_SET_NULL()),
                // payload
                TXCAP_ACTION_SET_PAYLOAD(PAYLOAD, strlen(PAYLOAD)),
                // ends parameters
                TXCAP_ACTION_SET_NULL()
                );

The XDMC will send:

PUT /services/resource-lists/users/sip:bob@doubano.org/index/~~/resource-lists/list\%5B\@name=\%22newlist\%22\%5D HTTP/1.1
Host: doubango.org:8080
Content-Length: 110
Connection: Keep-Alive
User-Agent: XDM-client/OMA1.1
X-3GPP-Intended-Identity: sip:bob@doubango.org
Content-Type: application/xcap-el+xml

<list name="newlist" xmlns="urn:ietf:params:xml:ns:resource-lists"><display-name>newlist</display-name></list>

=== The code below shows how to retrieve the previously added list

int ret = txcap_action_fetch_element(stack,
                // action-level selector
                TXCAP_ACTION_SET_SELECTOR("resource-lists",
                        TXCAP_SELECTOR_NODE_SET_ATTRIBUTE("list", "name", "newlist"),
                        TXCAP_SELECTOR_NODE_SET_NULL()),
                // ends parameters
                TXCAP_ACTION_SET_NULL()
                );

The XDMC will send:

GET /services/resource-lists/users/sip:bob@doubango.org/index/~~/resource-lists/list\%5B\@name=\%22newlist\%22\%5D HTTP/1.1
Host: doubango.org:8080
Connection: Keep-Alive
User-Agent: XDM-client/OMA1.1
X-3GPP-Intended-Identity: sip:bob@doubango.org
Content-Type: application/xcap-el+xml

=== The code below shows how to add a new entry (“sip:alice@doubango.org”) to the previously added list

int ret = txcap_action_create_element(stack,
                // selector
                TXCAP_ACTION_SET_SELECTOR("resource-lists",
                        TXCAP_SELECTOR_NODE_SET_ATTRIBUTE("list", "name", "newlist"),
                        TXCAP_SELECTOR_NODE_SET_ATTRIBUTE("entry", "uri", “sip:alice@doubango.org”),
                        TXCAP_SELECTOR_NODE_SET_NULL()),
                // payload
                TXCAP_ACTION_SET_PAYLOAD(PAYLOAD, strlen(PAYLOAD)),
                // ends parameters
                TXCAP_ACTION_SET_NULL()
                );

The XDMC will send:

PUT /services/resource-lists/users/sip:bob@doubango.org/index/~~/resource-lists/list\%5B\@name=\%22newlist\%22\%5D/entry\%5B\@uri=\%22sip:alice@doubango.org\%22\%5D HTTP/1.1
Host: doubango.org:8080
Content-Length: 125
Connection: Keep-Alive
User-Agent: XDM-client/OMA1.1
X-3GPP-Intended-Identity: sip:bob@doubango.org
Content-Type: application/xcap-el+xml

<entry uri="sip:alice@doubango.org" xmlns="urn:ietf:params:xml:ns:resource-lists"><display-name>alice</display-name></entry>

16.4.3 Obtaining Presence Content Document

=== The code below shows how an XDMC obtains the Presence Content document (avatar).

int ret = txcap_action_fetch_document(stack,
                // action-level options
                TXCAP_ACTION_SET_OPTION(TXCAP_ACTION_OPTION_TIMEOUT, "6000"),
                //action-level headers
                TXCAP_ACTION_SET_HEADER("Pragma", "No-Cache"),
                // selector
                TXCAP_ACTION_SET_SELECTOR("org.openmobilealliance.pres-content",
                        TXCAP_SELECTOR_NODE_SET_NULL()),
                // ends parameters
                TXCAP_ACTION_SET_NULL()
                );

The XDMC will send:

GET /services/org.openmobilealliance.pres-content/users/sip:mamadou@micromethod.com/oma_status-icon/rcs_status_icon HTTP/1.1
Host: doubango.org:8080
Connection: Keep-Alive
User-Agent: XDM-client/OMA1.1
X-3GPP-Intended-Identity: sip:bob@doubango.org
Pragma: No-Cache
Content-Type: application/vnd.oma.pres-content+xml