From 06fc0ef35dc7e5e6295ab9beecba6071e556d55e Mon Sep 17 00:00:00 2001 From: Lubomir Rintel Date: Tue, 7 Mar 2023 13:51:57 +0100 Subject: cloud-setup: document detect() and get_config() methods Clarify that detect() needs to succeed before get_config(). I thought it's sort of common sense, but it's better to be explicit as we're going to rely on that. (cherry picked from commit 088bfd817ab5eb8aa0fb9cffe52fa3f456030ecc) (cherry picked from commit d99864ccba6d7c9bac66dcbbcc49c01be0ddd719) --- src/nm-cloud-setup/nmcs-provider.h | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/src/nm-cloud-setup/nmcs-provider.h b/src/nm-cloud-setup/nmcs-provider.h index 502f1d0323..3662fbe391 100644 --- a/src/nm-cloud-setup/nmcs-provider.h +++ b/src/nm-cloud-setup/nmcs-provider.h @@ -152,8 +152,36 @@ typedef struct { const char *_name; const char *_env_provider_enabled; + /** + * detect: + * @self: the #NMCSProvider + * @task: a #GTask that's completed when the detection finishes. + * + * Checks whether the metadata of a particular cloud provider is + * accessible on the host machine. The check runs asynchronously. + * + * When the check finishes, @task is completed. If the check was + * successful, @task returns a gboolean of %TRUE. Otherwise + * a %FALSE value or an error is returned. + * + * The routine has to be called before the get_config() can be + * used. + */ void (*detect)(NMCSProvider *self, GTask *task); + /** + * get_config: + * @self: the #NMCSProvider + * @get_config_data: encapsulates a #GTask and network configuration data + * + * Collects the network configuration from metadata service of a + * particular cloud provider. The metadata is traversed and checked + * asynchronously, completing a task encapsulated in @get_config_data + * upon finishing. + * + * Call to detect() with a successful result is necessary before + * using this routine. + */ void (*get_config)(NMCSProvider *self, NMCSProviderGetConfigTaskData *get_config_data); } NMCSProviderClass; -- cgit v1.2.1