|
Home · All Namespaces · All Classes · Grouped Classes · Modules · Functions | |
The QObexClientSession class provides an implementation of the client side of the OBEX protocol. More...
#include <QObexClientSession>
Inherits QObject.
The QObexClientSession class provides an implementation of the client side of the OBEX protocol.
A QObexClientSession can be used over any type of transport that is accessible through a subclass of QIODevice. For example, QBluetoothRfcommSocket, QIrSocket and QTcpSocket are all subclasses of QIODevice, and objects of these subclasses can passed to the QObexClientSession constructor to run an OBEX client over RFCOMM, IrDA or TCP, respectively.
QObexClientSession performs OBEX requests asynchronously and depends on the presence of a running event loop.
The QObexClientSession class can be used to execute the standard OBEX requests: Connect, Disconnect, Put, Put-Delete, Get and SetPath. These requests are available through the connect(), disconnect(), put(), putDelete(), get() and setPath() functions, respectively.
All requests are performed asynchronously. These functions do not block; instead, they schedule requests for later execution, and return immediately. Each function returns a unique identifier for the scheduled request that can be used to track the request's progress by connecting to signals of interest such as requestStarted() and requestFinished(). The currentId() function can also be used to determine the request that is currently executed.
The use of scheduled requests allows the execution of a sequence of commands. For example, this code will connect to an OBEX server running on a particular Bluetooth device, download a file, and then disconnect:
QBluetoothRfcommSocket *rfcommSocket = new QBluetoothRfcommSocket;
rfcommSocket->connect("11:22:33:aa:bb:cc", 10);
QObexClientSession *client = new QObexClientSession(rfcommSocket);
client->connect();
QObexHeader header;
header.setName("SomeFile.txt");
client->get(header);
client->disconnect();
When the last scheduled request has finished, a done() signal is emitted with a bool argument that indicates whether the sequence of requests finished with an error.
As an example, the code example above will produce a sequence of signals similar to this:
requestStarted(1)
responseHeaderReceived(responseHeader)
requestFinished(1, false)
requestStarted(2)
responseHeaderReceived(responseHeader)
dataTransferProgress(962, 2415)
readyRead()
dataTransferProgress(1980, 2415)
readyRead()
dataTransferProgress(2415, 2415)
readyRead()
requestFinished(2, false)
requestStarted(3)
responseHeaderReceived(responseHeader)
requestFinished(3, false)
done(false)
The readyRead() signal tells you that there is data ready to be read following a Get request. The amount of data can then be queried with the bytesAvailable() function and it can be read with the read() or readAll() functions.
If an error occurs during the execution of one of the commands in a sequence of commands, all the pending commands (i.e. scheduled, but not yet executed commands) are cleared and no signals are emitted for them.
For example, if the Get request in the above example code fails because the server responded with a response code other than QObex::Success, the Disconnect request would not be executed, and the sequence of signals would look like this instead:
requestStarted(1)
responseHeaderReceived(responseHeader)
requestFinished(1, false)
requestStarted(2)
requestFinished(2, true)
done(true)
You can then get details about the error with the error() function.
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.
The errors that may occur for an OBEX client.
| Constant | Value | Description |
|---|---|---|
| QObexClientSession::NoError | 0 | No error has occurred. |
| QObexClientSession::ConnectionError | 1 | The client is unable to send data, or the client-server communication process is otherwise disrupted. In this case, the client and server are no longer synchronized with each other, so the QIODevice provided in the constructor should not be used for any more OBEX requests. |
| QObexClientSession::RequestFailed | 2 | The request was refused by the server (i.e. the server responded with a response code other than QObex::Success). |
| QObexClientSession::InvalidRequest | 3 | The client request is invalid. |
| QObexClientSession::InvalidResponse | 4 | The server sent an invalid or unreadable response. |
| QObexClientSession::Aborted | 5 | The request was aborted by a call to abort(). |
| QObexClientSession::AuthenticationFailed | 6 | The request failed because the client or server could not be authenticated. |
| QObexClientSession::UnknownError | 100 | An error other than those specified above occurred. |
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.
Destroys the client.
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.
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.
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.
Returns the number of bytes that can be read from read() or readAll() at the moment.
See also read(), readyRead(), readAll(), and get().
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().
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().
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().
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.
Returns the identifier of the request that is being executed, or 0 if there is no request being executed.
See also currentRequest().
Returns the request that is being executed, or QObex::NoRequest if there is no request being executed.
See also currentId().
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.
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().
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.)
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().
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().
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().
Returns whether the client has a Connection Id.
See also connectionId().
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().
Returns the server response code for the most recently completed request.
This value is reset to QObex::Success when a new request is started.
Returns the last response headers received from the server.
This value is reset when a new request is started.
See also responseHeaderReceived().
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().
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.
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().
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().
Reads all the bytes available from the data buffer and returns them.
See also read(), readyRead(), and get().
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.
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().
This signal is emitted when the client has started processing the request identified by id.
See also requestFinished(), currentId(), and currentRequest().
This signal is emitted when a response header is received. The header contains the header data that was received.
Returns the device used for this client session, as provided in the constructor.
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().
| Copyright © 2009 Nokia | Trademarks | Qt Extended 4.4.3 |