QSocket类

Qt 3.0.5

主页 | 所有的类 | 主要的类 | 注释的类 | 分组的类 | 函数

QSocket类参考
[网络模块]

QSocket类提供了一个有缓冲的TCP连接。 详情请见……

#include <qsocket.h>

继承了QObjectQIODevice

所有成员函数的列表。

公有成员

信号

保护槽


详细描述

QSocket类提供了一个有缓冲的TCP连接。

它提供一个完全非阻塞的QIODevice,使用套接字特征代码来修改和扩展了QIODevice的应用编程接口。

你和可能常常调用的connectToHost()、bytesAvailable()、canReadLine()这些函数并且它们继承了QIODevice。

connectToHost()是一个最常用的函数。就像它的名字那样,它打开一个被命名的主机的连接。

绝大多数网络协议是基于包的或者基于行的。canReadLine()可以识别一个连接中是否包含一个完全不可读的的行,并且bytesAvailable()返回可以被读取的字节数量。

信号error()、connected()、readyRead()和connectionClosed()通知你连接的进展。还有一些不太常用的信号。当connectToHost()已经完成它的DNS查找并且正在开始它的TCP连接时,hostFound()被发射。当close()成功时,delayedCloseFinished()被发射。当QSocket把它的“写”队列中的数据移到TCP运行中。

还有几个套接字的访问函数:state()返回这个对象是否空闲,是否正在做DNS查找,是否正在连接,还是一个正在操作的连接,等等。address()和port()返回连接所使用的IP地址和端口。peerAddress()和peerPort()函数返回自身所用到的IP地址和端口并且peerName()返回自身所用的名称(通常是被传送给connectToHost()的名字)。socket() 返回这个套接字所用到的QSocketDevice的指针。

QSocket继承了QIODevice并且重新实现了一些函数。通常你可以把它作为QIODevice来写,并且绝大多数情况也可以作为QIODevice来读。但匹配的不够完美,因为QIODevice应用编程接口是为同一个机器可以控制的设备而设计的,而异步的端对端网络连接和这个不太一样。例如,没有什么可以和QIODevice::size()确切地匹配。open()、close()、flush()、size()、at()、atEnd()、readBlock()、writeBlock()、getch()、putch()、ungetch()和readLine()的文档详细地描述了不同点。

也可以参考QSocketDeviceQHostAddressQSocketNotifier输入/输出和网络


成员类型文档

QSocket::Error

这个枚举变量指定了可能的错误:

  • QSocket::ErrConnectionRefused - 如果连接被拒绝
  • QSocket::ErrHostNotFound - 如果主机没有被找到
  • QSocket::ErrSocketRead - 如果读取套接字失败

QSocket::State

这个枚举变量定义了连接状态:

  • QSocket::Idle - 如果没有连接
  • QSocket::HostLookup - 在DNS查找期间
  • QSocket::Connecting - 在TCP连接建立期间
  • QSocket::Connected - 当存在一个可操作的连接时
  • QSocket::Closing - 如果这个套接字正在关闭,但是还没有被关闭。

成员函数文档

QSocket::QSocket ( QObject * parent = 0, const char * name = 0 )

创建一个QSocket::Idle状态的QSocket对象。

parentname参数被传递给QObject的构造函数。

QSocket::~QSocket () [虚]

销毁这个套接字。如果需要关闭连接。

也可以参考close()。

QHostAddress QSocket::address () const

返回这个套接字的主机地址。(这通常就是主机的主IP地址,但是对于到localhost的连接可能是127.0.0.1。)

Offset QSocket::at () const [虚]

返回当前的读索引。因为QSocket是一个顺序设备,当前读索引总是0。

Reimplemented from QIODevice.

bool QSocket::at ( Offset index ) [虚]

这是一个重载成员函数,提供了方便。它的行为基本上和上面的函数相同。

向前移动读索引到index并且如果操作成功返回真。向前移动读索引意味着忽略进入的数据。

QIODevice中重新实现的。

bool QSocket::atEnd () const [虚]

如果没有更多的数据可以读取,返回真,否则返回假。

QIODevice中重新实现的。

Q_ULONG QSocket::bytesAvailable () const

返回可以读取的进入数据的字节数,也就是输入缓存的大小。等于size()。

也可以参考bytesToWrite()。

实例:network/networkprotocol/nntp.cpp

Q_ULONG QSocket::bytesToWrite () const

返回正在等待被写的数据的字节数,也就是输出缓存的大小。

也可以参考bytesAvailable()。

void QSocket::bytesWritten ( int nbytes ) [信号]

当数据被实际写到网络时,这个信号被发射。nbytes参数指定了多少字节被写了。

bytesToWrite()函数常常会在相同的上下文中被使用,并且它说明了还有多少数量的缓存字节数要写。

也可以参考writeBlock()和bytesToWrite()。

bool QSocket::canReadLine () const

如果这一次可以从这个套接字中读取一个完整行的文本,返回真,否则返回假。

注意如果本地出乎意料地关闭连接,这个函数返回假。这也就是说这样的循环不会工作:

    while( !socket->canReadLine() ) // 错了。
        ...
  

也可以参考readLine()。

实例:network/clientserver/client/client.cppnetwork/httpd/httpd.cppnetwork/mail/smtp.cppnetwork/networkprotocol/nntp.cpp

void QSocket::close () [虚]

关闭这个套接字。

读缓存被清空。

如果输出缓存是空的,状态被设置为QSocket::Idle并且连接被立即终止。如果输出缓存中还有数据要写,QSocket进入QSocket::Closing状态并且等待这些数据被写完。当所有的输出数据被写完,状态被设置为QSocket::Idle并且连接被终止。在这时,delayedCloseFinished() 喜好被发射。

也可以参考state()和bytesToWrite()。

实例:network/clientserver/client/client.cppnetwork/httpd/httpd.cppnetwork/networkprotocol/nntp.cpp

QIODevice中重新实现的。

void QSocket::connectToHost ( const QString & host, Q_UINT16 port ) [虚]

试图连接主机host的指定端口port并且立即返回。

任何连接或者正在进行的连接被立即关闭,并且QSocket进入HostLookup 状态。当查找成功,它发射hostFound(),开始一个TCP连接并且进入Connecting状态。最后,当连接成功时,它发射connected()并且进入Connected状态。如果在任何一个地方出现错误,它发射error()。

host可以是一个字符串形式的IP地址,也可以是一个DNS名称。如果需要QSocket将会进行一个普通的DNS查找。注意port是本地字节顺序,不像其它库那样。

也可以参考state()。

实例:network/clientserver/client/client.cppnetwork/mail/smtp.cppnetwork/networkprotocol/nntp.cpp

void QSocket::connected () [信号]

connectToHost()已经被调用并且连接已经被成功建立之后,这个信号被发射。

也可以参考connectToHost()和connectionClosed()。

实例:network/clientserver/client/client.cppnetwork/mail/smtp.cppnetwork/networkprotocol/nntp.cpp

void QSocket::connectionClosed () [信号]

当另一端已经关闭这个连接时,这个信号被发射。在连接被关闭之后,读缓存中也许还包含被可读的缓存的输入数据。

也可以参考connectToHost()和close()。

实例:network/clientserver/client/client.cppnetwork/networkprotocol/nntp.cpp

void QSocket::delayedCloseFinished () [信号]

当一个延时的关闭被完成时,这个信号被发射。

如果你调用close()并且输出缓存中还有数据要写,QSocket进入QSocket::Closing状态并且立即返回。然后它将会继续要套接字写知道所有的数据被写完。然后,delayedCloseFinished()信号被发射。

也可以参考close()。

实例:network/clientserver/client/client.cppnetwork/httpd/httpd.cpp

void QSocket::error ( int ) [信号]

在错误发生之后,信号被发射。参数就是Error的值。

实例:network/clientserver/client/client.cppnetwork/networkprotocol/nntp.cpp

void QSocket::flush () [虚]

纯虚函数QIODevice::flush()的实现。

QIODevice中重新实现的。

int QSocket::getch () [虚]

从内部的读缓存中读取单一的字节/字符。返回读取的字节/字符,或者如果没有什么可以读取的,返回-1。

也可以参考bytesAvailable()和putch()。

QIODevice中重新实现的。

void QSocket::hostFound () [信号]

connectToHost()已经被调用并且主机查找已经成功之后,这个信号被发射。

也可以参考connected()。

实例:network/networkprotocol/nntp.cpp

bool QSocket::open ( int m ) [虚]

使用指定的QIODevice文件模式m打开套接字。当被需要的时候会被自动调用并且你不应该自己调用它。

也可以参考close()。

QIODevice中重新实现的。

QHostAddress QSocket::peerAddress () const

返回为connectToHost()函数指定名称的主机地址。

QString QSocket::peerName () const

返回为connectToHost()函数指定主机名称。如果没有被设置,返回一个空字符串。

实例:network/mail/smtp.cpp

Q_UINT16 QSocket::peerPort () const

返回本地的主机端口号,通常是为connectToHost()函数指定的。如果没有被设置,返回0。

注意Qt总是使用本地字节顺序,也就是在Qt中67就是67,不需要调用htons()。

Q_UINT16 QSocket::port () const

返回这个套接字的主机端口号,使用本地字节顺序。

int QSocket::putch ( int ch ) [虚]

写字符ch到输出缓存。

返回ch,或者如果发生错误,返回-1。

也可以参考getch()。

QIODevice中重新实现的。

Q_LONG QSocket::readBlock ( char * data, Q_ULONG maxlen ) [虚]

从套接字中读取最多maxlen字节到data中并且返回读取的字节数。如果发生错误,返回-1。

实例:network/networkprotocol/nntp.cpp

QIODevice中重新实现的。

QString QSocket::readLine () [虚]

返回包含终止新行符(\n)的一行文本。如果canReadLine()返回假,返回“”。

也可以参考canReadLine()。

实例:network/clientserver/client/client.cppnetwork/httpd/httpd.cppnetwork/mail/smtp.cppnetwork/networkprotocol/nntp.cpp

void QSocket::readyRead () [信号]

当有进入的数据可以被读取时,这个信号被发射。

每一次有新进入的数据时,这个信号都被发射一次。记住新进入的数据只被报告一次,也就是,如果你没有读取全部数据,这个信号不会被再次发射,除非新的数据到达这个套接字。

也可以参考readBlock()、readLine()和bytesAvailable()。

实例:network/clientserver/client/client.cppnetwork/httpd/httpd.cppnetwork/mail/smtp.cppnetwork/networkpotocol/nntp.cpp

void QSocket::setSocket ( int socket ) [虚]

设置套接字使用socket并且state()为Connected。这个套接字应该已经被连接。

这允许我们使用QSocket类作为一个其它套接字类型(也就是在Unix下的Unix领域套接字)的包装。

实例:network/httpd/httpd.cpp

void QSocket::setSocketDevice ( QSocketDevice * device ) [虚]

设置内部套接字设备为device。传递一个0的device将导致这个内部套接字设备被使用。在使用新的device之前,任何已经存在的连接将被取消连接。

新的设备在被关联到一个QSocket之前应该没有被连接,在设置套接字调用connectToHost()之后进行连接。

如果你继承QSocketDevice并且想使用QSocket应用编程接口,例如,实现Unix领域套接字,这个函数很有用。

Offset QSocket::size () const [虚]

立即返回可以读取的进入数据的字节数(就像bytesAvailable()一样)。

QIODevice中重新实现的。

void QSocket::sn_read ( bool force = FALSE ) [虚 保护 槽]

处理套接字读通知的内部槽。

这个函数通常只能被进入一次(也就是,不是递归调用)。如果参数force为真,这个函数被执行,但是没有readyRead()信号被发射。这种方式对于waitForMore()函数很有用,所以在一个连接到readyRead()信号的槽中调用waitForMore()是可能的。

void QSocket::sn_write () [虚 保护 槽]

处理套接字写通知的内部操。

int QSocket::socket () const

返回套接字数,或者如果这个时候没有套接字,返回-1。

QSocketDevice * QSocket::socketDevice ()

返回内部套接字设备的指针。

通常不需要直接操作这个套接字设备,因为这个类对于绝大多数应用程序不需要设置。

State QSocket::state () const

返回这个套接字连接的当前状态。

也可以参考QSocket::State

实例:network/clientserver/client/client.cppnetwork/networkprotocol/nntp.cpp

int QSocket::ungetch ( int ch ) [虚]

虚函数QIODevice::ungetch()的实现预先考虑写缓存中的字符ch,这样下一次读取把这个字符作为输出的第一个字符。

QIODevice中重新实现的。

Q_ULONG QSocket::waitForMore ( int msecs ) const

为了得到更多的可用数据,等待msecs毫秒。

如果msecs为-1,这个调用将会不确定地阻塞。

这个一个阻塞调用并且应该在事件驱动的应用程序中避免使用。

返回可以使用的字节数。

也可以参考bytesAvailable()。

Q_LONG QSocket::writeBlock ( const char * data, Q_ULONG len ) [虚]

data中向套接字中写入len字节并且返回所写的字节数。如果发生错误,返回-1。

实例:network/networkprotocol/nntp.cpp

QIODevice中重新实现的。


这个文件是Qt工具包一部分。 版权所有 © 1995-2002 Trolltech。保留所有权利。


Copyright © 2002 Trolltech Trademarks 译者:Cavendish
Qt 3.0.5版