QUnixSocketMessage Class Reference

The QUnixSocketMessage class encapsulates a message sent or received through the QUnixSocket class. More...

#include <qunixsocket_p.h>

Public Functions
const QByteArray &	bytes () const
	Return the data portion of the message. More...
gid_t	groupId () const
	Returns the group id credential associated with this message. More...
bool	isValid () const
	Return true if this message is valid. More...
QUnixSocketMessage &	operator= (const QUnixSocketMessage &)
	Assign the contents of other to this object. More...
pid_t	processId () const
	Returns the process id credential associated with this message. More...
	QUnixSocketMessage ()
	Construct an empty QUnixSocketMessage. More...
	QUnixSocketMessage (const QByteArray &)
	Construct a QUnixSocketMessage with an initial data payload of bytes. More...
	QUnixSocketMessage (const QByteArray &, const QList< QUnixSocketRights > &)
	Construct a QUnixSocketMessage with an initial data payload of bytes and an initial rights payload of rights. More...
	QUnixSocketMessage (const QUnixSocketMessage &)
	Create a copy of other. More...
	QUnixSocketMessage (const iovec *, int)
	Construct a QUnixSocketMessage with an initial data payload of data which points to an array of vecLen iovec structures. More...
const QList< QUnixSocketRights > &	rights () const
	Return the rights portion of the message. More...
bool	rightsWereTruncated () const
	Returns true if the rights portion of the message was truncated on reception due to insufficient buffer size. More...
void	setBytes (const QByteArray &)
	Set the data portion of the message to bytes. More...
void	setGroupId (gid_t)
	Set the group id credential associated with this message to gid. More...
void	setProcessId (pid_t)
	Set the process id credential associated with this message to pid. More...
void	setRights (const QList< QUnixSocketRights > &)
	Set the rights portion of the message to rights. More...
void	setUserId (uid_t)
	Set the user id credential associated with this message to uid. More...
uid_t	userId () const
	Returns the user id credential associated with this message. More...
	~QUnixSocketMessage ()
	Destroy this instance. More...

Properties
QSharedDataPointer< QUnixSocketMessagePrivate >	d

Friends
class	QUnixSocket
class	QUnixSocketPrivate

Detailed Description

The QUnixSocketMessage class encapsulates a message sent or received through the QUnixSocket class.

Warning

This function is not part of the public interface.

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

In addition to transmitting regular byte stream data, messages sent over Unix domain sockets may have special ancillary properties. QUnixSocketMessage instances allow programmers to retrieve and control these properties.

Every QUnixSocketMessage sent has an associated set of credentials. A message's credentials consist of the process id, the user id and the group id of the sending process. Normally these credentials are set automatically for you by the QUnixSocketMessage class and can be queried by the receiving process using the QUnixSocketMessage::processId() , QUnixSocketMessage::userId() and QUnixSocketMessage::groupId() methods respectively.

Advanced applications may wish to change the credentials that their message is sent with, and may do so though the QUnixSocketMessage::setProcessId() , QUnixSocketMessage::setUserId() and QUnixSocketMessage::setGroupId() methods. The validity of these credentials is verified by the system kernel. Only the root user can send messages with credentials that are not his own. Sending of the message will fail for any non-root user who attempts to fabricate credentials. Note that this failure is enforced by the system kernel - receivers can trust the accuracy of credential data!

Unix domain socket messages may also be used to transmit Unix file descriptors between processes. In this context, file descriptors are known as rights data and are encapsulated by the QUnixSocketRights class. Senders can set the file descriptors to transmit using the QUnixSocketMessage::setRights() and receivers can retrieve this data through a call to QUnixSocketMessage::rights() . QUnixSocket and QUnixSocketRights discuss the specific copy and ordering semantic associated with rights data.

QUnixSocketMessage messages are sent by the QUnixSocket::write() method. Like any normal network message, attempting to transmit an empty QUnixSocketMessage will succeed, but result in a no-op. Limitations in the Unix domain protocol semantic will cause a transmission of a QUnixSocketMessage with rights data, but no byte data portion, to fail.

See also

QUnixSocket QUnixSocketRights

Definition at line 92 of file qunixsocket_p.h.

Constructors and Destructors

QUnixSocketMessage() [1/5]

QUnixSocketMessage::QUnixSocketMessage

(

)

Construct an empty QUnixSocketMessage.

This instance will have not data and no rights information. The message's credentials will be set to the application's default credentials.

Definition at line 406 of file qunixsocket.cpp.

Referenced by QUnixSocketMessage().

: d(new QUnixSocketMessagePrivate())
{
}

QUnixSocketMessage() [2/5]

QUnixSocketMessage::QUnixSocketMessage

(

const QByteArray &

bytes

)

Construct a QUnixSocketMessage with an initial data payload of bytes.

The message's credentials will be set to the application's default credentials.

Definition at line 415 of file qunixsocket.cpp.

: d(new QUnixSocketMessagePrivate(bytes))
{
}

QUnixSocketMessage() [3/5]

QUnixSocketMessage::QUnixSocketMessage	(	const QByteArray &	bytes,
		const QList< QUnixSocketRights > &	rights
	)

Construct a QUnixSocketMessage with an initial data payload of bytes and an initial rights payload of rights.

The message's credentials will be set to the application's default credentials.

A message with rights data but an empty data payload cannot be transmitted by the system.

Definition at line 428 of file qunixsocket.cpp.

: d(new QUnixSocketMessagePrivate(bytes, rights))
{
}

QUnixSocketMessage() [4/5]

QUnixSocketMessage::QUnixSocketMessage

(

const QUnixSocketMessage &

other

)

Create a copy of other.

Definition at line 437 of file qunixsocket.cpp.

: d(other.d)
{
}

QUnixSocketMessage() [5/5]

QUnixSocketMessage::QUnixSocketMessage	(	const iovec *	data,
		int	vecLen
	)

Construct a QUnixSocketMessage with an initial data payload of data which points to an array of vecLen iovec structures.

The message's credentials will be set to the application's default credentials.

This method can be used to avoid the overhead of copying buffers of data and will directly send the data pointed to by data on the socket. It also avoids the syscall overhead of making a number of small socket write calls, if a number of data items can be delivered with one write.

Caller must ensure the iovec * data remains valid until the message is flushed. Caller retains ownership of the iovec structs.

~QUnixSocketMessage()

QUnixSocketMessage::~QUnixSocketMessage

(

)

Destroy this instance.

Definition at line 479 of file qunixsocket.cpp.

{
}

Functions

bytes()

const QByteArray & QUnixSocketMessage::bytes

(

)

const

Return the data portion of the message.

See also

QUnixSocketMessage::setBytes()

Definition at line 537 of file qunixsocket.cpp.

Referenced by QAuthDevice::recvReadyRead(), setBytes(), and QUnixSocketPrivate::writeActivated().

{
    return d->bytes;
}

groupId()

gid_t QUnixSocketMessage::groupId

(

)

const

Returns the group id credential associated with this message.

See also

QUnixSocketMessage::setGroupId()

Definition at line 573 of file qunixsocket.cpp.

{
    if(QUnixSocketMessagePrivate::Credential & d->state)
        return d->gid;
    else
        return ::getegid();
}

isValid()

bool QUnixSocketMessage::isValid

(

)

const

Return true if this message is valid.

A message with rights data but an empty byte data payload cannot be transmitted by the system and is marked as invalid.

Definition at line 637 of file qunixsocket.cpp.

Referenced by QUnixSocket::write().

{
    return d->rights.isEmpty() || !d->bytes.isEmpty();
}

operator=()

QUnixSocketMessage & QUnixSocketMessage::operator=

(

const QUnixSocketMessage &

other

)

Assign the contents of other to this object.

Definition at line 470 of file qunixsocket.cpp.

{
    d = other.d;
    return *this;
}

processId()

pid_t QUnixSocketMessage::processId

(

)

const

Returns the process id credential associated with this message.

See also

QUnixSocketMessage::setProcessId()

Definition at line 547 of file qunixsocket.cpp.

Referenced by QAuthDevice::recvReadyRead().

{
    if(QUnixSocketMessagePrivate::Credential & d->state)
        return d->pid;
    else
        return ::getpid();
}

rights()

const QList< QUnixSocketRights > & QUnixSocketMessage::rights

(

)

const

Return the rights portion of the message.

See also

QUnixSocketMessage::setRights()

Definition at line 513 of file qunixsocket.cpp.

Referenced by setRights(), and QUnixSocketPrivate::writeActivated().

{
    return d->rights;
}

rightsWereTruncated()

bool QUnixSocketMessage::rightsWereTruncated

(

)

const

Returns true if the rights portion of the message was truncated on reception due to insufficient buffer size.

The rights buffer size can be adjusted through calls to the QUnixSocket::setRightsBufferSize() method. QUnixSocket contains a discussion of the buffering and truncation characteristics of the Unix domain protocol.

See also

QUnixSocket QUnixSocket::setRightsBufferSize()

Definition at line 527 of file qunixsocket.cpp.

{
    return d->state & QUnixSocketMessagePrivate::Truncated;
}

setBytes()

void QUnixSocketMessage::setBytes

(

const QByteArray &

bytes

)

Set the data portion of the message to bytes.

See also

QUnixSocketMessage::bytes()

Definition at line 488 of file qunixsocket.cpp.

Referenced by QUnixSocket::read().

{
    d.detach();
    d->bytes = bytes;
}

setGroupId()

void QUnixSocketMessage::setGroupId

(

gid_t

gid

)

Set the group id credential associated with this message to gid.

Unless you are the root user, setting a fraudulant credential will cause this message to fail.

See also

QUnixSocketMessage::groupId()

Definition at line 622 of file qunixsocket.cpp.

{
    if(!(d->state & QUnixSocketMessagePrivate::Credential)) {
        d->state = (QUnixSocketMessagePrivate::AncillaryDataState)( d->state | QUnixSocketMessagePrivate::Credential );
        d->pid = ::getpid();
        d->uid = ::geteuid();
    }
    d->gid = gid;
}

setProcessId()

void QUnixSocketMessage::setProcessId

(

pid_t

pid

)

Set the process id credential associated with this message to pid.

Unless you are the root user, setting a fraudulant credential will cause this message to fail.

See also

QUnixSocketMessage::processId()

Definition at line 588 of file qunixsocket.cpp.

{
    if(!(d->state & QUnixSocketMessagePrivate::Credential)) {
        d->state = (QUnixSocketMessagePrivate::AncillaryDataState)( d->state | QUnixSocketMessagePrivate::Credential );
        d->uid = ::geteuid();
        d->gid = ::getegid();
    }
    d->pid = pid;
}

setRights()

void QUnixSocketMessage::setRights

(

const QList< QUnixSocketRights > &

rights

)

Set the rights portion of the message to rights.

A message with rights data but an empty byte data payload cannot be transmitted by the system.

See also

QUnixSocketMessage::rights()

Definition at line 502 of file qunixsocket.cpp.

{
    d.detach();
    d->rights = rights;
}

setUserId()

void QUnixSocketMessage::setUserId

(

uid_t

uid

)

Set the user id credential associated with this message to uid.

Unless you are the root user, setting a fraudulant credential will cause this message to fail.

See also

QUnixSocketMessage::userId()

Definition at line 605 of file qunixsocket.cpp.

{
    if(!(d->state & QUnixSocketMessagePrivate::Credential)) {
        d->state = (QUnixSocketMessagePrivate::AncillaryDataState)( d->state | QUnixSocketMessagePrivate::Credential );
        d->pid = ::getpid();
        d->gid = ::getegid();
    }
    d->uid = uid;
}

userId()

uid_t QUnixSocketMessage::userId

(

)

const

Returns the user id credential associated with this message.

See also

QUnixSocketMessage::setUserId()

Definition at line 560 of file qunixsocket.cpp.

{
    if(QUnixSocketMessagePrivate::Credential & d->state)
        return d->uid;
    else
        return ::geteuid();
}

Friends and Related Functions

QUnixSocket

friend class QUnixSocket

friend

Definition at line 120 of file qunixsocket_p.h.

QUnixSocketPrivate

friend class QUnixSocketPrivate

friend

Definition at line 121 of file qunixsocket_p.h.

Properties

d

QSharedDataPointer<QUnixSocketMessagePrivate> QUnixSocketMessage::d

private

Definition at line 122 of file qunixsocket_p.h.

Referenced by bytes(), groupId(), isValid(), operator=(), processId(), QUnixSocketMessage(), QUnixSocket::read(), rights(), rightsWereTruncated(), setBytes(), setGroupId(), setProcessId(), setRights(), setUserId(), userId(), QUnixSocket::write(), and QUnixSocketPrivate::writeActivated().

---

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

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