![]() |
![]() |
![]() |
GUPnP Reference Manual | ![]() |
---|---|---|---|---|
GUPnPService; GUPnPServiceAction; const char* gupnp_service_action_get_name (GUPnPServiceAction *action); GList* gupnp_service_action_get_locales (GUPnPServiceAction *action); void gupnp_service_action_get (GUPnPServiceAction *action, ...); void gupnp_service_action_get_valist (GUPnPServiceAction *action, va_list var_args); void gupnp_service_action_get_value (GUPnPServiceAction *action, const char *argument, GValue *value); void gupnp_service_action_set (GUPnPServiceAction *action, ...); void gupnp_service_action_set_valist (GUPnPServiceAction *action, va_list var_args); void gupnp_service_action_set_value (GUPnPServiceAction *action, const char *argument, const GValue *value); void gupnp_service_action_return (GUPnPServiceAction *action); void gupnp_service_action_return_error (GUPnPServiceAction *action, guint error_code, const char *error_description); void gupnp_service_notify (GUPnPService *service, ...); void gupnp_service_notify_valist (GUPnPService *service, va_list var_args); void gupnp_service_notify_value (GUPnPService *service, const char *variable, const GValue *value); void gupnp_service_freeze_notify (GUPnPService *service); void gupnp_service_thaw_notify (GUPnPService *service); void gupnp_service_signals_autoconnect (GUPnPService *service, gpointer user_data, GError **error);
"action-invoked" : Run Last / Has Details "notify-failed" : Run Last "query-variable" : Run Last / Has Details
GUPnPService allows for handling incoming actions and state variable notification. GUPnPService implements the GUPnPServiceInfo interface.
typedef struct _GUPnPService GUPnPService;
This struct contains private data only, and should be accessed using the functions below.
typedef struct _GUPnPServiceAction GUPnPServiceAction;
Opaque structure for holding in-progress action data.
const char* gupnp_service_action_get_name (GUPnPServiceAction *action);
Get the name of action
.
action : |
A GUPnPServiceAction |
Returns : | The name of action
|
GList* gupnp_service_action_get_locales (GUPnPServiceAction *action);
Get an ordered (preferred first) GList of locales preferred by the client. Free list and elements after use.
action : |
A GUPnPServiceAction |
Returns : | A GList of char* locale names. |
void gupnp_service_action_get (GUPnPServiceAction *action, ...);
Retrieves the specified action arguments.
action : |
A GUPnPServiceAction |
... : |
tuples of argument name, argument type, and argument value
location, terminated with NULL .
|
void gupnp_service_action_get_valist (GUPnPServiceAction *action, va_list var_args);
See gupnp_service_action_get()
; this version takes a va_list for
use by language bindings.
action : |
A GUPnPServiceAction |
var_args : |
va_list of tuples of argument name, argument type, and argument value location. |
void gupnp_service_action_get_value (GUPnPServiceAction *action, const char *argument, GValue *value);
Retrieves the value of argument
into value
.
action : |
A GUPnPServiceAction |
argument : |
The name of the argument to retrieve |
value : |
The GValue to store the value of the argument, initialized to the correct type. |
void gupnp_service_action_set (GUPnPServiceAction *action, ...);
Sets the specified action return values.
action : |
A GUPnPServiceAction |
... : |
tuples of return value name, return value type, and
actual return value, terminated with NULL .
|
void gupnp_service_action_set_valist (GUPnPServiceAction *action, va_list var_args);
See gupnp_service_action_set()
; this version takes a va_list for
use by language bindings.
action : |
A GUPnPServiceAction |
var_args : |
va_list of tuples of return value name, return value type, and actual return value. |
void gupnp_service_action_set_value (GUPnPServiceAction *action, const char *argument, const GValue *value);
Sets the value of argument
to value
.
action : |
A GUPnPServiceAction |
argument : |
The name of the return value to retrieve |
value : |
The GValue to store the return value |
void gupnp_service_action_return (GUPnPServiceAction *action);
Return succesfully.
action : |
A GUPnPServiceAction |
void gupnp_service_action_return_error (GUPnPServiceAction *action, guint error_code, const char *error_description);
Return error_code
.
action : |
A GUPnPServiceAction |
error_code : |
The error code |
error_description : |
The error description, or NULL if error_code is
one of GUPNP_CONTROL_ERROR_INVALID_ACTION,
GUPNP_CONTROL_ERROR_INVALID_ARGS, GUPNP_CONTROL_ERROR_OUT_OF_SYNC or
GUPNP_CONTROL_ERROR_ACTION_FAILED, in which case a description is
provided automatically.
|
void gupnp_service_notify (GUPnPService *service, ...);
Notifies listening clients that the properties listed in Varargs
have changed to the specified values.
service : |
A GUPnPService |
... : |
Tuples of variable name, variable type, and variable value,
terminated with NULL .
|
void gupnp_service_notify_valist (GUPnPService *service, va_list var_args);
See gupnp_service_notify()
; this version takes a va_list for
use by language bindings.
service : |
A GUPnPService |
var_args : |
A va_list of tuples of variable name, variable type, and variable
value, terminated with NULL .
|
void gupnp_service_notify_value (GUPnPService *service, const char *variable, const GValue *value);
Notifies listening clients that variable
has changed to value
.
service : |
A GUPnPService |
variable : |
The name of the variable to notify |
value : |
The value of the variable |
void gupnp_service_freeze_notify (GUPnPService *service);
Causes new notifications to be queued up until gupnp_service_thaw_notify()
is called.
service : |
A GUPnPService |
void gupnp_service_thaw_notify (GUPnPService *service);
Sends out any pending notifications, and stops queuing of new ones.
service : |
A GUPnPService |
void gupnp_service_signals_autoconnect (GUPnPService *service, gpointer user_data, GError **error);
A convenience function that attempts to connect all possible
"action-invoked" and "query-variable" signals to
appropriate callbacks for the service service
. It uses service introspection
and GModule's introspective features. It is very simillar to
glade_xml_signal_autoconnect()
except that it attempts to guess the names of
the signal handlers on its own.
For this function to do its magic, the application must name the callback functions for "action-invoked" signals by striping the CamelCase off the action names and either prepend "on_" or append "_cb" to them. Same goes for "query-variable" signals, except that "query_" should be prepended to the variable name. For example, callback function for "GetSystemUpdateID" action should be either named as "get_system_update_id_cb" or "on_get_system_update_id" and callback function for the query of "SystemUpdateID" state variable should be named "query_system_update_id_cb" or "on_query_system_update_id".
Note that this function will not work correctly if GModule is not supported
on the platform or introspection is not available for service service
.
WARNING: This function can not and therefore does not guarantee that the resulting signal connections will be correct as it depends heavily on a particular naming schemes described above.
service : |
A GUPnPService |
user_data : |
the data to pass to each of the callbacks |
error : |
return location for a GError, or NULL
|
"root-device"
property"root-device" GUPnPRootDevice* : Read / Write / Construct Only
The containing GUPnPRootDevice.
"action-invoked"
signalvoid user_function (GUPnPService *service, GUPnPServiceAction *action, gpointer user_data) : Run Last / Has Details
Emitted whenever an action is invoked. Handler should process
action
and must call either gupnp_service_action_return()
or
gupnp_service_action_return_error()
.
service : |
The GUPnPService that received the signal |
action : |
The invoked GUPnPAction |
user_data : |
user data set when the signal handler was connected. |
"notify-failed"
signalvoid user_function (GUPnPService *service, gpointer callback_url, gpointer reason, gpointer user_data) : Run Last
Emitted whenever notification of a client fails.
service : |
The GUPnPService that received the signal |
callback_url : |
The callback URL |
reason : |
A pointer to a GError describing why the notify failed |
user_data : |
user data set when the signal handler was connected. |
"query-variable"
signalvoid user_function (GUPnPService *service, gchar *variable, gpointer value, gpointer user_data) : Run Last / Has Details
Emitted whenever service
needs to know the value of variable
.
Handler should fill value
with the value of variable
.
service : |
The GUPnPService that received the signal |
variable : |
The variable that is being queried |
value : |
The location of the GValue of the variable |
user_data : |
user data set when the signal handler was connected. |