diff options
| author | Timothy Pearson <kb9vqf@pearsoncomputing.net> | 2011-07-10 15:24:15 -0500 |
|---|---|---|
| committer | Timothy Pearson <kb9vqf@pearsoncomputing.net> | 2011-07-10 15:24:15 -0500 |
| commit | bd0f3345a938b35ce6a12f6150373b0955b8dd12 (patch) | |
| tree | 7a520322212d48ebcb9fbe1087e7fca28b76185c /doc/html/network.html | |
| download | qt3-bd0f3345a938b35ce6a12f6150373b0955b8dd12.tar.gz qt3-bd0f3345a938b35ce6a12f6150373b0955b8dd12.zip | |
Add Qt3 development HEAD version
Diffstat (limited to 'doc/html/network.html')
| -rw-r--r-- | doc/html/network.html | 466 |
1 files changed, 466 insertions, 0 deletions
diff --git a/doc/html/network.html b/doc/html/network.html new file mode 100644 index 0000000..ba7be6d --- /dev/null +++ b/doc/html/network.html @@ -0,0 +1,466 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/doc/network.doc:41 --> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>Network Module</title> +<style type="text/css"><!-- +fn { margin-left: 1cm; text-indent: -1cm; } +a:link { color: #004faf; text-decoration: none } +a:visited { color: #672967; text-decoration: none } +body { background: #ffffff; color: black; } +--></style> +</head> +<body> + +<table border="0" cellpadding="0" cellspacing="0" width="100%"> +<tr bgcolor="#E5E5E5"> +<td valign=center> + <a href="index.html"> +<font color="#004faf">Home</font></a> + | <a href="classes.html"> +<font color="#004faf">All Classes</font></a> + | <a href="mainclasses.html"> +<font color="#004faf">Main Classes</font></a> + | <a href="annotated.html"> +<font color="#004faf">Annotated</font></a> + | <a href="groups.html"> +<font color="#004faf">Grouped Classes</font></a> + | <a href="functions.html"> +<font color="#004faf">Functions</font></a> +</td> +<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> + + + +<p> +<p> <!-- toc --> +<ul> +<li><a href="#1"> Introduction +</a> +<li><a href="#2"> Working Network Protocol independently with QUrlOperator and QNetworkOperation +</a> +<ul> +<li><a href="#2-1"> Implementing your own Network Protocol +</a> +<li><a href="#2-2"> Error Handling +</a> +</ul> +</ul> +<!-- endtoc --> + +<p> <h2> Introduction +</h2> +<a name="1"></a><p> The network module offers classes to make network programming easier +and portable. Essentially, there are three sets of classes, first low +level classes like <a href="qsocket.html">QSocket</a>, <a href="qserversocket.html">QServerSocket</a>, <a href="qdns.html">QDns</a>, etc. which +allow you to work in a portable way with TCP/IP sockets. In addition, +there are classes like <a href="qnetworkprotocol.html">QNetworkProtocol</a>, <a href="qnetworkoperation.html">QNetworkOperation</a> in +the Qt base library, which provide an abstract layer for implementing +network protocols and <a href="qurloperator.html">QUrlOperator</a> which operates on such network +protocols. Finally the third set of network classes are the passive +ones, specifically <a href="qurl.html">QUrl</a> and <a href="qurlinfo.html">QUrlInfo</a> which do URL parsing and +similar. +<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. +<p> The <a href="qsocket.html">QSocket</a> classes are not directly related to the QNetwork classes, +but QSocket should and will be used for implementing network +protocols, which are directly related to the QNetwork classes. For +example, the <a href="qftp.html">QFtp</a> class (which implements the FTP protocol) uses +QSockets. But QSockets don't need to be used for protocol +implementations, e.g. <a href="qlocalfs.html">QLocalFs</a> (which is an implementation of the +local filesystem as network protocol) uses <a href="qdir.html">QDir</a> and doesn't use +QSocket. Using QNetworkProtocols you can implement everything which +fits into a hierarchical structure and can be accessed using URLs. +This could be, for example, a protocol which can read pictures from a +digital camera using a serial connection. +<p> <h2> Working Network Protocol independently with <a href="qurloperator.html">QUrlOperator</a> and <a href="qnetworkoperation.html">QNetworkOperation</a> +</h2> +<a name="2"></a><p> It is quite easy to just use existing network protocol implementations +and operate on URLs. For example, downloading a file from an FTP +server to the local filesystem can be done with following code: +<p> <pre> + <a href="qurloperator.html">QUrlOperator</a> op; + op.<a href="qurloperator.html#copy">copy</a>( "ftp://ftp.trolltech.com/qt/source/qt-2.1.0.tar.gz", "file:/tmp", FALSE ); +</pre> + +<p> And that's all! Of course an implementation of the FTP protocol has to +be available and registered for doing that. More information on that +later. +<p> You can also do things like creating directories, removing files, +renaming, etc. For example, to create a folder on a private FTP +account do +<p> <pre> + <a href="qurloperator.html">QUrlOperator</a> op( "ftp://username:password@host.domain.no/home/username" ); + op.<a href="qurloperator.html#mkdir">mkdir</a>( "New Directory" ); +</pre> + +<p> To see all available operations, look at the <a href="qurloperator.html">QUrlOperator</a> class +documentation. +<p> Since networking works asynchronously, the function call for an +operation will normally return before the operation has been +completed. This means that the function cannot return a value +indicating failure or success. Instead, the return value always is a +pointer to a <a href="qnetworkoperation.html">QNetworkOperation</a>, and this object stores +all the information about the operation. +<p> For example, <a href="qnetworkoperation.html">QNetworkOperation</a> has a method which returns the state +of this operation. Using this you can find out the state of the +operation at any time. The object also makes available the arguments +you passed to the <a href="qurloperator.html">QUrlOperator</a> method, the type of the operation +and some more information. For more details see the class +documentation of <a href="qnetworkoperation.html">QNetworkOperation</a>. +<p> The <a href="qurloperator.html">QUrlOperator</a> emits signals to inform you about the progress of +the 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 +which operation the <a href="qurloperator.html">QUrlOperator</a> just processed. Clearly you will +want to know which operation just took place, so each signal's last +argument is a pointer to the <a href="qnetworkoperation.html">QNetworkOperation</a> object which was +just processed and which caused the signal to be emitted. +<p> Some of these operations send a <tt>start()</tt> signal at the beginning (if +this makes sense), and some of them send some signals during +processing. All operations send a <tt>finished()</tt> signal after they are +done. To find that out if an operation finished successfully you can +use the <a href="qnetworkoperation.html">QNetworkOperation</a> pointer you got with the <tt>finished()</tt> +signal. 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 +<a href="qnetworkprotocol.html#State-enum">QNetworkProtocol::StFailed</a> the operation failed. +<p> Example: A slot which you might connect to the +<tt>QUrlOperator::finished( QNetworkOperation * )</tt> +<pre> +void MyClass::slotOperationFinished( <a href="qnetworkoperation.html">QNetworkOperation</a> *op ) +{ + switch ( op-><a href="qnetworkoperation.html#operation">operation</a>() ) { + case QNetworkProtocol::OpMkDir: + if ( op-><a href="qnetworkoperation.html#state">state</a>() == QNetworkProtocol::StFailed ) + <a href="qapplication.html#qDebug">qDebug</a>( "Couldn't create directory %s", op-><a href="qnetworkoperation.html#arg">arg</a>( 0 ).latin1() ); + else + <a href="qapplication.html#qDebug">qDebug</a>( "Successfully created directory %s", op-><a href="qnetworkoperation.html#arg">arg</a>( 0 ).latin1() ); + break; + // ... and so on + } +} +</pre> + +<p> As mentioned earlier, some operations send other signals too. Let's +take the list children operation as an example (e.g. read a directory +on a FTP server): +<p> <pre> +QUrlOperator op; + +MyClass::MyClass() : <a href="qobject.html">QObject</a>(), op( "ftp://ftp.trolltech.com" ) +{ + connect( &op, SIGNAL( newChildren( const <a href="qvaluelist.html">QValueList</a><QUrlInfo> &, QNetworkOperation * ) ), + this, SLOT( slotInsertEntries( const <a href="qvaluelist.html">QValueList</a><QUrlInfo> &, QNetworkOperation * ) ) ); + connect( &op, SIGNAL( start( <a href="qnetworkoperation.html">QNetworkOperation</a> * ) ), + this, SLOT( slotStart( <a href="qnetworkoperation.html">QNetworkOperation</a> *) ) ); + connect( &op, SIGNAL( finished( <a href="qnetworkoperation.html">QNetworkOperation</a> * ) ), + this, SLOT( slotFinished( <a href="qnetworkoperation.html">QNetworkOperation</a> *) ) ); +} + +void MyClass::slotInsertEntries( const <a href="qvaluelist.html">QValueList</a><QUrlInfo> &info, QNetworkOperation * ) +{ + QValueList<QUrlInfo>::ConstIterator it = info.<a href="qvaluelist.html#begin">begin</a>(); + for ( ; it != info.<a href="qvaluelist.html#end">end</a>(); ++it ) { + const <a href="qurlinfo.html">QUrlInfo</a> &inf = *it; + <a href="qapplication.html#qDebug">qDebug</a>( "Name: %s, Size: %d, Last Modified: %s", + 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() ); + } +} + +void MyClass::slotStart( <a href="qnetworkoperation.html">QNetworkOperation</a> * ) +{ + <a href="qapplication.html#qDebug">qDebug</a>( "Start reading '%s'", op.toString().latin1() ); +} + +void MyClass::slotFinished( <a href="qnetworkoperation.html">QNetworkOperation</a> *operation ) +{ + if ( operation-><a href="qnetworkoperation.html#operation">operation</a>() == QNetworkProtocol::OpListChildren ) { + if ( operation-><a href="qnetworkoperation.html#state">state</a>() == QNetworkProtocol::StFailed ) + <a href="qapplication.html#qDebug">qDebug</a>( "Couldn't read '%s'! Following error occurred: %s", + op.toString().latin1(), operation-><a href="qnetworkoperation.html#protocolDetail">protocolDetail</a>().latin1() ); + else + <a href="qapplication.html#qDebug">qDebug</a>( "Finished reading '%s'!", op.toString().latin1() ); + } +} + +</pre> + +<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 +code. +<p> <h3> Implementing your own Network Protocol +</h3> +<a name="2-1"></a><p> <a href="qnetworkprotocol.html">QNetworkProtocol</a> provides a base class for implementations +of network protocols and an architecture for the a dynamic +registration and de-registration of network protocols. If you use this +architecture you don't need to care about asynchronous programming, as +the architecture hides this and does all the work for you. +<p> <em>Note</em> It is difficult to design a base class for network protocols +which is useful for all network protocols. The architecture described +here is designed to work with all kinds of hierarchical structures, +like filesystems. So everything which can be interpreted as +hierarchical structure and accessed via URLs, can be implemented as +network protocol and easily used in Qt. This is not limited to +filesystems only! +<p> To implement a network protocol create a class derived from +<a href="qnetworkprotocol.html">QNetworkProtocol</a>. +<p> Other classes will use this network protocol implementation +to operate on it. So you should reimplement following protected members +<p> <pre> + void QNetworkProtocol::operationListChildren( <a href="qnetworkoperation.html">QNetworkOperation</a> *op ); + void QNetworkProtocol::operationMkDir( <a href="qnetworkoperation.html">QNetworkOperation</a> *op ); + void QNetworkProtocol::operationRemove( <a href="qnetworkoperation.html">QNetworkOperation</a> *op ); + void QNetworkProtocol::operationRename( <a href="qnetworkoperation.html">QNetworkOperation</a> *op ); + void QNetworkProtocol::operationGet( <a href="qnetworkoperation.html">QNetworkOperation</a> *op ); + void QNetworkProtocol::operationPut( <a href="qnetworkoperation.html">QNetworkOperation</a> *op ); +</pre> + +<p> Some notes on reimplementing these methods: You always get a pointer +to a <a href="qnetworkoperation.html">QNetworkOperation</a> as argument. This pointer holds all the +information about the operation in the current state. If you start +processing such an operation, set the state to <a href="qnetworkprotocol.html#State-enum">QNetworkProtocol::StInProgress</a>. If you finished processing the +operation, set the state to <a href="qnetworkprotocol.html#State-enum">QNetworkProtocol::StDone</a> if it was +successful or <a href="qnetworkprotocol.html#State-enum">QNetworkProtocol::StFailed</a> if an error occurred. If +an error occurred you must set an error code (see +<a href="qnetworkoperation.html#setErrorCode">QNetworkOperation::setErrorCode</a>()) and if you know some details +(e.g. an error message) you can also set this message to the operation +pointer (see <a href="qnetworkoperation.html#setProtocolDetail">QNetworkOperation::setProtocolDetail</a>()). Also you get +all the relevant information (type, arguments, etc.) about the +operation from the <a href="qnetworkoperation.html">QNetworkOperation</a> pointer. For details about +which arguments you can get and set look at <a href="qnetworkoperation.html">QNetworkOperation</a>'s +class documentation. +<p> If you reimplement an operation function, it's very important to emit +the correct signals at the correct time: In general always emit <tt>finished()</tt> at the end of an operation (when you either successfully +finished processing the operation or an error occurred) with the +network operation as argument. The whole network architecture relies +on correctly emitted <tt>finished()</tt> signals! Then there are some more +specialized signals which are specific to operations: +<ul> +<li> Emit in <tt>operationListChildren</tt>: +<ul> +<li> <tt>start()</tt> just before starting to list the children +<li> <tt>newChildren()</tt> when new children are read +</ul> +<li> Emit in <tt>operationMkDir</tt>: +<ul> +<li> <tt>createdDirectory()</tt> after the directory has been created +<li> <tt>newChild()</tt> (or newChildren()) after the directory has been +created (since a new directory is a new child) +</ul> +<li> Emit in <tt>operationRemove</tt>: +<ul> +<li> <tt>removed()</tt> after a child has been removed +</ul> +<li> Emit in <tt>operationRename</tt>: +<ul> +<li> <tt>itemChanged()</tt> after a child has been renamed +</ul> +<li> Emit in <tt>operationGet</tt>: +<ul> +<li> <tt>data()</tt> each time new data has been read +<li> <tt>dataTransferProgress()</tt> each time new data has been read to +indicate how much of the data has been read now. +</ul> +<li> Emit in <tt>operationPut</tt>: +<ul> +<li> <tt>dataTransferProgress()</tt> each time data has been written to +indicate how much of the data has been written. Although you +know the whole data when this operation is called, it's +suggested not to write the whole data at once, but to do it +step by step to avoid blocking the GUI. Doing things +incrementally also means that progress can be made visible +to the user. +</ul> +</ul> +<p> And remember, always emit the <tt>finished()</tt> signal at the end! +<p> For more details about these signals' arguments look at the <a href="qnetworkprotocol.html">QNetworkProtocol</a> class documentation. +<p> Here is a list of which <a href="qnetworkoperation.html">QNetworkOperation</a> arguments you can get and +which you must set in which function: +<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 +operator. Using that you can get the path, host, name filter, etc.) +<p> <ul> +<li> In <tt>operationListChildren</tt>: +<ul> +<li> Nothing. +</ul> +<li> In <tt>operationMkDir</tt>: +<ul> +<li> <tt>QNetworkOperation::arg( 0 )</tt> contains the name of the directory which should be created +</ul> +<li> In <tt>operationRemove</tt>: +<ul> +<li> <tt>QNetworkOperation::arg( 0 )</tt> contains the name of the file +which should be removed. Normally this is a relative name. But +it could be absolute. Use <a href="qurl.html">QUrl</a>( op->arg( 0 ) ).fileName() +to get the filename. +</ul> +<li> In <tt>operationRename</tt>: +<ul> +<li> <tt>QNetworkOperation::arg( 0 )</tt> contains the name of the file +which should be renamed +<li> <tt>QNetworkOperation::arg( 1 )</tt> contains the name to which it +should be renamed. +</ul> +<li> In <tt>operationGet</tt>: +<ul> +<li> <tt>QNetworkOperation::arg( 0 )</tt> contains the full URL of the +file which should be retrieved. +</ul> +<li> In <tt>operationPut</tt>: +<ul> +<li> <tt>QNetworkOperation::arg( 0 )</tt> contains the full URL of the +file in which the data should be stored. +<li> <tt>QNetworkOperation::rawArg( 1 )</tt> contains the data which +should be stored in <tt>QNetworkOperation::arg( 0 )</tt> +</ul> +</ul> +<p> In summary: If you reimplement an operation function, you must emit +some 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 +change the state of the <a href="qnetworkoperation.html">QNetworkOperation</a> during processing. You +can also get and set <a href="qnetworkoperation.html">QNetworkOperation</a> arguments as the operation +progresses. +<p> It may occur that the network protocol you implement only requires a +subset of these operations. In such cases, simply reimplement the +operations which are supported by the protocol. Additionally you must +specify which operations you support. This is achieved by +reimplementing +<p> <pre> + int QNetworkProtocol::supportedOperations() const; +</pre> + +<p> In your implementation of this method return an <tt>int</tt> value +which is constructed by OR-ing together the correct values +(supported operations) of the following enum (of <a href="qnetworkprotocol.html">QNetworkProtocol</a>): +<p> <ul> +<li> <tt>OpListChildren</tt> +<li> <tt>OpMkDir</tt> +<li> <tt>OpRemove</tt> +<li> <tt>OpRename</tt> +<li> <tt>OpGet</tt> +<li> <tt>OpPut</tt> +</ul> +<p> For example, if your protocol supports listing children and renaming +them, your implementation of <tt>supportedOperations()</tt> should do this: +<p> <pre> + return OpListChildren | OpRename; +</pre> + +<p> The last method you must reimplement is +<p> <pre> + bool QNetworkProtocol::checkConnection( <a href="qnetworkoperation.html">QNetworkOperation</a> *op ); +</pre> + +<p> Here you must return TRUE, if the connection is up and okay (this means +operations on the protocol can be done). If the connection is not okay, +return FALSE and start to try opening it. If you cannot open the +connection at all (e.g. because the host is not found), emit a <tt>finished()</tt> +signal and set an error code and the <a href="qnetworkprotocol.html#State-enum">QNetworkProtocol::StFailed</a> state to +the <a href="qnetworkoperation.html">QNetworkOperation</a> pointer you get here. +<p> Now, you never need to check before doing an operation yourself, if +the connection is okay. The network architecture does this, which +means it uses <tt>checkConnection()</tt> to see if an operation can be done +and if not, it tries it again and again for some time, only calling an +operation function if the connection is okay. +<p> To be able to use a network protocol with a <a href="qurloperator.html">QUrlOperator</a> (and so, for +example, in the <a href="qfiledialog.html">QFileDialog</a>), you must register the network +protocol implementation. This can be done like this: +<p> <pre> + QNetworkProtocol::<a href="qnetworkprotocol.html#registerNetworkProtocol">registerNetworkProtocol</a>( "myprot", new QNetworkProtocolFactory<MyProtocol> ); +</pre> + +<p> In this case <tt>MyProtocol</tt> would be a class you implemented as +described here (derived from <a href="qnetworkprotocol.html">QNetworkProtocol</a>) and the name of the +protocol would be "myprot". So to use it, you would do something like +<p> <pre> + <a href="qurloperator.html">QUrlOperator</a> op( "myprot://host/path" ); + op.<a href="qurloperator.html#listChildren">listChildren</a>(); +</pre> + +<p> Finally, as example of a network protocol implementation you could +look at the implementation of <a href="qlocalfs.html">QLocalFs</a>. The network extension also +contains an example implementation of a network protocol. +<p> <h3> Error Handling +</h3> +<a name="2-2"></a><p> Error handling is important for both implementing new network +protocols for and using them (through <a href="qurloperator.html">QUrlOperator</a>). +<p> After processing an operation has been finished the network operation +the <a href="qurloperator.html">QUrlOperator</a> emits the <tt>finished()</tt> signal. This has as argument +a pointer to the processed <a href="qnetworkoperation.html">QNetworkOperation</a>. If the state of this +operation is <a href="qnetworkprotocol.html#State-enum">QNetworkProtocol::StFailed</a>, the operation contains +some more information about this error. The following error codes are +defined in <a href="qnetworkprotocol.html">QNetworkProtocol</a>: +<p> <center><table cellpadding="4" cellspacing="2" border="0"> +<tr bgcolor="#a2c511"> <th valign="top">Error <th valign="top">Meaning +<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::NoError</a> +<td valign="top">No error occurred +<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::ErrValid</a> +<td valign="top">The URL you are operating on is not valid +<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::ErrUnknownProtocol</a> +<td valign="top">There is no protocol implementation available for the protocol +of the URL you are operating on (e.g. if the protocol is http +and no http implementation has been registered) +<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::ErrUnsupported</a> +<td valign="top">The operation is not supported by the protocol +<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::ErrParse</a> +<td valign="top">Parse error of the URL +<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::ErrLoginIncorrect</a> +<td valign="top">You needed to login but the username or password are wrong +<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::ErrHostNotFound</a> +<td valign="top">The specified host (in the URL) couldn't be found +<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::ErrListChildren</a> +<td valign="top">An error occurred while listing the children +<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::ErrMkDir</a> +<td valign="top">An error occurred when creating a directory +<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::ErrRemove</a> +<td valign="top">An error occurred while removing a child +<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::ErrRename</a> +<td valign="top">An error occurred while renaming a child +<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::ErrGet</a> +<td valign="top">An error occurred while getting (retrieving) data +<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::ErrPut</a> +<td valign="top">An error occurred while putting (uploading) data +<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::ErrFileNotExisting</a> +<td valign="top">A file which is needed by the operation doesn't exist +<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qnetworkprotocol.html#Error-enum">QNetworkProtocol::ErrPermissionDenied</a> +<td valign="top">The permission for doing the operation has been denied +</table></center> +<p> <a href="qnetworkoperation.html#errorCode">QNetworkOperation::errorCode</a>() returns one of these codes or +perhaps a different one if you use your an own network protocol +implementation which defines additional error codes. +<p> <tt>QNetworkOperation::protocolDetails()</tt> may also return a string which +contains an error message then which might be suitable for display to +the user. +<p> If you implement your own network protocol, you must report any +errors which occurred. First you always need to be able to +access the <a href="qnetworkoperation.html">QNetworkOperation</a> which is being processed at the +moment. This is done using <tt>QNetworkOperation::operationInProgress()</tt>, which returns a pointer to +the current network operation or 0 if no operation is processed at the +moment. +<p> Now if an error occurred and you need to handle it, do this: +<pre> + if ( operationInProgress() ) { + operationInProgress()->setErrorCode( error_code_of_your_error ); + operationInProgress()->setProtocolDetails( detail ); // optional + emit finished( operationInProgress() ); + return; + } +</pre> + +<p> That's all. The connection to the <a href="qurloperator.html">QUrlOperator</a> and so on is done +automatically. Additionally, if the error was really bad so that no +more operations can be done in the current state (e.g. if the host +couldn't be found), call <tt>QNetworkProtocol::clearOperationStack()</tt> <em>before</em> emitting <tt>finished()</tt>. +<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 +- they are just normal <tt>int</tt>s. Just be careful that the value of the +error code doesn't conflict with an existing one. +<p> An example to look at is in qt/examples/network/ftpclient. +This is the implementation of a fairly complete FTP client, which +supports uploading and downloading files, making directories, etc., +all done using <tt>QUrlOperators</tt>. +<p> You might also like to look at <a href="qftp.html">QFtp</a> (in qt/src/network/qftp.cpp) or at +the example in qt/examples/network/networkprotocol/nntp.cpp. +<p> +<!-- eof --> +<p><address><hr><div align=center> +<table width=100% cellspacing=0 border=0><tr> +<td>Copyright © 2007 +<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a> +<td align=right><div align=right>Qt 3.3.8</div> +</table></div></address></body> +</html> |