[libdmapsharing] Update documentation to new API
- From: W. Michael Petullo <wmpetullo src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [libdmapsharing] Update documentation to new API
- Date: Sun, 25 Mar 2018 02:32:42 +0000 (UTC)
commit 6d67a78c36c0a9ed1d293ea6a1526992e36a2eb4
Author: W. Michael Petullo <mike flyn org>
Date: Thu Mar 22 14:46:51 2018 -0400
Update documentation to new API
Signed-off-by: W. Michael Petullo <mike flyn org>
doc/Makefile.am | 18 ++++---
doc/browserapi.xml | 8 ++-
doc/connectedcb.xml | 17 ++++---
doc/containerdb.xml | 11 +++--
doc/libdmapsharing-4.0-docs.xml | 93 +++++++++++++++++++++++---------------
doc/mediadb.xml | 19 ++++++--
doc/serviceaddedcb.xml | 56 ++++++++++++-----------
doc/shareapi.xml | 6 +-
libdmapsharing/Makefile.am | 12 ++++-
libdmapsharing/dmap-utils.h | 6 +++
10 files changed, 149 insertions(+), 97 deletions(-)
---
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 559f03c..bdff649 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -58,17 +58,19 @@ EXTRA_HFILES=
# Header files to ignore when scanning. Use base file name, no paths
# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
IGNORE_HFILES= \
- dmap-marshal.h \
dmap-config.h \
- dmap-md5.h \
+ dmap-connection-private.h \
+ dmap-gst-mp3-input-stream.h \
+ dmap-gst-qt-input-stream.h \
+ dmap-gst-wav-input-stream.h \
+ dmap.h \
+ dmap-marshal.h \
dmap-mdns-avahi.h \
- dmap-mdns-publisher.h \
+ dmap-private-utils.h \
+ dmap-share-private.h \
dmap-structure.h \
- dmap-utils.h \
- g-gst-input-stream.h \
- g-gst-mp3-input-stream.h \
- g-gst-wav-input-stream.h \
- gst-util.h
+ gst-util.h \
+ test-*.h
# Images to copy into HTML directory.
# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
diff --git a/doc/browserapi.xml b/doc/browserapi.xml
index f89e584..27f9187 100644
--- a/doc/browserapi.xml
+++ b/doc/browserapi.xml
@@ -19,9 +19,11 @@
<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.
+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
+DMAP service encountered, and it emits a "service-remove" signal when
+a service disappears. We describe callbacks in subsequent section.
</para>
</refsect1>
diff --git a/doc/connectedcb.xml b/doc/connectedcb.xml
index 7d2e59d..421b260 100644
--- a/doc/connectedcb.xml
+++ b/doc/connectedcb.xml
@@ -19,17 +19,18 @@
<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:
+Once the DmapConnection object completes its interrogation of a DMAP
+server, it will emit the "connected" signal. Libdmapsharing has fully
+populated the DmapConnection's DmapDb by this point. The following is
+a simple "connected" callback which assumes db had previously been passed as the
+third argument to dmap_connection_start:
</para>
<screen>
-connected_cb (DMAPConnection *connection,
- gboolean result,
- const char *reason,
- DMAPDb *db)
+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);
diff --git a/doc/containerdb.xml b/doc/containerdb.xml
index 017d8e8..cc5f004 100644
--- a/doc/containerdb.xml
+++ b/doc/containerdb.xml
@@ -19,10 +19,13 @@
<refsect1>
<title>Container Database Implementation</title>
<para>
-Second, define classes that implement the DMAPContainerDb and
-DMAPContainerRecord interfaces (see test-dmap-container-db.c and
-test-dmap-container-record.c). These classes will allow the creation of
-playlists (DAAP) or albums (DPAP).
+A program can collect media database records in a container database,
+allowing logical playlists (DAAP) or albums (DPAP).
+Creating a container database is a matter of implementing
+the DmapContainerDb and DmapContainerRecord interfaces. For an
+example of this, see libdmapsharing's test-dmap-container-db.c and
+test-dmap-container-record.c.
+
</para>
</refsect1>
</refentry>
diff --git a/doc/libdmapsharing-4.0-docs.xml b/doc/libdmapsharing-4.0-docs.xml
index a4c88f7..68b338f 100644
--- a/doc/libdmapsharing-4.0-docs.xml
+++ b/doc/libdmapsharing-4.0-docs.xml
@@ -6,55 +6,72 @@
<!ENTITY % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
%gtkdocentities;
]>
-<book id="index">
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude";>
<bookinfo>
- <title>&package_name; Reference Manual</title>
+ <title>libdmapsharing Reference Manual</title>
<releaseinfo>
- for &package_string;.
+ for libdmapsharing 3.0
The latest version of this documentation can be found on-line at
- <ulink role="online-location"
url="http://[SERVER]/&package_name;/index.html";>http://[SERVER]/&package_name;/</ulink>.
+ <ulink role="online-location"
url="http://www.flyn.org/projects/libdmapsharing/doc/";>http://www.flyn.org/projects/libdmapsharing/doc/</ulink>.
</releaseinfo>
</bookinfo>
<chapter>
- <title>[Insert title here]</title>
- <xi:include href="xml/dmap-av-connection.xml"/>
- <xi:include href="xml/dmap-av-record.xml"/>
- <xi:include href="xml/dmap-av-share.xml"/>
- <xi:include href="xml/dmap-connection.xml"/>
- <xi:include href="xml/dmap-container-db.xml"/>
- <xi:include href="xml/dmap-container-record.xml"/>
- <xi:include href="xml/dmap-control-connection.xml"/>
- <xi:include href="xml/dmap-control-player.xml"/>
- <xi:include href="xml/dmap-control-share.xml"/>
- <xi:include href="xml/dmap-db.xml"/>
- <xi:include href="xml/dmap-enums.xml"/>
- <xi:include href="xml/dmap-gst-input-stream.xml"/>
- <xi:include href="xml/dmap-gst-mp3-input-stream.xml"/>
- <xi:include href="xml/dmap-gst-qt-input-stream.xml"/>
- <xi:include href="xml/dmap-gst-wav-input-stream.xml"/>
- <xi:include href="xml/dmap-image-connection.xml"/>
- <xi:include href="xml/dmap-image-record.xml"/>
- <xi:include href="xml/dmap-image-share.xml"/>
- <xi:include href="xml/dmap-mdns-browser.xml"/>
- <xi:include href="xml/dmap-mdns-service.xml"/>
- <xi:include href="xml/dmap-private-utils.xml"/>
- <xi:include href="xml/dmap-record.xml"/>
- <xi:include href="xml/dmap-record-factory.xml"/>
- <xi:include href="xml/dmap-share.xml"/>
- <xi:include href="xml/test-dmap-av-record.xml"/>
- <xi:include href="xml/test-dmap-av-record-factory.xml"/>
- <xi:include href="xml/test-dmap-container-db.xml"/>
- <xi:include href="xml/test-dmap-container-record.xml"/>
- <xi:include href="xml/test-dmap-db.xml"/>
- <xi:include href="xml/test-dmap-image-record.xml"/>
- <xi:include href="xml/test-dmap-image-record-factory.xml"/>
+ <title>Libdmapsharing Sharing Overview</title>
+ <xi:include href="mediadb.xml"/>
+ <xi:include href="containerdb.xml"/>
+ <xi:include href="shareapi.xml"/>
+ </chapter>
+ <chapter>
+ <title>Libdmapsharing Browsing Overview</title>
+ <xi:include href="mediadb.xml"/>
+ <xi:include href="containerdb.xml"/>
+ <xi:include href="browserapi.xml"/>
+ <xi:include href="serviceaddedcb.xml"/>
+ <xi:include href="connectedcb.xml"/>
</chapter>
+
+ <chapter>
+ <title>Libdmapsharing Internals</title>
+ <xi:include href="coding-standards.xml"/>
+ <xi:include href="server-internals.xml"/>
+ <xi:include href="client-internals.xml"/>
+ </chapter>
+
+ <chapter>
+ <title>Libdmapsharing Objects and Interfaces</title>
+ <xi:include href="xml/dmap-av-connection.xml"/>
+ <xi:include href="xml/dmap-av-record.xml"/>
+ <xi:include href="xml/dmap-av-share.xml"/>
+ <xi:include href="xml/dmap-cc.xml"/>
+ <xi:include href="xml/dmap-connection.xml"/>
+ <xi:include href="xml/dmap-container-db.xml"/>
+ <xi:include href="xml/dmap-container-record.xml"/>
+ <xi:include href="xml/dmap-control-connection.xml"/>
+ <xi:include href="xml/dmap-control-player.xml"/>
+ <xi:include href="xml/dmap-control-share.xml"/>
+ <xi:include href="xml/dmap-db.xml"/>
+ <xi:include href="xml/dmap-enums.xml"/>
+ <xi:include href="xml/dmap-gst-input-stream.xml"/>
+ <xi:include href="xml/dmap-image-connection.xml"/>
+ <xi:include href="xml/dmap-image-record.xml"/>
+ <xi:include href="xml/dmap-image-share.xml"/>
+ <xi:include href="xml/dmap-md5.xml"/>
+ <xi:include href="xml/dmap-mdns-browser.xml"/>
+ <xi:include href="xml/dmap-mdns-service.xml"/>
+ <xi:include href="xml/dmap-record-factory.xml"/>
+ <xi:include href="xml/dmap-record.xml"/>
+ <xi:include href="xml/dmap-share.xml"/>
+ <xi:include href="xml/dmap-utils.xml"/>
+ </chapter>
+
+<!--
<chapter id="object-tree">
<title>Object Hierarchy</title>
- <xi:include href="xml/tree_index.sgml"/>
+ <xi:include href="xml/tree_index.xml"/>
</chapter>
+-->
<index id="api-index-full">
<title>API Index</title>
<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
@@ -63,5 +80,7 @@
<title>Index of deprecated API</title>
<xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
</index>
+
+
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
</book>
diff --git a/doc/mediadb.xml b/doc/mediadb.xml
index 49b465b..5bf5c81 100644
--- a/doc/mediadb.xml
+++ b/doc/mediadb.xml
@@ -19,11 +19,20 @@
<refsect1>
<title>Media Database Implementation</title>
<para>
-First, define classes that implement the DAAPDb (or DPAP) and DAAPRecord
-interfaces (for an example, see test-daap-db.c and test-daap-record.c). If
-your application already has a media database interface, then these new
-definitions will simply be adapter classes encapsulating your existing
-interface.
+A media database is a collection of records which describe the media a
+program can share or access; for example, connecting to a DAAP server
+will populate a media database with DmapAvRecords which correspond to
+the media the server provides.
+
+ </para>
+
+ <para>
+Creating a media database is a
+matter of implementing the DmapDb and DmapAvRecord (or DmapImageRecord)
+interfaces. For an example of this, see libdmapsharing's test-dmap-db.c
+and test-dmap-av-record.c. If your application already has a media
+database interface, then these new definitions will simply adapt your
+existing interface.
</para>
</refsect1>
diff --git a/doc/serviceaddedcb.xml b/doc/serviceaddedcb.xml
index 5f8fcd0..4529793 100644
--- a/doc/serviceaddedcb.xml
+++ b/doc/serviceaddedcb.xml
@@ -19,43 +19,45 @@
<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:
+The "service-added" callback typically creates DmapDb and
+DmapRecordFactory objects, and then passes these objects to
+dmap_connection_new. A subsequent call to the dmap_connection_start
+method causes this connection object to interact with the DAAP share in order to
+populate the client's DmapDb.
+The next section describes the "connected" callback.
+
+ </para>
+ <para>
+The following is a simple "service-added" callback which creates a DAAP connection:
</para>
<screen>
static void
-service_added_cb (DMAPMdnsBrowser *browser,
- DMAPMdnsBrowserService *service,
- gpointer user_data)
-{
- DMAPRecordFactory *factory;
- DMAPConnection *conn;
- DMAPDb *db;
+service_added_cb(DmapMdnsBrowser *browser,
+ DmapMdnsBrowserService *service,
+ gpointer user_data)
+
+ DmapRecordFactory *factory;
+ DmapConnection *conn;
+ DmapDb *db;
- db = DMAP_DB (my_dmap_db_new ());
+ db = DMAP_DB(my_dmap_db_new());
if (db == NULL) {
- g_error ("Error creating DB");
+ g_error("Error creating DB");
}
- factory = DMAP_RECORD_FACTORY (my_av_record_factory_new ());
+ factory = DMAP_RECORD_FACTORY(my_dmap_av_record_factory_new());
if (factory == NULL) {
- g_error ("Error creating record factory");
+ 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);
+ conn = DMAP_CONNECTION(dmap_av_connection_new(service->name,
+ service->host,
+ service->port,
+ db,
+ factory));
+ dmap_connection_start(conn,
+ (DmapConnectionFunc) connected_cb,
+ db);
}
</screen>
</refsect1>
diff --git a/doc/shareapi.xml b/doc/shareapi.xml
index 1d487c5..2852141 100644
--- a/doc/shareapi.xml
+++ b/doc/shareapi.xml
@@ -19,14 +19,14 @@
<refsect1>
<title>Share API</title>
<para>
-Finally, write the code that creates a new DAAPShare object (see
-test-dmap-server.c) and provide it your DAAPDb object.
+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.
</para>
<para>
The libdmapsharing package also provides an optional interface,
-DMAPRecordFactory, that may be convenient for application developers.
+DmapRecordFactory, that can be used in conjunction with a DmapDb implementation.
</para>
</refsect1>
diff --git a/libdmapsharing/Makefile.am b/libdmapsharing/Makefile.am
index 0cd63d2..b3f1b3a 100644
--- a/libdmapsharing/Makefile.am
+++ b/libdmapsharing/Makefile.am
@@ -131,9 +131,17 @@ noinst_HEADERS = \
test-dmap-image-record-factory.h \
test-dmap-image-record.h
-BUILT_SOURCES = dmap-marshal.c dmap-marshal.h dmap-enums.c dmap-enums.h unit-test.stamp
+BUILT_SOURCES = \
+ dmap-marshal.c \
+ dmap-marshal.h \
+ dmap-enums.c \
+ dmap-enums.h \
+ unit-test.stamp
-CLEANFILES = $(BUILT_SOURCES) ../tests/unit-test.c *-suite.c pedansee.conf
+CLEANFILES = $(BUILT_SOURCES) \
+ ../tests/unit-test.c \
+ *-suite.c \
+ pedansee.conf
dmap-marshal.c: dmap-marshal.list
@glib-genmarshal --prefix=dmap_marshal_generated $(srcdir)/dmap-marshal.list --body > dmap-marshal.c
diff --git a/libdmapsharing/dmap-utils.h b/libdmapsharing/dmap-utils.h
index aa6d737..d10f474 100644
--- a/libdmapsharing/dmap-utils.h
+++ b/libdmapsharing/dmap-utils.h
@@ -23,6 +23,12 @@
#include <glib.h>
#include <libsoup/soup.h>
+/**
+ * dmap_utils_mime_to_format:
+ * @transcode_mimetype: a string representing a MIME type (e.g., "audio/wav").
+ *
+ * Returns: a string representing the corresponding type (e.g., "wav").
+ */
gchar * dmap_utils_mime_to_format (const gchar * transcode_mimetype);
G_END_DECLS
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
