From d796c9dd933ab96ec83b9a634feedd5d32e1ba3f Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Tue, 8 Nov 2011 12:31:36 -0600 Subject: Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731 --- doc/html/qsocketdevice.html | 419 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 419 insertions(+) create mode 100644 doc/html/qsocketdevice.html (limited to 'doc/html/qsocketdevice.html') diff --git a/doc/html/qsocketdevice.html b/doc/html/qsocketdevice.html new file mode 100644 index 000000000..3b8350404 --- /dev/null +++ b/doc/html/qsocketdevice.html @@ -0,0 +1,419 @@ + + + + + +TQSocketDevice Class + + + + + + + +

TQSocketDevice Class Reference
[network module]

+ +

The TQSocketDevice class provides a platform-independent low-level socket API. +More... +

#include <qsocketdevice.h> +

Inherits TQIODevice. +

List of all member functions. +

Public Members

enum Type { Stream, Datagram }
enum Protocol { IPv4, IPv6, Unknown }
TQSocketDevice ( Type type = Stream )
TQSocketDevice ( Type type, Protocol protocol, int dummy )
TQSocketDevice ( int socket, Type type )
virtual ~TQSocketDevice ()
bool isValid () const
Type type () const
Protocol protocol () const
int socket () const
virtual void setSocket ( int socket, Type type )
bool blocking () const
virtual void setBlocking ( bool enable )
bool addressReusable () const
virtual void setAddressReusable ( bool enable )
int receiveBufferSize () const
virtual void setReceiveBufferSize ( uint size )
int sendBufferSize () const
virtual void setSendBufferSize ( uint size )
virtual bool connect ( const TQHostAddress & addr, Q_UINT16 port )
virtual bool bind ( const TQHostAddress & address, Q_UINT16 port )
virtual bool listen ( int backlog )
virtual int accept ()
Q_LONG bytesAvailable () const
Q_LONG waitForMore ( int msecs, bool * timeout = 0 ) const
virtual Q_LONG readBlock ( char * data, Q_ULONG maxlen )
virtual Q_LONG writeBlock ( const char * data, Q_ULONG len )
virtual Q_LONG writeBlock ( const char * data, Q_ULONG len, const TQHostAddress & host, Q_UINT16 port )
Q_UINT16 port () const
Q_UINT16 peerPort () const
TQHostAddress address () const
TQHostAddress peerAddress () const
enum Error { NoError, AlreadyBound, Inaccessible, NoResources, InternalError, Bug = InternalError, Impossible, NoFiles, ConnectionRefused, NetworkFailure, UnknownError }
Error error () const

Protected Members

void setError ( Error err )

Detailed Description

+ + +The TQSocketDevice class provides a platform-independent low-level socket API. + +

+ +

This class provides a low level API for working with sockets. Users of +this class are assumed to have networking experience. For most users the +TQSocket class provides a much easier and high level alternative, but +certain things (like UDP) can't be done with TQSocket and if you need a +platform-independent API for those, TQSocketDevice is the right choice. +

The essential purpose of the class is to provide a TQIODevice that +works on sockets, wrapped in a platform-independent API. +

When calling connect() or bind(), TQSocketDevice detects the +protocol family (IPv4, IPv6) automatically. Passing the protocol +family to TQSocketDevice's constructor or to setSocket() forces +creation of a socket device of a specific protocol. If not set, the +protocol will be detected at the first call to connect() or bind(). +

Member Type Documentation

TQSocketDevice::Error

+ +

This enum type describes the error states of TQSocketDevice. +

TQSocketDevice::NoError - No error has occurred. +
TQSocketDevice::AlreadyBound - The device is already bound, according to bind(). +
TQSocketDevice::Inaccessible - The operating system or firewall prohibited +the action. +
TQSocketDevice::NoResources - The operating system ran out of a resource. +
TQSocketDevice::InternalError - An internal error occurred in TQSocketDevice. +
TQSocketDevice::Impossible - An attempt was made to do something which makes +no sense. For example: +
```
+    ::close( sd->socket() );
+    sd->writeBlock( someData, 42 );
+    
```
+ +The libc ::close() closes the socket, but TQSocketDevice is not aware +of this. So when you call writeBlock(), the impossible happens. +
TQSocketDevice::NoFiles - The operating system will not let TQSocketDevice open +another file. +
TQSocketDevice::ConnectionRefused - A connection attempt was rejected by the +peer. +
TQSocketDevice::NetworkFailure - There is a network failure. +
TQSocketDevice::UnknownError - The operating system did something +unexpected. +

TQSocketDevice::Protocol

+ +

This enum type describes the protocol family of the socket. Possible values +are: +

TQSocketDevice::IPv4 - The socket is an IPv4 socket. +
TQSocketDevice::IPv6 - The socket is an IPv6 socket. +
TQSocketDevice::Unknown - The protocol family of the socket is not known. This can +happen if you use TQSocketDevice with an already existing socket; it +tries to determine the protocol family, but this can fail if the +protocol family is not known to TQSocketDevice. +

See also protocol() and setSocket(). + +

TQSocketDevice::Type

+ +

This enum type describes the type of the socket: +

TQSocketDevice::Stream - a stream socket (TCP, usually) +
TQSocketDevice::Datagram - a datagram socket (UDP, usually) +

Member Function Documentation

TQSocketDevice::TQSocketDevice ( Type type = Stream ) +

+Creates a TQSocketDevice object for a stream or datagram socket. +

The type argument must be either TQSocketDevice::Stream for a +reliable, connection-oriented TCP socket, or TQSocketDevice::Datagram for an unreliable UDP socket. +

The socket is created as an IPv4 socket. +

TQSocketDevice::TQSocketDevice ( Type type, Protocol protocol, int dummy ) +

+Creates a TQSocketDevice object for a stream or datagram socket. +

The type argument must be either TQSocketDevice::Stream for a +reliable, connection-oriented TCP socket, or TQSocketDevice::Datagram for an unreliable UDP socket. +

The protocol indicates whether the socket should be of type IPv4 +or IPv6. Passing Unknown is not meaningful in this context and you +should avoid using (it creates an IPv4 socket, but your code is not easily +readable). +

The argument dummy is necessary for compatibility with some +compilers. +

TQSocketDevice::TQSocketDevice ( int socket, Type type ) +

+Creates a TQSocketDevice object for the existing socket socket. +

The type argument must match the actual socket type; use TQSocketDevice::Stream for a reliable, connection-oriented TCP +socket, or TQSocketDevice::Datagram for an unreliable, +connectionless UDP socket. + +

TQSocketDevice::~TQSocketDevice () `[virtual]` +

+Destroys the socket device and closes the socket if it is open. + +

int TQSocketDevice::accept () `[virtual]` +

+Extracts the first connection from the queue of pending +connections for this socket and returns a new socket identifier. +Returns -1 if the operation failed. +

TQHostAddress TQSocketDevice::address () const +

+Returns the address of this socket device. This may be 0.0.0.0 for +a while, but is set to something sensible as soon as a sensible +value is available. + +

bool TQSocketDevice::addressReusable () const +

+Returns TRUE if the address of this socket can be used by other +sockets at the same time, and FALSE if this socket claims +exclusive ownership. +

bool TQSocketDevice::bind ( const TQHostAddress & address, Q_UINT16 port ) `[virtual]` +

+Assigns a name to an unnamed socket. The name is the host address +address and the port number port. If the operation succeeds, +bind() returns TRUE; otherwise it returns FALSE without changing +what port() and address() return. +

bind() is used by servers for setting up incoming connections. +Call bind() before listen(). + +

bool TQSocketDevice::blocking () const +

+Returns TRUE if the socket is valid and in blocking mode; +otherwise returns FALSE. +

Note that this function does not set error(). +

Warning: On Windows, this function always returns TRUE since the +ioctlsocket() function is broken. +

See also setBlocking() and isValid(). + +

Q_LONG TQSocketDevice::bytesAvailable () const +

+Returns the number of bytes available for reading, or -1 if an +error occurred. +

Warning: On Microsoft Windows, we use the ioctlsocket() function +to determine the number of bytes queued on the socket. According +to Microsoft (KB Q125486), ioctlsocket() sometimes returns an +incorrect number. The only safe way to determine the amount of +data on the socket is to read it using readBlock(). TQSocket has +workarounds to deal with this problem. + +

bool TQSocketDevice::connect ( const TQHostAddress & addr, Q_UINT16 port ) `[virtual]` +

+Connects to the IP address and port specified by addr and port. Returns TRUE if it establishes a connection; otherwise returns FALSE. +If it returns FALSE, error() explains why. +

Note that error() commonly returns NoError for non-blocking +sockets; this just means that you can call connect() again in a +little while and it'll probably succeed. + +

Error TQSocketDevice::error () const +

+Returns the first error seen. + +

bool TQSocketDevice::isValid () const +

+Returns TRUE if this is a valid socket; otherwise returns FALSE. +

bool TQSocketDevice::listen ( int backlog ) `[virtual]` +

+Specifies how many pending connections a server socket can have. +Returns TRUE if the operation was successful; otherwise returns +FALSE. A backlog value of 50 is tquite common. +

The listen() call only applies to sockets where type() is Stream, i.e. not to Datagram sockets. listen() must not be +called before bind() or after accept(). +

TQHostAddress TQSocketDevice::peerAddress () const +

+Returns the address of the port this socket device is connected +to. This may be 0.0.0.0 for a while, but is set to something +sensible as soon as a sensible value is available. +

Note that for Datagram sockets, this is the source port of the +last packet received. + +

Q_UINT16 TQSocketDevice::peerPort () const +

+Returns the port number of the port this socket device is +connected to. This may be 0 for a while, but is set to something +sensible as soon as a sensible value is available. +

Note that for Datagram sockets, this is the source port of the +last packet received, and that it is in native byte order. + +

Q_UINT16 TQSocketDevice::port () const +

+Returns the port number of this socket device. This may be 0 for a +while, but is set to something sensible as soon as a sensible +value is available. +

Note that TQt always uses native byte order, i.e. 67 is 67 in TQt; +there is no need to call htons(). + +

Protocol TQSocketDevice::protocol () const +

+Returns the socket's protocol family, which is one of Unknown, IPv4, +or IPv6. +

TQSocketDevice either creates a socket with a well known protocol family or +it uses an already existing socket. In the first case, this function +returns the protocol family it was constructed with. In the second case, it +tries to determine the protocol family of the socket; if this fails, it +returns Unknown. +

Q_LONG TQSocketDevice::readBlock ( char * data, Q_ULONG maxlen ) `[virtual]` +

+Reads maxlen bytes from the socket into data and returns the +number of bytes read. Returns -1 if an error occurred. Returning 0 +is not an error. For Stream sockets, 0 is returned when the remote +host closes the connection. For Datagram sockets, 0 is a valid +datagram size. + +

Reimplemented from TQIODevice. +

int TQSocketDevice::receiveBufferSize () const +

+Returns the size of the operating system receive buffer. +

int TQSocketDevice::sendBufferSize () const +

+Returns the size of the operating system send buffer. +

void TQSocketDevice::setAddressReusable ( bool enable ) `[virtual]` +

+Sets the address of this socket to be usable by other sockets too +if enable is TRUE, and to be used exclusively by this socket if +enable is FALSE. +

When a socket is reusable, other sockets can use the same port +number (and IP address), which is generally useful. Of course +other sockets cannot use the same +(address,port,peer-address,peer-port) 4-tuple as this socket, so +there is no risk of confusing the two TCP connections. +

void TQSocketDevice::setBlocking ( bool enable ) `[virtual]` +

+Makes the socket blocking if enable is TRUE or nonblocking if +enable is FALSE. +

Sockets are blocking by default, but we recommend using +nonblocking socket operations, especially for GUI programs that +need to be responsive. +

Warning: On Windows, this function should be used with care since +whenever you use a TQSocketNotifier on Windows, the socket is +immediately made nonblocking. +

void TQSocketDevice::setError ( Error err ) `[protected]` +

+Allows subclasses to set the error state to err. + +

void TQSocketDevice::setReceiveBufferSize ( uint size ) `[virtual]` +

+Sets the size of the operating system receive buffer to size. +

The operating system receive buffer size effectively limits two +things: how much data can be in transit at any one moment, and how +much data can be received in one iteration of the main event loop. +

The default is operating system-dependent. A socket that receives +large amounts of data is probably best with a buffer size of +49152. + +

void TQSocketDevice::setSendBufferSize ( uint size ) `[virtual]` +

+Sets the size of the operating system send buffer to size. +

The operating system send buffer size effectively limits how much +data can be in transit at any one moment. +

The default is operating system-dependent. A socket that sends +large amounts of data is probably best with a buffer size of +49152. + +

void TQSocketDevice::setSocket ( int socket, Type type ) `[virtual]` +

+Sets the socket device to operate on the existing socket socket. +

Any existing socket is closed. +

int TQSocketDevice::socket () const +

+Returns the socket number, or -1 if it is an invalid socket. +

Type TQSocketDevice::type () const +

+ +

Returns the socket type which is either TQSocketDevice::Stream +or TQSocketDevice::Datagram. +

Q_LONG TQSocketDevice::waitForMore ( int msecs, bool * timeout = 0 ) const +

+Wait up to msecs milliseconds for more data to be available. If +msecs is -1 the call will block indefinitely. +

Returns the number of bytes available for reading, or -1 if an +error occurred. +

If timeout is non-null and no error occurred (i.e. it does not +return -1): this function sets *timeout to TRUE, if the reason +for returning was that the timeout was reached; otherwise it sets +*timeout to FALSE. This is useful to find out if the peer +closed the connection. +

Warning: This is a blocking call and should be avoided in event +driven applications. +

Q_LONG TQSocketDevice::writeBlock ( const char * data, Q_ULONG len ) `[virtual]` +

+Writes len bytes to the socket from data and returns the +number of bytes written. Returns -1 if an error occurred. +

This is used for TQSocketDevice::Stream sockets. + +

Reimplemented from TQIODevice. +

Q_LONG TQSocketDevice::writeBlock ( const char * data, Q_ULONG len, const TQHostAddress & host, Q_UINT16 port ) `[virtual]` +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Writes len bytes to the socket from data and returns the +number of bytes written. Returns -1 if an error occurred. +

This is used for TQSocketDevice::Datagram sockets. You must +specify the host and port of the destination of the data. + + +

+ +

Trademarks +

TQt 3.3.8

+ -- cgit v1.2.1

TQSocketDevice Class Reference[network module]