InfDiscovery

InfDiscovery — Discovery of remote services

Synopsis

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

                    InfDiscovery;
struct              InfDiscoveryIface;
                    InfDiscoveryInfo;
void                (*InfDiscoveryResolvCompleteFunc)   (InfDiscoveryInfo *info,
                                                         InfXmlConnection *connection,
                                                         gpointer user_data);
void                (*InfDiscoveryResolvErrorFunc)      (InfDiscoveryInfo *info,
                                                         const GError *error,
                                                         gpointer user_data);
void                inf_discovery_discover              (InfDiscovery *discovery,
                                                         const gchar *type);
GSList *            inf_discovery_get_discovered        (InfDiscovery *discovery,
                                                         const gchar *type);
void                inf_discovery_resolve               (InfDiscovery *discovery,
                                                         InfDiscoveryInfo *info,
                                                         InfDiscoveryResolvCompleteFunc complete_func,
                                                         InfDiscoveryResolvErrorFunc error_func,
                                                         gpointer user_data);
gchar *             inf_discovery_info_get_service_name (InfDiscovery *discovery,
                                                         InfDiscoveryInfo *info);
const gchar *       inf_discovery_info_get_service_type (InfDiscovery *discovery,
                                                         InfDiscoveryInfo *info);
void                inf_discovery_discovered            (InfDiscovery *discovery,
                                                         InfDiscoveryInfo *info);
void                inf_discovery_undiscovered          (InfDiscovery *discovery,
                                                         InfDiscoveryInfo *info);

Object Hierarchy

  GInterface
   +----InfDiscovery

Prerequisites

InfDiscovery requires GObject.

Known Implementations

InfDiscovery is implemented by InfDiscoveryAvahi.

Signals

  "discovered"                                     : Has Details
  "undiscovered"                                   : Has Details

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().

Details

InfDiscovery

typedef struct _InfDiscovery InfDiscovery;

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


struct InfDiscoveryIface

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

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

  void (*resolve)(InfDiscovery* discovery,
                  InfDiscoveryInfo* info,
                  InfDiscoveryResolvCompleteFunc complete_func,
                  InfDiscoveryResolvErrorFunc error_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.

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.


InfDiscoveryResolvCompleteFunc ()

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

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

info :

The resolved InfDiscoveryInfo.

connection :

The resulting InfXmlConnection.

user_data :

The user_data passed to inf_discovery_resolve().

InfDiscoveryResolvErrorFunc ()

void                (*InfDiscoveryResolvErrorFunc)      (InfDiscoveryInfo *info,
                                                         const GError *error,
                                                         gpointer user_data);

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

info :

The resolved InfDiscoveryInfo.

error :

Reason for the 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.

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.

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().

inf_discovery_resolve ()

void                inf_discovery_resolve               (InfDiscovery *discovery,
                                                         InfDiscoveryInfo *info,
                                                         InfDiscoveryResolvCompleteFunc complete_func,
                                                         InfDiscoveryResolvErrorFunc error_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. This will call either complete_func or error_func, but not both.

discovery :

A InfDiscovery.

info :

A InfDiscoveryInfo discovered by discovery.

complete_func :

A callback that will be called when the resolving process has completed.

error_func :

A callback that will be called when an error has occured.

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.

discovery :

A InfDiscovery.

info :

A InfDiscoveryInfo discovered by discovery.

Returns :

A string owned by discovery.

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.

discovery :

A InfDiscovery.

info :

A InfDiscoveryInfo discovered by discovery.

Returns :

A string owned by discovery.

inf_discovery_discovered ()

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

Emits the "discovered" signal on discovery.

discovery :

A InfDiscovery.

info :

The discovered InfDiscoveryInfo.

inf_discovery_undiscovered ()

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

Emits the "undiscovered" signal on discovery.

discovery :

A InfDiscovery.

info :

The undiscovered InfDiscoveryInfo.

Signal Details

The "discovered" signal

void                user_function                      (InfDiscovery *discoverer,
                                                        gpointer      info,
                                                        gpointer      user_data)       : Has Details

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.

discoverer :

The InfDiscovery object discovering something

info :

The InfDiscoveryInfo describing the discovered service

user_data :

user data set when the signal handler was connected.

The "undiscovered" signal

void                user_function                      (InfDiscovery *discoverer,
                                                        gpointer      info,
                                                        gpointer      user_data)       : Has Details

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.

discoverer :

The InfDiscovery object undiscovering something

info :

The InfDiscoveryInfo describing the undiscovered service

user_data :

user data set when the signal handler was connected.

See Also

InfDiscoveryAvahi