135 lines
5.5 KiB
C
135 lines
5.5 KiB
C
/*
|
|
* Copyright (C) 2009 Mamadou Diop.
|
|
*
|
|
* Contact: Mamadou Diop <diopmamadou@yahoo.fr>
|
|
*
|
|
* This file is part of Open Source Doubango Framework.
|
|
*
|
|
* DOUBANGO is free software: you can redistribute it and/or modify
|
|
* it under the terms of the GNU General Public License as published by
|
|
* the Free Software Foundation, either version 3 of the License, or
|
|
* (at your option) any later version.
|
|
*
|
|
* DOUBANGO is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
* GNU Lesser General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU General Public License
|
|
* along with DOUBANGO.
|
|
*
|
|
*/
|
|
/**@file txc_document.c
|
|
* @brief <a href="http://tools.ietf.org/html/rfc4825#section-6.2">RFC 4825 subclause 6.2. Document Selector</a>
|
|
*
|
|
* @author Mamadou Diop <diopmamadou(at)yahoo.fr>
|
|
*
|
|
* @date Created: Sat Nov 8 16:54:58 2009 mdiop
|
|
*/
|
|
|
|
#include "txc_document.h"
|
|
#include "txc_macros.h"
|
|
|
|
/**@defgroup txc_document_group XCAP Document selector
|
|
*/
|
|
|
|
|
|
/**@page txc_document_page XCAP document selector Tutorial
|
|
*
|
|
* @par Settings<br>
|
|
* @a XCAP-ROOT = http://xcap.example.com:8080/services <br>
|
|
* @a XUI = sip:doubango@example.com <br>
|
|
*
|
|
* <H2>== Change resource-list default document name for a given XCAP context==</H2>
|
|
* @code
|
|
#include "txc_api.h"
|
|
|
|
txc_auid_update(context, ietf_resource_lists, "rlist.xml");
|
|
* @endcode
|
|
*
|
|
* <H2>== Well-known document selector ==</H2>
|
|
* A document is named well-known if we can retrieve it's selctor URI (name, auid and scope) from its AUID.
|
|
* For example, from xcap-caps AUID we know that the document's name should be 'default' within the 'global' scope.
|
|
* It is possible to change a default document name using @ref txc_auid_update function.
|
|
*
|
|
* IETF server capabilities
|
|
* @code
|
|
#include "txc_api.h"
|
|
|
|
char *url = TXC_DOC_GET_SEL(context, ietf_xcap_caps);
|
|
printf("Server capabilities url: \n%s\n***\n", url);
|
|
TSK_FREE(url);
|
|
* @endcode
|
|
* @a Output: http://xcap.example.com:8080/services/xcap-caps/global/index
|
|
*
|
|
* IETF resource-list
|
|
* @code
|
|
#include "txc_api.h"
|
|
|
|
char *url = TXC_DOC_GET_SEL(context, ietf_resource_lists);
|
|
printf("IETF resource-list: \n%s\n***\n", url);
|
|
TSK_FREE(url);
|
|
* @endcode
|
|
* @a Output: http://xcap.example.com:8080/services/resource-lists/users/sip:doubango@example.com/index
|
|
*
|
|
* <H2>== Custom document selector ==</H2>
|
|
* A custom document selctor can be full or semi custom.
|
|
* Keep in mind that it is possible to change a default document name using @ref txc_auid_update function.
|
|
*
|
|
* <H3>=== Semi-custom document selector ===</H3>
|
|
* For semi-custom document selector, only the document's name is set by the user:
|
|
* @code
|
|
#include "txc_api.h"
|
|
|
|
char *url = TXC_DOC_GET_SEL2(context, ietf_resource_lists, "usr-doc");
|
|
printf("semi-custom document selector: \n%s\n***\n", url);
|
|
TSK_FREE(url);
|
|
* @endcode
|
|
* @a Output: http://xcap.example.com:8080/services/resource-lists/users/sip:doubango@example.com/usr-doc
|
|
|
|
* <H3>=== Full custom selector ===</H3>
|
|
* For full-custom document selector, all members (xcap-root, auid, scope and document name) are set by the user:
|
|
* @code
|
|
#include "txc_api.h"
|
|
|
|
char *url = txc_doc_get_cust_sel("http://usr-root", "usr-auid", "usr-xui", "usr-doc");
|
|
printf("full-custom document selector: \n%s\n***\n", url);
|
|
TSK_FREE(url);
|
|
* @endcode
|
|
* @a Output: http://usr-root/usr-auid/users/usr-xui/usr-doc
|
|
*/
|
|
|
|
/**@ingroup txc_document_group
|
|
* Create a custom XCAP document selector URI as per <a href="http://tools.ietf.org/html/rfc4825#section-6.2">RFC 4825 subclause 6.2</a>
|
|
* @param xcaproot The XCAP Root URI. A context that contains all the documents across all
|
|
* application usages and users that are managed by the server. For more information see <a href="http://tools.ietf.org/html/rfc4825#section-4">RFC 4825 subclause 4</a>
|
|
* @param auid The Application Unique ID. unique identifier within the namespace of application unique IDs created by this specification
|
|
* that differentiates XCAP resources accessed by one application from XCAP resources accessed by another.
|
|
* For more information see <a href="http://tools.ietf.org/html/rfc4825#section-4">RFC 4825 subclause 4</a>
|
|
* @param xui The XCAP User Identifier. The XUI is a string, valid as a path element in an HTTP URI, that is associated with each user served
|
|
* by the XCAP server. For more information see <a href="http://tools.ietf.org/html/rfc4825#section-4">RFC 4825 subclause 4</a>.
|
|
* For global document, this parameter must be NULL or equal to "global"
|
|
* @param name The document name.
|
|
* @retval The HTTP URI containing the XCAP root and document selector, resulting in the selection of a specific document. As a
|
|
result, performing a GET against the document URI would retrieve the document.
|
|
* If supplied parameters are not valide this method will return NULL.
|
|
* You must free the returned string using TSK_FREE or TSK_SAFE_FREE.
|
|
* @sa @ref TXC_DOC_GET_SEL and @ref TXC_DOC_GET_SEL2
|
|
*/
|
|
char* txc_doc_get_cust_sel(const char *xcaproot, const char *auid, const char *xui, const char *name)
|
|
{
|
|
char *selector = 0;
|
|
|
|
if(!xcaproot || !auid || !name) return 0;
|
|
|
|
if(!xui || tsk_striequals("global", xui))
|
|
{ /* xdm-root/auid-name/global/doc-name */
|
|
tsk_sprintf(&selector, "%s/%s/global/%s", xcaproot, auid, name);
|
|
}
|
|
else
|
|
{ /* xdm-root/auid-name/users/xui/doc-name */
|
|
tsk_sprintf(&selector, "%s/%s/users/%s/%s", xcaproot, auid, xui, name);
|
|
}
|
|
|
|
return selector;
|
|
} |