GNOME.org
 

[gupnp/wip/gi-docgen: 11/14] wip: More doc fixes


commit 5aa539ad85e22b4005f8f0a8385144acc0bb7c21
Author: Jens Georg <mail jensge org>
Date:   Sat Aug 7 20:14:32 2021 +0200

    wip: More doc fixes

 doc/choosing-a-context-manager.md |  20 +++++++
 doc/glossary.md                   | 115 ++++++++++++++++++++++++++++++++++++++
 doc/gupnp.toml.in                 |   4 +-
 doc/meson.build                   |   8 ++-
 doc/server-tutorial.md            |  28 +++++-----
 libgupnp/gupnp-acl.c              |  35 ++++++++----
 libgupnp/gupnp-acl.h              |  19 +------
 libgupnp/gupnp-context-filter.c   |  43 ++++++++++----
 libgupnp/gupnp-context-manager.c  |  29 ++++++----
 9 files changed, 232 insertions(+), 69 deletions(-)
---
diff --git a/doc/choosing-a-context-manager.md b/doc/choosing-a-context-manager.md
new file mode 100644
index 0000000..bc98595
--- /dev/null
+++ b/doc/choosing-a-context-manager.md
@@ -0,0 +1,20 @@
+-----
+Title: Choosing a Context Manager Implementation
+-----
+
+# Choosing a Context Manager Implementation
+
+Ususally it is fine to trust the auto-detection. If the operating system is not Linux,
+there is only one choice anyway.
+
+For Linux, four different implementations exist:
+
+ - A basic polling implementation, the fall-back if nothing else works.
+ - A Netlink-based implementation
+ - Using NetworkManager to identify available network interfaces
+ - Using Connman to identify the available interfaces
+ - An Android-specific implementation
+ 
+With the exception of Android, It is generally recommended to use the Netlink-based implementation.
+It should co-exist with any other network management implementation.
+
diff --git a/doc/glossary.md b/doc/glossary.md
new file mode 100644
index 0000000..0b9dbb2
--- /dev/null
+++ b/doc/glossary.md
@@ -0,0 +1,115 @@
+---
+Title: UPnP Glossary
+---
+
+# Action
+
+> An Action is a method call on a Service, which encapsulated a single piece of
+functionality.  Actions can have multiple input and output arguments, and
+can return error codes.  UPnP allows one of the output arguments to be
+marked as the return value, but GUPnP doesn't treat return values specially.
+
+> Every action argument has a related State Variable,
+which determines the type of the argument.  Note that even if the argument
+wouldn't need a state variable it is still required, due to historical
+reasons.
+
+# Control Point
+
+> A Control Point is an entity on the network which
+communicates with other Devices and
+Services.  In the client/server model the control
+point is a client and the Service is a server,
+although it is common for devices to also be a control point because
+whilst a single control point/service connection is client/server, the
+UPnP network as whole is peer-to-peer.
+
+# Device
+> A Device is an entity on the network which
+communicates using the UPnP standards.  This can be a dedicated physical
+device such as a router or printer, or a PC which is running software
+implementing the UPnP standards.
+
+> A Device can contain sub-devices, for example a combination
+printer/scanner could appear as a general device with a printer
+sub-device and a scanner sub-device.
+
+> Every device has zero or more Services. UPnP defines many standard
+device types, which specify services which are required to be implemented.
+Alternatively, a non-standard device type could be used.  Examples of
+standard device types are `MediaRenderer` or
+`InternetGatewayDevice`.
+
+# DIDL-Lite
+
+> Digital Item Declaration Language - Lite
+
+> An XML schema used to represent digital content metadata. Defined by
+the UPnP Forum.
+
+# Service
+
+> A Service is a collection of related methods
+(called Actions) and public variables (called
+State Variables) which together form a logical interface.
+>      UPnP defines standard services that define actions and variables which
+must be present and their semantics.  Examples of these are
+`AVTransport` and `WANIPConnection`.
+
+See also:
+
+- [Action](#action)
+- [Device](#device)
+- [State Variable](#state-variable)
+
+# SCDP
+> Service Control Protocol Document
+
+
+> An XML document which defines the set of <glossterm>Actions</glossterm>
+and <glossterm>State Variables</glossterm> that a
+<glossterm>Service</glossterm> implements.
+
+See also:
+
+- [Action](#action)
+- [Device](#device)
+- [State Variable](#state-variable)
+
+# SSDP
+> <glossterm>Simple Service Discovery Protocol</glossterm>
+
+> UPnP device discovery protocol. Specifies how <glossterm>Devices</glossterm> 
+advertise their <glossterm>Services</glossterm> in the network and also how 
+<glossterm>Control Points</glossterm> search for
+services and devices respond.
+
+See also:
+
+- [Device](#device)
+- [Action](#controlpoint)
+- [Service](#service)
+
+# State Variable
+
+> A <firstterm>State Variable</firstterm> is a public variable exposing some
+aspect of the service's state.  State variables are typed and optionally
+are <firstterm>evented</firstterm>, which means that any changes will be
+notified.  Control points are said to <firstterm>subscribe</firstterm> to
+a state variable to receive change notifications.
+
+
+# UDN
+> Unique Device Name
+
+> An unique identifier which is <emphasis>unique</emphasis> for every
+device but <emphasis>never changes</emphasis> for each particular
+device.
+
+> A common practise is to generate a unique UDN on first boot from a
+random seed, or use some unique and persistent property such as the
+device's MAC address to create the UDN.
+
+See also:
+
+- [Device](#device)
diff --git a/doc/gupnp.toml.in b/doc/gupnp.toml.in
index efba00f..e416445 100644
--- a/doc/gupnp.toml.in
+++ b/doc/gupnp.toml.in
@@ -42,7 +42,9 @@ docs_url = "http://www.xmlsoft.org/html/index.html";
 [extra]
 content_files = [
     "client-tutorial.md",
-    "server-tutorial.md"
+    "server-tutorial.md",
+    "choosing-a-context-manager.md",
+    "glossary.md"
 ]
 
 content_images = [
diff --git a/doc/meson.build b/doc/meson.build
index 3cf2a38..55a40f2 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -31,7 +31,13 @@ if get_option('gtk_doc')
           '--content-dir=@0@'.format(meson.current_source_dir()),
           '@INPUT1@',
       ],
-      depend_files : [gupnp_toml, 'client-tutorial.md', 'server-tutorial.md'],
+      depend_files : [
+          gupnp_toml,
+          'client-tutorial.md',
+          'server-tutorial.md',
+          'choosing-a-context-manager.md',
+          'glossary.md',
+      ],
       build_by_default: true,
       install: true,
       install_dir : docs_dir,
diff --git a/doc/server-tutorial.md b/doc/server-tutorial.md
index ca8694c..884b1a2 100644
--- a/doc/server-tutorial.md
+++ b/doc/server-tutorial.md
@@ -265,7 +265,7 @@ void
 set_target_cb (GUPnPService *service, GUPnPServiceAction *action, gpointer user_data)
 {
     gupnp_service_action_get (action,
-                              "NewTargetValue", G_TYPE_BOOLEAN, &amp;status,
+                              "NewTargetValue", G_TYPE_BOOLEAN, &status,
                               NULL);
     gupnp_service_action_return (action);
     gupnp_service_notify (service, "Status", G_TYPE_STRING, status, NULL);
@@ -326,9 +326,9 @@ get_status_cb (GUPnPService *service,
            GUPnPServiceAction *action,
            gpointer user_data)
 {
-switch_get_status_action_set (action, status);
+    switch_get_status_action_set (action, status);
 
-gupnp_service_action_return (action);
+    gupnp_service_action_return (action);
 }
 
 static void
@@ -336,33 +336,33 @@ set_target_cb (GUPnPService *service,
            GUPnPServiceAction *action,
            gpointer user_data)
 {
-switch_set_target_action_get (action, &amp;status);
-switch_status_variable_notify (service, status);
+    switch_set_target_action_get (action, &status);
+    switch_status_variable_notify (service, status);
 
-gupnp_service_action_return (action);
+    gupnp_service_action_return (action);
 }
 
-...
+// ...
 
 switch_get_status_action_connect (service, G_CALLBACK(get_status_cb), NULL);
 switch_set_target_action_connect (service, G_CALLBACK(set_target_cb), NULL);
 ```
 
 Note how many possible problem situations that were run-time errors are 
-  actually compile-time errors when wrappers are used: Action names, 
-  argument names and argument types are easier to get correct (and available
-  in editor autocompletion).
+actually compile-time errors when wrappers are used: Action names, 
+argument names and argument types are easier to get correct (and available
+in editor autocompletion).
 
-  State variable query handlers are implemented in a similar manner, but 
-  they are even simpler as the return value of the handler is the state 
-  variable value.
+State variable query handlers are implemented in a similar manner, but 
+they are even simpler as the return value of the handler is the state 
+variable value.
 
 ```c
 static gboolean
 query_status_cb (GUPnPService *service, 
              gpointer user_data)
 {
-return status;
+    return status;
 }
 
 // ...
diff --git a/libgupnp/gupnp-acl.c b/libgupnp/gupnp-acl.c
index ff8c4f9..b747050 100644
--- a/libgupnp/gupnp-acl.c
+++ b/libgupnp/gupnp-acl.c
@@ -6,23 +6,35 @@
  * SPDX-License-Identifier: LGPL-2.1-or-later
  */
 
+#include <config.h>
+
+#include "gupnp-acl.h"
+#include "gupnp-acl-private.h"
+#include "gupnp-device.h"
+
 /**
- * SECTION:gupnp-acl
- * @short_description: Object providing a simple access control list for
- * GUPnP.
+ * GUPnPAcl:
+ *
+ * Provide simple access control
  *
  * #GUPnPAcl provides either synchronous or asynchronous functions to check
- * whether a peer sould be able to access a resource or not.
+ * whether a peer sould be able to access a resource that is hosted by GUPnP or not.
  *
  * Since: 0.20.11
  */
 
-#include <config.h>
-
-#include "gupnp-acl.h"
-#include "gupnp-acl-private.h"
-#include "gupnp-device.h"
-
+/**
+ * GUPnPAclInterface:
+ * @parent: The parent interface.
+ * @is_allowed: Check whether access to the resource is granted.
+ * @is_allowed_async: Asynchronously check whether the access is granted.
+ * @is_allowed_finish: Conclude the @is_allowed_async operation.
+ * @can_sync: Whether the ACL can do sync queries.
+ *
+ * Implement a simple access control list for GUPnP.
+ *
+ * Since: 0.20.11
+ */
 G_DEFINE_INTERFACE(GUPnPAcl, gupnp_acl, G_TYPE_OBJECT)
 
 static void
@@ -39,8 +51,7 @@ gupnp_acl_default_init (GUPnPAclInterface *klass)
  * unknown.
  * @path: The path being served.
  * @address: IP address of the peer.
- * @agent: (nullable): The User-Agent header of the peer or %NULL if not
- * unknown.
+ * @agent: (nullable): The User-Agent header of the peer or %NULL if unknown.
  * @returns %TRUE if the peer is allowed, %FALSE otherwise
  *
  * Check whether an IP address is allowed to access this resource.
diff --git a/libgupnp/gupnp-acl.h b/libgupnp/gupnp-acl.h
index c382c9f..1a55af4 100644
--- a/libgupnp/gupnp-acl.h
+++ b/libgupnp/gupnp-acl.h
@@ -18,25 +18,8 @@ G_BEGIN_DECLS
 #define GUPNP_TYPE_ACL (gupnp_acl_get_type())
 G_DECLARE_INTERFACE (GUPnPAcl, gupnp_acl, GUPNP, ACL, GObject)
 
-/**
- * GUPnPAcl:
- *
- * Handle to an object implementing the #GUPnPAclInterface interface.
- */
-typedef struct _GUPnPAcl GUPnPAcl;
 
-/**
- * GUPnPAclInterface:
- * @parent: The parent interface.
- * @is_allowed: Check whether access to the resource is granted.
- * @is_allowed_async: Asynchronously check whether the access is granted.
- * @is_allowed_finish: Conclude the @is_allowed_async operation.
- * @can_sync: Whether the ACL can do sync queries.
- *
- * Implement a simple access control list for GUPnP.
- *
- * Since: 0.20.11
- */
+typedef struct _GUPnPAcl GUPnPAcl;
 typedef struct _GUPnPAclInterface GUPnPAclInterface;
 
 /* Forward declarations to avoid recursive includes */
diff --git a/libgupnp/gupnp-context-filter.c b/libgupnp/gupnp-context-filter.c
index e23f0eb..73cc005 100644
--- a/libgupnp/gupnp-context-filter.c
+++ b/libgupnp/gupnp-context-filter.c
@@ -6,18 +6,6 @@
  * SPDX-License-Identifier: LGPL-2.1-or-later
  */
 
-/**
- * SECTION:gupnp-context-filter
- * @short_description: Class for network filtering.
- *
- * #GUPnPContextFilter handles network filtering. It provides API to manage a
- * list of entries that will be used to filter networks. The #GUPnPContextFilter
- * could be enabled or not. If it's enabled but the entries list is empty, it
- * behaves as disabled.
- *
- * Since: 1.4.0
- */
-
 #include "gupnp-context-filter.h"
 
 #include <string.h>
@@ -38,6 +26,37 @@ typedef struct _GUPnPContextFilterPrivate GUPnPContextFilterPrivate;
  * could be enabled or not. If it's enabled but the entries list is empty, it
  * behaves as disabled.
  *
+ * The GUPnPContextFilter is used with the [class@GUPnP.ContextManager]
+ * to narrow down the contexts that notified by it.
+ *
+ * Contexts can be filtered by the following criteria:
+ *
+ *  - Their IP addresses
+ *  - The network device they will live on
+ *  - The name of the network the context would join
+ *
+ *  To add or modify a context filter, you need to retrieve the current context filter
+ *  from the context manger using [method@GUPnP.ContextManager.get_context_filter].
+ *
+ *  By default, a context filter is empty and disabled.
+ *
+ *  For example, to only react to contexts that are appearing on eth0 or when being in the WiFi network with
+ *  the SSID "HomeNetwork", you should do:
+ *
+ *
+ * ```c
+ * GUPnPContextFilter* filter;
+ *
+ * filter = gupnp_context_manager_get_context_filter (manager);
+ * const char *filter_entries[] = {
+ *     "eth0",
+ *     "HomeNetwork",
+ *     NULL
+ * };
+ * gupnp_context_filter_add_entryv (filter, filter_entries);
+ * gupnp_context_filter_set_enabled (filter, TRUE);
+ * ```
+ *
  * Since: 1.4.0
  */
 
diff --git a/libgupnp/gupnp-context-manager.c b/libgupnp/gupnp-context-manager.c
index fa29d65..002ff74 100644
--- a/libgupnp/gupnp-context-manager.c
+++ b/libgupnp/gupnp-context-manager.c
@@ -11,17 +11,6 @@
  *
  */
 
-/**
- * SECTION:gupnp-context-manager
- * @short_description: Manages GUPnPContext objects.
- *
- * A Utility class that takes care of creation and destruction of
- * #GUPnPContext objects for all available network interfaces as they go up
- * (connect) and down (disconnect), respectively.
- *
- * Since: 0.13.0
- */
-
 #define G_LOG_DOMAIN "gupnp-context-manager"
 
 #include <config.h>
@@ -66,6 +55,24 @@ struct _GUPnPContextManagerPrivate {
 };
 typedef struct _GUPnPContextManagerPrivate GUPnPContextManagerPrivate;
 
+/**
+ * GUPnPContextManager:
+ *
+ * Manages GUPnPContext objects.
+ *
+ * An utility class that takes care of dynamic creation and destruction of
+ * #GUPnPContext objects for all available network interfaces as they go up
+ * (connect) and down (disconnect), respectively.
+ *
+ * The final implementation depends either on the underlying operating system
+ * or can configured during compile time.
+ *
+ * It also provides a simple filtering facility if requirted. See 
[method@GUPnP.ContextManager.get_context_filter] and
+ * [class@GUPnP.ContextFilter] for details.
+ *
+ * Since: 0.14.0
+ */
+
 G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GUPnPContextManager,
                                      gupnp_context_manager,
                                      G_TYPE_OBJECT)
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]