com.trolltech.qt.network
Class QLocalSocket

java.lang.Object
  extended by com.trolltech.qt.internal.QSignalEmitterInternal
      extended by com.trolltech.qt.QSignalEmitter
          extended by com.trolltech.qt.QtJambiObject
              extended by com.trolltech.qt.core.QObject
                  extended by com.trolltech.qt.core.QIODevice
                      extended by com.trolltech.qt.network.QLocalSocket
All Implemented Interfaces:
QtJambiInterface

public class QLocalSocket
extends QIODevice

The QLocalSocket class provides a local socket. On Windows this is a named pipe and on Unix this this is a local domain socket.

If an error occurs, socketError() returns the type of error, and errorString() can be called to get a human readable description of what happened.

Although QLocalSocket is designed for use with an event loop, it's possible to use it without one. In that case, you must use waitForConnected(), waitForReadyRead(), waitForBytesWritten(), and waitForDisconnected() which blocks until the operation is complete or the timeout expires.

Note that this feature is not supported on Window 9x.

See also:
QLocalServer.


Nested Class Summary
static class QLocalSocket.LocalSocketError
          The LocalServerError enumeration represents the errors that can occur.
static class QLocalSocket.LocalSocketState
          This enum describes the different states in which a socket can be.
 
Nested classes/interfaces inherited from class com.trolltech.qt.core.QIODevice
QIODevice.OpenMode, QIODevice.OpenModeFlag
 
Nested classes/interfaces inherited from class com.trolltech.qt.QSignalEmitter
QSignalEmitter.AbstractSignal, QSignalEmitter.PrivateSignal0, QSignalEmitter.PrivateSignal1, QSignalEmitter.PrivateSignal2, QSignalEmitter.PrivateSignal3, QSignalEmitter.PrivateSignal4, QSignalEmitter.PrivateSignal5, QSignalEmitter.PrivateSignal6, QSignalEmitter.PrivateSignal7, QSignalEmitter.PrivateSignal8, QSignalEmitter.PrivateSignal9, QSignalEmitter.Signal0, QSignalEmitter.Signal1, QSignalEmitter.Signal2, QSignalEmitter.Signal3, QSignalEmitter.Signal4, QSignalEmitter.Signal5, QSignalEmitter.Signal6, QSignalEmitter.Signal7, QSignalEmitter.Signal8, QSignalEmitter.Signal9
 
Nested classes/interfaces inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
com.trolltech.qt.internal.QSignalEmitterInternal.AbstractSignalInternal
 
Field Summary
 QSignalEmitter.Signal0 connected
          This signal is emitted after connectToServer() has been called and a connection has been successfully established.
 QSignalEmitter.Signal0 disconnected
          This signal is emitted when the socket has been disconnected.
 QSignalEmitter.Signal1 error
          This signal takes 1 generic argument(s).
 QSignalEmitter.Signal1 stateChanged
          This signal takes 1 generic argument(s).
 
Fields inherited from class com.trolltech.qt.core.QIODevice
aboutToClose, bytesWritten, readChannelFinished, readyRead
 
Fields inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
currentSender
 
Constructor Summary
QLocalSocket()
          Creates a new local socket.
QLocalSocket(QObject parent)
          Creates a new local socket.
 
Method Summary
 void abort()
          Aborts the current connection and resets the socket.
 void connectToServer(java.lang.String name)
          Attempts to make a connection to name.
 void connectToServer(java.lang.String name, QIODevice.OpenMode openMode)
          Attempts to make a connection to name.
 void connectToServer(java.lang.String name, QIODevice.OpenModeFlag[] openMode)
          This is an overloaded method provided for convenience.
 void disconnectFromServer()
          Attempts to close the socket.
 QLocalSocket.LocalSocketError error()
          Returns the type of error that last occurred.
 boolean flush()
          This function writes as much as possible from the internal write buffer to the socket, without blocking.
 java.lang.String fullServerName()
          Returns the server path that the socket is connected to.
 boolean isValid()
          Returns true if the socket is valid and ready for use; otherwise returns false.
 long readBufferSize()
          Returns the size of the internal read buffer.
 java.lang.String serverName()
          Returns the name of the peer as specified by connectToServer(), or an empty QString if connectToServer() has not been called or it failed.
 void setReadBufferSize(long size)
          Sets the size of QLocalSocket's internal read buffer to be size bytes.
 boolean setSocketDescriptor(long socketDescriptor)
          Initializes QLocalSocket with the native socket descriptor socketDescriptor.
 boolean setSocketDescriptor(long socketDescriptor, QLocalSocket.LocalSocketState socketState)
          Initializes QLocalSocket with the native socket descriptor socketDescriptor.
 boolean setSocketDescriptor(long socketDescriptor, QLocalSocket.LocalSocketState socketState, QIODevice.OpenMode openMode)
          Initializes QLocalSocket with the native socket descriptor socketDescriptor.
 boolean setSocketDescriptor(long socketDescriptor, QLocalSocket.LocalSocketState socketState, QIODevice.OpenModeFlag[] openMode)
          This is an overloaded method provided for convenience.
 long socketDescriptor()
          Returns the native socket descriptor of the QLocalSocket object if this is available; otherwise returns -1.
 QLocalSocket.LocalSocketState state()
          Returns the state of the socket.
 boolean waitForConnected()
          Waits until the socket is connected, up to msec milliseconds.
 boolean waitForConnected(int msecs)
          Waits until the socket is connected, up to msec milliseconds.
 boolean waitForDisconnected()
          Waits until the socket has disconnected, up to msecs milliseconds.
 boolean waitForDisconnected(int msecs)
          Waits until the socket has disconnected, up to msecs milliseconds.
 
Methods inherited from class com.trolltech.qt.core.QIODevice
atEnd, bytesAvailable, bytesToWrite, canReadLine, close, errorString, getByte, isOpen, isReadable, isSequential, isTextModeEnabled, isWritable, open, open, openMode, peek, peek, pos, putByte, read, read, readAll, readData, readLine, readLine, readLine, readLineData, reset, seek, setErrorString, setOpenMode, setOpenMode, setTextModeEnabled, size, ungetByte, waitForBytesWritten, waitForReadyRead, write, write, writeData
 
Methods inherited from class com.trolltech.qt.core.QObject
childEvent, children, connectSlotsByName, customEvent, disposeLater, dumpObjectInfo, dumpObjectTree, dynamicPropertyNames, event, eventFilter, findChild, findChild, findChild, findChildren, findChildren, findChildren, findChildren, indexOfProperty, installEventFilter, isWidgetType, killTimer, moveToThread, objectName, parent, properties, property, removeEventFilter, setObjectName, setParent, setProperty, startTimer, timerEvent, toString, userProperty
 
Methods inherited from class com.trolltech.qt.QtJambiObject
dispose, disposed, equals, finalize, reassignNativeResources, tr, tr, tr
 
Methods inherited from class com.trolltech.qt.QSignalEmitter
blockSignals, disconnect, disconnect, signalsBlocked, signalSender, thread
 
Methods inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
__qt_signalInitialization
 
Methods inherited from class java.lang.Object
clone, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface com.trolltech.qt.QtJambiInterface
disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership
 

Field Detail

connected

public final QSignalEmitter.Signal0 connected
This signal is emitted after connectToServer() has been called and a connection has been successfully established.

See also:
connectToServer(), and disconnected() .


disconnected

public final QSignalEmitter.Signal0 disconnected
This signal is emitted when the socket has been disconnected.

See also:
connectToServer(), disconnectFromServer(), abort(), and connected() .


error

public final QSignalEmitter.Signal1 error

This signal takes 1 generic argument(s). We list their type and the name they go by in the description of this signal. <com.trolltech.qt.network.QLocalSocket$LocalSocketError(named: socketError)>:

This signal is emitted after an error occurred. The socketError parameter describes the type of error that occurred.

QLocalSocket::LocalSocketError is not a registered metatype, so for queued connections, you will have to register it with Q_DECLARE_METATYPE.

See also:
error(), and errorString().


stateChanged

public final QSignalEmitter.Signal1 stateChanged

This signal takes 1 generic argument(s). We list their type and the name they go by in the description of this signal. <com.trolltech.qt.network.QLocalSocket$LocalSocketState(named: socketState)>:

This signal is emitted whenever QLocalSocket's state changes. The socketState parameter is the new state.

QLocalSocket::SocketState is not a registered metatype, so for queued connections, you will have to register it with Q_DECLARE_METATYPE.

See also:
state().

Constructor Detail

QLocalSocket

public QLocalSocket()
Creates a new local socket. The parent argument is passed to QObject's constructor.


QLocalSocket

public QLocalSocket(QObject parent)
Creates a new local socket. The parent argument is passed to QObject's constructor.

Method Detail

abort

public final void abort()
Aborts the current connection and resets the socket. Unlike disconnectFromServer(), this function immediately closes the socket, clearing any pending data in the write buffer.

See also:
disconnectFromServer(), and close().


connectToServer

public final void connectToServer(java.lang.String name,
                                  QIODevice.OpenModeFlag[] openMode)
This is an overloaded method provided for convenience.


connectToServer

public final void connectToServer(java.lang.String name)
Attempts to make a connection to name.

The socket is opened in the given openMode and first enters ConnectingState . It then attempts to connect to the address or addresses returned by the lookup. Finally, if a connection is established, QLocalSocket enters ConnectedState and emits connected() .

At any point, the socket can emit error() to signal that an error occurred.

See also state(), serverName(), and waitForConnected().


connectToServer

public final void connectToServer(java.lang.String name,
                                  QIODevice.OpenMode openMode)
Attempts to make a connection to name.

The socket is opened in the given openMode and first enters ConnectingState . It then attempts to connect to the address or addresses returned by the lookup. Finally, if a connection is established, QLocalSocket enters ConnectedState and emits connected() .

At any point, the socket can emit error() to signal that an error occurred.

See also state(), serverName(), and waitForConnected().


disconnectFromServer

public final void disconnectFromServer()
Attempts to close the socket. If there is pending data waiting to be written, QLocalSocket will enter ClosingState and wait until all data has been written. Eventually, it will enter UnconnectedState and emit the disconnectedFromServer() signal.

See also:
connectToServer().


error

public final QLocalSocket.LocalSocketError error()
Returns the type of error that last occurred.

See also:
state(), and errorString().


flush

public final boolean flush()
This function writes as much as possible from the internal write buffer to the socket, without blocking. If any data was written, this function returns true; otherwise false is returned.

Call this function if you need QLocalSocket to start sending buffered data immediately. The number of bytes successfully written depends on the operating system. In most cases, you do not need to call this function, because QLocalSocket will start sending data automatically once control goes back to the event loop. In the absence of an event loop, call waitForBytesWritten() instead.

See also:
write(), and waitForBytesWritten().


fullServerName

public final java.lang.String fullServerName()
Returns the server path that the socket is connected to.

Note: This is platform specific

See also:
connectToServer(), and serverName().


isValid

public final boolean isValid()
Returns true if the socket is valid and ready for use; otherwise returns false.

Note: The socket's state must be ConnectedState before reading and writing can occur.

See also:
state().


readBufferSize

public final long readBufferSize()
Returns the size of the internal read buffer. This limits the amount of data that the client can receive before you call read() or readAll(). A read buffer size of 0 (the default) means that the buffer has no size limit, ensuring that no data is lost.

See also:
setReadBufferSize(), and read().


serverName

public final java.lang.String serverName()
Returns the name of the peer as specified by connectToServer(), or an empty QString if connectToServer() has not been called or it failed.

See also:
connectToServer(), and fullServerName().


setReadBufferSize

public final void setReadBufferSize(long size)
Sets the size of QLocalSocket's internal read buffer to be size bytes.

If the buffer size is limited to a certain size, QLocalSocket won't buffer more than this size of data. Exceptionally, a buffer size of 0 means that the read buffer is unlimited and all incoming data is buffered. This is the default.

This option is useful if you only read the data at certain points in time (e.g., in a real-time streaming application) or if you want to protect your socket against receiving too much data, which may eventually cause your application to run out of memory.

See also:
readBufferSize(), and read().


setSocketDescriptor

public final boolean setSocketDescriptor(long socketDescriptor,
                                         QLocalSocket.LocalSocketState socketState,
                                         QIODevice.OpenModeFlag[] openMode)
This is an overloaded method provided for convenience.


setSocketDescriptor

public final boolean setSocketDescriptor(long socketDescriptor,
                                         QLocalSocket.LocalSocketState socketState)
Initializes QLocalSocket with the native socket descriptor socketDescriptor. Returns true if socketDescriptor is accepted as a valid socket descriptor; otherwise returns false. The socket is opened in the mode specified by openMode, and enters the socket state specified by socketState.

Note: It is not possible to initialize two local sockets with the same native socket descriptor.

See also:
socketDescriptor(), state(), and openMode().


setSocketDescriptor

public final boolean setSocketDescriptor(long socketDescriptor)
Initializes QLocalSocket with the native socket descriptor socketDescriptor. Returns true if socketDescriptor is accepted as a valid socket descriptor; otherwise returns false. The socket is opened in the mode specified by openMode, and enters the socket state specified by socketState.

Note: It is not possible to initialize two local sockets with the same native socket descriptor.

See also:
socketDescriptor(), state(), and openMode().


setSocketDescriptor

public final boolean setSocketDescriptor(long socketDescriptor,
                                         QLocalSocket.LocalSocketState socketState,
                                         QIODevice.OpenMode openMode)
Initializes QLocalSocket with the native socket descriptor socketDescriptor. Returns true if socketDescriptor is accepted as a valid socket descriptor; otherwise returns false. The socket is opened in the mode specified by openMode, and enters the socket state specified by socketState.

Note: It is not possible to initialize two local sockets with the same native socket descriptor.

See also:
socketDescriptor(), state(), and openMode().


socketDescriptor

public final long socketDescriptor()
Returns the native socket descriptor of the QLocalSocket object if this is available; otherwise returns -1.

The socket descriptor is not available when QLocalSocket is in UnconnectedState .

See also:
setSocketDescriptor().


state

public final QLocalSocket.LocalSocketState state()
Returns the state of the socket.

See also:
error().


waitForConnected

public final boolean waitForConnected()
Waits until the socket is connected, up to msec milliseconds. If the connection has been established, this function returns true; otherwise it returns false. In the case where it returns false, you can call error() to determine the cause of the error.

The following example waits up to one second for a connection to be established:

        socket.connectToServer("market");
        if (socket.waitForConnected(1000))
            System.out.println("Connected!");
If msecs is -1, this function will not time out.

See also:
connectToServer(), and connected() .


waitForConnected

public final boolean waitForConnected(int msecs)
Waits until the socket is connected, up to msec milliseconds. If the connection has been established, this function returns true; otherwise it returns false. In the case where it returns false, you can call error() to determine the cause of the error.

The following example waits up to one second for a connection to be established:

        socket.connectToServer("market");
        if (socket.waitForConnected(1000))
            System.out.println("Connected!");
If msecs is -1, this function will not time out.

See also:
connectToServer(), and connected() .


waitForDisconnected

public final boolean waitForDisconnected()
Waits until the socket has disconnected, up to msecs milliseconds. If the connection has been disconnected, this function returns true; otherwise it returns false. In the case where it returns false, you can call error() to determine the cause of the error.

The following example waits up to one second for a connection to be closed:

        socket.disconnectFromServer();
        if (socket.waitForDisconnected(1000))
            System.out.println("Disconnected!");
If msecs is -1, this function will not time out.

See also:
disconnectFromServer(), and close().


waitForDisconnected

public final boolean waitForDisconnected(int msecs)
Waits until the socket has disconnected, up to msecs milliseconds. If the connection has been disconnected, this function returns true; otherwise it returns false. In the case where it returns false, you can call error() to determine the cause of the error.

The following example waits up to one second for a connection to be closed:

        socket.disconnectFromServer();
        if (socket.waitForDisconnected(1000))
            System.out.println("Disconnected!");
If msecs is -1, this function will not time out.

See also:
disconnectFromServer(), and close().