source: trunk/doc/html/network.html@ 203

Last change on this file since 203 was 190, checked in by rudi, 14 years ago

reference documentation added
File size: 26.4 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/doc/network.doc:41 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>Network Module</title>
7<style type="text/css"><!--
8fn { margin-left: 1cm; text-indent: -1cm; }
9a:link { color: #004faf; text-decoration: none }
10a:visited { color: #672967; text-decoration: none }
11body { background: #ffffff; color: black; }
12--></style>
13</head>
14<body>
15
16<table border="0" cellpadding="0" cellspacing="0" width="100%">
17<tr bgcolor="#E5E5E5">
18<td valign=center>
19 <a href="index.html">
20<font color="#004faf">Home</font></a>
21 | <a href="classes.html">
22<font color="#004faf">All&nbsp;Classes</font></a>
23 | <a href="mainclasses.html">
24<font color="#004faf">Main&nbsp;Classes</font></a>
25 | <a href="annotated.html">
26<font color="#004faf">Annotated</font></a>
27 | <a href="groups.html">
28<font color="#004faf">Grouped&nbsp;Classes</font></a>
29 | <a href="functions.html">
30<font color="#004faf">Functions</font></a>
31</td>
32<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>Network Module</h1>
33
34
35
36<p>
37<p> <!-- toc -->
38<ul>
39<li><a href="#1"> Introduction
40</a>
41<li><a href="#2"> Working Network Protocol independently with QUrlOperator and QNetworkOperation
42</a>
43<ul>
44<li><a href="#2-1"> Implementing your own Network Protocol
45</a>
46<li><a href="#2-2"> Error Handling
47</a>
48</ul>
49</ul>
50<!-- endtoc -->
51
52<p> <h2> Introduction
53</h2>
54<a name="1"></a><p> The network module offers classes to make network programming easier
55and portable. Essentially, there are three sets of classes, first low
56level classes like <a href="qsocket.html">QSocket</a>, <a href="qserversocket.html">QServerSocket</a>, <a href="qdns.html">QDns</a>, etc. which
57allow you to work in a portable way with TCP/IP sockets. In addition,
58there are classes like <a href="qnetworkprotocol.html">QNetworkProtocol</a>, <a href="qnetworkoperation.html">QNetworkOperation</a> in
59the Qt base library, which provide an abstract layer for implementing
60network protocols and <a href="qurloperator.html">QUrlOperator</a> which operates on such network
61protocols. Finally the third set of network classes are the passive
62ones, specifically <a href="qurl.html">QUrl</a> and <a href="qurlinfo.html">QUrlInfo</a> which do URL parsing and
63similar.
64<p> The first set of classes (<a href="qsocket.html">QSocket</a>, <a href="qserversocket.html">QServerSocket</a>, <a href="qdns.html">QDns</a>, <a href="qftp.html">QFtp</a>, etc.) are included in Qt's "network" module.
65<p> The <a href="qsocket.html">QSocket</a> classes are not directly related to the QNetwork classes,
66but QSocket should and will be used for implementing network
67protocols, which are directly related to the QNetwork classes. For
68example, the <a href="qftp.html">QFtp</a> class (which implements the FTP protocol) uses
69QSockets. But QSockets don't need to be used for protocol
70implementations, e.g. <a href="qlocalfs.html">QLocalFs</a> (which is an implementation of the
71local filesystem as network protocol) uses <a href="qdir.html">QDir</a> and doesn't use
72QSocket. Using QNetworkProtocols you can implement everything which
73fits into a hierarchical structure and can be accessed using URLs.
74This could be, for example, a protocol which can read pictures from a
75digital camera using a serial connection.
76<p> <h2> Working Network Protocol independently with <a href="qurloperator.html">QUrlOperator</a> and <a href="qnetworkoperation.html">QNetworkOperation</a>
77</h2>
78<a name="2"></a><p> It is quite easy to just use existing network protocol implementations
79and operate on URLs. For example, downloading a file from an FTP
80server to the local filesystem can be done with following code:
81<p> <pre>
82 <a href="qurloperator.html">QUrlOperator</a> op;
83 op.<a href="qurloperator.html#copy">copy</a>( "ftp://ftp.trolltech.com/qt/source/qt-2.1.0.tar.gz", "file:/tmp", FALSE );
84</pre>
85
86<p> And that's all! Of course an implementation of the FTP protocol has to
87be available and registered for doing that. More information on that
88later.
89<p> You can also do things like creating directories, removing files,
90renaming, etc. For example, to create a folder on a private FTP
91account do
92<p> <pre>
93 <a href="qurloperator.html">QUrlOperator</a> op( "ftp://username:password@host.domain.no/home/username" );
94 op.<a href="qurloperator.html#mkdir">mkdir</a>( "New Directory" );
95</pre>
96
97<p> To see all available operations, look at the <a href="qurloperator.html">QUrlOperator</a> class
98documentation.
99<p> Since networking works asynchronously, the function call for an
100operation will normally return before the operation has been
101completed. This means that the function cannot return a value
102indicating failure or success. Instead, the return value always is a
103pointer to a <a href="qnetworkoperation.html">QNetworkOperation</a>, and this object stores
104all the information about the operation.
105<p> For example, <a href="qnetworkoperation.html">QNetworkOperation</a> has a method which returns the state
106of this operation. Using this you can find out the state of the
107operation at any time. The object also makes available the arguments
108you passed to the <a href="qurloperator.html">QUrlOperator</a> method, the type of the operation
109and some more information. For more details see the class
110documentation of <a href="qnetworkoperation.html">QNetworkOperation</a>.
111<p> The <a href="qurloperator.html">QUrlOperator</a> emits signals to inform you about the progress of
112the operations. As you can call many methods which operate on a <a href="qurloperator.html">QUrlOperator</a>'s URL, it queues up all the operations. So you can't know
113which operation the <a href="qurloperator.html">QUrlOperator</a> just processed. Clearly you will
114want to know which operation just took place, so each signal's last
115argument is a pointer to the <a href="qnetworkoperation.html">QNetworkOperation</a> object which was
116just processed and which caused the signal to be emitted.
117<p> Some of these operations send a <tt>start()</tt> signal at the beginning (if
118this makes sense), and some of them send some signals during
119processing. All operations send a <tt>finished()</tt> signal after they are
120done. To find that out if an operation finished successfully you can
121use the <a href="qnetworkoperation.html">QNetworkOperation</a> pointer you got with the <tt>finished()</tt>
122signal. If <a href="qnetworkoperation.html#state">QNetworkOperation::state</a>() equals <a href="qnetworkprotocol.html#State-enum">QNetworkProtocol::StDone</a> the operation finished successfully, if it is
123<a href="qnetworkprotocol.html#State-enum">QNetworkProtocol::StFailed</a> the operation failed.
124<p> Example: A slot which you might connect to the
125<tt>QUrlOperator::finished( QNetworkOperation * )</tt>
126<pre>
127void MyClass::slotOperationFinished( <a href="qnetworkoperation.html">QNetworkOperation</a> *op )
128{
129 switch ( op-&gt;<a href="qnetworkoperation.html#operation">operation</a>() ) {
130 case QNetworkProtocol::OpMkDir:
131 if ( op-&gt;<a href="qnetworkoperation.html#state">state</a>() == QNetworkProtocol::StFailed )
132 <a href="qapplication.html#qDebug">qDebug</a>( "Couldn't create directory %s", op-&gt;<a href="qnetworkoperation.html#arg">arg</a>( 0 ).latin1() );
133 else
134 <a href="qapplication.html#qDebug">qDebug</a>( "Successfully created directory %s", op-&gt;<a href="qnetworkoperation.html#arg">arg</a>( 0 ).latin1() );
135 break;
136 // ... and so on
137 }
138}
139</pre>
140
141<p> As mentioned earlier, some operations send other signals too. Let's
142take the list children operation as an example (e.g. read a directory
143on a FTP server):
144<p> <pre>
145QUrlOperator op;
146
147MyClass::MyClass() : <a href="qobject.html">QObject</a>(), op( "ftp://ftp.trolltech.com" )
148{
149 connect( &amp;op, SIGNAL( newChildren( const <a href="qvaluelist.html">QValueList</a>&lt;QUrlInfo&gt; &amp;, QNetworkOperation * ) ),
150 this, SLOT( slotInsertEntries( const <a href="qvaluelist.html">QValueList</a>&lt;QUrlInfo&gt; &amp;, QNetworkOperation * ) ) );
151 connect( &amp;op, SIGNAL( start( <a href="qnetworkoperation.html">QNetworkOperation</a> * ) ),
152 this, SLOT( slotStart( <a href="qnetworkoperation.html">QNetworkOperation</a> *) ) );
153 connect( &amp;op, SIGNAL( finished( <a href="qnetworkoperation.html">QNetworkOperation</a> * ) ),
154 this, SLOT( slotFinished( <a href="qnetworkoperation.html">QNetworkOperation</a> *) ) );
155}
156
157void MyClass::slotInsertEntries( const <a href="qvaluelist.html">QValueList</a>&lt;QUrlInfo&gt; &amp;info, QNetworkOperation * )
158{
159 QValueList&lt;QUrlInfo&gt;::ConstIterator it = info.<a href="qvaluelist.html#begin">begin</a>();
160 for ( ; it != info.<a href="qvaluelist.html#end">end</a>(); ++it ) {
161 const <a href="qurlinfo.html">QUrlInfo</a> &amp;inf = *it;
162 <a href="qapplication.html#qDebug">qDebug</a>( "Name: %s, Size: %d, Last Modified: %s",
163 inf.<a href="qurlinfo.html#name">name</a>().latin1(), inf.<a href="qurlinfo.html#size">size</a>(), inf.<a href="qurlinfo.html#lastModified">lastModified</a>().toString().latin1() );
164 }
165}
166
167void MyClass::slotStart( <a href="qnetworkoperation.html">QNetworkOperation</a> * )
168{
169 <a href="qapplication.html#qDebug">qDebug</a>( "Start reading '%s'", op.toString().latin1() );
170}
171
172void MyClass::slotFinished( <a href="qnetworkoperation.html">QNetworkOperation</a> *operation )
173{
174 if ( operation-&gt;<a href="qnetworkoperation.html#operation">operation</a>() == QNetworkProtocol::OpListChildren ) {
175 if ( operation-&gt;<a href="qnetworkoperation.html#state">state</a>() == QNetworkProtocol::StFailed )
176 <a href="qapplication.html#qDebug">qDebug</a>( "Couldn't read '%s'! Following error occurred: %s",
177 op.toString().latin1(), operation-&gt;<a href="qnetworkoperation.html#protocolDetail">protocolDetail</a>().latin1() );
178 else
179 <a href="qapplication.html#qDebug">qDebug</a>( "Finished reading '%s'!", op.toString().latin1() );
180 }
181}
182
183</pre>
184
185<p> These examples demonstrate now how to use the <a href="qurloperator.html">QUrlOperator</a> and <tt>QNetworkOperations</tt>. The network extension also contains useful example
186code.
187<p> <h3> Implementing your own Network Protocol
188</h3>
189<a name="2-1"></a><p> <a href="qnetworkprotocol.html">QNetworkProtocol</a> provides a base class for implementations
190of network protocols and an architecture for the a dynamic
191registration and de-registration of network protocols. If you use this
192architecture you don't need to care about asynchronous programming, as
193the architecture hides this and does all the work for you.
194<p> <em>Note</em> It is difficult to design a base class for network protocols
195which is useful for all network protocols. The architecture described
196here is designed to work with all kinds of hierarchical structures,
197like filesystems. So everything which can be interpreted as
198hierarchical structure and accessed via URLs, can be implemented as
199network protocol and easily used in Qt. This is not limited to
200filesystems only!
201<p> To implement a network protocol create a class derived from
202<a href="qnetworkprotocol.html">QNetworkProtocol</a>.
203<p> Other classes will use this network protocol implementation
204to operate on it. So you should reimplement following protected members
205<p> <pre>
206 void QNetworkProtocol::operationListChildren( <a href="qnetworkoperation.html">QNetworkOperation</a> *op );
207 void QNetworkProtocol::operationMkDir( <a href="qnetworkoperation.html">QNetworkOperation</a> *op );
208 void QNetworkProtocol::operationRemove( <a href="qnetworkoperation.html">QNetworkOperation</a> *op );
209 void QNetworkProtocol::operationRename( <a href="qnetworkoperation.html">QNetworkOperation</a> *op );
210 void QNetworkProtocol::operationGet( <a href="qnetworkoperation.html">QNetworkOperation</a> *op );
211 void QNetworkProtocol::operationPut( <a href="qnetworkoperation.html">QNetworkOperation</a> *op );
212</pre>
213
214<p> Some notes on reimplementing these methods: You always get a pointer
215to a <a href="qnetworkoperation.html">QNetworkOperation</a> as argument. This pointer holds all the
216information about the operation in the current state. If you start
217processing such an operation, set the state to <a href="qnetworkprotocol.html#State-enum">QNetworkProtocol::StInProgress</a>. If you finished processing the
218operation, set the state to <a href="qnetworkprotocol.html#State-enum">QNetworkProtocol::StDone</a> if it was
219successful or <a href="qnetworkprotocol.html#State-enum">QNetworkProtocol::StFailed</a> if an error occurred. If
220an error occurred you must set an error code (see
221<a href="qnetworkoperation.html#setErrorCode">QNetworkOperation::setErrorCode</a>()) and if you know some details
222(e.g. an error message) you can also set this message to the operation
223pointer (see <a href="qnetworkoperation.html#setProtocolDetail">QNetworkOperation::setProtocolDetail</a>()). Also you get
224all the relevant information (type, arguments, etc.) about the
225operation from the <a href="qnetworkoperation.html">QNetworkOperation</a> pointer. For details about
226which arguments you can get and set look at <a href="qnetworkoperation.html">QNetworkOperation</a>'s
227class documentation.
228<p> If you reimplement an operation function, it's very important to emit
229the correct signals at the correct time: In general always emit <tt>finished()</tt> at the end of an operation (when you either successfully
230finished processing the operation or an error occurred) with the
231network operation as argument. The whole network architecture relies
232on correctly emitted <tt>finished()</tt> signals! Then there are some more
233specialized signals which are specific to operations:
234<ul>
235<li> Emit in <tt>operationListChildren</tt>:
236<ul>
237<li> <tt>start()</tt> just before starting to list the children
238<li> <tt>newChildren()</tt> when new children are read
239</ul>
240<li> Emit in <tt>operationMkDir</tt>:
241<ul>
242<li> <tt>createdDirectory()</tt> after the directory has been created
243<li> <tt>newChild()</tt> (or newChildren()) after the directory has been
244created (since a new directory is a new child)
245</ul>
246<li> Emit in <tt>operationRemove</tt>:
247<ul>
248<li> <tt>removed()</tt> after a child has been removed
249</ul>
250<li> Emit in <tt>operationRename</tt>:
251<ul>
252<li> <tt>itemChanged()</tt> after a child has been renamed
253</ul>
254<li> Emit in <tt>operationGet</tt>:
255<ul>
256<li> <tt>data()</tt> each time new data has been read
257<li> <tt>dataTransferProgress()</tt> each time new data has been read to
258indicate how much of the data has been read now.
259</ul>
260<li> Emit in <tt>operationPut</tt>:
261<ul>
262<li> <tt>dataTransferProgress()</tt> each time data has been written to
263indicate how much of the data has been written. Although you
264know the whole data when this operation is called, it's
265suggested not to write the whole data at once, but to do it
266step by step to avoid blocking the GUI. Doing things
267incrementally also means that progress can be made visible
268to the user.
269</ul>
270</ul>
271<p> And remember, always emit the <tt>finished()</tt> signal at the end!
272<p> For more details about these signals' arguments look at the <a href="qnetworkprotocol.html">QNetworkProtocol</a> class documentation.
273<p> Here is a list of which <a href="qnetworkoperation.html">QNetworkOperation</a> arguments you can get and
274which you must set in which function:
275<p> (To get the URL on which you should work, use the <a href="qnetworkprotocol.html#url">QNetworkProtocol::url</a>() method which returns a pointer to the URL
276operator. Using that you can get the path, host, name filter, etc.)
277<p> <ul>
278<li> In <tt>operationListChildren</tt>:
279<ul>
280<li> Nothing.
281</ul>
282<li> In <tt>operationMkDir</tt>:
283<ul>
284<li> <tt>QNetworkOperation::arg( 0 )</tt> contains the name of the directory which should be created
285</ul>
286<li> In <tt>operationRemove</tt>:
287<ul>
288<li> <tt>QNetworkOperation::arg( 0 )</tt> contains the name of the file
289which should be removed. Normally this is a relative name. But
290it could be absolute. Use <a href="qurl.html">QUrl</a>( op->arg( 0 ) ).fileName()
291to get the filename.
292</ul>
293<li> In <tt>operationRename</tt>:
294<ul>
295<li> <tt>QNetworkOperation::arg( 0 )</tt> contains the name of the file
296which should be renamed
297<li> <tt>QNetworkOperation::arg( 1 )</tt> contains the name to which it
298should be renamed.
299</ul>
300<li> In <tt>operationGet</tt>:
301<ul>
302<li> <tt>QNetworkOperation::arg( 0 )</tt> contains the full URL of the
303file which should be retrieved.
304</ul>
305<li> In <tt>operationPut</tt>:
306<ul>
307<li> <tt>QNetworkOperation::arg( 0 )</tt> contains the full URL of the
308file in which the data should be stored.
309<li> <tt>QNetworkOperation::rawArg( 1 )</tt> contains the data which
310should be stored in <tt>QNetworkOperation::arg( 0 )</tt>
311</ul>
312</ul>
313<p> In summary: If you reimplement an operation function, you must emit
314some special signals and at the end you must <em>always</em> emit a <tt>finished()</tt> signal, regardless of success or failure. Also you must
315change the state of the <a href="qnetworkoperation.html">QNetworkOperation</a> during processing. You
316can also get and set <a href="qnetworkoperation.html">QNetworkOperation</a> arguments as the operation
317progresses.
318<p> It may occur that the network protocol you implement only requires a
319subset of these operations. In such cases, simply reimplement the
320operations which are supported by the protocol. Additionally you must
321specify which operations you support. This is achieved by
322reimplementing
323<p> <pre>
324 int QNetworkProtocol::supportedOperations() const;
325</pre>
326
327<p> In your implementation of this method return an <tt>int</tt> value
328which is constructed by OR-ing together the correct values
329(supported operations) of the following enum (of <a href="qnetworkprotocol.html">QNetworkProtocol</a>):
330<p> <ul>
331<li> <tt>OpListChildren</tt>
332<li> <tt>OpMkDir</tt>
333<li> <tt>OpRemove</tt>
334<li> <tt>OpRename</tt>
335<li> <tt>OpGet</tt>
336<li> <tt>OpPut</tt>
337</ul>
338<p> For example, if your protocol supports listing children and renaming
339them, your implementation of <tt>supportedOperations()</tt> should do this:
340<p> <pre>
341 return OpListChildren | OpRename;
342</pre>
343
344<p> The last method you must reimplement is
345<p> <pre>
346 bool QNetworkProtocol::checkConnection( <a href="qnetworkoperation.html">QNetworkOperation</a> *op );
347</pre>
348
349<p> Here you must return TRUE, if the connection is up and okay (this means
350operations on the protocol can be done). If the connection is not okay,
351return FALSE and start to try opening it. If you cannot open the
352connection at all (e.g. because the host is not found), emit a <tt>finished()</tt>
353signal and set an error code and the <a href="qnetworkprotocol.html#State-enum">QNetworkProtocol::StFailed</a> state to
354the <a href="qnetworkoperation.html">QNetworkOperation</a> pointer you get here.
355<p> Now, you never need to check before doing an operation yourself, if
356the connection is okay. The network architecture does this, which
357means it uses <tt>checkConnection()</tt> to see if an operation can be done
358and if not, it tries it again and again for some time, only calling an
359operation function if the connection is okay.
360<p> To be able to use a network protocol with a <a href="qurloperator.html">QUrlOperator</a> (and so, for
361example, in the <a href="qfiledialog.html">QFileDialog</a>), you must register the network
362protocol implementation. This can be done like this:
363<p> <pre>
364 QNetworkProtocol::<a href="qnetworkprotocol.html#registerNetworkProtocol">registerNetworkProtocol</a>( "myprot", new QNetworkProtocolFactory&lt;MyProtocol&gt; );
365</pre>
366
367<p> In this case <tt>MyProtocol</tt> would be a class you implemented as
368described here (derived from <a href="qnetworkprotocol.html">QNetworkProtocol</a>) and the name of the
369protocol would be "myprot". So to use it, you would do something like
370<p> <pre>
371 <a href="qurloperator.html">QUrlOperator</a> op( "myprot://host/path" );
372 op.<a href="qurloperator.html#listChildren">listChildren</a>();
373</pre>
374
375<p> Finally, as example of a network protocol implementation you could
376look at the implementation of <a href="qlocalfs.html">QLocalFs</a>. The network extension also
377contains an example implementation of a network protocol.
378<p> <h3> Error Handling
379</h3>
380<a name="2-2"></a><p> Error handling is important for both implementing new network
381protocols for and using them (through <a href="qurloperator.html">QUrlOperator</a>).
382<p> After processing an operation has been finished the network operation
383the <a href="qurloperator.html">QUrlOperator</a> emits the <tt>finished()</tt> signal. This has as argument
384a pointer to the processed <a href="qnetworkoperation.html">QNetworkOperation</a>. If the state of this
385operation is <a href="qnetworkprotocol.html#State-enum">QNetworkProtocol::StFailed</a>, the operation contains
386some more information about this error. The following error codes are
387defined in <a href="qnetworkprotocol.html">QNetworkProtocol</a>:
388<p> <center><table cellpadding="4" cellspacing="2" border="0">
389<tr bgcolor="#a2c511"> <th valign="top">Error <th valign="top">Meaning
390<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::NoError</a>
391<td valign="top">No error occurred
392<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::ErrValid</a>
393<td valign="top">The URL you are operating on is not valid
394<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::ErrUnknownProtocol</a>
395<td valign="top">There is no protocol implementation available for the protocol
396of the URL you are operating on (e.g. if the protocol is http
397and no http implementation has been registered)
398<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::ErrUnsupported</a>
399<td valign="top">The operation is not supported by the protocol
400<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::ErrParse</a>
401<td valign="top">Parse error of the URL
402<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::ErrLoginIncorrect</a>
403<td valign="top">You needed to login but the username or password are wrong
404<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::ErrHostNotFound</a>
405<td valign="top">The specified host (in the URL) couldn't be found
406<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::ErrListChildren</a>
407<td valign="top">An error occurred while listing the children
408<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::ErrMkDir</a>
409<td valign="top">An error occurred when creating a directory
410<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::ErrRemove</a>
411<td valign="top">An error occurred while removing a child
412<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::ErrRename</a>
413<td valign="top">An error occurred while renaming a child
414<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::ErrGet</a>
415<td valign="top">An error occurred while getting (retrieving) data
416<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::ErrPut</a>
417<td valign="top">An error occurred while putting (uploading) data
418<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::ErrFileNotExisting</a>
419<td valign="top">A file which is needed by the operation doesn't exist
420<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::ErrPermissionDenied</a>
421<td valign="top">The permission for doing the operation has been denied
422</table></center>
423<p> <a href="qnetworkoperation.html#errorCode">QNetworkOperation::errorCode</a>() returns one of these codes or
424perhaps a different one if you use your an own network protocol
425implementation which defines additional error codes.
426<p> <tt>QNetworkOperation::protocolDetails()</tt> may also return a string which
427contains an error message then which might be suitable for display to
428the user.
429<p> If you implement your own network protocol, you must report any
430errors which occurred. First you always need to be able to
431access the <a href="qnetworkoperation.html">QNetworkOperation</a> which is being processed at the
432moment. This is done using <tt>QNetworkOperation::operationInProgress()</tt>, which returns a pointer to
433the current network operation or 0 if no operation is processed at the
434moment.
435<p> Now if an error occurred and you need to handle it, do this:
436<pre>
437 if ( operationInProgress() ) {
438 operationInProgress()-&gt;setErrorCode( error_code_of_your_error );
439 operationInProgress()-&gt;setProtocolDetails( detail ); // optional
440 emit finished( operationInProgress() );
441 return;
442 }
443</pre>
444
445<p> That's all. The connection to the <a href="qurloperator.html">QUrlOperator</a> and so on is done
446automatically. Additionally, if the error was really bad so that no
447more operations can be done in the current state (e.g. if the host
448couldn't be found), call <tt>QNetworkProtocol::clearOperationStack()</tt> <em>before</em> emitting <tt>finished()</tt>.
449<p> Ideally you should use one of the predefined error codes of <a href="qnetworkprotocol.html">QNetworkProtocol</a>. If this is not possible, you can add own error codes
450- they are just normal <tt>int</tt>s. Just be careful that the value of the
451error code doesn't conflict with an existing one.
452<p> An example to look at is in qt/examples/network/ftpclient.
453This is the implementation of a fairly complete FTP client, which
454supports uploading and downloading files, making directories, etc.,
455all done using <tt>QUrlOperators</tt>.
456<p> You might also like to look at <a href="qftp.html">QFtp</a> (in qt/src/network/qftp.cpp) or at
457the example in qt/examples/network/networkprotocol/nntp.cpp.
458<p>
459<!-- eof -->
460<p><address><hr><div align=center>
461<table width=100% cellspacing=0 border=0><tr>
462<td>Copyright &copy; 2007
463<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
464<td align=right><div align=right>Qt 3.3.8</div>
465</table></div></address></body>
466</html>
Note: See TracBrowser for help on using the repository browser.