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.

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.

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.

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.

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.

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.

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.

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

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.

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.

epc_publisher_remove ()

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

Removes a key and its associated contents from a 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.

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

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

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

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

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.

epc_publisher_expand_name ()

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

Expands all known placeholders in name . Supported placeholders are:

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.

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.

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.

See also epc_publisher_set_auth_flags().

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.

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.

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.

epc_publisher_set_protocol ()

void
epc_publisher_set_protocol (EpcPublisher *publisher,
                            EpcProtocol protocol);

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

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.

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.

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.

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.

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.

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.

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.

epc_publisher_get_protocol ()

EpcProtocol
epc_publisher_get_protocol (EpcPublisher *publisher);

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

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.

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.

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.

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.

The “application” property

  “application”              gchar *

Program name for deriving the service type.

Flags: Read / Write / Construct

Default value: NULL

The “auth-flags” property

  “auth-flags”               EpcAuthFlags

The authentication settings to use.

Flags: Read / Write / Construct

The “certificate-file” property

  “certificate-file”         gchar *

File name for the PEM encoded server certificate.

Flags: Read / Write / Construct

Default value: NULL

The “collision-handling” property

  “collision-handling”       EpcCollisionHandling

The collision handling strategy the publisher uses.

Flags: Read / Write / Construct

Default value: EPC_COLLISIONS_CHANGE_NAME

Since: 0.3.1

The “contents-path” property

  “contents-path”            gchar *

The built-in server path for publishing resources.

Flags: Read / Write / Construct

Default value: "/contents"

The “private-key-file” property

  “private-key-file”         gchar *

File name for the PEM encoded private server key.

Flags: Read / Write / Construct

Default value: NULL

The “protocol” property

  “protocol”                 EpcProtocol

The transport protocol the publisher uses.

Flags: Read / Write / Construct

Default value: EPC_PROTOCOL_HTTPS

The “service-cookie” property

  “service-cookie”           gchar *

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.

Flags: Read / Write / Construct

Default value: NULL

Since: 0.3.1

The “service-domain” property

  “service-domain”           gchar *

Internet domain for publishing the service.

Flags: Read / Write / Construct

Default value: NULL

The “service-name” property

  “service-name”             gchar *

User friendly name for the service.

Flags: Read / Write / Construct

Default value: NULL