[gupnp/wip/gi-docgen: 14/14] wip
- From: Jens Georg <jensgeorg src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gupnp/wip/gi-docgen: 14/14] wip
- Date: Thu, 30 Dec 2021 09:18:06 +0000 (UTC)
commit 7082e75d81d77d1f98599b48d09b1f2c9a8f2e2d
Author: Jens Georg <mail jensge org>
Date: Sat Sep 18 18:32:39 2021 +0200
wip
libgupnp/gupnp-context-manager.c | 68 +++++++---
libgupnp/gupnp-control-point.c | 53 +++++---
libgupnp/gupnp-device-info.c | 270 ++++++++++++++++++--------------------
libgupnp/gupnp-device.c | 18 +--
libgupnp/gupnp-resource-factory.c | 1 +
5 files changed, 222 insertions(+), 188 deletions(-)
---
diff --git a/libgupnp/gupnp-context-manager.c b/libgupnp/gupnp-context-manager.c
index 06ab805..68bb59c 100644
--- a/libgupnp/gupnp-context-manager.c
+++ b/libgupnp/gupnp-context-manager.c
@@ -67,7 +67,7 @@ typedef struct _GUPnPContextManagerPrivate GUPnPContextManagerPrivate;
* 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
+ * It also provides a simple filtering facility if required. See
[method@GUPnP.ContextManager.get_context_filter] and
* [class@GUPnP.ContextFilter] for details.
*
* Since: 0.14.0
@@ -490,7 +490,7 @@ gupnp_context_manager_class_init (GUPnPContextManagerClass *klass)
object_class->dispose = gupnp_context_manager_dispose;
/**
- * GUPnPContextManager:port:
+ * GUPnPContextManager:port:(attributes org.gtk.Property.get=gupnp_context_manager_get_port)
*
* Port the contexts listen on, or 0 if you don't care what
* port is used by #GUPnPContext objects created by this object.
@@ -508,7 +508,7 @@ gupnp_context_manager_class_init (GUPnPContextManagerClass *klass)
G_PARAM_STATIC_NICK |
G_PARAM_STATIC_BLURB));
/**
- * GUPnPContextManager:family:
+ * GUPnPContextManager:family:(attributes
org.gtk.Property.get=gupnp_context_manager_get_socket_family)
*
* The socket family to create contexts for. Use %G_SOCKET_FAMILY_INVALID
* for any or %G_SOCKET_FAMILY_IPV4 for IPv4 contexts or
@@ -529,7 +529,7 @@ gupnp_context_manager_class_init (GUPnPContextManagerClass *klass)
G_PARAM_STATIC_STRINGS));
/**
- * GUPnPContextManager:uda-version:
+ * GUPnPContextManager:uda-version:(attributes
org.gtk.Property.get=gupnp_context_manager_get_uda_version)
*
* The UDA version the contexts will support. Use %GSSDP_UDA_VERSION_UNSPECIFIED
* for using the default UDA version.
@@ -549,7 +549,7 @@ gupnp_context_manager_class_init (GUPnPContextManagerClass *klass)
G_PARAM_STATIC_STRINGS));
/**
- * GUPnPContextManager:context-filter:
+ * GUPnPContextManager:context-filter:(attributes
org.gtk.Property.get=gupnp_context_manager_get_context_filter)
*
* The context filter to use.
**/
@@ -612,7 +612,7 @@ gupnp_context_manager_class_init (GUPnPContextManagerClass *klass)
*
* Factory-method to create a new #GUPnPContextManager. The final type of the
* #GUPnPContextManager depends on the compile-time selection or - in case of
- * NetworkManager - on its availability during runtime. If it is not available,
+ * NetworkManager - on its availability during run-time. If it is not available,
* the implementation falls back to the basic Unix context manager instead.
*
* Equivalent to calling #gupnp_context_manager_create_full (%GSSDP_UDA_VERSION_1_0, %G_SOCKET_FAMILY_IPV4,
port);
@@ -638,7 +638,7 @@ gupnp_context_manager_create (guint port)
*
* Factory-method to create a new #GUPnPContextManager. The final type of the
* #GUPnPContextManager depends on the compile-time selection or - in case of
- * NetworkManager - on its availability during runtime. If it is not available,
+ * NetworkManager - on its availability during run-time. If it is not available,
* the implementation falls back to the basic Unix context manager instead.
*
* Returns: (transfer full): A new #GUPnPContextManager object.
@@ -745,9 +745,23 @@ gupnp_context_manager_rescan_control_points (GUPnPContextManager *manager)
*
* By calling this function, you are asking @manager to keep a reference to
* @control_point until its associated #GUPnPContext is no longer available.
- * You usually want to call this function from
- * #GUPnPContextManager::context-available handler after you create a
+ * You usually want to call this function from your
+ * [signal@GUPnP.ContextManager::context-available] handler after you create a
* #GUPnPControlPoint object for the newly available context.
+ * You usually then give up your own reference to the control point so it will be
+ * automatically destroyed if its context is no longer available.
+ *
+ * This function is mainly useful when implementing a UPnP client.
+ *
+ * ```c
+ * void on_context_available (GUPnPContextManager *manager, GUPnPContext *context, gpointer user_data)
+ * {
+ * GUPnPControlPoint *cp = gupnp_control_point_new (context,
"urn:schemas-upnp-org:device:MediaRenderer:1");
+ * gupnp_context_manager_manage_control_point (manager, cp);
+ * // Subscribe to control point's signals etc.
+ * g_object_unref (cp);
+ * }
+ * ```
*
* Since: 0.14.0
**/
@@ -773,9 +787,25 @@ gupnp_context_manager_manage_control_point (GUPnPContextManager *manager,
* By calling this function, you are asking @manager to keep a reference to
* @root_device when its associated #GUPnPContext is no longer available. You
* usually want to call this function from
- * #GUPnPContextManager::context-available handler after you create a
+ * [signal@GUPnP.ContextManager::context-available] handler after you create a
* #GUPnPRootDevice object for the newly available context.
*
+ * You usually then give up your own reference to the root device so it will be
+ * automatically destroyed if its context is no longer available.
+ *
+ * This function is mainly useful when implementing a UPnP client.
+ *
+ * ```c
+ * void on_context_available (GUPnPContextManager *manager, GUPnPContext *context, gpointer user_data)
+ * {
+ * GError *error = NULL;
+ *
+ * GUPnPRootDevice *rd = gupnp_root_device_new (context, "BasicLight1.xml", ".", &error);
+ * gupnp_context_manager_manage_root_device (manager, rd);
+ * // Subscribe to control point's signals etc.
+ * g_object_unref (rd);
+ * }
+ * ```
* Since: 0.14.0
**/
void
@@ -793,11 +823,11 @@ gupnp_context_manager_manage_root_device (GUPnPContextManager *manager,
}
/**
- * gupnp_context_manager_get_port:
+ * gupnp_context_manager_get_port:(attributes org.gtk.Method.get_property=port)
* @manager: A #GUPnPContextManager
*
* Get the network port associated with this context manager.
- * Returns: The network port asssociated with this context manager.
+ * Returns: The network port associated with this context manager.
*
* Since: 0.20.0
*/
@@ -814,13 +844,15 @@ gupnp_context_manager_get_port (GUPnPContextManager *manager)
}
/**
- * gupnp_context_manager_get_context_filter:
+ * gupnp_context_manager_get_context_filter:(attributes org.gtk.Method.get_property=context-filter)
* @manager: A #GUPnPContextManager
*
* Get the #GUPnPContextFilter associated with @manager.
*
- * Returns: (transfer none): The #GUPnPContextFilter asssociated with this
+ * Returns: (transfer none): The #GUPnPContextFilter associated with this
* context manager.
+ *
+ * Since: 1.4.0
*/
GUPnPContextFilter *
gupnp_context_manager_get_context_filter (GUPnPContextManager *manager)
@@ -840,9 +872,9 @@ gupnp_context_manager_get_context_filter (GUPnPContextManager *manager)
*
* Get the #GUPnPContextFilter associated with @manager.
*
- * Returns: (transfer none): The #GUPnPContextFilter asssociated with this
+ * Returns: (transfer none): The #GUPnPContextFilter associated with this
* context manager.
- * Deprecated: 1.4.0: Use gupnp_context_manager_get_context_filter() instead.
+ * Deprecated: 1.4.0: Use [method@GUPnP.ContextManager.get_context_filter] instead.
*/
GUPnPWhiteList *
gupnp_context_manager_get_white_list (GUPnPContextManager *manager)
@@ -851,7 +883,7 @@ gupnp_context_manager_get_white_list (GUPnPContextManager *manager)
}
/**
- * gupnp_context_manager_get_socket_family:
+ * gupnp_context_manager_get_socket_family:(attributes org.gtk.Method.get_property=family)
* @manager: A #GUPnPContextManager
*
* Get the #GSocketFamily the contexts are created for. Can be
@@ -875,7 +907,7 @@ gupnp_context_manager_get_socket_family (GUPnPContextManager *manager)
}
/**
- * gupnp_context_manager_get_uda_version:
+ * gupnp_context_manager_get_uda_version:(attributes org.gtk.Method.get_property=uda-version)
* @manager: A #GUPnPContextManager
*
* Get the UDA protocol version the contexts are implementing
diff --git a/libgupnp/gupnp-control-point.c b/libgupnp/gupnp-control-point.c
index 1e028f4..ab46561 100644
--- a/libgupnp/gupnp-control-point.c
+++ b/libgupnp/gupnp-control-point.c
@@ -10,7 +10,7 @@
/**
* GUPnPControlPoint:
*
- * Class for resource discovery.
+ * Network resource discovery.
*
* #GUPnPControlPoint handles device and service discovery. After creating
* a control point and activating it using [method@GSSDP.ResourceBrowser.set_active],
@@ -1027,7 +1027,7 @@ gupnp_control_point_class_init (GUPnPControlPointClass *klass)
gupnp_control_point_resource_unavailable;
/**
- * GUPnPControlPoint:resource-factory:
+ * GUPnPControlPoint:resource-factory:(attributes
org.gtk.Property.get=gupnp_control_point_get_resource_factory)
*
* The resource factory to use. Set to NULL for default factory.
**/
@@ -1137,8 +1137,8 @@ gupnp_control_point_class_init (GUPnPControlPointClass *klass)
* Create a new #GUPnPControlPoint with the specified @context and @target.
*
* @target should be a service or device name, such as
- * <literal>urn:schemas-upnp-org:service:WANIPConnection:1</literal> or
- * <literal>urn:schemas-upnp-org:device:MediaRenderer:1</literal>.
+ * `urn:schemas-upnp-org:service:WANIPConnection:1` or
+ * `urn:schemas-upnp-org:device:MediaRenderer:1`.
*
* Return value: A new #GUPnPControlPoint object.
**/
@@ -1165,8 +1165,12 @@ gupnp_control_point_new (GUPnPContext *context,
* @target.
*
* @target should be a service or device name, such as
- * <literal>urn:schemas-upnp-org:service:WANIPConnection:1</literal> or
- * <literal>urn:schemas-upnp-org:device:MediaRenderer:1</literal>.
+ * `urn:schemas-upnp-org:service:WANIPConnection:1` or
+ * `urn:schemas-upnp-org:device:MediaRenderer:1`.
+ *
+ * By passing a custom `GUPnPResourceFactory`, the proxies handed out in ::device-available and
+ * ::service-available can be overridden to hand out custom classes instead of the generic
+ * [class@GUPnP.ServiceProxy] and [class@GUPnP.DeviceProxy].
*
* Return value: A new #GUPnPControlPoint object.
**/
@@ -1194,6 +1198,7 @@ gupnp_control_point_new_full (GUPnPContext *context,
* Get the #GUPnPControlPoint associated with @control_point.
*
* Returns: (transfer none): The #GUPnPContext.
+ * Deprecated: 1.4.0: Use [method@GSSDP.ResourceBrowser.get_client] instead.
**/
GUPnPContext *
gupnp_control_point_get_context (GUPnPControlPoint *control_point)
@@ -1212,11 +1217,17 @@ gupnp_control_point_get_context (GUPnPControlPoint *control_point)
* gupnp_control_point_list_device_proxies:
* @control_point: A #GUPnPControlPoint
*
- * Get the #GList of discovered #GUPnPDeviceProxy objects. Do not free the list
- * nor its elements.
+ * Get the list of #GUPnPDeviceProxy objects the control point currently assumes to
+ * be active.
+ *
+ * Since a device might have gone offline without signalizing it, but
+ * the automatic resource timeout has not happened yet, it is possible that some of
+ * the devices listed are not available anymore on the network.
+ *
+ * Do not free the list nor its elements.
*
- * Return value: (element-type GUPnP.DeviceProxy) (transfer none): a #GList of
- * #GUPnPDeviceProxy objects.
+ * Return value: (element-type GUPnP.DeviceProxy) (transfer none): Device proxies
+ * currently assumed to be active.
**/
const GList *
gupnp_control_point_list_device_proxies (GUPnPControlPoint *control_point)
@@ -1234,11 +1245,17 @@ gupnp_control_point_list_device_proxies (GUPnPControlPoint *control_point)
* gupnp_control_point_list_service_proxies:
* @control_point: A #GUPnPControlPoint
*
- * Get the #GList of discovered #GUPnPServiceProxy objects. Do not free the
- * list nor its elements.
+ * Get the list of discovered #GUPnPServiceProxy objects the control point currently assumes to
+ * be active.
+ *
+ * Since a device might have gone offline without signalizing it, but
+ * the automatic resource timeout has not happened yet, it is possible that some of
+ * the services listed are not available anymore on the network.
+ *
+ * Do not free the list nor its elements.
*
- * Return value: (element-type GUPnP.ServiceProxy) (transfer none): a #GList
- * of #GUPnPServiceProxy objects.
+ * Return value: (element-type GUPnP.ServiceProxy) (transfer none): Service proxies
+ * currently assumed to be active.
**/
const GList *
gupnp_control_point_list_service_proxies (GUPnPControlPoint *control_point)
@@ -1253,12 +1270,14 @@ gupnp_control_point_list_service_proxies (GUPnPControlPoint *control_point)
}
/**
- * gupnp_control_point_get_resource_factory:
+ * gupnp_control_point_get_resource_factory:(attributes org.gtk.Method.get_property=resource-factory)
* @control_point: A #GUPnPControlPoint
*
- * Get the #GUPnPResourceFactory used by the @control_point.
+ * Get the #GUPnPResourceFactory used by the @control_point. If none was set during construction
+ * by calling [ctor@GUPnP.ControlPoint.new_full], equivalent to calling
+ * [func@GUPnP.ResourceFactory.get_default]
*
- * Returns: (transfer none): A #GUPnPResourceFactory.
+ * Returns: (transfer none): The #GUPnPResourceFactory used by this control point
**/
GUPnPResourceFactory *
gupnp_control_point_get_resource_factory (GUPnPControlPoint *control_point)
diff --git a/libgupnp/gupnp-device-info.c b/libgupnp/gupnp-device-info.c
index fd3d8ce..51e10d0 100644
--- a/libgupnp/gupnp-device-info.c
+++ b/libgupnp/gupnp-device-info.c
@@ -7,13 +7,6 @@
*
*/
-/**
- * SECTION:gupnp-device-info
- * @short_description: Base abstract class for querying device information.
- *
- * The #GUPnPDeviceInfo base abstract class provides methods for querying
- * device information.
- */
#include <config.h>
#include <string.h>
@@ -39,6 +32,15 @@ struct _GUPnPDeviceInfoPrivate {
};
typedef struct _GUPnPDeviceInfoPrivate GUPnPDeviceInfoPrivate;
+/**
+ * GUPnPDeviceInfo:
+ *
+ * Base abstract class for querying device information.
+ *
+ * The #GUPnPDeviceInfo base abstract class provides methods for querying
+ * device information.
+ */
+
G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GUPnPDeviceInfo,
gupnp_device_info,
G_TYPE_OBJECT)
@@ -195,113 +197,99 @@ gupnp_device_info_class_init (GUPnPDeviceInfoClass *klass)
object_class->finalize = gupnp_device_info_finalize;
/**
- * GUPnPDeviceInfo:resource-factory:
+ * GUPnPDeviceInfo:resource-factory:(attributes
org.gtk.Property.get=gupnp_device_info_get_resource_factory):
*
* The resource factory to use. Set to NULL for default factory.
**/
- g_object_class_install_property
- (object_class,
- PROP_RESOURCE_FACTORY,
- g_param_spec_object ("resource-factory",
- "Resource Factory",
- "The resource factory to use",
- GUPNP_TYPE_RESOURCE_FACTORY,
- G_PARAM_READWRITE |
- G_PARAM_CONSTRUCT_ONLY |
- G_PARAM_STATIC_NAME |
- G_PARAM_STATIC_NICK |
- G_PARAM_STATIC_BLURB));
+ g_object_class_install_property (
+ object_class,
+ PROP_RESOURCE_FACTORY,
+ g_param_spec_object ("resource-factory",
+ "Resource Factory",
+ "The resource factory to use",
+ GUPNP_TYPE_RESOURCE_FACTORY,
+ G_PARAM_READWRITE |
+ G_PARAM_CONSTRUCT_ONLY |
+ G_PARAM_STATIC_STRINGS));
/**
- * GUPnPDeviceInfo:context:
+ * GUPnPDeviceInfo:context:(attributes org.gtk.Property.get=gupnp_device_info_get_context):
*
* The #GUPnPContext to use.
**/
- g_object_class_install_property
- (object_class,
- PROP_CONTEXT,
- g_param_spec_object ("context",
- "Context",
- "The GUPnPContext",
- GUPNP_TYPE_CONTEXT,
- G_PARAM_READWRITE |
- G_PARAM_CONSTRUCT_ONLY |
- G_PARAM_STATIC_NAME |
- G_PARAM_STATIC_NICK |
- G_PARAM_STATIC_BLURB));
+ g_object_class_install_property (
+ object_class,
+ PROP_CONTEXT,
+ g_param_spec_object ("context",
+ "Context",
+ "The GUPnPContext",
+ GUPNP_TYPE_CONTEXT,
+ G_PARAM_READWRITE |
+ G_PARAM_CONSTRUCT_ONLY |
+ G_PARAM_STATIC_STRINGS));
/**
- * GUPnPDeviceInfo:location:
+ * GUPnPDeviceInfo:location:(attributes org.gtk.Property.get=gupnp_device_info_get_location):
*
* The location of the device description file.
**/
- g_object_class_install_property
- (object_class,
- PROP_LOCATION,
- g_param_spec_string ("location",
- "Location",
- "The location of the device description "
- "file",
- NULL,
- G_PARAM_READWRITE |
- G_PARAM_CONSTRUCT |
- G_PARAM_STATIC_NAME |
- G_PARAM_STATIC_NICK |
- G_PARAM_STATIC_BLURB));
+ g_object_class_install_property (
+ object_class,
+ PROP_LOCATION,
+ g_param_spec_string ("location",
+ "Location",
+ "The location of the device description "
+ "file",
+ NULL,
+ G_PARAM_READWRITE | G_PARAM_CONSTRUCT |
+ G_PARAM_STATIC_STRINGS));
/**
- * GUPnPDeviceInfo:udn:
+ * GUPnPDeviceInfo:udn:(attributes org.gtk.Property.get=gupnp_device_info_get_udn):
*
* The UDN of this device.
**/
- g_object_class_install_property
- (object_class,
- PROP_UDN,
- g_param_spec_string ("udn",
- "UDN",
- "The UDN",
- NULL,
- G_PARAM_READWRITE |
- G_PARAM_CONSTRUCT_ONLY |
- G_PARAM_STATIC_NAME |
- G_PARAM_STATIC_NICK |
- G_PARAM_STATIC_BLURB));
+ g_object_class_install_property (
+ object_class,
+ PROP_UDN,
+ g_param_spec_string ("udn",
+ "UDN",
+ "The Unique Device Name",
+ NULL,
+ G_PARAM_READWRITE |
+ G_PARAM_CONSTRUCT_ONLY |
+ G_PARAM_STATIC_STRINGS));
/**
- * GUPnPDeviceInfo:device-type:
+ * GUPnPDeviceInfo:device-type:(attributes org.gtk.Property.get=gupnp_device_info_get_device_type):
*
- * The device type.
+ * The device type, e.g. `urn:schemas-upnp-org:device:InternetGatewayDevice:1`
**/
- g_object_class_install_property
- (object_class,
- PROP_DEVICE_TYPE,
- g_param_spec_string ("device-type",
- "Device type",
- "The device type",
- NULL,
- G_PARAM_READWRITE |
- G_PARAM_CONSTRUCT_ONLY |
- G_PARAM_STATIC_NAME |
- G_PARAM_STATIC_NICK |
- G_PARAM_STATIC_BLURB));
+ g_object_class_install_property (
+ object_class,
+ PROP_DEVICE_TYPE,
+ g_param_spec_string ("device-type",
+ "Device type",
+ "The device type",
+ NULL,
+ G_PARAM_READWRITE |
+ G_PARAM_CONSTRUCT_ONLY |
+ G_PARAM_STATIC_STRINGS));
/**
- * GUPnPDeviceInfo:url-base:
+ * GUPnPDeviceInfo:url-base:(attributes org.gtk.Property.get=gupnp_device_info_get_url_base):
*
* The URL base (#SoupURI).
**/
- g_object_class_install_property
- (object_class,
- PROP_URL_BASE,
- g_param_spec_boxed ("url-base",
- "URL base",
- "The URL base",
- SOUP_TYPE_URI,
- G_PARAM_READWRITE |
- G_PARAM_CONSTRUCT |
- G_PARAM_STATIC_NAME |
- G_PARAM_STATIC_NICK |
- G_PARAM_STATIC_BLURB));
+ g_object_class_install_property (
+ object_class,
+ PROP_URL_BASE,
+ g_param_spec_boxed ("url-base",
+ "URL base",
+ "The URL base",
+ SOUP_TYPE_URI,
+ G_PARAM_READWRITE | G_PARAM_CONSTRUCT |
+ G_PARAM_STATIC_STRINGS));
/**
* GUPnPDeviceInfo:document:
@@ -310,19 +298,17 @@ gupnp_device_info_class_init (GUPnPDeviceInfoClass *klass)
*
* Stability: Private
**/
- g_object_class_install_property
- (object_class,
- PROP_DOCUMENT,
- g_param_spec_object ("document",
- "Document",
- "The XML document related to this "
- "device",
- GUPNP_TYPE_XML_DOC,
- G_PARAM_READWRITE |
- G_PARAM_CONSTRUCT_ONLY |
- G_PARAM_STATIC_NAME |
- G_PARAM_STATIC_NICK |
- G_PARAM_STATIC_BLURB));
+ g_object_class_install_property (
+ object_class,
+ PROP_DOCUMENT,
+ g_param_spec_object ("document",
+ "Document",
+ "The XML document related to this "
+ "device",
+ GUPNP_TYPE_XML_DOC,
+ G_PARAM_READWRITE |
+ G_PARAM_CONSTRUCT_ONLY |
+ G_PARAM_STATIC_STRINGS));
/**
* GUPnPDeviceInfo:element:
@@ -331,22 +317,19 @@ gupnp_device_info_class_init (GUPnPDeviceInfoClass *klass)
*
* Stability: Private
**/
- g_object_class_install_property
- (object_class,
- PROP_ELEMENT,
- g_param_spec_pointer ("element",
- "Element",
- "The XML element related to this "
- "device",
- G_PARAM_WRITABLE |
- G_PARAM_CONSTRUCT |
- G_PARAM_STATIC_NAME |
- G_PARAM_STATIC_NICK |
- G_PARAM_STATIC_BLURB));
+ g_object_class_install_property (
+ object_class,
+ PROP_ELEMENT,
+ g_param_spec_pointer ("element",
+ "Element",
+ "The XML element related to this "
+ "device",
+ G_PARAM_WRITABLE | G_PARAM_CONSTRUCT |
+ G_PARAM_STATIC_STRINGS));
}
/**
- * gupnp_device_info_get_resource_factory:
+ * gupnp_device_info_get_resource_factory:(attributes org.gtk.Method.get_property=resource-factory):
* @device_info: A #GUPnPDeviceInfo
*
* Get the #GUPnPResourceFactory used by the @device_info.
@@ -366,12 +349,12 @@ gupnp_device_info_get_resource_factory (GUPnPDeviceInfo *info)
}
/**
- * gupnp_device_info_get_context:
+ * gupnp_device_info_get_context:(attributes org.gtk.Method.get_property=context):
* @info: A #GUPnPDeviceInfo
*
* Get the associated #GUPnPContext.
*
- * Returns: (transfer none): A #GUPnPContext.
+ * Returns: (transfer none): The #GUPnPContext the devices is operating on.
**/
GUPnPContext *
gupnp_device_info_get_context (GUPnPDeviceInfo *info)
@@ -389,9 +372,9 @@ gupnp_device_info_get_context (GUPnPDeviceInfo *info)
* gupnp_device_info_get_location:
* @info: A #GUPnPDeviceInfo
*
- * Get the location of the device description file.
+ * Get the URL of the device file
*
- * Returns: A constant string.
+ * Returns: A s
**/
const char *
gupnp_device_info_get_location (GUPnPDeviceInfo *info)
@@ -406,7 +389,7 @@ gupnp_device_info_get_location (GUPnPDeviceInfo *info)
}
/**
- * gupnp_device_info_get_url_base:
+ * gupnp_device_info_get_url_base:(attributes org.gtk.Method.get_property=url-base):
* @info: A #GUPnPDeviceInfo
*
* Get the URL base of this device.
@@ -426,7 +409,7 @@ gupnp_device_info_get_url_base (GUPnPDeviceInfo *info)
}
/**
- * gupnp_device_info_get_udn:
+ * gupnp_device_info_get_udn:(attributes org.gtk.Method.get_property=udn):
* @info: A #GUPnPDeviceInfo
*
* Get the Unique Device Name of the device.
@@ -451,10 +434,10 @@ gupnp_device_info_get_udn (GUPnPDeviceInfo *info)
}
/**
- * gupnp_device_info_get_device_type:
+ * gupnp_device_info_get_device_type:(attributes org.gtk.Method.get_property=device-type):
* @info: A #GUPnPDeviceInfo
*
- * Get the UPnP device type.
+ * Get the UPnP device type of this #GUPnPDeviceInfo, e.g.
`urn:schemas-upnp-org:device:InternetGatewayDevice:1`
*
* Returns: A constant string, or %NULL.
**/
@@ -481,7 +464,8 @@ gupnp_device_info_get_device_type (GUPnPDeviceInfo *info)
*
* Get the friendly name of the device.
*
- * Return value: A string, or %NULL. g_free() after use.
+ * Return value:(nullable)(transfer full):A newly allocated string containing the
+ * "friendly name" of the device, or %NULL if not available. g_free() after use.
**/
char *
gupnp_device_info_get_friendly_name (GUPnPDeviceInfo *info)
@@ -502,7 +486,8 @@ gupnp_device_info_get_friendly_name (GUPnPDeviceInfo *info)
*
* Get the manufacturer of the device.
*
- * Return value:(nullable)(transfer full): A string, or %NULL. g_free() after use.
+ * Return value:(nullable)(transfer full): A newly allocated string containing the
+ * manufacturer of the device, or %NULL if not available. g_free() after use.
**/
char *
gupnp_device_info_get_manufacturer (GUPnPDeviceInfo *info)
@@ -671,7 +656,7 @@ gupnp_device_info_get_upc (GUPnPDeviceInfo *info)
* @info: A #GUPnPDeviceInfo
*
* Get an URL pointing to the device's presentation page, for web-based
- * administration.
+ * administration, if available.
*
* Return value:(nullable)(transfer full): A string, or %NULL. g_free() after use.
**/
@@ -723,12 +708,8 @@ icon_parse (xmlNode *element)
static void
icon_free (Icon *icon)
{
- if (icon->mime_type)
- xmlFree (icon->mime_type);
-
- if (icon->url)
- xmlFree (icon->url);
-
+ g_clear_pointer (&icon->mime_type, xmlFree);
+ g_clear_pointer (&icon->url, xmlFree);
g_slice_free (Icon, icon);
}
@@ -753,7 +734,9 @@ icon_free (Icon *icon)
* returned icon, or %NULL
*
* Get an URL pointing to the icon most closely matching the
- * given criteria, or %NULL. If @requested_mime_type is set, only icons with
+ * given criteria, or %NULL.
+ *
+ * If @requested_mime_type is set, only icons with
* this mime type will be returned. If @requested_depth is set, only icons with
* this or lower depth will be returned. If @requested_width and/or
* @requested_height are set, only icons that are this size or smaller are
@@ -997,11 +980,12 @@ resource_type_match (const char *query,
* gupnp_device_info_list_dlna_device_class_identifier:
* @info: A #GUPnPDeviceInfo
*
- * Get a #GList of strings that represent the device class and version as
- * announced in the device description file using the <dlna:X_DLNADOC>
- * element.
+ * Get a list of strings that represent the device class and version as
+ * announced in the device description file using the `<dlna:X_DLNADOC>`
+ * element, e.g. `DMS-1.51`, `M-DMS-1.51` and so on.
+ *
* Returns:(nullable)(transfer full) (element-type utf8): a #GList of newly allocated strings or
- * %NULL if the device description doesn't contain the <dlna:X_DLNADOC>
+ * %NULL if the device description doesn't contain any `<dlna:X_DLNADOC>`
* element.
*
* Since: 0.20.4
@@ -1107,8 +1091,8 @@ gupnp_device_info_list_dlna_capabilities (GUPnPDeviceInfo *info)
* This function provides generic access to the contents of arbitrary elements
* in the device description file.
*
- * Return value:(nullable)(transfer full): a newly allocated string or %NULL if the device
- * description doesn't contain the given @element
+ * Return value:(nullable)(transfer full): a newly allocated string containing the
+ * requested value or %NULL if the device description doesn't contain the given @element
*
* Since: 0.14.0
**/
@@ -1132,8 +1116,7 @@ gupnp_device_info_get_description_value (GUPnPDeviceInfo *info,
* @info: A #GUPnPDeviceInfo
*
* Get a #GList of new objects implementing #GUPnPDeviceInfo
- * representing the devices directly contained in @info. The returned list
- * should be g_list_free()'d and the elements should be g_object_unref()'d.
+ * representing the devices directly contained in @info, excluding itself.
*
* Note that devices are not cached internally, so that every time you
* call this function new objects are created. The application
@@ -1141,7 +1124,7 @@ gupnp_device_info_get_description_value (GUPnPDeviceInfo *info,
* them.
*
* Return value:(nullable)(element-type GUPnP.DeviceInfo) (transfer full): a #GList of
- * new #GUPnPDeviceInfo objects.
+ * new #GUPnPDeviceInfo objects or %NULL if no devices are
**/
GList *
gupnp_device_info_list_devices (GUPnPDeviceInfo *info)
@@ -1229,7 +1212,7 @@ gupnp_device_info_list_device_types (GUPnPDeviceInfo *info)
* @info: A #GUPnPDeviceInfo
* @type: The type of the device to be retrieved.
*
- * Get the service with type @type directly contained in @info as
+ * Get the device with type @type directly contained in @info as
* a new object implementing #GUPnPDeviceInfo, or %NULL if no such device
* was found. The returned object should be unreffed when done.
*
@@ -1347,7 +1330,7 @@ gupnp_device_info_list_services (GUPnPDeviceInfo *info)
* @info: A #GUPnPDeviceInfo
*
* Get a #GList of strings representing the types of the services
- * directly contained in @info.
+ * directly contained in @info, but not in its subdevices.
*
* Return value: (nullable)(element-type utf8) (transfer full): A #GList of strings. The
* elements should be g_free()'d and the list should be g_list_free()'d.
@@ -1393,8 +1376,7 @@ gupnp_device_info_list_service_types (GUPnPDeviceInfo *info)
* @type: The type of the service to be retrieved.
*
* Get the service with type @type directly contained in @info as a new object
- * implementing #GUPnPServiceInfo, or %NULL if no such device was found. The
- * returned object should be unreffed when done.
+ * implementing #GUPnPServiceInfo, or %NULL if no such device was found.
*
* Note that services are not cached internally, so that every time you call
* this function a new object is created. The application must cache any used
diff --git a/libgupnp/gupnp-device.c b/libgupnp/gupnp-device.c
index 71b11cf..9dfef84 100644
--- a/libgupnp/gupnp-device.c
+++ b/libgupnp/gupnp-device.c
@@ -7,15 +7,6 @@
*
*/
-/**
- * SECTION:gupnp-device
- * @short_description: Class for device implementations.
- *
- * #GUPnPDevice allows for retrieving a device's subdevices
- * and services. #GUPnPDevice implements the #GUPnPDeviceInfo
- * interface.
- */
-
#include <config.h>
#include <string.h>
@@ -30,6 +21,15 @@ struct _GUPnPDevicePrivate {
};
typedef struct _GUPnPDevicePrivate GUPnPDevicePrivate;
+/**
+ * GUPnPDevice:
+ *
+ * Base class for UPnP device implementations.
+ *
+ * #GUPnPDevice allows for retrieving a device's sub-devices
+ * and services. #GUPnPDevice implements the #GUPnPDeviceInfo
+ * interface.
+ */
G_DEFINE_TYPE_WITH_PRIVATE (GUPnPDevice,
gupnp_device,
GUPNP_TYPE_DEVICE_INFO)
diff --git a/libgupnp/gupnp-resource-factory.c b/libgupnp/gupnp-resource-factory.c
index 51f121f..f73dfbb 100644
--- a/libgupnp/gupnp-resource-factory.c
+++ b/libgupnp/gupnp-resource-factory.c
@@ -11,6 +11,7 @@
/**
* GUPnPResourceFactory:
+ *
* Associating custom Services, Devices, ServiceProxies and DeviceProxies with UPnP types.
*
* #GUPnPResourceFactory objects are used by [class@GUPnP.ControlPoint],
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
