## InfDiscovery

InfDiscovery — Discovery of remote services

## Stability Level

Unstable, unless otherwise indicated

## Functions

void | ( *InfDiscoveryResolvCompleteFunc ) ()
void | inf_discovery_discover ()
GSList * | inf_discovery_get_discovered ()
void | inf_discovery_resolve ()
gchar * | inf_discovery_info_get_service_name ()
const gchar * | inf_discovery_info_get_service_type ()
void | inf_discovery_discovered ()
void | inf_discovery_undiscovered ()

## Signals

void | discovered | Has Details
void | undiscovered | Has Details

## Types and Values

| InfDiscovery
struct | InfDiscoveryInterface
| InfDiscoveryInfo

## Object Hierarchy

        GInterface
        ╰── InfDiscovery

## Prerequisites

InfDiscovery requires GObject.

## Known Implementations

InfDiscovery is implemented by InfDiscoveryAvahi.

## Includes

    #include <libinfinity/common/inf-discovery.h>

## Description

InfDiscovery provides a common interface for the discovery of services. Discovered services are represented by InfDiscoveryInfo objects and can be used to query the name of the discovered service.

To create a connection to the host providing a discovered service, use `inf_discovery_resolve()`.

## Functions

### InfDiscoveryResolvCompleteFunc ()

    void
    (*InfDiscoveryResolvCompleteFunc) (InfDiscoveryInfo *info,
                                       InfXmlConnection *connection,
                                       const GError *error,
                                       gpointer user_data);

This callback is called when a call to `inf_discovery_resolve()` finished.

#### Parameters

info | The resolved InfDiscoveryInfo. |
connection | The resulting InfXmlConnection. |
error | Reason in case of failure. |
user_data | The user_data passed to `inf_discovery_resolve()`. |

### inf_discovery_discover ()

    void
    inf_discovery_discover (InfDiscovery *discovery,
                            const gchar *type);

Starts the discovery of the given service type. Whenever a service of this type is discovered, the "discovered" signal is emitted. If the service disappears, the "undiscovered" signal is emitted. This can be called more than once for the same type, but only the first call has an effect.

Note also that implementations of InfDiscovery might restrict the service types that can be discovered.

#### Parameters

discovery | A InfDiscovery. |
type | The service type to discover. |

### inf_discovery_get_discovered ()

    GSList *
    inf_discovery_get_discovered (InfDiscovery *discovery,
                                  const gchar *type);

Returns a list of discovered InfDiscoveryInfo for the given type.

#### Parameters

discovery | A InfDiscovery. |
type | The service type of which to get discovered infos for. |

#### Returns

A newly allocated list that needs to be freed with `g_slist_free()`.

[transfer container][element-type InfDiscoveryInfo]

### inf_discovery_resolve ()

    void
    inf_discovery_resolve (InfDiscovery *discovery,
                           InfDiscoveryInfo *info,
                           InfDiscoveryResolvCompleteFunc complete_func,
                           gpointer user_data);

Attempts to resolve `info` . Resolving a InfDiscoveryInfo means creating a InfXmlConnection to the publisher. The connection might not be open when `complete_func` runs.

#### Parameters

discovery | A InfDiscovery. |
info | A InfDiscoveryInfo discovered by `discovery` . |
complete_func | A callback that will be called when the resolving process has completed. | [scope async]
user_data | Extra data to pass to `complete_func` and `error_func` . |

### inf_discovery_info_get_service_name ()

    gchar *
    inf_discovery_info_get_service_name (InfDiscovery *discovery,
                                         InfDiscoveryInfo *info);

Returns the service name of the discovered `info` .

#### Parameters

discovery | A InfDiscovery. |
info | A InfDiscoveryInfo discovered by `discovery` . |

#### Returns

A newly allocated string. Free with `g_free()`.

[transfer full]

### inf_discovery_info_get_service_type ()

    const gchar *
    inf_discovery_info_get_service_type (InfDiscovery *discovery,
                                         InfDiscoveryInfo *info);

Returns the service type of the discovered `info` .

#### Parameters

discovery | A InfDiscovery. |
info | A InfDiscoveryInfo discovered by `discovery` . |

#### Returns

A string owned by `discovery` .

[transfer none]

### inf_discovery_discovered ()

    void
    inf_discovery_discovered (InfDiscovery *discovery,
                              InfDiscoveryInfo *info);

Emits the "discovered" signal on `discovery` .

#### Parameters

discovery | A InfDiscovery. |
info | The discovered InfDiscoveryInfo. |

### inf_discovery_undiscovered ()

    void
    inf_discovery_undiscovered (InfDiscovery *discovery,
                                InfDiscoveryInfo *info);

Emits the "undiscovered" signal on `discovery` .

#### Parameters

discovery | A InfDiscovery. |
info | The undiscovered `InfDiscoveryInfo` . |

## Types and Values

### InfDiscovery

    typedef struct _InfDiscovery InfDiscovery;

InfDiscovery is an opaque data type. You should only access it via the public API functions.

### struct InfDiscoveryInterface

    struct InfDiscoveryInterface {
      void (*discover)(InfDiscovery* discovery,
                       const gchar* type);

      GSList* (*get_discovered)(InfDiscovery* discovery,
                                const gchar* type);

      void (*resolve)(InfDiscovery* discovery,
                      InfDiscoveryInfo* info,
                      InfDiscoveryResolvCompleteFunc complete_func,
                      gpointer user_data);

      gchar*(*info_get_service_name)(InfDiscovery* discovery,
                                     InfDiscoveryInfo* info);

      const gchar*(*info_get_service_type)(InfDiscovery* discovery,
                                           InfDiscoveryInfo* info);

      /* Signals */
      void (*discovered)(InfDiscovery* discovery,
                         InfDiscoveryInfo* info);

      void (*undiscovered)(InfDiscovery* discovery,
                           InfDiscoveryInfo* info);
    };

The virtual methods and default signal handlers of InfDiscovery. Implementing these allows discovering infinote servers.

#### Members

`discover` () | Virtual function to start discovery of services of the given type. If the discovery was already started ealier, then this function does nothing. |
`get_discovered` () | Virtual function to retrieve a list of InfDiscoveryInfos that represent discovered services. It needs to be freed by the caller via `g_slist_free()`. |
`resolve` () | Virtual function that attempts to resolve the given discovery info. It guarantees to either call `complete_func` or `error_func` when the process has finished. |
`info_get_service_name` () | Returns the service name of the given InfDiscoveryInfo as a new string, to be freed by the caller with `g_free()`. |
`info_get_service_type` () | Returns the type of the discovered service of the given InfDiscoveryInfo as a static string. |
`discovered` () | Default signal handler for the “discovered” signal. |
`undiscovered` () | Default signal handler for the “undiscovered” signal. |

### InfDiscoveryInfo

    typedef struct _InfDiscoveryInfo InfDiscoveryInfo;

InfDiscoveryInfo is an opaque data type. You should only access it via the public API functions.

## Signal Details

### The `“discovered”` signal

    void
    user_function (InfDiscovery *discoverer,
                   gpointer      info,
                   gpointer      user_data)

This signal is detailed. The detail is the name of the service that has been discovered, so you can connect to "discovered::my-service-name" if you are only interested in a particular service.

#### Parameters

discoverer | The InfDiscovery object discovering something |
info | The InfDiscoveryInfo describing the discovered service |
user_data | user data set when the signal handler was connected. |

Flags: Has Details

### The `“undiscovered”` signal

    void
    user_function (InfDiscovery *discoverer,
                   gpointer      info,
                   gpointer      user_data)

This signal is emitted if a previously discovered service is no longer available.

This signal is detailed. The detail is the name of the service that has been undiscovered, so you can connect to "undiscovered::my-service-name" if you are only interested in a particular service.

#### Parameters

discoverer | The InfDiscovery object undiscovering something |
info | The InfDiscoveryInfo describing the undiscovered service |
user_data | user data set when the signal handler was connected. |

Flags: Has Details

## See Also

InfDiscoveryAvahi