From 00d029f81d24e71c32672660e866dd7de75729fe Mon Sep 17 00:00:00 2001 From: Jonathan Maw Date: Tue, 7 Aug 2012 16:51:10 +0100 Subject: Add documentation to the ShutdownClient class --- NEWS | 1 + common/shutdown-client.c | 132 +++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 128 insertions(+), 5 deletions(-) diff --git a/NEWS b/NEWS index 5b80c9a..90497fe 100644 --- a/NEWS +++ b/NEWS @@ -7,6 +7,7 @@ x.y.z GLib) * Add documentation for the JobManager class * Add documentation for the LAHandlerService class +* Add documentation for the ShutdownClient class * Add documentation for the TargetStartupMonitor class * Add documentation for the WatchdogClient class * Add documentation for the NodeStartupControllerApplication class diff --git a/common/shutdown-client.c b/common/shutdown-client.c index 6df5138..fb62ed0 100644 --- a/common/shutdown-client.c +++ b/common/shutdown-client.c @@ -20,6 +20,25 @@ +/** + * SECTION: shutdown-client + * @title: ShutdownClient + * @short_description: A class to bundle information about a #ShutdownConsumer. + * @stability: Internal + * + * The #ShutdownClient is a container for a #ShutdownConsumerSkeleton if it is being used + * by the #LAHandlerService in the Node Startup Controller, and a #ShutdownConsumerProxy + * if it is being used by the #NSMConsumerService in the Node State Manager Dummy. + * + * The #LAHandlerService uses it to identify which #ShutdownConsumer was told to shut + * down, which it will then use to stop the associated systemd unit. + * + * The #NSMConsumerService uses it to locate the #ShutdownConsumer, shut it down with the + * appropriate mode, and wait for an appropriate length of time when expecting a response. + */ + + + /* property identifiers */ enum { @@ -78,6 +97,12 @@ shutdown_client_class_init (ShutdownClientClass *klass) gobject_class->get_property = shutdown_client_get_property; gobject_class->set_property = shutdown_client_set_property; + /** + * ShutdownClient:bus-name: + * + * The bus name which this shutdown consumer is registered with. + * e.g. org.genivi.NodeStartupController1. + */ g_object_class_install_property (gobject_class, PROP_BUS_NAME, g_param_spec_string ("bus-name", @@ -88,6 +113,12 @@ shutdown_client_class_init (ShutdownClientClass *klass) G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS)); + /** + * ShutdownClient:object-path: + * + * The D-Bus object path this shutdown consumer uses. + * e.g. /org/genivi/NodeStartupController1/ShutdownConsumer/1 + */ g_object_class_install_property (gobject_class, PROP_OBJECT_PATH, g_param_spec_string ("object-path", @@ -98,6 +129,12 @@ shutdown_client_class_init (ShutdownClientClass *klass) G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS)); + /** + * ShutdownClient:shutdown-mode: + * + * The shutdown mode of this shutdown client. + * For a full list of shutdown modes, see #NSMShutdownType. + */ g_object_class_install_property (gobject_class, PROP_SHUTDOWN_MODE, g_param_spec_flags ("shutdown-mode", @@ -109,6 +146,12 @@ shutdown_client_class_init (ShutdownClientClass *klass) G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS)); + /** + * ShutdownClient:timeout: + * + * The amount of time the Node State Manager will wait before deciding that the + * shutdown client is not responding. + */ g_object_class_install_property (gobject_class, PROP_TIMEOUT, g_param_spec_uint ("timeout", @@ -119,6 +162,11 @@ shutdown_client_class_init (ShutdownClientClass *klass) G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS)); + /** + * ShutdownClient:consumer: + * + * The #ShutdownConsumerSkeleton or #ShutdownConsumerProxy for this shutdown client. + */ g_object_class_install_property (gobject_class, PROP_CONSUMER, g_param_spec_object ("consumer", @@ -227,6 +275,21 @@ shutdown_client_set_property (GObject *object, +/** + * shutdown_client_new: + * @bus_name: The bus name which this shutdown consumer is registered with. + * e.g. org.genivi.NodeStartupController1. + * @object_path: The D-Bus object path this shutdown consumer uses. + * e.g. /org/genivi/NodeStartupController1/ShutdownConsumer/1 + * @shutdown_mode: The shutdown mode of this shutdown client. + * For a full list of shutdown modes, see #NSMShutdownType. + * @timeout: The amount of time the Node State Manager will wait before deciding + * that the shutdown client is not responding. + * + * Creates a new shutdown client. + * + * Returns: A new #ShutdownClient object. + */ ShutdownClient * shutdown_client_new (const gchar *bus_name, const gchar *object_path, @@ -243,6 +306,14 @@ shutdown_client_new (const gchar *bus_name, +/** + * shutdown_client_get_bus_name: + * @client: The #ShutdownClient. + * + * Retrieves the bus name of a #ShutdownClient. + * + * Returns: The bus name for this #ShutdownClient. + */ const gchar * shutdown_client_get_bus_name (ShutdownClient *client) { @@ -252,6 +323,14 @@ shutdown_client_get_bus_name (ShutdownClient *client) +/** + * shutdown_client_get_object_path: + * @client: The #ShutdownClient. + * + * Retrieves the object path of a #ShutdownClient. + * + * Returns: The object path for this #ShutdownClient. + */ const gchar * shutdown_client_get_object_path (ShutdownClient *client) { @@ -261,6 +340,14 @@ shutdown_client_get_object_path (ShutdownClient *client) +/** + * shutdown_client_get_shutdown_mode: + * @client: The #ShutdownClient. + * + * Retrieves the %shutdown_mode of a #ShutdownClient. + * + * Returns: The %shutdown_mode for this #ShutdownClient. + */ NSMShutdownType shutdown_client_get_shutdown_mode (ShutdownClient *client) { @@ -269,7 +356,13 @@ shutdown_client_get_shutdown_mode (ShutdownClient *client) } - +/** + * shutdown_client_set_shutdown_mode: + * @client: The #ShutdownClient. + * @shutdown_mode: The #NSMShutdownType for the @client. + * + * Sets the shutdown_mode of @client. + */ void shutdown_client_set_shutdown_mode (ShutdownClient *client, NSMShutdownType shutdown_mode) @@ -288,7 +381,14 @@ shutdown_client_set_shutdown_mode (ShutdownClient *client, } - +/** + * shutdown_client_get_timeout: + * @client: The #ShutdownClient. + * + * Retrieves the %timeout of a #ShutdownClient. + * + * Returns: The %timeout for this #ShutdownClient. + */ guint shutdown_client_get_timeout (ShutdownClient *client) { @@ -297,7 +397,13 @@ shutdown_client_get_timeout (ShutdownClient *client) } - +/** + * shutdown_client_set_timeout: + * @client: The #ShutdownClient. + * @timeout: The timeout for @client. + * + * Sets the timeout of @client. + */ void shutdown_client_set_timeout (ShutdownClient *client, guint timeout) @@ -316,7 +422,17 @@ shutdown_client_set_timeout (ShutdownClient *client, } - +/** + * shutdown_client_get_consumer: + * @client: The #ShutdownClient + * + * Retrieves the %consumer of a #ShutdownClient. + * + *Note: Ownership of the #ShutdownConsumer is not transferred. The object returned by this + * function should not be released. + * + * Returns: The #ShutdownConsumer for this #ShutdownClient. + */ ShutdownConsumer * shutdown_client_get_consumer (ShutdownClient *client) { @@ -325,7 +441,13 @@ shutdown_client_get_consumer (ShutdownClient *client) } - +/** + * shutdown_client_set_consumer: + * @client: The #ShutdownClient. + * @consumer: The #ShutdownConsumer for @client. + * + * Sets the consumer of @client. + */ void shutdown_client_set_consumer (ShutdownClient *client, ShutdownConsumer *consumer) -- cgit v1.2.1