QObexClientSession Class Reference
[QtBaseModule]

Multiplexing and Connection IDs

The Connection Id header is used when multiplexing OBEX connections over a single transport connection. If an OBEX server includes a Connection Id header in a response to a Connect request, the ID will be retained and the client will automatically include it in the OBEX headers for all future requests. You do not need to track and send the Connection Id yourself. The ID can be retrieved using connectionId().

Note that the Connection Id will not be automatically added if a request already contains a Target header, as a request cannot have both of these headers at the same time. (If it did, the server would be unsure as to whether the client was establishing a new directed connection or using an existing connection.)

See also QObexServerSession and Simple OBEX Demo.

Member Type Documentation

enum QObexClientSession::Error

The errors that may occur for an OBEX client.

Member Function Documentation

QObexClientSession::QObexClientSession ( QIODevice * device, QObject * parent = 0 )

Constructs an OBEX client session that uses device for the transport connection. The parent is the QObject parent.

The device must be opened in order to perform client requests. Otherwise, requests will fail with the QObexClientSession::ConnectionError error.

QObexClientSession::~QObexClientSession ()   [virtual]

Destroys the client.

void QObexClientSession::abort ()   [slot]

Aborts the current request and deletes all scheduled requests.

If there is an unfinished request, the client will send an Abort request to the server. Once the server replies to the request, the requestFinished() signal will be emitted with the error argument set to true, and the error() function will return QObexClientSession::Aborted if the server accepted the Abort request. If the request was refused, error() will return QObexClientSession::ConnectionError and the client should disconnect as it is no longer synchronized with the server.

Due to timing issues, the client may not be able to send the Abort immediately. If the request finishes before it can be aborted, the request will be completed normally and the requestFinished() error argument will be false.

If no other requests are started after the call to abort(), there will be no scheduled requests and the done() signal will be emitted.

void QObexClientSession::authenticationRequired ( QObexAuthenticationChallenge * challenge )   [signal]

This signal is emitted when the server requires the client to authenticate itself before proceeding with the current request.

The challenge provides the details of the authentication challenge sent by the server. The challenge object can then be filled in with the username and password that should be sent back to the server in order to authenticate this client.

If the server rejects the authentication details provided in challenge, the requestFinished() signal will be emitted with the error argument set to true, and the error() function will return QObexClientSession::AuthenticationFailed.

Note: It is not possible to use a QueuedConnection to connect to this signal, as the request will fail if the challenge has not been filled in with new information when the signal returns.

void QObexClientSession::authenticationResponse ( const QObexAuthenticationResponse & response, bool * accept )   [signal]

This signal is emitted when the client has previously issued an authentication challenge to indicate that the server must authenticate itself before proceeding with the current request, and the server has now responded with an authentication response containing a username and password for authentication.

Set accept to true if the authentication details in response are correct. If accept is set to true, the request will continue. Otherwise, the requestFinished() signal will be emitted with the error argument set to true, and the error() function will return QObexClientSession::AuthenticationFailed.

To issue an authentication challenge to the server, send a request with a QObexHeader object that includes an authentication challenge (by calling QObexHeader::setAuthenticationChallenge()).

Note: It is not possible to use a QueuedConnection to connect to this signal, as accept will automatically be set to false if its value has not been set when the signal returns.

qint64 QObexClientSession::bytesAvailable () const

Returns the number of bytes that can be read from read() or readAll() at the moment.

See also read(), readyRead(), readAll(), and get().

void QObexClientSession::clearPendingRequests ()

Deletes all pending requests from the list of scheduled requests. This does not affect the request that is being executed. If you want to stop this request as well, use abort().

See also hasPendingRequests() and currentId().

int QObexClientSession::connect ( const QObexHeader & header = QObexHeader() )

Initiates the OBEX session by sending a Connect request with the given header.

The function does not block and returns immediately. The request is scheduled, and executed asynchronously.

This function returns a unique identifier for the request. This identifier is passed by the requestStarted() signal when the request starts, and by the requestFinished() signal when the request is finished.

See also done().

quint32 QObexClientSession::connectionId () const

Returns the client's Connection Id, or 0 if it does not have a connection Id.

The Connection Id is used for directed OBEX connections. If the client sends a Connect request with a Target header, the OBEX server will include a Connection Id header in its response. In this case, the client will automatically send this Connection Id value in all future requests; you do not have to include the Connection Id header yourself.

The Connection Id will be reset following a Disconnect request.

See also hasConnectionId().

QIODevice * QObexClientSession::currentDevice () const

Returns the QIODevice pointer that is used as the data source or data target of the request currently in progress. Returns 0 if the current request does not use an IO device, or if there is no request in progress.

This function can be used to delete the QIODevice in a slot connected to the requestFinished() signal.

See also put() and get().

int QObexClientSession::currentId () const

Returns the identifier of the request that is being executed, or 0 if there is no request being executed.

See also currentRequest().

QObex::Request QObexClientSession::currentRequest () const

Returns the request that is being executed, or QObex::NoRequest if there is no request being executed.

See also currentId().

void QObexClientSession::dataTransferProgress ( qint64 done, qint64 total )   [signal]

This signal is emitted during file transfer requests to indicate the progress of the transfer. The done value is the number of bytes that have been sent or received so far, and total is the total number of bytes to be sent or received.

int QObexClientSession::disconnect ( const QObexHeader & header = QObexHeader() )

Signals the end of the OBEX session by sending a Disconnect request with the given header.

The function does not block and returns immediately. The request is scheduled, and executed asynchronously.

This function returns a unique identifier for the request. This identifier is passed by the requestStarted() signal when the request starts, and by the requestFinished() signal when the request is finished.

See also done().

void QObexClientSession::done ( bool error )   [signal]

This signal is emitted when all pending requests have finished; it is emitted after the requestFinished() signal for the last request. The error value is true if an error occurred during the processing of the request; otherwise error is false.

Warning: Do not delete a QObexClientSession instance while it is emitting this signal. If you need to delete it, call QObject::deleteLater() instead of using the delete keyword. (If you do this, you may have to store the instance as a QPointer if you need to check the validity of the pointer later on.)

Error QObexClientSession::error () const

Returns the last error that occurred. This is useful for finding out what happened when receiving an requestFinished() or done() signal that has the error argument set to true.

If you start a new request, the error status is reset to QObexClientSession::NoError.

See also errorString().

QString QObexClientSession::errorString () const

Returns a human-readable description of the last error that occurred.

The error string is reset when a new request is started.

See also error().

int QObexClientSession::get ( const QObexHeader & header, QIODevice * dev = 0 )

Retrieves a data object through a Get request with the given header.

If dev is not 0, the received data is written to dev. Make sure that the dev pointer is valid for the duration of the request; it is safe to delete it when the requestFinished() signal is emitted.

If dev is 0, the readyRead() signal is emitted when there is data available to be read. You can then read the data with read() or readAll().

The function does not block and returns immediately. The request is scheduled, and executed asynchronously.

This function returns a unique identifier for the request. This identifier is passed by the requestStarted() signal when the request starts, and by the requestFinished() signal when the request is finished.

See also done().

bool QObexClientSession::hasConnectionId () const

Returns whether the client has a Connection Id.

See also connectionId().

bool QObexClientSession::hasPendingRequests () const

Returns true if there are any requests scheduled that have not yet been executed; otherwise returns false.

The request that is being executed is not considered as a scheduled request.

See also clearPendingRequests() and currentId().

QObex::ResponseCode QObexClientSession::lastResponseCode () const

Returns the server response code for the most recently completed request.

This value is reset to QObex::Success when a new request is started.

QObexHeader QObexClientSession::lastResponseHeader () const

Returns the last response headers received from the server.

This value is reset when a new request is started.

See also responseHeaderReceived().

int QObexClientSession::put ( const QObexHeader & header, QIODevice * dev )

Sends a data object to the server through a Put request with the data from dev and the given header. The data is read in chunks from the QIODevice object, so this allows you to transmit large chunks of data without the need to read all the data into memory at once.

Make sure that the dev pointer is valid for the duration of the request; it is safe to delete it when the requestFinished() signal is emitted.

The progress of the data transfer is reported via the dataTransferProgress() signal.

The function does not block and returns immediately. The request is scheduled, and executed asynchronously.

This function returns a unique identifier for the request. This identifier is passed by the requestStarted() signal when the request starts, and by the requestFinished() signal when the request is finished.

See also dataTransferProgress(), putDelete(), and done().

int QObexClientSession::put ( const QObexHeader & header, const QByteArray & data )

This is an overloaded member function, provided for convenience.

Sends a data object to the server through a Put request with a copy of the data from data and the given header.

int QObexClientSession::putDelete ( const QObexHeader & header )

Deletes a file on the server through a Put-Delete request with the given header.

The function does not block and returns immediately. The request is scheduled, and executed asynchronously.

This function returns a unique identifier for the request. This identifier is passed by the requestStarted() signal when the request starts, and by the requestFinished() signal when the request is finished.

See also done().

qint64 QObexClientSession::read ( char * data, qint64 maxlen )

Reads maxlen bytes from the response content into data and returns the number of bytes read. Returns -1 if an error occurred.

See also readAll(), bytesAvailable(), readyRead(), and get().

QByteArray QObexClientSession::readAll ()

Reads all the bytes available from the data buffer and returns them.

See also read(), readyRead(), and get().

void QObexClientSession::readyRead ()   [signal]

This signal is emitted in response to a get() request when there is new data to read.

If you specify a device as the second argument in the get() request, this signal is not emitted; instead, the data is written directly to the device.

You can then read the data with the read() or readAll() functions.

This signal is useful if you want to process the data in chunks as soon as it becomes available. If you are only interested in the complete data, just connect to the requestFinished() signal and read the data then instead.

void QObexClientSession::requestFinished ( int id, bool error )   [signal]

This signal is emitted when the client has finished processing the request identified by id. The error value is true if an error occurred during the processing of the request; otherwise error is false.

Note: error is set to true if the server responded with a response code other than QObex::Success. In this case, error() will return QObexClientSession::RequestFailed, and lastResponseCode() will return the response code sent by the server.

Warning: Do not delete a QObexClientSession instance while it is emitting this signal. If you need to delete it, call QObject::deleteLater() instead of using the delete keyword. (If you do this, you may have to store the instance as a QPointer if you need to check the validity of the pointer later on.)

See also requestStarted(), currentId(), and currentRequest().

void QObexClientSession::requestStarted ( int id )   [signal]

This signal is emitted when the client has started processing the request identified by id.

See also requestFinished(), currentId(), and currentRequest().

void QObexClientSession::responseHeaderReceived ( const QObexHeader & header )   [signal]

This signal is emitted when a response header is received. The header contains the header data that was received.

QIODevice * QObexClientSession::sessionDevice () const

Returns the device used for this client session, as provided in the constructor.

int QObexClientSession::setPath ( const QObexHeader & header, QObex::SetPathFlags flags = 0 )

Sets the remote path on the server through a SetPath reqest with the specified flags and the given header.

The function does not block and returns immediately. The request is scheduled, and executed asynchronously.

This function returns a unique identifier for the request. This identifier is passed by the requestStarted() signal when the request starts, and by the requestFinished() signal when the request is finished.

See also done().