traversity/traversity

Create documentation for TraversityDiscoverer

20 months ago, Gary Kramlich
ce9e6617890a
Parents febd40cedbee
Children 1fab141c84ff
Create documentation for TraversityDiscoverer

Testing Done:
Compiled and verified that all the docs were popuplated for `TraversityDiscoverer`

Bugs closed: TRAVERSITY-4

Reviewed at https://reviews.imfreedom.org/r/1890/
2 files changed, 174 insertions(+), 0 deletions(-)
  • +28 -0
    traversity/traversitydiscoverer.c
  • +146 -0
    traversity/traversitydiscoverer.h
    • --- a/traversity/traversitydiscoverer.c Tue Oct 04 03:24:40 2022 -0500
    +++ b/traversity/traversitydiscoverer.c Wed Oct 05 00:53:02 2022 -0500
    @@ -109,24 +109,52 @@
    obj_class->set_property = traversity_discoverer_set_property;
    obj_class->dispose = traversity_discoverer_dispose;
    + /**
    + * TraversityDiscoverer:local-ipv4:
    + *
    + * The local IPv4 address if found or %NULL.
    + *
    + * Since: 1.0.0
    + */
    properties[PROP_LOCAL_IPV4] = g_param_spec_object(
    "local-ipv4", "local-ipv4",
    "The discovered local ipv4 address",
    G_TYPE_OBJECT,
    G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
    + /**
    + * TraversityDiscoverer:local-ipv6:
    + *
    + * The local IPv6 address if found or %NULL.
    + *
    + * Since: 1.0.0
    + */
    properties[PROP_LOCAL_IPV6] = g_param_spec_object(
    "local-ipv6", "local-ipv6",
    "The discovered local ipv6 address",
    G_TYPE_OBJECT,
    G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
    + /**
    + * TraversityDiscoverer:public-ipv4:
    + *
    + * The public IPv4 address if found or %NULL.
    + *
    + * Since: 1.0.0
    + */
    properties[PROP_PUBLIC_IPV4] = g_param_spec_object(
    "public-ipv4", "public-ipv4",
    "The discovered public ipv4 address",
    G_TYPE_OBJECT,
    G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
    + /**
    + * TraversityDiscoverer:public-ipv6:
    + *
    + * The public IPv6 address if found or %NULL.
    + *
    + * Since: 1.0.0
    + */
    properties[PROP_PUBLIC_IPV6] = g_param_spec_object(
    "public-ipv6", "public-ipv6",
    "The discovered public ipv6 address",
    --- a/traversity/traversitydiscoverer.h Tue Oct 04 03:24:40 2022 -0500
    +++ b/traversity/traversitydiscoverer.h Wed Oct 05 00:53:02 2022 -0500
    @@ -12,6 +12,15 @@
    G_BEGIN_DECLS
    +/**
    + * TraversityDiscoverer:
    + *
    + * A discoverer is an abstract class that defines the interface for discovering
    + * external IP addresses and gateway devices.
    + *
    + * Since: 1.0.0
    + */
    +
    #define TRAVERSITY_TYPE_DISCOVERER (traversity_discoverer_get_type())
    G_DECLARE_DERIVABLE_TYPE(TraversityDiscoverer, traversity_discoverer,
    TRAVERSITY, DISCOVERER, GObject)
    @@ -27,19 +36,156 @@
    gpointer reserved[8];
    };
    +/**
    + * traversity_discoverer_discover_async:
    + * @discoverer: The instance.
    + * @cancellable: (nullable): A [class@Gio.Cancellable] or %NULL.
    + * @callback: The callback to call when discovery is done.
    + * @data: User data to pass to @callback.
    + *
    + * Starts the discovery process asynchronously. When the process has been
    + * completed, @callback will be called with @data and you should call
    + * [method@Traversity.Discoverer.discover_finish] to get the results of the
    + * discovery.
    + *
    + * Since: 1.0.0
    + */
    void traversity_discoverer_discover_async(TraversityDiscoverer *discoverer, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer data);
    +
    +/**
    + * traversity_discoverer_discover_finish:
    + * @discoverer: The instance.
    + * @result: The [iface@Gio.AsyncResult] that was passed to your callback.
    + * @error: (out) (nullable): A return address for a [struct@Glib.Error].
    + *
    + * Retrieves the results from a previous call to
    + * [method@Traversity.Discoverer.discover_async] which should only be called in
    + * the callback function from the previous call.
    + *
    + * If a new address has been discovered, this will return %TRUE, otherwise
    + * %FALSE will be returned.
    + *
    + * Use [method@Traversity.Discoverer.get_local_ipv4],
    + * [method@Traversity.Discoverer.get_local_ipv6],
    + * [method@Traversity.Discoverer.get_public_ipv4], and
    + * [method@Traversity.Discoverer.get_public_ipv6] to get the new IP addresses.
    + *
    + * Returns: %TRUE if something new was discovered, otherwise %FALSE.
    + *
    + * Since: 1.0.0
    + */
    gboolean traversity_discoverer_discover_finish(TraversityDiscoverer *discoverer, GAsyncResult *result, GError **error);
    +/**
    + * traversity_discoverer_get_local_ipv4:
    + * @discoverer: The instance.
    + *
    + * Gets the IPv4 address that @discoverer found. That is, the local LAN IP
    + * address that @discoverer found.
    + *
    + * This will be %NULL if @discoverer hasn't determined it yet.
    + *
    + * Returns: (transfer none) (nullable): The discovered IPv4 address or %NULL.
    + *
    + * Since: 1.0.0
    + */
    GInetAddress *traversity_discoverer_get_local_ipv4(TraversityDiscoverer *discoverer);
    +
    +/**
    + * traversity_discoverer_set_local_ipv4:
    + * @discoverer: The instance.
    + * @address: (transfer none): The new IPv4 address.
    + *
    + * Sets the new IPv4 address for @discoverer.
    + *
    + * Note: This should only be called by subclasses.
    + *
    + * Since: 1.0.0
    + */
    void traversity_discoverer_set_local_ipv4(TraversityDiscoverer *discoverer, GInetAddress *local_ipv4);
    +/**
    + * traversity_discoverer_get_local_ipv6:
    + * @discoverer: The instance.
    + *
    + * Gets the local IPv6 address that @discoverer found. That is, the link-local
    + * IPv6 address that may or may not be routeable.
    + *
    + * This will be %NULL if @discoverer hasn't determined it yet.
    + *
    + * Returns: (transfer none) (nullable): The discovered IPv6 address or %NULL.
    + *
    + * Since: 1.0.0
    + */
    GInetAddress *traversity_discoverer_get_local_ipv6(TraversityDiscoverer *discoverer);
    +
    +/**
    + * traversity_discoverer_set_local_ipv6:
    + * @discoverer: The instance.
    + * @address: (transfer none): The new IPv6 address.
    + *
    + * Sets the new IPv6 address for @discoverer.
    + *
    + * Note: This should only be called by subclasses.
    + *
    + * Since: 1.0.0
    + */
    void traversity_discoverer_set_local_ipv6(TraversityDiscoverer *discoverer, GInetAddress *local_ipv6);
    +/**
    + * traversity_discoverer_get_public_ipv4:
    + * @discoverer: The instance.
    + *
    + * Gets the public IPv4 address that @discoverer found. That is the IPv4
    + * address on the public internet.
    + *
    + * This will be %NULL if @discoverer hasn't determined it yet.
    + *
    + * Returns: (transfer none) (nullable): The discovered IPv4 address or %NULL.
    + *
    + * Since: 1.0.0
    + */
    GInetAddress *traversity_discoverer_get_public_ipv4(TraversityDiscoverer *discoverer);
    +
    +/**
    + * traversity_discoverer_set_public_ipv4:
    + * @discoverer: The instance.
    + * @address: (transfer none): The new IPv4 address.
    + *
    + * Sets the new IPv4 address for @discoverer.
    + *
    + * Note: This should only be called by subclasses.
    + *
    + * Since: 1.0.0
    + */
    void traversity_discoverer_set_public_ipv4(TraversityDiscoverer *discoverer, GInetAddress *public_ipv4);
    +/**
    + * traversity_discoverer_get_public_ipv6:
    + * @discoverer: The instance.
    + *
    + * Gets the public IPv6 address that @discoverer found. That is the IPv6
    + * address on the public internet.
    + *
    + * This will be %NULL if @discoverer hasn't determined it yet.
    + *
    + * Returns: (transfer none) (nullable): The discovered IPv6 address or %NULL.
    + *
    + * Since: 1.0.0
    + */
    GInetAddress *traversity_discoverer_get_public_ipv6(TraversityDiscoverer *discoverer);
    +
    +/**
    + * traversity_discoverer_set_public_ipv6:
    + * @discoverer: The instance.
    + * @address: (transfer none): The new IPv6 address.
    + *
    + * Sets the new IPv6 address for @discoverer.
    + *
    + * Note: This should only be called by subclasses.
    + *
    + * Since: 1.0.0
    + */
    void traversity_discoverer_set_public_ipv6(TraversityDiscoverer *discoverer, GInetAddress *public_ipv6);
    G_END_DECLS