EpcConsumer

EpcConsumer — lookup published values

Stability Level

Unstable, unless otherwise indicated

Synopsis


#include <libepc/consumer.h>

#define             EPC_HTTP_ERROR
                    EpcConsumerPrivate;
                    EpcConsumerClass;
                    EpcConsumer;

EpcConsumer*        epc_consumer_new                    (const EpcServiceInfo *service);
EpcConsumer*        epc_consumer_new_for_name           (const gchar *name);
EpcConsumer*        epc_consumer_new_for_name_full      (const gchar *name,
                                                         const gchar *application,
                                                         const gchar *domain);

EpcProtocol         epc_consumer_get_protocol           (EpcConsumer *consumer);
const gchar*        epc_consumer_get_password           (EpcConsumer *consumer);
const gchar*        epc_consumer_get_username           (EpcConsumer *consumer);

void                epc_consumer_set_protocol           (EpcConsumer *consumer,
                                                         EpcProtocol protocol);
void                epc_consumer_set_password           (EpcConsumer *consumer,
                                                         const gchar *password);
void                epc_consumer_set_username           (EpcConsumer *consumer,
                                                         const gchar *username);

gboolean            epc_consumer_resolve_publisher      (EpcConsumer *consumer,
                                                         guint timeout);
gboolean            epc_consumer_is_publisher_resolved  (EpcConsumer *consumer);
gpointer            epc_consumer_lookup                 (EpcConsumer *consumer,
                                                         const gchar *key,
                                                         gsize *length,
                                                         GError **error);
GList*              epc_consumer_list                   (EpcConsumer *consumer,
                                                         const gchar *pattern,
                                                         GError **error);

Object Hierarchy

  GObject
   +----EpcConsumer

Properties

  "application"              gchar*                : Read / Write / Construct Only
  "domain"                   gchar*                : Read / Write / Construct Only
  "hostname"                 gchar*                : Read / Write / Construct Only
  "name"                     gchar*                : Read / Write / Construct Only
  "password"                 gchar*                : Read / Write / Construct
  "path"                     gchar*                : Read / Write / Construct Only
  "port"                     gint                  : Read / Write / Construct Only
  "protocol"                 EpcProtocol           : Read / Write / Construct
  "username"                 gchar*                : Read / Write / Construct

Signals

  "authenticate"                                   : Run Last
  "publisher-resolved"                             : Run First

Description

The EpcConsumer object is used to lookup values published by an EpcPublisher service. Currently HTTP is used for communication. To find a publisher, use DNS-SD (also known as ZeroConf) to list EPC_PUBLISHER_SERVICE_TYPE services.

Example 1. Lookup a value

  service_name = choose_recently_used_service ();

  if (service_name)
    consumer = epc_consumer_new_for_name (service_name);
  else
    consumer = epc_consumer_new (your_app_find_service ());

  value = epc_consumer_lookup (consumer, "glom-settings", NULL, &error);
  g_object_unref (consumer);

  your_app_consume_value (value);
  g_free (value);


Example 2. Find a publisher

  dialog = aui_service_dialog_new ("Choose a Service", main_window,
                                   GTK_STOCK_CANCEL, GTK_RESPONSE_CANCEL,
                                   GTK_STOCK_CONNECT, GTK_RESPONSE_ACCEPT,
                                   NULL);

  aui_service_dialog_set_browse_service_types (AUI_SERVICE_DIALOG (dialog),
                                               EPC_SERVICE_TYPE_HTTPS,
                                               EPC_SERVICE_TYPE_HTTP,
                                               NULL);

 aui_service_dialog_set_service_type_name (AUI_SERVICE_DIALOG (dialog),
                                           EPC_SERVICE_TYPE_HTTPS,
                                           "Secure Transport");
 aui_service_dialog_set_service_type_name (AUI_SERVICE_DIALOG (dialog),
                                           EPC_SERVICE_TYPE_HTTP,
                                           "Insecure Transport");

 if (GTK_RESPONSE_ACCEPT == gtk_dialog_run (GTK_DIALOG (dialog)))
  {
     EpcServiceInfo *service =
       epc_service_info_new (aui_service_dialog_get_service_type (AUI_SERVICE_DIALOG (dialog)),
                             aui_service_dialog_get_host_name    (AUI_SERVICE_DIALOG (dialog)),
                             aui_service_dialog_get_port         (AUI_SERVICE_DIALOG (dialog)),
                             aui_service_dialog_get_txt_data     (AUI_SERVICE_DIALOG (dialog)));

     consumer = epc_consumer_new (service);
     epc_service_info_unref (service);
     ...
  }


Details

EPC_HTTP_ERROR

#define EPC_HTTP_ERROR              (epc_http_error_quark())

Error domain for HTTP operations. Errors in this domain will be from the SoupKnownStatusCode enumeration. See GError for information on error domains.

EpcConsumerPrivate

typedef struct _EpcConsumerPrivate EpcConsumerPrivate;

Private fields of the EpcConsumer class.

EpcConsumerClass

typedef struct {
  void (*authenticate)       (EpcConsumer  *consumer,
                              const gchar  *realm);

  void (*publisher_resolved) (EpcConsumer  *consumer,
                              EpcProtocol   protocol,
                              const gchar  *hostname,
                              guint         port);
} EpcConsumerClass;

Virtual methods of the EpcConsumer class.

authenticate ()

 virtual method of the "authenticate" signal

publisher_resolved ()

 virtual method of the "publisher-resolved" signal

EpcConsumer

typedef struct _EpcConsumer EpcConsumer;

Public fields of the EpcConsumer class.

epc_consumer_new ()

EpcConsumer*        epc_consumer_new                    (const EpcServiceInfo *service);

Creates a new EpcConsumer object and associates it with a known EpcPublisher. The service description can be retrieved, for instance, by using EpcServiceMonitor, or by using the service selection dialog of avahi-ui (AuiServiceDialog).

The connection is not established until functions like epc_consumer_lookup(), epc_consumer_list() or epc_consumer_resolve_publisher are called.

service :

 the publisher's service description

Returns :

 The newly created EpcConsumer object

epc_consumer_new_for_name ()

EpcConsumer*        epc_consumer_new_for_name           (const gchar *name);

Creates a new EpcConsumer object and associates it with the EpcPublisher announcing itself with name on the local network. The DNS-SD service name used for searching the EpcPublisher is derived from the application's program name as returned by g_get_prgname().

See epc_consumer_new_for_name_full() for additional notes and a method allowing better control over the search process.

name :

 the service name of an EpcPublisher

Returns :

 The newly created EpcConsumer object

epc_consumer_new_for_name_full ()

EpcConsumer*        epc_consumer_new_for_name_full      (const gchar *name,
                                                         const gchar *application,
                                                         const gchar *domain);

Creates a new EpcConsumer object and associates it with the EpcPublisher announcing itself with name on domain. The DNS-SD service of the EpcPublisher is derived from application using epc_service_type_new().

Note

This function shall be used to re-connect to a formerly used EpcPublisher, selected for instance from a list for recently used services. Therefore using epc_consumer_new_for_name_full() is a quite optimistic approach for contacting a publisher: You call it without really knowing if the publisher you requested really exists. You only know that it existed in the past when you added it to your list of recently used publishers, but you do not know if it still exists.

To let your users choose from an up-to-date service list, you have to use a dynamic service list as provided by avahi-ui for choosing a service and pass the information this widget provides (hostname, port, protocol) to epc_consumer_new().

Note

The connection is not established until a function retrieving data, like for instance epc_consumer_lookup(), is called.

Explicitly call epc_consumer_resolve_publisher() or connect to the "publisher-resolved" signal, when your application needs reliable information about the existance of the EpcPublisher described by name.

name :

 the service name of an EpcPublisher

application :

 the publisher's program name

domain :

 the DNS domain of the EpcPublisher

Returns :

 The newly created EpcConsumer object

epc_consumer_get_protocol ()

EpcProtocol         epc_consumer_get_protocol           (EpcConsumer *consumer);

Queries the transport protocol to use for contacting the publisher. See "protocol" for details.

consumer :

 a EpcConsumer

Returns :

 The transport protocol this consumer uses.

epc_consumer_get_password ()

const gchar*        epc_consumer_get_password           (EpcConsumer *consumer);

Queries the password used for authentication. See "password" for details.

consumer :

 a EpcConsumer

Returns :

 The password this consumer uses.

epc_consumer_get_username ()

const gchar*        epc_consumer_get_username           (EpcConsumer *consumer);

Queries the user name used for authentication. See "username" for details.

consumer :

 a EpcConsumer

Returns :

 The user name this consumer uses.

epc_consumer_set_protocol ()

void                epc_consumer_set_protocol           (EpcConsumer *consumer,
                                                         EpcProtocol protocol);

Changes the transport protocol to use for contacting the publisher. See "protocol" for details.

consumer :

 a EpcConsumer

protocol :

 the new transport protocol

epc_consumer_set_password ()

void                epc_consumer_set_password           (EpcConsumer *consumer,
                                                         const gchar *password);

Changes the password used for authentication. See "password" for details.

consumer :

 a EpcConsumer

password :

 the new password, or NULL

epc_consumer_set_username ()

void                epc_consumer_set_username           (EpcConsumer *consumer,
                                                         const gchar *username);

Changes the user name used for authentication. See "username" for details.

consumer :

 a EpcConsumer

username :

 the new user name, or NULL

epc_consumer_resolve_publisher ()

gboolean            epc_consumer_resolve_publisher      (EpcConsumer *consumer,
                                                         guint timeout);

Waits until the consumer has found its EpcPublisher. A timeout of 0 requests infinite waiting.

See also: "publisher-resolved"

consumer :

 a EpcConsumer

timeout :

 the amount of milliseconds to wait

Returns :

 TRUE when a publisher has been found, FALSE otherwise.

epc_consumer_is_publisher_resolved ()

gboolean            epc_consumer_is_publisher_resolved  (EpcConsumer *consumer);

Checks if the host name of this consumer's EpcPublisher has been resolved already.

See also: epc_consumer_resolve_publisher(), "publisher-resolved"

consumer :

 a EpcConsumer

Returns :

 TRUE when the host name has been resolved, and FALSE otherwise.

epc_consumer_lookup ()

gpointer            epc_consumer_lookup                 (EpcConsumer *consumer,
                                                         const gchar *key,
                                                         gsize *length,
                                                         GError **error);

If the call was successful, this returns a newly allocated buffer containing the value the publisher provides for key. If the call was not successful it returns NULL and sets error. The error domain is EPC_HTTP_ERROR. Error codes are taken from the SoupKnownStatusCode enumeration.

For instance, the error code will be SOUP_STATUS_FORBIDDEN if authentication failed (see epc_publisher_set_auth_handler()). You must include libsoup/soup-status.h to use this error code.

The returned buffer should be freed when no longer needed.

See the description of EpcPublisher for discussion of NULL values.

consumer :

 the consumer

key :

 unique key of the value

length :

 location to store length in bytes of the contents, or NULL

error :

 return location for a GError, or NULL

Returns :

 A copy of the publisher's value for the the requested key, or NULL when an error occurred.

epc_consumer_list ()

GList*              epc_consumer_list                   (EpcConsumer *consumer,
                                                         const gchar *pattern,
                                                         GError **error);

Matches published keys against patterns containing '*' (wildcard) and '?' (joker). Passing NULL as pattern is equivalent to passing "*" and returns all published keys. This function is useful to find and select dynamically published values. See GPatternSpec for information about glob-style patterns.

If the call was successful, a list of keys matching pattern is returned. If the call was not successful, it returns NULL and sets error. The error domain is EPC_HTTP_ERROR. Error codes are taken from the SoupKnownStatusCode enumeration.

The returned list should be freed when no longer needed: 

 g_list_foreach (keys, (GFunc) g_free, NULL);
 g_list_free (keys);

See also epc_publisher_list() for creating custom listings.

consumer :

 a EpcConsumer

pattern :

 a glob-style pattern, or NULL

error :

 return location for a GError, or NULL

Returns :

 A newly allocated list of keys, or NULL when an error occurred.

Property Details

The "application" property

  "application"              gchar*                : Read / Write / Construct Only

Program name the publisher to use.

Default value: NULL

The "domain" property

  "domain"                   gchar*                : Read / Write / Construct Only

DNS domain of the publisher to use.

Default value: NULL

The "hostname" property

  "hostname"                 gchar*                : Read / Write / Construct Only

Host name of the publisher to use.

Default value: NULL

The "name" property

  "name"                     gchar*                : Read / Write / Construct Only

Service name of the publisher to use.

Default value: NULL

The "password" property

  "password"                 gchar*                : Read / Write / Construct

The password to use for authentication.

Default value: NULL

The "path" property

  "path"                     gchar*                : Read / Write / Construct Only

The path the publisher uses for contents.

Default value: "/contents"

The "port" property

  "port"                     gint                  : Read / Write / Construct Only

TCP/IP port of the publisher to use.

Allowed values: [0,65535]

Default value: 0

The "protocol" property

  "protocol"                 EpcProtocol           : Read / Write / Construct

The transport protocol to use for contacting the publisher.

Default value: EPC_PROTOCOL_UNKNOWN

The "username" property

  "username"                 gchar*                : Read / Write / Construct

The user name to use for authentication.

Default value: NULL

Signal Details

The "authenticate" signal

gboolean            user_function                      (EpcConsumer *consumer,
                                                        gchar       *realm,
                                                        gpointer     user_data)      : Run Last

Emitted when the EpcConsumer requires authentication. The signal handler should provide these credentials, which may come from the user or from cached information by setting the "username" and "password" properties. When providing credentials the signal handler should return TRUE to stop signal emission.

If the provided credentials fail then the signal will be emmitted again.

consumer :

 the EpcConsumer emitting the signal

realm :

 the realm being authenticated to

user_data :

 user data set when the signal handler was connected.

Returns :

 TRUE when the signal handler handled the authentication request, and FALSE otherwise.

The "publisher-resolved" signal

void                user_function                      (EpcConsumer *consumer,
                                                        EpcProtocol  protocol,
                                                        gchar       *hostname,
                                                        guint        port,
                                                        gpointer     user_data)      : Run First

This signal is emitted when a EpcConsumer created with epc_consumer_new_for_name() or epc_consumer_new_for_name_full has found its EpcPublisher.

Publisher detection is integrated with the GLib main loop. Therefore the signal will not be emitted before a main loop is run (g_main_loop_run(), gtk_main()). So to reliably consume this signal connect to it directly after creating the EpcConsumer.

See also: epc_consumer_resolve_publisher(), epc_consumer_is_pulisher_resolved

consumer :

 the EpcConsumer emitting the signal

protocol :

 the publisher's transport protocol

hostname :

 the publisher's host name

port :

 the publisher's TCP/IP port

user_data :

 user data set when the signal handler was connected.

See Also

EpcPublisher
Generated by GTK-Doc V1.12