QSocket类
QSocket类提供了一个有缓冲的TCP连接。 详情请见……
#include <qsocket.h>
公有成员
-
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 )
保护槽
详细描述
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()函数指定主机名称。如果没有被设置,返回一个空字符串。
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领域套接字)的包装。
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