Result

Result manipulation and error handlingEach command to the server will return a xmmsc_result_t to the programmer. More...

Modules
	ResultValueRetrieval
	Explains how you can retrive values from a xmmsc_result_t.

Macros
#define	GEN_RESULT_NOTIFIER_SET_FUNC(type)
#define	GEN_RESULT_NOTIFIER_SET_FULL_FUNC(type)

Functions
xmmsc_result_t *	xmmsc_result_ref (xmmsc_result_t *res)
	References the xmmsc_result_t. More...
xmmsc_result_type_t	xmmsc_result_get_class (xmmsc_result_t *res)
	Get the class of the result (default, signal, broadcast). More...
void	xmmsc_result_disconnect (xmmsc_result_t *res)
	Disconnect all notifiers for a signal or a broadcast result. More...
uint32_t	xmmsc_result_cookie_get (xmmsc_result_t *res)
	return the cookie of a resultset. More...
void	xmmsc_result_c2c_set (xmmsc_result_t *res)
	Set a result to be a client-to-client result. More...
void	xmmsc_result_visc_set (xmmsc_result_t *res, xmmsc_visualization_t *visc)
xmmsc_visualization_t *	xmmsc_result_visc_get (xmmsc_result_t *res)
xmmsc_connection_t *	xmmsc_result_get_connection (xmmsc_result_t *res)
void	xmmsc_result_unref (xmmsc_result_t *res)
	Decreases the references for the xmmsc_result_t When the number of references reaches 0 it will be freed. More...
void	xmmsc_result_wait (xmmsc_result_t *res)
	Set up a default callback for the result retrieval. More...

Detailed Description

Result manipulation and error handling

Each command to the server will return a xmmsc_result_t to the programmer.

This object will be used to see the results off the call. It will handle errors and the results.

results could be used in both sync and async fashions. Here is a sync example:

xmmsc_result_t *res;
xmmsv_t *val;
uint32_t id;
res = xmmsc_playback_get_current_id (connection);
xmmsc_result_wait (res);
if (!val = xmmsc_result_get_value (res)) {
  printf ("error: failed to retrieve value!");
}
if (xmmsv_is_error (val)) {
  printf ("error: %s", xmmsv_get_error (val));
}
xmmsv_get_uint (val, &id);
xmmsc_result_unref (res);
printf ("current id is: %d", id);

an async example is a bit more complex...

static void handler (xmmsv_t *val, void *userdata) {
  uint32_t id;
  if (xmmsv_is_error (val)) {
     printf ("error: %s", xmmsv_get_error (val));
  }
  xmmsv_get_uint (val, &id);
  printf ("current id is: %d", id);
}

int main () {
  // Connect blah blah ...
  xmmsc_result_t *res;
  res = xmmsc_playback_get_current_id (connection);
  xmmsc_result_notifier_set (res, handler);
  xmmsc_result_unref (res);
}

When the answer arrives handler will be called. with the resulting xmmsv_t

Macro Definition Documentation

#define GEN_RESULT_NOTIFIER_SET_FULL_FUNC

(

type

)

Value:

void \
xmmsc_result_notifier_set_##type##_full (xmmsc_result_t *res, \
                                         xmmsc_result_notifier_t func, \
                                         void *user_data, \
                                         xmmsc_user_data_free_func_t free_func) \
{ \
	xmmsc_result_callback_t *cb; \
\
    x_return_if_fail (res); \
    x_return_if_fail (func); \
\
    cb = xmmsc_result_callback_new_##type (func, user_data, free_func); \
    xmmsc_result_notifier_add (res, cb); \
}

#define GEN_RESULT_NOTIFIER_SET_FUNC

(

type

)

Value:

void \
xmmsc_result_notifier_set_##type (xmmsc_result_t *res, \
                                  xmmsc_result_notifier_t func, \
                                  void *user_data) \
{ \
    xmmsc_result_notifier_set_##type##_full (res, func, user_data, NULL); \
}

Function Documentation

void xmmsc_result_c2c_set

(

xmmsc_result_t *

res

)

Set a result to be a client-to-client result.

Referenced by xmmsc_broadcast_c2c_message(), xmmsc_c2c_reply(), and xmmsc_c2c_send().

uint32_t xmmsc_result_cookie_get

(

xmmsc_result_t *

res

)

return the cookie of a resultset.

Referenced by xmmsc_ipc_result_lookup(), and xmmsc_ipc_result_unregister().

void xmmsc_result_disconnect

(

xmmsc_result_t *

res

)

Disconnect all notifiers for a signal or a broadcast result.

Parameters

res	The result to disconnect, must be of class signal or broadcast.

xmmsc_result_type_t xmmsc_result_get_class

(

xmmsc_result_t *

res

)

Get the class of the result (default, signal, broadcast).

Returns

The class of the result of type xmmsc_result_type_t

xmmsc_connection_t* xmmsc_result_get_connection

(

xmmsc_result_t *

res

)

Referenced by setup_udp_handle().

xmmsc_result_t* xmmsc_result_ref

(

xmmsc_result_t *

res

)

References the xmmsc_result_t.

Parameters

result

the result to reference.

Returns

result

Referenced by xmmsc_result_new(), and xmmsc_result_run().

void xmmsc_result_unref

(

xmmsc_result_t *

res

)

Decreases the references for the xmmsc_result_t When the number of references reaches 0 it will be freed.

And thus all data you extracted from it will be deallocated.

Referenced by xmmsc_connect(), xmmsc_result_run(), xmmsc_sc_broadcast_emit(), and xmmsc_sc_init().

xmmsc_visualization_t* xmmsc_result_visc_get

(

xmmsc_result_t *

res

)

Referenced by setup_shm_handle(), setup_udp_handle(), xmmsc_visualization_init_handle(), and xmmsc_visualization_start_handle().

void xmmsc_result_visc_set	(	xmmsc_result_t *	res,
		xmmsc_visualization_t *	visc
	)

Referenced by setup_shm_prepare(), setup_udp_prepare(), and xmmsc_visualization_init().

void xmmsc_result_wait

(

xmmsc_result_t *

res

)

Set up a default callback for the result retrieval.

This callback will be called when the answer arrives. The callback receives the value as sent by the server or another client, that is, for c2c messages only the payload is passed to the callback.

Parameters

res	a xmmsc_result_t that you got from a command dispatcher.
func	the function that should be called when we receive the answer
user_data	optional user data to the callback Set up a default callback for the result retrieval. This callback will be called when the answer arrives. This function differs from xmmsc_result_default_notifier_set in the additional free_func parameter, which allows to pass a pointer to a function which will be called to free the user_data when needed.
res	a xmmsc_result_t that you got from a command dispatcher.
func	the function that should be called when we receive the answer
user_data	optional user data to the callback
free_func	optional function that should be called to free the user_data Set up a raw callback for the result retrieval. This callback will be called when the answer arrives. The client receives the value sent by the server or, for client-to-client messages, the full message, whose fields can be extracted with the appropriate functions.
res	a xmmsc_result_t that you got from a command dispatcher.
func	the function that should be called when we receive the answer
user_data	optional user data to the callback

See Also

xmmsv_c2c_message_get_payload and others. Set up a raw callback for the result retrieval. This callback will be called when the answer arrives. This function differs from xmmsc_result_raw_notifier_set in the additional free_func parameter, which allows to pass a pointer to a function which will be called to free the user_data when needed.

Parameters

res	a xmmsc_result_t that you got from a command dispatcher.
func	the function that should be called when we receive the answer
user_data	optional user data to the callback
free_func	optional function that should be called to free the user_data Set up a c2c callback for the result retrieval. This callback will be called when the answer arrives. This callback always receives values formatted as client-to-client messages, whose fields can be extracted with the appropriate functions. For values sent by the server, the sender id and message id fields will be zero.
res	a xmmsc_result_t that you got from a command dispatcher.
func	the function that should be called when we receive the answer
user_data	optional user data to the callback

See Also

xmmsv_c2c_message_get_payload and others. Set up a c2c callback for the result retrieval. This callback will be called when the answer arrives. This function differs from xmmsc_result_c2c_notifier_set in the additional free_func parameter, which allows to pass a pointer to a function which will be called to free the user_data when needed.

Parameters

res	a xmmsc_result_t that you got from a command dispatcher.
func	the function that should be called when we receive the answer
user_data	optional user data to the callback
free_func	optional function that should be called to free the user_data Block for the reply. In a synchronous application this can be used to wait for the result. Will return when the server replyed.

Referenced by xmmsc_connect().