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

    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.

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

See also: epc_publisher_lookup.

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

See also: epc_publisher_has_key.

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

See also `epc_publisher_set_auth_flags()`.

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

## Property Details

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

## See Also

EpcConsumer, EpcAuthContext, EpcContentsHandler