From 32bfbd521bf6157b1b00446db5b79288a249483d Mon Sep 17 00:00:00 2001
From: Simon McVittie <simon.mcvittie@collabora.co.uk>
Date: Mon, 16 Apr 2012 19:35:37 +0100
Subject: [PATCH 08/14] tp_account_channel_request_new_audio_call,
audio_video_call: add
---
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 f76f5c2..9ae02a6 100644
--- a/docs/reference/telepathy-glib-sections.txt
+++ b/docs/reference/telepathy-glib-sections.txt
@@ -6028,6 +6028,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 eb57efe..66e1c79 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 1536212..cbefa15 100644
--- a/telepathy-glib/capabilities.c
+++ b/telepathy-glib/capabilities.c
@@ -424,7 +424,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
@@ -446,7 +452,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
--
1.7.10