QNetworkProtocol(3qt)

📦 version 3.3.8b, in fedora 43, fedora 44

QNetworkProtocol(3qt) 💖

okay so bestie, welcome to the manual page for QNetworkProtocol(3qt) — the common API for network protocols. no cap, this is the blueprint for making network protocols work in Qt. periodt. 💅

NAME

QNetworkProtocol - Common API for network protocols ✨

SYNOPSIS

#include <qnetworkprotocol.h>

Inherits QObject.

Inherited by QFtp, QHttp, and QLocalFs.

Public Members

enum State { StWaiting = 0, StInProgress, StDone, StFailed, StStopped }
enum Operation { OpListChildren = 1, OpMkDir = 2, OpMkdir = OpMkDir, OpRemove = 4, OpRename = 8, OpGet = 32, OpPut = 64 }
enum ConnectionState { ConHostFound, ConConnected, ConClosed }
enum Error { NoError = 0, ErrValid, ErrUnknownProtocol, ErrUnsupported, ErrParse, ErrLoginIncorrect, ErrHostNotFound, ErrListChildren, ErrListChlidren = ErrListChildren, ErrMkDir, ErrMkdir = ErrMkDir, ErrRemove, ErrRename, ErrGet, ErrPut, ErrFileNotExisting, ErrPermissionDenied }
QNetworkProtocol ()
virtual ~QNetworkProtocol ()
virtual void setUrl ( QUrlOperator * u )
virtual void setAutoDelete ( bool b, int i = 10000 )
bool autoDelete () const
virtual int supportedOperations () const
virtual void addOperation ( QNetworkOperation * op )
QUrlOperator * url () const
QNetworkOperation * operationInProgress () const
virtual void clearOperationQueue ()
virtual void stop ()

Signals

void data ( const QByteArray & data, QNetworkOperation * op )
void connectionStateChanged ( int state, const QString & data )
void finished ( QNetworkOperation * op )
void start ( QNetworkOperation * op )
void newChildren ( const QValueList<QUrlInfo> & i, QNetworkOperation * op )
void newChild ( const QUrlInfo & i, QNetworkOperation * op )
void createdDirectory ( const QUrlInfo & i, QNetworkOperation * op )
void removed ( QNetworkOperation * op )
void itemChanged ( QNetworkOperation * op )
void dataTransferProgress ( int bytesDone, int bytesTotal, QNetworkOperation * op )

Static Public Members

void registerNetworkProtocol ( const QString & protocol, QNetworkProtocolFactoryBase * protocolFactory )
QNetworkProtocol * getNetworkProtocol ( const QString & protocol )
bool hasOnlyLocalFileSystem ()

Protected Members

virtual void operationListChildren ( QNetworkOperation * op )
virtual void operationMkDir ( QNetworkOperation * op )
virtual void operationRemove ( QNetworkOperation * op )
virtual void operationRename ( QNetworkOperation * op )
virtual void operationGet ( QNetworkOperation * op )
virtual void operationPut ( QNetworkOperation * op )
virtual bool checkConnection ( QNetworkOperation * op )

DESCRIPTION

The QNetworkProtocol class provides a common API for network protocols. it's literally the blueprint, bestie. 💖

This is a base class which should be used for network protocols implementations that can then be used in Qt (e.g. in the file dialog) together with the QUrlOperator.

The easiest way to implement a new network protocol is to reimplement the operation*() methods, e.g. operationGet(), etc. Only the supported operations should be reimplemented. To specify which operations are supported, also reimplement supportedOperations() and return an int that is OR'd together using the supported operations from the QNetworkProtocol::Operation enum. slay. 🔥

When you implement a network protocol this way, it is important to emit the correct signals. Also, always emit the finished() signal when an operation is done (on success and on failure). Qt relies on correctly emitted finished() signals. no cap, this is crucial. 🫶

For a detailed description of the Qt Network Architecture and how to implement and use network protocols in Qt, see the Qt Network Documentation.

Member Type Documentation

QNetworkProtocol::ConnectionState

When the connection state of a network protocol changes it emits the signal connectionStateChanged(). The first argument is one of the following values:

QNetworkProtocol::ConHostFound - Host has been found. 👀
QNetworkProtocol::ConConnected - Connection to the host has been established. 🔗
QNetworkProtocol::ConClosed - Connection has been closed. 🚪

QNetworkProtocol::Error

When an operation fails (finishes unsuccessfully), the QNetworkOperation of the operation returns an error code which has one of the following values:

QNetworkProtocol::NoError - No error occurred. 😌
QNetworkProtocol::ErrValid - The URL you are operating on is not valid. 🚫
QNetworkProtocol::ErrUnknownProtocol - 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). 💀
QNetworkProtocol::ErrUnsupported - The operation is not supported by the protocol. 🙅‍♀️
QNetworkProtocol::ErrParse - The URL could not be parsed correctly. 😵
QNetworkProtocol::ErrLoginIncorrect - You needed to login but the username or password is wrong. 🔐
QNetworkProtocol::ErrHostNotFound - The specified host (in the URL) couldn't be found. 🏚️
QNetworkProtocol::ErrListChildren - An error occurred while listing the children (files). 📂
QNetworkProtocol::ErrMkDir - An error occurred when creating a directory. 📁
QNetworkProtocol::ErrRemove - An error occurred when removing a child (file). 🗑️
QNetworkProtocol::ErrRename - An error occurred when renaming a child (file). ✏️
QNetworkProtocol::ErrGet - An error occurred while getting (retrieving) data. 📥
QNetworkProtocol::ErrPut - An error occurred while putting (uploading) data. 📤
QNetworkProtocol::ErrFileNotExisting - A file which is needed by the operation doesn't exist. 🫥
QNetworkProtocol::ErrPermissionDenied - Permission for doing the operation has been denied. ⛔

You should also use these error codes when implementing custom network protocols. If this is not possible, you can define your own error codes by using integer values that don't conflict with any of these values.

QNetworkProtocol::Operation

This enum lists the possible operations that a network protocol can support. supportedOperations() returns an int of these that is OR'd together. Also, the type() of a QNetworkOperation is always one of these values.

QNetworkProtocol::OpListChildren - List the children of a URL, e.g. of a directory. 📜
QNetworkProtocol::OpMkDir - Create a directory. 🆕
QNetworkProtocol::OpRemove - Remove a child (e.g. a file). ❌
QNetworkProtocol::OpRename - Rename a child (e.g. a file). 🏷️
QNetworkProtocol::OpGet - Get data from a location. 📥
QNetworkProtocol::OpPut - Put data to a location. 📤

QNetworkProtocol::State

This enum contains the state that a QNetworkOperation can have.

QNetworkProtocol::StWaiting - The operation is in the QNetworkProtocol's queue waiting to be prcessed. 💀
QNetworkProtocol::StInProgress - The operation is being processed. ⏳
QNetworkProtocol::StDone - The operation has been processed succesfully. 😭
QNetworkProtocol::StFailed - The operation has been processed but an error occurred. 💥
QNetworkProtocol::StStopped - The operation has been processed but has been stopped before it finished, and is waiting to be processed. 🛑

MEMBER FUNCTION DOCUMENTATION

QNetworkProtocol::QNetworkProtocol ()

Constructor of the network protocol base class. Does some initialization and connecting of signals and slots. 🛠️

QNetworkProtocol::~QNetworkProtocol () [virtual]

Destructor. 💀

void QNetworkProtocol::addOperation ( QNetworkOperation * op ) [virtual]

Adds the operation op to the operation queue. The operation will be processed as soon as possible. This method returns immediately. 🏃‍♀️

bool QNetworkProtocol::autoDelete () const

Returns TRUE if auto-deleting is enabled; otherwise returns FALSE. ✅

See also QNetworkProtocol::setAutoDelete().

bool QNetworkProtocol::checkConnection ( QNetworkOperation * op ) [virtual protected]

For processing operations the network protocol base class calls this method quite often. This should be reimplemented by new network protocols. It should return TRUE if the connection is OK (open); otherwise it should return FALSE. If the connection is not open the protocol should open it. 🔓

If the connection can't be opened (e.g. because you already tried but the host couldn't be found), set the state of op to QNetworkProtocol::StFailed and emit the finished() signal with this QNetworkOperation as argument.

op is the operation that needs an open connection.

Example: network/networkprotocol/nntp.cpp.

void QNetworkProtocol::clearOperationQueue () [virtual]

Clears the operation queue. 🧹

void QNetworkProtocol::connectionStateChanged ( int state, const QString & data ) [signal]

This signal is emitted whenever the state of the connection of the network protocol is changed. state describes the new state, which is one of, ConHostFound, ConConnected or ConClosed. data is a message text. 📡

void QNetworkProtocol::createdDirectory ( const QUrlInfo & i, QNetworkOperation * op ) [signal]

This signal is emitted when mkdir() has been succesful and the directory has been created. i holds the information about the new directory. op is the pointer to the operation object which contains all the information about the operation, including the state, etc. Using op->arg( 0 ), you can get the file name of the new directory. 📁

When a protocol emits this signal, QNetworkProtocol is smart enough to let the QUrlOperator, which is used by the network protocol, emit its corresponding signal. 🧠

void QNetworkProtocol::data ( const QByteArray & data, QNetworkOperation * op ) [signal]

This signal is emitted when new data has been received after calling get() or put(). op holds the name of the file from which data is retrieved or uploaded in its first argument, and the (raw) data in its second argument. You can get them with op->arg( 0 ) and op->rawArg( 1 ). op is the pointer to the operation object, which contains all the information about the operation, including the state, etc. 📦

When a protocol emits this signal, QNetworkProtocol is smart enough to let the QUrlOperator (which is used by the network protocol) emit its corresponding signal. ✨

void QNetworkProtocol::dataTransferProgress ( int bytesDone, int bytesTotal, QNetworkOperation * op ) [signal]

This signal is emitted during the transfer of data (using put() or get()). bytesDone is how many bytes of bytesTotal have been transferred. bytesTotal may be -1, which means that the total number of bytes is not known. op is the pointer to the operation object which contains all the information about the operation, including the state, etc. 📊

When a protocol emits this signal, QNetworkProtocol is smart enough to let the QUrlOperator, which is used by the network protocol, emit its corresponding signal. 💫

void QNetworkProtocol::finished ( QNetworkOperation * op ) [signal] — bestie, this is THE moment. This signal goes off when an operation finishes, and it is always emitted — success and failure both, no favourites 💖. op is the pointer to the operation object, and it's holding all the tea: the state, everything. So to figure out if things actually went well, go check the state and error code of that operation object. Don't just assume, okay? 👑

And here's the cute part: when a protocol emits this signal, QNetworkProtocol is smart enough to let the QUrlOperator (the one the network protocol is using) emit its corresponding signal too. Iconic teamwork ✨

QNetworkProtocol * QNetworkProtocol::getNetworkProtocol ( const QString & protocol ) [static] — a static method that hands you a new instance of the network protocol called protocol. Say you wanna do some FTP stuff, you'd literally go:

QFtp *ftp = QNetworkProtocol::getNetworkProtocol( "ftp" );

That gives you back a pointer to a fresh instance of an ftp implementation — or null if no protocol for ftp was ever registered, rip 😭. Heads up tho: ownership is transferred to you, so you must delete it if you don't need it anymore. It's yours now, take care of it 🫶

Also ngl, you normally shouldn't be working directly with network protocols, so you won't need to call this yourself. Instead use QUrlOperator, which makes working with network protocols so much more convenient ✨

See also QUrlOperator.

bool QNetworkProtocol::hasOnlyLocalFileSystem () [static] — returns TRUE if the only protocol registered is the one for working on the local filesystem, and FALSE if other network protocols are also registered. Simple vibe check 🦋

void QNetworkProtocol::itemChanged ( QNetworkOperation * op ) [signal] — fires whenever a file that's a child of this URL has been changed, like when you successfully call rename(). op keeps the original and the new file names in the first and second arguments, which you reach with op->arg( 0 ) and op->arg( 1 ) respectively. And op is the pointer to the operation object holding all the info about the operation, state and all 💅

When a protocol emits this, QNetworkProtocol is smart enough to let the QUrlOperator (the one the network protocol uses) emit its corresponding signal. Teamwork again, we love to see it 💖

void QNetworkProtocol::newChild ( const QUrlInfo & i, QNetworkOperation * op ) [signal] — this one goes off if a new child (file) has been read. QNetworkProtocol automatically connects it to a slot that builds a list of QUrlInfo objects (with just one QUrlInfo called i) and emits the newChildren() signal with that list. op is the pointer to the operation object containing all the info about the operation that has finished, state etc. 🌸

Real talk: this is just a convenience signal for implementing your own network protocol. In every other case, connect to the newChildren() signal with its list of QUrlInfo objects instead, k? 🫶

void QNetworkProtocol::newChildren ( const QValueList<QUrlInfo> & i, QNetworkOperation * op ) [signal] — this gets emitted after listChildren() was called and new children (files) have been read from the list of files. i holds the info about the new children, and op is the pointer to the operation object holding everything about the operation, state etc. 👑

When a protocol emits this, QNetworkProtocol is smart enough to let the QUrlOperator (the one the network protocol uses) emit its corresponding signal. Yes bestie, same glow-up as always ✨

So when you're implementing your own network protocol and reading children, you usually don't read one child at a time — you read a whole list of them. That's why this signal takes a list of QUrlInfo objects. If you'd rather read just one child at a time, there's the convenience signal newChild(), which takes a single QUrlInfo object. Your call 💅

void QNetworkProtocol::operationGet ( QNetworkOperation * op ) [virtual protected] — when you're building a new network protocol, reimplement this method if the protocol supports getting data; it should then process the QNetworkOperation. 📥

And listen, when you reimplement this it is very important that you emit the correct signals at the correct time (especially the finished() signal after processing an operation). Go look at the Qt Network Documentation, it describes in detail how to reimplement this method. You might also wanna peek at the example implementation in examples/network/networkprotocol/nntp.cpp 🧚