sl@0: // Copyright (c) 1995-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: // Shells Animate DLL
sl@0: // 
sl@0: //
sl@0: 
sl@0: #include <e32std.h>
sl@0: #include "../SERVER/w32cmd.h"
sl@0: #include "w32comm.h"
sl@0: #include "CLIENT.H"
sl@0: 
sl@0: EXPORT_C RAnimDll::RAnimDll()
sl@0: /** Default constructor. 
sl@0: 
sl@0: RAnimDll is a lightweight class which can be allocated as a non-pointer member. 
sl@0: This constructor is provided to allow such a member to be instantiated while 
sl@0: its owner is constructed.
sl@0: 
sl@0: Note that an RAnimDll constructed without a reference to a window server session 
sl@0: is invalid. */
sl@0: 	{}
sl@0: 
sl@0: EXPORT_C RAnimDll::RAnimDll(RWsSession &aWs) : MWsClientClass(aWs.iBuffer)
sl@0: /** Valid constructor. 
sl@0: 
sl@0: To be useable, an animation DLL should always be constructed with a reference 
sl@0: to a window server session as argument.
sl@0: 
sl@0: @param aWs Window server session to use. */
sl@0: 	{}
sl@0: 
sl@0: EXPORT_C RAnimDll::~RAnimDll()
sl@0: /** Empty virtual destructor. 
sl@0: 
sl@0: Destroy() should be used to instead of this function to destroy both this 
sl@0: object and the server-side CAnimDll object.
sl@0: 
sl@0: @see Destroy()
sl@0: @see Close() */
sl@0: 	{}
sl@0: 
sl@0: EXPORT_C void RAnimDll::Close()
sl@0: /** Closes an animation DLL. 
sl@0: 
sl@0: Use this function to close a polymorphic DLL which was previously loaded on 
sl@0: the server. Cleans up and frees all resources belonging to the DLL but does 
sl@0: not delete it. Closing is in accordance with the RLibrary mechanism.
sl@0: 
sl@0: Load() and Close() are symmetrical operations. A DLL can be re-loaded after 
sl@0: a close has been called on it.
sl@0: 
sl@0: To both close and delete a previously loaded DLL, use Destroy(). */
sl@0: 	{
sl@0: 	if (iBuffer && iWsHandle)
sl@0: 		Write(EWsAnimDllOpFree);
sl@0: 	iWsHandle=NULL;
sl@0: 	}
sl@0: 
sl@0: EXPORT_C void RAnimDll::Destroy()
sl@0: /** Closes and deletes a previously loaded polymorphic DLL. 
sl@0: 
sl@0: This function is equivalent to calling this->Close() followed by delete this, 
sl@0: in accordance with the RLibrary mechanism provided for managing polymorphic 
sl@0: DLLs. */
sl@0: 	{
sl@0: 	Close();
sl@0: 	delete this;
sl@0: 	}
sl@0: 
sl@0: EXPORT_C TInt RAnimDll::Load(const TDesC &aFileName)
sl@0: /** Instructs the server to load an animation DLL. 
sl@0: 
sl@0: Use this function to pass the name of a polymorphic DLL, the animation DLL, 
sl@0: for loading on the server side. Loading is in accordance with the RLibrary 
sl@0: mechanism. The DLL must conform to the interface defined by the window server, 
sl@0: otherwise an error will result. For requirements, see the description of CAnimDll.
sl@0: 
sl@0: Load() and Close() are symmetrical operations. A DLL can be re-loaded after 
sl@0: a close has been called on it.
sl@0: 
sl@0: This function always causes a flush of the window server buffer.
sl@0: 
sl@0: @param aFileName Filename of the DLL to load. 
sl@0: @return KErrNone if successful, otherwise one of the system-wide error codes. 
sl@0: @panic TW32Panic 17 in debug builds if called on an already constructed object.*/
sl@0: 	{
sl@0: 	 __ASSERT_DEBUG(iWsHandle == KNullHandle, Panic(EW32PanicGraphicDoubleConstruction));
sl@0: 	TWsClCmdLoadAnimDll load;
sl@0: 	load.length=aFileName.Length();
sl@0: 	TInt ret;
sl@0: 	ret=iBuffer->WriteReplyWs(&load,sizeof(load),aFileName.Ptr(),aFileName.Size(),EWsClOpCreateAnimDll);
sl@0: 	if (ret<0)
sl@0: 		return(ret);
sl@0: 	iWsHandle=ret;
sl@0: 	return(KErrNone);
sl@0: 	}
sl@0: 
sl@0: TInt RAnimDll::CommandReply(TInt aHandle, TInt aOpcode, const TDesC8& aArgs, const TIpcArgs* aIpcArgs)
sl@0: 	{
sl@0: 	TInt params[2];
sl@0: 	params[0]=aHandle;
sl@0: 	params[1]=aOpcode;
sl@0: 	return(WriteReply(&params,sizeof(params),aArgs.Ptr(),aArgs.Length(),EWsAnimDllOpCommandReply,aIpcArgs));
sl@0: 	}
sl@0: 
sl@0: TInt RAnimDll::CommandReply(TInt aHandle, TInt aOpcode, const TIpcArgs* aIpcArgs)
sl@0: 	{
sl@0: 	TInt params[2];
sl@0: 	params[0]=aHandle;
sl@0: 	params[1]=aOpcode;
sl@0: 	return(WriteReply(&params,sizeof(params),EWsAnimDllOpCommandReply,aIpcArgs));
sl@0: 	}
sl@0: 
sl@0: void RAnimDll::Command(TInt aHandle, TInt aOpcode, const TPtrC8 &aArgs)
sl@0: 	{
sl@0: 	TInt params[2];
sl@0: 	params[0]=aHandle;
sl@0: 	params[1]=aOpcode;
sl@0: 	Write(&params,sizeof(params),aArgs.Ptr(),aArgs.Length(),EWsAnimDllOpCommand);
sl@0: 	}
sl@0: 
sl@0: void RAnimDll::Command(TInt aHandle, TInt aOpcode)
sl@0: 	{
sl@0: 	TInt params[2];
sl@0: 	params[0]=aHandle;
sl@0: 	params[1]=aOpcode;
sl@0: 	Write(&params,sizeof(params),EWsAnimDllOpCommand);
sl@0: 	}
sl@0: 
sl@0: void RAnimDll::AsyncCommandReply(TRequestStatus& aStatus, TInt aOpcode, TIpcArgs& aIpcArgs)
sl@0: 	{
sl@0: 	__ASSERT_DEBUG((aOpcode&EWservMessAnimDllAsyncCommand)==0, Assert(EW32AssertIllegalOpcode));
sl@0: 	aIpcArgs.Set(KAsyncMessageSlotAnimDllHandle,iWsHandle);
sl@0: 	iBuffer->Flush(); // needs to happen first so that things occur in their correct order, and because this asynchronous function uses a different mechanism, i.e. assigns different meanings to, say, the first slot in the TIpcArgs
sl@0: 	iBuffer->Session()->SendReceive((aOpcode|EWservMessAnimDllAsyncCommand),aIpcArgs,aStatus);
sl@0: 	}
sl@0: 
sl@0: TInt RAnimDll::CreateInstance(TInt32& aHandle, const MWsClientClass &aDevice, TInt aType, const TDesC8 &aArgs, TInt aOpcode, const TIpcArgs* aIpcArgs)
sl@0: 	{
sl@0: 	TInt params[2];
sl@0: 	params[0]=aDevice.WsHandle();
sl@0: 	params[1]=aType;
sl@0: 	const TInt returnValue=WriteReply(&params,sizeof(params),aArgs.Ptr(),aArgs.Length(),aOpcode,aIpcArgs);
sl@0: 	if (returnValue>=0)
sl@0: 		{
sl@0: 		aHandle=returnValue;
sl@0: 		return KErrNone;
sl@0: 		}
sl@0: 	return returnValue;
sl@0: 	}
sl@0: 
sl@0: void RAnimDll::DestroyInstance(TInt aHandle)
sl@0: 	{
sl@0: 	WriteReplyInt(aHandle,EWsAnimDllOpDestroyInstance);
sl@0: 	}
sl@0: 
sl@0: EXPORT_C RAnim::RAnim() : iHandle(0)
sl@0: /** Default constructor. Developers should use the other constructor overload. */
sl@0: 	{}
sl@0: 
sl@0: EXPORT_C RAnim::RAnim(RAnimDll &aDll) : iHandle(0),iAnimDll(&aDll)
sl@0: /** Protected C++ constructor.
sl@0: 
sl@0: This constructor should be used to construct an animation object from a given 
sl@0: animation DLL. The DLL must be loaded first, see the discussion of RAnimDll.
sl@0: 
sl@0: @param aDll The animation DLL. */
sl@0: 	{}
sl@0: 
sl@0: EXPORT_C RAnim::~RAnim()
sl@0: /** Empty virtual destructor. */
sl@0: 	{}
sl@0: 
sl@0: EXPORT_C TInt RAnim::Construct(const RWindowBase &aDevice, TInt aType, const TDesC8 &aParams)
sl@0: /** Completes construction of the object based on a window device, and creates 
sl@0: the server-side animation system. 
sl@0: 
sl@0: Construction information is passed to the server side via aType and aParams. 
sl@0: The server then passes the information to the function CreateInstanceL() inside 
sl@0: the Anim DLL.
sl@0: 
sl@0: This function always causes a flush of the window server buffer.
sl@0: 
sl@0: @param aDevice A window device. 
sl@0: @param aType The type of this animation object, as understood by CAnimDll::CreateInstanceL(). 
sl@0: @param aParams Packaged arguments which will be passed to the server side object 
sl@0: to tell it how to construct itself or initialise itself. 
sl@0: @return KErrNone if successful, otherwise one of the system-wide error codes. 
sl@0: @see CAnim::ConstructL()
sl@0: @see CAnimDll::CreateInstanceL() */
sl@0: 	{
sl@0: 	return iAnimDll->CreateInstance(iHandle, aDevice, aType, aParams, EWsAnimDllOpCreateInstance, NULL);
sl@0: 	}
sl@0: 
sl@0: EXPORT_C TInt RAnim::Construct(const RWindowBase &aDevice, TInt aType, const TDesC8 &aParams, const TIpcArgs& aIpcArgs)
sl@0: /** Completes construction of the object based on a window device, and creates 
sl@0: the server-side animation system. 
sl@0: 
sl@0: Construction information is passed to the server side via aType and aParams. 
sl@0: The server then passes the information to the function CreateInstanceL() inside 
sl@0: the Anim DLL.
sl@0: 
sl@0: This function always causes a flush of the window server buffer.
sl@0: 
sl@0: @param aDevice A window device. 
sl@0: @param aType The type of this animation object, as understood by CAnimDll::CreateInstanceL(). 
sl@0: @param aParams Packaged arguments which will be passed to the server side object 
sl@0: to tell it how to construct itself or initialise itself. 
sl@0: @param aIpcArgs Inter-process communication arguments which will be passed to the server side 
sl@0: object. Panics if the first "slot" is set to anything other than TIpcArgs::ENothing.
sl@0: @return KErrNone if successful, otherwise one of the system-wide error codes. 
sl@0: @see CAnim::ConstructL()
sl@0: @see CAnimDll::CreateInstanceL() */
sl@0: 	{
sl@0: 	return iAnimDll->CreateInstance(iHandle, aDevice, aType, aParams, EWsAnimDllOpCreateInstance, &aIpcArgs);
sl@0: 	}
sl@0: 
sl@0: EXPORT_C TInt RAnim::Construct(const RWsSprite &aDevice, TInt aType, const TDesC8 &aParams)
sl@0: /** Completes construction of the Anim DLL based on a sprite. 
sl@0: 
sl@0: Construction information is passed to the server side via aType and aParams. 
sl@0: The server then passes the information to the function CreateInstanceL() inside 
sl@0: the Anim DLL.
sl@0: 
sl@0: This function always causes a flush of the window server buffer.
sl@0: 
sl@0: @param aDevice A sprite. 
sl@0: @param aType The type of this animation object, as understood by CAnimDll::CreateInstanceL(). 
sl@0: @param aParams Packaged arguments which will be passed to the server side object 
sl@0: to tell it how to construct itself or initialise itself. 
sl@0: @return KErrNone if successful, otherwise one of the system-wide error codes. 
sl@0: @see CAnim::ConstructL()
sl@0: @see CAnimDll::CreateInstanceL() */
sl@0: 	{
sl@0: 	return iAnimDll->CreateInstance(iHandle, aDevice, aType, aParams, EWsAnimDllOpCreateInstanceSprite, NULL);
sl@0: 	}
sl@0: 
sl@0: EXPORT_C TInt RAnim::Construct(const RWsSprite &aDevice, TInt aType, const TDesC8 &aParams, const TIpcArgs& aIpcArgs)
sl@0: /** Completes construction of the Anim DLL based on a sprite. 
sl@0: 
sl@0: Construction information is passed to the server side via aType and aParams. 
sl@0: The server then passes the information to the function CreateInstanceL() inside 
sl@0: the Anim DLL.
sl@0: 
sl@0: This function always causes a flush of the window server buffer.
sl@0: 
sl@0: @param aDevice A sprite. 
sl@0: @param aType The type of this animation object, as understood by CAnimDll::CreateInstanceL(). 
sl@0: @param aParams Packaged arguments which will be passed to the server side object 
sl@0: to tell it how to construct itself or initialise itself. 
sl@0: @param aIpcArgs Inter-process communication arguments which will be passed to the server side 
sl@0: object. Panics if the first "slot" is set to anything other than TIpcArgs::ENothing.
sl@0: @return KErrNone if successful, otherwise one of the system-wide error codes. 
sl@0: @see CAnim::ConstructL()
sl@0: @see CAnimDll::CreateInstanceL() */
sl@0: 	{
sl@0: 	return iAnimDll->CreateInstance(iHandle, aDevice, aType, aParams, EWsAnimDllOpCreateInstanceSprite, &aIpcArgs);
sl@0: 	}
sl@0: 
sl@0: EXPORT_C TInt RAnim::CommandReply(TInt aOpcode)
sl@0: /** Sends a command to the server-side CAnim instance, and waits for a response. 
sl@0: 
sl@0: This function executes synchronously and returns the code returned by the 
sl@0: server-side method CAnim::CommandReplyL(). The request is not buffered.
sl@0: 
sl@0: @param aOpcode An opcode meaningful to the server-side CAnim-derived class. 
sl@0: @return A value defined by the animation writer. The value may, in some cases, 
sl@0: be defined to be an error code.
sl@0: 
sl@0: This function always causes a flush of the window server buffer. 
sl@0: 
sl@0: @see Command()
sl@0: @see AsyncCommandReply()
sl@0: @see CAnim::CommandReplyL() */
sl@0: 	{
sl@0: 	return(iAnimDll->CommandReply(iHandle,aOpcode));
sl@0: 	}
sl@0: 
sl@0: EXPORT_C TInt RAnim::CommandReply(TInt aOpcode, const TPtrC8 &aArgs)
sl@0: /** Sends a command and its arguments to the server-side CAnim instance, and waits 
sl@0: for a response. 
sl@0: 
sl@0: The packaged command arguments are passed to the matching server side function, 
sl@0: where the behaviour should be implemented. The request is not buffered. The 
sl@0: function executes synchronously and returns the code returned by the server-side 
sl@0: method CAnim::CommandReplyL().
sl@0: 
sl@0: This function always causes a flush of the window server buffer. 
sl@0: 
sl@0: @param aOpcode An opcode meaningful to the server-side CAnim-derived class. 
sl@0: @param aArgs Packaged arguments which will be passed to the server side object. 
sl@0: @return A value defined by the animation writer. The value may, in some cases, 
sl@0: be defined to be an error code. 
sl@0: @see Command()
sl@0: @see AsyncCommandReply()
sl@0: @see CAnim::CommandReplyL() */
sl@0: 	{
sl@0: 	return(iAnimDll->CommandReply(iHandle,aOpcode, aArgs));
sl@0: 	}
sl@0: 
sl@0: EXPORT_C TInt RAnim::CommandReply(TInt aOpcode, const TDesC8& aArgs, const TIpcArgs& aIpcArgs)
sl@0: /** Sends a command and its arguments to the server-side CAnim instance, and waits 
sl@0: for a response. 
sl@0: 
sl@0: The IPC (inter-process communication) arguments are passed to the matching server side function, 
sl@0: where the behaviour should be implemented. The request is not buffered. The 
sl@0: function executes synchronously and returns the code returned by the server-side 
sl@0: method CAnim::CommandReplyL(). The first slot of the TIpcArgs parameter is reserved for 
sl@0: internal use. The second slot is used to receive an additional reply from the server-side CAnim.
sl@0: 
sl@0: This function always causes a flush of the window server buffer. 
sl@0: 
sl@0: @param aOpcode An opcode meaningful to the server-side CAnim-derived class. 
sl@0: @param aArgs Packaged arguments which will be passed to the server side object. 
sl@0: @param aIpcArgs Inter-process communication arguments which will be passed to the server side 
sl@0: object. Panics if the first "slot" is set to anything other than TIpcArgs::ENothing.
sl@0: @return A value defined by the animation writer. The value may, in some cases, 
sl@0: be defined to be an error code. 
sl@0: @see Command()
sl@0: @see AsyncCommandReply()
sl@0: @see CAnim::CommandReplyL() */
sl@0: 	{
sl@0: 	return(iAnimDll->CommandReply(iHandle,aOpcode,aArgs,&aIpcArgs));
sl@0: 	}
sl@0: 
sl@0: EXPORT_C void RAnim::Command(TInt aOpcode)
sl@0: /** Sends a command to the server-side CAnim instance, and returns immediately. 
sl@0: 
sl@0: Commands issued by this function may be buffered before being passed to the 
sl@0: server.
sl@0: 
sl@0: Server-side errors cannot be detected, so Command() should not be used for 
sl@0: operations which could fail or which may leave. Use CommandReply() for those. 
sl@0: Although the window server will not fail due to errors not being returned 
sl@0: to the client side, client side behaviour will almost certainly not be correct 
sl@0: if errors have been generated but not received.
sl@0: 
sl@0: Use of this function results in a server-side call to the equivalent CAnim::Command().
sl@0: 
sl@0: @param aOpcode An operation meaningful to the server-side CAnim object. 
sl@0: @see CommandReply()
sl@0: @see AsyncCommandReply()
sl@0: @see CAnim::Command() */
sl@0: 	{
sl@0: 	iAnimDll->Command(iHandle,aOpcode);
sl@0: 	}
sl@0: 
sl@0: EXPORT_C void RAnim::Command(TInt aOpcode, const TPtrC8 &aArgs)
sl@0: /** Sends a command and its arguments to the server-side CAnim instance, and returns 
sl@0: immediately. 
sl@0: 
sl@0: Commands issued by this function may be buffered before being passed to the 
sl@0: server.
sl@0: 
sl@0: Server-side errors cannot be detected, so Command() should not be used for 
sl@0: operations which could fail or which may leave. Use CommandReply() for those. 
sl@0: Although the window server will not fail due to errors not being returned 
sl@0: to the client side, client side behaviour will almost certainly not be correct 
sl@0: if errors have been generated but not received.
sl@0: 
sl@0: Use of this function results in a server-side call to the equivalent CAnim::Command().
sl@0: 
sl@0: @param aOpcode An operation meaningful to the server-side CAnim object. 
sl@0: @param aArgs Packaged arguments which will be passed to the server side object. 
sl@0: 
sl@0: @see CommandReply()
sl@0: @see AsyncCommandReply()
sl@0: @see CAnim::Command() */
sl@0: 	{
sl@0: 	iAnimDll->Command(iHandle,aOpcode, aArgs);
sl@0: 	}
sl@0: 
sl@0: EXPORT_C void RAnim::AsyncCommandReply(TRequestStatus& aRequestStatus,TInt aOpcode, const TIpcArgs& aIpcArgs)
sl@0: /** Sends a command and its arguments to the server-side CAnim instance asynchronously. 
sl@0: 
sl@0: The IPC (inter-process communication) arguments are passed to the CAnim-derived class' 
sl@0: CommandReplyL function, where the behaviour should be implemented. The request is not 
sl@0: buffered - rather the function executes asynchronously. The first and second slots of the 
sl@0: TIpcArgs parameter are reserved for internal use. 
sl@0: 
sl@0: If the code calling this function is itself an API that is asynchronous (i.e. if the 
sl@0: TRequestStatus passed into this function is simply a parameter to a higher-level API), then that 
sl@0: higher-level API should typically provide a corresponding "Cancel" function that its own clients 
sl@0: can use to cancel their asynchronous request - this would typically be implemented by the 
sl@0: higher-level API by using RAnim::CommandReply.
sl@0: 
sl@0: @param aRequestStatus Set initially by the function to KRequestPending. Then when this 
sl@0: asynchronous function at some potentially later point in time "completes", aRequestStatus 
sl@0: is set to the completion code which is a value defined by the animation writer (i.e. the value 
sl@0: that the server-side CAnim-derived class' CommandReplyL returns or leaves with). The value may, 
sl@0: in some cases, be defined to be an error code. 
sl@0: @param aOpcode An opcode meaningful to the server-side CAnim-derived class. 
sl@0: @param aIpcArgs Inter-process communication arguments which will be passed to the server side 
sl@0: object. Panics if either the first or second "slot" is set to anything other than 
sl@0: TIpcArgs::ENothing.
sl@0: 
sl@0: @see CommandReply()
sl@0: @see Command()
sl@0: @see CAnim::CommandReplyL() */
sl@0: 	{
sl@0: 	TIpcArgs ipcArgs;
sl@0: 	ipcArgs=aIpcArgs; // GCC doesn't seem to like doing a copy constructor on TIpcArgs, probably because it's confused by all the templated-ness of TIpcArgs' constructors
sl@0: 	// check that the caller hasn't used the first or second slot (the first is set by the RAnimDll::AsyncCommandReply call below)
sl@0: 	ipcArgs.Set(KAsyncMessageSlotAnimDllHandle,TIpcArgs::ENothing);
sl@0: 	ipcArgs.Set(KAsyncMessageSlotAnimHandle,TIpcArgs::ENothing);
sl@0: 	__ASSERT_ALWAYS(Mem::Compare(REINTERPRET_CAST(const TUint8*, &ipcArgs), sizeof(TIpcArgs), REINTERPRET_CAST(const TUint8*, &aIpcArgs), sizeof(TIpcArgs))==0,Panic(EW32PanicUsingReservedIpcSlot));
sl@0: 	ipcArgs.Set(KAsyncMessageSlotAnimHandle,iHandle);
sl@0: 	iAnimDll->AsyncCommandReply(aRequestStatus, aOpcode, ipcArgs);
sl@0: 	}
sl@0: 
sl@0: EXPORT_C void RAnim::Close()
sl@0: /** Sends the close command.
sl@0: 
sl@0: This frees resources belonging to an animation object. It would be called 
sl@0: to release resources when the RAnim is owned in-line by another object (so 
sl@0: that destruction is automatic). 
sl@0: 
sl@0: This function always causes a flush of the window server buffer. */
sl@0: 	{
sl@0: 	if (iHandle!=0)
sl@0: 		{
sl@0: 		iAnimDll->DestroyInstance(iHandle);
sl@0: 		iHandle=0;
sl@0: 		}
sl@0: 	}
sl@0: 
sl@0: EXPORT_C void RAnim::Destroy()
sl@0: /** Closes and deletes the server-side animation object. 
sl@0: 
sl@0: This should be called on heap allocated objects. 
sl@0: 
sl@0: This function always causes a flush of the window server buffer. */
sl@0: 	{
sl@0: 	Close();
sl@0: 	delete this;
sl@0: 	}