Main Page   Modules   Data Structures   File List   Data Fields   Related Pages  

DBusPendingCall
[D-BUS message system public API]

Pending reply to a method call message. More...

Typedefs

typedef DBusPendingCall DBusPendingCall
 Opaque data type representing a message pending.


Functions

DBusPendingCall * dbus_pending_call_ref (DBusPendingCall *pending)
 Increments the reference count on a pending call. More...

void dbus_pending_call_unref (DBusPendingCall *pending)
 Decrements the reference count on a pending call, freeing it if the count reaches 0. More...

dbus_bool_t dbus_pending_call_set_notify (DBusPendingCall *pending, DBusPendingCallNotifyFunction function, void *user_data, DBusFreeFunction free_user_data)
 Sets a notification function to be called when the reply is received or the pending call times out. More...

void dbus_pending_call_cancel (DBusPendingCall *pending)
 Cancels the pending call, such that any reply or error received will just be ignored. More...

dbus_bool_t dbus_pending_call_get_completed (DBusPendingCall *pending)
 Checks whether the pending call has received a reply yet, or not. More...

DBusMessagedbus_pending_call_get_reply (DBusPendingCall *pending)
 Gets the reply, or returns NULL if none has been received yet. More...

void dbus_pending_call_block (DBusPendingCall *pending)
 Block until the pending call is completed. More...

dbus_bool_t dbus_pending_call_allocate_data_slot (dbus_int32_t *slot_p)
 Allocates an integer ID to be used for storing application-specific data on any DBusPendingCall. More...

void dbus_pending_call_free_data_slot (dbus_int32_t *slot_p)
 Deallocates a global ID for DBusPendingCall data slots. More...

dbus_bool_t dbus_pending_call_set_data (DBusPendingCall *pending, dbus_int32_t slot, void *data, DBusFreeFunction free_data_func)
 Stores a pointer on a DBusPendingCall, along with an optional function to be used for freeing the data when the data is set again, or when the pending call is finalized. More...

void * dbus_pending_call_get_data (DBusPendingCall *pending, dbus_int32_t slot)
 Retrieves data previously set with dbus_pending_call_set_data(). More...


Detailed Description

Pending reply to a method call message.

A DBusPendingCall is an object representing an expected reply. A DBusPendingCall can be created when you send a message that should have a reply.


Function Documentation

dbus_bool_t dbus_pending_call_allocate_data_slot dbus_int32_t   slot_p
 

Allocates an integer ID to be used for storing application-specific data on any DBusPendingCall.

The allocated ID may then be used with dbus_pending_call_set_data() and dbus_pending_call_get_data(). The passed-in slot must be initialized to -1, and is filled in with the slot ID. If the passed-in slot is not -1, it's assumed to be already allocated, and its refcount is incremented.

The allocated slot is global, i.e. all DBusPendingCall objects will have a slot with the given integer ID reserved.

Parameters:
slot_p  address of a global variable storing the slot
Returns:
FALSE on failure (no memory)

Definition at line 329 of file dbus-pending-call.c.

void dbus_pending_call_block DBusPendingCall   pending
 

Block until the pending call is completed.

The blocking is as with dbus_connection_send_with_reply_and_block(); it does not enter the main loop or process other messages, it simply waits for the reply in question.

If the pending call is already completed, this function returns immediately.

Todo:
when you start blocking, the timeout is reset, but it should really only use time remaining since the pending call was created.
Parameters:
pending  the pending call

Definition at line 293 of file dbus-pending-call.c.

References connection, reply_serial, and timeout.

void dbus_pending_call_cancel DBusPendingCall   pending
 

Cancels the pending call, such that any reply or error received will just be ignored.

Drops at least one reference to the DBusPendingCall so will free the call if nobody else is holding a reference.

Parameters:
pending  the pending call

Definition at line 239 of file dbus-pending-call.c.

References connection.

void dbus_pending_call_free_data_slot dbus_int32_t   slot_p
 

Deallocates a global ID for DBusPendingCall data slots.

dbus_pending_call_get_data() and dbus_pending_call_set_data() may no longer be used with this slot. Existing data stored on existing DBusPendingCall objects will be freed when the DBusPendingCall is finalized, but may not be retrieved (and may only be replaced if someone else reallocates the slot). When the refcount on the passed-in slot reaches 0, it is set to -1.

Parameters:
slot_p  address storing the slot to deallocate

Definition at line 348 of file dbus-pending-call.c.

dbus_bool_t dbus_pending_call_get_completed DBusPendingCall   pending
 

Checks whether the pending call has received a reply yet, or not.

Todo:
not thread safe? I guess it has to lock though it sucks
Parameters:
pending  the pending call
Returns:
TRUE if a reply has been received

Definition at line 255 of file dbus-pending-call.c.

References completed.

void* dbus_pending_call_get_data DBusPendingCall   pending,
dbus_int32_t    slot
 

Retrieves data previously set with dbus_pending_call_set_data().

The slot must still be allocated (must not have been freed).

Parameters:
pending  the pending_call
slot  the slot to get data from
Returns:
the data, or NULL if not found

Definition at line 404 of file dbus-pending-call.c.

References slot_list.

DBusMessage* dbus_pending_call_get_reply DBusPendingCall   pending
 

Gets the reply, or returns NULL if none has been received yet.

The reference count is not incremented on the returned message, so you have to keep a reference count on the pending call (or add one to the message).

Todo:
not thread safe? I guess it has to lock though it sucks

maybe to make this threadsafe, it should be steal_reply(), i.e. only one thread can ever get the message

Parameters:
pending  the pending call
Returns:
the reply message or NULL.

Definition at line 273 of file dbus-pending-call.c.

References reply.

DBusPendingCall* dbus_pending_call_ref DBusPendingCall   pending
 

Increments the reference count on a pending call.

Parameters:
pending  the pending call object
Returns:
the pending call object

Definition at line 144 of file dbus-pending-call.c.

References refcount.

dbus_bool_t dbus_pending_call_set_data DBusPendingCall   pending,
dbus_int32_t    slot,
void *    data,
DBusFreeFunction    free_data_func
 

Stores a pointer on a DBusPendingCall, along with an optional function to be used for freeing the data when the data is set again, or when the pending call is finalized.

The slot number must have been allocated with dbus_pending_call_allocate_data_slot().

Parameters:
pending  the pending_call
slot  the slot number
data  the data to store
free_data_func  finalizer function for the data
Returns:
TRUE if there was enough memory to store the data

Definition at line 369 of file dbus-pending-call.c.

References slot_list.

dbus_bool_t dbus_pending_call_set_notify DBusPendingCall   pending,
DBusPendingCallNotifyFunction    function,
void *    user_data,
DBusFreeFunction    free_user_data
 

Sets a notification function to be called when the reply is received or the pending call times out.

Parameters:
pending  the pending call
function  notifier function
user_data  data to pass to notifier function
free_user_data  function to free the user data
Returns:
FALSE if not enough memory

Definition at line 212 of file dbus-pending-call.c.

References function.

void dbus_pending_call_unref DBusPendingCall   pending
 

Decrements the reference count on a pending call, freeing it if the count reaches 0.

Parameters:
pending  the pending call object

Definition at line 160 of file dbus-pending-call.c.

References connection, DBusList::data, refcount, reply, slot_list, timeout, timeout_added, and timeout_link.


Generated on Wed Jun 9 05:01:28 2004 for D-BUS by doxygen1.2.15