EpcPublisher

EpcPublisher — easily publish values

Stability Level

Unstable, unless otherwise indicated

Synopsis

#include <libepc/publish.h>

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

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

void                epc_publisher_add                   (EpcPublisher *publisher,
                                                         const gchar *key,
                                                         gconstpointer data,
                                                         gssize length);
void                epc_publisher_add_file              (EpcPublisher *publisher,
                                                         const gchar *key,
                                                         const gchar *filename);
void                epc_publisher_add_handler           (EpcPublisher *publisher,
                                                         const gchar *key,
                                                         EpcContentsHandler handler,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy_data);
void                epc_publisher_add_bookmark          (EpcPublisher *publisher,
                                                         const gchar *key,
                                                         const gchar *label);
gchar *             epc_publisher_get_path              (EpcPublisher *publisher,
                                                         const gchar *key);
gchar *             epc_publisher_get_uri               (EpcPublisher *publisher,
                                                         const gchar *key,
                                                         GError **error);
gboolean            epc_publisher_has_key               (EpcPublisher *publisher,
                                                         const gchar *key);
gpointer            epc_publisher_lookup                (EpcPublisher *publisher,
                                                         const gchar *key);
gboolean            epc_publisher_remove                (EpcPublisher *publisher,
                                                         const gchar *key);
GList *             epc_publisher_list                  (EpcPublisher *publisher,
                                                         const gchar *pattern);

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

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

void                epc_publisher_set_auth_flags        (EpcPublisher *publisher,
                                                         EpcAuthFlags flags);
void                epc_publisher_set_auth_handler      (EpcPublisher *publisher,
                                                         const gchar *key,
                                                         EpcAuthHandler handler,
                                                         gpointer user_data,
                                                         GDestroyNotify destroy_data);
void                epc_publisher_set_collision_handling
                                                        (EpcPublisher *publisher,
                                                         EpcCollisionHandling method);
void                epc_publisher_set_contents_path     (EpcPublisher *publisher,
                                                         const gchar *path);
void                epc_publisher_set_credentials       (EpcPublisher *publisher,
                                                         const gchar *certfile,
                                                         const gchar *keyfile);
void                epc_publisher_set_protocol          (EpcPublisher *publisher,
                                                         EpcProtocol protocol);
void                epc_publisher_set_service_cookie    (EpcPublisher *publisher,
                                                         const gchar *cookie);
void                epc_publisher_set_service_name      (EpcPublisher *publisher,
                                                         const gchar *name);

EpcAuthFlags        epc_publisher_get_auth_flags        (EpcPublisher *publisher);
const gchar *       epc_publisher_get_certificate_file  (EpcPublisher *publisher);
EpcCollisionHandling epc_publisher_get_collision_handling
                                                        (EpcPublisher *publisher);
const gchar *       epc_publisher_get_contents_path     (EpcPublisher *publisher);
const gchar *       epc_publisher_get_private_key_file  (EpcPublisher *publisher);
EpcProtocol         epc_publisher_get_protocol          (EpcPublisher *publisher);
const gchar *       epc_publisher_get_service_cookie    (EpcPublisher *publisher);
const gchar *       epc_publisher_get_service_domain    (EpcPublisher *publisher);
const gchar *       epc_publisher_get_service_name      (EpcPublisher *publisher);

Object Hierarchy

  GObject
   +----EpcPublisher

Properties

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

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

1
2
3
4
5
6
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.

Details

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.

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.

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.


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.

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.

Note

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.

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.

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.

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.

Note

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

Note

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

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.

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.

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.

See also: epc_publisher_lookup.

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.

See also: epc_publisher_has_key.

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.

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.

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

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.

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.

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.

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.

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.

Note

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

See also epc_publisher_set_auth_flags().

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

publisher :

a EpcPublisher

Returns :

The human friendly name of this EpcPublisher.

Property Details

The "application" property

  "application"              gchar*                : Read / Write / Construct

Program name for deriving the service type.

Default value: NULL


The "auth-flags" property

  "auth-flags"               EpcAuthFlags          : Read / Write / Construct

The authentication settings to use.


The "certificate-file" property

  "certificate-file"         gchar*                : Read / Write / Construct

File name for the PEM encoded server certificate.

Default value: NULL


The "collision-handling" property

  "collision-handling"       EpcCollisionHandling  : Read / Write / Construct

The collision handling strategy the publisher uses.

Default value: EPC_COLLISIONS_CHANGE_NAME

Since 0.3.1


The "contents-path" property

  "contents-path"            gchar*                : Read / Write / Construct

The built-in server path for publishing resources.

Default value: "/contents"


The "private-key-file" property

  "private-key-file"         gchar*                : Read / Write / Construct

File name for the PEM encoded private server key.

Default value: NULL


The "protocol" property

  "protocol"                 EpcProtocol           : Read / Write / Construct

The transport protocol the publisher uses.

Default value: EPC_PROTOCOL_HTTPS


The "service-cookie" property

  "service-cookie"           gchar*                : Read / Write / Construct

Unique identifier of the service. This cookie is used for implementing EPC_COLLISIONS_UNIQUE_SERVICE, and usually is a UUID or the MD5/SHA1/... checksum of a central document. When passing NULL, but using the EPC_COLLISIONS_UNIQUE_SERVICE strategy a time based UUID is generated and used as service identifier.

Default value: NULL

Since 0.3.1


The "service-domain" property

  "service-domain"           gchar*                : Read / Write / Construct

Internet domain for publishing the service.

Default value: NULL


The "service-name" property

  "service-name"             gchar*                : Read / Write / Construct

User friendly name for the service.

Default value: NULL