telepathy-glib: tp_account_channel_request_new_audio_call, audio_video_call : add
Simon McVittie
smcv at kemper.freedesktop.org
Mon Apr 30 11:57:29 PDT 2012
Module: telepathy-glib
Branch: master
Commit: 1079b72a6d0899115e9a33ea4a6ef7182330b913
URL: http://cgit.freedesktop.org/telepathy/telepathy-glib/commit/?id=1079b72a6d0899115e9a33ea4a6ef7182330b913
Author: Simon McVittie <simon.mcvittie at collabora.co.uk>
Date: Mon Apr 16 19:35:37 2012 +0100
tp_account_channel_request_new_audio_call, audio_video_call: add
Signed-off-by: Simon McVittie <simon.mcvittie at collabora.co.uk>
Reviewed-by: Jonny Lamb <jonny.lamb at collabora.co.uk>
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=48780
---
docs/reference/telepathy-glib-sections.txt | 2 +
telepathy-glib/account-channel-request.c | 117 ++++++++++++++++++++++++++++
telepathy-glib/account-channel-request.h | 9 ++
telepathy-glib/capabilities.c | 16 ++++-
4 files changed, 142 insertions(+), 2 deletions(-)
diff --git a/docs/reference/telepathy-glib-sections.txt b/docs/reference/telepathy-glib-sections.txt
index a3ab225..17d17fa 100644
--- a/docs/reference/telepathy-glib-sections.txt
+++ b/docs/reference/telepathy-glib-sections.txt
@@ -6034,6 +6034,8 @@ tp_account_channel_request_set_target_contact
tp_account_channel_request_set_target_id
tp_account_channel_request_set_request_property
tp_account_channel_request_new_text
+tp_account_channel_request_new_audio_call
+tp_account_channel_request_new_audio_video_call
tp_account_channel_request_create_and_handle_channel_async
tp_account_channel_request_create_and_handle_channel_finish
tp_account_channel_request_ensure_and_handle_channel_async
diff --git a/telepathy-glib/account-channel-request.c b/telepathy-glib/account-channel-request.c
index f84f2f5..a5e43c4 100644
--- a/telepathy-glib/account-channel-request.c
+++ b/telepathy-glib/account-channel-request.c
@@ -36,6 +36,9 @@
* has to be re-handled. This can be useful for example to move its window
* to the foreground, if applicable.
*
+ * Using this object is appropriate for most channel types.
+ * For a contact search channel, use tp_contact_search_new_async() instead.
+ *
* Since: 0.11.12
*/
@@ -1884,3 +1887,117 @@ tp_account_channel_request_set_request_property (
g_hash_table_insert (self->priv->request, g_strdup (name), v);
}
+
+/**
+ * tp_account_channel_request_new_audio_call:
+ * @account: a #TpAccount
+ * @user_action_time: the time of the user action that caused this request,
+ * or one of the special values %TP_USER_ACTION_TIME_NOT_USER_ACTION or
+ * %TP_USER_ACTION_TIME_CURRENT_TIME (see
+ * #TpAccountChannelRequest:user-action-time)
+ *
+ * Convenience function to create a new #TpAccountChannelRequest object
+ * which will yield a Call channel, initially carrying audio only.
+ *
+ * After creating the request, you will usually also need to set the "target"
+ * of the channel by calling one of the following functions:
+ *
+ * * tp_account_channel_request_set_target_contact()
+ * * tp_account_channel_request_set_target_id()
+ *
+ * To call a contact, either use
+ * tp_account_channel_request_set_target_contact() or one of the generic
+ * methods that takes a handle type argument. To check whether this
+ * is possible, use tp_capabilities_supports_audio_call() with
+ * @handle_type set to %TP_HANDLE_TYPE_CONTACT.
+ *
+ * In some protocols it is possible to create a conference call which
+ * takes place in a named chatroom, by calling
+ * tp_account_channel_request_set_target_id() with @handle_type
+ * set to %TP_HANDLE_TYPE_ROOM. To test whether this is possible, use
+ * tp_capabilities_supports_audio_call() with @handle_type set to
+ * %TP_HANDLE_TYPE_ROOM.
+ *
+ * In some protocols, it is possible to create a Call channel without
+ * setting a target at all, which will result in a new, empty
+ * conference call. To test whether this is possible, use
+ * tp_capabilities_supports_audio_call() with @handle_type set to
+ * %TP_HANDLE_TYPE_NONE.
+ *
+ * Returns: a new #TpAccountChannelRequest object
+ *
+ * Since: 0.19.UNRELEASED
+ */
+TpAccountChannelRequest *
+tp_account_channel_request_new_audio_call (
+ TpAccount *account,
+ gint64 user_action_time)
+{
+ TpAccountChannelRequest *self;
+ GHashTable *request;
+
+ g_return_val_if_fail (TP_IS_ACCOUNT (account), NULL);
+
+ request = tp_asv_new (
+ TP_PROP_CHANNEL_CHANNEL_TYPE, G_TYPE_STRING, TP_IFACE_CHANNEL_TYPE_CALL,
+ TP_PROP_CHANNEL_TYPE_CALL_INITIAL_AUDIO, G_TYPE_BOOLEAN, TRUE,
+ NULL);
+
+ self = g_object_new (TP_TYPE_ACCOUNT_CHANNEL_REQUEST,
+ "account", account,
+ "request", request,
+ "user-action-time", user_action_time,
+ NULL);
+ g_hash_table_unref (request);
+ return self;
+}
+
+/**
+ * tp_account_channel_request_new_audio_video_call:
+ * @account: a #TpAccount
+ * @user_action_time: the time of the user action that caused this request,
+ * or one of the special values %TP_USER_ACTION_TIME_NOT_USER_ACTION or
+ * %TP_USER_ACTION_TIME_CURRENT_TIME (see
+ * #TpAccountChannelRequest:user-action-time)
+ *
+ * Convenience function to create a new #TpAccountChannelRequest object
+ * which will yield a Call channel, initially carrying both audio
+ * and video.
+ *
+ * This is the same as tp_account_channel_request_new_audio_call(),
+ * except that the channel will initially carry video as well as audio,
+ * and instead of using tp_capabilities_supports_audio_call()
+ * you should test capabilities with
+ * tp_capabilities_supports_audio_video_call().
+ *
+ * See the documentation of tp_account_channel_request_new_audio_call()
+ * for details of how to set the target (contact, chatroom etc.) for the call.
+ *
+ * Returns: a new #TpAccountChannelRequest object
+ *
+ * Since: 0.19.UNRELEASED
+ */
+TpAccountChannelRequest *
+tp_account_channel_request_new_audio_video_call (
+ TpAccount *account,
+ gint64 user_action_time)
+{
+ TpAccountChannelRequest *self;
+ GHashTable *request;
+
+ g_return_val_if_fail (TP_IS_ACCOUNT (account), NULL);
+
+ request = tp_asv_new (
+ TP_PROP_CHANNEL_CHANNEL_TYPE, G_TYPE_STRING, TP_IFACE_CHANNEL_TYPE_CALL,
+ TP_PROP_CHANNEL_TYPE_CALL_INITIAL_AUDIO, G_TYPE_BOOLEAN, TRUE,
+ TP_PROP_CHANNEL_TYPE_CALL_INITIAL_VIDEO, G_TYPE_BOOLEAN, TRUE,
+ NULL);
+
+ self = g_object_new (TP_TYPE_ACCOUNT_CHANNEL_REQUEST,
+ "account", account,
+ "request", request,
+ "user-action-time", user_action_time,
+ NULL);
+ g_hash_table_unref (request);
+ return self;
+}
diff --git a/telepathy-glib/account-channel-request.h b/telepathy-glib/account-channel-request.h
index dd523fa..913739e 100644
--- a/telepathy-glib/account-channel-request.h
+++ b/telepathy-glib/account-channel-request.h
@@ -93,6 +93,15 @@ TpAccountChannelRequest *tp_account_channel_request_new_text (
TpAccount *account,
gint64 user_action_time) G_GNUC_WARN_UNUSED_RESULT;
+/* Calls */
+
+TpAccountChannelRequest *tp_account_channel_request_new_audio_call (
+ TpAccount *account,
+ gint64 user_action_time) G_GNUC_WARN_UNUSED_RESULT;
+TpAccountChannelRequest *tp_account_channel_request_new_audio_video_call (
+ TpAccount *account,
+ gint64 user_action_time) G_GNUC_WARN_UNUSED_RESULT;
+
/* Channel target (shared between all channel types) */
void tp_account_channel_request_set_target_contact (
diff --git a/telepathy-glib/capabilities.c b/telepathy-glib/capabilities.c
index e6a36e9..72f14a4 100644
--- a/telepathy-glib/capabilities.c
+++ b/telepathy-glib/capabilities.c
@@ -520,7 +520,13 @@ supports_call_full (TpCapabilities *self,
* private, #TP_HANDLE_TYPE_ROOM or #TP_HANDLE_TYPE_NONE for conference
* (depending on the protocol)
*
- * Return whether audio call can be established.
+ * Return whether audio calls can be established, for instance by calling
+ * tp_account_channel_request_new_audio_call(), followed by
+ * tp_account_channel_request_set_target_id() with @handle_type.
+ *
+ * To check whether requests using
+ * tp_account_channel_request_set_target_contact() would work, set
+ * @handle_type to %TP_HANDLE_TYPE_CONTACT.
*
* Returns: %TRUE if a channel request containing Call as ChannelType,
* @handle_type as TargetHandleType, a True value for InitialAudio and an
@@ -542,7 +548,13 @@ tp_capabilities_supports_audio_call (TpCapabilities *self,
* private, #TP_HANDLE_TYPE_ROOM or #TP_HANDLE_TYPE_NONE for conference
* (depending on the protocol)
*
- * Return whether audio/video call can be established.
+ * Return whether audio/video calls can be established, for instance by calling
+ * tp_account_channel_request_new_audio_video_call(), followed by
+ * tp_account_channel_request_set_target_id() with @handle_type.
+ *
+ * To check whether requests using
+ * tp_account_channel_request_set_target_contact() would work, set
+ * @handle_type to %TP_HANDLE_TYPE_CONTACT.
*
* Returns: %TRUE if a channel request containing Call as ChannelType,
* @handle_type as TargetHandleType, a True value for
More information about the telepathy-commits
mailing list