Merge branch 'ft-misc'

5 files changed, 231 insertions, 41 deletions

diff --git a/libempathy/empathy-tp-file.c b/libempathy/empathy-tp-file.c
index f003b0c70..079390c37 100644
--- a/libempathy/empathy-tp-file.c
+++ b/libempathy/empathy-tp-file.c
@@ -1,4 +1,3 @@
-/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */
 /*
  * Copyright (C) 2007-2008 Collabora Ltd.
  * Copyright (C) 2007 Marco Barisione <marco@barisione.org>
@@ -51,11 +50,18 @@
 
 /**
  * SECTION:empathy-tp-file
- * @short_description: File channel
- * @see_also: #EmpathyTpFile, #EmpathyContact, empathy_dispatcher_send_file()
- * @include: libempthy/empathy-tp-file.h
+ * @title: EmpathyTpFile
+ * @short_description: Object which represents a Telepathy file channel
+ * @include: libempathy/empathy-tp-file.h
  *
- * The #EmpathyTpFile object represents a Telepathy file channel.
+ * #EmpathyTpFile is an object which represents a Telepathy file channel.
+ */
+
+/**
+ * EmpathyTpFile:
+ * @parent: parent object
+ *
+ * Object which represents a Telepathy file channel.
  */
 
 /**
@@ -559,7 +565,7 @@ static void
 tp_file_check_if_ready (EmpathyTpFile *tp_file)
 {
   if (tp_file->priv->ready || tp_file->priv->contact == NULL ||
-      tp_file->priv->state == 0)
+      tp_file->priv->state == TP_FILE_TRANSFER_STATE_NONE)
     return;
 
   tp_file->priv->ready = TRUE;
@@ -578,7 +584,7 @@ tp_file_got_contact_cb (EmpathyTpContactFactory *factory,
   if (error)
     {
       DEBUG ("Error: %s", error->message);
-      empathy_tp_file_close (tp_file);
+      empathy_tp_file_cancel (tp_file);
       return;
     }
 
@@ -824,12 +830,13 @@ tp_file_weak_notify_cb (gpointer channel,
 
 /**
  * empathy_tp_file_new:
- * @channel: a Telepathy channel
+ * @channel: a #TpChannel
  *
  * Creates a new #EmpathyTpFile wrapping @channel, or return a new ref to an
- * existing #EmpathyTpFile for that channel.
+ * existing #EmpathyTpFile for that channel. The returned #EmpathyTpFile
+ * should be unrefed with g_object_unref() when finished with.
  *
- * Returns: a new #EmpathyTpFile
+ * Return value: a new #EmpathyTpFile
  */
 EmpathyTpFile *
 empathy_tp_file_new (TpChannel *channel)
@@ -863,9 +870,9 @@ empathy_tp_file_new (TpChannel *channel)
  * empathy_tp_file_get_channel
  * @tp_file: an #EmpathyTpFile
  *
- * Returns the Telepathy file transfer channel
+ * Returns the #TpChannel associated with @tp_file.
  *
- * Returns: the #TpChannel
+ * Returns: the #TpChannel associated with @tp_file
  */
 TpChannel *
 empathy_tp_file_get_channel (EmpathyTpFile *tp_file)
@@ -934,7 +941,7 @@ tp_file_method_cb (TpChannel *channel,
  * @error: a #GError set if there is an error when opening @gfile
  *
  * Accepts a file transfer that's in the "local pending" state (i.e.
- * TP_FILE_TRANSFER_STATE_LOCAL_PENDING).
+ * %TP_FILE_TRANSFER_STATE_LOCAL_PENDING).
  */
 void
 empathy_tp_file_accept (EmpathyTpFile *tp_file,
@@ -973,7 +980,7 @@ empathy_tp_file_accept (EmpathyTpFile *tp_file,
  * @error: a #GError set if there is an error when opening @gfile
  *
  * Offers a file transfer that's in the "not offered" state (i.e.
- * TP_FILE_TRANSFER_STATE_NOT_OFFERED).
+ * %TP_FILE_TRANSFER_STATE_NOT_OFFERED).
  */
 void
 empathy_tp_file_offer (EmpathyTpFile *tp_file, GFile *gfile, GError **error)
@@ -994,6 +1001,14 @@ empathy_tp_file_offer (EmpathyTpFile *tp_file, GFile *gfile, GError **error)
       &nothing, tp_file_method_cb, NULL, NULL, G_OBJECT (tp_file));
 }
 
+/**
+ * empathy_tp_file_get_contact:
+ * @tp_file: an #EmpathyTpFile
+ *
+ * Returns the #EmpathyContact that @tp_file is open with.
+ *
+ * Return value: the #EmpathyContact that @tp_file is open with.
+ */
 EmpathyContact *
 empathy_tp_file_get_contact (EmpathyTpFile *tp_file)
 {
@@ -1008,6 +1023,14 @@ empathy_tp_file_get_filename (EmpathyTpFile *tp_file)
   return tp_file->priv->filename;
 }
 
+/**
+ * empathy_tp_file_is_incoming:
+ * @tp_file: an #EmpathyTpFile
+ *
+ * Returns whether @tp_file is incoming.
+ *
+ * Return value: %TRUE if the @tp_file is incoming, otherwise %FALSE
+ */
 gboolean
 empathy_tp_file_is_incoming (EmpathyTpFile *tp_file)
 {
@@ -1015,6 +1038,16 @@ empathy_tp_file_is_incoming (EmpathyTpFile *tp_file)
   return tp_file->priv->incoming;
 }
 
+/**
+ * empathy_tp_file_get_state:
+ * @tp_file: an #EmpathyTpFile
+ * @reason: return location for state change reason, or %NULL
+ *
+ * Gets the current state of @tp_file. If @reason is not %NULL, then
+ * it is set to the reason of the last state change.
+ *
+ * Return value: a #TpFileTransferState
+ */
 TpFileTransferState
 empathy_tp_file_get_state (EmpathyTpFile *tp_file,
                            TpFileTransferStateChangeReason *reason)
@@ -1028,6 +1061,14 @@ empathy_tp_file_get_state (EmpathyTpFile *tp_file,
   return tp_file->priv->state;
 }
 
+/**
+ * empathy_tp_file_get_size:
+ * @tp_file: an #EmpathyTpFile
+ *
+ * Gets the size of the file being transferred over @tp_file, in bytes.
+ *
+ * Return value: the size of the file being transferred, in bytes
+ */
 guint64
 empathy_tp_file_get_size (EmpathyTpFile *tp_file)
 {
@@ -1036,6 +1077,14 @@ empathy_tp_file_get_size (EmpathyTpFile *tp_file)
   return tp_file->priv->size;
 }
 
+/**
+ * empathy_tp_file_get_transferred_bytes:
+ * @tp_file: an #EmpathyTpFile
+ *
+ * Gets the number of transferred bytes of @tp_file so far, in bytes.
+ *
+ * Return value: number of transferred bytes of @tp_file, in bytes
+ */
 guint64
 empathy_tp_file_get_transferred_bytes (EmpathyTpFile *tp_file)
 {
@@ -1047,9 +1096,9 @@ empathy_tp_file_get_transferred_bytes (EmpathyTpFile *tp_file)
  * empathy_tp_file_get_remaining_time:
  * @tp_file: a #EmpathyTpFile
  *
- * Get the current remaining time estimation, in seconds.
+ * Gets the estimated time remaining of @tp_file, in seconds.
  *
- * Returns: The time remaining.
+ * Return value: the estimated time remaining of @tp_file, in seconds
  **/
 gint
 empathy_tp_file_get_remaining_time (EmpathyTpFile *tp_file)
@@ -1067,11 +1116,13 @@ empathy_tp_file_get_remaining_time (EmpathyTpFile *tp_file)
 
 /**
  * empathy_tp_file_get_speed:
- * @tp_file: a #EmpathyTpFile
+ * @tp_file: an #EmpathyTpFile
  *
- * Get the current speed of the transfer, in bytes per seconds.
+ * Gets the current speed of the transfer @tp_file, in bytes per
+ * second.
  *
- * Returns: The current speed.
+ * Return value: the current speed of the transfer @tp_file, in
+ *               bytes per second
  **/
 gdouble
 empathy_tp_file_get_speed (EmpathyTpFile *tp_file)
@@ -1091,6 +1142,12 @@ empathy_tp_file_get_content_type (EmpathyTpFile *tp_file)
   return tp_file->priv->content_type;
 }
 
+/**
+ * empathy_tp_file_cancel:
+ * @tp_file: an #EmpathyTpFile
+ *
+ * Cancels the file transfer, @tp_file.
+ */
 void
 empathy_tp_file_cancel (EmpathyTpFile *tp_file)
 {
@@ -1104,12 +1161,18 @@ empathy_tp_file_cancel (EmpathyTpFile *tp_file)
     g_cancellable_cancel (tp_file->priv->cancellable);
 }
 
-void
-empathy_tp_file_close (EmpathyTpFile *tp_file)
-{
-  empathy_tp_file_cancel (tp_file);
-}
-
+/**
+ * empathy_tp_file_is_ready:
+ * @tp_file: an #EmpathyTpFile
+ *
+ * Returns whether the file channel @tp_file is ready for use.
+ *
+ * @tp_file is classed as ready if its state is no longer
+ * %TP_FILE_TRANSFER_STATE_NONE, or if details about the remote
+ * contact have been fully received.
+ *
+ * Return value: %TRUE if @tp_file is ready for use
+ */
 gboolean
 empathy_tp_file_is_ready (EmpathyTpFile *tp_file)
 {
@@ -1129,6 +1192,12 @@ empathy_tp_file_class_init (EmpathyTpFileClass *klass)
   object_class->set_property = tp_file_set_property;
 
   /* Construct-only properties */
+
+  /**
+   * EmpathyTpFile:channel:
+   *
+   * The #TpChannel associated with the #EmpathyTpFile.
+   */
   g_object_class_install_property (object_class,
       PROP_CHANNEL,
       g_param_spec_object ("channel",
@@ -1138,6 +1207,11 @@ empathy_tp_file_class_init (EmpathyTpFileClass *klass)
           G_PARAM_READWRITE |
           G_PARAM_CONSTRUCT_ONLY));
 
+  /**
+   * EmpathyTpFile:state:
+   *
+   * The #TpFileTransferState of the #EmpathyTpFile.
+   */
   g_object_class_install_property (object_class,
       PROP_STATE,
       g_param_spec_uint ("state",
@@ -1149,6 +1223,11 @@ empathy_tp_file_class_init (EmpathyTpFileClass *klass)
           G_PARAM_READWRITE |
           G_PARAM_CONSTRUCT));
 
+  /**
+   * EmpathyTpFile:incoming:
+   *
+   * Whether the #EmpathyTpFile is incoming.
+   */
   g_object_class_install_property (object_class,
       PROP_INCOMING,
       g_param_spec_boolean ("incoming",
@@ -1158,6 +1237,12 @@ empathy_tp_file_class_init (EmpathyTpFileClass *klass)
           G_PARAM_READWRITE |
           G_PARAM_CONSTRUCT));
 
+  /**
+   * EmpathyTpFile:ready:
+   *
+   * Whether the #EmpathyTpFile is ready to use. This property returns
+   * the same as empathy_tp_file_is_ready().
+   */
   g_object_class_install_property (object_class,
       PROP_READY,
       g_param_spec_boolean ("ready",
@@ -1166,6 +1251,11 @@ empathy_tp_file_class_init (EmpathyTpFileClass *klass)
           FALSE,
           G_PARAM_READABLE));
 
+  /**
+   * EmpathyTpFile:filename:
+   *
+   * The name of the file being transferred.
+   */
   g_object_class_install_property (object_class,
       PROP_FILENAME,
       g_param_spec_string ("filename",
@@ -1174,6 +1264,11 @@ empathy_tp_file_class_init (EmpathyTpFileClass *klass)
           "",
           G_PARAM_READWRITE));
 
+  /**
+   * EmpathyTpFile:size:
+   *
+   * The size of the file being transferred.
+   */
   g_object_class_install_property (object_class,
       PROP_SIZE,
       g_param_spec_uint64 ("size",
@@ -1184,6 +1279,11 @@ empathy_tp_file_class_init (EmpathyTpFileClass *klass)
           G_MAXUINT64,
           G_PARAM_READWRITE));
 
+  /**
+   * EmpathyTpFile:content-type:
+   *
+   * The content-type of the file being transferred.
+   */
   g_object_class_install_property (object_class,
       PROP_CONTENT_TYPE,
       g_param_spec_string ("content-type",
@@ -1192,6 +1292,12 @@ empathy_tp_file_class_init (EmpathyTpFileClass *klass)
           "",
           G_PARAM_READWRITE));
 
+  /**
+   * EmpathyTpFile:content-hash-type:
+   *
+   * The type of hash type stored in #EmpathyTpFile:content-hash,
+   * from #TpFileHashType.
+   */
   g_object_class_install_property (object_class,
       PROP_CONTENT_HASH_TYPE,
       g_param_spec_uint ("content-hash-type",
@@ -1202,6 +1308,11 @@ empathy_tp_file_class_init (EmpathyTpFileClass *klass)
           0,
           G_PARAM_READWRITE));
 
+  /**
+   * EmpathyTpFile:content-hash:
+   *
+   * A hash of the contents of the file being transferred.
+   */
   g_object_class_install_property (object_class,
       PROP_CONTENT_HASH,
       g_param_spec_string ("content-hash",
@@ -1210,6 +1321,11 @@ empathy_tp_file_class_init (EmpathyTpFileClass *klass)
           "",
           G_PARAM_READWRITE));
 
+  /**
+   * EmpathyTpFile:transferred-bytes:
+   *
+   * The number of bytes transferred in the #EmpathyTpFile.
+   */
   g_object_class_install_property (object_class,
       PROP_TRANSFERRED_BYTES,
       g_param_spec_uint64 ("transferred-bytes",
@@ -1220,6 +1336,19 @@ empathy_tp_file_class_init (EmpathyTpFileClass *klass)
           0,
           G_PARAM_READWRITE));
 
+  /**
+   * EmpathyTpFile::refresh:
+   * @tp_file: the #EmpathyTpFile
+   *
+   * The progress of @tp_file has changed. This can either be an update
+   * in the number of bytes transferred, or it can be to inform of the
+   * transfer stalling.
+   *
+   * This signal is designed for clients to provide more user feedback
+   * when something to do with @tp_file changes. To avoid emitting this
+   * signal too much, it is guaranteed that it will only ever be fired
+   * at least every two seconds.
+   */
   signals[REFRESH] = g_signal_new ("refresh", G_TYPE_FROM_CLASS (klass),
       G_SIGNAL_RUN_LAST, 0, NULL, NULL,
       g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0);
diff --git a/libempathy/empathy-tp-file.h b/libempathy/empathy-tp-file.h
index 357372f1b..1d4443153 100644
--- a/libempathy/empathy-tp-file.h
+++ b/libempathy/empathy-tp-file.h
@@ -52,6 +52,7 @@ struct _EmpathyTpFile
 {
   GObject      parent;
 
+  /*<private>*/
   EmpathyTpFilePriv *priv;
 };
 
@@ -68,7 +69,6 @@ TpChannel *empathy_tp_file_get_channel (EmpathyTpFile *tp_file);
 void empathy_tp_file_accept (EmpathyTpFile *tp_file, guint64 offset,
   GFile *gfile, GError **error);
 void empathy_tp_file_cancel (EmpathyTpFile *tp_file);
-void empathy_tp_file_close (EmpathyTpFile *tp_file);
 void empathy_tp_file_offer (EmpathyTpFile *tp_file, GFile *gfile,
   GError **error);
 
diff --git a/python/pyempathy/pyempathy.defs b/python/pyempathy/pyempathy.defs
index 3e9fd624c..6f8f0f65d 100644
--- a/python/pyempathy/pyempathy.defs
+++ b/python/pyempathy/pyempathy.defs
@@ -474,6 +474,30 @@
   (return-type "EmpathyTpChat*")
 )
 
+(define-method set_tp_chat
+  (of-object "EmpathyChatroom")
+  (c-name "empathy_chatroom_set_tp_chat")
+  (return-type "none")
+  (parameters
+    '("EmpathyTpChat*" "tp_chat")
+  )
+)
+
+(define-method is_favorite
+  (of-object "EmpathyChatroom")
+  (c-name "empathy_chatroom_is_favorite")
+  (return-type "gboolean")
+)
+
+(define-method set_favorite
+  (of-object "EmpathyChatroom")
+  (c-name "empathy_chatroom_set_favorite")
+  (return-type "none")
+  (parameters
+    '("gboolean" "favorite")
+  )
+)
+
 
 
 ;; From empathy-chatroom-manager.h
@@ -642,6 +666,17 @@
   )
 )
 
+(define-function contact_new_for_log
+  (c-name "empathy_contact_new_for_log")
+  (return-type "EmpathyContact*")
+  (parameters
+    '("McAccount*" "account")
+    '("const-gchar*" "id")
+    '("const-gchar*" "name")
+    '("gboolean" "is_user")
+  )
+)
+
 (define-method get_tp_contact
   (of-object "EmpathyContact")
   (c-name "empathy_contact_get_tp_contact")
@@ -2187,7 +2222,7 @@
   (parameters
     '("guint" "n_ids")
     '("const-gchar*-const*" "ids")
-    '("EmpathyTpContactFactoryGotContactsCb" "callback")
+    '("EmpathyTpContactFactoryContactsByIdCb" "callback")
     '("gpointer" "user_data")
     '("GDestroyNotify" "destroy")
     '("GObject*" "weak_object")
@@ -2201,7 +2236,33 @@
   (parameters
     '("guint" "n_handles")
     '("const-TpHandle*" "handles")
-    '("EmpathyTpContactFactoryGotContactsCb" "callback")
+    '("EmpathyTpContactFactoryContactsByHandleCb" "callback")
+    '("gpointer" "user_data")
+    '("GDestroyNotify" "destroy")
+    '("GObject*" "weak_object")
+  )
+)
+
+(define-method get_from_id
+  (of-object "EmpathyTpContactFactory")
+  (c-name "empathy_tp_contact_factory_get_from_id")
+  (return-type "none")
+  (parameters
+    '("const-gchar*" "id")
+    '("EmpathyTpContactFactoryContactCb" "callback")
+    '("gpointer" "user_data")
+    '("GDestroyNotify" "destroy")
+    '("GObject*" "weak_object")
+  )
+)
+
+(define-method get_from_handle
+  (of-object "EmpathyTpContactFactory")
+  (c-name "empathy_tp_contact_factory_get_from_handle")
+  (return-type "none")
+  (parameters
+    '("TpHandle" "handle")
+    '("EmpathyTpContactFactoryContactCb" "callback")
     '("gpointer" "user_data")
     '("GDestroyNotify" "destroy")
     '("GObject*" "weak_object")
@@ -2306,12 +2367,6 @@
   (return-type "none")
 )
 
-(define-method close
-  (of-object "EmpathyTpFile")
-  (c-name "empathy_tp_file_close")
-  (return-type "none")
-)
-
 (define-method offer
   (of-object "EmpathyTpFile")
   (c-name "empathy_tp_file_offer")
@@ -2367,6 +2422,12 @@
   (return-type "gint")
 )
 
+(define-method get_speed
+  (of-object "EmpathyTpFile")
+  (c-name "empathy_tp_file_get_speed")
+  (return-type "gdouble")
+)
+
 (define-method get_content_type
   (of-object "EmpathyTpFile")
   (c-name "empathy_tp_file_get_content_type")
diff --git a/python/pyempathygtk/pyempathygtk.defs b/python/pyempathygtk/pyempathygtk.defs
index df829a031..816261d39 100644
--- a/python/pyempathygtk/pyempathygtk.defs
+++ b/python/pyempathygtk/pyempathygtk.defs
@@ -278,9 +278,9 @@
   (return-type "GtkWidget*")
 )
 
-(define-method get_account
+(define-method dup_account
   (of-object "EmpathyAccountChooser")
-  (c-name "empathy_account_chooser_get_account")
+  (c-name "empathy_account_chooser_dup_account")
   (return-type "McAccount*")
 )
 
@@ -1145,9 +1145,9 @@
   )
 )
 
-(define-method get_selected
+(define-method dup_selected
   (of-object "EmpathyContactListView")
-  (c-name "empathy_contact_list_view_get_selected")
+  (c-name "empathy_contact_list_view_dup_selected")
   (return-type "EmpathyContact*")
 )
 
@@ -1546,8 +1546,8 @@
   (return-type "GtkWidget*")
 )
 
-(define-function profile_chooser_get_selected
-  (c-name "empathy_profile_chooser_get_selected")
+(define-function profile_chooser_dup_selected
+  (c-name "empathy_profile_chooser_dup_selected")
   (return-type "McProfile*")
   (parameters
     '("GtkWidget*" "widget")
diff --git a/src/empathy-ft-manager.c b/src/empathy-ft-manager.c
index d3d22fbd8..87531f0fe 100644
--- a/src/empathy-ft-manager.c
+++ b/src/empathy-ft-manager.c
@@ -447,7 +447,7 @@ ft_manager_remove_file_from_model (EmpathyFTManager *ft_manager,
   if (update_selection)
     gtk_tree_selection_select_iter (selection, &iter);
 
-  empathy_tp_file_close (tp_file);
+  empathy_tp_file_cancel (tp_file);
 }
 
 static gboolean