modules_k/presence, modules_k/presence_xml: Added new exported functions to enable the online status of a user to be checked

- Exported two new API functions from presence (get_presentity() and
  free_presentity()). These functions are used by the new exported
  functions.

- Added two new exported functions to presence_xml. pres_check_basic()
  enables you to find out whether a users basic status matches the
  string you provide. pres_check_activities() enables you to find out
  whether any of a users listed activities matches the string you
  provide.

  pres_check_basic() effectively lets you tell whether a user is
  online or offline (based on presence). pres_check_activities()
  lets you see what a user is currently doing (for example, is the
  user too busy to take a call?).

  The results from these exported functions can be used to make
  routing decisions. For example, you can choose not to route calls
  to users who are away or busy.

modules_k/presence/README

@@ -83,6 +83,8 @@ Juha Heinanen
         13. get_event_list
         14. update_watchers_status
         15. get_sphere
+        16. get_presentity
+        17. free_presentity
 
    List of Examples
 
@@ -647,6 +649,8 @@ Chapter 2. Developer Guide
    13. get_event_list
    14. update_watchers_status
    15. get_sphere
+   16. get_presentity
+   17. free_presentity
 
    The module provides the following functions that can be used in other
    Kamailio modules.
@@ -911,3 +915,30 @@ typedef char* (*pres_get_sphere_t)(str* pres_uri);
    This function searches for a sphere definition in the published
    information if this has type RPID. If not found returns NULL. (the
    return value is allocated in private memory and should be freed)
+
+16.  get_presentity
+
+   Field type:
+...
+typedef str* (*pres_get_presentity_t)(str pres_uri, pres_ev_t *ev, str *etag, st
+r *contact);
+...
+
+   This function returns a pointer to a str containing an XML document
+   with all of the matching presentities. If no matching presentities are
+   found the function returns NULL.
+
+   The etag and contact parameters are optional and may be set to NULL.
+   Once you are finished with the presentity document you must call
+   free_presentity to free the allocated memory.
+
+17.  free_presentity
+
+   Field type:
+...
+typedef void (*pres_free_presentity_t)(str *presentity, pres_ev_t *ev);
+...
+
+   This function frees memory allocated by a call to get_presentity. The
+   ev parameter MUST point to the same pres_ev_t data-structure that was
+   used in the call to get_presentity.

modules_k/presence/bind_presence.c

@@ -40,6 +40,7 @@
 #include "../../sr_module.h"
 #include "presence.h"
 #include "bind_presence.h"
+#include "notify.h"
 
 int bind_presence(presence_api_t* api)
 {
@@ -63,6 +64,8 @@ int bind_presence(presence_api_t* api)
 	api->update_db_subs= update_db_subs;
 	api->extract_sdialog_info= extract_sdialog_info;
 	api->get_sphere= get_sphere;
+	api->get_presentity= get_p_notify_body;
+	api->free_presentity= free_notify_body;
 	return 0;
 }
 

modules_k/presence/bind_presence.h

@@ -40,6 +40,8 @@
 #include "presentity.h"
 
 typedef int (*update_watchers_t)(str pres_uri, pres_ev_t* ev, str* rules_doc);
+typedef str* (*pres_get_presentity_t)(str pres_uri, pres_ev_t *ev, str *etag, str *contact);
+typedef void (*pres_free_presentity_t)(str *presentity, pres_ev_t *ev);
 
 typedef struct presence_api {
 	add_event_t add_event;
@@ -58,6 +60,8 @@ typedef struct presence_api {
 	update_db_subs_t update_db_subs;
 	extract_sdialog_info_t extract_sdialog_info;
 	pres_get_sphere_t get_sphere;
+	pres_get_presentity_t get_presentity;
+	pres_free_presentity_t free_presentity;
 } presence_api_t;
 
 int bind_presence(presence_api_t* api);

modules_k/presence/doc/presence_devel.xml

@@ -399,5 +399,50 @@ typedef char* (*pres_get_sphere_t)(str* pres_uri);
 	</para>
 </section>
 
+<section>
+	<title>
+	<function moreinfo="none">get_presentity</function>
+	</title>
+	<para>
+		Field type:
+	</para>
+		<programlisting format="linespecific">
+...
+typedef str* (*pres_get_presentity_t)(str pres_uri, pres_ev_t *ev, str *etag, str *contact);
+...
+</programlisting>
+	<para>
+	This function returns a pointer to a <emphasis>str</emphasis> containing an
+	XML document with all of the matching presentities.  If no matching
+	presentities are found the function returns NULL.
+	</para>
+	<para>
+	The <emphasis>etag</emphasis> and <emphasis>contact</emphasis> parameters are
+	optional and may be set to NULL.  Once you are finished with the presentity
+	document you must call <emphasis>free_presentity</emphasis> to free the
+	allocated memory.
+	</para>
+</section>
+
+<section>
+	<title>
+	<function moreinfo="none">free_presentity</function>
+	</title>
+	<para>
+		Field type:
+	</para>
+		<programlisting format="linespecific">
+...
+typedef void (*pres_free_presentity_t)(str *presentity, pres_ev_t *ev);
+...
+</programlisting>
+	<para>
+	This function frees memory allocated by a call to 
+	<emphasis>get_presentity</emphasis>.  The <emphasis>ev</emphasis> parameter
+	MUST point to the same <emphasis>pres_ev_t</emphasis> data-structure
+	that was used in the call to <emphasis>get_presentity</emphasis>.
+	</para>
+</section>
+
 </chapter>
 

modules_k/presence/notify.c

@@ -896,6 +896,23 @@ error:
 	return NULL;
 }
 
+void free_notify_body(str *body, pres_ev_t *ev)
+{
+	if (body != NULL)
+	{
+		if (body->s != NULL)
+		{
+			if (ev->type & WINFO_TYPE)
+				xmlFree(body->s);
+			else if (ev->agg_nbody== NULL && ev->apply_auth_nbody== NULL)
+				pkg_free(body->s);
+			else
+				ev->free_body(body->s);
+		}
+		pkg_free(body);
+	}
+}
+
 int free_tm_dlg(dlg_t *td)
 {
 	if(td)
@@ -1374,18 +1391,7 @@ int publ_notify(presentity_t* p, str pres_uri, str* body, str* offline_etag, str
 
 done:
 	free_subs_list(subs_array, PKG_MEM_TYPE, 0);
-	
-	if(notify_body!=NULL)
-	{
-		if(notify_body->s)
-		{
-			if(	p->event->agg_nbody== NULL && p->event->apply_auth_nbody== NULL)
-				pkg_free(notify_body->s);
-			else
-				p->event->free_body(notify_body->s);
-		}
-		pkg_free(notify_body);
-	}
+	free_notify_body(notify_body, p->event);	
 	return ret_code;
 }	
 
@@ -1442,20 +1448,7 @@ int query_db_notify(str* pres_uri, pres_ev_t* event, subs_t* watcher_subs )
 
 done:
 	free_subs_list(subs_array, PKG_MEM_TYPE, 0);
-	if(notify_body!=NULL)
-	{
-		if(notify_body->s)
-		{
-			if(event->type & WINFO_TYPE)
-				pkg_free(notify_body->s);
-			else
-			if(event->agg_nbody== NULL && event->apply_auth_nbody== NULL)
-				pkg_free(notify_body->s);
-			else
-				event->free_body(notify_body->s);
-		}
-		pkg_free(notify_body);
-	}
+	free_notify_body(notify_body, event);
 
 	return ret_code;
 }
@@ -1604,23 +1597,8 @@ jump_over_body:
 	if(str_hdr.s) pkg_free(str_hdr.s);
 	
 	if((int)(long)n_body!= (int)(long)notify_body)
-	{
-		if(notify_body!=NULL)
-		{
-			if(notify_body->s!=NULL)
-			{
-				if(subs->event->type& WINFO_TYPE )
-					xmlFree(notify_body->s);
-				else
-				if(subs->event->apply_auth_nbody== NULL
-						&& subs->event->agg_nbody== NULL)
-					pkg_free(notify_body->s);
-				else
-				subs->event->free_body(notify_body->s);
-			}
-			pkg_free(notify_body);
-		}
-	}	
+		free_notify_body(notify_body, subs->event);
+
 	return 0;
 
 error:

modules_k/presence/notify.h

@@ -113,4 +113,6 @@ int send_notify_request(subs_t* subs, subs_t * watcher_subs,
 
 char* get_status_str(int flag);
 
+str *get_p_notify_body(str pres_uri, pres_ev_t *event, str *etag, str *contact);
+void free_notify_body(str *body, pres_ev_t *ev);
 #endif

modules_k/presence_xml/README

@@ -35,6 +35,11 @@ Anca-Maria Vamanu
               3.10. passive_mode(int)
 
         4. Exported Functions
+
+              4.1. pres_check_basic(char *presentity_uri, char *status)
+              4.2. pres_check_activities(char *presentity_uri, char
+                      *activity)
+
         5. Installation
         6. Exported pseudo-variables
 
@@ -52,6 +57,8 @@ Anca-Maria Vamanu
    1.8. Set integrated_xcap_server parameter
    1.9. Set xcap_server parameter
    1.10. Set passive_mode parameter
+   1.11. pres_check_basic usage
+   1.12. pres_check_activities usage
 
 Chapter 1. Admin Guide
 
@@ -77,6 +84,10 @@ Chapter 1. Admin Guide
         3.10. passive_mode(int)
 
    4. Exported Functions
+
+        4.1. pres_check_basic(char *presentity_uri, char *status)
+        4.2. pres_check_activities(char *presentity_uri, char *activity)
+
    5. Installation
    6. Exported pseudo-variables
 
@@ -273,7 +284,54 @@ modparam("presence_xml", "passive_mode", 1)
 
 4. Exported Functions
 
-   None to be used in configuration file.
+   4.1. pres_check_basic(char *presentity_uri, char *status)
+   4.2. pres_check_activities(char *presentity_uri, char *activity)
+
+4.1.  pres_check_basic(char *presentity_uri, char *status)
+
+   Checks the /presence/tuple/status/basic nodes in the presentity for
+   presentity_uri against the value in status.
+
+   This function can be used from ANY_ROUTE.
+
+   Return code:
+     * 1 - if a match is found.
+     * -1 - if a match is not found.
+
+   Example 1.11. pres_check_basic usage
+...
+    if (pres_check_basic("$ru", "open")) {
+        ...
+    } else {
+        if (is_method("MESSAGE"))
+            m_store();
+    else
+        send_reply("404", "Not Found");
+    }
+...
+
+4.2.  pres_check_activities(char *presentity_uri, char *activity)
+
+   Checks whether a /presence/person/activities/activity node exists in
+   the presentity for presentity_uri.
+
+   This function can be used from ANY_ROUTE.
+
+   Return code:
+     * 1 - if a match is found.
+     * -1 - if a match is not found.
+
+   Example 1.12. pres_check_activities usage
+...
+    if (pres_check_basic("$ru", "open")) {
+        if (pres_check_activities("$ru", "unknown") || !is_method("INVITE"))
+            t_relay();
+        else
+            send_reply("486", "Busy Here");
+    } else {
+        ...
+    }
+...
 
 5. Installation
 

modules_k/presence_xml/doc/presence_xml_admin.xml

@@ -315,9 +315,91 @@ modparam("presence_xml", "passive_mode", 1)
 
 <section>
 	<title>Exported Functions</title>
-	<para>
-	None to be used in configuration file.
-	</para>
+	<section>
+		<title>
+		<function moreinfo="none">pres_check_basic(char *presentity_uri, char *status)</function>
+		</title>
+		<para>
+		Checks the /presence/tuple/status/basic nodes in the presentity for
+		<emphasis>presentity_uri</emphasis> against the value in status.
+		</para>
+		<para>
+		This function can be used from ANY_ROUTE.
+		</para>
+		<para>
+		<emphasis>Return code:</emphasis>
+		<itemizedlist>
+			<listitem>
+			<para>
+				<emphasis> 1 - if a match is found</emphasis>.
+			</para>
+			</listitem>
+			<listitem>
+			<para>
+				<emphasis> -1 - if a match is not found</emphasis>.
+			</para>
+			</listitem>
+		</itemizedlist>
+		</para>
+		<example>
+		<title><function>pres_check_basic</function> usage</title>
+		<programlisting format="linespecific">
+...
+    if (pres_check_basic("$ru", "open")) {
+        ...
+    } else {
+        if (is_method("MESSAGE"))
+            m_store();
+    else
+        send_reply("404", "Not Found");
+    }
+...
+</programlisting>
+		</example>
+	</section>
+	<section>
+		<title>
+		<function moreinfo="none">pres_check_activities(char *presentity_uri, char *activity)</function>
+		</title>
+		<para>
+		Checks whether a /presence/person/activities/<emphasis>activity</emphasis>
+		node exists in the presentity for <emphasis>presentity_uri</emphasis>.
+		</para>
+		<para>
+		This function can be used from ANY_ROUTE.
+		</para>
+		<para>
+		<emphasis>Return code:</emphasis>
+		<itemizedlist>
+			<listitem>
+			<para>
+				<emphasis> 1 - if a match is found</emphasis>.
+			</para>
+			</listitem>
+			<listitem>
+			<para>
+				<emphasis> -1 - if a match is not found</emphasis>.
+			</para>
+			</listitem>
+		</itemizedlist>
+		</para>
+		<example>
+		<title><function>pres_check_activities</function> usage</title>
+		<programlisting format="linespecific">
+...
+    if (pres_check_basic("$ru", "open")) {
+        if (pres_check_activities("$ru", "unknown") || !is_method("INVITE"))
+            t_relay();
+	else
+            send_reply("486", "Busy Here");
+    } else {
+        ...
+    }
+...
+</programlisting>
+		</example>
+	</section>
+
 </section>
 
 <section>

modules_k/presence_xml/pres_check.c

@@ -0,0 +1,220 @@
+/*
+ * Copyright (C) 2011 Crocodile RCS Ltd.
+ *
+ * This file is part of Kamailio, a free SIP server.
+ *
+ * Kamailio 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 2 of the License, or
+ * (at your option) any later version
+ *
+ * Kamailio 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 General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License 
+ * along with this program; if not, write to the Free Software 
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ */
+
+
+#include <stdio.h>
+#include <libxml/parser.h>
+
+#include "pres_check.h"
+#include "pidf.h"
+#include "../../mod_fix.h"
+#include "../../parser/msg_parser.h"
+#include "../../parser/parse_uri.h"
+#include "../../str.h"
+#include "../presence/event_list.h"
+
+int fixup_presxml_check(void **param, int param_no)
+{
+        if(param_no==1)
+        {
+                return fixup_spve_null(param, 1);
+        } else if(param_no==2) {
+                return fixup_spve_null(param, 1);
+        }
+        return 0;
+}
+
+int presxml_check_basic(struct sip_msg *msg, char *presentity_uri, char *status)
+{
+	str uri, basic;
+	str *presentity = NULL;
+	struct sip_uri parsed_uri;
+	pres_ev_t *ev;
+	static str event = str_init("presence");
+	int retval = -1;
+	xmlDocPtr xmlDoc = NULL;
+	xmlNodePtr tuple = NULL, basicNode = NULL;
+	char *basicVal = NULL;
+
+	if (fixup_get_svalue(msg, (gparam_p)presentity_uri, &uri) != 0)
+	{
+		LM_ERR("invalid presentity uri parameter\n");
+		return -1;
+	}
+
+	if (fixup_get_svalue(msg, (gparam_p)status, &basic) != 0)
+	{
+		LM_ERR("invalud status parameter\n");
+		return -1;
+	}
+
+	if (parse_uri(uri.s, uri.len, &parsed_uri) < 0)
+	{
+		LM_ERR("bad uri: %.*s\n", uri.len, uri.s);
+		return -1;
+	}
+
+	ev = pres_contains_event(&event, NULL);
+	if (ev == NULL)
+	{
+		LM_ERR("event presence is not registered\n");
+		return -1;
+	}
+
+	presentity = pres_get_presentity(uri, ev, NULL, NULL);
+
+	if (presentity == NULL || presentity->len <= 0 || presentity->s == NULL)
+	{
+		LM_DBG("cannot get presentity for %.*s\n", uri.len, uri.s);
+		return -1;
+	}
+
+	if ((xmlDoc = xmlParseMemory(presentity->s, presentity->len)) == NULL)
+	{
+		LM_ERR("while parsing XML memory\n");
+		goto error;
+	}
+
+	if ((tuple = xmlDocGetNodeByName(xmlDoc, "tuple", NULL)) == NULL)
+	{
+		LM_ERR("unable to extract 'tuple'\n");
+		goto error;
+	}
+
+	while (tuple->next != NULL)
+	{
+		if (xmlStrcasecmp(tuple->name, (unsigned char *) "tuple") == 0)
+		{
+			if ((basicNode = xmlNodeGetNodeByName(tuple, "basic", NULL)) == NULL)
+			{
+				LM_ERR("while extracting 'basic' node\n");
+				goto error;
+			}
+
+			if ((basicVal = (char *) xmlNodeGetContent(basicNode)) == NULL)
+			{
+				LM_ERR("while getting 'basic' content\n");
+				goto error;
+			}
+
+			if (strncasecmp(basicVal, basic.s, basic.len) == 0)
+				retval = 1;
+
+			xmlFree(basicVal);
+		}
+		tuple = tuple->next;
+	}
+error:
+	if (xmlDoc != NULL)
+		xmlFreeDoc(xmlDoc);
+	pres_free_presentity(presentity, ev);
+	return retval;
+}
+
+int presxml_check_activities(struct sip_msg *msg, char *presentity_uri, char *activity)
+{
+	str uri, act;
+	str *presentity = NULL;
+	struct sip_uri parsed_uri;
+	pres_ev_t *ev;
+	static str event = str_init("presence");
+	char *nodeName = NULL;
+	int retval = -1;
+	xmlDocPtr xmlDoc = NULL;
+	xmlNodePtr person = NULL, activitiesNode = NULL, activityNode = NULL;
+
+	if (fixup_get_svalue(msg, (gparam_p)presentity_uri, &uri) != 0)
+	{
+		LM_ERR("invalid presentity uri parameter\n");
+		return -1;
+	}
+
+	if (fixup_get_svalue(msg, (gparam_p)activity, &act) != 0)
+	{
+		LM_ERR("invalid activity parameter\n");
+		return -1;
+	}
+
+	if (parse_uri(uri.s, uri.len, &parsed_uri) < 0)
+	{
+		LM_ERR("bad uri: %.*s\n", uri.len, uri.s);
+		return -1;
+	}
+
+	ev = pres_contains_event(&event, NULL);
+	if (ev == NULL)
+	{
+		LM_ERR("event presence is not registered\n");
+		return -1;
+	}
+
+	if ((nodeName = pkg_malloc(act.len + 1)) == NULL)
+	{
+		LM_ERR("cannot pkg_malloc for nodeName\n");
+		return -1;		
+	}
+	memcpy(nodeName, act.s, act.len);
+	nodeName[act.len] = '\0';
+
+	presentity = pres_get_presentity(uri, ev, NULL, NULL);
+
+	if (presentity == NULL || presentity->len <= 0 || presentity->s == NULL)
+	{
+		LM_DBG("cannot get presentity for %.*s\n", uri.len, uri.s);
+		return -1;
+	}
+
+	if ((xmlDoc = xmlParseMemory(presentity->s, presentity->len)) == NULL)
+	{
+		LM_ERR("while parsing XML memory\n");
+		goto error;
+	}
+
+	if ((person = xmlDocGetNodeByName(xmlDoc, "person", NULL)) == NULL)
+	{
+		LM_ERR("unable to extract 'person'\n");
+		goto error;
+	}
+
+	while (person->next != NULL)
+	{
+		if (xmlStrcasecmp(person->name, (unsigned char *) "person") == 0)
+		{
+			if ((activitiesNode = xmlNodeGetNodeByName(person, "activities", NULL)) == NULL)
+			{
+				LM_ERR("while extracting 'actvities' node\n");
+				goto error;
+			}
+
+			if ((activityNode = xmlNodeGetNodeByName(activitiesNode, nodeName, NULL)) != NULL)
+			{
+				retval = 1;
+			}
+		}
+		person = person->next;
+	}
+error:
+	if (nodeName != NULL)
+		pkg_free(nodeName);
+	if (xmlDoc != NULL)
+		xmlFreeDoc(xmlDoc);
+	pres_free_presentity(presentity, ev);
+	return retval;
+}

modules_k/presence_xml/pres_check.h

@@ -0,0 +1,32 @@
+/*
+ * Copyright (C) 2011 Crocodile RCS Ltd.
+ *
+ * This file is part of Kamailio, a free SIP server.
+ *
+ * Kamailio 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 2 of the License, or
+ * (at your option) any later version
+ *
+ * Kamailio 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 General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License 
+ * along with this program; if not, write to the Free Software 
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ */
+
+
+#include <stdio.h>
+#include "../../parser/msg_parser.h"
+#include "../presence/bind_presence.h"
+#include "../presence/event_list.h"
+
+int presxml_check_basic(struct sip_msg* msg, char *presentity_uri, char *status);
+int presxml_check_activities(struct sip_msg* msg, char *presentity_uri, char *activity);
+int fixup_presxml_check(void **param, int param_no);
+contains_event_t pres_contains_event;
+pres_get_presentity_t pres_get_presentity;
+pres_free_presentity_t pres_free_presentity;

modules_k/presence_xml/presence_xml.c

@@ -55,6 +55,7 @@
 #include "pidf.h"
 #include "add_events.h"
 #include "presence_xml.h"
+#include "pres_check.h"
 
 MODULE_VERSION
 #define S_TABLE_VERSION 4
@@ -100,6 +101,14 @@ db_func_t pxml_dbf;
 
 xcapGetNewDoc_t xcap_GetNewDoc;
 
+static cmd_export_t cmds[]={
+	{ "pres_check_basic",		(cmd_function)presxml_check_basic, 2,
+		fixup_presxml_check, 0, ANY_ROUTE},
+	{ "pres_check_activities",	(cmd_function)presxml_check_activities, 2,
+		fixup_presxml_check, 0, ANY_ROUTE},
+	{ 0, 0, 0, 0, 0, 0}
+};
+
 static param_export_t params[]={
 	{ "db_url",		STR_PARAM, &db_url.s},
 	{ "xcap_table",		STR_PARAM, &xcap_table.s},
@@ -124,7 +133,7 @@ static mi_export_t mi_cmds[] = {
 struct module_exports exports= {
 	"presence_xml",		/* module name */
 	 DEFAULT_DLFLAGS,	/* dlopen flags */
-	 0,  			/* exported functions */
+	 cmds,  		/* exported functions */
 	 params,		/* exported parameters */
 	 0,				/* exported statistics */
 	 mi_cmds,		/* exported MI functions */
@@ -202,6 +211,9 @@ static int mod_init(void)
 	pres_get_sphere= pres.get_sphere;
 	pres_add_event= pres.add_event;
 	pres_update_watchers= pres.update_watchers_status;
+	pres_contains_event= pres.contains_event;
+	pres_get_presentity= pres.get_presentity;
+	pres_free_presentity= pres.free_presentity;
 	if (pres_add_event == NULL || pres_update_watchers== NULL)
 	{
 		LM_ERR("Can't import add_event\n");