[next] telepathy-glib: tp_account_channel_request_set_file_transfer_description etc.: add

[Simon McVittie]

Module: telepathy-glib
Branch: next
Commit: 4670e6639445555fc6fd42f5d045d1131e5f512f
URL:    http://cgit.freedesktop.org/telepathy/telepathy-glib/commit/?id=4670e6639445555fc6fd42f5d045d1131e5f512f

Author: Simon McVittie <simon.mcvittie at collabora.co.uk>
Date:   Mon Apr 16 19:37:08 2012 +0100

tp_account_channel_request_set_file_transfer_description etc.: add

These are partly useful in their own right, and partly a demonstration
of how any other optional properties should work in this API.

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 |    4 +
 telepathy-glib/account-channel-request.c   |  159 ++++++++++++++++++++++++++++
 telepathy-glib/account-channel-request.h   |   13 +++
 3 files changed, 176 insertions(+), 0 deletions(-)

diff --git a/docs/reference/telepathy-glib-sections.txt b/docs/reference/telepathy-glib-sections.txt
index df52754..5b81dca 100644
--- a/docs/reference/telepathy-glib-sections.txt
+++ b/docs/reference/telepathy-glib-sections.txt
@@ -6041,6 +6041,10 @@ 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_new_file_transfer
+tp_account_channel_request_set_file_transfer_description
+tp_account_channel_request_set_file_transfer_initial_offset
+tp_account_channel_request_set_file_transfer_timestamp
+tp_account_channel_request_set_file_transfer_uri
 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 674aef5..9abe534 100644
--- a/telepathy-glib/account-channel-request.c
+++ b/telepathy-glib/account-channel-request.c
@@ -2064,3 +2064,162 @@ tp_account_channel_request_new_file_transfer (
   g_hash_table_unref (request);
   return self;
 }
+
+/**
+ * tp_account_channel_request_set_file_transfer_description:
+ * @self: a #TpAccountChannelRequest
+ * @description: a description of the file
+ *
+ * Configure this channel request to provide the recipient of the file
+ * with the given description.
+ *
+ * If file descriptions are not supported by the protocol, or if this
+ * method is used on a request that is not actually a file transfer, the
+ * channel request will fail. Use
+ * tp_capabilities_supports_file_transfer_description() to determine
+ * whether outgoing file transfers can have a description.
+ *
+ * This function can't be called once @self has been used to request a
+ * channel.
+ *
+ * Since: 0.19.UNRELEASED
+ */
+void
+tp_account_channel_request_set_file_transfer_description (
+    TpAccountChannelRequest *self,
+    const gchar *description)
+{
+  g_return_if_fail (TP_IS_ACCOUNT_CHANNEL_REQUEST (self));
+  g_return_if_fail (!self->priv->requested);
+  g_return_if_fail (description != NULL);
+
+  g_hash_table_insert (self->priv->request,
+      g_strdup (TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_DESCRIPTION),
+      tp_g_value_slice_new_string (description));
+}
+
+/**
+ * tp_account_channel_request_set_file_transfer_uri:
+ * @self: a #TpAccountChannelRequest
+ * @uri: the source URI for the file
+ *
+ * Configure this channel request to provide other local Telepathy
+ * components with the URI of the file being sent. Unlike most
+ * properties on a file transfer channel, this information is not
+ * sent to the recipient of the file; instead, it is signalled on
+ * D-Bus for use by other Telepathy components.
+ *
+ * The URI should usually be a <code>file</code> URI as defined by
+ * <ulink url="http://www.apps.ietf.org/rfc/rfc1738.html#sec-3.10">RFC 1738
+ * §3.10</ulink> (for instance, <code>file:///path/to/file</code> or
+ * <code>file://localhost/path/to/file</code>). If a remote resource
+ * is being transferred to a contact, it may have a different scheme,
+ * such as <code>http</code>.
+ *
+ * Even if this method is used, the connection manager will not read
+ * the file from disk: the handler for the channel is still
+ * responsible for streaming the file. However, providing the URI
+ * allows a local logger to log which file was transferred, for instance.
+ *
+ * If this functionality is not supported by the connection manager, or
+ * if this method is used on a request that is not actually a file transfer,
+ * the channel request will fail. Use
+ * tp_capabilities_supports_file_transfer_uri() to determine
+ * whether outgoing file transfers can have a URI.
+ *
+ * This function can't be called once @self has been used to request a
+ * channel.
+ *
+ * Since: 0.19.UNRELEASED
+ */
+void
+tp_account_channel_request_set_file_transfer_uri (
+    TpAccountChannelRequest *self,
+    const gchar *uri)
+{
+  g_return_if_fail (TP_IS_ACCOUNT_CHANNEL_REQUEST (self));
+  g_return_if_fail (!self->priv->requested);
+  g_return_if_fail (uri != NULL);
+
+  g_hash_table_insert (self->priv->request,
+      g_strdup (TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_URI),
+      tp_g_value_slice_new_string (uri));
+}
+
+/**
+ * tp_account_channel_request_set_file_transfer_timestamp:
+ * @self: a #TpAccountChannelRequest
+ * @timestamp: the modification timestamp of the file, in seconds since the
+ *  Unix epoch (the beginning of 1970 in the UTC time zone), as returned
+ *  by g_date_time_to_unix()
+ *
+ * Configure this channel request to accompany the file transfer with
+ * the given modification timestamp for the file.
+ *
+ * If file timestamps are not supported by the protocol, or if this
+ * method is used on a request that is not actually a file transfer, the
+ * channel request will fail. Use
+ * tp_capabilities_supports_file_transfer_date() to determine
+ * whether outgoing file transfers can have a timestamp.
+ *
+ * This function can't be called once @self has been used to request a
+ * channel.
+ *
+ * Since: 0.19.UNRELEASED
+ */
+void
+tp_account_channel_request_set_file_transfer_timestamp (
+    TpAccountChannelRequest *self,
+    guint64 timestamp)
+{
+  g_return_if_fail (TP_IS_ACCOUNT_CHANNEL_REQUEST (self));
+  g_return_if_fail (!self->priv->requested);
+
+  g_hash_table_insert (self->priv->request,
+      g_strdup (TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_DATE),
+      tp_g_value_slice_new_uint64 (timestamp));
+}
+
+/**
+ * tp_account_channel_request_set_file_transfer_initial_offset:
+ * @self: a #TpAccountChannelRequest
+ * @offset: the offset into the file at which the transfer will start
+ *
+ * Configure this channel request to inform the recipient of the file
+ * that this channel will not send the first @offset bytes of the file.
+ * In some protocols, this can be used to resume an interrupted transfer.
+ *
+ * If this method is not called, the default is to start from the
+ * beginning of the file (equivalent to @offset = 0).
+ *
+ * If offsets greater than 0 are not supported by the protocol, or if this
+ * method is used on a request that is not actually a file transfer, the
+ * channel request will fail. Use
+ * tp_capabilities_supports_file_transfer_initial_offset() to determine
+ * whether offsets greater than 0 are available.
+ *
+ * This function can't be called once @self has been used to request a
+ * channel.
+ *
+ * Since: 0.19.UNRELEASED
+ */
+void
+tp_account_channel_request_set_file_transfer_initial_offset (
+    TpAccountChannelRequest *self,
+    guint64 offset)
+{
+  g_return_if_fail (TP_IS_ACCOUNT_CHANNEL_REQUEST (self));
+  g_return_if_fail (!self->priv->requested);
+
+  if (offset == 0)
+    {
+      g_hash_table_remove (self->priv->request,
+          TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_INITIAL_OFFSET);
+    }
+  else
+    {
+      g_hash_table_insert (self->priv->request,
+          g_strdup (TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_INITIAL_OFFSET),
+          tp_g_value_slice_new_uint64 (offset));
+    }
+}
diff --git a/telepathy-glib/account-channel-request.h b/telepathy-glib/account-channel-request.h
index 1de6dd5..effa1f8 100644
--- a/telepathy-glib/account-channel-request.h
+++ b/telepathy-glib/account-channel-request.h
@@ -111,6 +111,19 @@ TpAccountChannelRequest *tp_account_channel_request_new_file_transfer (
     guint64 size,
     gint64 user_action_time) G_GNUC_WARN_UNUSED_RESULT;
 
+void tp_account_channel_request_set_file_transfer_description (
+    TpAccountChannelRequest *self,
+    const gchar *description);
+void tp_account_channel_request_set_file_transfer_uri (
+    TpAccountChannelRequest *self,
+    const gchar *uri);
+void tp_account_channel_request_set_file_transfer_timestamp (
+    TpAccountChannelRequest *self,
+    guint64 timestamp);
+void tp_account_channel_request_set_file_transfer_initial_offset (
+    TpAccountChannelRequest *self,
+    guint64 offset);
+
 /* Channel target (shared between all channel types) */
 
 void tp_account_channel_request_set_target_contact (