IBusPendingCall

## IBusPendingCall IBusPendingCall — A DBusPendingCall in IBus. |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    typedef             IBusPendingCall;
    void                (*IBusPendingCallNotifyFunction)    (IBusPendingCall *pending,
                                                             gpointer user_data);
    IBusPendingCall*    ibus_pending_call_ref               (IBusPendingCall *pending);
    void                ibus_pending_call_unref             (IBusPendingCall *pending);
    gboolean            ibus_pending_call_set_notify        (IBusPendingCall *pending,
                                                             IBusPendingCallNotifyFunction function,
                                                             gpointer user_data,
                                                             GDestroyNotify free_user_data);
    void                ibus_pending_call_cancel            (IBusPendingCall *pending);
    gboolean            ibus_pending_call_get_completed     (IBusPendingCall *pending);
    IBusMessage*        ibus_pending_call_steal_reply       (IBusPendingCall *pending);
    void                ibus_pending_call_block             (IBusPendingCall *pending);
    void                ibus_pending_call_wait              (IBusPendingCall *pending);
    gboolean            ibus_pending_call_allocate_data_slot
                                                            (gint *slot_p);
    void                ibus_pending_call_free_data_slot    (gint *slot_p);
    gboolean            ibus_pending_call_set_data          (IBusPendingCall *pending,
                                                             gint slot,
                                                             gpointer data,
                                                             GDestroyNotify free_data_func);
    gpointer            ibus_pending_call_get_data          (IBusPendingCall *pending,
                                                             gint slot);

## Description

An IBusPendingCall is essentially a DBusPendingCall, which representing an expected reply. A IBusPendingCall can be created when you send a message that should have a reply.

Besides DBusPendingCall functions, An IBusPendingCall can be manipulated with its own specific functions, which are defined in this section.

## Details

### IBusPendingCall

An opaque data structure that represents IBusPendingCall.

### IBusPendingCallNotifyFunction ()

    void                (*IBusPendingCallNotifyFunction)    (IBusPendingCall *pending,
                                                             gpointer user_data);

Callback prototype of pending call notify function.

`pending` : | An IBusPendingCall.
`user_data` : | User data for the callback function.

### ibus_pending_call_ref ()

    IBusPendingCall*    ibus_pending_call_ref               (IBusPendingCall *pending);

Increases the reference count on a pending call.

`pending` : | An IBusPendingCall.
Returns : | A reference of IBusPendingCall.

### ibus_pending_call_unref ()

    void                ibus_pending_call_unref             (IBusPendingCall *pending);

Decreases the reference count on a pending call.

`pending` : | An IBusPendingCall.

### ibus_pending_call_set_notify ()

    gboolean            ibus_pending_call_set_notify        (IBusPendingCall *pending,
                                                             IBusPendingCallNotifyFunction function,
                                                             gpointer user_data,
                                                             GDestroyNotify free_user_data);

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

`pending` : | An IBusPendingCall.
`function` : | An pending call notify callback function.
`user_data` : | User data for the callback function.
`free_user_data` : | Callback to free the user_data.
Returns : | TRUE if succeed; FALSE if not enough memory.

### ibus_pending_call_cancel ()

    void                ibus_pending_call_cancel            (IBusPendingCall *pending);

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

Drops the dbus library's internal reference to the DBusPendingCall so will free the call if nobody else is holding a reference. But usually application owns a reference from `dbus_connection_send_with_reply()`.

Note that canceling a pending call will not simulate a timed-out call; if a call times out, then a timeout error reply is received. If you cancel the call, no reply is received unless the reply was already received before you canceled.

`pending` : | An IBusPendingCall.

### ibus_pending_call_get_completed ()

    gboolean            ibus_pending_call_get_completed     (IBusPendingCall *pending);

Whether the pending call has received a reply or not.

`pending` : | An IBusPendingCall.
Returns : | TRUE if pending call has received a reply; FALSE otherwise.

### ibus_pending_call_steal_reply ()

    IBusMessage*        ibus_pending_call_steal_reply       (IBusPendingCall *pending);

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

Ownership of the reply message passes to the caller. This function can only be called once per pending call, since the reply message is transferred to the caller.

`pending` : | An IBusPendingCall.
Returns : | Replied message; NULL if none has been received yet.

### ibus_pending_call_block ()

    void                ibus_pending_call_block             (IBusPendingCall *pending);

Block until the pending call is completed. The blocking is as with `ibus_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.

`pending` : | An IBusPendingCall.

### ibus_pending_call_wait ()

    void                ibus_pending_call_wait              (IBusPendingCall *pending);

Wait until the pending call is completed.

See also: `ibus_pending_call_get_completed()`.

`pending` : | An IBusPendingCall.

### ibus_pending_call_allocate_data_slot ()

    gboolean            ibus_pending_call_allocate_data_slot
                                                            (gint *slot_p);

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

The allocated ID may then be used with `ibus_pending_call_set_data()` and `ibus_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 reference count is increased.

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

`slot_p` : | Address of a global variable storing the slot.
Returns : | TRUE if succeed; FALSE if insufficient memory.

### ibus_pending_call_free_data_slot ()

    void                ibus_pending_call_free_data_slot    (gint *slot_p);

Deallocates a global ID for IBusPendingCall data slots.

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

`slot_p` : | Address of a global variable storing the slot.

### ibus_pending_call_set_data ()

    gboolean            ibus_pending_call_set_data          (IBusPendingCall *pending,
                                                             gint slot,
                                                             gpointer data,
                                                             GDestroyNotify free_data_func);

Stores a pointer on a IBusPendingCall, 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 `ibus_pending_call_allocate_data_slot()`.

`pending` : | An IBusPendingCall.
`slot` : | The slot number.
`data` : | The data to store
`free_data_func` : | Callback to free the data.
Returns : | TRUE if there was enough memory to store the data; FALSE otherwise.

### ibus_pending_call_get_data ()

    gpointer            ibus_pending_call_get_data          (IBusPendingCall *pending,
                                                             gint slot);

Retrieves data previously set with `ibus_pending_call_set_data()`.

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

`pending` : | An IBusPendingCall.
`slot` : | The slot number.
Returns : | The stored data; NULL if no such data.