Описание класса QAbstractSocketКласс QAbstractSocket предоставляет возможности, общие для сокетов всех типов. Далее... #include <QAbstractSocket> Унаследован от: QIODevice. От него наследуются: QTcpSocket и QUdpSocket. Замечание: Все функции в этом классе реентерабельны. Открытые типы
Открытые функции
Переопределённые открытые функции
Сигналы
Защищенные функции
Переопределённые защищённые функции
Защищённые слоты
Дополнительные унаследованные члены
Подробное описаниеКласс QAbstractSocket предоставляет возможности, общие для сокетов всех типов. Класс QAbstractSocket является базовым для классов QTcpSocket и QUdpSocket и содержит все возможности, общие для этих двух классов. Если вам требуется сокет, вы можете сделать одно из двух:
TCP (Transmission Control Protocol) представляет собой надежный, потокоориентированный, основывающийся на соединениях транспортный протокол. UDP (User Datagram Protocol) представляет собой ненадежный, датаграммный транспортный протокол без соединений. На практике это означает, что протокол TCP более приспособлен для непрерывной передачи данных, в то время как более "легкий" протокол UDP можно использовать там, где надежность менее важна. API класса QAbstractSocket унифицирует большинство различий между этими протоколами. Например, хотя протокол UDP соединений не поддерживает, функция connectToHost() создает виртуальное соединение для UDP-сокетов, что дает возможность пользоваться объектом класса QAbstractSocket более или менее одинаковым образом вне зависимости от используемого протокола. Технически QAbstractSocket запоминает адрес и порт, переданные функции connectToHost(), а функции вроде read() и write() будут потом использовать эти значения. В любой момент времени объект класса QAbstractSocket находится в некотором состоянии (его возвращает функция state()). Начальным состоянием является UnconnectedState. После вызова connectToHost(), сокет переходит в состояние HostLookupState. Если узел найден, объект QAbstractSocket переходит в состояние ConnectingState и посылает сигнал hostFound(). Когда соединение установлено, он переходит в состояние ConnectedState и посылает connected(). Если на любом из этих шагов происходит ошибка, посылается сигнал error(). Всякий раз, когда состояние изменяется, посылается сигнал stateChanged(). Для удобства имеется функция isValid(), которая возвращает true, если сокет готов для чтения и записи, но учтите, что прежде, чем чтение или запись можно будет производить, сокет должен находиться в состоянии ConnectedState. Производите чтение или запись с помощью вызова read() или write() или используйте вспомогательные функции readLine() и readAll(). QAbstractSocket также наследует getChar(), putChar() и ungetChar() от QIODevice, который работает с отдельными байтами. Сигнал bytesWritten() испускается когда данные записаны в сокет (т.е., когда клиент прочитает данные). Обратите внимание на то, что Qt не ограничивает размер буфера записи. Вы можете следить за его размером перехватывая сигнал. Сигнал readyRead() испускается каждый раз, когда новая порция данных приходит. Тогда bytesAvailable() возвращает число байт, доступных для чтения. Обычно вы соединяетесь с сигналом readyRead() слотом и читаете все доступные данные. Если вы не хотите читать все данные за один раз, оставшееся всегда доступно позже, всё, что приходит потом присоединяется к накопленному в буфере чтения QAbstractSocket'а. Для ограничения буфера чтения, вызовите setReadBufferSize(). Для закрытия сокета, вызовите disconnectFromHost(). QAbstractSocket enters QAbstractSocket::ClosingState. После того, как все необходимые данные были записаны в сокет, QAbstractSocket закрывает соединение, устанавливает QAbstractSocket::ClosedState и высылает disconnected(). Если вы хотите отменить соединение немедленно с откатом всех переданных данных, используйте abort(). Если удалённый узел закрывает соединение, QAbstractSocket вышлет ошибку(QAbstractSocket::RemoteHostClosedError), в то время как состояние сокета будет ConnectedState, а потом будет выслан сигнал disconnected(). Порт и адрес соединённого узла доступны с помощью peerPort() и peerAddress(). peerName() возвращает имя узла, как оно определено connectToHost(). localPort() и localAddress() возвращают порт и адрес локального сокета. QAbstractSocket обеспечивает набор функций, которые приостанавливают обращения к потоку, пока определённый сигнал не будет послан. Эти функции могут быть использованы для реализации блокируемых сокетов:
Покажем на примере: int numRead = 0, numReadTotal = 0; char buffer[50]; forever { numRead = socket.read(buffer, 50); // сделать что-то с массивом numReadTotal += numRead; if (numRead == 0 && !socket.waitForReadyRead()) break; } Если waitForReadyRead() возвращает false, соединение закрылось или произошла ошибка. Программирование с блокируемыми сокетами радикально отличается от работы с обычными сокетами. Блокируемые сокеты не требуют зацикливания событий и обычно помогает писать более простой код. Однако в GUI приложении они могут быть использованы только с не-GUI потоками, чтобы избежать замораживания графического интерфейса. Смотрите примеры network/fortuneclient и network/blockingfortuneclient, где реализованы оба подхода. Замечание: Мы не одобряем использование блокирующих функций вместе с сигналами. Использовать нужно только одну из двух возмоностей. QAbstractSocket может быть использован с операциями потоков QTextStream и QDataStream (operator<<() и operator>>()). Существует одна особенность, которую следует знать: вы должны убедиться, что достаточно доступных для чтения данных, чтобы использовать операцию operator>>(). Смотрите также QFtp, QNetworkAccessManager и QTcpServer. Описание типов-членовenum QAbstractSocket::NetworkLayerProtocolЭто перечисление описывает какие версии протокола на межсетевом уровне используются в Qt.
Смотрите также QHostAddress::protocol(). enum QAbstractSocket::SocketErrorЭто перечисление описывает ошибки, которые случаются при работе с сокетами.
Смотрите также QAbstractSocket::error(). enum QAbstractSocket::SocketOptionДанное перечисление представляет опции, которые могут быть установлены у сокета. Если требуется, они могут установить после получения сигнала connected() от сокета или после получения нового сокета от QTcpServer.
Данное перечисление было введено или модифицировано в Qt 4.6. Смотрите также QAbstractSocket::setSocketOption() и QAbstractSocket::socketOption(). enum QAbstractSocket::SocketStateЭто перечисление описывает различные состояния сокета.
Смотрите также QAbstractSocket::state(). enum QAbstractSocket::SocketTypeЭто перечисление описывает протокол транспортного уровня.
Смотрите также QAbstractSocket::socketType(). Описание функций-членовQAbstractSocket::QAbstractSocket ( SocketType socketType, QObject * parent )Создаёт новый абстрактный сокет типа socketType. Аргумент parent передаётся конструктору QObject. Смотрите также socketType(), QTcpSocket и QUdpSocket. QAbstractSocket::~QAbstractSocket () [virtual]Уничтожает сокет. void QAbstractSocket::abort ()Закрывает текущее соединение и перезагружает сокет. В отличие от disconnectFromHost(), эта функция немедленно закрывает сокет, очищая буфер записи. Смотрите также disconnectFromHost() и close(). bool QAbstractSocket::atEnd () const [virtual]Переопределено из QIODevice::atEnd(). Возвращает true если в настоящее время больше нет данных, доступных для чтения; в противном случае возвратит false. Чаще всего эта функция используется когда в цикле читаются данные из сокета. Например: // Этот слот соединен с QAbstractSocket::readyRead() void SocketClass::readyReadSlot() { while (!socket.atEnd()) { QByteArray data = socket.read(100); .... } } Смотрите также bytesAvailable() и readyRead(). qint64 QAbstractSocket::bytesAvailable () const [virtual]Переопределено из QIODevice::bytesAvailable(). Возвращает число присланных байт, которые ждут прочтения. Смотрите также bytesToWrite() и read(). qint64 QAbstractSocket::bytesToWrite () const [virtual]Переопределено из QIODevice::bytesToWrite(). Возвращает число байт, которые ждут отправки. Байты будут отосланы, когда управление вернётся обратно, или при вызове flush(). Смотрите также bytesAvailable() и flush(). bool QAbstractSocket::canReadLine () const [virtual]Переопределено из QIODevice::canReadLine(). Возвращает true, если строка данных может быть прочитана из сокета; в противном случает возвращает false. Смотрите также readLine(). void QAbstractSocket::close () [virtual]Переопределено из QIODevice::close(). Закрывает устройство ввода/вывода для сокета, разъединяет соединения сокета с узлом, закрывает сокет и сбрасывает имя, адрес, номер порта и дескриптор базового сокет. Описание действий, которые происходят когда устройство ввода/вывод закрывается смотрите QIODevice::close(). Смотрите также abort(). void QAbstractSocket::connectToHost ( const QString & hostName, quint16 port, OpenMode openMode = ReadWrite )Пытается создать соединение с узлом hostName по порту port. Сокет открывается по переданному openMode и сначала переходит в HostLookupState, затем выполняет поиск hostName. Если поиск завершился успешно, посылается hostFound() и QAbstractSocket переходит в состояние ConnectingState. Затем он пытается соединиться по адресу, полученному в результате поиска. В итоге, если соединение установлено, QAbstractSocket переходит в состояние ConnectedState и посылает сигнал connected(). На любом шаге сокет может отправить сигнал об ошибке error(). hostName может быть как IP-адресом в виде строки (например, "43.195.83.32"), так и именем узла (например, "example.com"). QAbstractSocket будет совершать поиск, только если это необходимо. port представляется в текущей степени байта. Смотрите также state(), peerName(), peerAddress(), peerPort() и waitForConnected(). void QAbstractSocket::connectToHost ( const QHostAddress & address, quint16 port, OpenMode openMode = ReadWrite )Это перегруженная функция. Пытается создать соединение с address по порту port. void QAbstractSocket::connectToHostImplementation ( const QString & hostName, quint16 port, OpenMode openMode = ReadWrite ) [protected slot]Содержит реализацию connectToHost(). Пытается создать соединение с узлом hostName по порту port. Сокет открывается в режиме openMode. Эта функция была введена в Qt 4.1. void QAbstractSocket::connected () [signal]Этот сигнал испускается после того, как connectToHost() была вызвана и соединение было успешно установлено. Замечание: В некоторых операционных системах сигнал connected() может быть непосредственно отправлен из вызова connectToHost() для соединения с localhost. Смотрите также connectToHost() и disconnected(). void QAbstractSocket::disconnectFromHost ()Попытка закрыть сокет. Если есть данные для записи, QAbstractSocket перейдёт в состояние ClosingState и будет ждать, пока данные не будут переданы. В конце концов, он перейдёт в состояние UnconnectedState и пошлёт сигнал disconnected(). Смотрите также connectToHost(). void QAbstractSocket::disconnectFromHostImplementation () [protected slot]Содержит реализацию disconnectFromHost(). Эта функция была введена в Qt 4.1. void QAbstractSocket::disconnected () [signal]Этот сигнал посылается, когда сокет разрывает соединение. Предупреждение: Если в соединенном с ним слоте нужно удалить sender() этого сигнала, то используйте функцию deleteLater(). Смотрите также connectToHost(), disconnectFromHost() и abort(). SocketError QAbstractSocket::error () constВозвращает тип последней произошедшей ошибки. Смотрите также state() и errorString(). void QAbstractSocket::error ( QAbstractSocket::SocketError socketError ) [signal]Этот сигнал посылается после того, как произошла ошибка. Параметр socketError описывает тип ошибки. QAbstractSocket::SocketError - незарегистрированный метатип, поэтому для соединений через очереди вы будете регистрировать его с помощью Q_DECLARE_METATYPE() и qRegisterMetaType(). Смотрите также error(), errorString() и Создание пользовательских типов Qt. bool QAbstractSocket::flush ()Эта функция передаёт по основному сетевому сокету столько байт из внутреннего буфера записи, сколько это возможно без блокировки. Если данные были записаны, функция вернёт true; в противном случае возвращается false. Вызывайте эту функцию, если вам необходимо немедленно отправить данные по QAbstractSocket. Число переданный байт будет зависеть от операционной системы. В большинстве случаев вызывать эту функцию нет необходимости, так как QAbstractSocket начинает отправку данных автоматически, как только к нему переходит управление. Если этого не происходит, лучше вызывайте waitForBytesWritten() вместо текущей функции. Смотрите также write() и waitForBytesWritten(). void QAbstractSocket::hostFound () [signal]Этот сигнал посылается после вызова connectToHost() и успешного завершения поиска. Замечание: Начиная с Qt 4.6.3 QAbstractSocket может отправить hostFound() непосредственно из вызова connectToHost() поскольку результат DNS может быть кэширован. Смотрите также connected(). bool QAbstractSocket::isSequential () const [virtual]Переопределено из QIODevice::isSequential(). bool QAbstractSocket::isValid () constВозвращает true, если сокет корректен и готов к использованию; в противном случае возвращает false. Замечание: Состояние сокета должно быть ConnectedState до того, как будет произведено чтение или запись. Смотрите также state(). QHostAddress QAbstractSocket::localAddress () constВозвращает адрес узла локального сокета, если это возможно; если нет, возвращает QHostAddress::Null. Как правило, это главный IP-адрес узла, но может являться и QHostAddress::LocalHost (127.0.0.1) для соединений локального узла. Смотрите также localPort(), peerAddress() и setLocalAddress(). quint16 QAbstractSocket::localPort () constВозвращает порт узла (в родном байтовом виде) локального сокета, если он доступен; если нет, возвращается 0. Смотрите также localAddress(), peerPort() и setLocalPort(). QHostAddress QAbstractSocket::peerAddress () constВозвращает адрес присоединённого узла, если сокет находится в состоянии ConnectedState; в противном случае возвращает QHostAddress::Null. Смотрите также peerName(), peerPort(), localAddress() и setPeerAddress(). QString QAbstractSocket::peerName () constВозвращает имя присоединённого узла, определённого в connectToHost(), или пустую строку QString, если connectToHost() был закрыт. Смотрите также peerAddress(), peerPort() и setPeerName(). quint16 QAbstractSocket::peerPort () constВозвращает порт присоединённого узла, если сокет находится в ConnectedState; в противном случае возвращает 0. Смотрите также peerAddress(), localPort() и setPeerPort(). QNetworkProxy QAbstractSocket::proxy () constВозвращает сетевой прокси для данного сокета. По умолчанию использует QNetworkProxy::DefaultProxy, что означает что этот сокет будет запрашивать для приложения настройки прокси. Эта функция была введена в Qt 4.1. Смотрите также setProxy(), QNetworkProxy и QNetworkProxyFactory. void QAbstractSocket::proxyAuthenticationRequired ( const QNetworkProxy & proxy, QAuthenticator * authenticator ) [signal]Этот сигнал посылается, когда используется прокси proxy, требующий аутентификации. Объект authenticator может быть заполнен необходимыми сведениями для продолжения соединения. Замечание: невозможно использовать QueuedConnection для подключения к этому сигналу, так как соединение не удастся установить без заполнения информации для аутентификации при возвращении сигнала. Эта функция была введена в Qt 4.3. Смотрите также QAuthenticator и QNetworkProxy. qint64 QAbstractSocket::readBufferSize () constВозвращает размер внутреннего буфера чтения. Это ограничение определяет, какой объём данных может получить клиент, прежде чем вы вызовите read() или readAll(). Размер, равный 0 (по умолчанию), означает, что буфер не ограничен, что позволяет быть уверенным в том, что данные не потеряются. Смотрите также setReadBufferSize() и read(). qint64 QAbstractSocket::readData ( char * data, qint64 maxSize ) [virtual protected]Переопределено из QIODevice::readData(). qint64 QAbstractSocket::readLineData ( char * data, qint64 maxlen ) [virtual protected]Переопределено из QIODevice::readLineData(). void QAbstractSocket::setLocalAddress ( const QHostAddress & address ) [protected]Устанавливает адрес локальной стороны соединения в address. Вы можете вызывать эту функцию в подклассе QAbstractSocket для изменения возвращаемого значения функцией localAddress() после установления соединения. Эта функциональность также используется в прокси соединениях для создания виртуальных настроек соединения. Помните, что эта функция не связывает локальный адрес сокета до соединения (например, QUdpSocket::bind()). Эта функция была введена в Qt 4.1. Смотрите также localAddress(), setLocalPort() и setPeerAddress(). void QAbstractSocket::setLocalPort ( quint16 port ) [protected]Устанавливает локальный порт соединения в port. Вы можете вызывать эту функцию в подклассе QAbstractSocket для изменения возвращаемого значения функцией localPort() после установления соединения. Эта функциональность также используется в прокси соединениях для создания виртуальных настроек соединения. Помните, что эта функция не связывает локальный порт сокета до соединения (например, QUdpSocket::bind()). Эта функция была введена в Qt 4.1. Смотрите также localPort(), localAddress(), setLocalAddress() и setPeerPort(). void QAbstractSocket::setPeerAddress ( const QHostAddress & address ) [protected]Устанавливает адрес удалённой стороны соединения в address. Вы можете вызывать эту функцию в подклассе QAbstractSocket для изменения возвращаемого значения функцией peerAddress() после установления соединения. Эта функциональность также используется в прокси соединениях для создания виртуальных настроек соединения. Эта функция была введена в Qt 4.1. Смотрите также peerAddress(), setPeerPort() и setLocalAddress(). void QAbstractSocket::setPeerName ( const QString & name ) [protected]Устанавливает имя удалённого узла в name. Вы можете вызывать эту функцию в подклассе QAbstractSocket для изменения возвращаемого значения функцией peerName() после установления соединения. Эта функциональность также используется в прокси соединениях для создания виртуальных настроек соединения. Эта функция была введена в Qt 4.1. Смотрите также peerName(). void QAbstractSocket::setPeerPort ( quint16 port ) [protected]Устанавливает порт удалённой стороны соединения в port. Вы можете вызывать эту функцию в подклассе QAbstractSocket для изменения возвращаемого значения функцией peerPort() после установления соединения. Эта функциональность также используется в прокси соединениях для создания виртуальных настроек соединения. Эта функция была введена в Qt 4.1. Смотрите также peerPort(), setPeerAddress() и setLocalPort(). void QAbstractSocket::setProxy ( const QNetworkProxy & networkProxy )Устанавливает явно сетевой прокси для текущего сокета в networkProxy. Для выключения использования прокси для текущего сокета используйте тип прокси QNetworkProxy::NoProxy: socket->setProxy(QNetworkProxy::NoProxy); Значение по умолчанию для прокси равно QNetworkProxy::DefaultProxy, что означает что сокет будет использовать настройки приложения: если прокси установлен с помощью QNetworkProxy::setApplicationProxy, он будет использовать это; в противном случае, если фабрика установлена с помощью QNetworkProxyFactory::setApplicationProxyFactory, она будет запрашивать эту фабрику с помощью типа QNetworkProxyQuery::TcpSocket. Эта функция была введена в Qt 4.1. Смотрите также proxy(), QNetworkProxy и QNetworkProxyFactory::queryProxy(). void QAbstractSocket::setReadBufferSize ( qint64 size )Устанавливает размер буфера QAbstractSocket чтения равным size байт. Если установлен предел размера буфера, QAbstractSocket не будет помещать в буфер больше данных, чем этот предел. В частности, если размер буфер установлен как 0, предел не установлен, все поступающие данные буферизируются. Это значение по умолчанию. Эта опция полезна, если вы хотите только читать данные в определённое время (например, в случае с потоковым приложением реального времени) или вы хотите защитить сокет от переполнения, что может привести к нехватке памяти. Только QTcpSocket использует внутренний буфер QAbstractSocket; QUdpSocket не использует буферизацию вовсе, а скорее основывается на возможностях буферизации операционной системы. Потому вызов функции QUdpSocket не вызовет никакого эффекта. Смотрите также readBufferSize() и read(). bool QAbstractSocket::setSocketDescriptor ( int socketDescriptor, SocketState socketState = ConnectedState, OpenMode openMode = ReadWrite )Инициализирует QAbstractSocket с родным дескриптором сокета socketDescriptor. Возвращает true, если socketDescriptor принят как валидный; в противном случае возвращает false. Сокет открывается в режиме, определённом в openMode, и переводится в состояние, определённое в socketState. Замечание: невозможно инициализировать два абстрактных сокета с одинаковыми родными дескрипторами. Смотрите также socketDescriptor(). void QAbstractSocket::setSocketError ( SocketError socketError ) [protected]Устанавливает тип последней произошедшей ошибки в socketError. Смотрите также setSocketState() и setErrorString(). void QAbstractSocket::setSocketOption ( QAbstractSocket::SocketOption option, const QVariant & value )Устанавливает заданную опцию option равным значению, описываемым значением value. Эта функция была введена в Qt 4.6. Смотрите также socketOption(). void QAbstractSocket::setSocketState ( SocketState state ) [protected]Устанавливает состояние сокета в state. Смотрите также state(). int QAbstractSocket::socketDescriptor () constВозвращает родной дескриптор сокета объекта QAbstractSocket, если он доступен; в противном случае возвращает -1. Если сокет использует QNetworkProxy, возвращаемый дескриптор может быть недоступен для использования с родными функциями сокета. Дескриптор сокета недоступен, когда QAbstractSocket находится в состоянии UnconnectedState. Смотрите также setSocketDescriptor(). QVariant QAbstractSocket::socketOption ( QAbstractSocket::SocketOption option )Возвращает значение опции option. Эта функция была введена в Qt 4.6. Смотрите также setSocketOption(). SocketType QAbstractSocket::socketType () constВозвращает тип сокета (TCP, UDP или другое). Смотрите также QTcpSocket и QUdpSocket. SocketState QAbstractSocket::state () constВозвращает состояние сокета. Смотрите также error(). void QAbstractSocket::stateChanged ( QAbstractSocket::SocketState socketState ) [signal]Этот сигнал испускается, когда изменяется состояние сокета QAbstractSocket. Параметр socketState является новым состоянием. QAbstractSocket::SocketState - незарегистрированный метатип, поэтому для соединений через очереди вы будете регистрировать его с помощью Q_REGISTER_METATYPE() и qRegisterMetaType(). Смотрите также state() и Создание пользовательских типов Qt. bool QAbstractSocket::waitForBytesWritten ( int msecs = 30000 ) [virtual]Переопределено из QIODevice::waitForBytesWritten(). bool QAbstractSocket::waitForConnected ( int msecs = 30000 )Ждёт msecs миллисекунд, пока установится соединение. Если соединение установлено, возвращает true; если нет - false. В случае, если функция возвращает false, вы можете вызвать error() для определения, что за ошибка произошла. Следующий пример ждёт одну секунду для установления соединения: socket->connectToHost("imap", 143); if (socket->waitForConnected(1000)) qDebug("Connected!"); Если задать время тайм-аута как -1, таймер будет отключён. Замечание: Эта функция может ждать немного дольше чем msecs, в зависимости от времени требуемого для завершения поиска узла. Замечание: Множественные вызовы этой функции не ведут к сложению времени. Если время ожидания функции вышло, процесс соединения будет прерван. Смотрите также connectToHost() и connected(). bool QAbstractSocket::waitForDisconnected ( int msecs = 30000 )Ждёт msecs миллисекунд, пока сокет разорвёт соединение. Если соединение разорвано, функция возвращает true; если нет - false. В случае, если функция возвращает false, вы можете вызвать error() для определения, что за ошибка произошла. Следующий пример ждёт до разрыва соединения одну секунду: socket->disconnectFromHost(); if (socket->state() == QAbstractSocket::UnconnectedState || socket->waitForDisconnected(1000)) qDebug("Disconnected!"); Если задать время тайм-аута как -1, таймер будет отключён. Смотрите также disconnectFromHost() и close(). bool QAbstractSocket::waitForReadyRead ( int msecs = 30000 ) [virtual]Переопределено из QIODevice::waitForReadyRead(). Эта функция блокирует, пока доступны для чтения новые данные и не будет испущен сигнал readyRead(). Эта функция имеет тайм-аут после msecs миллисекунд; по умолчанию тайм-аут равен 30000 мс. Функция возвращает true если сигнал readyRead() испущен и имеются новые данные, доступные для чтения; в противном случае она возвращает false (если произойдет ошибка или время выполнения операции истекло). Смотрите также waitForBytesWritten(). qint64 QAbstractSocket::writeData ( const char * data, qint64 size ) [virtual protected]Переопределено из QIODevice::writeData(). |
Попытка перевода Qt документации. Если есть желание присоединиться, или если есть замечания или пожелания, то заходите на форум: Перевод Qt документации на русский язык... Люди внесшие вклад в перевод: Команда переводчиков |