MafwExtension

MafwExtension — Base class for both sources and renderers

Synopsis

                    MafwExtension;
#define             MAFW_EXTENSION_ERROR
#define             MAFW_EXTENSION_SUPPORTS_ERROR_POLICY(self)
#define             MAFW_EXTENSION_SUPPORTS_MUTE        (self)
#define             MAFW_EXTENSION_SUPPORTS_VOLUME      (self)
#define             MAFW_EXTENSION_SUPPORTS_XID         (self)
#define             MAFW_EXTENSION_SUPPORTS_AUTOPAINT   (self)
#define             MAFW_EXTENSION_SUPPORTS_COLORKEY    (self)
enum                MafwExtensionError;
                    MafwExtensionProperty;
void                (*MafwExtensionPropertyCallback)    (MafwExtension *self,
                                                         const gchar *name,
                                                         GValue *value,
                                                         gpointer udata,
                                                         const GError *error);
const gchar*        mafw_extension_get_name             (MafwExtension *self);
const gchar*        mafw_extension_get_uuid             (MafwExtension *self);
void                mafw_extension_set_name             (MafwExtension *self,
                                                         const gchar *name);
const gchar*        mafw_extension_get_plugin           (MafwExtension *self);
void                mafw_extension_add_property         (MafwExtension *self,
                                                         const gchar *name,
                                                         GType type);
void                mafw_extension_emit_property_changed
                                                        (MafwExtension *self,
                                                         const gchar *property,
                                                         const GValue *value);
void                mafw_extension_get_property         (MafwExtension *self,
                                                         const gchar *name,
                                                         MafwExtensionPropertyCallback cb,
                                                         gpointer udata);
const GPtrArray*    mafw_extension_list_properties      (MafwExtension *self);
gboolean            mafw_extension_set_property         (MafwExtension *self,
                                                         const gchar *name,
                                                         const GValue *value);
gboolean            mafw_extension_set_property_boolean (MafwExtension *self,
                                                         const gchar *name,
                                                         gboolean value);
gboolean            mafw_extension_set_property_char    (MafwExtension *self,
                                                         const gchar *name,
                                                         gchar value);
gboolean            mafw_extension_set_property_double  (MafwExtension *self,
                                                         const gchar *name,
                                                         gdouble value);
gboolean            mafw_extension_set_property_float   (MafwExtension *self,
                                                         const gchar *name,
                                                         gfloat value);
gboolean            mafw_extension_set_property_int     (MafwExtension *self,
                                                         const gchar *name,
                                                         gint value);
gboolean            mafw_extension_set_property_int64   (MafwExtension *self,
                                                         const gchar *name,
                                                         gint64 value);
gboolean            mafw_extension_set_property_long    (MafwExtension *self,
                                                         const gchar *name,
                                                         glong value);
gboolean            mafw_extension_set_property_string  (MafwExtension *self,
                                                         const gchar *name,
                                                         const gchar *value);
gboolean            mafw_extension_set_property_uchar   (MafwExtension *self,
                                                         const gchar *name,
                                                         guchar value);
gboolean            mafw_extension_set_property_uint    (MafwExtension *self,
                                                         const gchar *name,
                                                         guint value);
gboolean            mafw_extension_set_property_uint64  (MafwExtension *self,
                                                         const gchar *name,
                                                         guint64 value);
gboolean            mafw_extension_set_property_ulong   (MafwExtension *self,
                                                         const gchar *name,
                                                         gulong value);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----MafwExtension
               +----MafwSource
               +----MafwRenderer

Properties

  "name"                     gchar*                : Read / Write / Construct
  "plugin"                   gchar*                : Read / Write / Construct Only
  "uuid"                     gchar*                : Read / Write / Construct Only

Signals

  "error"                                          : Run First
  "property-changed"                               : Run First / Has Details

Description

MafwExtension is an abstract base class common to both sources and renderers. It provides the name and uuid properties, as described in MafwRegistry.

Run-time properties

Sources and renderers may have class- (or even instance-) specific run-time properties. Examples are Brightness of the screen of an UPnP renderer, or Volume, but subclasses are free to use this facility for their own purposes. If a subclass wants to have run-time properties, it should call mafw_extension_add_property() for each of its properties at some point (probably in the instance initializer). Known properties (and their types) may be listed with mafw_extension_list_properties(); queried with mafw_extension_get_property() and set using the mafw_extension_set_property_*() family of functions.

Details

MafwExtension

typedef struct _MafwExtension MafwExtension;

Mafw SiSo object structure

MAFW_EXTENSION_ERROR

#define MAFW_EXTENSION_ERROR g_quark_from_static_string("com.nokia.mafw.error.extension")

Gets a quark for common renderer/source errors

MAFW_EXTENSION_SUPPORTS_ERROR_POLICY()

#define             MAFW_EXTENSION_SUPPORTS_ERROR_POLICY(self)

Adds property for selecting an error policy.

self : MafwExtension instance to add the property on

MAFW_EXTENSION_SUPPORTS_MUTE()

#define             MAFW_EXTENSION_SUPPORTS_MUTE(self)

Adds property for selecting mute

self : MafwExtension instance to add the property on

MAFW_EXTENSION_SUPPORTS_VOLUME()

#define             MAFW_EXTENSION_SUPPORTS_VOLUME(self)

Adds property for selecting volume

self : MafwExtension instance to add the property on

MAFW_EXTENSION_SUPPORTS_XID()

#define             MAFW_EXTENSION_SUPPORTS_XID(self)

Adds property for selecting a xid

self : MafwExtension instance to add the property on

MAFW_EXTENSION_SUPPORTS_AUTOPAINT()

#define             MAFW_EXTENSION_SUPPORTS_AUTOPAINT(self)

self :

MAFW_EXTENSION_SUPPORTS_COLORKEY()

#define             MAFW_EXTENSION_SUPPORTS_COLORKEY(self)

self :

enum MafwExtensionError

typedef enum
{
/* Common errors */
  MAFW_EXTENSION_ERROR_EXTENSION_NOT_AVAILABLE,
  MAFW_EXTENSION_ERROR_UNSUPPORTED_OPERATION,
  MAFW_EXTENSION_ERROR_NETWORK_DOWN,
  MAFW_EXTENSION_ERROR_SERVICE_NOT_RESPONDING,
  MAFW_EXTENSION_ERROR_EXTENSION_NOT_RESPONDING,
  MAFW_EXTENSION_ERROR_INVALID_PROPERTY,
  MAFW_EXTENSION_ERROR_SET_PROPERTY,
  MAFW_EXTENSION_ERROR_GET_PROPERTY,
  MAFW_EXTENSION_ERROR_ACCESS_DENIED,
  MAFW_EXTENSION_ERROR_INVALID_PARAMS,
  MAFW_EXTENSION_ERROR_OUT_OF_MEMORY,
  MAFW_EXTENSION_ERROR_FAILED
} MafwExtensionError;

MAFW error code definitions for common errors for all renderers and sources.

MAFW_EXTENSION_ERROR_EXTENSION_NOT_AVAILABLE Source or renderer with the specified uuid was not available or could not be reached.
MAFW_EXTENSION_ERROR_UNSUPPORTED_OPERATION Tried to invoke an action which was not supported at the moment (e.g. due to policy management, media format, missing functionality...)
MAFW_EXTENSION_ERROR_NETWORK_DOWN Bad network conditions or no network at all. Extension cannot connect to the service in the network.
MAFW_EXTENSION_ERROR_SERVICE_NOT_RESPONDING Service in the network not responding. Request timed out.
MAFW_EXTENSION_ERROR_EXTENSION_NOT_RESPONDING Extension is busy or not responding. Request timed out.
MAFW_EXTENSION_ERROR_INVALID_PROPERTY Tried to get/set a property which doesn't exist
MAFW_EXTENSION_ERROR_SET_PROPERTY Error setting property
MAFW_EXTENSION_ERROR_GET_PROPERTY Error getting property
MAFW_EXTENSION_ERROR_ACCESS_DENIED Authorization to extension or service failed.
MAFW_EXTENSION_ERROR_INVALID_PARAMS Action invoked with some invalid parameter, e.g. wrong search filter, seek target, etc.
MAFW_EXTENSION_ERROR_OUT_OF_MEMORY System is in low memory state.
MAFW_EXTENSION_ERROR_FAILED Other failure, error->message should explain

MafwExtensionProperty

typedef struct {
        gchar *name;
        GType type;
} MafwExtensionProperty;

Information about a run-time property.

gchar *name; name of the property.
GType type; the GType of the property.

MafwExtensionPropertyCallback ()

void                (*MafwExtensionPropertyCallback)    (MafwExtension *self,
                                                         const gchar *name,
                                                         GValue *value,
                                                         gpointer udata,
                                                         const GError *error);

Callback for asynchronous run-time property retrieval. Ownership of value is passed to the callee. If error is set, value is NULL.

self : a MafwExtension instance.
name : the name of the returned property.
value : the value of the property, owned by the callee.
udata : additional data.
error : non-NULL if an error occurred. Freed by the caller.

mafw_extension_get_name ()

const gchar*        mafw_extension_get_name             (MafwExtension *self);

Queries the name of the extension.

self : a MafwExtension instance.
Returns : the name of the extension. The value is owned by the MafwExtension and should never be modified or freed.

mafw_extension_get_uuid ()

const gchar*        mafw_extension_get_uuid             (MafwExtension *self);

Queries the UUID of the extension.

self : a MafwExtension instance.
Returns : the UUID of the object. The value is owned by the MafwExtension and should never be modified or freed.

mafw_extension_set_name ()

void                mafw_extension_set_name             (MafwExtension *self,
                                                         const gchar *name);

Sets the name of the extension to name.

self : a MafwExtension instance.
name : the new name of the extension.

mafw_extension_get_plugin ()

const gchar*        mafw_extension_get_plugin           (MafwExtension *self);

Queries the name of the plugin that created self.

self : a MafwExtension instance.
Returns : MafwExtension:name, owned by the extension, not modifiable by the user.

mafw_extension_add_property ()

void                mafw_extension_add_property         (MafwExtension *self,
                                                         const gchar *name,
                                                         GType type);

Adds name to the list of supported properties of this MafwExtension instance. This function exists for the convenience of subclasses (to call e.g. in their list_extension_properties implementation). It does nothing if a property already exists with the given name.

self : a MafwExtension instance.
name : the name of the property.
type : the GType of the property.

mafw_extension_emit_property_changed ()

void                mafw_extension_emit_property_changed
                                                        (MafwExtension *self,
                                                         const gchar *property,
                                                         const GValue *value);

Emits "property-changed" with property as detail. This is a helper function for subclasses, who should call this after the property change initiated with mafw_extension_set_property() is in effect.

self : a MafwExtension instance.
property : property to signal
value : GValue with property value.

mafw_extension_get_property ()

void                mafw_extension_get_property         (MafwExtension *self,
                                                         const gchar *name,
                                                         MafwExtensionPropertyCallback cb,
                                                         gpointer udata);

Queries a run-time property asynchronously. The callback will be always invoked (with a GError if appropriate).

self : a MafwExtension instance.
name : name of a property.
cb : a function to call with the result.
udata : additional data passed to cb.

mafw_extension_list_properties ()

const GPtrArray*    mafw_extension_list_properties      (MafwExtension *self);

List the SiSo properties.

self : a MafwExtension instance.
Returns : a GPtrArray containing pointers to MafwExtensionProperty structures. The caller should NOT modify it in any way. It is assumed that the returned list will not change after the first invocation of this function (callers may cache it).

mafw_extension_set_property ()

gboolean            mafw_extension_set_property         (MafwExtension *self,
                                                         const gchar *name,
                                                         const GValue *value);

Sets the run-time property named name on self. This may happen asynchronously, so the new value may not be in effect for a while. If the change is in effect "property-changed" will be emitted. If some error happens, the interested is notified using "error" (codes from MafwExtensionError).

self : a MafwExtension instance.
name : name of the property.
value : the value to set.
Returns : FALSE if the property does not exists or it's type is different than of value.

mafw_extension_set_property_boolean ()

gboolean            mafw_extension_set_property_boolean (MafwExtension *self,
                                                         const gchar *name,
                                                         gboolean value);

Sets a value of type gboolean.

self : a MafwExtension instance
name : name
value : value
Returns : TRUE if success, FALSE otherwise.

mafw_extension_set_property_char ()

gboolean            mafw_extension_set_property_char    (MafwExtension *self,
                                                         const gchar *name,
                                                         gchar value);

Sets a value of type gchar.

self : a MafwExtension instance
name : name
value : value
Returns : TRUE if success, FALSE otherwise.

mafw_extension_set_property_double ()

gboolean            mafw_extension_set_property_double  (MafwExtension *self,
                                                         const gchar *name,
                                                         gdouble value);

Sets a value of type gdouble.

self : a MafwExtension instance
name : name
value : value
Returns : TRUE if success, FALSE otherwise.

mafw_extension_set_property_float ()

gboolean            mafw_extension_set_property_float   (MafwExtension *self,
                                                         const gchar *name,
                                                         gfloat value);

Sets a value of type gfloat.

self : a MafwExtension instance
name : name
value : value
Returns : TRUE if success, FALSE otherwise.

mafw_extension_set_property_int ()

gboolean            mafw_extension_set_property_int     (MafwExtension *self,
                                                         const gchar *name,
                                                         gint value);

Sets a value of type gint.

self : a MafwExtension instance
name : name
value : value
Returns : TRUE if success, FALSE otherwise.

mafw_extension_set_property_int64 ()

gboolean            mafw_extension_set_property_int64   (MafwExtension *self,
                                                         const gchar *name,
                                                         gint64 value);

Sets a value of type gint64.

self : a MafwExtension instance
name : name
value : value
Returns : TRUE if success, FALSE otherwise.

mafw_extension_set_property_long ()

gboolean            mafw_extension_set_property_long    (MafwExtension *self,
                                                         const gchar *name,
                                                         glong value);

Sets a value of type glong.

self : a MafwExtension instance
name : name
value : value
Returns : TRUE if success, FALSE otherwise.

mafw_extension_set_property_string ()

gboolean            mafw_extension_set_property_string  (MafwExtension *self,
                                                         const gchar *name,
                                                         const gchar *value);

Sets a property of value gchar*.

self : a MafwExtension object
name : property name
value : value
Returns : TRUE on success, FALSE otherwise

mafw_extension_set_property_uchar ()

gboolean            mafw_extension_set_property_uchar   (MafwExtension *self,
                                                         const gchar *name,
                                                         guchar value);

Sets a value of type guchar.

self : a MafwExtension instance
name : name
value : value
Returns : TRUE if success, FALSE otherwise.

mafw_extension_set_property_uint ()

gboolean            mafw_extension_set_property_uint    (MafwExtension *self,
                                                         const gchar *name,
                                                         guint value);

Sets a value of type guint.

self : a MafwExtension instance
name : name
value : value
Returns : TRUE if success, FALSE otherwise.

mafw_extension_set_property_uint64 ()

gboolean            mafw_extension_set_property_uint64  (MafwExtension *self,
                                                         const gchar *name,
                                                         guint64 value);

Sets a value of type guint64.

self : a MafwExtension instance
name : name
value : value
Returns : TRUE if success, FALSE otherwise.

mafw_extension_set_property_ulong ()

gboolean            mafw_extension_set_property_ulong   (MafwExtension *self,
                                                         const gchar *name,
                                                         gulong value);

Sets a value of type gulong.

self : a MafwExtension instance
name : name
value : value
Returns : TRUE if success, FALSE otherwise.

Property Details

The "name" property

  "name"                     gchar*                : Read / Write / Construct

The name of the extension.

Default value: ""

The "plugin" property

  "plugin"                   gchar*                : Read / Write / Construct Only

Name of the plugin which created the extension. MUST be given at construction-time and it is not modifiable afterwards.

Default value: NULL

The "uuid" property

  "uuid"                     gchar*                : Read / Write / Construct Only

The read-only UUID of the extension, MUST be given at construction-time and it is not modifiable afterwards.

Default value: NULL

Signal Details

The "error" signal

void                user_function                      (MafwExtension *self,
                                                        guint          domain,
                                                        gint           code,
                                                        gchar         *message,
                                                        gpointer       user_data)      : Run First

A signal indicating that a spontaneous error has occured.

self : a MafwExtension instance.
domain : GQuark representing the error domain string.
code : an error code.
message : Error description string
user_data : user data set when the signal handler was connected.

The "property-changed" signal

void                user_function                      (MafwExtension *self,
                                                        gchar         *name,
                                                        GValue        *val,
                                                        gpointer       user_data)      : Run First / Has Details

A detailed signal indicating that a run-time property has changed ("property-changed::foo" is emitted if a property named "foo" changed). Note that `changed' does not necessary mean a different value, but the fact that someone has issued mafw_extension_set_property(). The handler prototype looks like the following: 

void property_changed(MafwExtension *object, const gchar *name,
                      const GValue *value);

self : a MafwExtension instance.
name : the name of the changed property.
val : a GValue representing the new value.
user_data : user data set when the signal handler was connected.
Generated by GTK-Doc V1.10