Skip to content

GitLab

Commit cbaa1805 authored by W. Michael Petullo's avatar W. Michael Petullo
Browse files

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's avatarW. Michael Petullo <mike@flyn.org>
parent cfa81ab5
Hide whitespace changes
Inline Side-by-side
AUTHORS
View file @ cbaa1805
......@@ -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
ChangeLog
View file @ cbaa1805
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.
......
docs/Makefile.am
View file @ cbaa1805
......@@ -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
......
docs/browserapi.sgml 0 → 100644
View file @ cbaa1805
<?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>
docs/client-internals.sgml 0 → 100644
View file @ cbaa1805
<?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>
docs/connectedcb.sgml 0 → 100644
View file @ cbaa1805
<?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>
docs/libdmapsharing-docs.sgml
View file @ cbaa1805
......@@ -30,6 +30,12 @@
<xi:include href="connectedcb.sgml"/>
</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"/>
......
docs/server-internals.sgml 0 → 100644
View file @ cbaa1805
<?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>
docs/serviceaddedcb.sgml 0 → 100644
View file @ cbaa1805
<?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>
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment