baselibs/thread_messaging/src/pv_proxied_interface.h

/* ------------------------------------------------------------------
 * Copyright (C) 1998-2009 PacketVideo
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
 * express or implied.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 * -------------------------------------------------------------------
 */

#ifndef PV_PROXIED_INTERFACE__H
#define PV_PROXIED_INTERFACE__H


#ifndef OSCL_BASE_H_INCLUDED
#include "oscl_base.h"
#endif
#ifndef PV_UUID_H_INCLUDED
#include "pv_uuid.h"
#endif
#ifndef PV_INTERFACE_H_INCLUDED
#include "pv_interface.h"
#endif

#define PVUidProxiedInterface  PVUuid(0xf7076653,0x6088,0x47c6,0x88,0xc1,0xb7,0xed,0x28,0xe7,0x2b,0xea)

class PVProxiedInterface;
class PVProxiedInterfaceClient;
class PVProxiedInterfaceServer;
class PVProxiedEngine;

typedef int32 TPVProxyId;
typedef int32 TPVProxyMsgId;
typedef PVUuid TPVProxyUUID;
typedef PVProxiedInterface* TPVProxyInterfacePtr;

/**
** Main proxy class.  This class defines the public interface
** to the PV proxy.
*/
class PVMainProxy
{
    public:
        virtual ~PVMainProxy() {}

        /**
        ** This call registers a proxied interface with the main
        ** proxy and assigns a unique interface ID.
        ** Interfaces may be registered at any time during
        ** the life of the main proxy.
        **
        ** @return aProxyId: the ID of this interface pair.
        ** @param aServer: server side (PV Thread) implementation.
        ** @param aClient: client side (app thread) implementation.
        ** This function will leave if memory allocation fails.
        */
        virtual TPVProxyId RegisterProxiedInterface(
            PVProxiedInterfaceServer& aServer,
            PVProxiedInterfaceClient& aClient) = 0;

        /**
        ** This call un-registers a proxied interface with the main
        ** proxy.  During this call, the main proxy will de-queue all
        ** undelivered messages belonging to this interface and will
        ** call their memory cleanup routine.
        ** If the interface is not currently registered, this call
        ** will have no effect.
        ** Interfaces may be un-registered at any time during the
        ** life of the main proxy.
        **
        ** @param aProxyId: the ID of this interface pair.
        ** @return : result code
        **/
        virtual void UnregisterProxiedInterface(TPVProxyId aProxyId) = 0;

        /**
        ** This API adds message to the command queue.  This would
        ** typically be called from a PVProxiedInterfaceClient
        ** module.  The message will be delivered asynchronously under
        ** the PV thread.
        **
        ** @param aProxyId: the ID of this interface pair.
        ** @param aCmd: the command.
        ** @return: a unique message ID, assigned by the proxy.
        ** This function will leave if memory allocation fails.
        **/
        virtual TPVProxyMsgId SendCommand(TPVProxyId aProxyId, OsclAny* aCmd) = 0;

        /**
        ** This API will cancel a command that was previously sent
        ** and may still be queued.  This is a synchronous operation.
        ** The proxy will de-queue the message and call its memory cleanup
        ** routine.  If the message is no longer queued, this call will
        ** have no effect.
        **
        ** @param aProxyId: the ID of this interface pair.
        ** @param aMsgId: the command's ID, previously returned by SendCommand.
        ** @return : result code
        */
        virtual void CancelCommand(TPVProxyId aProxyId, TPVProxyMsgId aMsgId) = 0;

        /**
        ** This API will de-queue and cleanup all commands that were
        ** previously sent for an interface and may still be queued.
        ** The cancel operation is synchronous.
        ** If no commands are queued for the interface, this call has
        ** no effect.
        **
        ** @param aProxyId: the ID of this interface pair.
        ** @return : result code
        */
        virtual void CancelAllCommands(TPVProxyId aProxyId) = 0;

        /**
        ** This API adds a message to the notification queue.
        ** This would typically be called by a PVProxiedInterfaceServer
        ** module.  The message will be delivered asynchronously under
        ** the app thread.
        **
        ** @param aProxyId: the ID of this interface pair.
        ** @param aResp: the notification.
        ** @return: a unique message ID, assigned by the proxy.
        ** This function will leave if memory allocation fails.
        **/
        virtual TPVProxyMsgId SendNotification(TPVProxyId aProxyId, OsclAny* aResp) = 0;

        /**
        ** This API will cancel a notification that was previously sent
        ** and may still be queued.  This is a synchronous operation.
        ** The proxy will de-queue the message and call its memory cleanup
        ** routine.  If the message is no longer queued, this call will
        ** have no effect.
        **
        ** @param aProxyId: the ID of this interface pair.
        ** @param aMsgId: the message ID, previously returned by SendNotification.
        ** @return : result code
        */
        virtual void CancelNotification(TPVProxyId aProxyId, TPVProxyMsgId aMsgId) = 0;

        /**
        ** This API will de-queue and cleanup all notifications that were
        ** previously sent for an interface and may still be queued.
        ** The cancel operation is synchronous.
        ** If no notifications are queued for the interface, this call has
        ** no effect.
        **
        ** @param aProxyId: the ID of this interface pair.
        ** @return : result code
        */
        virtual void CancelAllNotifications(TPVProxyId aProxyId) = 0;

        /**
        ** This API will start the PV thread.  The call will block
        ** until the thread starts up and the engine thread logon
        ** completes.
        **
        **  @returns: true if thread creation succeeded-- false otherwise.
        */
        virtual bool StartPVThread() = 0;

        /**
        ** This API will stop the PV thread's scheduler and block
        ** until the thread cleanup is complete.  During the thread
        ** cleanup, the scheduler is stopped, all un-sent messages
        ** are automatically cleaned up, and the engine Thread Logoff
        ** routine is called.
        **
        ** Calling this API under the PV thread context is an error
        ** and will leave
        */
        virtual void StopPVThread() = 0;

        /**
        ** This API may be used to run the client-side of the proxy
        ** in a non-blocking mode, for cases where there is no Oscl
        ** scheduler or native scheduler running in the application
        ** thread.
        ** The proxy client will run until all pending notifications
        ** have been sent, or else the max count of notifications has
        ** been reached.  This API also returns the count of notifications
        ** still pending after the processing is complete.
        ** Any call to this API from within the PV thread context is
        ** an error and will leave
        **
        ** @param aMaxCount: (input param) the maximum of pending
        **   notifications to process during the call.
        ** @param aPendingCount: (output param) number of pending
        **   notifications still remaining on the queue.
        */
        virtual void DeliverNotifications(int32 aMaxCount, int32& aPendingCount) = 0;
};

/**
** A proxied engine must implement this class
*/
class PVProxiedEngine
{
    public:
        virtual ~PVProxiedEngine() {}

        /**
        ** Create PV logger appenders for the PV thread.
        ** Creating appenders in this call is optional and
        ** allows logging by the PV thread related to thread
        ** and scheduler initialization that occurs before
        ** the thread logon.
        **/
        virtual void CreateLoggerAppenders() = 0;

        /**
        ** Perform all thread-specific engine creation and
        ** initialization.
        ** This call is made by the main proxy from the PV
        ** Thread after Oscl has been initialized
        ** in the thread, but before starting the scheduler.
        **
        ** @param proxy: reference to the caller.  The app
        **   may save this pointer and use it to make calls
        **   to the main proxy.
        */
        virtual void PVThreadLogon(PVMainProxy &proxy) = 0;

        /**
        ** Perform all thread-specific engine cleanup.
        ** This call is made by the main proxy from the PV thread
        ** after the scheduler has exited, but before Oscl has been
        ** cleaned up.
        **
        ** @param proxy: reference to the caller.  The app
        **   may save this pointer and use it to make calls
        **   to the main proxy.
        */
        virtual void PVThreadLogoff(PVMainProxy &proxy) = 0;
};

/**
** Proxied interface modules may implement this class
** in order to provide a common interface query mechanism.
*/
class PVProxiedInterface : public PVInterface
{
    public:
        /**
        ** To query for supported (proxied) interfaces.
        **
        ** @param aUuid (input): the requested UUID
        ** @param aInterfacePtr (output): a pointer to
        **    the interface implementation, or NULL if not available.
        **
        ** The holder of the interface pointer must call
        ** "removeRef" when it is done with the pointer.
        */
        virtual void QueryProxiedInterface(const TPVProxyUUID& aUuid, PVInterface*& aInterfacePtr) = 0;
        /**
        ** May be used to pass the main proxy pointer to
        ** the implementation.
        */
        virtual void SetMainProxy(PVMainProxy*) = 0;
};


/**
** Proxied interface modules must implement this class on the
** PV thread side.
*/
class PVProxiedInterfaceServer
{
    public:
        /**
        ** PVMainProxy calls this under the PV thread to process a
        ** command off the queue.
        **
        ** @param aId: the message ID assigned by the SendCommand call.
        ** @param aMsg: the command data.
        */
        virtual void HandleCommand(TPVProxyMsgId aMsgId, OsclAny* aMsg) = 0;

        /**
        ** PVMainProxy calls this to cleanup an un-sent or canceled
        ** notification.  The server module should clean up any
        ** allocated memory.  The cleanup operation must be synchronous
        ** and thread-safe.
        **
        ** @param aId: the message ID assigned by the SendNotification call.
        ** @param aMsg: the notification data.
        */
        virtual void CleanupNotification(TPVProxyMsgId aId, OsclAny* aMsg) = 0;
};

/**
** Proxied interface pairs must implement this class on the
** app thread side.
*/
class PVProxiedInterfaceClient
{
    public:
        PVProxiedInterfaceClient() {}

        /**
        ** PVMainProxy calls this to process a notification off the
        ** queue.
        ** @param aId: the message ID assigned by the SendNotification call.
        ** @param aMsg: the notification data.
        */
        virtual void HandleNotification(TPVProxyMsgId aId, OsclAny* aMsg) = 0;

        /**
        ** PVMainProxy calls this to cleanup an un-sent or canceled
        ** command.  The client module should clean up any allocated
        ** memory.  The cleanup operation must be synchronous
        ** and thread-safe.
        **
        ** @param aId: the message ID assigned by the SendCommand call.
        ** @param aMsg: the command data.
        */
        virtual void CleanupCommand(TPVProxyMsgId aId, OsclAny* aMsg) = 0;
};

/**
//A basic implemention of PVProxiedInterface.
//Interface implementations
//can derive from this.
*/
template<class Alloc>
class PVProxiedInterfaceImpl : public PVProxiedInterface
{
    public:
        PVProxiedInterfaceImpl(const PVUuid& uuid)
                : iRefCounter(1)
                , iUuid(uuid)
                , iMainProxy(NULL)
        {}
        void SetUuid(const PVUuid& uuid)
        {
            iUuid = uuid;
        }
        bool TestUuid(const PVUuid& uuid)
        {
            return iUuid == uuid;
        }
        virtual ~PVProxiedInterfaceImpl()
        {}
        void removeRef()
        {
            --iRefCounter;
            if (iRefCounter <= 0)
            {
                this->~PVProxiedInterfaceImpl();
                Alloc alloc;
                alloc.deallocate(this);
            }
        }
        void addRef()
        {
            iRefCounter++;
        }
        bool queryInterface(const PVUuid&, PVInterface*&)
        {
            return false;
        }

        void SetMainProxy(PVMainProxy*p)
        {
            iMainProxy = p;
        }
        void QueryProxiedInterface(const TPVProxyUUID& aUuid, PVInterface*& aInterfacePtr)
        {
            if (aUuid == iUuid)
                aInterfacePtr = (PVInterface*)this;
            else
                aInterfacePtr = NULL;
        }
    protected:
        int32 iRefCounter;
        PVUuid iUuid;
        PVMainProxy *iMainProxy;
};


#endif