QUnixSocket Class Reference

The QUnixSocket class provides a Unix domain socket. More...

#include <qunixsocket_p.h>

Inheritance diagram for QUnixSocket:

Public Types
enum	SocketError {   NoError, InvalidPath, ResourceError, NonexistentPath,   ConnectionRefused, UnknownError, ReadFailure, WriteFailure }
	The SocketError enumeration represents the various errors that can occur on a Unix domain socket. More...
enum	SocketState {   UnconnectedState = QAbstractSocket::UnconnectedState, HostLookupState = QAbstractSocket::HostLookupState, ConnectingState = QAbstractSocket::ConnectingState, ConnectedState = QAbstractSocket::ConnectedState,   BoundState = QAbstractSocket::BoundState, ClosingState = QAbstractSocket::ClosingState, ListeningState = QAbstractSocket::ListeningState }
	The SocketState enumeration represents the connection state of a QUnixSocket instance. More...
Public Types inherited from QIODevice
enum	OpenModeFlag {   NotOpen = 0x0000, ReadOnly = 0x0001, WriteOnly = 0x0002, ReadWrite = ReadOnly | WriteOnly,   Append = 0x0004, Truncate = 0x0008, Text = 0x0010, Unbuffered = 0x0020 }
	This enum is used with open() to describe the mode in which a device is opened. More...

Signals
void	stateChanged (SocketState socketState)
	This signal is emitted each time the socket changes connection state. More...
Signals inherited from QIODevice
void	aboutToClose ()
	This signal is emitted when the device is about to close. More...
void	bytesWritten (qint64 bytes)
	This signal is emitted every time a payload of data has been written to the device. More...
void	readChannelFinished ()
	This signal is emitted when the input (reading) stream is closed in this device. More...
void	readyRead ()
	This signal is emitted once every time new data is available for reading from the device. More...
Signals inherited from QObject
void	destroyed (QObject *=0)
	This signal is emitted immediately before the object obj is destroyed, and can not be blocked. More...

Public Functions
void	abort ()
	Abort the connection. More...
QByteArray	address () const
	Returns the Unix path address passed to QUnixSocket::connect() . More...
qint64	bytesAvailable () const
	Returns the number of bytes available for immediate retrieval through a call to QUnixSocket::read() . More...
qint64	bytesToWrite () const
	Returns the number of enqueued bytes still to be written to the socket. More...
bool	canReadLine () const
void	close ()
	Close the connection. More...
bool	connect (const QByteArray &path)
	Attempt to connect to path. More...
SocketError	error () const
	Returns the last error to have occurred on this object. More...
bool	flush ()
	This function writes as much as possible from the internal write buffer to the underlying socket, without blocking. More...
virtual bool	isSequential () const
	QUnixSocket (QObject *=0)
	Construct a QUnixSocket instance, with parent. More...
	QUnixSocket (qint64, qint64, QObject *=0)
	Construct a QUnixSocket instance, with parent. More...
qint64	read (char *data, qint64 maxSize)
QByteArray	read (qint64 maxSize)
QUnixSocketMessage	read ()
	Return the next available message, or an empty message if none is available. More...
qint64	readBufferSize () const
	Returns the size of the read buffer in bytes. More...
qint64	rightsBufferSize () const
	Returns the size of the rights buffer in rights entries. More...
void	setReadBufferSize (qint64 size)
	Sets the size of the socket's read buffer in bytes. More...
void	setRightsBufferSize (qint64 size)
	Sets the size of the socket's rights buffer in rights entries. More...
bool	setSocketDescriptor (int socketDescriptor)
	Sets the socket descriptor to use to socketDescriptor, bypassing QUnixSocket's connection infrastructure, and return true on success and false on failure. More...
int	socketDescriptor () const
	Returns the socket descriptor currently in use. More...
SocketState	state () const
	Returns the connection state of this instance. More...
virtual bool	waitForBytesWritten (int msec=300)
	For buffered devices, this function waits until a payload of buffered written data has been written to the device and the bytesWritten() signal has been emitted, or until msecs milliseconds have passed. More...
virtual bool	waitForReadyRead (int msec=300)
qint64	write (const char *data, qint64 maxSize)
qint64	write (const QByteArray &byteArray)
qint64	write (const QUnixSocketMessage &)
	Writes socketdata to the socket. More...
virtual	~QUnixSocket ()
	Destroys the QUnixSocket instance. More...
Public Functions inherited from QIODevice
virtual bool	atEnd () const
	Returns true if the current read and write position is at the end of the device (i.e. More...
QString	errorString () const
	Returns a human-readable description of the last device error that occurred. More...
bool	getChar (char *c)
	Reads one character from the device and stores it in c. More...
bool	isOpen () const
	Returns true if the device is open; otherwise returns false. More...
bool	isReadable () const
	Returns true if data can be read from the device; otherwise returns false. More...
bool	isTextModeEnabled () const
	Returns true if the Text flag is enabled; otherwise returns false. More...
bool	isWritable () const
	Returns true if data can be written to the device; otherwise returns false. More...
virtual bool	open (OpenMode mode)
	Opens the device and sets its OpenMode to mode. More...
OpenMode	openMode () const
	Returns the mode in which the device has been opened; i.e. More...
qint64	peek (char *data, qint64 maxlen)
	Reads at most maxSize bytes from the device into data, without side effects (i. More...
QByteArray	peek (qint64 maxlen)
	Peeks at most maxSize bytes from the device, returning the data peeked as a QByteArray. More...
virtual qint64	pos () const
	For random-access devices, this function returns the position that data is written to or read from. More...
bool	putChar (char c)
	Writes the character c to the device. More...
	QIODevice ()
	Constructs a QIODevice object. More...
	QIODevice (QObject *parent)
	Constructs a QIODevice object with the given parent. More...
qint64	read (char *data, qint64 maxlen)
	Reads at most maxSize bytes from the device into data, and returns the number of bytes read. More...
QByteArray	read (qint64 maxlen)
	Reads at most maxSize bytes from the device, and returns the data read as a QByteArray. More...
QByteArray	readAll ()
	Reads all available data from the device, and returns it as a QByteArray. More...
qint64	readLine (char *data, qint64 maxlen)
	This function reads a line of ASCII characters from the device, up to a maximum of maxSize - 1 bytes, stores the characters in data, and returns the number of bytes read. More...
QByteArray	readLine (qint64 maxlen=0)
	Reads a line from the device, but no more than maxSize characters, and returns the result as a QByteArray. More...
virtual bool	reset ()
	Seeks to the start of input for random-access devices. More...
virtual bool	seek (qint64 pos)
	For random-access devices, this function sets the current position to pos, returning true on success, or false if an error occurred. More...
void	setTextModeEnabled (bool enabled)
	If enabled is true, this function sets the Text flag on the device; otherwise the Text flag is removed. More...
virtual qint64	size () const
	For open random-access devices, this function returns the size of the device. More...
void	ungetChar (char c)
	Puts the character c back into the device, and decrements the current position unless the position is 0. More...
qint64	write (const char *data, qint64 len)
	Writes at most maxSize bytes of data from data to the device. More...
qint64	write (const char *data)
	Writes data from a zero-terminated string of 8-bit characters to the device. More...
qint64	write (const QByteArray &data)
	Writes the content of byteArray to the device. More...
virtual	~QIODevice ()
	The destructor is virtual, and QIODevice is an abstract base class. More...
Public Functions inherited from QObject
bool	blockSignals (bool b)
	If block is true, signals emitted by this object are blocked (i.e., emitting a signal will not invoke anything connected to it). More...
const QObjectList &	children () const
	Returns a list of child objects. More...
bool	connect (const QObject *sender, const char *signal, const char *member, Qt::ConnectionType type=Qt::AutoConnection) const
bool	disconnect (const char *signal=0, const QObject *receiver=0, const char *member=0)
bool	disconnect (const QObject *receiver, const char *member=0)
void	dumpObjectInfo ()
	Dumps information about signal connections, etc. More...
void	dumpObjectTree ()
	Dumps a tree of children to the debug output. More...
QList< QByteArray >	dynamicPropertyNames () const
	Returns the names of all properties that were dynamically added to the object using setProperty(). More...
virtual bool	event (QEvent *)
	This virtual function receives events to an object and should return true if the event e was recognized and processed. More...
virtual bool	eventFilter (QObject *, QEvent *)
	Filters events if this object has been installed as an event filter for the watched object. More...
template<typename T >
T	findChild (const QString &aName=QString()) const
	Returns the child of this object that can be cast into type T and that is called name, or 0 if there is no such object. More...
template<typename T >
QList< T >	findChildren (const QString &aName=QString()) const
	Returns all children of this object with the given name that can be cast to type T, or an empty list if there are no such objects. More...
template<typename T >
QList< T >	findChildren (const QRegExp &re) const
bool	inherits (const char *classname) const
	Returns true if this object is an instance of a class that inherits className or a QObject subclass that inherits className; otherwise returns false. More...
void	installEventFilter (QObject *)
	Installs an event filter filterObj on this object. More...
bool	isWidgetType () const
	Returns true if the object is a widget; otherwise returns false. More...
void	killTimer (int id)
	Kills the timer with timer identifier, id. More...
virtual const QMetaObject *	metaObject () const
	Returns a pointer to the meta-object of this object. More...
void	moveToThread (QThread *thread)
	Changes the thread affinity for this object and its children. More...
QString	objectName () const
QObject *	parent () const
	Returns a pointer to the parent object. More...
QVariant	property (const char *name) const
	Returns the value of the object's name property. More...
Q_INVOKABLE	QObject (QObject *parent=0)
	Constructs an object with parent object parent. More...
void	removeEventFilter (QObject *)
	Removes an event filter object obj from this object. More...
void	setObjectName (const QString &name)
void	setParent (QObject *)
	Makes the object a child of parent. More...
bool	setProperty (const char *name, const QVariant &value)
	Sets the value of the object's name property to value. More...
void	setUserData (uint id, QObjectUserData *data)
bool	signalsBlocked () const
	Returns true if signals are blocked; otherwise returns false. More...
int	startTimer (int interval)
	Starts a timer and returns a timer identifier, or returns zero if it could not start a timer. More...
QThread *	thread () const
	Returns the thread in which the object lives. More...
QObjectUserData *	userData (uint id) const
virtual	~QObject ()
	Destroys the object, deleting all its child objects. More...

Protected Functions
virtual qint64	readData (char *data, qint64 maxSize)
virtual qint64	writeData (const char *data, qint64 maxSize)
Protected Functions inherited from QIODevice
	QIODevice (QIODevicePrivate &dd, QObject *parent=0)
virtual qint64	readLineData (char *data, qint64 maxlen)
	Reads up to maxSize characters into data and returns the number of characters read. More...
void	setErrorString (const QString &errorString)
	Sets the human readable description of the last device error that occurred to str. More...
void	setOpenMode (OpenMode openMode)
	Sets the OpenMode of the device to openMode. More...
Protected Functions inherited from QObject
virtual void	childEvent (QChildEvent *)
	This event handler can be reimplemented in a subclass to receive child events. More...
virtual void	connectNotify (const char *signal)
	This virtual function is called when something has been connected to signal in this object. More...
virtual void	customEvent (QEvent *)
	This event handler can be reimplemented in a subclass to receive custom events. More...
virtual void	disconnectNotify (const char *signal)
	This virtual function is called when something has been disconnected from signal in this object. More...
	QObject (QObjectPrivate &dd, QObject *parent=0)
int	receivers (const char *signal) const
	Returns the number of receivers connected to the signal. More...
QObject *	sender () const
	Returns a pointer to the object that sent the signal, if called in a slot activated by a signal; otherwise it returns 0. More...
int	senderSignalIndex () const
virtual void	timerEvent (QTimerEvent *)
	This event handler can be reimplemented in a subclass to receive timer events for the object. More...

Private Functions
QUnixSocket &	operator= (const QUnixSocket &)
	QUnixSocket (const QUnixSocket &)

Properties
QUnixSocketPrivate *	d

Additional Inherited Members
Public Slots inherited from QObject
void	deleteLater ()
	Schedules this object for deletion. More...
Static Public Functions inherited from QObject
static bool	connect (const QObject *sender, const char *signal, const QObject *receiver, const char *member, Qt::ConnectionType=Qt::AutoConnection)
	Creates a connection of the given type from the signal in the sender object to the method in the receiver object. More...
static bool	connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type=Qt::AutoConnection)
static bool	disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *member)
	Disconnects signal in object sender from method in object receiver. More...
static bool	disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &member)
static uint	registerUserData ()
static QString	tr (const char *sourceText, const char *comment=0, int n=-1)
static QString	trUtf8 (const char *sourceText, const char *comment=0, int n=-1)
Static Public Variables inherited from QObject
static const QMetaObject	staticMetaObject
	This variable stores the meta-object for the class. More...
Protected Variables inherited from QObject
QScopedPointer< QObjectData >	d_ptr
Static Protected Variables inherited from QObject
static const QMetaObject	staticQtMetaObject
Related Functions inherited from QObject
T	qFindChildqFindChildren (const QObject *obj, const QString &name)()
QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QString &name)()
QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QRegExp &regExp)()
T *	qobject_cast (QObject *object)
	QObjectList
void *	qt_find_obj_child (QObject *parent, const char *type, const QString &name)
	Returns a pointer to the object named name that inherits type and with a given parent. More...

Detailed Description

The QUnixSocket class provides a Unix domain socket.

Warning

This function is not part of the public interface.

This function is not part of the public interface. :: :: ::

Unix domain sockets provide an efficient mechanism for communications between Unix processes on the same machine. Unix domain sockets support a reliable, stream-oriented, connection-oriented transport protocol, much like TCP sockets. Unlike IP based sockets, the connection endpoint of a Unix domain socket is a file on disk of type socket.

In addition to transporting raw data bytes, Unix domain sockets are able to transmit special ancillary data. The two types of ancillary data supported by the QUnixSocket class are:

• Credential Data - Allows a receiver to reliably identify the process sending each message.
• QUnixSocketRights{Rights Data } - Allows Unix file descriptors to be transmitted between processes.

Because of the need to support ancillary data, QUnixSocket is not a QIODevice, like QTcpSocket and QUdpSocket. Instead, QUnixSocket contains a number of read and write methods that clients must invoke directly. Rather than returning raw data bytes, QUnixSocket::read() returns QUnixSocketMessage instances that encapsulate the message's byte data and any other ancillary data.

Ancillary data is transmitted "out of band". Every QUnixSocketMessage received will have credential data associated with it that the client can access through calls to QUnixSocketMessage::processId() , QUnixSocketMessage::groupId() and QUnixSocketMessage::userId() . Likewise, message creators can set the credential data to send through calls to QUnixSocketMessage::setProcessId() , QUnixSocketMessage::setGroupId() and QUnixSocketMessage::setUserId() respectively. The authenticity of the credential values is verified by the system kernel and cannot be fabricated by unprivileged processes. Only processes running as the root user can specify credential data that does not match the sending process.

Unix file descriptors, known as "rights data", transmitted between processes appear as though they had been dup(2)'d between the two. As Unix domain sockets present a continuous stream of bytes to the receiver, the rights data - which is transmitted out of band - must be "slotted" in at some point. The rights data is logically associated with the first byte - called the anchor byte - of the QUnixSocketMessage to which they are attached. Received rights data will be available from the QUnixSocketMessage::rights() method for the QUnixSocketMessage instance that contains the anchor byte.

In addition to a QUnixSocket::write() that takes a QUnixSocketMessage instance - allowing a client to transmit both byte and rights data - a number of convenience overloads are provided for use when only transmitting simple byte data. Unix requires that at least one byte of raw data be transmitted in order to send rights data. A QUnixSocketMessage instance with rights data, but no byte data, cannot be transmitted.

Unix sockets present a stream interface, such that, for example, a single six byte transmission might be received as two three byte messages. Rights data, on the other hand, is conceptually transmitted as unfragmentable datagrams. If the receiving buffer is not large enough to contain all the transmitted rights information, the data is truncated and irretreivably lost. Users should use the QUnixSocket::setRightsBufferSize() method to control the buffer size used for this data, and develop protocols that avoid the problem. If the buffer size is too small and rights data is truncated, the QUnixSocketMessage::rightsWereTruncated() flag will be set.

See also

QUnixSocketMessage QUnixSocketRights

Definition at line 125 of file qunixsocket_p.h.

Enumerations

SocketError

enum QUnixSocket::SocketError

The SocketError enumeration represents the various errors that can occur on a Unix domain socket.

The most recent error for the socket is available through the QUnixSocket::error() method.

• NoError No error has occurred.
• InvalidPath An invalid path endpoint was passed to QUnixSocket::connect() . As defined by unix(7), invalid paths include an empty path, or what more than 107 characters long.
• ResourceError An error acquiring or manipulating the system's socket resources occurred. For example, if the process runs out of available socket descriptors, a ResourceError will occur.
• NonexistentPath The endpoing passed to QUnixSocket::connect() does not refer to a Unix domain socket entity on disk.
• ConnectionRefused The connection to the specified endpoint was refused. Generally this means that there is no server listening on that endpoint.
• UnknownError An unknown error has occurred.
• ReadFailure An error occurred while reading bytes from the connection.
• WriteFailure An error occurred while writing bytes into the connection.

Enumerator
NoError
InvalidPath
ResourceError
NonexistentPath
ConnectionRefused
UnknownError
ReadFailure
WriteFailure

Definition at line 143 of file qunixsocket_p.h.

                     { NoError, InvalidPath, ResourceError,
                       NonexistentPath, ConnectionRefused, UnknownError,
                       ReadFailure, WriteFailure };

SocketState

enum QUnixSocket::SocketState

The SocketState enumeration represents the connection state of a QUnixSocket instance.

• UnconnectedState The connection is not established.
• ConnectedState The connection is established.
• ClosingState The connection is being closed, following a call to QUnixSocket::close() . While closing, any pending data will be transmitted, but further writes by the application will be refused.

Enumerator
UnconnectedState
HostLookupState
ConnectingState
ConnectedState
BoundState
ClosingState
ListeningState

Definition at line 133 of file qunixsocket_p.h.

                     {
        UnconnectedState = QAbstractSocket::UnconnectedState,
        HostLookupState = QAbstractSocket::HostLookupState,
        ConnectingState = QAbstractSocket::ConnectingState,
        ConnectedState = QAbstractSocket::ConnectedState,
        BoundState = QAbstractSocket::BoundState,
        ClosingState = QAbstractSocket::ClosingState,
        ListeningState = QAbstractSocket::ListeningState,
    };

Constructors and Destructors

QUnixSocket() [1/3]

QUnixSocket::QUnixSocket

(

QObject *

parent = 0

)

Construct a QUnixSocket instance, with parent.

The read buffer is initially set to 1024 bytes, and the rights buffer to 0 entries.

See also

QUnixSocket::readBufferSize() QUnixSocket::rightsBufferSize()

Definition at line 898 of file qunixsocket.cpp.

: QIODevice(parent), d(new QUnixSocketPrivate(this))
{
    setOpenMode(QIODevice::NotOpen);
    setReadBufferSize(QUNIXSOCKET_DEFAULT_READBUFFER);
    setRightsBufferSize(QUNIXSOCKET_DEFAULT_ANCILLARYBUFFER);
}

QUnixSocket() [2/3]

QUnixSocket::QUnixSocket	(	qint64	readBufferSize,
		qint64	rightsBufferSize,
		QObject *	parent = 0
	)

Construct a QUnixSocket instance, with parent.

The read buffer is initially set to readBufferSize bytes, and the rights buffer to rightsBufferSize entries.

See also

QUnixSocket::readBufferSize() QUnixSocket::rightsBufferSize()

Definition at line 914 of file qunixsocket.cpp.

: QIODevice(parent), d(new QUnixSocketPrivate(this))
{
    Q_ASSERT(readBufferSize > 0 && rightsBufferSize >= 0);

    setOpenMode(QIODevice::NotOpen);
    setReadBufferSize(readBufferSize);
    setRightsBufferSize(rightsBufferSize);
}

~QUnixSocket()

QUnixSocket::~QUnixSocket ( )

virtual

Destroys the QUnixSocket instance.

Any unsent data is discarded.

Definition at line 928 of file qunixsocket.cpp.

{
    abort();
    delete d;
}

QUnixSocket() [3/3]

QUnixSocket::QUnixSocket ( const QUnixSocket &  )

private

Functions

abort()

void QUnixSocket::abort

(

)

Abort the connection.

This will immediately disconnect (if connected) and discard any pending data. Following a call to QUnixSocket::abort() the object will always be in the disconnected state.

See also

QUnixSocket::close()

Definition at line 1133 of file qunixsocket.cpp.

Referenced by connect(), setSocketDescriptor(), QUnixSocketPrivate::timerEvent(), waitForBytesWritten(), waitForReadyRead(), and ~QUnixSocket().

{
    setOpenMode(QIODevice::NotOpen);

    // We want to be able to use QUnixSocket::abort() to cleanup our state but
    // also preserve the error message that caused the abort.  It is not
    // possible to reorder code to do this:
    //        abort();
    //        d->error = SomeError
    // as QUnixSocket::abort() might emit a signal and we need the error to be
    // set within that signal.  So, if we want an error message to be preserved
    // across a *single* call to abort(), we set the
    // QUnixSocketPrivate::CausedAbort flag in the error.
    if(d->error & QUnixSocketPrivate::CausedAbort)
        d->error = (QUnixSocket::SocketError)(d->error &
                                              ~QUnixSocketPrivate::CausedAbort);
    else
        d->error = NoError;

    if( UnconnectedState == d->state) return;

#ifdef QUNIXSOCKET_DEBUG
    int closerv =
#endif
        ::close(d->fd);
#ifdef QUNIXSOCKET_DEBUG
    if(0 != closerv) {
        qDebug() << "QUnixSocket: Unable to close socket during abort ("
                 << strerror(errno) << ')';
    }
#endif

    // Reset variables
    d->fd = -1;
    d->state = UnconnectedState;
    d->dataBufferLength = 0;
    d->flushAncillary();
    d->address = QByteArray();
    if(d->readNotifier) {
        d->readNotifier->setEnabled(false);
        d->readNotifier->deleteLater();
    }
    if(d->writeNotifier) {
        d->writeNotifier->setEnabled(false);
        d->writeNotifier->deleteLater();
    }
    d->readNotifier = 0;
    d->writeNotifier = 0;
    d->writeQueue.clear();
    d->writeQueueBytes = 0;
    if(d->closingTimer) {
        d->killTimer(d->closingTimer);
    }
    d->closingTimer = 0;
    emit stateChanged(d->state);
}

address()

QByteArray QUnixSocket::address

(

)

const

Returns the Unix path address passed to QUnixSocket::connect() .

This method will return an empty path if the object is in the Unconnected QUnixSocket::state(){state } or was connected through a call to QUnixSocket::setSocketDescriptor()

See also

QUnixSocket::connect() QUnixSocket::setSocketDescriptor()

Definition at line 1258 of file qunixsocket.cpp.

{
    return d->address;
}

bytesAvailable()

qint64 QUnixSocket::bytesAvailable ( ) const

virtual

Returns the number of bytes available for immediate retrieval through a call to QUnixSocket::read() .

Reimplemented from QIODevice.

Definition at line 1267 of file qunixsocket.cpp.

{
    return QIODevice::bytesAvailable() + d->dataBufferLength;
}

bytesToWrite()

qint64 QUnixSocket::bytesToWrite ( ) const

virtual

Returns the number of enqueued bytes still to be written to the socket.

Reimplemented from QIODevice.

Definition at line 1275 of file qunixsocket.cpp.

{
    return d->writeQueueBytes;
}

canReadLine()

bool QUnixSocket::canReadLine ( ) const

virtual

Warning

This function is not part of the public interface.

Reimplemented from QIODevice.

Definition at line 1608 of file qunixsocket.cpp.

{
    for(unsigned int ii = 0; ii < d->dataBufferLength; ++ii)
        if(d->dataBuffer[ii] == '\n') return true;
    return false;
}

close()

void QUnixSocket::close ( )

virtual

Close the connection.

The instance will enter the Closing QUnixSocket::state(){state } until all pending data has been transmitted, at which point it will enter the Unconnected state.

Even if there is no pending data for transmission, the object will never jump directly to Disconnect without first passing through the Closing state.

See also

QUnixSocket::abort()

Reimplemented from QIODevice.

Definition at line 1201 of file qunixsocket.cpp.

Referenced by abort().

{
    if(ConnectedState != state()) return;

    d->state = ClosingState;
    if(d->writeQueue.isEmpty()) {
        d->closingTimer = d->startTimer(0); // Start a timer to "fake"
                                            // completing writes
    }
    emit stateChanged(d->state);
}

connect()

bool QUnixSocket::connect

(

const QByteArray &

path

)

Attempt to connect to path.

This method is synchronous and will return true if the connection succeeds and false otherwise. In the case of failure, QUnixSocket::error() will be set accordingly.

Any existing connection will be aborted, and all pending data will be discarded.

See also

QUnixSocket::close() QUnixSocket::abort() QUnixSocket::error()

Definition at line 946 of file qunixsocket.cpp.

Referenced by QWSSocket::connectToLocalFile().

{
    int _true;
    int crv;
#ifdef QUNIXSOCKET_DEBUG
    qDebug() << "QUnixSocket: Connect requested to '"
             << path << '\'';
#endif

    abort(); // Reset any existing connection

    if(UnconnectedState != d->state) // abort() caused a signal and someone messed
                                 // with us.  We'll assume they know what
                                 // they're doing and bail.  Alternative is to
                                 // have a special "Connecting" state
        return false;


    if(path.isEmpty() || path.size() > UNIX_PATH_MAX) {
        d->error = InvalidPath;
        return false;
    }

    // Create the socket
    d->fd = ::socket(PF_UNIX, SOCK_STREAM, 0);
    if(-1 == d->fd) {
#ifdef QUNIXSOCKET_DEBUG
        qDebug() << "QUnixSocket: Unable to create socket ("
                 << strerror(errno) << ')';
#endif
        d->error = ResourceError;
        goto connect_error;
    }

    // Set socket options
    _true = 1;
    crv = ::setsockopt(d->fd, SOL_SOCKET, SO_PASSCRED, (void *)&_true,
                       sizeof(int));
    if(-1 == crv) {
#ifdef QUNIXSOCKET_DEBUG
        qDebug() << "QUnixSocket: Unable to configure socket ("
                 << ::strerror(errno) << ')';
#endif
        d->error = ResourceError;

        goto connect_error;
    }

    // Construct our unix address
    struct ::sockaddr_un addr;
    addr.sun_family = AF_UNIX;
    ::memcpy(addr.sun_path, path.data(), path.size());
    if(path.size() < UNIX_PATH_MAX)
        addr.sun_path[path.size()] = '\0';

    // Attempt the connect
    crv = ::connect(d->fd, (sockaddr *)&addr, sizeof(sockaddr_un));
    if(-1 == crv) {
#ifdef QUNIXSOCKET_DEBUG
        qDebug() << "QUnixSocket: Unable to connect ("
                 << ::strerror(errno) << ')';
#endif
        if(ECONNREFUSED == errno)
            d->error = ConnectionRefused;
        else if(ENOENT == errno)
            d->error = NonexistentPath;
        else
            d->error = UnknownError;

        goto connect_error;
    }

    // We're connected!
    d->address = path;
    d->state = ConnectedState;
    d->readNotifier = new QSocketNotifier(d->fd, QSocketNotifier::Read, d);
    d->writeNotifier = new QSocketNotifier(d->fd, QSocketNotifier::Write, d);
    QObject::connect(d->readNotifier, SIGNAL(activated(int)),
                     d, SLOT(readActivated()));
    QObject::connect(d->writeNotifier, SIGNAL(activated(int)),
                     d, SLOT(writeActivated()));
    d->readNotifier->setEnabled(true);
    d->writeNotifier->setEnabled(false);
    setOpenMode(QIODevice::ReadWrite);
    emit stateChanged(ConnectedState);

#ifdef QUNIXSOCKET_DEBUG
    qDebug() << "QUnixSocket: Connected to " << path;
#endif
    return true;

connect_error: // Cleanup failed connection
    if(-1 != d->fd) {
#ifdef QUNIXSOCKET_DEBUG
        int closerv =
#endif
            QT_CLOSE(d->fd);
#ifdef QUNIXSOCKET_DEBUG
        if(0 != closerv) {
            qDebug() << "QUnixSocket: Unable to close file descriptor after "
                        "failed connect (" << ::strerror(errno) << ')';
        }
#endif
    }
    d->fd = -1;
    return false;
}

error()

QUnixSocket::SocketError QUnixSocket::error

(

)

const

Returns the last error to have occurred on this object.

This method is not destructive, so multiple calls to QUnixSocket::error() will return the same value. The error is only reset by a call to QUnixSocket::connect() or QUnixSocket::abort()

Definition at line 1236 of file qunixsocket.cpp.

Referenced by QWSSocket::errorString(), QWSSocket::forwardStateChange(), QUnixSocketPrivate::readActivated(), and QUnixSocketPrivate::writeActivated().

{
    return (QUnixSocket::SocketError)
        (d->error & ~QUnixSocketPrivate::CausedAbort);
}

flush()

bool QUnixSocket::flush

(

)

This function writes as much as possible from the internal write buffer to the underlying socket, without blocking.

If any data was written, this function returns true; otherwise false is returned.

Definition at line 1219 of file qunixsocket.cpp.

{
    // This needs to have the same semantics as QAbstractSocket, if it is to
    // be used interchangeably with that class.
    if (d->writeQueue.isEmpty())
        return false;

    d->writeActivated();
    return true;
}

isSequential()

bool QUnixSocket::isSequential ( ) const

virtual

Warning

This function is not part of the public interface.

Reimplemented from QIODevice.

Definition at line 1474 of file qunixsocket.cpp.

{
    return true;
}

operator=()

QUnixSocket& QUnixSocket::operator= ( const QUnixSocket &  )

private

read() [1/3]

qint64 QUnixSocket::read ( char *  data, qint64  maxSize  )

inline

Definition at line 174 of file qunixsocket_p.h.

Referenced by QAuthDevice::recvReadyRead().

    { return QIODevice::read(data, maxSize); }

read() [2/3]

QByteArray QUnixSocket::read ( qint64  maxSize )

inline

Definition at line 176 of file qunixsocket_p.h.

    { return QIODevice::read(maxSize); }

read() [3/3]

QUnixSocketMessage QUnixSocket::read

(

)

Return the next available message, or an empty message if none is available.

To avoid retrieving empty messages, applications should connect to the QUnixSocket::readyRead() signal to be notified when new messages are available or periodically poll the QUnixSocket::bytesAvailable() method.

See also

QUnixSocket::readyRead() QUnixSocket::bytesAvailable()

Definition at line 1409 of file qunixsocket.cpp.

{
    QUnixSocketMessage data;
    if(!d->dataBufferLength)
        return data;

    data.d->state = QUnixSocketMessagePrivate::Credential;

    // Bytes are easy
    data.setBytes(QByteArray(d->dataBuffer, d->dataBufferLength));

    // Extract ancillary data
    QList<QUnixSocketRights> a;

    ::cmsghdr * h = (::cmsghdr *)CMSG_FIRSTHDR(&(d->message));
    while(h) {

        if(SCM_CREDENTIALS == h->cmsg_type) {
            ::ucred * cred = (::ucred *)CMSG_DATA(h);
#ifdef QUNIXSOCKET_DEBUG
            qDebug( "Credentials recd: pid %lu - gid %lu - uid %lu",
                    cred->pid, cred->gid, cred->uid );
#endif
            data.d->pid = cred->pid;
            data.d->gid = cred->gid;
            data.d->uid = cred->uid;

        } else if(SCM_RIGHTS == h->cmsg_type) {

            int * fds = (int *)CMSG_DATA(h);
            int numFds = (h->cmsg_len - CMSG_LEN(0)) / sizeof(int);

            for(int ii = 0; ii < numFds; ++ii) {
                QUnixSocketRights qusr(fds[ii], 0);
                a.append(qusr);
            }

        } else {

#ifdef QUNIXSOCKET_DEBUG
            qFatal("QUnixSocket: Unknown ancillary data type (%d) received.",
                   h->cmsg_type);
#endif

        }

        h = (::cmsghdr *)CMSG_NXTHDR(&(d->message), h);
    }

    if(d->message.msg_flags & MSG_CTRUNC) {
        data.d->state = (QUnixSocketMessagePrivate::AncillaryDataState)(QUnixSocketMessagePrivate::Truncated |
                               QUnixSocketMessagePrivate::Credential );
    }

    if(!a.isEmpty())
        data.d->rights = a;

    d->dataBufferLength = 0;
    d->messageValid = false;
    d->readNotifier->setEnabled(true);

    return data;
}

readBufferSize()

qint64 QUnixSocket::readBufferSize

(

)

const

Returns the size of the read buffer in bytes.

The read buffer size determines the amount of byte data that can be read from the socket in one go. The read buffer size caps the maximum value that can be returned by QUnixSocket::bytesAvailable() and will always be greater than zero. By default, the read buffer size is 1024 bytes.

The size of the read buffer is independent of the rights buffer, which can be queried by QUnixSocket::rightsBufferSize() .

See also

QUnixSocket::setReadBufferSize()

Definition at line 1292 of file qunixsocket.cpp.

{
    return d->dataBufferCapacity;
}

readData()

qint64 QUnixSocket::readData ( char *  data, qint64  maxSize  )

protectedvirtual

Warning

This function is not part of the public interface.

Implements QIODevice.

Definition at line 1616 of file qunixsocket.cpp.

{
    Q_ASSERT(data);
    if(0 >= maxSize) return 0;
    if(!d->dataBufferLength) return 0;

    // Read data
    unsigned int size = d->dataBufferLength>maxSize?maxSize:d->dataBufferLength;
    memcpy(data, d->dataBuffer, size);
    if(size == d->dataBufferLength) {
        d->dataBufferLength = 0;
    } else {
        memmove(d->dataBuffer, d->dataBuffer + size, d->dataBufferLength - size);
        d->dataBufferLength -= size;
    }


    // Flush ancillary
    d->flushAncillary();

    if(0 == d->dataBufferLength)
        d->readNotifier->setEnabled(true);

    return size;
}

rightsBufferSize()

qint64 QUnixSocket::rightsBufferSize

(

)

const

Returns the size of the rights buffer in rights entries.

The rights buffer size determines the number of rights transferences that can be received in any message. Unlike byte stream data which can be fragmented into many smaller messages if the read buffer is not large enough to contain all the available data, rights data is transmitted as unfragmentable datagrams. If the rights buffer is not large enough to contain this unfragmentable datagram, the datagram will be truncated and rights data irretrievably lost. If truncation occurs, the QUnixSocketMessage::rightsWereTruncated() flag will be set. By default the rights buffer size is 0 entries - rights data cannot be received.

The size of the rights buffer is independent of the read buffer, which can be queried by QUnixSocket::readBufferSize() .

See also

QUnixSocket::setRightsBufferSize()

Definition at line 1334 of file qunixsocket.cpp.

{
    return d->ancillaryBufferCount;
}

setReadBufferSize()

void QUnixSocket::setReadBufferSize

(

qint64

size

)

Sets the size of the socket's read buffer in bytes.

The size of the read buffer is independent of the rights buffer, which can be set by QUnixSocket::setRightsBufferSize() .

Attempting to reduce the buffer size while bytes are available for reading (ie. while the buffer is in use) will fail.

See also

QUnixSocket::readBufferSize()

Definition at line 1308 of file qunixsocket.cpp.

Referenced by QUnixSocket().

{
    Q_ASSERT(size > 0);
    if(size == d->dataBufferCapacity || d->dataBufferLength) return;
    if(d->dataBuffer) delete [] d->dataBuffer;
    d->dataBuffer = new char[size];
    d->dataBufferCapacity = size;
}

setRightsBufferSize()

void QUnixSocket::setRightsBufferSize

(

qint64

size

)

Sets the size of the socket's rights buffer in rights entries.

The size of the rights buffer is independent of the read buffer, which can be set by QUnixSocket::setReadBufferSize() .

Attempting to reduce the buffer size while bytes are available for reading (ie. while the buffer is in use) will fail.

See also

QUnixSocket::rightsBufferSize()

Definition at line 1350 of file qunixsocket.cpp.

Referenced by QUnixSocket().

{
    Q_ASSERT(size >= 0);

    if((size == d->ancillaryBufferCount || d->dataBufferLength) &&
            d->ancillaryBuffer)
        return;

    qint64 byteSize = CMSG_SPACE(sizeof(::ucred)) +
                      CMSG_SPACE(size * sizeof(int));

    if(d->ancillaryBuffer) delete [] d->ancillaryBuffer;
    d->ancillaryBuffer = new char[byteSize];
    d->ancillaryBufferCount = size;
}

setSocketDescriptor()

bool QUnixSocket::setSocketDescriptor

(

int

socketDescriptor

)

Sets the socket descriptor to use to socketDescriptor, bypassing QUnixSocket's connection infrastructure, and return true on success and false on failure.

socketDescriptor must be in the connected state, and must be a Unix domain socket descriptor. Following a successful call to this method, the QUnixSocket instance will be in the Connected state and will have assumed ownership of socketDescriptor.

Any existing connection will be aborted, and all pending data will be discarded.

See also

QUnixSocket::connect()

Definition at line 1067 of file qunixsocket.cpp.

{
    abort();

    if(UnconnectedState != state()) // See QUnixSocket::connect()
        return false;

    // Attempt to set the socket options
    if(-1 == socketDescriptor) {
#ifdef QUNIXSOCKET_DEBUG
        qDebug() << "QUnixSocket: User provided socket is invalid";
#endif
        d->error = ResourceError;
        return false;
    }

    // Set socket options
    int _true = 1;
    int crv = ::setsockopt(socketDescriptor, SOL_SOCKET,
                           SO_PASSCRED, (void *)&_true, sizeof(int));
    if(-1 == crv) {
#ifdef QUNIXSOCKET_DEBUG
        qDebug() << "QUnixSocket: Unable to configure client provided socket ("
                 << ::strerror(errno) << ')';
#endif
        d->error = ResourceError;

        return false;
    }

    d->fd = socketDescriptor;
    d->state = ConnectedState;
    d->address = QByteArray();
    setOpenMode(QIODevice::ReadWrite);
    d->readNotifier = new QSocketNotifier(d->fd, QSocketNotifier::Read, d);
    d->writeNotifier = new QSocketNotifier(d->fd, QSocketNotifier::Write, d);
    QObject::connect(d->readNotifier, SIGNAL(activated(int)),
                     d, SLOT(readActivated()));
    QObject::connect(d->writeNotifier, SIGNAL(activated(int)),
                     d, SLOT(writeActivated()));
    d->readNotifier->setEnabled(true);
    d->writeNotifier->setEnabled(false);
    emit stateChanged(d->state);

    return true;
}

socketDescriptor()

int QUnixSocket::socketDescriptor

(

)

const

Returns the socket descriptor currently in use.

This method will return -1 if the QUnixSocket instance is in the UnconnectedState QUnixSocket::state(){state. }

See also

QUnixSocket::setSocketDescriptor()

Definition at line 1120 of file qunixsocket.cpp.

Referenced by setSocketDescriptor().

{
    return d->fd;
}

state()

QUnixSocket::SocketState QUnixSocket::state

(

)

const

Returns the connection state of this instance.

Definition at line 1245 of file qunixsocket.cpp.

Referenced by close(), setSocketDescriptor(), and write().

{
    return d->state;
}

stateChanged

QUnixSocket::stateChanged ( SocketState  socketState )

signal

This signal is emitted each time the socket changes connection state.

socketState will be set to the socket's new state.

Referenced by abort(), close(), connect(), and setSocketDescriptor().

waitForBytesWritten()

bool QUnixSocket::waitForBytesWritten ( int  msecs = 300 )

virtual

For buffered devices, this function waits until a payload of buffered written data has been written to the device and the bytesWritten() signal has been emitted, or until msecs milliseconds have passed.

If msecs is -1, this function will not time out. For unbuffered devices, it returns immediately.

Returns true if a payload of data was written to the device; otherwise returns false (i.e. if the operation timed out, or if an error occurred).

This function can operate without an event loop. It is useful when writing non-GUI applications and when performing I/O operations in a non-GUI thread.

If called from within a slot connected to the bytesWritten() signal, bytesWritten() will not be reemitted.

Reimplement this function to provide a blocking API for a custom device. The default implementation does nothing, and returns false.

Warning

Calling this function from the main (GUI) thread might cause your user interface to freeze.

See also

waitForReadyRead()

Reimplemented from QIODevice.

Definition at line 1533 of file qunixsocket.cpp.

{
    if(UnconnectedState == d->state)
        return false;

    Q_ASSERT(-1 != d->fd);

    if ( d->writeQueue.isEmpty() )
        return true;

    QTime stopWatch;
    stopWatch.start();

    while ( true )
    {
        fd_set fdwrite;
        FD_ZERO(&fdwrite);
        FD_SET(d->fd, &fdwrite);
        int timeout = msecs < 0 ? 0 : msecs - stopWatch.elapsed();
        struct timeval tv;
        struct timeval *ptrTv = 0;
        if ( -1 != msecs )
        {
            tv.tv_sec = timeout / 1000;
            tv.tv_usec = (timeout % 1000) * 1000;
            ptrTv = &tv;
        }

        int rv = ::select(d->fd + 1, 0, &fdwrite, 0, ptrTv);
        switch ( rv )
        {
            case 0:
                // timeout
                return false;
            case 1:
            {
                // ok to write
                qint64 bytesWritten = d->writeActivated();
                if (bytesWritten == 0) {
                    // We need to retry
                    int delay = 1;
                    do {
                        if (-1 != msecs) {
                            timeout = msecs - stopWatch.elapsed();
                            if (timeout <= 0) {
                                // We have exceeded our allotted time
                                return false;
                            } else {
                                if (delay > timeout)
                                    delay = timeout;
                            }
                        }

                        // Pause before we make another attempt to send
                        ::usleep(delay * 1000);
                        if (delay < 1024)
                            delay *= 2;

                        bytesWritten = d->writeActivated();
                    } while (bytesWritten == 0);
                }
                return (bytesWritten != -1);
            }
            default:
                // error - or an uncaught signal!!!!!!!!!
                if ( rv == EINTR )
                    continue;
                abort();
                return false;
        }
    }
    return false; // fix warnings
}

waitForReadyRead()

bool QUnixSocket::waitForReadyRead ( int  msecs = 300 )

virtual

Warning

This function is not part of the public interface.

Reimplemented from QIODevice.

Definition at line 1480 of file qunixsocket.cpp.

{
    if(UnconnectedState == d->state)
        return false;

    if(d->messageValid) {
        return true;
    }

    Q_ASSERT(-1 != d->fd);

    int     timeout = msecs;
    struct  timeval tv;
    struct  timeval *ptrTv = 0;
    QTime   stopWatch;

    stopWatch.start();

    do
    {
        fd_set readset;

        FD_ZERO(&readset);
        FD_SET(d->fd, &readset);

        if(-1 != msecs) {
            tv.tv_sec = timeout / 1000;
            tv.tv_usec = (timeout % 1000) * 1000;
            ptrTv = &tv;
        }

        int rv = ::select(d->fd + 1, &readset, 0, 0, ptrTv);
        switch(rv) {
            case 0:
                // timeout
                return false;
            case 1:
                // ok
                d->readActivated();
                return true;
            default:
                if (errno != EINTR)
                    abort();    // error
                break;
        }

        timeout = msecs - stopWatch.elapsed();
    }
    while (timeout > 0);

    return false;
}

write() [1/3]

qint64 QUnixSocket::write ( const char *  data, qint64  maxSize  )

inline

Definition at line 170 of file qunixsocket_p.h.

Referenced by writeData().

    { return QIODevice::write(data, maxSize); }

write() [2/3]

qint64 QUnixSocket::write ( const QByteArray &  byteArray )

inline

Definition at line 172 of file qunixsocket_p.h.

    { return QIODevice::write(byteArray); }

write() [3/3]

qint64 QUnixSocket::write

(

const QUnixSocketMessage &

socketdata

)

Writes socketdata to the socket.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

In addition to failing if the socket is not in the Connected state, writing will fail if socketdata is QUnixSocketMessage::isValid(){invalid. }

Writes through the QUnixSocket class are asynchronous. Rather than being written immediately, data is enqueued and written once the application reenters the Qt event loop and the socket becomes available for writing. Thus, this method will only fail if the socket is not in the Connected state

• it is illegal to attempt a write on a Unconnected or Closing socket.

Applications can monitor the progress of data writes through the QUnixSocket::bytesWritten() signal and QUnixSocket::bytesToWrite() method.

See also

QUnixSocketMessage

Definition at line 1388 of file qunixsocket.cpp.

{
    if(ConnectedState != state() || !socketdata.isValid()) return -1;
    if(socketdata.d->size() == 0) return 0;

    d->writeQueue.enqueue(socketdata);
    d->writeQueueBytes += socketdata.d->size();
    d->writeNotifier->setEnabled(true);

    return socketdata.d->size();
}

writeData()

qint64 QUnixSocket::writeData ( const char *  data, qint64  maxSize  )

protectedvirtual

Warning

This function is not part of the public interface.

Implements QIODevice.

Definition at line 1643 of file qunixsocket.cpp.

{
    return write(QUnixSocketMessage(QByteArray(data, maxSize)));
}

Properties

d

QUnixSocketPrivate* QUnixSocket::d

private

Definition at line 197 of file qunixsocket_p.h.

Referenced by abort(), address(), bytesAvailable(), bytesToWrite(), canReadLine(), close(), connect(), error(), flush(), read(), readBufferSize(), readData(), rightsBufferSize(), setReadBufferSize(), setRightsBufferSize(), setSocketDescriptor(), socketDescriptor(), state(), waitForBytesWritten(), waitForReadyRead(), write(), and ~QUnixSocket().

---

The documentation for this class was generated from the following files:

• /src/gui/embedded/qunixsocket_p.h
• /src/gui/embedded/qunixsocket.cpp