blob: 76f86a951ea3a391c8b394a403247086b561ee84 [file] [log] [blame]
/* ------------------------------------------------------------------
* 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