[Bug 39188] TpFileTransferChannel: add API to send and receive the file

[bugzilla-daemon at freedesktop.org]

https://bugs.freedesktop.org/show_bug.cgi?id=39188

--- Comment #12 from Will Thompson <will.thompson at collabora.co.uk> 2011-11-10 05:35:27 UTC ---
+ * <informalexample><programlisting>GHashTable *request = tp_asv_new (

Do you know about the |[ ... ]| shortcut for <informalexample><programlisting>
... <//>?

+ * Once a #TpFileTransferChannel is created as a proxy to the channel
+ * on D-Bus, the "notify::state" GObject signal should be monitored
+ * and when at %TP_FILE_TRANSFER_STATE_ACCEPTED
  * tp_file_transfer_channel_provide_file_async() should be called.

I don't think this flows very well. “The "notify::state" GObject signals on the
resulting channel should be monitored; when the channel moves to state 
%TP_FILE_TRANSFER_STATE_ACCEPTED, tp_file_transfer_channel_provide_file_async()
should be called.” maybe?

+   * <informalexample><programlisting>tp_base_client_take_handler_filter
(handler, tp_asv_new (
+   *               TP_PROP_CHANNEL_CHANNEL_TYPE, G_TYPE_STRING,
TP_IFACE_CHANNEL_TYPE_FILE_TRANSFER,
+   *               TP_PROP_CHANNEL_TARGET_HANDLE_TYPE, G_TYPE_UINT,
TP_HANDLE_TYPE_CONTACT,
+   *                TP_PROP_CHANNEL_REQUESTED, G_TYPE_BOOLEAN, FALSE,
+   *              
TP_PROP_CHANNEL_INTERFACE_FILE_TRANSFER_METADATA_SERVICE_NAME, G_TYPE_STRING,
"service.name",
+   *               NULL));
+   * </programlisting></informalexample>

REQUESTED has an extra space of indentation.

I forgot to say before: I think the documentation for
TpFileTransferChannel:metadata should say what type its keys and values have,
like the getter does.

I've just noticed that lots of the gtk-doc comments for the various new
properties don't have colons at the end of their names:

  /**
   * TpFileTransferChannel:date

I wonder if they work regardless?

(In reply to comment #10)
> (In reply to comment #8)
> > Both paragraphs here are ambiguous. “may be set”, but it's a read-only
> > property.  How does one set it? Who sets it? etc.
> 
> I updated these docs, what do you think now?

Clearer!

> > +  /**
> > +   * TpFileTransferChannel:service-name:
> > +   *
> > +   * A string representing the service name that will be used over
> > +   * this file transfer channel or %NULL.
> > 
> > This doesn't really help someone reading the documentation understand what this
> > property is for.
> 
> Okay updated, and with an example, better?

Yup.

-- 
Configure bugmail: https://bugs.freedesktop.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are the QA Contact for the bug.
You are the assignee for the bug.