43
* An opaque data structure that represents IBusPendingCall.
29
45
typedef DBusPendingCall IBusPendingCall;
48
* IBusPendingCallNotifyFunction:
49
* @pending: An IBusPendingCall.
50
* @user_data: User data for the callback function.
52
* Callback prototype of pending call notify function.
30
54
typedef void (* IBusPendingCallNotifyFunction)(IBusPendingCall *pending, gpointer user_data);
57
* ibus_pending_call_ref:
58
* @pending: An IBusPendingCall.
59
* @returns: A reference of IBusPendingCall.
61
* Increases the reference count on a pending call.
33
63
IBusPendingCall* ibus_pending_call_ref (IBusPendingCall *pending);
66
* ibus_pending_call_unref:
67
* @pending: An IBusPendingCall.
69
* Decreases the reference count on a pending call.
34
71
void ibus_pending_call_unref (IBusPendingCall *pending);
74
* ibus_pending_call_set_notify:
75
* @pending: An IBusPendingCall.
76
* @function: An pending call notify callback function.
77
* @user_data: User data for the callback function.
78
* @free_user_data: Callback to free the user_data.
79
* @returns: TRUE if succeed; FALSE if not enough memory.
81
* Sets a notification function to be called when the reply is received or the pending call times out.
35
83
gboolean ibus_pending_call_set_notify (IBusPendingCall *pending,
36
84
IBusPendingCallNotifyFunction function,
37
85
gpointer user_data,
38
86
GDestroyNotify free_user_data);
89
* ibus_pending_call_cancel:
90
* @pending: An IBusPendingCall.
92
* Cancels the pending call, such that any reply or error received will just be ignored.
94
* Drops the dbus library's internal reference to the DBusPendingCall so will free the call
95
* if nobody else is holding a reference.
96
* But usually application owns a reference from dbus_connection_send_with_reply().
98
* Note that canceling a pending call will not simulate a timed-out call;
99
* if a call times out, then a timeout error reply is received.
100
* If you cancel the call, no reply is received unless the reply was already received before you canceled.
39
102
void ibus_pending_call_cancel (IBusPendingCall *pending);
105
* ibus_pending_call_get_completed:
106
* @pending: An IBusPendingCall.
107
* @returns: TRUE if pending call has received a reply; FALSE otherwise.
109
* Whether the pending call has received a reply or not.
40
111
gboolean ibus_pending_call_get_completed (IBusPendingCall *pending);
114
* ibus_pending_call_steal_reply:
115
* @pending: An IBusPendingCall.
116
* @returns: Replied message; NULL if none has been received yet.
118
* Gets the reply, or returns NULL if none has been received yet.
120
* Ownership of the reply message passes to the caller.
121
* This function can only be called once per pending call,
122
* since the reply message is transferred to the caller.
41
124
IBusMessage* ibus_pending_call_steal_reply (IBusPendingCall *pending);
127
* ibus_pending_call_block:
128
* @pending: An IBusPendingCall.
130
* Block until the pending call is completed.
131
* The blocking is as with ibus_connection_send_with_reply_and_block();
132
* it does not enter the main loop or process other messages,
133
* it simply waits for the reply in question.
135
* If the pending call is already completed, this function returns immediately.
42
137
void ibus_pending_call_block (IBusPendingCall *pending);
140
* ibus_pending_call_wait:
141
* @pending: An IBusPendingCall.
143
* Wait until the pending call is completed.
145
* See also: ibus_pending_call_get_completed().
43
147
void ibus_pending_call_wait (IBusPendingCall *pending);
150
* ibus_pending_call_allocate_data_slot:
151
* @slot_p: Address of a global variable storing the slot.
152
* @returns: TRUE if succeed; FALSE if insufficient memory.
154
* Allocates an integer ID to be used for storing application-specific data on any IBusPendingCall.
156
* The allocated ID may then be used with ibus_pending_call_set_data() and ibus_pending_call_get_data().
157
* The passed-in slot must be initialized to -1, and is filled in with the slot ID.
158
* If the passed-in slot is not -1, it's assumed to be already allocated, and
159
* its reference count is increased.
161
* The allocated slot is global, i.e. all DBusPendingCall objects
162
* will have a slot with the given integer ID reserved.
44
164
gboolean ibus_pending_call_allocate_data_slot
168
* ibus_pending_call_free_data_slot:
169
* @slot_p: Address of a global variable storing the slot.
171
* Deallocates a global ID for IBusPendingCall data slots.
173
* ibus_pending_call_get_data() and ibus_pending_call_set_data() may no longer be used with this slot.
174
* Existing data stored on existing IBusPendingCall objects will be freed when
175
* the IBusPendingCall is finalized, but may not be retrieved
176
* (and may only be replaced if someone else reallocates the slot).
177
* When the reference count on the passed-in slot reaches 0, it is set to -1.
46
179
void ibus_pending_call_free_data_slot
183
* ibus_pending_call_set_data:
184
* @pending: An IBusPendingCall.
185
* @slot: The slot number.
186
* @data: The data to store
187
* @free_data_func: Callback to free the data.
188
* @returns: TRUE if there was enough memory to store the data; FALSE otherwise.
190
* Stores a pointer on a IBusPendingCall, along with an optional function
191
* to be used for freeing the data when the data is set again, or when the pending call is finalized.
193
* The slot number must have been allocated with ibus_pending_call_allocate_data_slot().
48
195
gboolean ibus_pending_call_set_data (IBusPendingCall *pending,
51
198
GDestroyNotify free_data_func);
201
* ibus_pending_call_get_data:
202
* @pending: An IBusPendingCall.
203
* @slot: The slot number.
204
* @returns: The stored data; NULL if no such data.
206
* Retrieves data previously set with ibus_pending_call_set_data().
208
* The slot must still be allocated (must not have been freed).
52
210
gpointer ibus_pending_call_get_data (IBusPendingCall *pending,