Home · All Classes · Grouped Classes · Annotated · Functions

QObexPushClient Class Reference

The QObexPushClient class encapsulates an OBEX PUSH client. More...

    #include <QObexPushClient>

Inherits QObject.

Public Types

Public Functions

Public Slots

Signals

Additional Inherited Members


Detailed Description

The QObexPushClient class encapsulates an OBEX PUSH client.

The QObexPushClient class can be used to send files to an OBEX Push server. The file sent can either be a business card (vCard), calendar (vCal), or any other file type. This class can also be used to request a business card, or perform a business card exchange.

Here is an example of using QObexPushClient to send a file over a Bluetooth connection:

    // Connect to an RFCOMM server
    QBluetoothRfcommSocket *rfcommSocket = new QBluetoothRfcommSocket;
    if (rfcommSocket->connect("11:22:33:aa:bb:cc", 9)) {

        QObexPushClient *sender = new QObexPushClient(rfcommSocket);
        sender->connect();
        QByteArray data = getSomeData();
        sender->send(data, "MyData.txt");
        sender->disconnect();
    }

The functions connect(), disconnect(), send(), sendBusinessCard(), requestBusinessCard() and exchangeBusinessCard() are all asynchronous. When called, they return immediately, returning a unique identifier for that particular operation. If the command cannot be performed immediately because another command is in progress, the command is scheduled for later execution.

When the execution of a command starts, the commandStarted() signal is emitted with the identifier of the command. When it is finished, the commandFinished() signal is emitted with the identifier and also a bool to indicate whether the command finished with an error.

The done() signal is emitted when all pending commands have finished. This can be used to automatically delete the client object when it has finished its operations, by connecting the client's done() signal to the client's QObject::deleteLater() slot. (The QIODevice object can similarly be connected to automatically delete it when the client has finished.)

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. In this case, the done() signal is emitted with the error argument set to true.

Handling socket disconnections

You should ensure that the QIODevice provided in the constructor emits QIODevice::aboutToClose() or QObject::destroyed() when the associated transport connection is disconnected. If one of these signals are emitted while a command is in progress, QObexPushClient will know the transport connection has been lost, and will emit commandFinished() with error set to true, and error() will return ConnectionError.

This is particularly an issue for socket classes such as QTcpSocket that do not emit QIODevice::aboutToClose() when a disconnected() signal is emitted. In these cases, QObexPushClient will not know that the transport has been disconnected. To avoid this, you can make the socket emit QIODevice::aboutToClose() when it is disconnected:

    // make the socket emit aboutToClose() when disconnected() is emitted
    QObject::connect(socket, SIGNAL(disconnected()), socket, SIGNAL(aboutToClose()));

Or, if the socket can be discarded as soon as it is disconnected:

    // delete the socket when the transport is disconnected
    QObject::connect(socket, SIGNAL(disconnected()), socket, SLOT(deleteLater()));

See also QObexPushService and QObexClientSession.


Member Type Documentation

enum QObexPushClient::Command

Defines the commands that may be returned from currentCommand() to indicate the command that is being executed.

ConstantValueDescription
QObexPushClient::None0No command is being executed.
QObexPushClient::Connect1connect() is being executed.
QObexPushClient::Disconnect2disconnect() is being executed.
QObexPushClient::Send3send() is being executed.
QObexPushClient::SendBusinessCard4sendBusinessCard() is being executed.
QObexPushClient::RequestBusinessCard5requestBusinessCard() is being executed.

enum QObexPushClient::Error

Defines the possible errors for a push client.

ConstantValueDescription
QObexPushClient::NoError0No error has occurred.
QObexPushClient::ConnectionError1The 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.
QObexPushClient::RequestFailed2The client's request was refused by the remote service, or an error occurred while sending the request.
QObexPushClient::Aborted3The command was aborted by a call to abort().
QObexPushClient::UnknownError100An error other than those specified above occurred.


Member Function Documentation

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

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

The device should already be opened, or else commands will fail with ConnectionError.

QObexPushClient::~QObexPushClient ()   [virtual]

Destroys the client.

void QObexPushClient::abort ()   [slot]

Aborts the current file transfer operation and deletes all scheduled commands.

If there is a file transfer operation in progress, an Abort command will be sent to the server. When the server replies that the command is aborted, the commandFinished() signal will be emitted with the error argument set to true, and the error() function will return QObexPushClient::Aborted.

If there is no file transfer operation in progress, or the operation finishes before it can be aborted, the operation will be completed normally and the error argument for the commandFinished() signal will be set to false.

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

void QObexPushClient::clearPendingCommands ()

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

See also hasPendingCommands(), currentId(), currentCommand(), and abort().

void QObexPushClient::commandFinished ( int id, bool error )   [signal]

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

Note: Some OBEX Push services close the transport connection as soon as a file transfer operation is completed. In this case, if an OBEX Push client sends a file transfer request and then sends a disconnect() request, the disconnect() request will fail as the transport connection is no longer available.

See also commandStarted() and currentId().

void QObexPushClient::commandStarted ( int id )   [signal]

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

See also commandFinished() and currentId().

int QObexPushClient::connect ()

Sends a Connect command to the OBEX server to initiate the OBEX session.

This function returns immediately. It will be executed asynchronously, and the unique identifier that is returned from this function can be used to track the the status of the command through the currentId() function and the commandStarted() and commandFinished() signals.

See also disconnect().

Command QObexPushClient::currentCommand () const

Returns the command that is being executed, or QObexPushClient::None if there is no command being executed.

See also currentId().

int QObexPushClient::currentId () const

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

See also currentCommand() and hasPendingCommands().

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

This signal is emitted during file transfer operations 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 QObexPushClient::disconnect ()

Sends a Disconnect command to the OBEX server to close the OBEX session.

This function returns immediately. It will be executed asynchronously, and the unique identifier that is returned from this function can be used to track the the status of the command through the currentId() function and the commandStarted() and commandFinished() signals.

Note: Some OBEX Push services close the transport connection as soon as a file transfer operation is completed. In this case, if an OBEX Push client sends a file transfer request and then sends a disconnect() request, the disconnect() request will fail as the transport connection is no longer available.

See also connect().

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

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

Error QObexPushClient::error () const

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

If you start a new command, the error status is reset to NoError.

void QObexPushClient::exchangeBusinessCard ( QIODevice * mine, QIODevice * theirs, int * putId = 0, int * getId = 0 )

Performs a business card exchange operation by sending this client's business card, given by mine, and then requesting a business card from the remote device, which will be stored in theirs.

The putId will be set to the unique identifier for the Put command that is executed when the client's business card is sent. The getId will be set to the unique identifier for Get command that is executed when the client requests the business card from the server.

Note that this method is equivalent to calling the sendBusinessCard() method and then calling the requestBusinessCard() method.

bool QObexPushClient::hasPendingCommands () const

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

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

See also clearPendingCommands(), currentId(), and currentCommand().

QObex::ResponseCode QObexPushClient::lastCommandResponse () const

Returns the server's response code for the last completed command.

int QObexPushClient::requestBusinessCard ( QIODevice * vcard )

Requests a business card from the OBEX server. The received contents will be stored in vcard.

int QObexPushClient::send ( QIODevice * device, const QString & name, const QString & type = QString(), const QString & description = QString() )

Sends the contents of device to the OBEX server, using the given name, type and description to describe the contents to the server. If a given name, type or description value is a null string, that value will not be used in the request.

This function returns immediately. It will be executed asynchronously, and the unique identifier that is returned from this function can be used to track the the status of the command through the currentId() function and the commandStarted() and commandFinished() signals.

int QObexPushClient::send ( const QByteArray & array, const QString & name, const QString & type = QString(), const QString & description = QString() )

This is an overloaded member function, provided for convenience.

This convenience function sends the contents of array to the OBEX server, using name, type and description to describe the contents to the server. If a given name, type or description value is a null string, that value will not be used in the request.

int QObexPushClient::sendBusinessCard ( QIODevice * vcard )

Sends the business card stored in vcard to the OBEX server.

QIODevice * QObexPushClient::sessionDevice () const

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


Copyright © 2008 Nokia Trademarks
Qtopia 4.3.3