![]() |
![]() |
![]() |
Easy Publish and Consume Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Signals |
#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);
"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
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); ... }
#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.
typedef struct _EpcConsumerPrivate EpcConsumerPrivate;
Private fields of the EpcConsumer class.
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.
|
virtual method of the "authenticate" signal |
|
virtual method of the "publisher-resolved" signal |
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.
|
the publisher's service description |
Returns : |
The newly created EpcConsumer object |
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.
|
the service name of an EpcPublisher |
Returns : |
The newly created EpcConsumer object |
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()
.
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()
.
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
.
|
the service name of an EpcPublisher |
|
the publisher's program name |
|
the DNS domain of the EpcPublisher |
Returns : |
The newly created EpcConsumer object |
EpcProtocol epc_consumer_get_protocol (EpcConsumer *consumer);
Queries the transport protocol to use for contacting the publisher. See "protocol" for details.
|
a EpcConsumer |
Returns : |
The transport protocol this consumer uses. |
const gchar* epc_consumer_get_password (EpcConsumer *consumer);
Queries the password used for authentication. See "password" for details.
|
a EpcConsumer |
Returns : |
The password this consumer uses. |
const gchar* epc_consumer_get_username (EpcConsumer *consumer);
Queries the user name used for authentication. See "username" for details.
|
a EpcConsumer |
Returns : |
The user name this consumer uses. |
void epc_consumer_set_protocol (EpcConsumer *consumer, EpcProtocol protocol);
Changes the transport protocol to use for contacting the publisher. See "protocol" for details.
|
a EpcConsumer |
|
the new transport protocol |
void epc_consumer_set_password (EpcConsumer *consumer, const gchar *password);
Changes the password used for authentication. See "password" for details.
|
a EpcConsumer |
|
the new password, or NULL
|
void epc_consumer_set_username (EpcConsumer *consumer, const gchar *username);
Changes the user name used for authentication. See "username" for details.
|
a EpcConsumer |
|
the new user name, or NULL
|
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"
|
a EpcConsumer |
|
the amount of milliseconds to wait |
Returns : |
TRUE when a publisher has been found, FALSE otherwise.
|
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"
|
a EpcConsumer |
Returns : |
TRUE when the host name has been resolved, and FALSE otherwise.
|
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.
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.
|
a EpcConsumer |
|
a glob-style pattern, or NULL
|
|
return location for a GError, or NULL
|
Returns : |
A newly allocated list of keys, or NULL when an error occurred.
|
"application"
property"application" gchar* : Read / Write / Construct Only
Program name the publisher to use.
Default value: NULL
"domain"
property"domain" gchar* : Read / Write / Construct Only
DNS domain of the publisher to use.
Default value: NULL
"hostname"
property"hostname" gchar* : Read / Write / Construct Only
Host name of the publisher to use.
Default value: NULL
"name"
property"name" gchar* : Read / Write / Construct Only
Service name of the publisher to use.
Default value: NULL
"password"
property"password" gchar* : Read / Write / Construct
The password to use for authentication.
Default value: NULL
"path"
property"path" gchar* : Read / Write / Construct Only
The path the publisher uses for contents.
Default value: "/contents"
"port"
property"port" gint : Read / Write / Construct Only
TCP/IP port of the publisher to use.
Allowed values: [0,65535]
Default value: 0
"protocol"
property"protocol" EpcProtocol : Read / Write / Construct
The transport protocol to use for contacting the publisher.
Default value: EPC_PROTOCOL_UNKNOWN
"authenticate"
signalgboolean 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.
|
the EpcConsumer emitting the signal |
|
the realm being authenticated to |
|
user data set when the signal handler was connected. |
Returns : |
TRUE when the signal handler handled the authentication request,
and FALSE otherwise.
|
"publisher-resolved"
signalvoid 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
|
the EpcConsumer emitting the signal |
|
the publisher's transport protocol |
|
the publisher's host name |
|
the publisher's TCP/IP port |
|
user data set when the signal handler was connected. |