GUPnPServiceProxy

GUPnPServiceProxy — Proxy class for remote services.

Synopsis

                    GUPnPServiceProxy;
                    GUPnPServiceProxyAction;
void                (*GUPnPServiceProxyActionCallback)  (GUPnPServiceProxy *proxy,
                                                         GUPnPServiceProxyAction *action,
                                                         gpointer user_data);
void                (*GUPnPServiceProxyNotifyCallback)  (GUPnPServiceProxy *proxy,
                                                         const char *variable,
                                                         GValue *value,
                                                         gpointer user_data);
gboolean            gupnp_service_proxy_send_action     (GUPnPServiceProxy *proxy,
                                                         const char *action,
                                                         GError **error,
                                                         ...);
gboolean            gupnp_service_proxy_send_action_valist
                                                        (GUPnPServiceProxy *proxy,
                                                         const char *action,
                                                         GError **error,
                                                         va_list var_args);
gboolean            gupnp_service_proxy_send_action_hash
                                                        (GUPnPServiceProxy *proxy,
                                                         const char *action,
                                                         GError **error,
                                                         GHashTable *in_hash,
                                                         GHashTable *out_hash);
GUPnPServiceProxyAction* gupnp_service_proxy_begin_action
                                                        (GUPnPServiceProxy *proxy,
                                                         const char *action,
                                                         GUPnPServiceProxyActionCallback callback,
                                                         gpointer user_data,
                                                         ...);
GUPnPServiceProxyAction* gupnp_service_proxy_begin_action_valist
                                                        (GUPnPServiceProxy *proxy,
                                                         const char *action,
                                                         GUPnPServiceProxyActionCallback callback,
                                                         gpointer user_data,
                                                         va_list var_args);
GUPnPServiceProxyAction* gupnp_service_proxy_begin_action_hash
                                                        (GUPnPServiceProxy *proxy,
                                                         const char *action,
                                                         GUPnPServiceProxyActionCallback callback,
                                                         gpointer user_data,
                                                         GHashTable *hash);
gboolean            gupnp_service_proxy_end_action      (GUPnPServiceProxy *proxy,
                                                         GUPnPServiceProxyAction *action,
                                                         GError **error,
                                                         ...);
gboolean            gupnp_service_proxy_end_action_valist
                                                        (GUPnPServiceProxy *proxy,
                                                         GUPnPServiceProxyAction *action,
                                                         GError **error,
                                                         va_list var_args);
gboolean            gupnp_service_proxy_end_action_hash (GUPnPServiceProxy *proxy,
                                                         GUPnPServiceProxyAction *action,
                                                         GError **error,
                                                         GHashTable *hash);
void                gupnp_service_proxy_cancel_action   (GUPnPServiceProxy *proxy,
                                                         GUPnPServiceProxyAction *action);
gboolean            gupnp_service_proxy_add_notify      (GUPnPServiceProxy *proxy,
                                                         const char *variable,
                                                         GType type,
                                                         GUPnPServiceProxyNotifyCallback callback,
                                                         gpointer user_data);
gboolean            gupnp_service_proxy_remove_notify   (GUPnPServiceProxy *proxy,
                                                         const char *variable,
                                                         GUPnPServiceProxyNotifyCallback callback,
                                                         gpointer user_data);
void                gupnp_service_proxy_set_subscribed  (GUPnPServiceProxy *proxy,
                                                         gboolean subscribed);
gboolean            gupnp_service_proxy_get_subscribed  (GUPnPServiceProxy *proxy);

Object Hierarchy

  GObject
   +----GUPnPServiceInfo
         +----GUPnPServiceProxy

Properties

  "subscribed"               gboolean              : Read / Write

Signals

  "subscription-lost"                              : Run Last

Description

GUPnPServiceProxy sends commands to a remote UPnP service and handles incoming event notifications. GUPnPServiceProxy implements the GUPnPServiceInfo interface.

Details

GUPnPServiceProxy

typedef struct _GUPnPServiceProxy GUPnPServiceProxy;

This struct contains private data only, and should be accessed using the functions below.

GUPnPServiceProxyAction

typedef struct _GUPnPServiceProxyAction GUPnPServiceProxyAction;

Opaque structure for holding in-progress action data.

GUPnPServiceProxyActionCallback ()

void                (*GUPnPServiceProxyActionCallback)  (GUPnPServiceProxy *proxy,
                                                         GUPnPServiceProxyAction *action,
                                                         gpointer user_data);

Callback notifying that action on proxy has returned and gupnp_service_proxy_end_action() etc can be called.

proxy :

 The GUPnPServiceProxy action is called from

action :

 The GUPnPServiceProxyAction in progress

user_data :

 User data

GUPnPServiceProxyNotifyCallback ()

void                (*GUPnPServiceProxyNotifyCallback)  (GUPnPServiceProxy *proxy,
                                                         const char *variable,
                                                         GValue *value,
                                                         gpointer user_data);

Callback notifying that the state variable variable on proxy has changed to value.

proxy :

 The GUPnPServiceProxy the notification originates from

variable :

 The name of the variable being notified

value :

 The GValue of the variable being notified

user_data :

 User data

gupnp_service_proxy_send_action ()

gboolean            gupnp_service_proxy_send_action     (GUPnPServiceProxy *proxy,
                                                         const char *action,
                                                         GError **error,
                                                         ...);

Sends action action with parameters Varargs to the service exposed by proxy synchronously. If an error occurred, error will be set. In case of a UPnPError the error code will be the same in error.

proxy :

 A GUPnPServiceProxy

action :

 An action

error :

 The location where to store any error, or NULL

... :

 tuples of in parameter name, in parameter type, and in parameter value, followed by NULL, and then tuples of out parameter name, out parameter type, and out parameter value location, terminated with NULL

Returns :

 TRUE if sending the action was succesful.

gupnp_service_proxy_send_action_valist ()

gboolean            gupnp_service_proxy_send_action_valist
                                                        (GUPnPServiceProxy *proxy,
                                                         const char *action,
                                                         GError **error,
                                                         va_list var_args);

See gupnp_service_proxy_send_action(); this version takes a va_list for use by language bindings.

proxy :

 A GUPnPServiceProxy

action :

 An action

error :

 The location where to store any error, or NULL

var_args :

 va_list of tuples of in parameter name, in parameter type, and in parameter value, followed by NULL, and then tuples of out parameter name, out parameter type, and out parameter value location

Returns :

 TRUE if sending the action was succesful.

gupnp_service_proxy_send_action_hash ()

gboolean            gupnp_service_proxy_send_action_hash
                                                        (GUPnPServiceProxy *proxy,
                                                         const char *action,
                                                         GError **error,
                                                         GHashTable *in_hash,
                                                         GHashTable *out_hash);

See gupnp_service_proxy_send_action(); this version takes a pair of GHashTables for runtime determined parameter lists.

proxy :

 A GUPnPServiceProxy

action :

 An action

error :

 The location where to store any error, or NULL

in_hash :

 A GHashTable of in parameter name and GValue pairs

out_hash :

 A GHashTable of out parameter name and initialized GValue pairs

Returns :

 TRUE if sending the action was succesful.

gupnp_service_proxy_begin_action ()

GUPnPServiceProxyAction* gupnp_service_proxy_begin_action
                                                        (GUPnPServiceProxy *proxy,
                                                         const char *action,
                                                         GUPnPServiceProxyActionCallback callback,
                                                         gpointer user_data,
                                                         ...);

Sends action action with parameters Varargs to the service exposed by proxy asynchronously, calling callback on completion. From callback, call gupnp_service_proxy_end_action() to check for errors, to retrieve return values, and to free the GUPnPServiceProxyAction.

proxy :

 A GUPnPServiceProxy

action :

 An action

callback :

 The callback to call when sending the action has succeeded or failed

user_data :

 User data for callback

... :

 tuples of in parameter name, in parameter type, and in parameter value, terminated with NULL

Returns :

 A GUPnPServiceProxyAction handle. This will be freed when calling gupnp_service_proxy_cancel_action() or gupnp_service_proxy_end_action_valist().

gupnp_service_proxy_begin_action_valist ()

GUPnPServiceProxyAction* gupnp_service_proxy_begin_action_valist
                                                        (GUPnPServiceProxy *proxy,
                                                         const char *action,
                                                         GUPnPServiceProxyActionCallback callback,
                                                         gpointer user_data,
                                                         va_list var_args);

See gupnp_service_proxy_begin_action(); this version takes a va_list for use by language bindings.

proxy :

 A GUPnPServiceProxy

action :

 An action

callback :

 The callback to call when sending the action has succeeded or failed

user_data :

 User data for callback

var_args :

 A va_list of tuples of in parameter name, in parameter type, and in parameter value

Returns :

 A GUPnPServiceProxyAction handle. This will be freed when calling gupnp_service_proxy_cancel_action() or gupnp_service_proxy_end_action_valist().

gupnp_service_proxy_begin_action_hash ()

GUPnPServiceProxyAction* gupnp_service_proxy_begin_action_hash
                                                        (GUPnPServiceProxy *proxy,
                                                         const char *action,
                                                         GUPnPServiceProxyActionCallback callback,
                                                         gpointer user_data,
                                                         GHashTable *hash);

See gupnp_service_proxy_begin_action(); this version takes a GHashTable for runtime generated parameter lists.

proxy :

 A GUPnPServiceProxy

action :

 An action

callback :

 The callback to call when sending the action has succeeded or failed

user_data :

 User data for callback

hash :

 A GHashTable of in parameter name and GValue pairs

Returns :

 A GUPnPServiceProxyAction handle. This will be freed when calling gupnp_service_proxy_cancel_action() or gupnp_service_proxy_end_action_hash().

gupnp_service_proxy_end_action ()

gboolean            gupnp_service_proxy_end_action      (GUPnPServiceProxy *proxy,
                                                         GUPnPServiceProxyAction *action,
                                                         GError **error,
                                                         ...);

Retrieves the result of action. The out parameters in Varargs will be filled in, and if an error occurred, error will be set. In case of a UPnPError the error code will be the same in error.

proxy :

 A GUPnPServiceProxy

action :

 A GUPnPServiceProxyAction handle

error :

 The location where to store any error, or NULL

... :

 tuples of out parameter name, out parameter type, and out parameter value location, terminated with NULL. The out parameter values should be freed after use

Returns :

 TRUE on success.

gupnp_service_proxy_end_action_valist ()

gboolean            gupnp_service_proxy_end_action_valist
                                                        (GUPnPServiceProxy *proxy,
                                                         GUPnPServiceProxyAction *action,
                                                         GError **error,
                                                         va_list var_args);

See gupnp_service_proxy_end_action(); this version takes a va_list for use by language bindings.

proxy :

 A GUPnPServiceProxy

action :

 A GUPnPServiceProxyAction handle

error :

 The location where to store any error, or NULL

var_args :

 A va_list of tuples of out parameter name, out parameter type, and out parameter value location. The out parameter values should be freed after use

Returns :

 TRUE on success.

gupnp_service_proxy_end_action_hash ()

gboolean            gupnp_service_proxy_end_action_hash (GUPnPServiceProxy *proxy,
                                                         GUPnPServiceProxyAction *action,
                                                         GError **error,
                                                         GHashTable *hash);

See gupnp_service_proxy_end_action(); this version takes a GHashTable for runtime generated parameter lists.

proxy :

 A GUPnPServiceProxy

action :

 A GUPnPServiceProxyAction handle

error :

 The location where to store any error, or NULL

hash :

 A GHashTable of out parameter name and initialised GValue pairs

Returns :

 TRUE on success.

gupnp_service_proxy_cancel_action ()

void                gupnp_service_proxy_cancel_action   (GUPnPServiceProxy *proxy,
                                                         GUPnPServiceProxyAction *action);

Cancels action, freeing the action handle.

proxy :

 A GUPnPServiceProxy

action :

 A GUPnPServiceProxyAction handle

gupnp_service_proxy_add_notify ()

gboolean            gupnp_service_proxy_add_notify      (GUPnPServiceProxy *proxy,
                                                         const char *variable,
                                                         GType type,
                                                         GUPnPServiceProxyNotifyCallback callback,
                                                         gpointer user_data);

Sets up callback to be called whenever a change notification for variable is recieved.

proxy :

 A GUPnPServiceProxy

variable :

 The variable to add notification for

type :

 The type of the variable

callback :

 The callback to call when variable changes

user_data :

 User data for callback

Returns :

 TRUE on success.

gupnp_service_proxy_remove_notify ()

gboolean            gupnp_service_proxy_remove_notify   (GUPnPServiceProxy *proxy,
                                                         const char *variable,
                                                         GUPnPServiceProxyNotifyCallback callback,
                                                         gpointer user_data);

Cancels the variable change notification for callback and user_data.

proxy :

 A GUPnPServiceProxy

variable :

 The variable to add notification for

callback :

 The callback to call when variable changes

user_data :

 User data for callback

Returns :

 TRUE on success.

gupnp_service_proxy_set_subscribed ()

void                gupnp_service_proxy_set_subscribed  (GUPnPServiceProxy *proxy,
                                                         gboolean subscribed);

(Un)subscribes to this service.

Note that the relevant messages are not immediately sent but queued. If you want to unsubcribe from this service because the application is quitting, rely on automatic synchronised unsubscription on object destruction instead.

proxy :

 A GUPnPServiceProxy

subscribed :

 TRUE to subscribe to this service

gupnp_service_proxy_get_subscribed ()

gboolean            gupnp_service_proxy_get_subscribed  (GUPnPServiceProxy *proxy);

Returns if we are subscribed to this service.

proxy :

 A GUPnPServiceProxy

Returns :

 TRUE if we are subscribed to this service, otherwise FALSE.

Property Details

The "subscribed" property

  "subscribed"               gboolean              : Read / Write

Whether we are subscribed to this service.

Default value: FALSE

Signal Details

The "subscription-lost" signal

void                user_function                      (GUPnPServiceProxy *proxy,
                                                        gpointer           error,
                                                        gpointer           user_data)      : Run Last

Emitted whenever the subscription to this service has been lost due to an error condition.

proxy :

 The GUPnPServiceProxy that received the signal

error :

 A pointer to a GError describing why the subscription has been lost

user_data :

 user data set when the signal handler was connected.
Generated by GTK-Doc V1.10