GNOME.org
 

[libdmapsharing] More work on documentation

commit 84aeadebd77d656f368e268bc657a92a75e6b0ac
Author: W. Michael Petullo <mike flyn org>
Date:   Sun Mar 25 15:27:02 2018 -0400

    More work on documentation
    
    Signed-off-by: W. Michael Petullo <mike flyn org>

 doc/browserapi.xml       |   11 +++++++-
 doc/client-internals.xml |   26 ++++++++++-----------
 doc/server-internals.xml |   55 ++++++++++++++++++++++++---------------------
 doc/serviceaddedcb.xml   |   14 +++--------
 doc/shareapi.xml         |   38 ++++++++++++++++++++++++++-----
 5 files changed, 86 insertions(+), 58 deletions(-)
---
diff --git a/doc/browserapi.xml b/doc/browserapi.xml
index 27f9187..5df690d 100644
--- a/doc/browserapi.xml
+++ b/doc/browserapi.xml
@@ -21,9 +21,16 @@
                <para>
 The mDNS browser API allows a client program to discover and connect to
 DMAP services.  The dmap_mdns_browser_new function creates a new mDNS
-browser object. The mDNS browser object emits a "service-added" signal for each
+browser object. Passing DMAP_MDNS_SERVICE_TYPE_DAAP to this function
+results in a DAAP browser, and passing DMAP_MDNS_SERVICE_TYPE_DPAP results in
+a DPAP browser. Subsequently calling dmap_mdns_browser_start and g_main_loop_run
+causes the browser to begin watching for services of the appropriate type.
+
+               </para>
+               <para>
+The mDNS browser object emits a "service-added" signal for each
 DMAP service encountered, and it emits a "service-remove" signal when
-a service disappears. We describe callbacks in subsequent section.
+a service disappears. We describe these callbacks in the next sections.
 
                </para>
        </refsect1>
diff --git a/doc/client-internals.xml b/doc/client-internals.xml
index d583823..d57d133 100644
--- a/doc/client-internals.xml
+++ b/doc/client-internals.xml
@@ -24,20 +24,18 @@ 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.
+The DmapConnection class's dmap_connection_start 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_MEDIA
+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>
diff --git a/doc/server-internals.xml b/doc/server-internals.xml
index b2ebfcb..e11bea4 100644
--- a/doc/server-internals.xml
+++ b/doc/server-internals.xml
@@ -19,41 +19,44 @@
        <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
+This description uses DmapAvShare to describe the libdmapsharing internals.
+DmapAvShare resembles each implmentation of
+the abstract class DMAPShare, including its cousin DmapImageShare. 
+After creating a new DmapAvShare, an application should call the object's
+dmap_share_serve and dmap_share_publish methods.
+The former method starts a new web server by calling
+soup_server_new, and it 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).
+/content-codes, /login, and so on). DmapAvShare implements these callbacks,
+and DmapShare wraps them in an adapter method to make them suitable
+for the SoupServer's requirements.
+(Note that some callbacks are common to all DMAP protocols
+and are implemented in DMAPShare; e.g., the login callback.) The latter
+method, dmap_share_publish, starts the mDNS subsystem. It does
+this by using the mDNS implmentation option choosen at compile-time
+(either Avahi, DNS-SD, or Howl).
 
                </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 DmapStructure class represents the data
+which makes up a DMAP request or response. The _cc_defs array defines the
+allowed 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.
+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
+at the same relative position.
 
                </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
+Assuming DmapStructure defines all the entries you require, DmapAvShare builds
+the actual
+protocol-specific structures. Note the use of the
+function dmap_structure_add. Often, the data dmap_structure_add
+adds is provided by a DmapAvRecord 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.
+the DmapAvShare provides the DmapStructure to the SoupServer object using
+the dmap_share_message_set_from_dmap_structure function.
 
                </para>
        </refsect1>
diff --git a/doc/serviceaddedcb.xml b/doc/serviceaddedcb.xml
index 1b870ea..4f764af 100644
--- a/doc/serviceaddedcb.xml
+++ b/doc/serviceaddedcb.xml
@@ -35,20 +35,14 @@ The following is a simple "service-added" callback which creates a DAAP connecti
 static void
 service_added_cb(DmapMdnsBrowser *browser, DmapMdnsBrowserService *service, gpointer user_data)
 
+       DmapDb *db;
        DmapRecordFactory *factory;
        DmapConnection *conn;
-       DmapDb *db;
-
-       db = DMAP_DB(my_dmap_db_new());
-       if (db == NULL) {
-               g_error("Error creating DB");
-       }
 
+       db      = DMAP_DB(my_dmap_db_new());
        factory = DMAP_RECORD_FACTORY(my_dmap_av_record_factory_new());
-       if (factory == NULL) {
-               g_error("Error creating record factory");
-       }
-       conn = DMAP_CONNECTION(dmap_av_connection_new(service->name, service->host, service->port, db, 
factory));
+       conn    = DMAP_CONNECTION(dmap_av_connection_new(service->name, service->host, service->port, db, 
factory));
+
        dmap_connection_start(conn, (DmapConnectionFunc) connected_cb, db);
 }
                </screen>
diff --git a/doc/shareapi.xml b/doc/shareapi.xml
index 2852141..2932200 100644
--- a/doc/shareapi.xml
+++ b/doc/shareapi.xml
@@ -19,15 +19,41 @@
        <refsect1>
                <title>Share API</title>
                <para>
-A DmapAvShare allows a program to share the media described by its DmapDb
-object. See libdmapsharing's test-dmap-server.c for an example of using DmapDb.
+A DmapAvShare (or DmapImageShare) allows a program to share the media
+described by its DmapDb object.  The libdmapsharing package also provides
+an optional interface, DmapRecordFactory, that can be used in conjunction
+with a DmapDb implementation.  The following demonstrates the use of
+the share API; it serves up a media database made up of a single record.
 
                </para>
+               <screen>
+DmapRecordFactory *factory;
+DmapRecord *record;
+DmapDb *db;
+DmapShare *share;
+gboolean ok;
 
-               <para>
-The libdmapsharing package also provides an optional interface,
-DmapRecordFactory, that can be used in conjunction with a DmapDb implementation.
+factory = DMAP_RECORD_FACTORY (my_dmap_av_record_factory_new ());
+record  = DMAP_RECORD (dmap_record_factory_create (factory, path_to_media_file));
 
-               </para>
+db = DMAP_DB (my_dmap_db_new ());
+dmap_db_add (db, record);
+g_object_unref (record);
+
+share = DMAP_SHARE(dmap_av_share_new (name, NULL, db, dmap_container_db, NULL);
+
+ok = dmap_share_serve(share);
+if (!ok) {
+       g_error("Error sharing");
+}
+
+ok = dmap_share_publish(share);
+if (!ok) {
+       g_error("Error publishing");
+}
+
+g_main_loop_run(loop);
+
+               </screen>
        </refsect1>
 </refentry>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]