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

  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
Generated by GTK-Doc V1.11