InfDiscovery

InfDiscovery — Discovery of remote services

Stability Level

Unstable, unless otherwise indicated

Functions

Signals

void discovered Has Details
void undiscovered Has Details

Types and Values

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