/*!

    \class XQServiceRequest_Private

    \inpublicgroup QtBaseModule

    \ingroup ipc

    \brief Private implementation of the XQServiceRequest.

*/

    \class XQServiceRequest

    \inpublicgroup QtBaseModule

    \ingroup ipc

    \brief Allows applications to request services from other applications.

    The XQServiceRequest class allows applications to request services from other applications.

    A XQServiceRequest encapsulates a service name and the message to be sent to that service.

    \note One should be using XQApplicationManager and the related XQAiwRequest instead of XQServiceRequest.

          The XQApplicationManager and related classes encapsulate basic, target-architecture approved

          support for out-of-process Application Interworking, e.g. support for launching URLs

          (including activity URLs), normal files, sharable files, etc. (whatever needed).

    \b Examples: \n

    How to create synchronous request without parameters and return value? 

    \note The full name (yourservice.Interface) need to be used (with dot (.) between service name and interface name).

    \code

        XQServiceRequest request("yourservice.<b>Interface</b>", "functionName1()");

        bool res = request.send();

        if  (!res) {

            int error = request.latestError();

        }

    \endcode

    How to create synchronous request with several parameters and return value?

    \code

        QString parameter1("+3581234567890");

        int parameter2 = 3;

        XQServiceRequest request("yourservice.<b>Interface</b>", "functionName2(QString, int)");

        request << parameter1;

        request << parameter2;

        int returnvalue;

        bool res = request.send(returnvalue);

        if  (!res) {

            int error = request.latestError();

        }

    \endcode

    How to create asynchronous request without return value?

    \code

        QString parameter1("+3581234567890");

        int parameter2 = 3;

        XQServiceRequest request("yourservice.Interface", "functionName2(QString, int)", false);

        request << parameter1;

        request << parameter2;

        bool res = request.send();

        if (!res) {

            int error = request.latestError();

        }

    \endcode

    How to create asynchronous request with return value?

    \code

        QString parameter1("+3581234567890");

        int parameter2 = 3;

        XQServiceRequest request("yourservice.Interface", "functionName2(QString, int)", false);

        request << parameter1;

        request << parameter2;

        connect(request, SIGNAL(requestCompleted(QVariant)), this, SLOT(requestCompleted(QVariant)));

        bool res = request.send();

        if (!res) {

            int error = request.latestError();

        }

        ...

        void requestCompleted(const QVariant& value)

        {

            int returnvalue = value.toInt();

        }

    \endcode

    How to use declare custom type?

    Header:

    \code

        class CustomType 

        { 

        public: 

            CustomType (){}; 

            virtual ~CustomType(){};

            QString mString1; 

            QString mString2; 

            QUuid mUid;

            template <typename Stream> void serialize(Stream &stream) const; 

            template <typename Stream> void deserialize(Stream &stream); 

        };

        Q_DECLARE_USER_METATYPE(CustomType)

    \endcode

    Implementation:

    \code        

        template <typename Stream> void CustomType::serialize(Stream &s) const 

            { 

            s << mString1; 

            s << mString2; 

            s << mUid; 

            }

        template <typename Stream> void CustomType::deserialize(Stream &s) 

            { 

            s >> mString1; 

            s >> mString2; 

            s >> mUid; 

            }

        Q_IMPLEMENT_USER_METATYPE(CustomType)

    \endcode

    How to declare custom type that doesn't need data stream operators?

    Header:

    \code

        typedef QList<CustomType> CustomTypeList;

        Q_DECLARE_USER_METATYPE_NO_OPERATORS(CustomTypeList)

    \endcode

    Implementation:

    \code

        Q_IMPLEMENT_USER_METATYPE_NO_OPERATORS(CustomTypeList)

    \endcode

*/

/*!

    \fn bool XQServiceRequest::send(T& retValue)

    Sends the request. If the request is synchronous, then client is blocked

    until service provider completes the request or request fails for some reason.

    If the request is asynchronous, then client won't be blocked.

    \param retValue Defines refence to a value service provider will return after service.

    \return False if there was no application that could service the request, otherwise true.

*/

/*!

    \fn XQServiceRequest &XQServiceRequest::operator<< (const T &var)

    Adds \a var to the list of arguments for this service request.

    \param var Defines the argument value to add to the list of arguments.

*/

/*!

    \fn XQServiceRequest &XQServiceRequest::operator<< (const char *var)

    Adds \a var to the list of arguments for this service request.

    \param var Defines the argument value to add to the list of arguments.

*/

/*!

    \fn void XQServiceRequest::requestCompleted(const QVariant& value)

    This signal is emitted when service provider returns a return value asynchronously back to the client.

    \param value Result of the request.

*/

/*!

    \fn void XQServiceRequest::requestError(int err);

    This signal is emitted when error has happened in request handling.

    \param err Error code as integer value.

    \sa XQService::ServiceIPCErrors

*/

/*!

    \fn void XQServiceRequest::addVariantArg(const QVariant& var)

    Adds the variant value to the list of arguments, so that the variant's

    value is serialized in send() rather than the variant itself.

    \param var Value to be added to the list of arguments.

*/

/*!

    Construct a null service request.

    setService() and setMessage() must be called before send(), but the

    service may be written prior to the calls.

    Construct a service request that will send \a message to

    a \a service when send() is called. The service may be written

    prior to the calls.

    \param service Defines the full service name to send message. The full name is:

                   - The name of the service in the service configuration file

                   - Character *.* (dot)

                   - The name of the interface from the service XML.

    \param message Defines the message to send to the service provider i.e. it is

                 the signature of the service provider function to be called.

    \param synchronous Defines should message be sent synchronously or asynchronously.

                     By default message is sent synchronously.

    Copy constructor. Any data previously written to the \a orig

    service will be in the copy.

    \param orig XQServiceRequest from which data will be copied to this object.

    Construct a service request by service descriptor which contains exact details of the service and interface.

    The service may be written prior to the calls.

    \param descriptor Defines details of the service and it's interface.

    \param message Message to be sent when send() is called.

    \param synchronous Defines should message be sent synchronously or asynchronously.

                       By default message is sent synchronously.

    Assignment operator.

    Any data previously written to the \a orig

    service will be in the copy.

    Destroys the service request. Unlike QtopiaIpcEnvelope, the

    request is not automatically sent.

    Checks if request is NULL.

    \return True if either the service() or message() is not set.

    \sa service(), message()

/*!

    Checks if request is synchronous or asynchronous.

    \return True if request is synchronous, false if request is asynchronous.

    \sa setSynchronous()

 */

/*!

    Sets request to be synchronous or asynchronous.

    \param synchronous If set to true, request will be synchronous.

                       If set to false, request will be asynchronous.

    \sa isSynchronous()

 */

    Sends the request. If the request is synchronous, then client is blocked

    until service provider completes the request or request fails for some reason.

    If the request is asynchronous, then client won't be blocked. If the request

    is asynchronous and clients wants to receive a return value from the service

    provider, then clients should connect to the requestCompleted() signal.

    \return False if there was no application that could service the request, otherwise true.

    Sends the request. If the request is synchronous, then client is blocked

    until service provider completes the request or request fails for some reason.

    If the request is asynchronous, then client won't be blocked.

    \param retData Defines refence to a value service provider will return after service.

    \return False if there was no application that could service the request, otherwise true.

    Sets the full name of the service to which the request will be sent.

    \param fullServiceName Full name of the service to send message to. See

                           XQServiceRequest(const QString& service, const QString& message, const bool &synchronous)

                           for the full name definition.

    \sa service()

    Gets the service name to which this request will be sent.

    \return Full service name to which request will be sent.

    \sa setService()