You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
467 lines
26 KiB
467 lines
26 KiB
14 years ago
|
<!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>
|