171
171
<td><p><span class="term"><em class="parameter"><code>request</code></em> :</span></p></td>
172
172
<td> the requested
173
properties of the channel. <span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>][<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> utf8 GObject.Value]</span>
173
properties of the channel (see <a class="link" href="telepathy-glib-account-channel-request.html#TpAccountChannelRequest--request" title='The "request" property'><span class="type">"request"</span></a>). <span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>][<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> utf8 GObject.Value]</span>
177
177
<td><p><span class="term"><em class="parameter"><code>user_action_time</code></em> :</span></p></td>
178
<td>the user action time to pass to the channel dispatcher
179
when requesting the channel
178
<td>the time of the user action that caused this request,
179
or one of the special values <a class="link" href="telepathy-glib-defs.html#TP-USER-ACTION-TIME-NOT-USER-ACTION:CAPS" title="TP_USER_ACTION_TIME_NOT_USER_ACTION"><code class="literal">TP_USER_ACTION_TIME_NOT_USER_ACTION</code></a> or
180
<a class="link" href="telepathy-glib-defs.html#TP-USER-ACTION-TIME-CURRENT-TIME:CAPS" title="TP_USER_ACTION_TIME_CURRENT_TIME"><code class="literal">TP_USER_ACTION_TIME_CURRENT_TIME</code></a> (see
181
<a class="link" href="telepathy-glib-account-channel-request.html#TpAccountChannelRequest--user-action-time" title='The "user-action-time" property'><span class="type">"user-action-time"</span></a>)
281
283
<a class="link" href="telepathy-glib-account-channel-request.html#tp-account-channel-request-create-and-handle-channel-finish" title="tp_account_channel_request_create_and_handle_channel_finish ()"><code class="function">tp_account_channel_request_create_and_handle_channel_finish()</code></a> to get the
282
284
result of the operation.
287
(Behind the scenes, this works by creating a temporary <a class="link" href="telepathy-glib-base-client.html#TpBaseClient"><span class="type">TpBaseClient</span></a>, then
288
acting like <a class="link" href="telepathy-glib-account-channel-request.html#tp-account-channel-request-create-channel-async" title="tp_account_channel_request_create_channel_async ()"><code class="function">tp_account_channel_request_create_channel_async()</code></a> with the
289
temporary <a class="link" href="telepathy-glib-base-client.html#TpBaseClient"><span class="type">TpBaseClient</span></a> as the <em class="parameter"><code>preferred_handler</code></em>.)
284
291
<div class="variablelist"><table border="0">
285
292
<col align="left" valign="top">
374
381
If the channel already exists and is already being handled, or if a
375
382
newly created channel is sent to a different handler, this operation
376
383
will fail with the error <a class="link" href="telepathy-glib-errors.html#TP-ERROR-NOT-YOURS:CAPS"><code class="literal">TP_ERROR_NOT_YOURS</code></a>. The other handler
377
will be notified that the channel was requested again, and can
378
move its window to the foreground, if applicable.
384
will be notified that the channel was requested again (for instance
385
with <a class="link" href="telepathy-glib-account-channel-request.html#TpAccountChannelRequest-re-handled" title='The "re-handled" signal'><span class="type">"re-handled"</span></a>,
386
<a class="link" href="telepathy-glib-base-client.html#TpBaseClientClassHandleChannelsImpl" title="TpBaseClientClassHandleChannelsImpl ()"><span class="type">TpBaseClientClassHandleChannelsImpl</span></a> or <a class="link" href="telepathy-glib-simple-handler.html#TpSimpleHandler--callback" title='The "callback" property'><span class="type">"callback"</span></a>),
387
and can move its window to the foreground, if applicable.
390
(Behind the scenes, this works by creating a temporary <a class="link" href="telepathy-glib-base-client.html#TpBaseClient"><span class="type">TpBaseClient</span></a>, then
391
acting like <a class="link" href="telepathy-glib-account-channel-request.html#tp-account-channel-request-ensure-channel-async" title="tp_account_channel_request_ensure_channel_async ()"><code class="function">tp_account_channel_request_ensure_channel_async()</code></a> with the
392
temporary <a class="link" href="telepathy-glib-base-client.html#TpBaseClient"><span class="type">TpBaseClient</span></a> as the <em class="parameter"><code>preferred_handler</code></em>.)
380
394
<div class="variablelist"><table border="0">
381
395
<col align="left" valign="top">
560
574
Asynchronously calls EnsureChannel on the ChannelDispatcher to create a
561
575
channel with the properties defined in <a class="link" href="telepathy-glib-account-channel-request.html#TpAccountChannelRequest--request" title='The "request" property'><span class="type">"request"</span></a>
562
576
and let the ChannelDispatcher dispatch it to an handler.
579
If a suitable channel already existed, its handler will be notified that
580
the channel was requested again (for instance with
581
<a class="link" href="telepathy-glib-account-channel-request.html#TpAccountChannelRequest-re-handled" title='The "re-handled" signal'><span class="type">"re-handled"</span></a>, <a class="link" href="telepathy-glib-base-client.html#TpBaseClientClassHandleChannelsImpl" title="TpBaseClientClassHandleChannelsImpl ()"><span class="type">TpBaseClientClassHandleChannelsImpl</span></a>
582
or <a class="link" href="telepathy-glib-simple-handler.html#TpSimpleHandler--callback" title='The "callback" property'><span class="type">"callback"</span></a>), and can move its window to the foreground,
583
if applicable. Otherwise, a new channel will be created and dispatched to
563
587
<em class="parameter"><code>callback</code></em> will be called when an existing channel's handler has been
564
588
notified, a new channel has been created and dispatched, or the request
654
678
This property can't be <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.
656
<p class="since">Since 0.11.UNRELEASED</p>
680
<p class="since">Since 0.11.12</p>
659
683
<div class="refsect2" title='The "request" property'>
660
684
<a name="TpAccountChannelRequest--request"></a><h3>The <code class="literal">"request"</code> property</h3>
661
685
<pre class="programlisting"> "request" <span class="type">GHashTable_gchararray+GValue_*</span> : Read / Write / Construct Only</pre>
663
The <a class="link" href="telepathy-glib-account.html#TpAccount"><span class="type">TpAccount</span></a> used to request the channel.
664
Read-only except during construction.
687
The desired D-Bus properties for the channel, represented as a
688
<a href="http://library.gnome.org/devel/glib/unstable/glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> where the keys are strings and the values are <a href="http://library.gnome.org/devel/gobject/unstable/gobject-Generic-values.html#GValue"><span class="type">GValue</span></a>.
667
691
This property can't be <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.
669
<p class="since">Since 0.11.UNRELEASED</p>
693
<p class="since">Since 0.11.12</p>
672
696
<div class="refsect2" title='The "user-action-time" property'>
673
697
<a name="TpAccountChannelRequest--user-action-time"></a><h3>The <code class="literal">"user-action-time"</code> property</h3>
674
698
<pre class="programlisting"> "user-action-time" <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gint64"><span class="type">gint64</span></a> : Read / Write / Construct Only</pre>
676
The user action time that will be passed to mission-control when
700
The user action time that will be passed to the channel dispatcher when
677
701
requesting the channel.
704
This may be the time at which user action occurred, or one of the special
705
values <a class="link" href="telepathy-glib-defs.html#TP-USER-ACTION-TIME-NOT-USER-ACTION:CAPS" title="TP_USER_ACTION_TIME_NOT_USER_ACTION"><code class="literal">TP_USER_ACTION_TIME_NOT_USER_ACTION</code></a> or
706
<a class="link" href="telepathy-glib-defs.html#TP-USER-ACTION-TIME-CURRENT-TIME:CAPS" title="TP_USER_ACTION_TIME_CURRENT_TIME"><code class="literal">TP_USER_ACTION_TIME_CURRENT_TIME</code></a>.
709
If <a class="link" href="telepathy-glib-defs.html#TP-USER-ACTION-TIME-NOT-USER-ACTION:CAPS" title="TP_USER_ACTION_TIME_NOT_USER_ACTION"><code class="literal">TP_USER_ACTION_TIME_NOT_USER_ACTION</code></a>, the action doesn't involve any
710
user action. Clients should avoid stealing focus when presenting the
714
If <a class="link" href="telepathy-glib-defs.html#TP-USER-ACTION-TIME-CURRENT-TIME:CAPS" title="TP_USER_ACTION_TIME_CURRENT_TIME"><code class="literal">TP_USER_ACTION_TIME_CURRENT_TIME</code></a>, clients SHOULD behave as though the
715
user action happened at the current time, e.g. a client may
716
request that its window gains focus.
719
On X11-based systems, Gdk 2.x, Clutter 1.0 etc.,
720
<a class="link" href="telepathy-glib-util.html#tp-user-action-time-from-x11" title="tp_user_action_time_from_x11 ()"><code class="function">tp_user_action_time_from_x11()</code></a> can be used to convert an X11 timestamp to
721
a Telepathy user action time.
724
If the channel request succeeds, this user action time will be passed on
725
to the channel's handler. If the handler is a GUI, it may use
726
<a class="link" href="telepathy-glib-util.html#tp-user-action-time-should-present" title="tp_user_action_time_should_present ()"><code class="function">tp_user_action_time_should_present()</code></a> to decide whether to bring its
727
window to the foreground.
679
729
<p>Default value: 0</p>
680
<p class="since">Since 0.11.UNRELEASED</p>
730
<p class="since">Since 0.11.12</p>
683
733
<div class="refsect1" title="Signal Details">
690
740
<a class="link" href="telepathy-glib-handle-channels-context.html#TpHandleChannelsContext"><span class="type">TpHandleChannelsContext</span></a> *context,
691
741
<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data) : Run Last / Has Details</pre>
693
Emitted when channel which has been created using <em class="parameter"><code>self</code></em> has be re-handled.
743
Emitted when the channel created using <em class="parameter"><code>self</code></em> has been "re-handled".
746
This means that a Telepathy client has made another request for a
747
matching channel using an "ensure" API like
748
<a class="link" href="telepathy-glib-account-channel-request.html#tp-account-channel-request-ensure-channel-async" title="tp_account_channel_request_ensure_channel_async ()"><code class="function">tp_account_channel_request_ensure_channel_async()</code></a>, while the channel
749
still exists. Instead of creating a new channel, the channel dispatcher
750
notifies the existing handler of <em class="parameter"><code>channel</code></em>, resulting in this signal.
753
Most GUI handlers should respond to this signal by checking
754
<em class="parameter"><code>user_action_time</code></em>, and if appropriate, moving to the foreground.
695
756
<div class="variablelist"><table border="0">
696
757
<col align="left" valign="top">
709
770
<td><p><span class="term"><em class="parameter"><code>user_action_time</code></em> :</span></p></td>
710
<td>the time at which user action occurred, or 0 if this
711
channel is to be handled for some reason not involving user action.
771
<td>the time at which user action occurred, or one of the
772
special values <a class="link" href="telepathy-glib-defs.html#TP-USER-ACTION-TIME-NOT-USER-ACTION:CAPS" title="TP_USER_ACTION_TIME_NOT_USER_ACTION"><code class="literal">TP_USER_ACTION_TIME_NOT_USER_ACTION</code></a> or
773
<a class="link" href="telepathy-glib-defs.html#TP-USER-ACTION-TIME-CURRENT-TIME:CAPS" title="TP_USER_ACTION_TIME_CURRENT_TIME"><code class="literal">TP_USER_ACTION_TIME_CURRENT_TIME</code></a>; see
774
<a class="link" href="telepathy-glib-account-channel-request.html#TpAccountChannelRequest--user-action-time" title='The "user-action-time" property'><span class="type">"user-action-time"</span></a>