Network Module

QNetworkProtocol 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.

Note 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!

To implement a network protocol create a class derived from QNetworkProtocol.

Other classes will use this network protocol implementation to operate on it. So you should reimplement following protected members

    void QNetworkProtocol::operationListChildren( QNetworkOperation *op );
    void QNetworkProtocol::operationMkDir( QNetworkOperation *op );
    void QNetworkProtocol::operationRemove( QNetworkOperation *op );
    void QNetworkProtocol::operationRename( QNetworkOperation *op );
    void QNetworkProtocol::operationGet( QNetworkOperation *op );
    void QNetworkProtocol::operationPut( QNetworkOperation *op );

Some notes on reimplementing these methods: You always get a pointer to a QNetworkOperation 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 QNetworkProtocol::StInProgress. If you finished processing the operation, set the state to QNetworkProtocol::StDone if it was successful or QNetworkProtocol::StFailed if an error occurred. If an error occurred you must set an error code (see QNetworkOperation::setErrorCode()) and if you know some details (e.g. an error message) you can also set this message to the operation pointer (see QNetworkOperation::setProtocolDetail()). Also you get all the relevant information (type, arguments, etc.) about the operation from the QNetworkOperation pointer. For details about which arguments you can get and set look at QNetworkOperation's class documentation.

If you reimplement an operation function, it's very important to emit the correct signals at the correct time: In general always emit finished() 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 finished() signals! Then there are some more specialized signals which are specific to operations:

• Emit in operationListChildren:
  • start() just before starting to list the children
  • newChildren() when new children are read
• Emit in operationMkDir:
  • createdDirectory() after the directory has been created
  • newChild() (or newChildren()) after the directory has been created (since a new directory is a new child)
• Emit in operationRemove:
  • removed() after a child has been removed
• Emit in operationRename:
  • itemChanged() after a child has been renamed
• Emit in operationGet:
  • data() each time new data has been read
  • dataTransferProgress() each time new data has been read to indicate how much of the data has been read now.
• Emit in operationPut:
  • dataTransferProgress() 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.

And remember, always emit the finished() signal at the end!

For more details about these signals' arguments look at the QNetworkProtocol class documentation.

Here is a list of which QNetworkOperation arguments you can get and which you must set in which function:

(To get the URL on which you should work, use the QNetworkProtocol::url() method which returns a pointer to the URL operator. Using that you can get the path, host, name filter, etc.)

• In operationListChildren:
  • Nothing.
• In operationMkDir:
  • QNetworkOperation::arg( 0 ) contains the name of the directory which should be created
• In operationRemove:
  • QNetworkOperation::arg( 0 ) contains the name of the file which should be removed. Normally this is a relative name. But it could be absolute. Use QUrl( op->arg( 0 ) ).fileName() to get the filename.
• In operationRename:
  • QNetworkOperation::arg( 0 ) contains the name of the file which should be renamed
  • QNetworkOperation::arg( 1 ) contains the name to which it should be renamed.
• In operationGet:
  • QNetworkOperation::arg( 0 ) contains the full URL of the file which should be retrieved.
• In operationPut:
  • QNetworkOperation::arg( 0 ) contains the full URL of the file in which the data should be stored.
  • QNetworkOperation::rawArg( 1 ) contains the data which should be stored in QNetworkOperation::arg( 0 )

In summary: If you reimplement an operation function, you must emit some special signals and at the end you must always emit a finished() signal, regardless of success or failure. Also you must change the state of the QNetworkOperation during processing. You can also get and set QNetworkOperation arguments as the operation progresses.

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

    int QNetworkProtocol::supportedOperations() const;

In your implementation of this method return an int value which is constructed by OR-ing together the correct values (supported operations) of the following enum (of QNetworkProtocol):

• OpListChildren
• OpMkDir
• OpRemove
• OpRename
• OpGet
• OpPut

For example, if your protocol supports listing children and renaming them, your implementation of supportedOperations() should do this:

    return OpListChildren | OpRename;

The last method you must reimplement is

    bool QNetworkProtocol::checkConnection( QNetworkOperation *op );

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 finished() signal and set an error code and the QNetworkProtocol::StFailed state to the QNetworkOperation pointer you get here.

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 checkConnection() 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.

To be able to use a network protocol with a QUrlOperator (and so, for example, in the QFileDialog), you must register the network protocol implementation. This can be done like this:

    QNetworkProtocol::registerNetworkProtocol( "myprot", new QNetworkProtocolFactory<MyProtocol> );

In this case MyProtocol would be a class you implemented as described here (derived from QNetworkProtocol) and the name of the protocol would be "myprot". So to use it, you would do something like

    QUrlOperator op( "myprot://host/path" );
    op.listChildren();

Finally, as example of a network protocol implementation you could look at the implementation of QLocalFs. The network extension also contains an example implementation of a network protocol.

Error Handling

    if ( operationInProgress() ) {
        operationInProgress()->setErrorCode( error_code_of_your_error );
        operationInProgress()->setProtocolDetails( detail ); // optional
        emit finished( operationInProgress() );
        return;
    }