2 * empathy-ft-handler.c - Source for EmpathyFTHandler
3 * Copyright (C) 2009 Collabora Ltd.
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2.1 of the License, or (at your option) any later version.
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this library; if not, write to the Free Software
17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
19 * Author: Cosimo Cecchi <cosimo.cecchi@collabora.co.uk>
22 /* empathy-ft-handler.c */
25 #include "empathy-ft-handler.h"
27 #include <glib/gi18n-lib.h>
29 #include "empathy-time.h"
30 #include "empathy-utils.h"
32 #define DEBUG_FLAG EMPATHY_DEBUG_FT
33 #include "empathy-debug.h"
36 * SECTION:empathy-ft-handler
37 * @title: EmpathyFTHandler
38 * @short_description: an object representing a File Transfer
39 * @include: libempathy/empathy-ft-handler
41 * #EmpathyFTHandler is the object which represents a File Transfer with all
43 * The creation of an #EmpathyFTHandler is done with
44 * empathy_ft_handler_new_outgoing() or empathy_ft_handler_new_incoming(),
45 * even though clients should not need to call them directly, as
46 * #EmpathyFTFactory does it for them. Remember that for the file transfer
47 * to work with an incoming handler,
48 * empathy_ft_handler_incoming_set_destination() should be called after
49 * empathy_ft_handler_new_incoming(). #EmpathyFTFactory does this
51 * It's important to note that, as the creation of the handlers is async, once
52 * an handler is created, it already has all the interesting properties set,
53 * like filename, total bytes, content type and so on, making it useful
54 * to be displayed in an UI.
55 * The transfer API works like a state machine; it has three signals,
56 * ::transfer-started, ::transfer-progress, ::transfer-done, which will be
57 * emitted in the relevant phases.
58 * In addition, if the handler is created with checksumming enabled,
59 * other three signals (::hashing-started, ::hashing-progress, ::hashing-done)
60 * will be emitted before or after the transfer, depending on the direction
61 * (respectively outgoing and incoming) of the handler.
62 * At any time between the call to empathy_ft_handler_start_transfer() and
63 * the last signal, a ::transfer-error can be emitted, indicating that an
64 * error has happened in the operation. The message of the error is localized
68 G_DEFINE_TYPE (EmpathyFTHandler, empathy_ft_handler, G_TYPE_OBJECT)
70 #define GET_PRIV(obj) EMPATHY_GET_PRIV (obj, EmpathyFTHandler)
72 #define BUFFER_SIZE 4096
81 PROP_MODIFICATION_TIME,
83 PROP_TRANSFERRED_BYTES,
100 GError *error /* comment to make the style checker happy */;
105 EmpathyFTHandler *handler;
109 EmpathyFTHandlerReadyCallback callback;
111 EmpathyFTHandler *handler;
116 gboolean dispose_run;
119 TpFileTransferChannel *channel;
120 GCancellable *cancellable;
123 /* request for the new transfer */
126 /* transfer properties */
127 EmpathyContact *contact;
132 guint64 transferred_bytes;
135 TpFileHashType content_hash_type;
137 gint64 user_action_time;
141 guint remaining_time;
142 gint64 last_update_time;
144 gboolean is_completed;
145 } EmpathyFTHandlerPriv;
147 static guint signals[LAST_SIGNAL] = { 0 };
149 static gboolean do_hash_job_incoming (GIOSchedulerJob *job,
150 GCancellable *cancellable, gpointer user_data);
152 /* GObject implementations */
154 do_get_property (GObject *object,
159 EmpathyFTHandlerPriv *priv = GET_PRIV (object);
164 g_value_set_object (value, priv->contact);
166 case PROP_CONTENT_TYPE:
167 g_value_set_string (value, priv->content_type);
169 case PROP_DESCRIPTION:
170 g_value_set_string (value, priv->description);
173 g_value_set_string (value, priv->filename);
175 case PROP_MODIFICATION_TIME:
176 g_value_set_uint64 (value, priv->mtime);
178 case PROP_TOTAL_BYTES:
179 g_value_set_uint64 (value, priv->total_bytes);
181 case PROP_TRANSFERRED_BYTES:
182 g_value_set_uint64 (value, priv->transferred_bytes);
185 g_value_set_object (value, priv->gfile);
188 g_value_set_object (value, priv->channel);
190 case PROP_USER_ACTION_TIME:
191 g_value_set_int64 (value, priv->user_action_time);
194 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
199 do_set_property (GObject *object,
204 EmpathyFTHandlerPriv *priv = GET_PRIV (object);
209 priv->contact = g_value_dup_object (value);
211 case PROP_CONTENT_TYPE:
212 priv->content_type = g_value_dup_string (value);
214 case PROP_DESCRIPTION:
215 priv->description = g_value_dup_string (value);
218 priv->filename = g_value_dup_string (value);
220 case PROP_MODIFICATION_TIME:
221 priv->mtime = g_value_get_uint64 (value);
223 case PROP_TOTAL_BYTES:
224 priv->total_bytes = g_value_get_uint64 (value);
226 case PROP_TRANSFERRED_BYTES:
227 priv->transferred_bytes = g_value_get_uint64 (value);
230 priv->gfile = g_value_dup_object (value);
233 priv->channel = g_value_dup_object (value);
235 case PROP_USER_ACTION_TIME:
236 priv->user_action_time = g_value_get_int64 (value);
239 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
244 do_dispose (GObject *object)
246 EmpathyFTHandlerPriv *priv = GET_PRIV (object);
248 if (priv->dispose_run)
251 priv->dispose_run = TRUE;
253 if (priv->contact != NULL) {
254 g_object_unref (priv->contact);
255 priv->contact = NULL;
258 if (priv->gfile != NULL) {
259 g_object_unref (priv->gfile);
263 if (priv->channel != NULL) {
264 tp_channel_close_async (TP_CHANNEL (priv->channel), NULL, NULL);
265 g_object_unref (priv->channel);
266 priv->channel = NULL;
269 if (priv->cancellable != NULL) {
270 g_object_unref (priv->cancellable);
271 priv->cancellable = NULL;
274 if (priv->request != NULL)
276 g_hash_table_unref (priv->request);
277 priv->request = NULL;
280 G_OBJECT_CLASS (empathy_ft_handler_parent_class)->dispose (object);
284 do_finalize (GObject *object)
286 EmpathyFTHandlerPriv *priv = GET_PRIV (object);
288 DEBUG ("%p", object);
290 g_free (priv->content_type);
291 priv->content_type = NULL;
293 g_free (priv->filename);
294 priv->filename = NULL;
296 g_free (priv->description);
297 priv->description = NULL;
299 g_free (priv->content_hash);
300 priv->content_hash = NULL;
302 G_OBJECT_CLASS (empathy_ft_handler_parent_class)->finalize (object);
306 empathy_ft_handler_class_init (EmpathyFTHandlerClass *klass)
308 GObjectClass *object_class = G_OBJECT_CLASS (klass);
309 GParamSpec *param_spec;
311 g_type_class_add_private (klass, sizeof (EmpathyFTHandlerPriv));
313 object_class->get_property = do_get_property;
314 object_class->set_property = do_set_property;
315 object_class->dispose = do_dispose;
316 object_class->finalize = do_finalize;
321 * EmpathyFTHandler:contact:
323 * The remote #EmpathyContact for the transfer
325 param_spec = g_param_spec_object ("contact",
326 "contact", "The remote contact",
327 EMPATHY_TYPE_CONTACT,
328 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS | G_PARAM_CONSTRUCT_ONLY);
329 g_object_class_install_property (object_class, PROP_CONTACT, param_spec);
332 * EmpathyFTHandler:content-type:
334 * The content type of the file being transferred
336 param_spec = g_param_spec_string ("content-type",
337 "content-type", "The content type of the file", NULL,
338 G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
339 g_object_class_install_property (object_class,
340 PROP_CONTENT_TYPE, param_spec);
343 * EmpathyFTHandler:description:
345 * The description of the file being transferred
347 param_spec = g_param_spec_string ("description",
348 "description", "The description of the file", NULL,
349 G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
350 g_object_class_install_property (object_class,
351 PROP_DESCRIPTION, param_spec);
354 * EmpathyFTHandler:filename:
356 * The name of the file being transferred
358 param_spec = g_param_spec_string ("filename",
359 "filename", "The name of the file", NULL,
360 G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
361 g_object_class_install_property (object_class,
362 PROP_FILENAME, param_spec);
365 * EmpathyFTHandler:modification-time:
367 * The modification time of the file being transferred
369 param_spec = g_param_spec_uint64 ("modification-time",
370 "modification-time", "The mtime of the file", 0,
371 G_MAXUINT64, 0, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
372 g_object_class_install_property (object_class,
373 PROP_MODIFICATION_TIME, param_spec);
376 * EmpathyFTHandler:total-bytes:
378 * The size (in bytes) of the file being transferred
380 param_spec = g_param_spec_uint64 ("total-bytes",
381 "total-bytes", "The size of the file", 0,
382 G_MAXUINT64, 0, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
383 g_object_class_install_property (object_class,
384 PROP_TOTAL_BYTES, param_spec);
387 * EmpathyFTHandler:transferred-bytes:
389 * The number of the bytes already transferred
391 param_spec = g_param_spec_uint64 ("transferred-bytes",
392 "transferred-bytes", "The number of bytes already transferred", 0,
393 G_MAXUINT64, 0, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
394 g_object_class_install_property (object_class,
395 PROP_TRANSFERRED_BYTES, param_spec);
398 * EmpathyFTHandler:gfile:
400 * The #GFile object where the transfer actually happens
402 param_spec = g_param_spec_object ("gfile",
403 "gfile", "The GFile we're handling",
405 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
406 g_object_class_install_property (object_class, PROP_G_FILE, param_spec);
409 * EmpathyFTHandler:channel:
411 * The underlying #TpFileTransferChannel managing the transfer
413 param_spec = g_param_spec_object ("channel",
414 "channel", "The file transfer channel",
415 TP_TYPE_FILE_TRANSFER_CHANNEL,
416 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS | G_PARAM_CONSTRUCT_ONLY);
417 g_object_class_install_property (object_class, PROP_CHANNEL, param_spec);
419 param_spec = g_param_spec_int64 ("user-action-time", "user action time",
422 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS | G_PARAM_CONSTRUCT_ONLY);
423 g_object_class_install_property (object_class, PROP_USER_ACTION_TIME,
429 * EmpathyFTHandler::transfer-started
430 * @handler: the object which has received the signal
431 * @channel: the #TpFileTransferChannel for which the transfer has started
433 * This signal is emitted when the actual transfer starts.
435 signals[TRANSFER_STARTED] =
436 g_signal_new ("transfer-started", G_TYPE_FROM_CLASS (klass),
437 G_SIGNAL_RUN_LAST, 0, NULL, NULL,
438 g_cclosure_marshal_generic,
440 1, TP_TYPE_FILE_TRANSFER_CHANNEL);
443 * EmpathyFTHandler::transfer-done
444 * @handler: the object which has received the signal
445 * @channel: the #TpFileTransferChannel for which the transfer has started
447 * This signal will be emitted when the actual transfer is completed
450 signals[TRANSFER_DONE] =
451 g_signal_new ("transfer-done", G_TYPE_FROM_CLASS (klass),
452 G_SIGNAL_RUN_LAST, 0, NULL, NULL,
453 g_cclosure_marshal_generic,
455 1, TP_TYPE_FILE_TRANSFER_CHANNEL);
458 * EmpathyFTHandler::transfer-error
459 * @handler: the object which has received the signal
462 * This signal can be emitted anytime between the call to
463 * empathy_ft_handler_start_transfer() and the last expected signal
464 * (::transfer-done or ::hashing-done), and it's guaranteed to be the last
465 * signal coming from the handler, meaning that no other operation will
466 * take place after this signal.
468 signals[TRANSFER_ERROR] =
469 g_signal_new ("transfer-error", G_TYPE_FROM_CLASS (klass),
470 G_SIGNAL_RUN_LAST, 0, NULL, NULL,
471 g_cclosure_marshal_generic,
476 * EmpathyFTHandler::transfer-progress
477 * @handler: the object which has received the signal
478 * @current_bytes: the bytes currently transferred
479 * @total_bytes: the total bytes of the handler
480 * @remaining_time: the number of seconds remaining for the transfer
482 * @speed: the current speed of the transfer (in KB/s)
484 * This signal is emitted to notify clients of the progress of the
487 signals[TRANSFER_PROGRESS] =
488 g_signal_new ("transfer-progress", G_TYPE_FROM_CLASS (klass),
489 G_SIGNAL_RUN_LAST, 0, NULL, NULL,
490 g_cclosure_marshal_generic,
492 4, G_TYPE_UINT64, G_TYPE_UINT64, G_TYPE_UINT, G_TYPE_DOUBLE);
495 * EmpathyFTHandler::hashing-started
496 * @handler: the object which has received the signal
498 * This signal is emitted when the hashing operation of the handler
499 * is started. Note that this might happen or not, depending on the CM
500 * and remote contact capabilities. Clients shoud use
501 * empathy_ft_handler_get_use_hash() before calling
502 * empathy_ft_handler_start_transfer() to know whether they should connect
505 signals[HASHING_STARTED] =
506 g_signal_new ("hashing-started", G_TYPE_FROM_CLASS (klass),
507 G_SIGNAL_RUN_LAST, 0, NULL, NULL,
508 g_cclosure_marshal_generic,
512 * EmpathyFTHandler::hashing-progress
513 * @handler: the object which has received the signal
514 * @current_bytes: the bytes currently hashed
515 * @total_bytes: the total bytes of the handler
517 * This signal is emitted to notify clients of the progress of the
520 signals[HASHING_PROGRESS] =
521 g_signal_new ("hashing-progress", G_TYPE_FROM_CLASS (klass),
522 G_SIGNAL_RUN_LAST, 0, NULL, NULL,
523 g_cclosure_marshal_generic,
525 2, G_TYPE_UINT64, G_TYPE_UINT64);
528 * EmpathyFTHandler::hashing-done
529 * @handler: the object which has received the signal
531 * This signal is emitted when the hashing operation of the handler
534 signals[HASHING_DONE] =
535 g_signal_new ("hashing-done", G_TYPE_FROM_CLASS (klass),
536 G_SIGNAL_RUN_LAST, 0, NULL, NULL,
537 g_cclosure_marshal_generic,
542 empathy_ft_handler_init (EmpathyFTHandler *self)
544 EmpathyFTHandlerPriv *priv = G_TYPE_INSTANCE_GET_PRIVATE (self,
545 EMPATHY_TYPE_FT_HANDLER, EmpathyFTHandlerPriv);
548 priv->cancellable = g_cancellable_new ();
551 /* private functions */
554 hash_data_free (HashingData *data)
556 g_free (data->buffer);
558 if (data->stream != NULL)
559 g_object_unref (data->stream);
561 if (data->checksum != NULL)
562 g_checksum_free (data->checksum);
564 if (data->error != NULL)
565 g_error_free (data->error);
567 if (data->handler != NULL)
568 g_object_unref (data->handler);
570 g_slice_free (HashingData, data);
574 tp_file_hash_to_g_checksum (TpFileHashType type)
576 GChecksumType retval;
580 case TP_FILE_HASH_TYPE_MD5:
581 retval = G_CHECKSUM_MD5;
583 case TP_FILE_HASH_TYPE_SHA1:
584 retval = G_CHECKSUM_SHA1;
586 case TP_FILE_HASH_TYPE_SHA256:
587 retval = G_CHECKSUM_SHA256;
589 case TP_FILE_HASH_TYPE_NONE:
591 g_assert_not_reached ();
599 check_hash_incoming (EmpathyFTHandler *handler)
601 HashingData *hash_data;
602 EmpathyFTHandlerPriv *priv = GET_PRIV (handler);
604 if (!EMP_STR_EMPTY (priv->content_hash))
606 hash_data = g_slice_new0 (HashingData);
607 hash_data->total_bytes = priv->total_bytes;
608 hash_data->handler = g_object_ref (handler);
609 hash_data->checksum = g_checksum_new
610 (tp_file_hash_to_g_checksum (priv->content_hash_type));
612 g_signal_emit (handler, signals[HASHING_STARTED], 0);
614 g_io_scheduler_push_job (do_hash_job_incoming, hash_data, NULL,
615 G_PRIORITY_DEFAULT, priv->cancellable);
620 emit_error_signal (EmpathyFTHandler *handler,
623 EmpathyFTHandlerPriv *priv = GET_PRIV (handler);
625 DEBUG ("Error in transfer: %s\n", error->message);
627 if (!g_cancellable_is_cancelled (priv->cancellable))
628 g_cancellable_cancel (priv->cancellable);
630 g_signal_emit (handler, signals[TRANSFER_ERROR], 0, error);
634 update_remaining_time_and_speed (EmpathyFTHandler *handler,
635 guint64 transferred_bytes)
637 EmpathyFTHandlerPriv *priv = GET_PRIV (handler);
638 gint64 elapsed_time, current_time;
639 guint64 transferred, last_transferred_bytes;
643 last_transferred_bytes = priv->transferred_bytes;
644 priv->transferred_bytes = transferred_bytes;
646 current_time = empathy_time_get_current ();
647 elapsed_time = current_time - priv->last_update_time;
649 if (elapsed_time >= 1)
651 transferred = transferred_bytes - last_transferred_bytes;
652 speed = (gdouble) transferred / (gdouble) elapsed_time;
653 remaining_time = (priv->total_bytes - priv->transferred_bytes) / speed;
655 priv->remaining_time = remaining_time;
656 priv->last_update_time = current_time;
661 ft_transfer_transferred_bytes_cb (TpFileTransferChannel *channel,
663 EmpathyFTHandler *handler)
665 EmpathyFTHandlerPriv *priv = GET_PRIV (handler);
668 if (empathy_ft_handler_is_cancelled (handler))
671 bytes = tp_file_transfer_channel_get_transferred_bytes (channel);
673 if (priv->transferred_bytes == 0)
675 priv->last_update_time = empathy_time_get_current ();
676 g_signal_emit (handler, signals[TRANSFER_STARTED], 0, channel);
679 if (priv->transferred_bytes != bytes)
681 update_remaining_time_and_speed (handler, bytes);
683 g_signal_emit (handler, signals[TRANSFER_PROGRESS], 0,
684 bytes, priv->total_bytes, priv->remaining_time,
690 ft_transfer_provide_cb (GObject *source,
691 GAsyncResult *result,
694 TpFileTransferChannel *channel = TP_FILE_TRANSFER_CHANNEL (source);
695 EmpathyFTHandler *handler = user_data;
696 GError *error = NULL;
698 if (!tp_file_transfer_channel_provide_file_finish (channel, result, &error))
700 emit_error_signal (handler, error);
701 g_clear_error (&error);
706 ft_transfer_accept_cb (GObject *source,
707 GAsyncResult *result,
710 TpFileTransferChannel *channel = TP_FILE_TRANSFER_CHANNEL (source);
711 EmpathyFTHandler *handler = user_data;
712 GError *error = NULL;
714 if (!tp_file_transfer_channel_accept_file_finish (channel, result, &error))
716 emit_error_signal (handler, error);
717 g_clear_error (&error);
722 error_from_state_change_reason (TpFileTransferStateChangeReason reason)
725 GError *retval = NULL;
731 case TP_FILE_TRANSFER_STATE_CHANGE_REASON_NONE:
732 string = _("No reason was specified");
734 case TP_FILE_TRANSFER_STATE_CHANGE_REASON_REQUESTED:
735 string = _("The change in state was requested");
737 case TP_FILE_TRANSFER_STATE_CHANGE_REASON_LOCAL_STOPPED:
738 string = _("You canceled the file transfer");
740 case TP_FILE_TRANSFER_STATE_CHANGE_REASON_REMOTE_STOPPED:
741 string = _("The other participant canceled the file transfer");
743 case TP_FILE_TRANSFER_STATE_CHANGE_REASON_LOCAL_ERROR:
744 string = _("Error while trying to transfer the file");
746 case TP_FILE_TRANSFER_STATE_CHANGE_REASON_REMOTE_ERROR:
747 string = _("The other participant is unable to transfer the file");
750 string = _("Unknown reason");
754 retval = g_error_new_literal (EMPATHY_FT_ERROR_QUARK,
755 EMPATHY_FT_ERROR_TP_ERROR, string);
761 ft_transfer_state_cb (TpFileTransferChannel *channel,
763 EmpathyFTHandler *handler)
765 EmpathyFTHandlerPriv *priv = GET_PRIV (handler);
766 TpFileTransferStateChangeReason reason;
767 TpFileTransferState state = tp_file_transfer_channel_get_state (
770 if (state == TP_FILE_TRANSFER_STATE_COMPLETED)
772 priv->is_completed = TRUE;
773 g_signal_emit (handler, signals[TRANSFER_DONE], 0, channel);
775 tp_channel_close_async (TP_CHANNEL (channel), NULL, NULL);
777 if (empathy_ft_handler_is_incoming (handler) && priv->use_hash)
779 check_hash_incoming (handler);
782 else if (state == TP_FILE_TRANSFER_STATE_CANCELLED)
784 GError *error = error_from_state_change_reason (reason);
785 emit_error_signal (handler, error);
786 g_clear_error (&error);
791 ft_handler_create_channel_cb (GObject *source,
792 GAsyncResult *result,
795 EmpathyFTHandler *handler = user_data;
796 EmpathyFTHandlerPriv *priv = GET_PRIV (handler);
797 GError *error = NULL;
800 DEBUG ("Dispatcher create channel CB");
802 channel = tp_account_channel_request_create_and_handle_channel_finish (
803 TP_ACCOUNT_CHANNEL_REQUEST (source), result, NULL, &error);
806 DEBUG ("Failed to request FT channel: %s", error->message);
808 g_cancellable_set_error_if_cancelled (priv->cancellable, &error);
812 emit_error_signal (handler, error);
814 g_clear_object (&channel);
815 g_error_free (error);
819 priv->channel = TP_FILE_TRANSFER_CHANNEL (channel);
821 tp_g_signal_connect_object (priv->channel, "notify::state",
822 G_CALLBACK (ft_transfer_state_cb), handler, 0);
823 tp_g_signal_connect_object (priv->channel, "notify::transferred-bytes",
824 G_CALLBACK (ft_transfer_transferred_bytes_cb), handler, 0);
826 tp_file_transfer_channel_provide_file_async (priv->channel, priv->gfile,
827 ft_transfer_provide_cb, handler);
831 ft_handler_push_to_dispatcher (EmpathyFTHandler *handler)
834 EmpathyFTHandlerPriv *priv = GET_PRIV (handler);
835 TpAccountChannelRequest *req;
837 DEBUG ("Pushing request to the dispatcher");
839 account = empathy_contact_get_account (priv->contact);
841 req = tp_account_channel_request_new (account, priv->request,
842 priv->user_action_time);
844 tp_account_channel_request_create_and_handle_channel_async (req, NULL,
845 ft_handler_create_channel_cb, handler);
847 g_object_unref (req);
851 ft_handler_populate_outgoing_request (EmpathyFTHandler *handler)
853 guint contact_handle;
854 EmpathyFTHandlerPriv *priv = GET_PRIV (handler);
857 contact_handle = empathy_contact_get_handle (priv->contact);
858 uri = g_file_get_uri (priv->gfile);
860 priv->request = tp_asv_new (
861 TP_PROP_CHANNEL_CHANNEL_TYPE, G_TYPE_STRING,
862 TP_IFACE_CHANNEL_TYPE_FILE_TRANSFER,
863 TP_PROP_CHANNEL_TARGET_HANDLE_TYPE, G_TYPE_UINT,
864 TP_HANDLE_TYPE_CONTACT,
865 TP_PROP_CHANNEL_TARGET_HANDLE, G_TYPE_UINT,
867 TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_CONTENT_TYPE, G_TYPE_STRING,
869 TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_FILENAME, G_TYPE_STRING,
871 TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_SIZE, G_TYPE_UINT64,
873 TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_DATE, G_TYPE_UINT64,
875 TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_URI, G_TYPE_STRING, uri,
882 hash_job_done (gpointer user_data)
884 HashingData *hash_data = user_data;
885 EmpathyFTHandler *handler = hash_data->handler;
886 EmpathyFTHandlerPriv *priv;
887 GError *error = NULL;
889 DEBUG ("Closing stream after hashing.");
891 priv = GET_PRIV (handler);
893 if (hash_data->error != NULL)
895 error = hash_data->error;
896 hash_data->error = NULL;
900 DEBUG ("Got file hash %s", g_checksum_get_string (hash_data->checksum));
902 if (empathy_ft_handler_is_incoming (handler))
904 if (g_strcmp0 (g_checksum_get_string (hash_data->checksum),
907 DEBUG ("Hash mismatch when checking incoming handler: "
908 "received %s, calculated %s", priv->content_hash,
909 g_checksum_get_string (hash_data->checksum));
911 error = g_error_new_literal (EMPATHY_FT_ERROR_QUARK,
912 EMPATHY_FT_ERROR_HASH_MISMATCH,
913 _("File transfer completed, but the file was corrupted"));
918 DEBUG ("Hash verification matched, received %s, calculated %s",
920 g_checksum_get_string (hash_data->checksum));
925 /* set the checksum in the request...
926 * org.freedesktop.Telepathy.Channel.Type.FileTransfer.ContentHash
928 tp_asv_set_string (priv->request,
929 TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_CONTENT_HASH,
930 g_checksum_get_string (hash_data->checksum));
937 emit_error_signal (handler, error);
938 g_clear_error (&error);
942 g_signal_emit (handler, signals[HASHING_DONE], 0);
944 if (!empathy_ft_handler_is_incoming (handler))
945 /* the request is complete now, push it to the dispatcher */
946 ft_handler_push_to_dispatcher (handler);
949 hash_data_free (hash_data);
955 emit_hashing_progress (gpointer user_data)
957 HashingData *hash_data = user_data;
959 g_signal_emit (hash_data->handler, signals[HASHING_PROGRESS], 0,
960 (guint64) hash_data->total_read, (guint64) hash_data->total_bytes);
966 do_hash_job (GIOSchedulerJob *job,
967 GCancellable *cancellable,
970 HashingData *hash_data = user_data;
972 GError *error = NULL;
975 if (hash_data->buffer == NULL)
976 hash_data->buffer = g_malloc0 (BUFFER_SIZE);
978 bytes_read = g_input_stream_read (hash_data->stream, hash_data->buffer,
979 BUFFER_SIZE, cancellable, &error);
983 hash_data->total_read += bytes_read;
985 /* we now have the chunk */
988 g_checksum_update (hash_data->checksum, hash_data->buffer, bytes_read);
989 g_io_scheduler_job_send_to_mainloop_async (job, emit_hashing_progress,
992 g_free (hash_data->buffer);
993 hash_data->buffer = NULL;
999 g_input_stream_close (hash_data->stream, cancellable, &error);
1004 hash_data->error = error;
1006 g_io_scheduler_job_send_to_mainloop_async (job, hash_job_done,
1013 do_hash_job_incoming (GIOSchedulerJob *job,
1014 GCancellable *cancellable,
1017 HashingData *hash_data = user_data;
1018 EmpathyFTHandler *handler = hash_data->handler;
1019 EmpathyFTHandlerPriv *priv = GET_PRIV (handler);
1020 GError *error = NULL;
1022 DEBUG ("checking integrity for incoming handler");
1024 /* need to get the stream first */
1026 G_INPUT_STREAM (g_file_read (priv->gfile, cancellable, &error));
1030 hash_data->error = error;
1031 g_io_scheduler_job_send_to_mainloop_async (job, hash_job_done,
1036 return do_hash_job (job, cancellable, user_data);
1040 ft_handler_read_async_cb (GObject *source,
1044 GFileInputStream *stream;
1045 GError *error = NULL;
1046 HashingData *hash_data;
1047 EmpathyFTHandler *handler = user_data;
1048 EmpathyFTHandlerPriv *priv = GET_PRIV (handler);
1050 DEBUG ("GFile read async CB.");
1052 stream = g_file_read_finish (priv->gfile, res, &error);
1055 emit_error_signal (handler, error);
1056 g_clear_error (&error);
1061 hash_data = g_slice_new0 (HashingData);
1062 hash_data->stream = G_INPUT_STREAM (stream);
1063 hash_data->total_bytes = priv->total_bytes;
1064 hash_data->handler = g_object_ref (handler);
1065 /* FIXME: MD5 is the only ContentHashType supported right now */
1066 hash_data->checksum = g_checksum_new (G_CHECKSUM_MD5);
1068 tp_asv_set_uint32 (priv->request,
1069 TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_CONTENT_HASH_TYPE,
1070 TP_FILE_HASH_TYPE_MD5);
1072 g_signal_emit (handler, signals[HASHING_STARTED], 0);
1074 g_io_scheduler_push_job (do_hash_job, hash_data, NULL,
1075 G_PRIORITY_DEFAULT, priv->cancellable);
1079 callbacks_data_free (gpointer user_data)
1081 CallbacksData *data = user_data;
1083 if (data->handler != NULL)
1084 g_object_unref (data->handler);
1086 g_slice_free (CallbacksData, data);
1090 set_content_hash_type_from_classes (EmpathyFTHandler *handler,
1093 GArray *possible_values;
1096 EmpathyFTHandlerPriv *priv = GET_PRIV (handler);
1097 gboolean support_ft = FALSE;
1100 possible_values = g_array_new (TRUE, TRUE, sizeof (guint));
1102 for (i = 0; i < classes->len; i++)
1106 const gchar *chan_type;
1108 tp_value_array_unpack (g_ptr_array_index (classes, i), 2,
1111 chan_type = tp_asv_get_string (fixed, TP_PROP_CHANNEL_CHANNEL_TYPE);
1113 if (tp_strdiff (chan_type, TP_IFACE_CHANNEL_TYPE_FILE_TRANSFER))
1116 if (tp_asv_get_uint32 (fixed, TP_PROP_CHANNEL_TARGET_HANDLE_TYPE, NULL) !=
1117 TP_HANDLE_TYPE_CONTACT)
1122 value = tp_asv_get_uint32
1123 (fixed, TP_PROP_CHANNEL_TYPE_FILE_TRANSFER_CONTENT_HASH_TYPE,
1127 g_array_append_val (possible_values, value);
1132 g_array_unref (possible_values);
1136 if (possible_values->len == 0)
1138 /* there are no channel classes with hash support, disable it. */
1139 priv->use_hash = FALSE;
1140 priv->content_hash_type = TP_FILE_HASH_TYPE_NONE;
1145 priv->use_hash = TRUE;
1147 if (possible_values->len == 1)
1149 priv->content_hash_type = g_array_index (possible_values, guint, 0);
1153 /* order the array and pick the first non zero, so that MD5
1154 * is the preferred value.
1156 g_array_sort (possible_values, empathy_uint_compare);
1158 if (g_array_index (possible_values, guint, 0) == 0)
1159 priv->content_hash_type = g_array_index (possible_values, guint, 1);
1161 priv->content_hash_type = g_array_index (possible_values, guint, 0);
1165 g_array_unref (possible_values);
1167 DEBUG ("Hash enabled %s; setting content hash type as %u",
1168 priv->use_hash ? "True" : "False", priv->content_hash_type);
1174 check_hashing (CallbacksData *data)
1176 EmpathyFTHandler *handler = data->handler;
1177 EmpathyFTHandlerPriv *priv = GET_PRIV (handler);
1178 GError *myerr = NULL;
1179 TpCapabilities *caps;
1183 conn = empathy_contact_get_connection (priv->contact);
1185 caps = tp_connection_get_capabilities (conn);
1188 data->callback (handler, NULL, data->user_data);
1192 classes = tp_capabilities_get_channel_classes (caps);
1194 /* set whether we support hash and the type of it */
1195 if (!set_content_hash_type_from_classes (handler, classes))
1197 g_set_error_literal (&myerr, EMPATHY_FT_ERROR_QUARK,
1198 EMPATHY_FT_ERROR_NOT_SUPPORTED,
1199 _("File transfer not supported by remote contact"));
1201 if (!g_cancellable_is_cancelled (priv->cancellable))
1202 g_cancellable_cancel (priv->cancellable);
1204 data->callback (handler, myerr, data->user_data);
1205 g_clear_error (&myerr);
1209 /* get back to the caller now */
1210 data->callback (handler, NULL, data->user_data);
1214 callbacks_data_free (data);
1218 ft_handler_complete_request (EmpathyFTHandler *handler)
1220 EmpathyFTHandlerPriv *priv = GET_PRIV (handler);
1222 /* populate the request table with all the known properties */
1223 ft_handler_populate_outgoing_request (handler);
1226 /* start hashing the file */
1227 g_file_read_async (priv->gfile, G_PRIORITY_DEFAULT,
1228 priv->cancellable, ft_handler_read_async_cb, handler);
1230 /* push directly the handler to the dispatcher */
1231 ft_handler_push_to_dispatcher (handler);
1235 ft_handler_gfile_ready_cb (GObject *source,
1237 CallbacksData *cb_data)
1240 GError *error = NULL;
1242 EmpathyFTHandlerPriv *priv = GET_PRIV (cb_data->handler);
1244 DEBUG ("Got GFileInfo.");
1246 info = g_file_query_info_finish (priv->gfile, res, &error);
1251 if (g_file_info_get_file_type (info) != G_FILE_TYPE_REGULAR)
1253 error = g_error_new_literal (EMPATHY_FT_ERROR_QUARK,
1254 EMPATHY_FT_ERROR_INVALID_SOURCE_FILE,
1255 _("The selected file is not a regular file"));
1259 priv->total_bytes = g_file_info_get_size (info);
1260 if (priv->total_bytes == 0)
1262 error = g_error_new_literal (EMPATHY_FT_ERROR_QUARK,
1263 EMPATHY_FT_ERROR_EMPTY_SOURCE_FILE,
1264 _("The selected file is empty"));
1268 priv->content_type = g_strdup (g_file_info_get_content_type (info));
1269 priv->filename = g_strdup (g_file_info_get_display_name (info));
1270 g_file_info_get_modification_time (info, &mtime);
1271 priv->mtime = mtime.tv_sec;
1272 priv->transferred_bytes = 0;
1273 priv->description = NULL;
1275 g_object_unref (info);
1280 if (!g_cancellable_is_cancelled (priv->cancellable))
1281 g_cancellable_cancel (priv->cancellable);
1283 cb_data->callback (cb_data->handler, error, cb_data->user_data);
1284 g_error_free (error);
1286 callbacks_data_free (cb_data);
1290 /* see if FT/hashing are allowed */
1291 check_hashing (cb_data);
1296 channel_get_all_properties_cb (TpProxy *proxy,
1297 GHashTable *properties,
1298 const GError *error,
1300 GObject *weak_object)
1302 CallbacksData *cb_data = user_data;
1303 EmpathyFTHandler *handler = EMPATHY_FT_HANDLER (weak_object);
1304 EmpathyFTHandlerPriv *priv = GET_PRIV (handler);
1309 if (!g_cancellable_is_cancelled (priv->cancellable))
1310 g_cancellable_cancel (priv->cancellable);
1312 cb_data->callback (handler, (GError *) error, cb_data->user_data);
1314 callbacks_data_free (cb_data);
1318 priv->content_hash = g_value_dup_string (
1319 g_hash_table_lookup (properties, "ContentHash"));
1321 priv->content_hash_type = g_value_get_uint (
1322 g_hash_table_lookup (properties, "ContentHashType"));
1324 contact = tp_channel_get_target_contact (TP_CHANNEL (proxy));
1325 priv->contact = empathy_contact_dup_from_tp_contact (contact);
1327 cb_data->callback (handler, NULL, cb_data->user_data);
1330 /* public methods */
1333 * empathy_ft_handler_new_outgoing:
1334 * @contact: the #EmpathyContact to send @source to
1335 * @source: the #GFile to send
1336 * @callback: callback to be called when the handler has been created
1337 * @user_data: user data to be passed to @callback
1339 * Triggers the creation of a new #EmpathyFTHandler for an outgoing transfer.
1342 empathy_ft_handler_new_outgoing (EmpathyContact *contact,
1345 EmpathyFTHandlerReadyCallback callback,
1348 EmpathyFTHandler *handler;
1349 CallbacksData *data;
1350 EmpathyFTHandlerPriv *priv;
1352 DEBUG ("New handler outgoing");
1354 g_return_if_fail (EMPATHY_IS_CONTACT (contact));
1355 g_return_if_fail (G_IS_FILE (source));
1357 handler = g_object_new (EMPATHY_TYPE_FT_HANDLER,
1360 "user-action-time", action_time,
1363 priv = GET_PRIV (handler);
1365 data = g_slice_new0 (CallbacksData);
1366 data->callback = callback;
1367 data->user_data = user_data;
1368 data->handler = g_object_ref (handler);
1370 /* start collecting info about the file */
1371 g_file_query_info_async (priv->gfile,
1372 G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME ","
1373 G_FILE_ATTRIBUTE_STANDARD_SIZE ","
1374 G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE ","
1375 G_FILE_ATTRIBUTE_STANDARD_TYPE ","
1376 G_FILE_ATTRIBUTE_TIME_MODIFIED,
1377 G_FILE_QUERY_INFO_NONE, G_PRIORITY_DEFAULT,
1378 NULL, (GAsyncReadyCallback) ft_handler_gfile_ready_cb, data);
1382 * empathy_ft_handler_new_incoming:
1383 * @channel: the #TpFileTransferChannel proxy to the incoming channel
1384 * @callback: callback to be called when the handler has been created
1385 * @user_data: user data to be passed to @callback
1387 * Triggers the creation of a new #EmpathyFTHandler for an incoming transfer.
1388 * Note that for the handler to be useful, you will have to set a destination
1389 * file with empathy_ft_handler_incoming_set_destination() after the handler
1393 empathy_ft_handler_new_incoming (TpFileTransferChannel *channel,
1394 EmpathyFTHandlerReadyCallback callback,
1397 EmpathyFTHandler *handler;
1398 CallbacksData *data;
1399 EmpathyFTHandlerPriv *priv;
1401 g_return_if_fail (TP_IS_FILE_TRANSFER_CHANNEL (channel));
1403 handler = g_object_new (EMPATHY_TYPE_FT_HANDLER,
1404 "channel", channel, NULL);
1406 priv = GET_PRIV (handler);
1408 data = g_slice_new0 (CallbacksData);
1409 data->callback = callback;
1410 data->user_data = user_data;
1411 data->handler = g_object_ref (handler);
1413 priv->total_bytes = tp_file_transfer_channel_get_size (channel);
1415 priv->transferred_bytes = tp_file_transfer_channel_get_transferred_bytes (
1418 priv->filename = g_strdup (tp_file_transfer_channel_get_filename (channel));
1420 priv->content_type = g_strdup (tp_file_transfer_channel_get_mime_type (
1423 priv->description = g_strdup (tp_file_transfer_channel_get_description (
1426 tp_cli_dbus_properties_call_get_all (channel,
1427 -1, TP_IFACE_CHANNEL_TYPE_FILE_TRANSFER,
1428 channel_get_all_properties_cb, data, NULL, G_OBJECT (handler));
1432 * empathy_ft_handler_start_transfer:
1433 * @handler: an #EmpathyFTHandler
1435 * Starts the transfer machinery. After this call, the transfer and hashing
1436 * signals will be emitted by the handler.
1439 empathy_ft_handler_start_transfer (EmpathyFTHandler *handler)
1441 EmpathyFTHandlerPriv *priv;
1443 g_return_if_fail (EMPATHY_IS_FT_HANDLER (handler));
1445 priv = GET_PRIV (handler);
1447 if (priv->channel == NULL)
1449 ft_handler_complete_request (handler);
1453 /* TODO: add support for resume. */
1454 tp_file_transfer_channel_accept_file_async (priv->channel,
1455 priv->gfile, 0, ft_transfer_accept_cb, handler);
1457 tp_g_signal_connect_object (priv->channel, "notify::state",
1458 G_CALLBACK (ft_transfer_state_cb), handler, 0);
1459 tp_g_signal_connect_object (priv->channel, "notify::transferred-bytes",
1460 G_CALLBACK (ft_transfer_transferred_bytes_cb), handler, 0);
1465 * empathy_ft_handler_cancel_transfer:
1466 * @handler: an #EmpathyFTHandler
1468 * Cancels an ongoing handler operation. Note that this doesn't destroy
1469 * the object, which will keep all the properties, altough it won't be able
1470 * to do any more I/O.
1473 empathy_ft_handler_cancel_transfer (EmpathyFTHandler *handler)
1475 EmpathyFTHandlerPriv *priv;
1477 g_return_if_fail (EMPATHY_IS_FT_HANDLER (handler));
1479 priv = GET_PRIV (handler);
1481 /* if we don't have a channel, we are hashing, so
1482 * we can just cancel the GCancellable to stop it.
1484 if (priv->channel == NULL)
1485 g_cancellable_cancel (priv->cancellable);
1487 tp_channel_close_async (TP_CHANNEL (priv->channel), NULL, NULL);
1491 * empathy_ft_handler_incoming_set_destination:
1492 * @handler: an #EmpathyFTHandler
1493 * @destination: the #GFile where the transfer should be saved
1495 * Sets the destination of the incoming handler to be @destination.
1496 * Note that calling this method is mandatory before starting the transfer
1497 * for incoming handlers.
1500 empathy_ft_handler_incoming_set_destination (EmpathyFTHandler *handler,
1503 EmpathyFTHandlerPriv *priv;
1505 g_return_if_fail (EMPATHY_IS_FT_HANDLER (handler));
1506 g_return_if_fail (G_IS_FILE (destination));
1508 priv = GET_PRIV (handler);
1510 g_object_set (handler, "gfile", destination, NULL);
1512 /* check if hash is supported. if it isn't, set use_hash to FALSE
1513 * anyway, so that clients won't be expecting us to checksum.
1515 if (EMP_STR_EMPTY (priv->content_hash) ||
1516 priv->content_hash_type == TP_FILE_HASH_TYPE_NONE)
1517 priv->use_hash = FALSE;
1519 priv->use_hash = TRUE;
1523 * empathy_ft_handler_get_filename:
1524 * @handler: an #EmpathyFTHandler
1526 * Returns the name of the file being transferred.
1528 * Return value: the name of the file being transferred
1531 empathy_ft_handler_get_filename (EmpathyFTHandler *handler)
1533 EmpathyFTHandlerPriv *priv;
1535 g_return_val_if_fail (EMPATHY_IS_FT_HANDLER (handler), NULL);
1537 priv = GET_PRIV (handler);
1539 return priv->filename;
1543 * empathy_ft_handler_get_content_type:
1544 * @handler: an #EmpathyFTHandler
1546 * Returns the content type of the file being transferred.
1548 * Return value: the content type of the file being transferred
1551 empathy_ft_handler_get_content_type (EmpathyFTHandler *handler)
1553 EmpathyFTHandlerPriv *priv;
1555 g_return_val_if_fail (EMPATHY_IS_FT_HANDLER (handler), NULL);
1557 priv = GET_PRIV (handler);
1559 return priv->content_type;
1563 * empathy_ft_handler_get_contact:
1564 * @handler: an #EmpathyFTHandler
1566 * Returns the remote #EmpathyContact at the other side of the transfer.
1568 * Return value: the remote #EmpathyContact for @handler
1571 empathy_ft_handler_get_contact (EmpathyFTHandler *handler)
1573 EmpathyFTHandlerPriv *priv;
1575 g_return_val_if_fail (EMPATHY_IS_FT_HANDLER (handler), NULL);
1577 priv = GET_PRIV (handler);
1579 return priv->contact;
1583 * empathy_ft_handler_get_gfile:
1584 * @handler: an #EmpathyFTHandler
1586 * Returns the #GFile where the transfer is being read/saved.
1588 * Return value: the #GFile where the transfer is being read/saved
1591 empathy_ft_handler_get_gfile (EmpathyFTHandler *handler)
1593 EmpathyFTHandlerPriv *priv;
1595 g_return_val_if_fail (EMPATHY_IS_FT_HANDLER (handler), NULL);
1597 priv = GET_PRIV (handler);
1603 * empathy_ft_handler_get_use_hash:
1604 * @handler: an #EmpathyFTHandler
1606 * Returns whether @handler has checksumming enabled. This can depend on
1607 * the CM and the remote contact capabilities.
1609 * Return value: %TRUE if the handler has checksumming enabled,
1613 empathy_ft_handler_get_use_hash (EmpathyFTHandler *handler)
1615 EmpathyFTHandlerPriv *priv;
1617 g_return_val_if_fail (EMPATHY_IS_FT_HANDLER (handler), FALSE);
1619 priv = GET_PRIV (handler);
1621 return priv->use_hash;
1625 * empathy_ft_handler_is_incoming:
1626 * @handler: an #EmpathyFTHandler
1628 * Returns whether @handler is incoming or outgoing.
1630 * Return value: %TRUE if the handler is incoming, %FALSE otherwise.
1633 empathy_ft_handler_is_incoming (EmpathyFTHandler *handler)
1635 EmpathyFTHandlerPriv *priv;
1637 g_return_val_if_fail (EMPATHY_IS_FT_HANDLER (handler), FALSE);
1639 priv = GET_PRIV (handler);
1641 if (priv->channel == NULL)
1644 return !tp_channel_get_requested ((TpChannel *) priv->channel);
1648 * empathy_ft_handler_get_transferred_bytes:
1649 * @handler: an #EmpathyFTHandler
1651 * Returns the number of bytes already transferred by the handler.
1653 * Return value: the number of bytes already transferred by the handler.
1656 empathy_ft_handler_get_transferred_bytes (EmpathyFTHandler *handler)
1658 EmpathyFTHandlerPriv *priv;
1660 g_return_val_if_fail (EMPATHY_IS_FT_HANDLER (handler), 0);
1662 priv = GET_PRIV (handler);
1664 return priv->transferred_bytes;
1668 * empathy_ft_handler_get_total_bytes:
1669 * @handler: an #EmpathyFTHandler
1671 * Returns the total size of the file being transferred by the handler.
1673 * Return value: a number of bytes indicating the total size of the file being
1674 * transferred by the handler.
1677 empathy_ft_handler_get_total_bytes (EmpathyFTHandler *handler)
1679 EmpathyFTHandlerPriv *priv;
1681 g_return_val_if_fail (EMPATHY_IS_FT_HANDLER (handler), 0);
1683 priv = GET_PRIV (handler);
1685 return priv->total_bytes;
1689 * empathy_ft_handler_is_completed:
1690 * @handler: an #EmpathyFTHandler
1692 * Returns whether the transfer for @handler has been completed succesfully.
1694 * Return value: %TRUE if the handler has been transferred correctly, %FALSE
1698 empathy_ft_handler_is_completed (EmpathyFTHandler *handler)
1700 EmpathyFTHandlerPriv *priv;
1702 g_return_val_if_fail (EMPATHY_IS_FT_HANDLER (handler), FALSE);
1704 priv = GET_PRIV (handler);
1706 return priv->is_completed;
1710 * empathy_ft_handler_is_cancelled:
1711 * @handler: an #EmpathyFTHandler
1713 * Returns whether the transfer for @handler has been cancelled or has stopped
1716 * Return value: %TRUE if the transfer for @handler has been cancelled
1717 * or has stopped due to an error, %FALSE otherwise.
1720 empathy_ft_handler_is_cancelled (EmpathyFTHandler *handler)
1722 EmpathyFTHandlerPriv *priv;
1724 g_return_val_if_fail (EMPATHY_IS_FT_HANDLER (handler), FALSE);
1726 priv = GET_PRIV (handler);
1728 return g_cancellable_is_cancelled (priv->cancellable);