GNOME.org
 

[libdmapsharing] Documentation work

commit cbaa1805fd19be443448d57ea85399ba050e8982
Author: W. Michael Petullo <mike flyn org>
Date:   Sun May 16 05:22:33 2010 -0500

    Documentation work
    
    In support of Alexandre Rosenfeld's Google Summer of Code work, I am
    documenting libdmapsharing in a way that I hope will help people extend
    libdmapsharing. This will supplement the documentation that is provided
    to application developers.
    Signed-off-by: W. Michael Petullo <mike flyn org>

 AUTHORS                       |  130 ++++++++++++++++++++--------------------
 ChangeLog                     |    4 +
 docs/Makefile.am              |    1 -
 docs/browserapi.sgml          |   28 +++++++++
 docs/client-internals.sgml    |   44 ++++++++++++++
 docs/connectedcb.sgml         |   40 +++++++++++++
 docs/libdmapsharing-docs.sgml |    6 ++
 docs/server-internals.sgml    |   60 +++++++++++++++++++
 docs/serviceaddedcb.sgml      |   62 +++++++++++++++++++
 9 files changed, 309 insertions(+), 66 deletions(-)
---
diff --git a/AUTHORS b/AUTHORS
index f187d21..c43bb95 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -28,77 +28,77 @@ from SourceForge to GNOME Git in August of 2009.
 The original authors of Rhythmbox's DAAP plugin have endorsed the
 re-licensing of their code in the following two emails:
 
-Date: Sun, 11 Jan 2009 14:46:35 -0500
-From: Charles Schmidt <cschmidt2[ ]gmail com>
-To: "W. Michael Petullo" <mike[ ]flyn org>
-Subject: Re: LGPL of Rhythmbox DAAP Code
-Cc: "cschmidt2[ ]emich edu" <cschmidt2[ ]emich edu>,
- "jmccann[ ]redhat com" <jmccann[ ]redhat com>,
- "jonathan[ ]d14n org" <jonathan[ ]d14n org>
+	Date: Sun, 11 Jan 2009 14:46:35 -0500
+	From: Charles Schmidt <cschmidt2[ ]gmail com>
+	To: "W. Michael Petullo" <mike[ ]flyn org>
+	Subject: Re: LGPL of Rhythmbox DAAP Code
+	Cc: "cschmidt2[ ]emich edu" <cschmidt2[ ]emich edu>,
+	 "jmccann[ ]redhat com" <jmccann[ ]redhat com>,
+	 "jonathan[ ]d14n org" <jonathan[ ]d14n org>
 
-Totally fine by me.  Is there a website or vcs I can look at?
+	Totally fine by me.  Is there a website or vcs I can look at?
 
-Charlie Schmidt
+	Charlie Schmidt
 
-On Jan 11, 2009, at 2:30 PM, "W. Michael Petullo" <mike[ ]flyn org> wrote:
+	On Jan 11, 2009, at 2:30 PM, "W. Michael Petullo" <mike[ ]flyn org> wrote:
 
-> Charles, Jon & Jonathan,
->
-> I recently began maintaining the libdmapsharing library, a DMAP  
-> library originally based on Rhythmbox's DAAP plugin. The library is  
-> distributed under the LGPL license. Your original work was  
-> distributed under the GPL.
->
-> The original maintainer of libdmapsharing has stated that he  
-> obtained permission from you regarding the relicensing of your code  
-> to the LGPL. If you do not have any objections, would each of you  
-> provide me with a brief statement to this effect that I may formally  
-> distribute with libdmapsharing?
->
-> The following files were used in developing libdmapsharing:
->
-> rb-daap-connection.c
-> rb-daap-connection.h
-> rb-daap-hash.c
-> rb-daap-hash.h
-> rb-daap-mdns-avahi.c
-> rb-daap-mdns-avahi.h
-> rb-daap-mdns-browser-avahi.c
-> rb-daap-mdns-browser.h
-> rb-daap-mdns-publisher-avahi.c
-> rb-daap-mdns-publisher.h
-> rb-daap-share.c
-> rb-daap-share.h
-> rb-daap-structure.c
-> rb-daap-structure.h
->
-> Thank you.
->
-> Sincerely,
->
-> Mike Petullo
+	> Charles, Jon & Jonathan,
+	>
+	> I recently began maintaining the libdmapsharing library, a DMAP  
+	> library originally based on Rhythmbox's DAAP plugin. The library is  
+	> distributed under the LGPL license. Your original work was  
+	> distributed under the GPL.
+	>
+	> The original maintainer of libdmapsharing has stated that he  
+	> obtained permission from you regarding the relicensing of your code  
+	> to the LGPL. If you do not have any objections, would each of you  
+	> provide me with a brief statement to this effect that I may formally  
+	> distribute with libdmapsharing?
+	>
+	> The following files were used in developing libdmapsharing:
+	>
+	> rb-daap-connection.c
+	> rb-daap-connection.h
+	> rb-daap-hash.c
+	> rb-daap-hash.h
+	> rb-daap-mdns-avahi.c
+	> rb-daap-mdns-avahi.h
+	> rb-daap-mdns-browser-avahi.c
+	> rb-daap-mdns-browser.h
+	> rb-daap-mdns-publisher-avahi.c
+	> rb-daap-mdns-publisher.h
+	> rb-daap-share.c
+	> rb-daap-share.h
+	> rb-daap-structure.c
+	> rb-daap-structure.h
+	>
+	> Thank you.
+	>
+	> Sincerely,
+	>
+	> Mike Petullo
 
-Date: Wed, 14 Jan 2009 21:00:45 +1000
-From: Jonathan Matthew <jonathan[ ]d14n org>
-To: "W. Michael Petullo" <mike[ ]flyn org>
-Subject: Re: LGPL of Rhythmbox DAAP Code
+	Date: Wed, 14 Jan 2009 21:00:45 +1000
+	From: Jonathan Matthew <jonathan[ ]d14n org>
+	To: "W. Michael Petullo" <mike[ ]flyn org>
+	Subject: Re: LGPL of Rhythmbox DAAP Code
 
-On Sun, Jan 11, 2009 at 02:30:15PM -0500, W. Michael Petullo wrote:
-> Charles, Jon & Jonathan,
->
-> I recently began maintaining the libdmapsharing library, a DMAP library 
-> originally based on Rhythmbox's DAAP plugin. The library is distributed 
-> under the LGPL license. Your original work was distributed under the GPL.
->
-> The original maintainer of libdmapsharing has stated that he obtained  
-> permission from you regarding the relicensing of your code to the LGPL. 
-> If you do not have any objections, would each of you provide me with a 
-> brief statement to this effect that I may formally distribute with 
-> libdmapsharing?
->
+	On Sun, Jan 11, 2009 at 02:30:15PM -0500, W. Michael Petullo wrote:
+	> Charles, Jon & Jonathan,
+	>
+	> I recently began maintaining the libdmapsharing library, a DMAP library 
+	> originally based on Rhythmbox's DAAP plugin. The library is distributed 
+	> under the LGPL license. Your original work was distributed under the GPL.
+	>
+	> The original maintainer of libdmapsharing has stated that he obtained  
+	> permission from you regarding the relicensing of your code to the LGPL. 
+	> If you do not have any objections, would each of you provide me with a 
+	> brief statement to this effect that I may formally distribute with 
+	> libdmapsharing?
+	>
 
-sure, why not.
+	sure, why not.
 
-enjoy,
+	enjoy,
 
--jonathan
+	-jonathan
diff --git a/ChangeLog b/ChangeLog
index 8d768be..aef71db 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+16 May 2010 W. Michael Petullo <mike flyn org>
+
+	* Documentation work.
+
 07 May 2010 W. Michael Petullo <mike flyn org>
 
 	* Send artist and album sort order to DAAP clients.
diff --git a/docs/Makefile.am b/docs/Makefile.am
index 91dbb88..bd6f455 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -14,7 +14,6 @@ DOC_MODULE=libdmapsharing
 # Uncomment for versioned docs and specify the version of the module, e.g. '2'.
 #DOC_MODULE_VERSION=2
 
-
 # The top-level SGML file. You can change this if you want to.
 DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
 
diff --git a/docs/browserapi.sgml b/docs/browserapi.sgml
new file mode 100644
index 0000000..f89e584
--- /dev/null
+++ b/docs/browserapi.sgml
@@ -0,0 +1,28 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"; [
+]>
+<refentry id="browserapi">
+	<refmeta>
+		<refentrytitle>mDNS Browser API</refentrytitle>
+		<manvolnum>3</manvolnum>
+		<refmiscinfo>Libdmapsharing</refmiscinfo>
+	</refmeta>
+
+	<refnamediv>
+		<refname>mDNS Browser API</refname>
+		<refpurpose>
+			Using the mDNS browser API
+		</refpurpose>
+	</refnamediv>
+
+	<refsect1>
+		<title>mDNS Browser API</title>
+		<para>
+Create a mDNS browser using dmap_mdns_browser_new. This object emits
+a "service-added" signal for each DMAP service encountered. Add a
+"service-added" callback and call dmap_mdns_browser_start.
+
+		</para>
+	</refsect1>
+</refentry>
diff --git a/docs/client-internals.sgml b/docs/client-internals.sgml
new file mode 100644
index 0000000..de52111
--- /dev/null
+++ b/docs/client-internals.sgml
@@ -0,0 +1,44 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"; [
+]>
+<refentry id="client-internals">
+	<refmeta>
+		<refentrytitle>Libdmapsharing Client Internals</refentrytitle>
+		<manvolnum>3</manvolnum>
+		<refmiscinfo>Libdmapsharing</refmiscinfo>
+	</refmeta>
+
+	<refnamediv>
+		<refname>Libdmapsharing Client Internals</refname>
+		<refpurpose>
+			Detailed decription of libdmapsharing's code for programmers who wish to contribute to libdmapsharing
+		</refpurpose>
+	</refnamediv>
+
+	<refsect1>
+		<title>Libdmapsharing Client Internals</title>
+		<para>
+The DMAPMdnsBrowser class allows for asynchronous interaction with a DMAP
+server using mDNS.
+		
+		</para>
+		<para>
+The DMAPConnection class's dmap_connection_connect()
+sets up a connection to a DMAP server using libsoup, stores the
+application-provided callback, sets the connection state to DMAP_GET_INFO,
+adds dmap_connection_do_something() as a GLib loop idle function
+and connects the function connected_cb() to the "operation-done"
+signal. The connection state progresses from DMAP_GET_INFO to
+DMAP_GET_PASSWORD then DMAP_LOGIN then DMAP_GET_REVISION_NUMBER then
+DMAP_GET_DB_INFO then DMAP_GET_SONGS then DMAP_GET_PLAYLISTS then
+(possibly) DMAP_GET_PLAYLIST_ENTRIES. Each time the state changes,
+dmap_connection_do_something() executes as an idle function. By the
+time these state transitions are complete, DMAPConnection has populated
+the media database. The
+connected_cb() function, in turn, executes the application-provided
+callback.
+
+		</para>
+	</refsect1>
+</refentry>
diff --git a/docs/connectedcb.sgml b/docs/connectedcb.sgml
new file mode 100644
index 0000000..7d2e59d
--- /dev/null
+++ b/docs/connectedcb.sgml
@@ -0,0 +1,40 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"; [
+]>
+<refentry id="connectedcb">
+	<refmeta>
+		<refentrytitle>Connected Callback</refentrytitle>
+		<manvolnum>3</manvolnum>
+		<refmiscinfo>Libdmapsharing</refmiscinfo>
+	</refmeta>
+
+	<refnamediv>
+		<refname>Connected Callback</refname>
+		<refpurpose>
+			Defining a Connected Callback
+		</refpurpose>
+	</refnamediv>
+
+	<refsect1>
+		<title>Connected Callback</title>
+		<para>
+Once the DMAPConnection object completes its interrogation of a DMAP
+server, it will emit the "connected" signal. The "connected" callback
+will receive a fully populated media database. The following is a simple
+"connected" callback:
+
+		</para>
+		<screen>
+connected_cb (DMAPConnection *connection,
+	      gboolean        result,
+	      const char     *reason,
+	      DMAPDb         *db)
+{
+	g_print ("DB has %lu entries\n", dmap_db_count (db));
+	dmap_db_foreach (db, print_record, NULL);
+	g_main_loop_quit (loop);
+}
+		</screen>
+	</refsect1>
+</refentry>
diff --git a/docs/libdmapsharing-docs.sgml b/docs/libdmapsharing-docs.sgml
index 2b16098..9fd9c39 100644
--- a/docs/libdmapsharing-docs.sgml
+++ b/docs/libdmapsharing-docs.sgml
@@ -31,6 +31,12 @@
   </chapter>
 
   <chapter>
+    <title>Libdmapsharing Internals</title>
+    <xi:include href="server-internals.sgml"/>
+    <xi:include href="client-internals.sgml"/>
+  </chapter>
+
+  <chapter>
     <title>Libdmapsharing Objects and Interfaces</title>
     <xi:include href="xml/daap-record.xml"/>
     <xi:include href="xml/daap-share.xml"/>
diff --git a/docs/server-internals.sgml b/docs/server-internals.sgml
new file mode 100644
index 0000000..9c0f2c6
--- /dev/null
+++ b/docs/server-internals.sgml
@@ -0,0 +1,60 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"; [
+]>
+<refentry id="server-internals">
+	<refmeta>
+		<refentrytitle>Libdmapsharing Server Internals</refentrytitle>
+		<manvolnum>3</manvolnum>
+		<refmiscinfo>Libdmapsharing</refmiscinfo>
+	</refmeta>
+
+	<refnamediv>
+		<refname>Libdmapsharing Server Internals</refname>
+		<refpurpose>
+			Detailed decription of libdmapsharing's code for programmers who wish to contribute to libdmapsharing
+		</refpurpose>
+	</refnamediv>
+
+	<refsect1>
+		<title>Libdmapsharing Server Internals</title>
+		<para>
+I will use DAAPShare to document the libdmapsharing internals. DAAPShare
+provides an example appropriate for any implmentation of the
+abstract class DMAPShare, including DPAPShare. DAAPShare calls
+_dmap_share_server_start() and _dmap_share_publish_start() when an
+object is created. The latter function starts a new web server by calling
+soup_server_new() and adds callbacks to the SoupServer object to handle
+the various paths required by the DMAP specification (/server-info,
+/content-codes, /login, etc). These callbacks are implemented in
+DAAPShare and provided to the SoupServer object after being wrapped
+in adapter functions (note that some callbacks are common to all
+DMAP protocols and are implemented in DMAPShare; e.g., the login
+callback). The latter function, _dmap_share_publish_start, starts the
+mDNS subsystem. It does this by using the mDNS implmentation option
+choosen at compile-time (e.g., Avahi, Howl or DNS-SD).
+
+		</para>
+		<para>
+The DMAPStructure class is used to build a representation of the data
+that makes up a DMAP request or response. The array cc_defs defines all
+possible valid entries in a DMAPStructure representation. Likewise,
+the numeric content code used by each node is defined by the enum
+DMAPContentCode. Both the cc_defs array and the DMAPContentCode enum
+must be in the same order. That is, if you add an entry to cc_defs,
+then you must add its corresponding content code to DMAPContentCode in
+the same order.
+
+		</para>
+		<para>
+Assuming DMAPStructure defines all the entries you require, the actual
+protocol-specific structures are built in DAAPShare. Note the use of the
+function dmap_structure_add(). Often, the data dmap_structure_add()
+adds is provided by a DAAPRecord object that exists in a DMAPDb
+object (both interfaces are implemented by the application). Eventually,
+the DAAPShare provides the DMAPStructure to the SoupServer object using
+the _dmap_share_message_set_from_dmap_structure() function.
+
+		</para>
+	</refsect1>
+</refentry>
diff --git a/docs/serviceaddedcb.sgml b/docs/serviceaddedcb.sgml
new file mode 100644
index 0000000..80e06bc
--- /dev/null
+++ b/docs/serviceaddedcb.sgml
@@ -0,0 +1,62 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"; [
+]>
+<refentry id="serviceaddedcb">
+	<refmeta>
+		<refentrytitle>Service Added Callback</refentrytitle>
+		<manvolnum>3</manvolnum>
+		<refmiscinfo>Libdmapsharing</refmiscinfo>
+	</refmeta>
+
+	<refnamediv>
+		<refname>Service Added Callback</refname>
+		<refpurpose>
+			Defining a Service Added Callback
+		</refpurpose>
+	</refnamediv>
+
+	<refsect1>
+		<title>Service Added Callback</title>
+		<para>
+A "service-added" callback should create a media DB and a record
+factory. Both of these objects will be passed to dmap_connection_new. This
+object will interact with a DMAP share and populate the media DB. In
+order to instruct the object to begin interrogating the DMAP service,
+call the dmap_connection_connect function and pass it a "connected"
+callback. The following is a simple "service-added" callback that creates
+a DAAP connection:
+
+		</para>
+		<screen>
+static void
+service_added_cb (DMAPMdnsBrowser *browser,
+                  DMAPMdnsBrowserService *service,
+                  gpointer user_data)
+{
+	DMAPRecordFactory *factory;
+	DMAPConnection *conn;
+	DMAPDb *db;
+
+	db = DMAP_DB (my_dmap_db_new ());
+	if (db == NULL) {
+		g_error ("Error creating DB");
+	}
+
+	factory = DMAP_RECORD_FACTORY (my_daap_record_factory_new ());
+	if (factory == NULL) {
+		g_error ("Error creating record factory");
+	}
+	conn = DMAP_CONNECTION (dmap_connection_new (service->name,
+						     service->host,
+						     service->port,
+						     FALSE,
+						     db,
+						     factory));
+	dmap_connection_connect (DMAP_CONNECTION (conn),
+				(DMAPConnectionCallback) connected_cb,
+				 db);
+}
+		</screen>
+	</refsect1>
+</refentry>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]