\class ServiceAdaptorProxy

    \brief Proxy class for converting signal and slot members into IPC message names

/*!

    \class XQServiceProvider_Private

    \inpublicgroup QtBaseModule

    \brief Private implementation of XQServiceProvider

*/

/*!

    \class XQServiceProvider

    \inpublicgroup QtBaseModule

    \brief The XQServiceProvider class provides an interface to messages on a XQService service

    which simplifies remote slot invocations

    Service messages consist of a service name, a message name, and a list of parameter values.

    Qt extension dispatches service messages to the applications associated with the service

    name, on the application's \c{QPE/Application/appname} channel, where

    \c{appname} is the application's name.

    <b>Service registration</b> \n

    Service provider need to register it's service into the system before they can be used by

    the service client. Registration is done by creating a XML formatted service configuration

    file and defining the service in the provider's .pro-file. QMake will notice service provider

    from the .pro-file, with help of the service.prf file, and generate a make file that uses

    a helper application xqsreg.exe. The helper application sqsreg.exe will generate an application

    registration resource file ( _reg.rss) from the configuration-file and provider's definitions

    that include the needed declarations for the services provided.

    <b>Service Names Allocation</b> \n

    The harmonize service and interface names the Symba specific names and guidelines can be found

    from http://s60wiki.nokia.com/S60Wiki/QtFw_for_S60_coding_conventions/Service_name_registry#Service.

    Before implementing a service you need to allocate the name according to the guidelines. Please

    inform intended service clients (customers) and matti.parnanen@nokia.com.

    <b>Service Configuration File</b> \n

    All the service configuration are added to the run-time service registry to make them available

    for service discovery and creating service requests.

    \note Only one service element with multiple interface is supported!

    To support services a new configuration was introduced to qmake and two new variables for

    that configuration:

    \code

        CONFIG = service

        service.file = <service configuration file path>

        service.options = <embeddable> (optional, default not embeddable), <hidden> (optional, default not hidden) 

    \endcode

    The fornat of the service configuration file is same as XML format used in Qt Service Framework.

    Example configuration file:

    \code

        <?xml version="1.0" encoding="utf-8" ?>

        <service>

            <name>Music Fetcher</name>

            <filepath>No path</filepath>

            <description>Music Fetcher</description>

            <interface>

                <name><b>com.nokia.symbian.IMusicFetch</b></name>

                <version>1.0</version>

                <description>Interface for fetching music files</description>

            </interface>

        </service>

    \endcode

    \code

        <ELEMENT service ( name, filepath, description?, interface+ ) >

        <ELEMENT description ( #CDATA ) >

        <ELEMENT filepath ( #PCDATA ) >

        <ELEMENT interface ( '''name''', version, description?, capabilities?, customproperty* ) >

        <ELEMENT capabilities ( #PCDATA ) >

        <ELEMENT name ( #PCDATA ) >

        <ELEMENT version ( #PCDATA ) >

        <ELEMENT customproperty ( #CDATA ) >

        <ATTLIST customproperty key NMTOKEN #REQUIRED >

    \endcode

    Also the old format described below is supported, With old format you can not have custom properties, which

    for example are used for AIW purposes.

    \code

        <ELEMENT service ( description?, interface+ ) >

        <ATTLIST service name #CDATA  #REQUIRED >

        <ATTLIST service filepath #CDATA  #REQUIRED >

        <ELEMENT description ( #CDATA ) >

        <ELEMENT interface ( description? ) >

        <ATTLIST interface '''name''' #CDATA  #REQUIRED >

        <ATTLIST interface version #CDATA  #REQUIRED >

        <ATTLIST interface capabilities #CDATA  #REQUIRED >

    \endcode

    <b>Changing service or interface names</b> \n

    Before you think about changing the name of the already released and used service implementation, read this

    http://s60wiki.nokia.com/S60Wiki/QtFw_for_S60_coding_conventions/Service_name_registry#About_changing_service_or_interface_names

    first.

    The basic message is the service name, interface name and operation (message) slot signatures for the API. And for API changes you have to apply development time API deprecation process.

    <b>Service Registration tools</b> \n

    The needed utility files for service registration:

    - xqsreg.exe should be in \epoc32\tools or some other directory that can be found from the path

    - service.prf should be in \epoc32\tools\qt\mkspecs\features\symbian directory.

    If necessary you can copy those files to target directories from qthighway/bin.

    Sources for the xqsreg.exe can be found from the qthighway\xqsreg and it is also possible to compile it.

        - cd \qthighway\xqsreg

        - qmake -platform win32-mwc

        - make

    Usage: \n

    How to create a simple synchronously working service provider?

    \code

        class YourService : public XQServiceProvider

            {

            Q_OBJECT

            public:

                YourService ( ServiceApp *parent = 0 );

                ~YourService ();

            public slots:

                void functionName1(); 

                int functionName2(const QString& number, int times);

            private:

                ServiceApp *mServiceApp;

            };

    \endcode

    Implementation:

    \code

        YourService::YourService(ServiceApp* parent) 

        : XQServiceProvider(QLatin1String("yourservice.Interface"), parent), mServiceApp(parent)

            {

            publishAll();

            }

        YourService::~YourService() { } 

        void YourService::functionName1() { } 

        int YourService::functionName2(const QString& number, int times)

            {

            int returnValue = 1;

            return returnValue;

            }

    \endcode

    Additions to .pro-file:

    \code

        CONFIG += service

        SERVICE.FILE = service_conf.xml

        SERVICE.OPTIONS = embeddable

        SERVICE.OPTIONS += hidden

    \endcode

    Service configuration file (service_conf.xml):

    \code

    <?xml version="1.0" encoding="utf-8" ?>

    <service>

        <name>yourservice</name>

        <filepath>No path</filepath>

        <description>Service description</description>

        <interface>

            <name>Interface</name>

            <version>1.0</version>

            <description>Interface description</description>

        </interface>

    </service>

    \endcode

    How to create a simple asynchronously working service provider?

    Header:

    \code

        class YourService : public XQServiceProvider

        {

        Q_OBJECT

        public:

            YourService ( ServiceApp *parent = 0 );

            ~YourService ();

            void compleAsyncFunction();

        public slots:

            void functionName1(); 

            int functionName2(const QString& number, int times);

        private:

            ServiceApp *mServiceApp;

            int mAsyncRequestIndex;

            QVariant mReturnValue;

        };

    \endcode

    Implementation:

    \code

        YourService::YourService(ServiceApp* parent) 

        : XQServiceProvider(QLatin1String("yourservice.Interface"), parent), mServiceApp(parent)

            {

            publishAll();

            }

        YourService::~YourService() { } 

        void YourService::compleAsyncFunction()

            {

            completeRequest(mAsyncRequestIndex, mReturnValue);

            }

        void YourService::functionName1() 

            { 

            mAsyncRequestIndex = setCurrentRequestAsync();

            mReturnValue.setValue(0);

            } 

        int YourService::functionName2(const QString& number, int times)

            {

            mAsyncRequestIndex = setCurrentRequestAsync();

            mReturnValue.setValue(1);

            return mReturnValue.toInt();

            }

    \endcode

    <b>Examples:</b> \n

    The use of XQServiceProvider will be demonstrated using the \c{Time}

    service.  This has a single message called \c{editTime()} which asks

    the service to pop up a dialog allowing the user to edit the current time.

    \code

    class TimeService : public XQServiceProvider

    {

        Q_OBJECT

    public:

        TimeService( QObject *parent = 0 );

    public slots:

        void editTime(QTime time);

    };

    TimeService::TimeService( QObject *parent )

        : XQServiceProvider( "Time", parent )

    {

        publishAll();

    }

    \endcode

    The call to publishAll() causes all public slots within \c{TimeService}

    to be automatically registered as Service messages.  This can be

    useful if the service has many message types.

    The client can send a request to the service using QtopiaServiceRequest:

    \code

    XQServiceRequest req( "Time", "editTime()" );

    req << QTime::currentTime();

    req.send();

    \endcode

    <b>URI viewer</b> \n

    This is a simple example for implementing out-of-process scheme handlers.

    - "http", "https" and are handled via standard QDesktopServices::openUrl() function. 

       This is fire-and-forget launch. The options are ignored and no control and signals available after the launch.

    - "appto" is routed to Activity Manager for opening the attached activity.

      This is fire-and-forget launch. The options are ignored and no control and signals available after the launch.

    - The "file" scheme is handled as the QFile based create below. 

      So the com.nokia.symbian.IFileView interface is applied as for the QFile.

    Service application needs to publish support for:

    - The common interface "com.nokia.symbian.IUriView", and

    - The scheme(s), like "testo" in the example below. The custom custom property "schemes" contains one or more schemes as comma separated list (CSV)

    - The slot "view(QString)" to view the URI

    \code

        <?xml version="1.0" encoding="utf-8" ?>

        <service>

          <name>serviceapp</name>

          <filepath>No path</filepath>

          <description>Test service</description>

          <interface>

             <name>com.nokia.symbian.IUriView</name>

             <version>1.0</version>

             <description>Interface for showing URIs</description>

             <customproperty key="schemes">testto</customproperty>

           </interface>

        </service>

    \endcode

    An service application that offers support for a scheme implements the common "UriService" with the pre-defined "view" slot:

    \code

        class UriService : public XQServiceProvider

        {

            Q_OBJECT

            public:

                UriService( ServiceApp *parent = 0 );

                ~UriService();

                bool asyncAnswer() {return mAsyncAnswer;}

                void complete(bool ok);

            public slots:

                bool view(const QString& uri);

            private slots:

                void handleClientDisconnect();

            private:

                ServiceApp* mServiceApp;

                bool mAsyncAnswer;

                int mAsyncReqId;

                bool mRetValue;

        };

    \endcode

    Client application accesses the service via the URI:

    \code

        // Assume in example we have own scheme "testo" but this can be applied to 

        // "mailto", etc. standard schemes.

        //

        // (As mentioned in the documentation, some schemes are CURRENTLY handled specially,

        // like "http" scheme uses QDesktopServices::openUrl).  

        // 

        QUrl url("testto://authority?param1=value1&param1=value2"); 

        // The difference to the previous example is is how request is created

        // via application mgr.

        request = mAiwMgr.create(url);

        if (request == NULL)

        {

            // No handlers for the URI

            return;

         }

        // Set function parameters

        QList<QVariant> args;

        args << uri.toSring();

        request->setArguments(args);

        // Send the request

        bool res = request.send();

        if  (!res) 

        {

            // Request failed. 

            int error = request->lastError();

            // Handle error

        }

        // If making multiple requests to same service, you can save the request as member variable

        // In this example all done.

        delete request;

    \endcode

    <b>File viewer</b> \n

    As for URis, a service application that support viewing a file with a dedicated MIME-type need to publish support for:

    - The common interface "com.nokia.symbian.IFileView".

    - The slot "view(QString)" to view the non-data-caged file by file name.

    - The slot "view(XQSharable)" to view the data-caged file by sharable file handle.

    - MIME type list (registered in the .pro file).

    So there are multiple service applications implementing the same interface.

    In service provider side you need the following entry in XML:

    \code

        <interface>

            <name>com.nokia.symbian.IFileView</name>

            <version>1.0</version>

            <description>Interface for showing Files</description>

        </interface>

    \endcode

    The file viewer application shall offer slots both for viewing filename (QString) and viewing sharable file (XQSharable):

    \code

    class FileService : public XQServiceProvider

    {

        Q_OBJECT

        public:

            FileService( ServiceApp *parent = 0 );

            ~FileService();

            bool asyncAnswer() {return mAsyncAnswer;}

            void complete(bool ok);

        public slots:

            bool view(QString file);

            bool view(XQSharableFile file);

        private slots:

            void handleClientDisconnect();

        private:

            ServiceApp* mServiceApp;

            bool mAsyncAnswer;

            int mAsyncReqId;

            bool mRetValue;

    };

    \endcode

    In the .pro file the service publishes the supported MIME types, e.g:

    \code

        RSS_RULES += \