EpcContents

EpcContents — custom contents

Stability Level

Unstable, unless otherwise indicated

Types and Values

Includes

#include <libepc/contents.h>

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);
}


Functions

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

Parameters

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.


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

Parameters

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

Parameters

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 .

Parameters

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

Parameters

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

Parameters

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.

Parameters

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

Parameters

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

Parameters

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

Parameters

contents

a EpcContents buffer

 

Returns

Returns TRUE when stream routines have to be used.

Types and Values

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.

See Also

EpcPublisher