EpcPublisher: Easy Publish and Consume Reference Manual

EpcPublisher

EpcPublisher — easily publish values

Stability Level

Unstable, unless otherwise indicated

Functions

EpcContents *	(*EpcContentsHandler) ()
EpcPublisher *	epc_publisher_new ()
void	epc_publisher_add ()
void	epc_publisher_add_file ()
void	epc_publisher_add_handler ()
void	epc_publisher_add_bookmark ()
gchar *	epc_publisher_get_path ()
gchar *	epc_publisher_get_uri ()
gboolean	epc_publisher_has_key ()
gpointer	epc_publisher_lookup ()
gboolean	epc_publisher_remove ()
GList *	epc_publisher_list ()
gboolean	epc_publisher_run ()
gboolean	epc_publisher_run_async ()
gboolean	epc_publisher_quit ()
gchar *	epc_publisher_expand_name ()
void	epc_publisher_set_auth_flags ()
void	epc_publisher_set_auth_handler ()
void	epc_publisher_set_collision_handling ()
void	epc_publisher_set_contents_path ()
void	epc_publisher_set_credentials ()
void	epc_publisher_set_protocol ()
void	epc_publisher_set_service_cookie ()
void	epc_publisher_set_service_name ()
EpcAuthFlags	epc_publisher_get_auth_flags ()
const gchar *	epc_publisher_get_certificate_file ()
EpcCollisionHandling	epc_publisher_get_collision_handling ()
const gchar *	epc_publisher_get_contents_path ()
const gchar *	epc_publisher_get_private_key_file ()
EpcProtocol	epc_publisher_get_protocol ()
const gchar *	epc_publisher_get_service_cookie ()
const gchar *	epc_publisher_get_service_domain ()
const gchar *	epc_publisher_get_service_name ()

Properties

gchar *	application	Read / Write / Construct
EpcAuthFlags	auth-flags	Read / Write / Construct
gchar *	certificate-file	Read / Write / Construct
EpcCollisionHandling	collision-handling	Read / Write / Construct
gchar *	contents-path	Read / Write / Construct
gchar *	private-key-file	Read / Write / Construct
EpcProtocol	protocol	Read / Write / Construct
gchar *	service-cookie	Read / Write / Construct
gchar *	service-domain	Read / Write / Construct
gchar *	service-name	Read / Write / Construct

Types and Values

	EpcPublisherPrivate
struct	EpcPublisherClass
struct	EpcPublisher

Object Hierarchy

    GObject
    ╰── EpcPublisher

Includes

#include <libepc/publish.h>

Description

The EpcPublisher starts a HTTP server to publish information. To allow EpcConsumer to find the publisher it automatically publishes its contact information (host name, TCP/IP port) per DNS-SD.

In future it might use DNS-DS to notify EpcConsumer of changes.

Example 6. Publish a value

publisher = epc_publisher_new ("Easy Publisher Example", NULL, NULL);

epc_publisher_add (publisher, "maman", "bar", -1);
epc_publisher_add_file (publisher, "source-code", __FILE__);

epc_publisher_run (NULL);

EpcPublisher doesn't provide a way to explicitly publish NULL values, as publishing NULL values doesn't seem very valueable in our scenario: Usually you want to "publish" NULL values to express, that your application doesn't have any meaningful information for the requested identifier. By "publishing" a NULL value essentially you say "this information does not exist". So publishing NULL values is not different from not publishing any value at all or rejected access to some values. Without explicitly inspecting the details for not receiving a value, a consumer calling epc_consumer_lookup() has no chance to distinguish between the cases "never published", "network problem", "authorization rejected", "no meaningful value available".

So if feel like publishing a NULL value, just remove the key in question from the EpcPublisher by calling epc_publisher_remove(). When using a custom EpcContentsHandler an alternate approach is returning NULL from that handler. In that case the EpcPublisher will behave exactly the same, as if the value has been removed.

Functions

EpcContentsHandler ()

EpcContents *
(*EpcContentsHandler) (EpcPublisher *publisher,
                       const gchar *key,
                       gpointer user_data);

This callback is used to generate custom contents published with the epc_publisher_add_handler function. The arguments passed are the same as passed to epc_publisher_add_handler. The EpcPublisher will decrease the reference count of the returned buffer after deliving it. It's valid to return NULL in situations were no contents can be generated.

Parameters

publisher	the EpcPublisher
key	the unique key
user_data	user data set when the signal handler was installed

Returns

The EpcContents buffer for this publication, or NULL.

epc_publisher_new ()

EpcPublisher *
epc_publisher_new (const gchar *name,
                   const gchar *application,
                   const gchar *domain);

Creates a new EpcPublisher object. The publisher announces its service per DNS-SD to the DNS domain specified by domain , using name as service name. The service type is derived from application . When NULL is passed for application the value returned by g_get_prgname() is used. See epc_service_type_new() for details.

Parameters

name	the human friendly service name, or `NULL`
application	application name used for DNS-SD service type, or `NULL`
domain	the DNS domain for announcing the service, or `NULL`

Returns

The newly created EpcPublisher object.

epc_publisher_add ()

void
epc_publisher_add (EpcPublisher *publisher,
                   const gchar *key,
                   gconstpointer data,
                   gssize length);

Publishes a new value on the EpcPublisher using the unique key for addressing. When -1 is passed for length , data is expected to be a null-terminated string and its length in bytes is determined automatically using strlen.

Values published by the EpcPublisher can be arbitrary data, possibly including null characters in the middle. The kind of data associated with a key is chosen by the application providing values and should be specified separately. However, when publishing plain text it is strongly recommended to use UTF-8 encoding to avoid internationalization issues.

Parameters

publisher	a EpcPublisher
key	the key for addressing the value
data	the value to publish
length	the length of `data` in bytes, or -1 if `data` is a null-terminated string.

epc_publisher_add_file ()

void
epc_publisher_add_file (EpcPublisher *publisher,
                        const gchar *key,
                        const gchar *filename);

Publishes a local file on the EpcPublisher using the unique key for addressing. The publisher delivers the current contents of the file at the time of access.

Parameters

publisher	a EpcPublisher
key	the key for addressing the file
filename	the name of the file to publish

epc_publisher_add_handler ()

void
epc_publisher_add_handler (EpcPublisher *publisher,
                           const gchar *key,
                           EpcContentsHandler handler,
                           gpointer user_data,
                           GDestroyNotify destroy_data);

Publishes contents on the EpcPublisher which are generated by a custom EpcContentsHandler callback. This is the most flexible method for publishing information.

The handler is called on every request matching key . When called, publisher , key and user_data are passed to the handler . When replacing or deleting the resource referenced by key , or when the the Publisher is destroyed, the function described by destroy_data is called with user_data as argument.

Parameters

publisher	a EpcPublisher
key	the key for addressing the contents
handler	the EpcContentsHandler for handling this contents
user_data	data to pass on `handler` calls
destroy_data	a function for releasing `user_data`

epc_publisher_add_bookmark ()

void
epc_publisher_add_bookmark (EpcPublisher *publisher,
                            const gchar *key,
                            const gchar *label);

Installs a dynamic HTTP (respectively HTTPS) bookmark for key . This allows consumption of EpcPublisher resources by foreign applications that support ZeroConf bookmarks, but not libepc. This is useful for instance for publishing media playlists.

Passing NULL as key installs a bookmark for the root context of the builtin web server. When passing NULL as label the publisher's name is used as bookmark label.

Dynamic bookmarks must be unique within the service domain. Therefore the label will get modified on name collisions.

This should be called after adding the resource identified by key, not before. For instance, after calling epc_publisher_add().

Parameters

publisher	a EpcResource
key	the key of the resource to publish, or `NULL`
label	the bookmark's label, or `NULL`

epc_publisher_get_path ()

gchar *
epc_publisher_get_path (EpcPublisher *publisher,
                        const gchar *key);

Queries the path component of the URI used to publish the resource associated with key . This is useful when referencing keys in published resources. Passing NULL as key retrieve the path of the root context.

Parameters

publisher	a EpcPublisher
key	the resource key to inspect, or `NULL`.

Returns

The resource path for key .

epc_publisher_get_uri ()

gchar *
epc_publisher_get_uri (EpcPublisher *publisher,
                       const gchar *key,
                       GError **error);

Queries the URI used to publish the resource associated with key . This is useful when referencing keys in published resources. When passing NULL the publisher's base URI is returned.

The function fails if the publisher's host name cannot be retrieved. In that case NULL is returned and error is set. The error domain is EPC_AVAHI_ERROR. Possible error codes are those of the

Avahi library.

Parameters

publisher	a EpcPublisher
key	the resource key to inspect, or `NULL`
error	return location for a GError, or `NULL`

Returns

The fully qualified URI for key , or NULL on error.

epc_publisher_has_key ()

gboolean
epc_publisher_has_key (EpcPublisher *publisher,
                       const gchar *key);

Checks if information is published for key .

This function allows to use the publisher as local key/value store, which is useful for instance to prevent accidental key collisions.

Parameters

publisher	a EcpPublisher
key	the key for addressing contents

Returns

TRUE when the publisher has information for key , and FALSE otherwise.

epc_publisher_lookup ()

gpointer
epc_publisher_lookup (EpcPublisher *publisher,
                      const gchar *key);

Looks up the user_data passed to epc_publisher_add_handler() for key . Returns NULL if the specified key doesn't exist or wasn't published with epc_publisher_add_handler().

This function allows to use the publisher as local key/value store, which is useful for instance to prevent accidental key collisions.

Parameters

publisher	a EcpPublisher
key	the key for addressing contents

Returns

The user_data associated with key , or NULL.

epc_publisher_remove ()

gboolean
epc_publisher_remove (EpcPublisher *publisher,
                      const gchar *key);

Removes a key and its associated contents from a EpcPublisher.

Parameters

publisher	a EpcPublisher
key	the key for addressing the contents

Returns

TRUE if the key was found and removed from the EpcPublisher.

epc_publisher_list ()

GList *
epc_publisher_list (EpcPublisher *publisher,
                    const gchar *pattern);

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 for generating dynamic resource listings in other formats than libepc's specific format. 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.

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_consumer_list() for builtin listing capabilities.

Parameters

publisher	a EpcPublisher
pattern	a glob-style pattern, or `NULL`

Returns

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

epc_publisher_run ()

gboolean
epc_publisher_run (EpcPublisher *publisher,
                   GError **error);

Starts the server component of the EpcPublisher and blocks until it is shutdown using epc_publisher_quit(). If the server could not be started, the function returns FALSE and sets error . The error domain is EPC_AVAHI_ERROR. Possible error codes are those of the

Avahi library.

When starting the publisher in HTTPS mode for the first time self-signed keys must be generated. Generating secure keys needs some time, so it is recommended to call epc_progress_window_install(), or epc_shell_set_progress_hooks() to provide visual feedback during that operation. Key generation takes place in a separate background thread and the calling thread waits in a GMainLoop. Therefore the UI can remain responsive when generating keys.

To start the server without blocking call epc_publisher_run_async().

Parameters

publisher	a EpcPublisher
error	return location for a GError, or `NULL`

Returns

TRUE when the publisher was successfully started, FALSE if an error occurred.

epc_publisher_run_async ()

gboolean
epc_publisher_run_async (EpcPublisher *publisher,
                         GError **error);

Starts the server component of the EpcPublisher without blocking. If the server could not be started then the function returns FALSE and sets error . The error domain is EPC_AVAHI_ERROR. Possible error codes are those of the

Avahi library.

To stop the server component call epc_publisher_quit(). See epc_publisher_run() for additional information.

Parameters

publisher	a EpcPublisher
error	return location for a GError, or `NULL`

Returns

TRUE when the publisher was successfully started, FALSE if an error occurred.

epc_publisher_quit ()

gboolean
epc_publisher_quit (EpcPublisher *publisher);

Stops the server component of the EpcPublisher started with epc_publisher_run() or epc_publisher_run_async. The functions returns TRUE when the built-in server was running and had to be stopped. If the server wasn't running the function returns FALSE.

Parameters

publisher

a EpcPublisher

Returns

TRUE when the server had to be stopped, and FALSE otherwise.

epc_publisher_expand_name ()

gchar *
epc_publisher_expand_name (const gchar *name,
                           GError **error);

Expands all known placeholders in name . Supported placeholders are:

%a: the program name as returned by g_get_application_name()
%h: the machine's host name in title case
%u: the user's login name in title case
%U: the user's real name
%%: the percent sign

The function fails when the host name cannot looked up. In that case NULL is returned and error is set. The error domain is EPC_AVAHI_ERROR. Possible error codes are those of the Avahi library.

Parameters

name	a service name with placeholders
error	return location for a GError, or `NULL`

Returns

The name with all known placeholders expanded, or NULL on error.

epc_publisher_set_auth_flags ()

void
epc_publisher_set_auth_flags (EpcPublisher *publisher,
                              EpcAuthFlags flags);

Changes the authentication settings the publisher uses when epc_publisher_set_auth_handler() is used. See “auth-flags” for details.

Parameters

publisher	a EpcPublisher
flags	new authentication settings

epc_publisher_set_auth_handler ()

void
epc_publisher_set_auth_handler (EpcPublisher *publisher,
                                const gchar *key,
                                EpcAuthHandler handler,
                                gpointer user_data,
                                GDestroyNotify destroy_data);

Installs an authentication handler for the specified key . Passing NULL as key installs a fallback handler for all resources.

The handler is called on every request matching key . On this call a temporary EpcAuthContext and user_data are passed to the handler . The EpcAuthContext references the publisher and key passed here. When replacing or deleting the resource referenced by key , or when the publisher is destroyed, the function described by destroy_data is called with user_data as argument.

This should be called after adding the resource identified by key, not before. For instance, after calling epc_publisher_add().

Parameters

publisher	a EpcPublisher
key	the key of the resource to protect, or `NULL`
handler	the EpcAuthHandler to connect
user_data	data to pass on `handler` calls
destroy_data	a function for releasing `user_data`

epc_publisher_set_collision_handling ()

void
epc_publisher_set_collision_handling (EpcPublisher *publisher,
                                      EpcCollisionHandling method);

Changes the collision handling strategy the publisher uses. See “collision-handling” for details.

Parameters

publisher	a EpcPublisher
method	the new strategy

Since: 0.3.1

epc_publisher_set_contents_path ()

void
epc_publisher_set_contents_path (EpcPublisher *publisher,
                                 const gchar *path);

Changes the server path used for publishing contents. See “contents-path” for details.

Parameters

publisher	a EpcPublisher
path	the new contents path

epc_publisher_set_credentials ()

void
epc_publisher_set_credentials (EpcPublisher *publisher,
                               const gchar *certfile,
                               const gchar *keyfile);

Changes the file names of the PEM encoded TLS credentials the publisher use for its services, when the transport “protocol” is EPC_PROTOCOL_HTTPS.

See “certificate-file” and “private-key-file” for details.

Parameters

publisher	a EpcPublisher
certfile	file name of the server certificate
keyfile	file name of the private key

epc_publisher_set_protocol ()

void
epc_publisher_set_protocol (EpcPublisher *publisher,
                            EpcProtocol protocol);

Changes the transport protocol the publisher uses. See “protocol” for details.

Parameters

publisher	a EpcPublisher
protocol	the transport protocol

epc_publisher_set_service_cookie ()

void
epc_publisher_set_service_cookie (EpcPublisher *publisher,
                                  const gchar *cookie);

Changes the unique identifier of the service. See “service-cookie” for details.

Parameters

publisher	a EpcPublisher
cookie	the new service identifier, or `NULL`

Since: 0.3.1

epc_publisher_set_service_name ()

void
epc_publisher_set_service_name (EpcPublisher *publisher,
                                const gchar *name);

Changes the human friendly name this EpcPublisher uses to announce its service. See “service-name” for details.

Parameters

publisher	a EpcPublisher
name	the new name of this EpcPublisher

epc_publisher_get_auth_flags ()

EpcAuthFlags
epc_publisher_get_auth_flags (EpcPublisher *publisher);

Queries the current authentication settings of the publisher. See “auth-flags” for details.

Parameters

publisher

a EpcPublisher

Returns

The authentication settings of the publisher, or EPC_AUTH_DEFAULT on error.

epc_publisher_get_certificate_file ()

const gchar *
epc_publisher_get_certificate_file (EpcPublisher *publisher);

Queries the file name of the PEM encoded server certificate. See “certificate-file” for details.

Parameters

publisher

a EpcPublisher

Returns

The certificate's file name, or NULL.

epc_publisher_get_collision_handling ()

EpcCollisionHandling
epc_publisher_get_collision_handling (EpcPublisher *publisher);

Queries the collision handling strategy the publisher uses. See “collision-handling” for details.

Parameters

publisher

a EpcPublisher

Returns

The publisher's collision handling strategy, or EPC_COLLISIONS_IGNORE on error.

Since: 0.3.1

epc_publisher_get_contents_path ()

const gchar *
epc_publisher_get_contents_path (EpcPublisher *publisher);

Queries the server path used for publishing contents. See “contents-path” for details.

Parameters

publisher

a EpcPublisher

Returns

The server's contents path.

epc_publisher_get_private_key_file ()

const gchar *
epc_publisher_get_private_key_file (EpcPublisher *publisher);

Queries the file name of the PEM encoded private server key. See “private-key-file” for details.

Parameters

publisher

a EpcPublisher

Returns

The private key's file name, or NULL.

epc_publisher_get_protocol ()

EpcProtocol
epc_publisher_get_protocol (EpcPublisher *publisher);

Queries the transport protocol the publisher uses. See “protocol” for details.

Parameters

publisher

a EpcPublisher

Returns

The transport protocol the publisher uses, or EPC_PROTOCOL_UNKNOWN on error.

epc_publisher_get_service_cookie ()

const gchar *
epc_publisher_get_service_cookie (EpcPublisher *publisher);

Queries the unique identifier of the service. See “service-cookie” for details.

Parameters

publisher

a EpcPublisher

Returns

The unique identifier of the service, or NULL on error.

Since: 0.3.1

epc_publisher_get_service_domain ()

const gchar *
epc_publisher_get_service_domain (EpcPublisher *publisher);

Queries the DNS domain for which this EpcPublisher announces its service. See “domain” for details.

Parameters

publisher

a EpcPublisher

Returns

The DNS-SD domain of this EpcPublisher, or NULL.

epc_publisher_get_service_name ()

const gchar *
epc_publisher_get_service_name (EpcPublisher *publisher);

Queries the human friendly name this EpcPublisher uses to announce its service. See “name” for details.

Parameters

publisher

a EpcPublisher

Returns

The human friendly name of this EpcPublisher.

Types and Values

EpcPublisherPrivate

typedef struct _EpcPublisherPrivate EpcPublisherPrivate;

Private fields of the EpcPublisher class.

struct EpcPublisherClass

struct EpcPublisherClass {
};

Virtual methods of the EpcPublisher class.

struct EpcPublisher

struct EpcPublisher;

Public fields of the EpcPublisher class.