[sr-dev] git:master: domain: Documentation of internal API

[Jan Janak]

Module: sip-router
Branch: master
Commit: c4dbb39571c5e8d801956d8afc5134387de1a59a
URL:    http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=c4dbb39571c5e8d801956d8afc5134387de1a59a

Author: Jan Janak <jan at iptel.org>
Committer: Jan Janak <jan at iptel.org>
Date:   Fri Jul 17 11:34:24 2009 +0200

domain: Documentation of internal API

Add docbook documentation for the internal API of domain module.

---

 modules_s/domain/doc/domain.xml     |    1 +
 modules_s/domain/doc/domain_api.xml |   47 +++++++++++++++++++++++++++++++++++
 2 files changed, 48 insertions(+), 0 deletions(-)

diff --git a/modules_s/domain/doc/domain.xml b/modules_s/domain/doc/domain.xml
index 0e4879f..9c8aa57 100644
--- a/modules_s/domain/doc/domain.xml
+++ b/modules_s/domain/doc/domain.xml
@@ -241,5 +241,6 @@ iptel
 	<xi:include href="params.xml"/>
 	<xi:include href="functions.xml"/>
 	<xi:include href="fifo.xml"/>
+	<xi:include href="domain_api.xml"/>
 	
 </section>
diff --git a/modules_s/domain/doc/domain_api.xml b/modules_s/domain/doc/domain_api.xml
new file mode 100644
index 0000000..27c2c10
--- /dev/null
+++ b/modules_s/domain/doc/domain_api.xml
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
+   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<section id="domain.api" xmlns:xi="http://www.w3.org/2001/XInclude">
+    <title>Internal API</title>
+	<para>The domain module has an internal API which can be used to access
+	additional functions of the module (i.e. functions that are normally not
+	available from the routing script). Currently the API exports only the
+	function <function>is_domain_local</function>. That function can be used
+	to determine whether a given domain name is on the list of locally
+	configured domain names.</para>
+
+	<para>If you want to use the internal API of domain module from your
+	module then you need to include the header file
+	<filename>domain_api.h</filename> and call
+	<function>load_domain_api</function> first.</para>
+	
+	<example>
+		<title>Calling <function>load_domain_api</function></title>
+		<programlisting>
+#include "../domain/domain_api.h"
+
+domain_api_t dom_api;
+
+if (load_domain_api(&amp;dom_api) != 0) {
+    /* error */
+}
+</programlisting>
+	</example>
+
+	<para>After that you can call function
+	<function>is_domain_local</function> whose pointer is stored in the
+	initialized data structure:</para>
+	
+	<programlisting>
+str tmp = STR_STATIC_INIT("mydomain.com");
+
+if (dom_api.is_domain_local(&amp;tmp) == 1) {
+    /* Domain is local */
+} else {
+    /* Domain is not local or an error was encountered */
+}
+	</programlisting>
+</section>
+
+		
\ No newline at end of file