1 // Copyright (c) 1995-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 // Shells Animate DLL

    15 // 

    16 //

    17 

    18 #include <e32std.h>

    19 #include "../SERVER/w32cmd.h"

    20 #include "w32comm.h"

    21 #include "CLIENT.H"

    22 

    23 EXPORT_C RAnimDll::RAnimDll()

    24 /** Default constructor. 

    25 

    26 RAnimDll is a lightweight class which can be allocated as a non-pointer member. 

    27 This constructor is provided to allow such a member to be instantiated while 

    28 its owner is constructed.

    29 

    30 Note that an RAnimDll constructed without a reference to a window server session 

    31 is invalid. */

    32 	{}

    33 

    34 EXPORT_C RAnimDll::RAnimDll(RWsSession &aWs) : MWsClientClass(aWs.iBuffer)

    35 /** Valid constructor. 

    36 

    37 To be useable, an animation DLL should always be constructed with a reference 

    38 to a window server session as argument.

    39 

    40 @param aWs Window server session to use. */

    41 	{}

    42 

    43 EXPORT_C RAnimDll::~RAnimDll()

    44 /** Empty virtual destructor. 

    45 

    46 Destroy() should be used to instead of this function to destroy both this 

    47 object and the server-side CAnimDll object.

    48 

    49 @see Destroy()

    50 @see Close() */

    51 	{}

    52 

    53 EXPORT_C void RAnimDll::Close()

    54 /** Closes an animation DLL. 

    55 

    56 Use this function to close a polymorphic DLL which was previously loaded on 

    57 the server. Cleans up and frees all resources belonging to the DLL but does 

    58 not delete it. Closing is in accordance with the RLibrary mechanism.

    59 

    60 Load() and Close() are symmetrical operations. A DLL can be re-loaded after 

    61 a close has been called on it.

    62 

    63 To both close and delete a previously loaded DLL, use Destroy(). */

    64 	{

    65 	if (iBuffer && iWsHandle)

    66 		Write(EWsAnimDllOpFree);

    67 	iWsHandle=NULL;

    68 	}

    69 

    70 EXPORT_C void RAnimDll::Destroy()

    71 /** Closes and deletes a previously loaded polymorphic DLL. 

    72 

    73 This function is equivalent to calling this->Close() followed by delete this, 

    74 in accordance with the RLibrary mechanism provided for managing polymorphic 

    75 DLLs. */

    76 	{

    77 	Close();

    78 	delete this;

    79 	}

    80 

    81 EXPORT_C TInt RAnimDll::Load(const TDesC &aFileName)

    82 /** Instructs the server to load an animation DLL. 

    83 

    84 Use this function to pass the name of a polymorphic DLL, the animation DLL, 

    85 for loading on the server side. Loading is in accordance with the RLibrary 

    86 mechanism. The DLL must conform to the interface defined by the window server, 

    87 otherwise an error will result. For requirements, see the description of CAnimDll.

    88 

    89 Load() and Close() are symmetrical operations. A DLL can be re-loaded after 

    90 a close has been called on it.

    91 

    92 This function always causes a flush of the window server buffer.

    93 

    94 @param aFileName Filename of the DLL to load. 

    95 @return KErrNone if successful, otherwise one of the system-wide error codes. 

    96 @panic TW32Panic 17 in debug builds if called on an already constructed object.*/

    97 	{

    98 	 __ASSERT_DEBUG(iWsHandle == KNullHandle, Panic(EW32PanicGraphicDoubleConstruction));

    99 	TWsClCmdLoadAnimDll load;

   100 	load.length=aFileName.Length();

   101 	TInt ret;

   102 	ret=iBuffer->WriteReplyWs(&load,sizeof(load),aFileName.Ptr(),aFileName.Size(),EWsClOpCreateAnimDll);

   103 	if (ret<0)

   104 		return(ret);

   105 	iWsHandle=ret;

   106 	return(KErrNone);

   107 	}

   108 

   109 TInt RAnimDll::CommandReply(TInt aHandle, TInt aOpcode, const TDesC8& aArgs, const TIpcArgs* aIpcArgs)

   110 	{

   111 	TInt params[2];

   112 	params[0]=aHandle;

   113 	params[1]=aOpcode;

   114 	return(WriteReply(&params,sizeof(params),aArgs.Ptr(),aArgs.Length(),EWsAnimDllOpCommandReply,aIpcArgs));

   115 	}

   116 

   117 TInt RAnimDll::CommandReply(TInt aHandle, TInt aOpcode, const TIpcArgs* aIpcArgs)

   118 	{

   119 	TInt params[2];

   120 	params[0]=aHandle;

   121 	params[1]=aOpcode;

   122 	return(WriteReply(&params,sizeof(params),EWsAnimDllOpCommandReply,aIpcArgs));

   123 	}

   124 

   125 void RAnimDll::Command(TInt aHandle, TInt aOpcode, const TPtrC8 &aArgs)

   126 	{

   127 	TInt params[2];

   128 	params[0]=aHandle;

   129 	params[1]=aOpcode;

   130 	Write(&params,sizeof(params),aArgs.Ptr(),aArgs.Length(),EWsAnimDllOpCommand);

   131 	}

   132 

   133 void RAnimDll::Command(TInt aHandle, TInt aOpcode)

   134 	{

   135 	TInt params[2];

   136 	params[0]=aHandle;

   137 	params[1]=aOpcode;

   138 	Write(&params,sizeof(params),EWsAnimDllOpCommand);

   139 	}

   140 

   141 void RAnimDll::AsyncCommandReply(TRequestStatus& aStatus, TInt aOpcode, TIpcArgs& aIpcArgs)

   142 	{

   143 	__ASSERT_DEBUG((aOpcode&EWservMessAnimDllAsyncCommand)==0, Assert(EW32AssertIllegalOpcode));

   144 	aIpcArgs.Set(KAsyncMessageSlotAnimDllHandle,iWsHandle);

   145 	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

   146 	iBuffer->Session()->SendReceive((aOpcode|EWservMessAnimDllAsyncCommand),aIpcArgs,aStatus);

   147 	}

   148 

   149 TInt RAnimDll::CreateInstance(TInt32& aHandle, const MWsClientClass &aDevice, TInt aType, const TDesC8 &aArgs, TInt aOpcode, const TIpcArgs* aIpcArgs)

   150 	{

   151 	TInt params[2];

   152 	params[0]=aDevice.WsHandle();

   153 	params[1]=aType;

   154 	const TInt returnValue=WriteReply(&params,sizeof(params),aArgs.Ptr(),aArgs.Length(),aOpcode,aIpcArgs);

   155 	if (returnValue>=0)

   156 		{

   157 		aHandle=returnValue;

   158 		return KErrNone;

   159 		}

   160 	return returnValue;

   161 	}

   162 

   163 void RAnimDll::DestroyInstance(TInt aHandle)

   164 	{

   165 	WriteReplyInt(aHandle,EWsAnimDllOpDestroyInstance);

   166 	}

   167 

   168 EXPORT_C RAnim::RAnim() : iHandle(0)

   169 /** Default constructor. Developers should use the other constructor overload. */

   170 	{}

   171 

   172 EXPORT_C RAnim::RAnim(RAnimDll &aDll) : iHandle(0),iAnimDll(&aDll)

   173 /** Protected C++ constructor.

   174 

   175 This constructor should be used to construct an animation object from a given 

   176 animation DLL. The DLL must be loaded first, see the discussion of RAnimDll.

   177 

   178 @param aDll The animation DLL. */

   179 	{}

   180 

   181 EXPORT_C RAnim::~RAnim()

   182 /** Empty virtual destructor. */

   183 	{}

   184 

   185 EXPORT_C TInt RAnim::Construct(const RWindowBase &aDevice, TInt aType, const TDesC8 &aParams)

   186 /** Completes construction of the object based on a window device, and creates 

   187 the server-side animation system. 

   188 

   189 Construction information is passed to the server side via aType and aParams. 

   190 The server then passes the information to the function CreateInstanceL() inside 

   191 the Anim DLL.

   192 

   193 This function always causes a flush of the window server buffer.

   194 

   195 @param aDevice A window device. 

   196 @param aType The type of this animation object, as understood by CAnimDll::CreateInstanceL(). 

   197 @param aParams Packaged arguments which will be passed to the server side object 

   198 to tell it how to construct itself or initialise itself. 

   199 @return KErrNone if successful, otherwise one of the system-wide error codes. 

   200 @see CAnim::ConstructL()

   201 @see CAnimDll::CreateInstanceL() */

   202 	{

   203 	return iAnimDll->CreateInstance(iHandle, aDevice, aType, aParams, EWsAnimDllOpCreateInstance, NULL);

   204 	}

   205 

   206 EXPORT_C TInt RAnim::Construct(const RWindowBase &aDevice, TInt aType, const TDesC8 &aParams, const TIpcArgs& aIpcArgs)

   207 /** Completes construction of the object based on a window device, and creates 

   208 the server-side animation system. 

   209 

   210 Construction information is passed to the server side via aType and aParams. 

   211 The server then passes the information to the function CreateInstanceL() inside 

   212 the Anim DLL.

   213 

   214 This function always causes a flush of the window server buffer.

   215 

   216 @param aDevice A window device. 

   217 @param aType The type of this animation object, as understood by CAnimDll::CreateInstanceL(). 

   218 @param aParams Packaged arguments which will be passed to the server side object 

   219 to tell it how to construct itself or initialise itself. 

   220 @param aIpcArgs Inter-process communication arguments which will be passed to the server side 

   221 object. Panics if the first "slot" is set to anything other than TIpcArgs::ENothing.

   222 @return KErrNone if successful, otherwise one of the system-wide error codes. 

   223 @see CAnim::ConstructL()

   224 @see CAnimDll::CreateInstanceL() */

   225 	{

   226 	return iAnimDll->CreateInstance(iHandle, aDevice, aType, aParams, EWsAnimDllOpCreateInstance, &aIpcArgs);

   227 	}

   228 

   229 EXPORT_C TInt RAnim::Construct(const RWsSprite &aDevice, TInt aType, const TDesC8 &aParams)

   230 /** Completes construction of the Anim DLL based on a sprite. 

   231 

   232 Construction information is passed to the server side via aType and aParams. 

   233 The server then passes the information to the function CreateInstanceL() inside 

   234 the Anim DLL.

   235 

   236 This function always causes a flush of the window server buffer.

   237 

   238 @param aDevice A sprite. 

   239 @param aType The type of this animation object, as understood by CAnimDll::CreateInstanceL(). 

   240 @param aParams Packaged arguments which will be passed to the server side object 

   241 to tell it how to construct itself or initialise itself. 

   242 @return KErrNone if successful, otherwise one of the system-wide error codes. 

   243 @see CAnim::ConstructL()

   244 @see CAnimDll::CreateInstanceL() */

   245 	{

   246 	return iAnimDll->CreateInstance(iHandle, aDevice, aType, aParams, EWsAnimDllOpCreateInstanceSprite, NULL);

   247 	}

   248 

   249 EXPORT_C TInt RAnim::Construct(const RWsSprite &aDevice, TInt aType, const TDesC8 &aParams, const TIpcArgs& aIpcArgs)

   250 /** Completes construction of the Anim DLL based on a sprite. 

   251 

   252 Construction information is passed to the server side via aType and aParams. 

   253 The server then passes the information to the function CreateInstanceL() inside 

   254 the Anim DLL.

   255 

   256 This function always causes a flush of the window server buffer.

   257 

   258 @param aDevice A sprite. 

   259 @param aType The type of this animation object, as understood by CAnimDll::CreateInstanceL(). 

   260 @param aParams Packaged arguments which will be passed to the server side object 

   261 to tell it how to construct itself or initialise itself. 

   262 @param aIpcArgs Inter-process communication arguments which will be passed to the server side 

   263 object. Panics if the first "slot" is set to anything other than TIpcArgs::ENothing.

   264 @return KErrNone if successful, otherwise one of the system-wide error codes. 

   265 @see CAnim::ConstructL()

   266 @see CAnimDll::CreateInstanceL() */

   267 	{

   268 	return iAnimDll->CreateInstance(iHandle, aDevice, aType, aParams, EWsAnimDllOpCreateInstanceSprite, &aIpcArgs);

   269 	}

   270 

   271 EXPORT_C TInt RAnim::CommandReply(TInt aOpcode)

   272 /** Sends a command to the server-side CAnim instance, and waits for a response. 

   273 

   274 This function executes synchronously and returns the code returned by the 

   275 server-side method CAnim::CommandReplyL(). The request is not buffered.

   276 

   277 @param aOpcode An opcode meaningful to the server-side CAnim-derived class. 

   278 @return A value defined by the animation writer. The value may, in some cases, 

   279 be defined to be an error code.

   280 

   281 This function always causes a flush of the window server buffer. 

   282 

   283 @see Command()

   284 @see AsyncCommandReply()

   285 @see CAnim::CommandReplyL() */

   286 	{

   287 	return(iAnimDll->CommandReply(iHandle,aOpcode));

   288 	}

   289 

   290 EXPORT_C TInt RAnim::CommandReply(TInt aOpcode, const TPtrC8 &aArgs)

   291 /** Sends a command and its arguments to the server-side CAnim instance, and waits 

   292 for a response. 

   293 

   294 The packaged command arguments are passed to the matching server side function, 

   295 where the behaviour should be implemented. The request is not buffered. The 

   296 function executes synchronously and returns the code returned by the server-side 

   297 method CAnim::CommandReplyL().

   298 

   299 This function always causes a flush of the window server buffer. 

   300 

   301 @param aOpcode An opcode meaningful to the server-side CAnim-derived class. 

   302 @param aArgs Packaged arguments which will be passed to the server side object. 

   303 @return A value defined by the animation writer. The value may, in some cases, 

   304 be defined to be an error code. 

   305 @see Command()

   306 @see AsyncCommandReply()

   307 @see CAnim::CommandReplyL() */

   308 	{

   309 	return(iAnimDll->CommandReply(iHandle,aOpcode, aArgs));

   310 	}

   311 

   312 EXPORT_C TInt RAnim::CommandReply(TInt aOpcode, const TDesC8& aArgs, const TIpcArgs& aIpcArgs)

   313 /** Sends a command and its arguments to the server-side CAnim instance, and waits 

   314 for a response. 

   315 

   316 The IPC (inter-process communication) arguments are passed to the matching server side function, 

   317 where the behaviour should be implemented. The request is not buffered. The 

   318 function executes synchronously and returns the code returned by the server-side 

   319 method CAnim::CommandReplyL(). The first slot of the TIpcArgs parameter is reserved for 

   320 internal use. The second slot is used to receive an additional reply from the server-side CAnim.

   321 

   322 This function always causes a flush of the window server buffer. 

   323 

   324 @param aOpcode An opcode meaningful to the server-side CAnim-derived class. 

   325 @param aArgs Packaged arguments which will be passed to the server side object. 

   326 @param aIpcArgs Inter-process communication arguments which will be passed to the server side 

   327 object. Panics if the first "slot" is set to anything other than TIpcArgs::ENothing.

   328 @return A value defined by the animation writer. The value may, in some cases, 

   329 be defined to be an error code. 

   330 @see Command()

   331 @see AsyncCommandReply()

   332 @see CAnim::CommandReplyL() */

   333 	{

   334 	return(iAnimDll->CommandReply(iHandle,aOpcode,aArgs,&aIpcArgs));

   335 	}

   336 

   337 EXPORT_C void RAnim::Command(TInt aOpcode)

   338 /** Sends a command to the server-side CAnim instance, and returns immediately. 

   339 

   340 Commands issued by this function may be buffered before being passed to the 

   341 server.

   342 

   343 Server-side errors cannot be detected, so Command() should not be used for 

   344 operations which could fail or which may leave. Use CommandReply() for those. 

   345 Although the window server will not fail due to errors not being returned 

   346 to the client side, client side behaviour will almost certainly not be correct 

   347 if errors have been generated but not received.

   348 

   349 Use of this function results in a server-side call to the equivalent CAnim::Command().

   350 

   351 @param aOpcode An operation meaningful to the server-side CAnim object. 

   352 @see CommandReply()

   353 @see AsyncCommandReply()

   354 @see CAnim::Command() */

   355 	{

   356 	iAnimDll->Command(iHandle,aOpcode);

   357 	}

   358 

   359 EXPORT_C void RAnim::Command(TInt aOpcode, const TPtrC8 &aArgs)

   360 /** Sends a command and its arguments to the server-side CAnim instance, and returns 

   361 immediately. 

   362 

   363 Commands issued by this function may be buffered before being passed to the 

   364 server.

   365 

   366 Server-side errors cannot be detected, so Command() should not be used for 

   367 operations which could fail or which may leave. Use CommandReply() for those. 

   368 Although the window server will not fail due to errors not being returned 

   369 to the client side, client side behaviour will almost certainly not be correct 

   370 if errors have been generated but not received.

   371 

   372 Use of this function results in a server-side call to the equivalent CAnim::Command().

   373 

   374 @param aOpcode An operation meaningful to the server-side CAnim object. 

   375 @param aArgs Packaged arguments which will be passed to the server side object. 

   376 

   377 @see CommandReply()

   378 @see AsyncCommandReply()

   379 @see CAnim::Command() */

   380 	{

   381 	iAnimDll->Command(iHandle,aOpcode, aArgs);

   382 	}

   383 

   384 EXPORT_C void RAnim::AsyncCommandReply(TRequestStatus& aRequestStatus,TInt aOpcode, const TIpcArgs& aIpcArgs)

   385 /** Sends a command and its arguments to the server-side CAnim instance asynchronously. 

   386 

   387 The IPC (inter-process communication) arguments are passed to the CAnim-derived class' 

   388 CommandReplyL function, where the behaviour should be implemented. The request is not 

   389 buffered - rather the function executes asynchronously. The first and second slots of the 

   390 TIpcArgs parameter are reserved for internal use. 

   391 

   392 If the code calling this function is itself an API that is asynchronous (i.e. if the 

   393 TRequestStatus passed into this function is simply a parameter to a higher-level API), then that 

   394 higher-level API should typically provide a corresponding "Cancel" function that its own clients 

   395 can use to cancel their asynchronous request - this would typically be implemented by the 

   396 higher-level API by using RAnim::CommandReply.

   397 

   398 @param aRequestStatus Set initially by the function to KRequestPending. Then when this 

   399 asynchronous function at some potentially later point in time "completes", aRequestStatus 

   400 is set to the completion code which is a value defined by the animation writer (i.e. the value 

   401 that the server-side CAnim-derived class' CommandReplyL returns or leaves with). The value may, 

   402 in some cases, be defined to be an error code. 

   403 @param aOpcode An opcode meaningful to the server-side CAnim-derived class. 

   404 @param aIpcArgs Inter-process communication arguments which will be passed to the server side 

   405 object. Panics if either the first or second "slot" is set to anything other than 

   406 TIpcArgs::ENothing.

   407 

   408 @see CommandReply()

   409 @see Command()

   410 @see CAnim::CommandReplyL() */

   411 	{

   412 	TIpcArgs ipcArgs;

   413 	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

   414 	// check that the caller hasn't used the first or second slot (the first is set by the RAnimDll::AsyncCommandReply call below)

   415 	ipcArgs.Set(KAsyncMessageSlotAnimDllHandle,TIpcArgs::ENothing);

   416 	ipcArgs.Set(KAsyncMessageSlotAnimHandle,TIpcArgs::ENothing);

   417 	__ASSERT_ALWAYS(Mem::Compare(REINTERPRET_CAST(const TUint8*, &ipcArgs), sizeof(TIpcArgs), REINTERPRET_CAST(const TUint8*, &aIpcArgs), sizeof(TIpcArgs))==0,Panic(EW32PanicUsingReservedIpcSlot));

   418 	ipcArgs.Set(KAsyncMessageSlotAnimHandle,iHandle);

   419 	iAnimDll->AsyncCommandReply(aRequestStatus, aOpcode, ipcArgs);

   420 	}

   421 

   422 EXPORT_C void RAnim::Close()

   423 /** Sends the close command.

   424 

   425 This frees resources belonging to an animation object. It would be called 

   426 to release resources when the RAnim is owned in-line by another object (so 

   427 that destruction is automatic). 

   428 

   429 This function always causes a flush of the window server buffer. */

   430 	{

   431 	if (iHandle!=0)

   432 		{

   433 		iAnimDll->DestroyInstance(iHandle);

   434 		iHandle=0;

   435 		}

   436 	}

   437 

   438 EXPORT_C void RAnim::Destroy()

   439 /** Closes and deletes the server-side animation object. 

   440 

   441 This should be called on heap allocated objects. 

   442 

   443 This function always causes a flush of the window server buffer. */

   444 	{

   445 	Close();

   446 	delete this;

   447 	}