QSocket类

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

#include <qsocket.h>

继承了QObject和QIODevice。

所有成员函数的列表。

公有成员

• enum Error { ErrConnectionRefused, ErrHostNotFound, ErrSocketRead }
• QSocket ( QObject * parent = 0, const char * name = 0 )
• virtual ~QSocket ()
• enum State { Idle, HostLookup, Connecting, Connected, Closing, Connection = Connected }
• State state () const
• int socket () const
• virtual void setSocket ( int socket )
• QSocketDevice * socketDevice ()
• virtual void setSocketDevice ( QSocketDevice * device )
• virtual void connectToHost ( const QString & host, Q_UINT16 port )
• QString peerName () const
• virtual bool open ( int m )
• virtual void close ()
• virtual void flush ()
• virtual Offset size () const
• virtual Offset at () const
• virtual bool at ( Offset index )
• virtual bool atEnd () const
• Q_ULONG bytesAvailable () const
• Q_ULONG waitForMore ( int msecs ) const
• Q_ULONG bytesToWrite () const
• virtual Q_LONG readBlock ( char * data, Q_ULONG maxlen )
• virtual Q_LONG writeBlock ( const char * data, Q_ULONG len )
• virtual int getch ()
• virtual int putch ( int ch )
• virtual int ungetch ( int ch )
• bool canReadLine () const
• virtual QString readLine ()
• Q_UINT16 port () const
• Q_UINT16 peerPort () const
• QHostAddress address () const
• QHostAddress peerAddress () const

信号

• void hostFound ()
• void connected ()
• void connectionClosed ()
• void delayedCloseFinished ()
• void readyRead ()
• void bytesWritten ( int nbytes )
• void error ( int )

保护槽

• virtual void sn_read ( bool force = FALSE )
• virtual void sn_write ()

---

详细描述

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()的文档详细地描述了不同点。

也可以参考QSocketDevice、QHostAddress、QSocketNotifier和输入/输出和网络。

---

成员类型文档

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对象。

parent和name参数被传递给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.cpp、network/httpd/httpd.cpp、network/mail/smtp.cpp和network/networkprotocol/nntp.cpp。

void QSocket::close () [虚]

关闭这个套接字。

读缓存被清空。

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

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

实例：network/clientserver/client/client.cpp、network/httpd/httpd.cpp和network/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.cpp、network/mail/smtp.cpp和network/networkprotocol/nntp.cpp。

void QSocket::connected () [信号]

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

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

实例：network/clientserver/client/client.cpp、network/mail/smtp.cpp和network/networkprotocol/nntp.cpp。

void QSocket::connectionClosed () [信号]

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

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

实例：network/clientserver/client/client.cpp和network/networkprotocol/nntp.cpp。

void QSocket::delayedCloseFinished () [信号]

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

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

也可以参考close()。

实例：network/clientserver/client/client.cpp和network/httpd/httpd.cpp。

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

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

实例：network/clientserver/client/client.cpp和network/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.cpp、network/httpd/httpd.cpp、network/mail/smtp.cpp和network/networkprotocol/nntp.cpp。

void QSocket::readyRead () [信号]

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

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

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

实例：network/clientserver/client/client.cpp、network/httpd/httpd.cpp、network/mail/smtp.cpp和network/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.cpp和network/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中重新实现的。

转自：http://www.kuqin.com/qtdocument/qsocket.html