EpcConsumer: Easy Publish and Consume Reference Manual

## EpcConsumer EpcConsumer — lookup published values |

## Stability Level

Unstable, unless otherwise indicated

## Functions

EpcConsumer * | epc_consumer_new ()
EpcConsumer * | epc_consumer_new_for_name ()
EpcConsumer * | epc_consumer_new_for_name_full ()
EpcProtocol | epc_consumer_get_protocol ()
const gchar * | epc_consumer_get_password ()
const gchar * | epc_consumer_get_username ()
void | epc_consumer_set_protocol ()
void | epc_consumer_set_password ()
void | epc_consumer_set_username ()
gboolean | epc_consumer_resolve_publisher ()
gboolean | epc_consumer_is_publisher_resolved ()
gpointer | epc_consumer_lookup ()
GList * | epc_consumer_list ()

## Properties

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

## Signals

gboolean | authenticate | Run Last
void | publisher-resolved | Run First

## Types and Values

#define | EPC_HTTP_ERROR
| EpcConsumerPrivate
struct | EpcConsumerClass
struct | EpcConsumer

## Object Hierarchy

        GObject
        ╰── EpcConsumer

## Includes

    #include <libepc/consumer.h>

## 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

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    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

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    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);
       ...
    }

## Functions

### 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.

#### Parameters

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.

#### Parameters

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

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`.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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”

#### Parameters

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”

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

## Types and Values

### 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.

### struct EpcConsumerClass

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

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

Virtual methods of the EpcConsumer class.

#### Members

`authenticate` () | virtual method of the “authenticate” signal |
`publisher_resolved` () | virtual method of the “publisher-resolved” signal |

### struct EpcConsumer

    struct EpcConsumer;

Public fields of the EpcConsumer class.

## Property Details

### The `“application”` property

      “application”              gchar *

Program name the publisher to use.

Flags: Read / Write / Construct Only

Default value: NULL

### The `“domain”` property

      “domain”                   gchar *

DNS domain of the publisher to use.

Flags: Read / Write / Construct Only

Default value: NULL

### The `“hostname”` property

      “hostname”                 gchar *

Host name of the publisher to use.

Flags: Read / Write / Construct Only

Default value: NULL

### The `“name”` property

      “name”                     gchar *

Service name of the publisher to use.

Flags: Read / Write / Construct Only

Default value: NULL

### The `“password”` property

      “password”                 gchar *

The password to use for authentication.

Flags: Read / Write / Construct

Default value: NULL

### The `“path”` property

      “path”                     gchar *

The path the publisher uses for contents.

Flags: Read / Write / Construct Only

Default value: "/contents"

### The `“port”` property

      “port”                     gint

TCP/IP port of the publisher to use.

Flags: Read / Write / Construct Only

Allowed values: [0,65535]

Default value: 0

### The `“protocol”` property

      “protocol”                 EpcProtocol

The transport protocol to use for contacting the publisher.

Flags: Read / Write / Construct

Default value: EPC_PROTOCOL_UNKNOWN

### The `“username”` property

      “username”                 gchar *

The user name to use for authentication.

Flags: Read / Write / Construct

Default value: NULL

## Signal Details

### The `“authenticate”` signal

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

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.

#### Parameters

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.

Flags: Run Last

### The `“publisher-resolved”` signal

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

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

#### Parameters

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

Flags: Run First

## See Also

EpcPublisher