1 // Copyright (c) 2002-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".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
17 #ifndef __MMFCONTROLLERFRAMEWORK_H__
18 #define __MMFCONTROLLERFRAMEWORK_H__
23 #include <mmf/common/mmfutilities.h>
24 #include <mmf/common/mmfcontrollerframeworkbase.h>
25 #include <mmf/common/mmfipc.h>
28 class CMMFControllerImplementationInformation;
31 _LIT(KMMFControllerProxyServerName, "MMFControllerProxyServer-");
37 Signals that the message is destined for the controller
39 const TInt KMMFObjectHandleController = -2;
45 Null, or invalid, object handle
47 const TInt KMMFObjectHandleNull = 0;
53 Describes the destination of a message in the controller framework.
55 The destination is defined by a UID describing the interface and an integer object handle.
56 The controller framework uses this information when it receives a message to decide where
59 The controller plugin and controller proxy use the special constant handles
60 KMMFObjectHandleControllerProxy and KMMFObjectHandleController for
65 class TMMFMessageDestination
72 Assigns a null UID to the interface, and a null handle to the handle.
76 IMPORT_C TMMFMessageDestination();
79 Constructor for sending messages to the controller plugin.
81 Assigns KMMFObjectHandleController to the destination handle.
84 The UID of the interface of this message destination.
88 IMPORT_C TMMFMessageDestination(TUid aInterfaceId);
94 The UID of the interface of this message destination.
95 @param aDestinationHandle
96 The handle of the destination object in the controller framework.
100 IMPORT_C TMMFMessageDestination(TUid aInterfaceId, TInt aDestinationHandle);
106 The TMMFMessageDestination object to be copied.
110 IMPORT_C TMMFMessageDestination(const TMMFMessageDestination& aOther);
113 Returns the UID of the interface of the message destination.
115 @return The interface UID.
119 IMPORT_C TUid InterfaceId() const;
122 Returns the handle of the destination object in the controller framework.
124 @return The destination handle.
128 IMPORT_C TInt DestinationHandle() const;
131 Compares two destinations.
134 The object to be compared with this object.
136 @return A boolean indicating if the objects are the same. ETrue if the objects are the same,
137 EFalse if the objects are different.
141 IMPORT_C TBool operator==(const TMMFMessageDestination& aOther) const;
145 TInt iDestinationHandle;
147 This member is internal and not intended for use.
158 Package buffer for TMMFMessageDestination
160 typedef TPckgBuf<TMMFMessageDestination> TMMFMessageDestinationPckg;
167 Encapsulation of an RMessage or an RMessage2 to provide protection to controller plugins
168 from the changes occurring with secure APIs.
170 Adds required destination information to the message so the controller framework
171 can determine which object the message is for.
173 Adds capability to check whether the message has been completed.
175 Allows two descriptors to be read from the client, and one descriptor to be copied to the client.
177 @see RMMFControllerProxy::SendSync
178 @see RMMFControllerProxy::SendAsync
184 friend class CMMFControllerProxySession;
185 friend class CMMFDevSoundSession;
191 A controller plugin should use this to take a copy of the message when it must wait for some
192 other event before completing it.
195 The message object to copy.
199 IMPORT_C TMMFMessage(const TMMFMessage& aMessage);
202 Returns the destination of the message.
204 @return The destination of the message, consisting of a UID defining the interface and the
205 handle of the destination object.
209 IMPORT_C const TMMFMessageDestination& Destination();
212 Returns an integer describing the function being called. Equivalent to
213 RMessage::Function().
215 @return The function being called over IPC.
217 @see RMessage::Function()
221 IMPORT_C TInt Function();
224 Returns the size of the first descriptor that can be copied over from the client.
226 Use this to create a descriptor of appropriate size before reading the data from the client.
228 @return The size of data 1.
231 IMPORT_C TInt SizeOfData1FromClient();
234 Copy the first descriptor from the client.
237 A descriptor defining the area of memory into which the data from the client
238 will be copied. Note, the descriptor must be of sufficient size.
240 @return One of the system-wide error codes. In particular, KErrBadDescriptor will be returned
241 if the client did not provide a valid descriptor.
245 IMPORT_C TInt ReadData1FromClient(TDes8& aDes);
248 Copy the first descriptor from the client.
250 This functino can leave with one of the system-wide error codes. In particular, the leave code
251 KErrBadDescriptor will be used if the client did not provide a valid descriptor.
254 A descriptor defining the area of memory into which the data from the client
255 will be copied. Note, the descriptor must be of sufficient size.
259 IMPORT_C void ReadData1FromClientL(TDes8& aDes);
263 Returns the size of the second descriptor that can be copied over from the client.
265 Use this to create a descriptor of appropriate size before reading the data from the client.
267 @return The size of data 2.
271 IMPORT_C TInt SizeOfData2FromClient();
274 Copies the second descriptor from the client.
277 A descriptor defining the area of memory into which the data from the client
278 will be copied. Note, the descriptor must be of sufficient size.
280 @return One of the system-wide error codes. In particular, KErrBadDescriptor will be returned
281 if the client did not provide a valid descriptor.
285 IMPORT_C TInt ReadData2FromClient(TDes8& aDes);
288 Copies the second descriptor from the client.
290 This function can leave with one of the system-wide error codes. In particular, the leave code
291 KErrBadDescriptor will be used if the client did not provide a valid descriptor.
294 A descriptor defining the area of memory into which the data from the client
295 will be copied. Note, the descriptor must be of sufficient size.
299 IMPORT_C void ReadData2FromClientL(TDes8& aDes);
302 Copies data back to the client.
305 The data to be copied back to the client. Note that the client must
306 have already created a descriptor of sufficient size for the data to be
309 @return One of the system-wide error codes. In particular, the error code KErrBadDescriptor will
310 be returned if the client did not provide a valid descriptor.
314 IMPORT_C TInt WriteDataToClient(const TDesC8& aDes);
317 Copies the data back to the client.
319 This function can leave with one of the system-wide error codes. In particular, the leave code
320 KErrBadDescriptor will be used if the client did not provide a valid descriptor.
323 The data to be copied back to the client. Note that the client must have already
324 created a descriptor of sufficient size for the data to be copied into.
328 IMPORT_C void WriteDataToClientL(const TDesC8& aDes);
331 Signals to the client that its request has been completed.
333 Equivalent to RMessage::Complete.
336 The result code to be given back to the client.
340 IMPORT_C void Complete(TInt aReason);
342 IMPORT_C void AdoptFileHandleFromClientL(TInt aFsHandleIndex, TInt aFileHandleIndex, RFile& aFile);
345 Checks whether this message has already been completed.
347 @return A boolean indicating if the message has been completed. ETrue if the message has been
348 completed, EFalse if not.
352 IMPORT_C TBool IsCompleted();
355 Constructs a TMMFMessage from an RMmfIpcMessage.
358 The handle to the remote message.
362 IMPORT_C TMMFMessage(const RMmfIpcMessage& aMessage);
365 Gets the destination info from the client.
369 IMPORT_C void FetchDestinationL();
371 #ifdef __MMF_USE_IPC_V2__
373 The encapsulated message
375 RMessagePtr2 iMessage;
377 The encapsulated function
381 Private padding to preserve BC with earlier versions
383 TInt iDummyPadding[6];
386 The RMessage encapsulated by this object.
389 #endif // __MMF_USE_IPC_V2__
392 The destination of this message.
394 TMMFMessageDestination iDestination;
397 Defines whether this object has yet to be completed.
405 Mixin class used by CLogonMonitor to inform about its state
409 class MLogonMonitorObserver
413 The monitored thread has been terminated.
415 virtual void ThreadTerminated() = 0;
421 RSessionBase-based client class to handle the creation of the controller thread and
422 message sending over IPC.
424 The controller proxy is responsible for sending and recieving messages over IPC; it does not
425 care exactly what those messages are.
427 Note the fact that, although this is an internal component, its size cannot be changed because
428 it's embedded in a publishedAll class (RMMFController) and the size of the latter would also be
429 changed raising a binary compatibility problem.
433 NONSHARABLE_CLASS(RMMFControllerProxy) : public RMmfSessionBase, public MLogonMonitorObserver
441 IMPORT_C RMMFControllerProxy();
444 Create a new thread and load a controller plugin into that thread.
446 @param aControllerUid
447 The UID of the controller plugin to be loaded.
448 @param aUseSharedHeap
449 If this value is EFalse each controller is created with its own heap. The alternative,
450 if the value is ETrue, is that controllers share a special heap with other controllers
451 created the same way. Each heap uses a chunk, so this avoids situations where the
452 number of chunks per process is limited. The default behaviour is generally to be
453 preferred, and should give lower overall memory usage. However, if many controllers are
454 to be created for a particular thread, then ETrue should be provided to prevent running
455 out of heaps or chunks.
457 @return One of the system-wide error codes.
460 IMPORT_C TInt LoadController(TUid aControllerUid, TBool aUseSharedHeap);
463 Create a new thread and load a controller plugin into that thread.
465 @param aControllerInfo
466 A reference to a CMMFControllerImplementationInformation object
467 used for determining the controller UID and heap size
468 @param aUseSharedHeap
469 If this value is EFalse each controller is created with its own heap. The alternative,
470 if the value is ETrue, is that controllers share a special heap with other controllers
471 created the same way. Each heap uses a chunk, so this avoids situations where the
472 number of chunks per process is limited. The default behaviour is generally to be
473 preferred, and should give lower overall memory usage. However, if many controllers are
474 to be created for a particular thread, then ETrue should be provided to prevent running
475 out of heaps or chunks.
477 @return One of the system-wide error codes.
480 IMPORT_C TInt LoadController(const CMMFControllerImplementationInformation& aControllerInfo, TBool aUseSharedHeap);
483 Create a new thread in another process through Secure DRM Plugin server and load a controller plugin
484 into that thread. The motivation of this model is to allow applications without DRM capability able
485 to play protected content through MMF.
487 @param aControllerUid
488 The UID of the controller plugin to be loaded.
489 @param aUseSharedHeap
490 If this value is EFalse each controller is created with its own heap. The alternative,
491 if the value is ETrue, is that controllers share a special heap with other controllers
492 created the same way. Each heap uses a chunk, so this avoids situations where the
493 number of chunks per process is limited. The default behaviour is generally to be
494 preferred, and should give lower overall memory usage. However, if many controllers are
495 to be created for a particular thread, then ETrue should be provided to prevent running
496 out of heaps or chunks.
498 @return One of the system-wide error codes.
500 IMPORT_C TInt LoadControllerInSecureDRMProcess(TUid aControllerUid, TBool aUseSharedHeap);
503 Create a new thread in another process through Secure DRM Plugin server and load a controller plugin
504 into that thread. The motivation of this model is to allow applications without DRM capability able
505 to play protected content through MMF.
507 @param aControllerInfo
508 A reference to a CMMFControllerImplementationInformation object
509 used for determining the controller UID and heap size
510 @param aUseSharedHeap
511 If this value is EFalse each controller is created with its own heap. The alternative,
512 if the value is ETrue, is that controllers share a special heap with other controllers
513 created the same way. Each heap uses a chunk, so this avoids situations where the
514 number of chunks per process is limited. The default behaviour is generally to be
515 preferred, and should give lower overall memory usage. However, if many controllers are
516 to be created for a particular thread, then ETrue should be provided to prevent running
517 out of heaps or chunks.
519 @return One of the system-wide error codes.
521 IMPORT_C TInt LoadControllerInSecureDRMProcess(const CMMFControllerImplementationInformation& aControllerInfo, TBool aUseSharedHeap);
524 Delete the controller plugin and close its thread.
526 Clients must call Close() on the controller proxy, otherwise leaks will occur.
530 IMPORT_C void Close();
533 Send a message synchronously to the controller thread.
535 The controller framework will analyze the message to determine its correct destination.
537 Note: This method will not return until the controller framework has serviced the command.
540 The destination of the message, consisting of the uid of
541 the interface of this message.
543 The function number to indicate which function is to be called
544 on the interface defined in the aDestination parameter.
546 A reference to the first chunk of data to be copied to the controller
547 framework. The exact contents of the data are dependent on the
548 interface being called. Can be NULL.
550 A reference to the second chunk of data to be copied to the controller
551 framework. The exact contents of the data are dependent on the
552 interface being called. Can be NULL.
554 A reference to an area of memory to which the controller framework will
555 write any data to be passed back to the client. Can't be NULL.
557 @return The result of the request. Exact range of values is dependent on the interface.
560 IMPORT_C TInt SendSync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom) const;
563 Send a message synchronously to the controller thread.
565 The controller framework will analyze the message to determine its correct destination.
567 Note: This method will not return until the controller framework has serviced the command.
570 The destination of the message, consisting of the uid of
571 the interface of this message.
573 The function number to indicate which function is to be called
574 on the interface defined in the aDestination parameter.
576 A reference to the first chunk of data to be copied to the controller
577 framework. The exact contents of the data are dependent on the
578 interface being called. Can be NULL.
580 A reference to the second chunk of data to be copied to the controller
581 framework. The exact contents of the data are dependent on the
582 interface being called. Can be NULL.
584 @return The result of the request. Exact range of values is dependent on the interface.
587 IMPORT_C TInt SendSync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2) const;
590 Send a message asynchronously to the controller thread.
592 The controller framework will analyze the message to determine its correct destination.
594 Note: This method will return immediately. The RunL of the active object owning the
595 aStatus parameter will be called when the command is completed by the
596 controller framework.
599 The destination of the message, consisting of the uid of
600 the interface of this message.
602 The function number to indicate which function is to be called
603 on the interface defined in the aDestination parameter.
605 A reference to the first chunk of data to be copied to the controller
606 framework. The exact contents of the data are dependent on the
607 interface being called. Can be NULL.
609 A reference to the second chunk of data to be copied to the controller
610 framework. The exact contents of the data are dependent on the
611 interface being called. Can be NULL.
613 A reference to an area of memory to which the controller framework will
614 write any data to be passed back to the client. Can't be NULL.
616 The TRequestStatus of an active object. This will contain the
617 result of the request on completion. The exact range of
618 result values is dependent on the interface.
622 IMPORT_C void SendAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom, TRequestStatus& aStatus) const;
625 Send a message asynchronously to the controller thread.
627 The controller framework will analyze the message to determine its correct destination.
629 Note: This method will return immediately. The RunL of the active object owning the
630 aStatus parameter will be called when the command is completed by the
631 controller framework.
634 The destination of the message, consisting of the uid of
635 the interface of this message.
637 The function number to indicate which function is to be called
638 on the interface defined in the aDestination parameter.
640 A reference to the first chunk of data to be copied to the controller
641 framework. The exact contents of the data are dependent on the
642 interface being called. Can be NULL.
644 A reference to the second chunk of data to be copied to the controller
645 framework. The exact contents of the data are dependent on the
646 interface being called. Can be NULL.
648 The TRequestStatus of an active object. This will contain the
649 result of the request on completion. The exact range of
650 result values is dependent on the interface.
654 IMPORT_C void SendAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TRequestStatus& aStatus) const;
656 IMPORT_C TInt SendSync(TInt aFunction, const TIpcArgs& aIpcArgs) const;
657 IMPORT_C void SendAsync(TInt aFunction, const TIpcArgs& aIpcArgs, TRequestStatus& aStatus) const;
659 Register to receive events from the controller framework.
661 Events can be generated at any time, and are generally associated with things that occur
662 due to something happening internally within the controller. For example, an event will
663 be generated if the controller stops playing due to reaching the end of a file.
666 A reference to a TMMFEventPckg object that must be member data
667 of the active object calling this method. The details of the event
668 will be copied into this object when an event occurs.
670 The TRequestStatus of the active object calling this method.
673 @see CMMFControllerEventMonitor
676 IMPORT_C void ReceiveEvents(TMMFEventPckg& aEvent, TRequestStatus& aStatus);
679 Cancel a previous registration to receive events from the controller framework.
681 This must be called from the DoCancel() method of the active object using the
684 @return One of the standard system-wide error codes.
689 IMPORT_C TInt CancelReceiveEvents();
692 Set the priority of the controller's sub thread.
694 This can be used to increase the responsiveness of the audio plugin to minimise
695 any lag in processing. This function should be used with care as it may have knock-on
696 effects elsewhere in the system.
699 The TThreadPriority that the thread should run under. The default is EPriorityNormal.
701 A standard error code: KErrNone if successful, KErrNotReady if the thread does not have a
704 IMPORT_C TInt SetThreadPriority(const TThreadPriority& aPriority) const;
707 The controller subthread has been terminated.
709 This is called by CLogonMonitor when the the thread terminates
711 void ThreadTerminated();
714 Creates the new thread
716 TInt DoCreateSubThread(RServer2* aServer2, TUint aMaxHeapSize, TBool aUseSharedHeap, TUint aStackSize);
719 Determines the maximum heap size required by the selected controller
721 TUint ControllersMaxHeapSizeL(TUid aControllerUid);
724 Load a controller by UID
726 @param aControllerUid
727 The UID of the controller plugin to be loaded.
728 @param aControllerInfo
729 A reference to a CMMFControllerImplementationInformation object
730 used for determining the heap size and DRM server supporting state.
731 @param aUseSharedHeap
732 If this value is EFalse each controller is created with its own heap. The alternative,
733 if the value is ETrue, is that controllers share a special heap with other controllers
734 created the same way. Each heap uses a chunk, so this avoids situations where the
735 number of chunks per process is limited. The default behaviour is generally to be
736 preferred, and should give lower overall memory usage. However, if many controllers are
737 to be created for a particular thread, then ETrue should be provided to prevent running
738 out of heaps or chunks.
740 The indicator supplied from user used to determine whether the user's process has DRM
743 One of the system-wide error codes.
745 TInt LoadController(TUid aControllerUid, const CMMFControllerImplementationInformation& aControllerInfo, TBool aUseSharedHeap,
746 TBool aNoDRMCap = EFalse);
749 Release heap - for use when a shared heap has been registered
754 Create a session to handle situation of playing DRM protected content in
755 process with no DRM capability.
756 DRM server process will be created, if not yet created. This server is responsible to
757 manage and monitor all the MMF Controller servers created as seperate threads belong to
758 DRM server process. Once the new MMF Controller server is running, a MMF Controller server
759 session will be created and the handle is passing back.
761 TInt DoCreateSessionForNoDRMCapClient(TUint aMaxHeapSize, TBool aUseSharedHeap, TUint aStackSize);
767 Shared heap has been opened for this object, and must be closed
769 EFlagOpenedSharedHeap=0x01
774 The thread in which the controller plugin will run.
778 Used to hold destination for messages from the controller proxy
779 (not from clients calling SendSync/SendAsync!!)
781 TMMFMessageDestinationPckg iDestinationPckg;
783 Used to determine the success of a logon. If the status is not pending, the logon has failed
784 and the thread should be closed.
786 CLogonMonitor* iLogonAO;
788 The priority at which the controller plugin thread runs.
790 TThreadPriority iThreadPriority;
796 This member is internal and not intended for use.
805 Mixin class to define an object capable of handling an event within the controller framework.
807 class MAsyncEventHandler
812 Sends an event to the client.
819 virtual TInt SendEventToClient(const TMMFEvent& aEvent) = 0;
822 #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS
823 #include <mmf/common/mmfcontrollerframeworkclasses.h>