EpcContents

## EpcContents EpcContents — custom contents |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <libepc/contents.h>

    gboolean            (*EpcContentsReadFunc)              (EpcContents *contents,
                                                             gpointer buffer,
                                                             gsize *length,
                                                             gpointer user_data);
                        EpcContents;
    EpcContents *       epc_contents_new                    (const gchar *type,
                                                             gpointer data,
                                                             gssize length,
                                                             GDestroyNotify destroy_data);
    EpcContents *       epc_contents_new_dup                (const gchar *type,
                                                             gconstpointer data,
                                                             gssize length);
    EpcContents *       epc_contents_ref                    (EpcContents *contents);
    void                epc_contents_unref                  (EpcContents *contents);

    gconstpointer       epc_contents_get_data               (EpcContents *contents,
                                                             gsize *length);
    const gchar *       epc_contents_get_mime_type          (EpcContents *contents);

    EpcContents *       epc_contents_stream_new             (const gchar *type,
                                                             EpcContentsReadFunc callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy_data);
    gconstpointer       epc_contents_stream_read            (EpcContents *contents,
                                                             gsize *length);
    gboolean            epc_contents_is_stream              (EpcContents *contents);

## Description

EpcContents is a reference counted structure for storing custom contents. To publish custom content call `epc_publisher_add_handler()` to register a EpcContentsHandler like this:

Example 5. A custom contents handler

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    static EpcContents*
    timestamp_handler (EpcPublisher *publisher G_GNUC_UNUSED,
                       const gchar  *key G_GNUC_UNUSED,
                       gpointer      data)
    {
      time_t now = time (NULL);
      struct tm *tm = localtime (&now);
      const gchar *format = data;
      gsize length = 60;
      gchar *buffer;

      buffer = g_malloc (length);
      length = strftime (buffer, length, format, tm);

      return epc_content_new ("text/plain", buffer, length);
    }

## Details

### EpcContentsReadFunc ()

    gboolean            (*EpcContentsReadFunc)              (EpcContents *contents,
                                                             gpointer buffer,
                                                             gsize *length,
                                                             gpointer user_data);

This callback is used to retrieve the next chunk of data for a streaming contents buffer created with epc_contents_stream_read.

Return `FALSE` when the buffer has reached its end, and no more data is available. Also return `FALSE`, when the buffer size passed in `length` is not sufficient. Copy your minimal buffer size to `length` in that situation.

The library might pass `NULL` for `buffer` on the first call to start buffer size negotation.

See also: epc_contents_stream_new, epc_contents_stream_read

`contents` : | a EpcContents buffer
`buffer` : | a location for storing the contents, or `NULL`
`length` : | a location for passing and storing the contents length in bytes.
`user_data` : | the user_data passed to epc_contents_stream_new
Returns : | Returns `TRUE` when the next chunk could be read, and `FALSE` on error.

### EpcContents

    typedef struct _EpcContents EpcContents;

A reference counted buffer for storing contents to deliver by the EpcPublisher. Use `epc_contents_new()` or epc_contents_new_dup to create instances of this buffer.

### epc_contents_new ()

    EpcContents *       epc_contents_new                    (const gchar *type,
                                                             gpointer data,
                                                             gssize length,
                                                             GDestroyNotify destroy_data);

Creates a new EpcContents buffer, and takes ownership of the `data` passed. Passing `NULL` for `type` is equivalent to passing "application/octet-stream".

See also: epc_contents_new_dup, epc_contents_stream_new

`type` : | the MIME type of this contents, or `NULL`
`data` : | static contents for the buffer
`length` : | the contents length in bytes, or -1 if `data` is a null-terminated string.
`destroy_data` : | This function will be called to free `data` when it is no longer needed.
Returns : | The newly created EpcContents buffer.

### epc_contents_new_dup ()

    EpcContents *       epc_contents_new_dup                (const gchar *type,
                                                             gconstpointer data,
                                                             gssize length);

Creates a new EpcContents buffer, and copies the `data` passed. Passing `NULL` for `type` is equivalent to passing "application/octet-stream".

See also: epc_contents_new, epc_contents_stream_new

`type` : | the MIME type of this contents, or `NULL`
`data` : | static contents for the buffer
`length` : | the content's length in bytes, or -1 if `data` is a null-terminated string.
Returns : | The newly created EpcContents buffer.

### epc_contents_ref ()

    EpcContents *       epc_contents_ref                    (EpcContents *contents);

Increases the reference count of `contents`.

`contents` : | a EpcContents buffer
Returns : | the same `contents` buffer.

### epc_contents_unref ()

    void                epc_contents_unref                  (EpcContents *contents);

Decreases the reference count of `contents`. When its reference count drops to 0, the buffer is released (i.e. its memory is freed).

`contents` : | a EpcContents buffer

### epc_contents_get_data ()

    gconstpointer       epc_contents_get_data               (EpcContents *contents,
                                                             gsize *length);

Retrieves the contents of a static contents buffer created with `epc_contents_new()`. Any other buffer returns `NULL`. The data returned is owned by the EpcContents buffer and must not be freeded.

See also: `epc_contents_stream_read()`.

`contents` : | a EpcContents buffer
`length` : | a location for storing the contents length
Returns : | Returns the static buffer contents, or `NULL`. This should not be freed or modified.

### epc_contents_get_mime_type ()

    const gchar *       epc_contents_get_mime_type          (EpcContents *contents);

Queries the MIME type associated with the buffer. Returns the MIME type specified for `epc_contents_new()` or epc_contents_stream_new, or "application/octet-stream" when `NULL` was passed.

`contents` : | a EpcContents buffer
Returns : | Returns the MIME type of the buffer.

### epc_contents_stream_new ()

    EpcContents *       epc_contents_stream_new             (const gchar *type,
                                                             EpcContentsReadFunc callback,
                                                             gpointer user_data,
                                                             GDestroyNotify destroy_data);

Creates a new EpcContents buffer for large contents like movie files, which cannot, or should be delivered as solid blob of data.

Passing `NULL` for `type` is equivalent to passing "application/octet-stream".

See also: `epc_contents_stream_read()`, epc_contents_is_stream

`type` : | the MIME type of this contents, or `NULL`
`callback` : | the function for retrieving chunks
`user_data` : | data which will be passed to `callback`
`destroy_data` : | This function will be called to free `user_data` when it is no longer needed.
Returns : | The newly created EpcContents buffer.

### epc_contents_stream_read ()

    gconstpointer       epc_contents_stream_read            (EpcContents *contents,
                                                             gsize *length);

Retrieves the next chunk of data for a streaming contents buffer created with `epc_contents_stream_read()`. `NULL` is returned, when the buffer has reached its end, or isn't a streaming contents buffer.

The data returned is owned by the EpcContents buffer and must not be freeded by the called. Make sure to copy the returned data before the function again, as repeated calls to the function might return the same buffer, but filled with new data.

See also: `epc_contents_stream_new()`, epc_contents_is_stream

`contents` : | a EpcContents buffer
`length` : | a location for storing the contents length
Returns : | Returns the next chunk of data, or `NULL`. The should not be freed or modified.

### epc_contents_is_stream ()

    gboolean            epc_contents_is_stream              (EpcContents *contents);

Checks if stream routines can be used for retreiving the contents of the buffer.

See also: `epc_contents_stream_new()`, epc_contents_stream_read

`contents` : | a EpcContents buffer
Returns : | Returns `TRUE` when stream routines have to be used.

## See Also

EpcPublisher