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

## See Also

EpcConsumer, EpcAuthContext, EpcContentsHandler