~ubuntu-branches/ubuntu/wily/telepathy-glib/wily

« back to all changes in this revision

Viewing changes to docs/reference/html/telepathy-glib-account-channel-request.html

  • Committer: Bazaar Package Importer
  • Author(s): Simon McVittie
  • Date: 2010-08-17 12:22:44 UTC
  • mfrom: (1.6.9 upstream)
  • mto: (35.1.6 maverick)
  • mto: This revision was merged to the branch mainline in revision 38.
  • Revision ID: james.westby@ubuntu.com-20100817122244-5mj9z00ss3bmibe7
Tags: 0.11.13-1
New upstream version (new API, ABI)

Show diffs side-by-side

added added

removed removed

Lines of Context:
147
147
<p>
148
148
Data structure representing a <a class="link" href="telepathy-glib-account-channel-request.html#TpAccountChannelRequest"><span class="type">TpAccountChannelRequest</span></a> object.
149
149
</p>
150
 
<p class="since">Since 0.11.UNRELEASED</p>
 
150
<p class="since">Since 0.11.12</p>
151
151
</div>
152
152
<hr>
153
153
<div class="refsect2" title="tp_account_channel_request_new ()">
170
170
<tr>
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>
174
174
</td>
175
175
</tr>
176
176
<tr>
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>)
180
182
</td>
181
183
</tr>
182
184
<tr>
187
189
</tr>
188
190
</tbody>
189
191
</table></div>
190
 
<p class="since">Since 0.11.UNRELEASED</p>
 
192
<p class="since">Since 0.11.12</p>
191
193
</div>
192
194
<hr>
193
195
<div class="refsect2" title="tp_account_channel_request_get_request ()">
212
214
</tr>
213
215
</tbody>
214
216
</table></div>
215
 
<p class="since">Since 0.11.UNRELEASED</p>
 
217
<p class="since">Since 0.11.12</p>
216
218
</div>
217
219
<hr>
218
220
<div class="refsect2" title="tp_account_channel_request_get_user_action_time ()">
238
240
</tr>
239
241
</tbody>
240
242
</table></div>
241
 
<p class="since">Since 0.11.UNRELEASED</p>
 
243
<p class="since">Since 0.11.12</p>
242
244
</div>
243
245
<hr>
244
246
<div class="refsect2" title="tp_account_channel_request_get_account ()">
263
265
</tr>
264
266
</tbody>
265
267
</table></div>
266
 
<p class="since">Since 0.11.UNRELEASED</p>
 
268
<p class="since">Since 0.11.12</p>
267
269
</div>
268
270
<hr>
269
271
<div class="refsect2" title="tp_account_channel_request_create_and_handle_channel_async ()">
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.
283
285
</p>
 
286
<p>
 
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>.)
 
290
</p>
284
291
<div class="variablelist"><table border="0">
285
292
<col align="left" valign="top">
286
293
<tbody>
306
313
</tr>
307
314
</tbody>
308
315
</table></div>
309
 
<p class="since">Since 0.11.UNRELEASED</p>
 
316
<p class="since">Since 0.11.12</p>
310
317
</div>
311
318
<hr>
312
319
<div class="refsect2" title="tp_account_channel_request_create_and_handle_channel_finish ()">
352
359
</tr>
353
360
</tbody>
354
361
</table></div>
355
 
<p class="since">Since 0.11.UNRELEASED</p>
 
362
<p class="since">Since 0.11.12</p>
356
363
</div>
357
364
<hr>
358
365
<div class="refsect2" title="tp_account_channel_request_ensure_and_handle_channel_async ()">
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.
 
388
</p>
 
389
<p>
 
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>.)
379
393
</p>
380
394
<div class="variablelist"><table border="0">
381
395
<col align="left" valign="top">
402
416
</tr>
403
417
</tbody>
404
418
</table></div>
405
 
<p class="since">Since 0.11.UNRELEASED</p>
 
419
<p class="since">Since 0.11.12</p>
406
420
</div>
407
421
<hr>
408
422
<div class="refsect2" title="tp_account_channel_request_ensure_and_handle_channel_finish ()">
453
467
</tr>
454
468
</tbody>
455
469
</table></div>
456
 
<p class="since">Since 0.11.UNRELEASED</p>
 
470
<p class="since">Since 0.11.12</p>
457
471
</div>
458
472
<hr>
459
473
<div class="refsect2" title="tp_account_channel_request_create_channel_async ()">
505
519
</tr>
506
520
</tbody>
507
521
</table></div>
508
 
<p class="since">Since 0.11.UNRELEASED</p>
 
522
<p class="since">Since 0.11.12</p>
509
523
</div>
510
524
<hr>
511
525
<div class="refsect2" title="tp_account_channel_request_create_channel_finish ()">
545
559
</tr>
546
560
</tbody>
547
561
</table></div>
548
 
<p class="since">Since 0.11.UNRELEASED</p>
 
562
<p class="since">Since 0.11.12</p>
549
563
</div>
550
564
<hr>
551
565
<div class="refsect2" title="tp_account_channel_request_ensure_channel_async ()">
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.
 
577
</p>
 
578
<p>
 
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
 
584
a handler.
 
585
</p>
 
586
<p>
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
565
589
has failed.
598
622
</tr>
599
623
</tbody>
600
624
</table></div>
601
 
<p class="since">Since 0.11.UNRELEASED</p>
 
625
<p class="since">Since 0.11.12</p>
602
626
</div>
603
627
<hr>
604
628
<div class="refsect2" title="tp_account_channel_request_ensure_channel_finish ()">
638
662
</tr>
639
663
</tbody>
640
664
</table></div>
641
 
<p class="since">Since 0.11.UNRELEASED</p>
 
665
<p class="since">Since 0.11.12</p>
642
666
</div>
643
667
</div>
644
668
<div class="refsect1" title="Property Details">
653
677
<p>
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>.
655
679
</p>
656
 
<p class="since">Since 0.11.UNRELEASED</p>
 
680
<p class="since">Since 0.11.12</p>
657
681
</div>
658
682
<hr>
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>
662
686
<p>
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>.
665
689
</p>
666
690
<p>
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>.
668
692
</p>
669
 
<p class="since">Since 0.11.UNRELEASED</p>
 
693
<p class="since">Since 0.11.12</p>
670
694
</div>
671
695
<hr>
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>
675
699
<p>
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.
678
702
</p>
 
703
<p>
 
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>.
 
707
</p>
 
708
<p>
 
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
 
711
channel.
 
712
</p>
 
713
<p>
 
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.
 
717
</p>
 
718
<p>
 
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.
 
722
</p>
 
723
<p>
 
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.
 
728
</p>
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>
681
731
</div>
682
732
</div>
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>
692
742
<p>
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".
 
744
</p>
 
745
<p>
 
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.
 
751
</p>
 
752
<p>
 
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.
694
755
</p>
695
756
<div class="variablelist"><table border="0">
696
757
<col align="left" valign="top">
707
768
</tr>
708
769
<tr>
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>
712
775
</td>
713
776
</tr>
714
777
<tr>
723
786
</tr>
724
787
</tbody>
725
788
</table></div>
726
 
<p class="since">Since 0.11.UNRELEASED</p>
 
789
<p class="since">Since 0.11.12</p>
727
790
</div>
728
791
</div>
729
792
</div>