2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
4
<!ENTITY version SYSTEM "version.xml">
6
<refentry id="EmpathyFTHandler">
8
<refentrytitle role="top_of_page" id="EmpathyFTHandler.top_of_page">EmpathyFTHandler</refentrytitle>
9
<manvolnum>3</manvolnum>
10
<refmiscinfo>LIBEMPATHY Library</refmiscinfo>
14
<refname>EmpathyFTHandler</refname>
15
<refpurpose>an object representing a File Transfer</refpurpose>
18
<refsynopsisdiv id="EmpathyFTHandler.synopsis" role="synopsis">
19
<title role="synopsis.title">Synopsis</title>
23
#include <libempathy/empathy-ft-handler>
25
<link linkend="EmpathyFTHandler-struct">EmpathyFTHandler</link>;
26
<link linkend="void">void</link> (<link linkend="EmpathyFTHandlerReadyCallback">*EmpathyFTHandlerReadyCallback</link>) (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler,
27
<link linkend="GError">GError</link> *error,
28
<link linkend="gpointer">gpointer</link> user_data);
29
<link linkend="void">void</link> <link linkend="empathy-ft-handler-new-outgoing">empathy_ft_handler_new_outgoing</link> (<link linkend="EmpathyContact">EmpathyContact</link> *contact,
30
<link linkend="GFile">GFile</link> *source,
31
<link linkend="EmpathyFTHandlerReadyCallback">EmpathyFTHandlerReadyCallback</link> callback,
32
<link linkend="gpointer">gpointer</link> user_data);
33
<link linkend="void">void</link> <link linkend="empathy-ft-handler-new-incoming">empathy_ft_handler_new_incoming</link> (<link linkend="EmpathyTpFile">EmpathyTpFile</link> *tp_file,
34
<link linkend="EmpathyFTHandlerReadyCallback">EmpathyFTHandlerReadyCallback</link> callback,
35
<link linkend="gpointer">gpointer</link> user_data);
36
<link linkend="void">void</link> <link linkend="empathy-ft-handler-incoming-set-destination">empathy_ft_handler_incoming_set_destination</link>
37
(<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler,
38
<link linkend="GFile">GFile</link> *destination);
39
<link linkend="void">void</link> <link linkend="empathy-ft-handler-start-transfer">empathy_ft_handler_start_transfer</link> (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler);
40
<link linkend="void">void</link> <link linkend="empathy-ft-handler-cancel-transfer">empathy_ft_handler_cancel_transfer</link> (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler);
41
const <link linkend="char">char</link> * <link linkend="empathy-ft-handler-get-filename">empathy_ft_handler_get_filename</link> (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler);
42
const <link linkend="char">char</link> * <link linkend="empathy-ft-handler-get-content-type">empathy_ft_handler_get_content_type</link> (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler);
43
<link linkend="EmpathyContact">EmpathyContact</link> * <link linkend="empathy-ft-handler-get-contact">empathy_ft_handler_get_contact</link> (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler);
44
<link linkend="GFile">GFile</link> * <link linkend="empathy-ft-handler-get-gfile">empathy_ft_handler_get_gfile</link> (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler);
45
<link linkend="gboolean">gboolean</link> <link linkend="empathy-ft-handler-get-use-hash">empathy_ft_handler_get_use_hash</link> (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler);
46
<link linkend="gboolean">gboolean</link> <link linkend="empathy-ft-handler-is-incoming">empathy_ft_handler_is_incoming</link> (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler);
47
<link linkend="guint64">guint64</link> <link linkend="empathy-ft-handler-get-transferred-bytes">empathy_ft_handler_get_transferred_bytes</link>
48
(<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler);
49
<link linkend="guint64">guint64</link> <link linkend="empathy-ft-handler-get-total-bytes">empathy_ft_handler_get_total_bytes</link> (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler);
50
<link linkend="gboolean">gboolean</link> <link linkend="empathy-ft-handler-is-completed">empathy_ft_handler_is_completed</link> (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler);
51
<link linkend="gboolean">gboolean</link> <link linkend="empathy-ft-handler-is-cancelled">empathy_ft_handler_is_cancelled</link> (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler);
55
<refsect1 id="EmpathyFTHandler.object-hierarchy" role="object_hierarchy">
56
<title role="object_hierarchy.title">Object Hierarchy</title>
58
<link linkend="GObject">GObject</link>
67
<refsect1 id="EmpathyFTHandler.properties" role="properties">
68
<title role="properties.title">Properties</title>
70
"<link linkend="EmpathyFTHandler--contact">contact</link>" <link linkend="EmpathyContact">EmpathyContact</link>* : Read / Write / Construct Only
71
"<link linkend="EmpathyFTHandler--content-type">content-type</link>" <link linkend="gchar">gchar</link>* : Read
72
"<link linkend="EmpathyFTHandler--description">description</link>" <link linkend="gchar">gchar</link>* : Read
73
"<link linkend="EmpathyFTHandler--filename">filename</link>" <link linkend="gchar">gchar</link>* : Read
74
"<link linkend="EmpathyFTHandler--gfile">gfile</link>" <link linkend="GFile">GFile</link>* : Read / Write
75
"<link linkend="EmpathyFTHandler--modification-time">modification-time</link>" <link linkend="guint64">guint64</link> : Read
76
"<link linkend="EmpathyFTHandler--total-bytes">total-bytes</link>" <link linkend="guint64">guint64</link> : Read
77
"<link linkend="EmpathyFTHandler--tp-file">tp-file</link>" <link linkend="EmpathyTpFile">EmpathyTpFile</link>* : Read / Write / Construct Only
78
"<link linkend="EmpathyFTHandler--transferred-bytes">transferred-bytes</link>" <link linkend="guint64">guint64</link> : Read
82
<refsect1 id="EmpathyFTHandler.signals" role="signal_proto">
83
<title role="signal_proto.title">Signals</title>
85
"<link linkend="EmpathyFTHandler-hashing-done">hashing-done</link>" : Run Last
86
"<link linkend="EmpathyFTHandler-hashing-progress">hashing-progress</link>" : Run Last
87
"<link linkend="EmpathyFTHandler-hashing-started">hashing-started</link>" : Run Last
88
"<link linkend="EmpathyFTHandler-transfer-done">transfer-done</link>" : Run Last
89
"<link linkend="EmpathyFTHandler-transfer-error">transfer-error</link>" : Run Last
90
"<link linkend="EmpathyFTHandler-transfer-progress">transfer-progress</link>" : Run Last
91
"<link linkend="EmpathyFTHandler-transfer-started">transfer-started</link>" : Run Last
96
<refsect1 id="EmpathyFTHandler.description" role="desc">
97
<title role="desc.title">Description</title>
99
<link linkend="EmpathyFTHandler"><type>EmpathyFTHandler</type></link> is the object which represents a File Transfer with all
101
The creation of an <link linkend="EmpathyFTHandler"><type>EmpathyFTHandler</type></link> is done with
102
<link linkend="empathy-ft-handler-new-outgoing"><function>empathy_ft_handler_new_outgoing()</function></link> or <link linkend="empathy-ft-handler-new-incoming"><function>empathy_ft_handler_new_incoming()</function></link>,
103
even though clients should not need to call them directly, as
104
<link linkend="EmpathyFTFactory"><type>EmpathyFTFactory</type></link> does it for them. Remember that for the file transfer
105
to work with an incoming handler,
106
<link linkend="empathy-ft-handler-incoming-set-destination"><function>empathy_ft_handler_incoming_set_destination()</function></link> should be called after
107
<link linkend="empathy-ft-handler-new-incoming"><function>empathy_ft_handler_new_incoming()</function></link>. <link linkend="EmpathyFTFactory"><type>EmpathyFTFactory</type></link> does this
109
It's important to note that, as the creation of the handlers is async, once
110
an handler is created, it already has all the interesting properties set,
111
like filename, total bytes, content type and so on, making it useful
112
to be displayed in an UI.
113
The transfer API works like a state machine; it has three signals,
114
::transfer-started, ::transfer-progress, ::transfer-done, which will be
115
emitted in the relevant phases.
116
In addition, if the handler is created with checksumming enabled,
117
other three signals (::hashing-started, ::hashing-progress, ::hashing-done)
118
will be emitted before or after the transfer, depending on the direction
119
(respectively outgoing and incoming) of the handler.
120
At any time between the call to <link linkend="empathy-ft-handler-start-transfer"><function>empathy_ft_handler_start_transfer()</function></link> and
121
the last signal, a ::transfer-error can be emitted, indicating that an
122
error has happened in the operation. The message of the error is localized
123
to use in an UI.</para>
128
<refsect1 id="EmpathyFTHandler.details" role="details">
129
<title role="details.title">Details</title>
130
<refsect2 id="EmpathyFTHandler-struct" role="struct">
131
<title>EmpathyFTHandler</title>
132
<indexterm zone="EmpathyFTHandler-struct"><primary sortas="EmpathyFTHandler">EmpathyFTHandler</primary></indexterm><programlisting>typedef struct _EmpathyFTHandler EmpathyFTHandler;</programlisting>
135
<refsect2 id="EmpathyFTHandlerReadyCallback" role="function">
136
<title>EmpathyFTHandlerReadyCallback ()</title>
137
<indexterm zone="EmpathyFTHandlerReadyCallback"><primary sortas="EmpathyFTHandlerReadyCallback">EmpathyFTHandlerReadyCallback</primary></indexterm><programlisting><link linkend="void">void</link> (*EmpathyFTHandlerReadyCallback) (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler,
138
<link linkend="GError">GError</link> *error,
139
<link linkend="gpointer">gpointer</link> user_data);</programlisting>
143
</para><variablelist role="params">
144
<varlistentry><term><parameter>handler</parameter> :</term>
145
<listitem><simpara> the handler which is now ready
146
</simpara></listitem></varlistentry>
147
<varlistentry><term><parameter>error</parameter> :</term>
148
<listitem><simpara> a <link linkend="GError"><type>GError</type></link> if the operation failed, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
149
</simpara></listitem></varlistentry>
150
<varlistentry><term><parameter>user_data</parameter> :</term>
151
<listitem><simpara> user data passed to the callback
152
</simpara></listitem></varlistentry>
153
</variablelist></refsect2>
154
<refsect2 id="empathy-ft-handler-new-outgoing" role="function">
155
<title>empathy_ft_handler_new_outgoing ()</title>
156
<indexterm zone="empathy-ft-handler-new-outgoing"><primary sortas="empathy_ft_handler_new_outgoing">empathy_ft_handler_new_outgoing</primary></indexterm><programlisting><link linkend="void">void</link> empathy_ft_handler_new_outgoing (<link linkend="EmpathyContact">EmpathyContact</link> *contact,
157
<link linkend="GFile">GFile</link> *source,
158
<link linkend="EmpathyFTHandlerReadyCallback">EmpathyFTHandlerReadyCallback</link> callback,
159
<link linkend="gpointer">gpointer</link> user_data);</programlisting>
161
Triggers the creation of a new <link linkend="EmpathyFTHandler"><type>EmpathyFTHandler</type></link> for an outgoing transfer.</para>
163
</para><variablelist role="params">
164
<varlistentry><term><parameter>contact</parameter> :</term>
165
<listitem><simpara> the <link linkend="EmpathyContact"><type>EmpathyContact</type></link> to send <parameter>source</parameter> to
166
</simpara></listitem></varlistentry>
167
<varlistentry><term><parameter>source</parameter> :</term>
168
<listitem><simpara> the <link linkend="GFile"><type>GFile</type></link> to send
169
</simpara></listitem></varlistentry>
170
<varlistentry><term><parameter>callback</parameter> :</term>
171
<listitem><simpara> callback to be called when the handler has been created
172
</simpara></listitem></varlistentry>
173
<varlistentry><term><parameter>user_data</parameter> :</term>
174
<listitem><simpara> user data to be passed to <parameter>callback</parameter>
175
</simpara></listitem></varlistentry>
176
</variablelist></refsect2>
177
<refsect2 id="empathy-ft-handler-new-incoming" role="function">
178
<title>empathy_ft_handler_new_incoming ()</title>
179
<indexterm zone="empathy-ft-handler-new-incoming"><primary sortas="empathy_ft_handler_new_incoming">empathy_ft_handler_new_incoming</primary></indexterm><programlisting><link linkend="void">void</link> empathy_ft_handler_new_incoming (<link linkend="EmpathyTpFile">EmpathyTpFile</link> *tp_file,
180
<link linkend="EmpathyFTHandlerReadyCallback">EmpathyFTHandlerReadyCallback</link> callback,
181
<link linkend="gpointer">gpointer</link> user_data);</programlisting>
183
Triggers the creation of a new <link linkend="EmpathyFTHandler"><type>EmpathyFTHandler</type></link> for an incoming transfer.
184
Note that for the handler to be useful, you will have to set a destination
185
file with <link linkend="empathy-ft-handler-incoming-set-destination"><function>empathy_ft_handler_incoming_set_destination()</function></link> after the handler
188
</para><variablelist role="params">
189
<varlistentry><term><parameter>tp_file</parameter> :</term>
190
<listitem><simpara> the <link linkend="EmpathyTpFile"><type>EmpathyTpFile</type></link> wrapping the incoming channel
191
</simpara></listitem></varlistentry>
192
<varlistentry><term><parameter>callback</parameter> :</term>
193
<listitem><simpara> callback to be called when the handler has been created
194
</simpara></listitem></varlistentry>
195
<varlistentry><term><parameter>user_data</parameter> :</term>
196
<listitem><simpara> user data to be passed to <parameter>callback</parameter>
197
</simpara></listitem></varlistentry>
198
</variablelist></refsect2>
199
<refsect2 id="empathy-ft-handler-incoming-set-destination" role="function">
200
<title>empathy_ft_handler_incoming_set_destination ()</title>
201
<indexterm zone="empathy-ft-handler-incoming-set-destination"><primary sortas="empathy_ft_handler_incoming_set_destination">empathy_ft_handler_incoming_set_destination</primary></indexterm><programlisting><link linkend="void">void</link> empathy_ft_handler_incoming_set_destination
202
(<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler,
203
<link linkend="GFile">GFile</link> *destination);</programlisting>
205
Sets the destination of the incoming handler to be <parameter>destination</parameter>.
206
Note that calling this method is mandatory before starting the transfer
207
for incoming handlers.</para>
209
</para><variablelist role="params">
210
<varlistentry><term><parameter>handler</parameter> :</term>
211
<listitem><simpara> an <link linkend="EmpathyFTHandler"><type>EmpathyFTHandler</type></link>
212
</simpara></listitem></varlistentry>
213
<varlistentry><term><parameter>destination</parameter> :</term>
214
<listitem><simpara> the <link linkend="GFile"><type>GFile</type></link> where the transfer should be saved
215
</simpara></listitem></varlistentry>
216
</variablelist></refsect2>
217
<refsect2 id="empathy-ft-handler-start-transfer" role="function">
218
<title>empathy_ft_handler_start_transfer ()</title>
219
<indexterm zone="empathy-ft-handler-start-transfer"><primary sortas="empathy_ft_handler_start_transfer">empathy_ft_handler_start_transfer</primary></indexterm><programlisting><link linkend="void">void</link> empathy_ft_handler_start_transfer (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler);</programlisting>
221
Starts the transfer machinery. After this call, the transfer and hashing
222
signals will be emitted by the handler.</para>
224
</para><variablelist role="params">
225
<varlistentry><term><parameter>handler</parameter> :</term>
226
<listitem><simpara> an <link linkend="EmpathyFTHandler"><type>EmpathyFTHandler</type></link>
227
</simpara></listitem></varlistentry>
228
</variablelist></refsect2>
229
<refsect2 id="empathy-ft-handler-cancel-transfer" role="function">
230
<title>empathy_ft_handler_cancel_transfer ()</title>
231
<indexterm zone="empathy-ft-handler-cancel-transfer"><primary sortas="empathy_ft_handler_cancel_transfer">empathy_ft_handler_cancel_transfer</primary></indexterm><programlisting><link linkend="void">void</link> empathy_ft_handler_cancel_transfer (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler);</programlisting>
233
Cancels an ongoing handler operation. Note that this doesn't destroy
234
the object, which will keep all the properties, altough it won't be able
235
to do any more I/O.</para>
237
</para><variablelist role="params">
238
<varlistentry><term><parameter>handler</parameter> :</term>
239
<listitem><simpara> an <link linkend="EmpathyFTHandler"><type>EmpathyFTHandler</type></link>
240
</simpara></listitem></varlistentry>
241
</variablelist></refsect2>
242
<refsect2 id="empathy-ft-handler-get-filename" role="function">
243
<title>empathy_ft_handler_get_filename ()</title>
244
<indexterm zone="empathy-ft-handler-get-filename"><primary sortas="empathy_ft_handler_get_filename">empathy_ft_handler_get_filename</primary></indexterm><programlisting>const <link linkend="char">char</link> * empathy_ft_handler_get_filename (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler);</programlisting>
246
Returns the name of the file being transferred.</para>
248
</para><variablelist role="params">
249
<varlistentry><term><parameter>handler</parameter> :</term>
250
<listitem><simpara> an <link linkend="EmpathyFTHandler"><type>EmpathyFTHandler</type></link>
251
</simpara></listitem></varlistentry>
252
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the name of the file being transferred
253
</simpara></listitem></varlistentry>
254
</variablelist></refsect2>
255
<refsect2 id="empathy-ft-handler-get-content-type" role="function">
256
<title>empathy_ft_handler_get_content_type ()</title>
257
<indexterm zone="empathy-ft-handler-get-content-type"><primary sortas="empathy_ft_handler_get_content_type">empathy_ft_handler_get_content_type</primary></indexterm><programlisting>const <link linkend="char">char</link> * empathy_ft_handler_get_content_type (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler);</programlisting>
259
Returns the content type of the file being transferred.</para>
261
</para><variablelist role="params">
262
<varlistentry><term><parameter>handler</parameter> :</term>
263
<listitem><simpara> an <link linkend="EmpathyFTHandler"><type>EmpathyFTHandler</type></link>
264
</simpara></listitem></varlistentry>
265
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the content type of the file being transferred
266
</simpara></listitem></varlistentry>
267
</variablelist></refsect2>
268
<refsect2 id="empathy-ft-handler-get-contact" role="function">
269
<title>empathy_ft_handler_get_contact ()</title>
270
<indexterm zone="empathy-ft-handler-get-contact"><primary sortas="empathy_ft_handler_get_contact">empathy_ft_handler_get_contact</primary></indexterm><programlisting><link linkend="EmpathyContact">EmpathyContact</link> * empathy_ft_handler_get_contact (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler);</programlisting>
272
Returns the remote <link linkend="EmpathyContact"><type>EmpathyContact</type></link> at the other side of the transfer.</para>
274
</para><variablelist role="params">
275
<varlistentry><term><parameter>handler</parameter> :</term>
276
<listitem><simpara> an <link linkend="EmpathyFTHandler"><type>EmpathyFTHandler</type></link>
277
</simpara></listitem></varlistentry>
278
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the remote <link linkend="EmpathyContact"><type>EmpathyContact</type></link> for <parameter>handler</parameter>
279
</simpara></listitem></varlistentry>
280
</variablelist></refsect2>
281
<refsect2 id="empathy-ft-handler-get-gfile" role="function">
282
<title>empathy_ft_handler_get_gfile ()</title>
283
<indexterm zone="empathy-ft-handler-get-gfile"><primary sortas="empathy_ft_handler_get_gfile">empathy_ft_handler_get_gfile</primary></indexterm><programlisting><link linkend="GFile">GFile</link> * empathy_ft_handler_get_gfile (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler);</programlisting>
285
Returns the <link linkend="GFile"><type>GFile</type></link> where the transfer is being read/saved.</para>
287
</para><variablelist role="params">
288
<varlistentry><term><parameter>handler</parameter> :</term>
289
<listitem><simpara> an <link linkend="EmpathyFTHandler"><type>EmpathyFTHandler</type></link>
290
</simpara></listitem></varlistentry>
291
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the <link linkend="GFile"><type>GFile</type></link> where the transfer is being read/saved
292
</simpara></listitem></varlistentry>
293
</variablelist></refsect2>
294
<refsect2 id="empathy-ft-handler-get-use-hash" role="function">
295
<title>empathy_ft_handler_get_use_hash ()</title>
296
<indexterm zone="empathy-ft-handler-get-use-hash"><primary sortas="empathy_ft_handler_get_use_hash">empathy_ft_handler_get_use_hash</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> empathy_ft_handler_get_use_hash (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler);</programlisting>
298
Returns whether <parameter>handler</parameter> has checksumming enabled. This can depend on
299
the CM and the remote contact capabilities.</para>
301
</para><variablelist role="params">
302
<varlistentry><term><parameter>handler</parameter> :</term>
303
<listitem><simpara> an <link linkend="EmpathyFTHandler"><type>EmpathyFTHandler</type></link>
304
</simpara></listitem></varlistentry>
305
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the handler has checksumming enabled,
306
<link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise.
307
</simpara></listitem></varlistentry>
308
</variablelist></refsect2>
309
<refsect2 id="empathy-ft-handler-is-incoming" role="function">
310
<title>empathy_ft_handler_is_incoming ()</title>
311
<indexterm zone="empathy-ft-handler-is-incoming"><primary sortas="empathy_ft_handler_is_incoming">empathy_ft_handler_is_incoming</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> empathy_ft_handler_is_incoming (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler);</programlisting>
313
Returns whether <parameter>handler</parameter> is incoming or outgoing.</para>
315
</para><variablelist role="params">
316
<varlistentry><term><parameter>handler</parameter> :</term>
317
<listitem><simpara> an <link linkend="EmpathyFTHandler"><type>EmpathyFTHandler</type></link>
318
</simpara></listitem></varlistentry>
319
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the handler is incoming, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise.
320
</simpara></listitem></varlistentry>
321
</variablelist></refsect2>
322
<refsect2 id="empathy-ft-handler-get-transferred-bytes" role="function">
323
<title>empathy_ft_handler_get_transferred_bytes ()</title>
324
<indexterm zone="empathy-ft-handler-get-transferred-bytes"><primary sortas="empathy_ft_handler_get_transferred_bytes">empathy_ft_handler_get_transferred_bytes</primary></indexterm><programlisting><link linkend="guint64">guint64</link> empathy_ft_handler_get_transferred_bytes
325
(<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler);</programlisting>
327
Returns the number of bytes already transferred by the handler.</para>
329
</para><variablelist role="params">
330
<varlistentry><term><parameter>handler</parameter> :</term>
331
<listitem><simpara> an <link linkend="EmpathyFTHandler"><type>EmpathyFTHandler</type></link>
332
</simpara></listitem></varlistentry>
333
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the number of bytes already transferred by the handler.
334
</simpara></listitem></varlistentry>
335
</variablelist></refsect2>
336
<refsect2 id="empathy-ft-handler-get-total-bytes" role="function">
337
<title>empathy_ft_handler_get_total_bytes ()</title>
338
<indexterm zone="empathy-ft-handler-get-total-bytes"><primary sortas="empathy_ft_handler_get_total_bytes">empathy_ft_handler_get_total_bytes</primary></indexterm><programlisting><link linkend="guint64">guint64</link> empathy_ft_handler_get_total_bytes (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler);</programlisting>
340
Returns the total size of the file being transferred by the handler.</para>
342
</para><variablelist role="params">
343
<varlistentry><term><parameter>handler</parameter> :</term>
344
<listitem><simpara> an <link linkend="EmpathyFTHandler"><type>EmpathyFTHandler</type></link>
345
</simpara></listitem></varlistentry>
346
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a number of bytes indicating the total size of the file being
347
transferred by the handler.
348
</simpara></listitem></varlistentry>
349
</variablelist></refsect2>
350
<refsect2 id="empathy-ft-handler-is-completed" role="function">
351
<title>empathy_ft_handler_is_completed ()</title>
352
<indexterm zone="empathy-ft-handler-is-completed"><primary sortas="empathy_ft_handler_is_completed">empathy_ft_handler_is_completed</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> empathy_ft_handler_is_completed (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler);</programlisting>
354
Returns whether the transfer for <parameter>handler</parameter> has been completed succesfully.</para>
356
</para><variablelist role="params">
357
<varlistentry><term><parameter>handler</parameter> :</term>
358
<listitem><simpara> an <link linkend="EmpathyFTHandler"><type>EmpathyFTHandler</type></link>
359
</simpara></listitem></varlistentry>
360
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the handler has been transferred correctly, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>
362
</simpara></listitem></varlistentry>
363
</variablelist></refsect2>
364
<refsect2 id="empathy-ft-handler-is-cancelled" role="function">
365
<title>empathy_ft_handler_is_cancelled ()</title>
366
<indexterm zone="empathy-ft-handler-is-cancelled"><primary sortas="empathy_ft_handler_is_cancelled">empathy_ft_handler_is_cancelled</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> empathy_ft_handler_is_cancelled (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler);</programlisting>
368
Returns whether the transfer for <parameter>handler</parameter> has been cancelled or has stopped
369
due to an error.</para>
371
</para><variablelist role="params">
372
<varlistentry><term><parameter>handler</parameter> :</term>
373
<listitem><simpara> an <link linkend="EmpathyFTHandler"><type>EmpathyFTHandler</type></link>
374
</simpara></listitem></varlistentry>
375
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the transfer for <parameter>handler</parameter> has been cancelled
376
or has stopped due to an error, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise.
377
</simpara></listitem></varlistentry>
378
</variablelist></refsect2>
381
<refsect1 id="EmpathyFTHandler.property-details" role="property_details">
382
<title role="property_details.title">Property Details</title>
383
<refsect2 id="EmpathyFTHandler--contact" role="property"><title>The <literal>"contact"</literal> property</title>
384
<indexterm zone="EmpathyFTHandler--contact"><primary sortas="EmpathyFTHandler:contact">EmpathyFTHandler:contact</primary></indexterm><programlisting> "contact" <link linkend="EmpathyContact">EmpathyContact</link>* : Read / Write / Construct Only</programlisting>
386
The remote <link linkend="EmpathyContact"><type>EmpathyContact</type></link> for the transfer</para>
389
<refsect2 id="EmpathyFTHandler--content-type" role="property"><title>The <literal>"content-type"</literal> property</title>
390
<indexterm zone="EmpathyFTHandler--content-type"><primary sortas="EmpathyFTHandler:content-type">EmpathyFTHandler:content-type</primary></indexterm><programlisting> "content-type" <link linkend="gchar">gchar</link>* : Read</programlisting>
392
The content type of the file being transferred</para>
394
</para><para>Default value: NULL</para>
396
<refsect2 id="EmpathyFTHandler--description" role="property"><title>The <literal>"description"</literal> property</title>
397
<indexterm zone="EmpathyFTHandler--description"><primary sortas="EmpathyFTHandler:description">EmpathyFTHandler:description</primary></indexterm><programlisting> "description" <link linkend="gchar">gchar</link>* : Read</programlisting>
399
The description of the file being transferred</para>
401
</para><para>Default value: NULL</para>
403
<refsect2 id="EmpathyFTHandler--filename" role="property"><title>The <literal>"filename"</literal> property</title>
404
<indexterm zone="EmpathyFTHandler--filename"><primary sortas="EmpathyFTHandler:filename">EmpathyFTHandler:filename</primary></indexterm><programlisting> "filename" <link linkend="gchar">gchar</link>* : Read</programlisting>
406
The name of the file being transferred</para>
408
</para><para>Default value: NULL</para>
410
<refsect2 id="EmpathyFTHandler--gfile" role="property"><title>The <literal>"gfile"</literal> property</title>
411
<indexterm zone="EmpathyFTHandler--gfile"><primary sortas="EmpathyFTHandler:gfile">EmpathyFTHandler:gfile</primary></indexterm><programlisting> "gfile" <link linkend="GFile">GFile</link>* : Read / Write</programlisting>
413
The <link linkend="GFile"><type>GFile</type></link> object where the transfer actually happens</para>
416
<refsect2 id="EmpathyFTHandler--modification-time" role="property"><title>The <literal>"modification-time"</literal> property</title>
417
<indexterm zone="EmpathyFTHandler--modification-time"><primary sortas="EmpathyFTHandler:modification-time">EmpathyFTHandler:modification-time</primary></indexterm><programlisting> "modification-time" <link linkend="guint64">guint64</link> : Read</programlisting>
419
The modification time of the file being transferred</para>
421
</para><para>Default value: 0</para>
423
<refsect2 id="EmpathyFTHandler--total-bytes" role="property"><title>The <literal>"total-bytes"</literal> property</title>
424
<indexterm zone="EmpathyFTHandler--total-bytes"><primary sortas="EmpathyFTHandler:total-bytes">EmpathyFTHandler:total-bytes</primary></indexterm><programlisting> "total-bytes" <link linkend="guint64">guint64</link> : Read</programlisting>
426
The size (in bytes) of the file being transferred</para>
428
</para><para>Default value: 0</para>
430
<refsect2 id="EmpathyFTHandler--tp-file" role="property"><title>The <literal>"tp-file"</literal> property</title>
431
<indexterm zone="EmpathyFTHandler--tp-file"><primary sortas="EmpathyFTHandler:tp-file">EmpathyFTHandler:tp-file</primary></indexterm><programlisting> "tp-file" <link linkend="EmpathyTpFile">EmpathyTpFile</link>* : Read / Write / Construct Only</programlisting>
433
The underlying <link linkend="EmpathyTpFile"><type>EmpathyTpFile</type></link> managing the transfer</para>
436
<refsect2 id="EmpathyFTHandler--transferred-bytes" role="property"><title>The <literal>"transferred-bytes"</literal> property</title>
437
<indexterm zone="EmpathyFTHandler--transferred-bytes"><primary sortas="EmpathyFTHandler:transferred-bytes">EmpathyFTHandler:transferred-bytes</primary></indexterm><programlisting> "transferred-bytes" <link linkend="guint64">guint64</link> : Read</programlisting>
439
The number of the bytes already transferred</para>
441
</para><para>Default value: 0</para>
445
<refsect1 id="EmpathyFTHandler.signal-details" role="signals">
446
<title role="signals.title">Signal Details</title>
447
<refsect2 id="EmpathyFTHandler-hashing-done" role="signal"><title>The <literal>"hashing-done"</literal> signal</title>
448
<indexterm zone="EmpathyFTHandler-hashing-done"><primary sortas="EmpathyFTHandler::hashing-done">EmpathyFTHandler::hashing-done</primary></indexterm><programlisting><link linkend="void">void</link> user_function (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler,
449
<link linkend="gpointer">gpointer</link> user_data) : Run Last</programlisting>
451
This signal is emitted when the hashing operation of the handler
454
</para><variablelist role="params">
455
<varlistentry><term><parameter>handler</parameter> :</term>
456
<listitem><simpara> the object which has received the signal
457
</simpara></listitem></varlistentry>
458
<varlistentry><term><parameter>user_data</parameter> :</term>
459
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
460
</variablelist></refsect2><refsect2 id="EmpathyFTHandler-hashing-progress" role="signal"><title>The <literal>"hashing-progress"</literal> signal</title>
461
<indexterm zone="EmpathyFTHandler-hashing-progress"><primary sortas="EmpathyFTHandler::hashing-progress">EmpathyFTHandler::hashing-progress</primary></indexterm><programlisting><link linkend="void">void</link> user_function (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler,
462
<link linkend="guint64">guint64</link> current_bytes,
463
<link linkend="guint64">guint64</link> total_bytes,
464
<link linkend="gpointer">gpointer</link> user_data) : Run Last</programlisting>
466
This signal is emitted to notify clients of the progress of the
467
hashing operation.</para>
469
</para><variablelist role="params">
470
<varlistentry><term><parameter>handler</parameter> :</term>
471
<listitem><simpara> the object which has received the signal
472
</simpara></listitem></varlistentry>
473
<varlistentry><term><parameter>current_bytes</parameter> :</term>
474
<listitem><simpara> the bytes currently hashed
475
</simpara></listitem></varlistentry>
476
<varlistentry><term><parameter>total_bytes</parameter> :</term>
477
<listitem><simpara> the total bytes of the handler
478
</simpara></listitem></varlistentry>
479
<varlistentry><term><parameter>user_data</parameter> :</term>
480
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
481
</variablelist></refsect2><refsect2 id="EmpathyFTHandler-hashing-started" role="signal"><title>The <literal>"hashing-started"</literal> signal</title>
482
<indexterm zone="EmpathyFTHandler-hashing-started"><primary sortas="EmpathyFTHandler::hashing-started">EmpathyFTHandler::hashing-started</primary></indexterm><programlisting><link linkend="void">void</link> user_function (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler,
483
<link linkend="gpointer">gpointer</link> user_data) : Run Last</programlisting>
485
This signal is emitted when the hashing operation of the handler
486
is started. Note that this might happen or not, depending on the CM
487
and remote contact capabilities. Clients shoud use
488
<link linkend="empathy-ft-handler-get-use-hash"><function>empathy_ft_handler_get_use_hash()</function></link> before calling
489
<link linkend="empathy-ft-handler-start-transfer"><function>empathy_ft_handler_start_transfer()</function></link> to know whether they should connect
490
to this signal.</para>
492
</para><variablelist role="params">
493
<varlistentry><term><parameter>handler</parameter> :</term>
494
<listitem><simpara> the object which has received the signal
495
</simpara></listitem></varlistentry>
496
<varlistentry><term><parameter>user_data</parameter> :</term>
497
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
498
</variablelist></refsect2><refsect2 id="EmpathyFTHandler-transfer-done" role="signal"><title>The <literal>"transfer-done"</literal> signal</title>
499
<indexterm zone="EmpathyFTHandler-transfer-done"><primary sortas="EmpathyFTHandler::transfer-done">EmpathyFTHandler::transfer-done</primary></indexterm><programlisting><link linkend="void">void</link> user_function (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler,
500
<link linkend="EmpathyTpFile">EmpathyTpFile</link> *tp_file,
501
<link linkend="gpointer">gpointer</link> user_data) : Run Last</programlisting>
503
This signal will be emitted when the actual transfer is completed
506
</para><variablelist role="params">
507
<varlistentry><term><parameter>handler</parameter> :</term>
508
<listitem><simpara> the object which has received the signal
509
</simpara></listitem></varlistentry>
510
<varlistentry><term><parameter>tp_file</parameter> :</term>
511
<listitem><simpara> the <link linkend="EmpathyTpFile"><type>EmpathyTpFile</type></link> for which the transfer has started
512
</simpara></listitem></varlistentry>
513
<varlistentry><term><parameter>user_data</parameter> :</term>
514
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
515
</variablelist></refsect2><refsect2 id="EmpathyFTHandler-transfer-error" role="signal"><title>The <literal>"transfer-error"</literal> signal</title>
516
<indexterm zone="EmpathyFTHandler-transfer-error"><primary sortas="EmpathyFTHandler::transfer-error">EmpathyFTHandler::transfer-error</primary></indexterm><programlisting><link linkend="void">void</link> user_function (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler,
517
<link linkend="gpointer">gpointer</link> error,
518
<link linkend="gpointer">gpointer</link> user_data) : Run Last</programlisting>
520
This signal can be emitted anytime between the call to
521
<link linkend="empathy-ft-handler-start-transfer"><function>empathy_ft_handler_start_transfer()</function></link> and the last expected signal
522
(::transfer-done or ::hashing-done), and it's guaranteed to be the last
523
signal coming from the handler, meaning that no other operation will
524
take place after this signal.</para>
526
</para><variablelist role="params">
527
<varlistentry><term><parameter>handler</parameter> :</term>
528
<listitem><simpara> the object which has received the signal
529
</simpara></listitem></varlistentry>
530
<varlistentry><term><parameter>error</parameter> :</term>
531
<listitem><simpara> a <link linkend="GError"><type>GError</type></link>
532
</simpara></listitem></varlistentry>
533
<varlistentry><term><parameter>user_data</parameter> :</term>
534
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
535
</variablelist></refsect2><refsect2 id="EmpathyFTHandler-transfer-progress" role="signal"><title>The <literal>"transfer-progress"</literal> signal</title>
536
<indexterm zone="EmpathyFTHandler-transfer-progress"><primary sortas="EmpathyFTHandler::transfer-progress">EmpathyFTHandler::transfer-progress</primary></indexterm><programlisting><link linkend="void">void</link> user_function (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler,
537
<link linkend="guint64">guint64</link> current_bytes,
538
<link linkend="guint64">guint64</link> total_bytes,
539
<link linkend="guint">guint</link> remaining_time,
540
<link linkend="gdouble">gdouble</link> speed,
541
<link linkend="gpointer">gpointer</link> user_data) : Run Last</programlisting>
543
This signal is emitted to notify clients of the progress of the
546
</para><variablelist role="params">
547
<varlistentry><term><parameter>handler</parameter> :</term>
548
<listitem><simpara> the object which has received the signal
549
</simpara></listitem></varlistentry>
550
<varlistentry><term><parameter>current_bytes</parameter> :</term>
551
<listitem><simpara> the bytes currently transferred
552
</simpara></listitem></varlistentry>
553
<varlistentry><term><parameter>total_bytes</parameter> :</term>
554
<listitem><simpara> the total bytes of the handler
555
</simpara></listitem></varlistentry>
556
<varlistentry><term><parameter>remaining_time</parameter> :</term>
557
<listitem><simpara> the number of seconds remaining for the transfer
559
</simpara></listitem></varlistentry>
560
<varlistentry><term><parameter>speed</parameter> :</term>
561
<listitem><simpara> the current speed of the transfer (in KB/s)
562
</simpara></listitem></varlistentry>
563
<varlistentry><term><parameter>user_data</parameter> :</term>
564
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
565
</variablelist></refsect2><refsect2 id="EmpathyFTHandler-transfer-started" role="signal"><title>The <literal>"transfer-started"</literal> signal</title>
566
<indexterm zone="EmpathyFTHandler-transfer-started"><primary sortas="EmpathyFTHandler::transfer-started">EmpathyFTHandler::transfer-started</primary></indexterm><programlisting><link linkend="void">void</link> user_function (<link linkend="EmpathyFTHandler">EmpathyFTHandler</link> *handler,
567
<link linkend="EmpathyTpFile">EmpathyTpFile</link> *tp_file,
568
<link linkend="gpointer">gpointer</link> user_data) : Run Last</programlisting>
570
This signal is emitted when the actual transfer starts.</para>
572
</para><variablelist role="params">
573
<varlistentry><term><parameter>handler</parameter> :</term>
574
<listitem><simpara> the object which has received the signal
575
</simpara></listitem></varlistentry>
576
<varlistentry><term><parameter>tp_file</parameter> :</term>
577
<listitem><simpara> the <link linkend="EmpathyTpFile"><type>EmpathyTpFile</type></link> for which the transfer has started
578
</simpara></listitem></varlistentry>
579
<varlistentry><term><parameter>user_data</parameter> :</term>
580
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
581
</variablelist></refsect2>
added
removed
docs/libempathy/xml/empathy-ft-handler.xml
