← Back to branch summary

~bcurtiswx/ubuntu/precise/empathy/3.4.2.1-0ubuntu1

« back to all changes in this revision

Viewing changes to docs/libempathy/xml/empathy-tp-file.xml

  • Committer: Bazaar Package Importer
  • Author(s): Laurent Bigonville
  • Date: 2009-11-16 23:40:52 UTC
  • mfrom: (1.1.39 upstream)
  • mto: (6.3.7 experimental)
  • mto: This revision was merged to the branch mainline in revision 80.
  • Revision ID: james.westby@ubuntu.com-20091116234052-7hhwrpeln4mwdyw7
Tags: upstream-2.29.2
Import upstream version 2.29.2

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/libempathy/xml/empathy-tp-file.xml
1
 
<?xml version="1.0"?>
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">
5
 
]>
6
 
<refentry id="EmpathyTpFile">
7
 
<refmeta>
8
 
<refentrytitle role="top_of_page" id="EmpathyTpFile.top_of_page">EmpathyTpFile</refentrytitle>
9
 
<manvolnum>3</manvolnum>
10
 
<refmiscinfo>LIBEMPATHY Library</refmiscinfo>
11
 
</refmeta>
12
 
 
13
 
<refnamediv>
14
 
<refname>EmpathyTpFile</refname>
15
 
<refpurpose>Object which represents a Telepathy file channel</refpurpose>
16
 
</refnamediv>
17
 
 
18
 
<refsynopsisdiv id="EmpathyTpFile.synopsis" role="synopsis">
19
 
<title role="synopsis.title">Synopsis</title>
20
 
 
21
 
<synopsis>
22
 
 
23
 
#include &lt;libempathy/empathy-tp-file.h&gt;
24
 
 
25
 
                    <link linkend="EmpathyTpFile-struct">EmpathyTpFile</link>;
26
 
<link linkend="EmpathyTpFile">EmpathyTpFile</link> *     <link linkend="empathy-tp-file-new">empathy_tp_file_new</link>                 (<link linkend="TpChannel">TpChannel</link> *channel,
27
 
                                                         <link linkend="gboolean">gboolean</link> incoming);
28
 
<link linkend="void">void</link>                <link linkend="empathy-tp-file-accept">empathy_tp_file_accept</link>              (<link linkend="EmpathyTpFile">EmpathyTpFile</link> *tp_file,
29
 
                                                         <link linkend="guint64">guint64</link> offset,
30
 
                                                         <link linkend="GFile">GFile</link> *gfile,
31
 
                                                         <link linkend="GCancellable">GCancellable</link> *cancellable,
32
 
                                                         <link linkend="EmpathyTpFileProgressCallback">EmpathyTpFileProgressCallback</link> progress_callback,
33
 
                                                         <link linkend="gpointer">gpointer</link> progress_user_data,
34
 
                                                         <link linkend="EmpathyTpFileOperationCallback">EmpathyTpFileOperationCallback</link> op_callback,
35
 
                                                         <link linkend="gpointer">gpointer</link> op_user_data);
36
 
<link linkend="void">void</link>                <link linkend="empathy-tp-file-cancel">empathy_tp_file_cancel</link>              (<link linkend="EmpathyTpFile">EmpathyTpFile</link> *tp_file);
37
 
<link linkend="void">void</link>                <link linkend="empathy-tp-file-close">empathy_tp_file_close</link>               (<link linkend="EmpathyTpFile">EmpathyTpFile</link> *tp_file);
38
 
<link linkend="void">void</link>                <link linkend="empathy-tp-file-offer">empathy_tp_file_offer</link>               (<link linkend="EmpathyTpFile">EmpathyTpFile</link> *tp_file,
39
 
                                                         <link linkend="GFile">GFile</link> *gfile,
40
 
                                                         <link linkend="GCancellable">GCancellable</link> *cancellable,
41
 
                                                         <link linkend="EmpathyTpFileProgressCallback">EmpathyTpFileProgressCallback</link> progress_callback,
42
 
                                                         <link linkend="gpointer">gpointer</link> progress_user_data,
43
 
                                                         <link linkend="EmpathyTpFileOperationCallback">EmpathyTpFileOperationCallback</link> op_callback,
44
 
                                                         <link linkend="gpointer">gpointer</link> op_user_data);
45
 
<link linkend="gboolean">gboolean</link>            <link linkend="empathy-tp-file-is-incoming">empathy_tp_file_is_incoming</link>         (<link linkend="EmpathyTpFile">EmpathyTpFile</link> *tp_file);
46
 
</synopsis>
47
 
</refsynopsisdiv>
48
 
 
49
 
<refsect1 id="EmpathyTpFile.object-hierarchy" role="object_hierarchy">
50
 
<title role="object_hierarchy.title">Object Hierarchy</title>
51
 
<synopsis>
52
 
  <link linkend="GObject">GObject</link>
53
 
   +----EmpathyTpFile
54
 
</synopsis>
55
 
</refsect1>
56
 
 
57
 
 
58
 
 
59
 
 
60
 
 
61
 
<refsect1 id="EmpathyTpFile.properties" role="properties">
62
 
<title role="properties.title">Properties</title>
63
 
<synopsis>
64
 
  &quot;<link linkend="EmpathyTpFile--channel">channel</link>&quot;                  <link linkend="TpChannel">TpChannel</link>*            : Read / Write / Construct Only
65
 
  &quot;<link linkend="EmpathyTpFile--incoming">incoming</link>&quot;                 <link linkend="gboolean">gboolean</link>              : Read / Write / Construct Only
66
 
</synopsis>
67
 
</refsect1>
68
 
 
69
 
 
70
 
 
71
 
<refsect1 id="EmpathyTpFile.description" role="desc">
72
 
<title role="desc.title">Description</title>
73
 
<para>
74
 
<link linkend="EmpathyTpFile"><type>EmpathyTpFile</type></link> is an object which represents a Telepathy file channel.
75
 
Usually, clients do not need to deal with <link linkend="EmpathyTpFile"><type>EmpathyTpFile</type></link> objects directly,
76
 
and are supposed to use <link linkend="EmpathyFTHandler"><type>EmpathyFTHandler</type></link> and <link linkend="EmpathyFTFactory"><type>EmpathyFTFactory</type></link> for
77
 
transferring files using libempathy.</para>
78
 
<para>
79
 
</para>
80
 
</refsect1>
81
 
 
82
 
<refsect1 id="EmpathyTpFile.details" role="details">
83
 
<title role="details.title">Details</title>
84
 
<refsect2 id="EmpathyTpFile-struct" role="struct">
85
 
<title>EmpathyTpFile</title>
86
 
<indexterm zone="EmpathyTpFile-struct"><primary sortas="EmpathyTpFile">EmpathyTpFile</primary></indexterm><programlisting>typedef struct _EmpathyTpFile EmpathyTpFile;</programlisting>
87
 
<para>
88
 
</para></refsect2>
89
 
<refsect2 id="empathy-tp-file-new" role="function">
90
 
<title>empathy_tp_file_new ()</title>
91
 
<indexterm zone="empathy-tp-file-new"><primary sortas="empathy_tp_file_new">empathy_tp_file_new</primary></indexterm><programlisting><link linkend="EmpathyTpFile">EmpathyTpFile</link> *     empathy_tp_file_new                 (<link linkend="TpChannel">TpChannel</link> *channel,
92
 
                                                         <link linkend="gboolean">gboolean</link> incoming);</programlisting>
93
 
<para>
94
 
Creates a new <link linkend="EmpathyTpFile"><type>EmpathyTpFile</type></link> wrapping <parameter>channel</parameter>, with the direction
95
 
specified by <parameter>incoming</parameter>. The returned <link linkend="EmpathyTpFile"><type>EmpathyTpFile</type></link> should be unrefed
96
 
with <link linkend="g-object-unref"><function>g_object_unref()</function></link> when finished with.</para>
97
 
<para>
98
 
</para><variablelist role="params">
99
 
<varlistentry><term><parameter>channel</parameter>&#160;:</term>
100
 
<listitem><simpara> a <link linkend="TpChannel"><type>TpChannel</type></link>
101
 
</simpara></listitem></varlistentry>
102
 
<varlistentry><term><parameter>incoming</parameter>&#160;:</term>
103
 
<listitem><simpara> whether the file transfer is incoming or not
104
 
</simpara></listitem></varlistentry>
105
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a new <link linkend="EmpathyTpFile"><type>EmpathyTpFile</type></link>
106
 
</simpara></listitem></varlistentry>
107
 
</variablelist></refsect2>
108
 
<refsect2 id="empathy-tp-file-accept" role="function">
109
 
<title>empathy_tp_file_accept ()</title>
110
 
<indexterm zone="empathy-tp-file-accept"><primary sortas="empathy_tp_file_accept">empathy_tp_file_accept</primary></indexterm><programlisting><link linkend="void">void</link>                empathy_tp_file_accept              (<link linkend="EmpathyTpFile">EmpathyTpFile</link> *tp_file,
111
 
                                                         <link linkend="guint64">guint64</link> offset,
112
 
                                                         <link linkend="GFile">GFile</link> *gfile,
113
 
                                                         <link linkend="GCancellable">GCancellable</link> *cancellable,
114
 
                                                         <link linkend="EmpathyTpFileProgressCallback">EmpathyTpFileProgressCallback</link> progress_callback,
115
 
                                                         <link linkend="gpointer">gpointer</link> progress_user_data,
116
 
                                                         <link linkend="EmpathyTpFileOperationCallback">EmpathyTpFileOperationCallback</link> op_callback,
117
 
                                                         <link linkend="gpointer">gpointer</link> op_user_data);</programlisting>
118
 
<para>
119
 
Accepts an incoming file transfer, saving the result into <parameter>gfile</parameter>.
120
 
The callback <parameter>op_callback</parameter> will be called both when the transfer is
121
 
successful and in case of an error. Note that cancelling <parameter>cancellable</parameter>,
122
 
closes the socket of the file operation in progress, but doesn't
123
 
guarantee that the transfer channel will be closed as well. Thus,
124
 
<link linkend="empathy-tp-file-cancel"><function>empathy_tp_file_cancel()</function></link> or <link linkend="empathy-tp-file-close"><function>empathy_tp_file_close()</function></link> should be used to
125
 
actually cancel an ongoing <link linkend="EmpathyTpFile"><type>EmpathyTpFile</type></link>.</para>
126
 
<para>
127
 
</para><variablelist role="params">
128
 
<varlistentry><term><parameter>tp_file</parameter>&#160;:</term>
129
 
<listitem><simpara> an incoming <link linkend="EmpathyTpFile"><type>EmpathyTpFile</type></link>
130
 
</simpara></listitem></varlistentry>
131
 
<varlistentry><term><parameter>offset</parameter>&#160;:</term>
132
 
<listitem><simpara> the offset of <parameter>gfile</parameter> where we should start writing
133
 
</simpara></listitem></varlistentry>
134
 
<varlistentry><term><parameter>gfile</parameter>&#160;:</term>
135
 
<listitem><simpara> the destination <link linkend="GFile"><type>GFile</type></link> for the transfer
136
 
</simpara></listitem></varlistentry>
137
 
<varlistentry><term><parameter>cancellable</parameter>&#160;:</term>
138
 
<listitem><simpara> a <link linkend="GCancellable"><type>GCancellable</type></link>
139
 
</simpara></listitem></varlistentry>
140
 
<varlistentry><term><parameter>progress_callback</parameter>&#160;:</term>
141
 
<listitem><simpara> function to callback with progress information
142
 
</simpara></listitem></varlistentry>
143
 
<varlistentry><term><parameter>progress_user_data</parameter>&#160;:</term>
144
 
<listitem><simpara> user_data to pass to <parameter>progress_callback</parameter>
145
 
</simpara></listitem></varlistentry>
146
 
<varlistentry><term><parameter>op_callback</parameter>&#160;:</term>
147
 
<listitem><simpara> function to callback when the transfer ends
148
 
</simpara></listitem></varlistentry>
149
 
<varlistentry><term><parameter>op_user_data</parameter>&#160;:</term>
150
 
<listitem><simpara> user_data to pass to <parameter>op_callback</parameter>
151
 
</simpara></listitem></varlistentry>
152
 
</variablelist></refsect2>
153
 
<refsect2 id="empathy-tp-file-cancel" role="function">
154
 
<title>empathy_tp_file_cancel ()</title>
155
 
<indexterm zone="empathy-tp-file-cancel"><primary sortas="empathy_tp_file_cancel">empathy_tp_file_cancel</primary></indexterm><programlisting><link linkend="void">void</link>                empathy_tp_file_cancel              (<link linkend="EmpathyTpFile">EmpathyTpFile</link> *tp_file);</programlisting>
156
 
<para>
157
 
Cancels an ongoing <link linkend="EmpathyTpFile"><type>EmpathyTpFile</type></link>, first closing the channel and then
158
 
cancelling any I/O operation and closing the socket.</para>
159
 
<para>
160
 
</para><variablelist role="params">
161
 
<varlistentry><term><parameter>tp_file</parameter>&#160;:</term>
162
 
<listitem><simpara> an <link linkend="EmpathyTpFile"><type>EmpathyTpFile</type></link>
163
 
</simpara></listitem></varlistentry>
164
 
</variablelist></refsect2>
165
 
<refsect2 id="empathy-tp-file-close" role="function">
166
 
<title>empathy_tp_file_close ()</title>
167
 
<indexterm zone="empathy-tp-file-close"><primary sortas="empathy_tp_file_close">empathy_tp_file_close</primary></indexterm><programlisting><link linkend="void">void</link>                empathy_tp_file_close               (<link linkend="EmpathyTpFile">EmpathyTpFile</link> *tp_file);</programlisting>
168
 
<para>
169
 
Closes the channel for an ongoing <link linkend="EmpathyTpFile"><type>EmpathyTpFile</type></link>. It's safe to call this
170
 
method after the transfer has ended.</para>
171
 
<para>
172
 
</para><variablelist role="params">
173
 
<varlistentry><term><parameter>tp_file</parameter>&#160;:</term>
174
 
<listitem><simpara> an <link linkend="EmpathyTpFile"><type>EmpathyTpFile</type></link>
175
 
</simpara></listitem></varlistentry>
176
 
</variablelist></refsect2>
177
 
<refsect2 id="empathy-tp-file-offer" role="function">
178
 
<title>empathy_tp_file_offer ()</title>
179
 
<indexterm zone="empathy-tp-file-offer"><primary sortas="empathy_tp_file_offer">empathy_tp_file_offer</primary></indexterm><programlisting><link linkend="void">void</link>                empathy_tp_file_offer               (<link linkend="EmpathyTpFile">EmpathyTpFile</link> *tp_file,
180
 
                                                         <link linkend="GFile">GFile</link> *gfile,
181
 
                                                         <link linkend="GCancellable">GCancellable</link> *cancellable,
182
 
                                                         <link linkend="EmpathyTpFileProgressCallback">EmpathyTpFileProgressCallback</link> progress_callback,
183
 
                                                         <link linkend="gpointer">gpointer</link> progress_user_data,
184
 
                                                         <link linkend="EmpathyTpFileOperationCallback">EmpathyTpFileOperationCallback</link> op_callback,
185
 
                                                         <link linkend="gpointer">gpointer</link> op_user_data);</programlisting>
186
 
<para>
187
 
Offers an outgoing file transfer, reading data from <parameter>gfile</parameter>.
188
 
The callback <parameter>op_callback</parameter> will be called both when the transfer is
189
 
successful and in case of an error. Note that cancelling <parameter>cancellable</parameter>,
190
 
closes the socket of the file operation in progress, but doesn't
191
 
guarantee that the transfer channel will be closed as well. Thus,
192
 
<link linkend="empathy-tp-file-cancel"><function>empathy_tp_file_cancel()</function></link> or <link linkend="empathy-tp-file-close"><function>empathy_tp_file_close()</function></link> should be used to
193
 
actually cancel an ongoing <link linkend="EmpathyTpFile"><type>EmpathyTpFile</type></link>.</para>
194
 
<para>
195
 
</para><variablelist role="params">
196
 
<varlistentry><term><parameter>tp_file</parameter>&#160;:</term>
197
 
<listitem><simpara> an outgoing <link linkend="EmpathyTpFile"><type>EmpathyTpFile</type></link>
198
 
</simpara></listitem></varlistentry>
199
 
<varlistentry><term><parameter>gfile</parameter>&#160;:</term>
200
 
<listitem><simpara> the source <link linkend="GFile"><type>GFile</type></link> for the transfer
201
 
</simpara></listitem></varlistentry>
202
 
<varlistentry><term><parameter>cancellable</parameter>&#160;:</term>
203
 
<listitem><simpara> a <link linkend="GCancellable"><type>GCancellable</type></link>
204
 
</simpara></listitem></varlistentry>
205
 
<varlistentry><term><parameter>progress_callback</parameter>&#160;:</term>
206
 
<listitem><simpara> function to callback with progress information
207
 
</simpara></listitem></varlistentry>
208
 
<varlistentry><term><parameter>progress_user_data</parameter>&#160;:</term>
209
 
<listitem><simpara> user_data to pass to <parameter>progress_callback</parameter>
210
 
</simpara></listitem></varlistentry>
211
 
<varlistentry><term><parameter>op_callback</parameter>&#160;:</term>
212
 
<listitem><simpara> function to callback when the transfer ends
213
 
</simpara></listitem></varlistentry>
214
 
<varlistentry><term><parameter>op_user_data</parameter>&#160;:</term>
215
 
<listitem><simpara> user_data to pass to <parameter>op_callback</parameter>
216
 
</simpara></listitem></varlistentry>
217
 
</variablelist></refsect2>
218
 
<refsect2 id="empathy-tp-file-is-incoming" role="function">
219
 
<title>empathy_tp_file_is_incoming ()</title>
220
 
<indexterm zone="empathy-tp-file-is-incoming"><primary sortas="empathy_tp_file_is_incoming">empathy_tp_file_is_incoming</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            empathy_tp_file_is_incoming         (<link linkend="EmpathyTpFile">EmpathyTpFile</link> *tp_file);</programlisting>
221
 
<para>
222
 
Returns whether <parameter>tp_file</parameter> is incoming.</para>
223
 
<para>
224
 
</para><variablelist role="params">
225
 
<varlistentry><term><parameter>tp_file</parameter>&#160;:</term>
226
 
<listitem><simpara> an <link linkend="EmpathyTpFile"><type>EmpathyTpFile</type></link>
227
 
</simpara></listitem></varlistentry>
228
 
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the <parameter>tp_file</parameter> is incoming, otherwise <link linkend="FALSE--CAPS"><literal>FALSE</literal></link>
229
 
</simpara></listitem></varlistentry>
230
 
</variablelist></refsect2>
231
 
 
232
 
</refsect1>
233
 
<refsect1 id="EmpathyTpFile.property-details" role="property_details">
234
 
<title role="property_details.title">Property Details</title>
235
 
<refsect2 id="EmpathyTpFile--channel" role="property"><title>The <literal>&quot;channel&quot;</literal> property</title>
236
 
<indexterm zone="EmpathyTpFile--channel"><primary sortas="EmpathyTpFile:channel">EmpathyTpFile:channel</primary></indexterm><programlisting>  &quot;channel&quot;                  <link linkend="TpChannel">TpChannel</link>*            : Read / Write / Construct Only</programlisting>
237
 
<para>
238
 
The <link linkend="TpChannel"><type>TpChannel</type></link> requested for the file transfer.</para>
239
 
<para>
240
 
</para></refsect2>
241
 
<refsect2 id="EmpathyTpFile--incoming" role="property"><title>The <literal>&quot;incoming&quot;</literal> property</title>
242
 
<indexterm zone="EmpathyTpFile--incoming"><primary sortas="EmpathyTpFile:incoming">EmpathyTpFile:incoming</primary></indexterm><programlisting>  &quot;incoming&quot;                 <link linkend="gboolean">gboolean</link>              : Read / Write / Construct Only</programlisting>
243
 
<para>
244
 
<link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the transfer is incoming, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if it's outgoing.</para>
245
 
<para>
246
 
</para><para>Default value: FALSE</para>
247
 
</refsect2>
248
 
</refsect1>
249
 
 
250
 
 
251
 
 
252
 
 
253
 
</refentry>