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

Data structure representing a <a class="link" href="telepathy-glib-account-channel-request.html#TpAccountChannelRequest"><span class="type">TpAccountChannelRequest</span></a> object.

149

</p>

150

<p class="since">Since 0.11.UNRELEASED</p>

150

<p class="since">Since 0.11.12</p>

151

</div>

152

<hr>

153

170

<tr>

171

<td><p><span class="term"><em class="parameter"><code>request</code></em> :</span></p></td>

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

</td>

175

</tr>

176

<tr>

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

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

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

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

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

285

292

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

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

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

381

395

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

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

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

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

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

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

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

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

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

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

696

757

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>

Older »