1.1 --- a/epoc32/include/mmf/common/mmfcontrollerframework.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/mmf/common/mmfcontrollerframework.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,1268 @@
1.4 -mmfcontrollerframework.h
1.5 +// Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +// All rights reserved.
1.7 +// This component and the accompanying materials are made available
1.8 +// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
1.9 +// which accompanies this distribution, and is available
1.10 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +//
1.12 +// Initial Contributors:
1.13 +// Nokia Corporation - initial contribution.
1.14 +//
1.15 +// Contributors:
1.16 +//
1.17 +// Description:
1.18 +//
1.19 +
1.20 +
1.21 +#ifndef __MMFCONTROLLERFRAMEWORK_H__
1.22 +#define __MMFCONTROLLERFRAMEWORK_H__
1.23 +
1.24 +#include <e32base.h>
1.25 +#include <e32std.h>
1.26 +#include <f32file.h>
1.27 +#include <mmf/common/mmfutilities.h>
1.28 +#include <mmf/common/mmfcontrollerframeworkbase.h>
1.29 +#include <mmf/common/mmfipc.h>
1.30 +
1.31 +// fwd ref
1.32 +class CMMFControllerImplementationInformation;
1.33 +class CLogonMonitor;
1.34 +
1.35 +_LIT(KMMFControllerProxyServerName, "MMFControllerProxyServer-");
1.36 +
1.37 +/**
1.38 +@internalComponent
1.39 +*/
1.40 +#define KMMFControllerProxyVersion TVersion(7,1,1)
1.41 +
1.42 +/**
1.43 +@internalComponent
1.44 +*/
1.45 +const TInt KMMFControllerProxyMaxHeapSize = 0x1000000;//16MB
1.46 +
1.47 +/**
1.48 +@internalComponent
1.49 +*/
1.50 +const TInt KMMFControllerProxyMaxCachedMessages = 10;
1.51 +
1.52 +/**
1.53 +@internalComponent
1.54 +
1.55 +Signals that the message is destined for the controller proxy
1.56 +*/
1.57 +const TInt KMMFObjectHandleControllerProxy = -1;
1.58 +
1.59 +/**
1.60 +@publishedAll
1.61 +@released
1.62 +
1.63 +Signals that the message is destined for the controller
1.64 +*/
1.65 +const TInt KMMFObjectHandleController = -2;
1.66 +
1.67 +/**
1.68 +@publishedAll
1.69 +@released
1.70 +
1.71 +Null, or invalid, object handle
1.72 +*/
1.73 +const TInt KMMFObjectHandleNull = 0;
1.74 +/**
1.75 +@internalComponent
1.76 +
1.77 +The first valid object handle. The MMF Object container will
1.78 +begin iterating from here when generating object handles.
1.79 +*/
1.80 +const TInt KMMFObjectHandleFirstValid = 1;
1.81 +
1.82 +/**
1.83 +@internalComponent
1.84 +*/
1.85 +const TInt KMmfControllerThreadShutdownTimeout = 20000000; // 20 seconds
1.86 +
1.87 +/**
1.88 +@internalComponent
1.89 +
1.90 +The UID and messages associated with the controller proxy interface.
1.91 +*/
1.92 +const TUid KUidInterfaceMMFControllerProxy = {0x101F77E7};
1.93 +
1.94 +/**
1.95 +@internalComponent
1.96 +
1.97 +Struct to allow RMMFController to pass several parameters to new CControllerProxyServer threads.
1.98 +*/
1.99 +struct TControllerProxyServerParams
1.100 + {
1.101 + RServer2* iServer;
1.102 + TBool iUsingSharedHeap;
1.103 + };
1.104 +
1.105 +
1.106 +/**
1.107 +@internalComponent
1.108 +*/
1.109 +enum TMMFControllerProxyMessages
1.110 + {
1.111 + EMMFControllerProxyLoadControllerPluginByUid,
1.112 + EMMFControllerProxyReceiveEvents,
1.113 + EMMFControllerProxyCancelReceiveEvents
1.114 + };
1.115 +
1.116 +
1.117 +/**
1.118 +@publishedAll
1.119 +@released
1.120 +
1.121 +Describes the destination of a message in the controller framework.
1.122 +
1.123 +The destination is defined by a UID describing the interface and an integer object handle.
1.124 +The controller framework uses this information when it receives a message to decide where
1.125 +to send the message.
1.126 +
1.127 +The controller plugin and controller proxy use the special constant handles
1.128 +KMMFObjectHandleControllerProxy and KMMFObjectHandleController for
1.129 +efficiency.
1.130 +
1.131 +@since 7.0s
1.132 +*/
1.133 +class TMMFMessageDestination
1.134 + {
1.135 +public:
1.136 +
1.137 + /**
1.138 + Default constructor.
1.139 +
1.140 + Assigns a null UID to the interface, and a null handle to the handle.
1.141 +
1.142 + @since 7.0s
1.143 + */
1.144 + IMPORT_C TMMFMessageDestination();
1.145 +
1.146 + /**
1.147 + Constructor for sending messages to the controller plugin.
1.148 +
1.149 + Assigns KMMFObjectHandleController to the destination handle.
1.150 +
1.151 + @param aInterfaceId
1.152 + The UID of the interface of this message destination.
1.153 +
1.154 + @since 7.0s
1.155 + */
1.156 + IMPORT_C TMMFMessageDestination(TUid aInterfaceId);
1.157 +
1.158 + /**
1.159 + Full constructor.
1.160 +
1.161 + @param aInterfaceId
1.162 + The UID of the interface of this message destination.
1.163 + @param aDestinationHandle
1.164 + The handle of the destination object in the controller framework.
1.165 +
1.166 + @since 7.0s
1.167 + */
1.168 + IMPORT_C TMMFMessageDestination(TUid aInterfaceId, TInt aDestinationHandle);
1.169 +
1.170 + /**
1.171 + Copy constructor.
1.172 +
1.173 + @param aOther
1.174 + The TMMFMessageDestination object to be copied.
1.175 +
1.176 + @since 7.0s
1.177 + */
1.178 + IMPORT_C TMMFMessageDestination(const TMMFMessageDestination& aOther);
1.179 +
1.180 + /**
1.181 + Returns the UID of the interface of the message destination.
1.182 +
1.183 + @return The interface UID.
1.184 +
1.185 + @since 7.0s
1.186 + */
1.187 + IMPORT_C TUid InterfaceId() const;
1.188 +
1.189 + /**
1.190 + Returns the handle of the destination object in the controller framework.
1.191 +
1.192 + @return The destination handle.
1.193 +
1.194 + @since 7.0s
1.195 + */
1.196 + IMPORT_C TInt DestinationHandle() const;
1.197 +
1.198 + /**
1.199 + Compares two destinations.
1.200 +
1.201 + @param aOther
1.202 + The object to be compared with this object.
1.203 +
1.204 + @return A boolean indicating if the objects are the same. ETrue if the objects are the same,
1.205 + EFalse if the objects are different.
1.206 +
1.207 + @since 7.0s
1.208 + */
1.209 + IMPORT_C TBool operator==(const TMMFMessageDestination& aOther) const;
1.210 +
1.211 +private:
1.212 + TUid iInterfaceId;
1.213 + TInt iDestinationHandle;
1.214 + /**
1.215 + This member is internal and not intended for use.
1.216 + */
1.217 + TInt iReserved1;
1.218 + TInt iReserved2;
1.219 + TInt iReserved3;
1.220 + };
1.221 +
1.222 +/**
1.223 +@publishedAll
1.224 +@released
1.225 +
1.226 +Package buffer for TMMFMessageDestination
1.227 +*/
1.228 +typedef TPckgBuf<TMMFMessageDestination> TMMFMessageDestinationPckg;
1.229 +
1.230 +
1.231 +/**
1.232 +@publishedAll
1.233 +@released
1.234 +
1.235 +Encapsulation of an RMessage or an RMessage2 to provide protection to controller plugins
1.236 +from the changes occurring with secure APIs.
1.237 +
1.238 +Adds required destination information to the message so the controller framework
1.239 +can determine which object the message is for.
1.240 +
1.241 +Adds capability to check whether the message has been completed.
1.242 +
1.243 +Allows two descriptors to be read from the client, and one descriptor to be copied to the client.
1.244 +
1.245 +@see RMMFControllerProxy::SendSync
1.246 +@see RMMFControllerProxy::SendAsync
1.247 +
1.248 +@since 7.0s
1.249 +*/
1.250 +class TMMFMessage
1.251 + {
1.252 +friend class CMMFControllerProxySession;
1.253 +friend class CMMFDevSoundSession;
1.254 +public:
1.255 +
1.256 + /**
1.257 + Copy constructor.
1.258 +
1.259 + A controller plugin should use this to take a copy of the message when it must wait for some
1.260 + other event before completing it.
1.261 +
1.262 + @param aMessage
1.263 + The message object to copy.
1.264 +
1.265 + @since 7.0s
1.266 + */
1.267 + IMPORT_C TMMFMessage(const TMMFMessage& aMessage);
1.268 +
1.269 + /**
1.270 + Returns the destination of the message.
1.271 +
1.272 + @return The destination of the message, consisting of a UID defining the interface and the
1.273 + handle of the destination object.
1.274 +
1.275 + @since 7.0s
1.276 + */
1.277 + IMPORT_C const TMMFMessageDestination& Destination();
1.278 +
1.279 + /**
1.280 + Returns an integer describing the function being called. Equivalent to
1.281 + RMessage::Function().
1.282 +
1.283 + @return The function being called over IPC.
1.284 +
1.285 + @see RMessage::Function()
1.286 +
1.287 + @since 7.0s
1.288 + */
1.289 + IMPORT_C TInt Function();
1.290 +
1.291 + /**
1.292 + Returns the size of the first descriptor that can be copied over from the client.
1.293 +
1.294 + Use this to create a descriptor of appropriate size before reading the data from the client.
1.295 +
1.296 + @return The size of data 1.
1.297 + @since 7.0s
1.298 + */
1.299 + IMPORT_C TInt SizeOfData1FromClient();
1.300 +
1.301 + /**
1.302 + Copy the first descriptor from the client.
1.303 +
1.304 + @param aDes
1.305 + A descriptor defining the area of memory into which the data from the client
1.306 + will be copied. Note, the descriptor must be of sufficient size.
1.307 +
1.308 + @return One of the system-wide error codes. In particular, KErrBadDescriptor will be returned
1.309 + if the client did not provide a valid descriptor.
1.310 +
1.311 + @since 7.0s
1.312 + */
1.313 + IMPORT_C TInt ReadData1FromClient(TDes8& aDes);
1.314 +
1.315 + /**
1.316 + Copy the first descriptor from the client.
1.317 +
1.318 + This functino can leave with one of the system-wide error codes. In particular, the leave code
1.319 + KErrBadDescriptor will be used if the client did not provide a valid descriptor.
1.320 +
1.321 + @param aDes
1.322 + A descriptor defining the area of memory into which the data from the client
1.323 + will be copied. Note, the descriptor must be of sufficient size.
1.324 +
1.325 + @since 7.0s
1.326 + */
1.327 + IMPORT_C void ReadData1FromClientL(TDes8& aDes);
1.328 +
1.329 +
1.330 + /**
1.331 + Returns the size of the second descriptor that can be copied over from the client.
1.332 +
1.333 + Use this to create a descriptor of appropriate size before reading the data from the client.
1.334 +
1.335 + @return The size of data 2.
1.336 +
1.337 + @since 7.0s
1.338 + */
1.339 + IMPORT_C TInt SizeOfData2FromClient();
1.340 +
1.341 + /**
1.342 + Copies the second descriptor from the client.
1.343 +
1.344 + @param aDes
1.345 + A descriptor defining the area of memory into which the data from the client
1.346 + will be copied. Note, the descriptor must be of sufficient size.
1.347 +
1.348 + @return One of the system-wide error codes. In particular, KErrBadDescriptor will be returned
1.349 + if the client did not provide a valid descriptor.
1.350 +
1.351 + @since 7.0s
1.352 + */
1.353 + IMPORT_C TInt ReadData2FromClient(TDes8& aDes);
1.354 +
1.355 + /**
1.356 + Copies the second descriptor from the client.
1.357 +
1.358 + This function can leave with one of the system-wide error codes. In particular, the leave code
1.359 + KErrBadDescriptor will be used if the client did not provide a valid descriptor.
1.360 +
1.361 + @param aDes
1.362 + A descriptor defining the area of memory into which the data from the client
1.363 + will be copied. Note, the descriptor must be of sufficient size.
1.364 +
1.365 + @since 7.0s
1.366 + */
1.367 + IMPORT_C void ReadData2FromClientL(TDes8& aDes);
1.368 +
1.369 + /**
1.370 + Copies data back to the client.
1.371 +
1.372 + @param aDes
1.373 + The data to be copied back to the client. Note that the client must
1.374 + have already created a descriptor of sufficient size for the data to be
1.375 + copied into.
1.376 +
1.377 + @return One of the system-wide error codes. In particular, the error code KErrBadDescriptor will
1.378 + be returned if the client did not provide a valid descriptor.
1.379 +
1.380 + @since 7.0s
1.381 + */
1.382 + IMPORT_C TInt WriteDataToClient(const TDesC8& aDes);
1.383 +
1.384 + /**
1.385 + Copies the data back to the client.
1.386 +
1.387 + This function can leave with one of the system-wide error codes. In particular, the leave code
1.388 + KErrBadDescriptor will be used if the client did not provide a valid descriptor.
1.389 +
1.390 + @param aDes
1.391 + The data to be copied back to the client. Note that the client must have already
1.392 + created a descriptor of sufficient size for the data to be copied into.
1.393 +
1.394 + @since 7.0s
1.395 + */
1.396 + IMPORT_C void WriteDataToClientL(const TDesC8& aDes);
1.397 +
1.398 + /**
1.399 + Signals to the client that its request has been completed.
1.400 +
1.401 + Equivalent to RMessage::Complete.
1.402 +
1.403 + @param aReason
1.404 + The result code to be given back to the client.
1.405 +
1.406 + @since 7.0s
1.407 + */
1.408 + IMPORT_C void Complete(TInt aReason);
1.409 +
1.410 + IMPORT_C void AdoptFileHandleFromClientL(TInt aFsHandleIndex, TInt aFileHandleIndex, RFile& aFile);
1.411 +
1.412 + /**
1.413 + Checks whether this message has already been completed.
1.414 +
1.415 + @return A boolean indicating if the message has been completed. ETrue if the message has been
1.416 + completed, EFalse if not.
1.417 +
1.418 + @since 7.0s
1.419 + */
1.420 + IMPORT_C TBool IsCompleted();
1.421 +
1.422 + /**
1.423 + Constructs a TMMFMessage from an RMmfIpcMessage.
1.424 +
1.425 + @param aMessage
1.426 + The handle to the remote message.
1.427 +
1.428 + @since 7.0s
1.429 + */
1.430 + IMPORT_C TMMFMessage(const RMmfIpcMessage& aMessage);
1.431 +
1.432 + /**
1.433 + Gets the destination info from the client.
1.434 +
1.435 + @since 7.0s
1.436 + */
1.437 + IMPORT_C void FetchDestinationL();
1.438 +private:
1.439 +#ifdef __MMF_USE_IPC_V2__
1.440 + /**
1.441 + The encapsulated message
1.442 + */
1.443 + RMessagePtr2 iMessage;
1.444 + /**
1.445 + The encapsulated function
1.446 + */
1.447 + TInt iFunction;
1.448 + /**
1.449 + Private padding to preserve BC with earlier versions
1.450 + */
1.451 + TInt iDummyPadding[6];
1.452 +#else
1.453 + /**
1.454 + The RMessage encapsulated by this object.
1.455 + */
1.456 + RMessage iMessage;
1.457 +#endif // __MMF_USE_IPC_V2__
1.458 +
1.459 + /**
1.460 + The destination of this message.
1.461 + */
1.462 + TMMFMessageDestination iDestination;
1.463 +
1.464 + /**
1.465 + Defines whether this object has yet to be completed.
1.466 + */
1.467 + TBool iAmCompleted;
1.468 + };
1.469 +
1.470 +/**
1.471 +@internalComponent
1.472 +
1.473 +Mixin class used by CLogonMonitor to inform about its state
1.474 +
1.475 +@since 9.3
1.476 +*/
1.477 +class MLogonMonitorObserver
1.478 + {
1.479 +public:
1.480 + /**
1.481 + The monitored thread has been terminated.
1.482 + */
1.483 + virtual void ThreadTerminated() = 0;
1.484 + };
1.485 +
1.486 +/**
1.487 +@internalComponent
1.488 +
1.489 +RSessionBase-based client class to handle the creation of the controller thread and
1.490 +message sending over IPC.
1.491 +
1.492 +The controller proxy is responsible for sending and recieving messages over IPC; it does not
1.493 +care exactly what those messages are.
1.494 +
1.495 +Note the fact that, although this is an internal component, its size cannot be changed because
1.496 +it's embedded in a publishedAll class (RMMFController) and the size of the latter would also be
1.497 +changed raising a binary compatibility problem.
1.498 +
1.499 +@since 7.0s
1.500 +*/
1.501 +NONSHARABLE_CLASS(RMMFControllerProxy) : public RMmfSessionBase, public MLogonMonitorObserver
1.502 + {
1.503 +public:
1.504 +
1.505 + /**
1.506 + Constructor.
1.507 + @since 7.0s
1.508 + */
1.509 + IMPORT_C RMMFControllerProxy();
1.510 +
1.511 + /**
1.512 + Create a new thread and load a controller plugin into that thread.
1.513 +
1.514 + @param aControllerUid
1.515 + The UID of the controller plugin to be loaded.
1.516 + @param aUseSharedHeap
1.517 + If this value is EFalse each controller is created with its own heap. The alternative,
1.518 + if the value is ETrue, is that controllers share a special heap with other controllers
1.519 + created the same way. Each heap uses a chunk, so this avoids situations where the
1.520 + number of chunks per process is limited. The default behaviour is generally to be
1.521 + preferred, and should give lower overall memory usage. However, if many controllers are
1.522 + to be created for a particular thread, then ETrue should be provided to prevent running
1.523 + out of heaps or chunks.
1.524 +
1.525 + @return One of the system-wide error codes.
1.526 + @since 7.0s
1.527 + */
1.528 + IMPORT_C TInt LoadController(TUid aControllerUid, TBool aUseSharedHeap);
1.529 +
1.530 + /**
1.531 + Create a new thread and load a controller plugin into that thread.
1.532 +
1.533 + @param aControllerInfo
1.534 + A reference to a CMMFControllerImplementationInformation object
1.535 + used for determining the controller UID and heap size
1.536 + @param aUseSharedHeap
1.537 + If this value is EFalse each controller is created with its own heap. The alternative,
1.538 + if the value is ETrue, is that controllers share a special heap with other controllers
1.539 + created the same way. Each heap uses a chunk, so this avoids situations where the
1.540 + number of chunks per process is limited. The default behaviour is generally to be
1.541 + preferred, and should give lower overall memory usage. However, if many controllers are
1.542 + to be created for a particular thread, then ETrue should be provided to prevent running
1.543 + out of heaps or chunks.
1.544 +
1.545 + @return One of the system-wide error codes.
1.546 + @since 7.0s
1.547 + */
1.548 + IMPORT_C TInt LoadController(const CMMFControllerImplementationInformation& aControllerInfo, TBool aUseSharedHeap);
1.549 +
1.550 + /**
1.551 + Create a new thread in another process through Secure DRM Plugin server and load a controller plugin
1.552 + into that thread. The motivation of this model is to allow applications without DRM capability able
1.553 + to play protected content through MMF.
1.554 +
1.555 + @param aControllerUid
1.556 + The UID of the controller plugin to be loaded.
1.557 + @param aUseSharedHeap
1.558 + If this value is EFalse each controller is created with its own heap. The alternative,
1.559 + if the value is ETrue, is that controllers share a special heap with other controllers
1.560 + created the same way. Each heap uses a chunk, so this avoids situations where the
1.561 + number of chunks per process is limited. The default behaviour is generally to be
1.562 + preferred, and should give lower overall memory usage. However, if many controllers are
1.563 + to be created for a particular thread, then ETrue should be provided to prevent running
1.564 + out of heaps or chunks.
1.565 +
1.566 + @return One of the system-wide error codes.
1.567 + */
1.568 + IMPORT_C TInt LoadControllerInSecureDRMProcess(TUid aControllerUid, TBool aUseSharedHeap);
1.569 +
1.570 + /**
1.571 + Create a new thread in another process through Secure DRM Plugin server and load a controller plugin
1.572 + into that thread. The motivation of this model is to allow applications without DRM capability able
1.573 + to play protected content through MMF.
1.574 +
1.575 + @param aControllerInfo
1.576 + A reference to a CMMFControllerImplementationInformation object
1.577 + used for determining the controller UID and heap size
1.578 + @param aUseSharedHeap
1.579 + If this value is EFalse each controller is created with its own heap. The alternative,
1.580 + if the value is ETrue, is that controllers share a special heap with other controllers
1.581 + created the same way. Each heap uses a chunk, so this avoids situations where the
1.582 + number of chunks per process is limited. The default behaviour is generally to be
1.583 + preferred, and should give lower overall memory usage. However, if many controllers are
1.584 + to be created for a particular thread, then ETrue should be provided to prevent running
1.585 + out of heaps or chunks.
1.586 +
1.587 + @return One of the system-wide error codes.
1.588 + */
1.589 + IMPORT_C TInt LoadControllerInSecureDRMProcess(const CMMFControllerImplementationInformation& aControllerInfo, TBool aUseSharedHeap);
1.590 +
1.591 + /**
1.592 + Delete the controller plugin and close its thread.
1.593 +
1.594 + Clients must call Close() on the controller proxy, otherwise leaks will occur.
1.595 +
1.596 + @since 7.0s
1.597 + */
1.598 + IMPORT_C void Close();
1.599 +
1.600 + /**
1.601 + Send a message synchronously to the controller thread.
1.602 +
1.603 + The controller framework will analyze the message to determine its correct destination.
1.604 +
1.605 + Note: This method will not return until the controller framework has serviced the command.
1.606 +
1.607 + @param aDestination
1.608 + The destination of the message, consisting of the uid of
1.609 + the interface of this message.
1.610 + @param aFunction
1.611 + The function number to indicate which function is to be called
1.612 + on the interface defined in the aDestination parameter.
1.613 + @param aDataTo1
1.614 + A reference to the first chunk of data to be copied to the controller
1.615 + framework. The exact contents of the data are dependent on the
1.616 + interface being called. Can be NULL.
1.617 + @param aDataTo2
1.618 + A reference to the second chunk of data to be copied to the controller
1.619 + framework. The exact contents of the data are dependent on the
1.620 + interface being called. Can be NULL.
1.621 + @param aDataFrom
1.622 + A reference to an area of memory to which the controller framework will
1.623 + write any data to be passed back to the client. Can't be NULL.
1.624 +
1.625 + @return The result of the request. Exact range of values is dependent on the interface.
1.626 + @since 7.0s
1.627 + */
1.628 + IMPORT_C TInt SendSync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom) const;
1.629 +
1.630 + /**
1.631 + Send a message synchronously to the controller thread.
1.632 +
1.633 + The controller framework will analyze the message to determine its correct destination.
1.634 +
1.635 + Note: This method will not return until the controller framework has serviced the command.
1.636 +
1.637 + @param aDestination
1.638 + The destination of the message, consisting of the uid of
1.639 + the interface of this message.
1.640 + @param aFunction
1.641 + The function number to indicate which function is to be called
1.642 + on the interface defined in the aDestination parameter.
1.643 + @param aDataTo1
1.644 + A reference to the first chunk of data to be copied to the controller
1.645 + framework. The exact contents of the data are dependent on the
1.646 + interface being called. Can be NULL.
1.647 + @param aDataTo2
1.648 + A reference to the second chunk of data to be copied to the controller
1.649 + framework. The exact contents of the data are dependent on the
1.650 + interface being called. Can be NULL.
1.651 +
1.652 + @return The result of the request. Exact range of values is dependent on the interface.
1.653 + @since 7.0s
1.654 + */
1.655 + IMPORT_C TInt SendSync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2) const;
1.656 +
1.657 + /**
1.658 + Send a message asynchronously to the controller thread.
1.659 +
1.660 + The controller framework will analyze the message to determine its correct destination.
1.661 +
1.662 + Note: This method will return immediately. The RunL of the active object owning the
1.663 + aStatus parameter will be called when the command is completed by the
1.664 + controller framework.
1.665 +
1.666 + @param aDestination
1.667 + The destination of the message, consisting of the uid of
1.668 + the interface of this message.
1.669 + @param aFunction
1.670 + The function number to indicate which function is to be called
1.671 + on the interface defined in the aDestination parameter.
1.672 + @param aDataTo1
1.673 + A reference to the first chunk of data to be copied to the controller
1.674 + framework. The exact contents of the data are dependent on the
1.675 + interface being called. Can be NULL.
1.676 + @param aDataTo2
1.677 + A reference to the second chunk of data to be copied to the controller
1.678 + framework. The exact contents of the data are dependent on the
1.679 + interface being called. Can be NULL.
1.680 + @param aDataFrom
1.681 + A reference to an area of memory to which the controller framework will
1.682 + write any data to be passed back to the client. Can't be NULL.
1.683 + @param aStatus
1.684 + The TRequestStatus of an active object. This will contain the
1.685 + result of the request on completion. The exact range of
1.686 + result values is dependent on the interface.
1.687 +
1.688 + @since 7.0s
1.689 + */
1.690 + IMPORT_C void SendAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom, TRequestStatus& aStatus) const;
1.691 +
1.692 + /**
1.693 + Send a message asynchronously to the controller thread.
1.694 +
1.695 + The controller framework will analyze the message to determine its correct destination.
1.696 +
1.697 + Note: This method will return immediately. The RunL of the active object owning the
1.698 + aStatus parameter will be called when the command is completed by the
1.699 + controller framework.
1.700 +
1.701 + @param aDestination
1.702 + The destination of the message, consisting of the uid of
1.703 + the interface of this message.
1.704 + @param aFunction
1.705 + The function number to indicate which function is to be called
1.706 + on the interface defined in the aDestination parameter.
1.707 + @param aDataTo1
1.708 + A reference to the first chunk of data to be copied to the controller
1.709 + framework. The exact contents of the data are dependent on the
1.710 + interface being called. Can be NULL.
1.711 + @param aDataTo2
1.712 + A reference to the second chunk of data to be copied to the controller
1.713 + framework. The exact contents of the data are dependent on the
1.714 + interface being called. Can be NULL.
1.715 + @param aStatus
1.716 + The TRequestStatus of an active object. This will contain the
1.717 + result of the request on completion. The exact range of
1.718 + result values is dependent on the interface.
1.719 +
1.720 + @since 7.0s
1.721 + */
1.722 + IMPORT_C void SendAsync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TRequestStatus& aStatus) const;
1.723 +
1.724 + IMPORT_C TInt SendSync(TInt aFunction, const TIpcArgs& aIpcArgs) const;
1.725 + IMPORT_C void SendAsync(TInt aFunction, const TIpcArgs& aIpcArgs, TRequestStatus& aStatus) const;
1.726 + /**
1.727 + Register to receive events from the controller framework.
1.728 +
1.729 + Events can be generated at any time, and are generally associated with things that occur
1.730 + due to something happening internally within the controller. For example, an event will
1.731 + be generated if the controller stops playing due to reaching the end of a file.
1.732 +
1.733 + @param aEvent
1.734 + A reference to a TMMFEventPckg object that must be member data
1.735 + of the active object calling this method. The details of the event
1.736 + will be copied into this object when an event occurs.
1.737 + @param aStatus
1.738 + The TRequestStatus of the active object calling this method.
1.739 +
1.740 + @see TMMFEvent
1.741 + @see CMMFControllerEventMonitor
1.742 + @since 7.0s
1.743 + */
1.744 + IMPORT_C void ReceiveEvents(TMMFEventPckg& aEvent, TRequestStatus& aStatus);
1.745 +
1.746 + /**
1.747 + Cancel a previous registration to receive events from the controller framework.
1.748 +
1.749 + This must be called from the DoCancel() method of the active object using the
1.750 + ReceiveEvents() API.
1.751 +
1.752 + @return One of the standard system-wide error codes.
1.753 +
1.754 + @see TMMFEvent
1.755 + @since 7.0s
1.756 + */
1.757 + IMPORT_C TInt CancelReceiveEvents();
1.758 +
1.759 + /**
1.760 + Set the priority of the controller's sub thread.
1.761 +
1.762 + This can be used to increase the responsiveness of the audio plugin to minimise
1.763 + any lag in processing. This function should be used with care as it may have knock-on
1.764 + effects elsewhere in the system.
1.765 +
1.766 + @param aPriority
1.767 + The TThreadPriority that the thread should run under. The default is EPriorityNormal.
1.768 + @return TInt
1.769 + A standard error code: KErrNone if successful, KErrNotReady if the thread does not have a
1.770 + valid handle.
1.771 + */
1.772 + IMPORT_C TInt SetThreadPriority(const TThreadPriority& aPriority) const;
1.773 +
1.774 + /**
1.775 + The controller subthread has been terminated.
1.776 +
1.777 + This is called by CLogonMonitor when the the thread terminates
1.778 + */
1.779 + void ThreadTerminated();
1.780 +private:
1.781 + /**
1.782 + Creates the new thread
1.783 + */
1.784 + TInt DoCreateSubThread(RServer2* aServer2, TUint aMaxHeapSize, TBool aUseSharedHeap);
1.785 +
1.786 + /**
1.787 + Determines the maximum heap size required by the selected controller
1.788 + */
1.789 + TUint ControllersMaxHeapSizeL(TUid aControllerUid);
1.790 +
1.791 + /**
1.792 + Load a controller by UID
1.793 +
1.794 + @param aControllerUid
1.795 + The UID of the controller plugin to be loaded.
1.796 + @param aControllerInfo
1.797 + A reference to a CMMFControllerImplementationInformation object
1.798 + used for determining the heap size and DRM server supporting state.
1.799 + @param aUseSharedHeap
1.800 + If this value is EFalse each controller is created with its own heap. The alternative,
1.801 + if the value is ETrue, is that controllers share a special heap with other controllers
1.802 + created the same way. Each heap uses a chunk, so this avoids situations where the
1.803 + number of chunks per process is limited. The default behaviour is generally to be
1.804 + preferred, and should give lower overall memory usage. However, if many controllers are
1.805 + to be created for a particular thread, then ETrue should be provided to prevent running
1.806 + out of heaps or chunks.
1.807 + @param aNoDRMCap
1.808 + The indicator supplied from user used to determine whether the user's process has DRM
1.809 + capability
1.810 + @return TInt
1.811 + One of the system-wide error codes.
1.812 + */
1.813 + TInt LoadController(TUid aControllerUid, const CMMFControllerImplementationInformation& aControllerInfo, TBool aUseSharedHeap,
1.814 + TBool aNoDRMCap = EFalse);
1.815 +
1.816 + /**
1.817 + Release heap - for use when a shared heap has been registered
1.818 + */
1.819 + void ReleaseHeap();
1.820 +
1.821 + /**
1.822 + Create a session to handle situation of playing DRM protected content in
1.823 + process with no DRM capability.
1.824 + DRM server process will be created, if not yet created. This server is responsible to
1.825 + manage and monitor all the MMF Controller servers created as seperate threads belong to
1.826 + DRM server process. Once the new MMF Controller server is running, a MMF Controller server
1.827 + session will be created and the handle is passing back.
1.828 + */
1.829 + TInt DoCreateSessionForNoDRMCapClient(TUint aMaxHeapSize, TBool aUseSharedHeap);
1.830 +
1.831 +private:
1.832 + enum
1.833 + {
1.834 + /**
1.835 + Shared heap has been opened for this object, and must be closed
1.836 + */
1.837 + EFlagOpenedSharedHeap=0x01
1.838 + };
1.839 +
1.840 +private:
1.841 + /**
1.842 + The thread in which the controller plugin will run.
1.843 + */
1.844 + RThread iSubThread;
1.845 + /**
1.846 + Used to hold destination for messages from the controller proxy
1.847 + (not from clients calling SendSync/SendAsync!!)
1.848 + */
1.849 + TMMFMessageDestinationPckg iDestinationPckg;
1.850 + /**
1.851 + Used to determine the success of a logon. If the status is not pending, the logon has failed
1.852 + and the thread should be closed.
1.853 + */
1.854 + CLogonMonitor* iLogonAO;
1.855 + /**
1.856 + The priority at which the controller plugin thread runs.
1.857 + */
1.858 + TThreadPriority iThreadPriority;
1.859 + /**
1.860 + Flags field
1.861 + */
1.862 + TInt iFlags;
1.863 + /**
1.864 + This member is internal and not intended for use.
1.865 + */
1.866 + TInt iReserved1;
1.867 + };
1.868 +
1.869 +/**
1.870 +@internalComponent
1.871 +
1.872 +Used to Kill the controller thread either immediately or after a timeout.
1.873 +Used by the controller thread on startup to prevent orphaning if no sessions are created to it.
1.874 +*/
1.875 +class CMMFControllerProxyShutdown : public CTimer
1.876 + {
1.877 + enum {EMMFControllerProxyShutdownDelay=1000000}; // 1s
1.878 +public:
1.879 +
1.880 + /**
1.881 + Create a new shutdown timer.
1.882 +
1.883 + This method can leave with one of the system-wide error codes.
1.884 +
1.885 + @since 7.0s
1.886 + */
1.887 + static CMMFControllerProxyShutdown* NewL();
1.888 +
1.889 + /**
1.890 + Start the shutdown timer. The RunL of this active object will be called after
1.891 + EMMFControllerProxyShutdownDelay microseconds.
1.892 +
1.893 + @since 7.0s
1.894 + */
1.895 + void Start();
1.896 +
1.897 + /**
1.898 + Shut down the controller thread immediately.
1.899 +
1.900 + Calls CActiveScheduler::Stop().
1.901 +
1.902 + @since 7.0s
1.903 + */
1.904 + void ShutdownNow();
1.905 +private:
1.906 + CMMFControllerProxyShutdown();
1.907 + void ConstructL();
1.908 +
1.909 + /**
1.910 + Calls ShutdownNow().
1.911 +
1.912 + @since 7.0s
1.913 + */
1.914 + void RunL();
1.915 + };
1.916 +
1.917 +
1.918 +/**
1.919 +@publishedAll
1.920 +@released
1.921 +
1.922 +Mixin class to define an object capable of handling an event within the controller framework.
1.923 +*/
1.924 +class MAsyncEventHandler
1.925 + {
1.926 +public:
1.927 +
1.928 + /**
1.929 + Sends an event to the client.
1.930 +
1.931 + @param aEvent
1.932 + The event.
1.933 +
1.934 + @since 7.0s
1.935 + */
1.936 + virtual TInt SendEventToClient(const TMMFEvent& aEvent) = 0;
1.937 + };
1.938 +
1.939 +/**
1.940 +@internalComponent
1.941 +
1.942 +Used to hold on to an TMMFMessage so we can complete it asynchronously to
1.943 +send an event to the client.
1.944 +
1.945 +@since 7.0s
1.946 +*/
1.947 +class CMMFEventReceiver : public CBase
1.948 + {
1.949 +public:
1.950 +
1.951 + /**
1.952 + Constructs a new event receiver.
1.953 +
1.954 + This method may leave with one of the system-wide error codes.
1.955 +
1.956 + @param aMessage
1.957 + The message to be completed when an event occurs.
1.958 +
1.959 + @return A pointer to the newly created event receiver.
1.960 +
1.961 + @since 7.0s
1.962 + */
1.963 + static CMMFEventReceiver* NewL(const TMMFMessage& aMessage);
1.964 +
1.965 + /**
1.966 + Destructor.
1.967 +
1.968 + Completes the message with KErrCancel if the message hasn't already been completed.
1.969 +
1.970 + @since 7.0s
1.971 + */
1.972 + ~CMMFEventReceiver();
1.973 +
1.974 + /**
1.975 + Sends an event to the client.
1.976 +
1.977 + @param aEvent
1.978 + The event.
1.979 +
1.980 + @since 7.0s
1.981 + */
1.982 + void SendEvent(const TMMFEvent& aEvent);
1.983 +private:
1.984 +
1.985 + /**
1.986 + Constructor.
1.987 +
1.988 + @param aMessage
1.989 + The message to be completed when an event occurs.
1.990 +
1.991 + @since 7.0s
1.992 + */
1.993 + CMMFEventReceiver(const TMMFMessage& aMessage);
1.994 +private:
1.995 + /**
1.996 + The message to be completed when an event occurs.
1.997 + */
1.998 + TMMFMessage iMessage;
1.999 + };
1.1000 +
1.1001 +
1.1002 +
1.1003 +/**
1.1004 +@internalComponent
1.1005 +
1.1006 +The controller proxy server.
1.1007 +
1.1008 +The main server inside the controller thread, responsible for creating and destroying the single
1.1009 +session used to transmit messages from the client to the server.
1.1010 +
1.1011 +Every controller plugin runs in its own thread, and has its own controller proxy server.
1.1012 +
1.1013 +@since 7.0s
1.1014 +*/
1.1015 +class CMMFControllerProxyServer : public CMmfIpcServer
1.1016 + {
1.1017 +public:
1.1018 + /**
1.1019 + Construct the server.
1.1020 +
1.1021 + This method may leave with one of the system-wide error codes.
1.1022 +
1.1023 + @return The newly created server.
1.1024 +
1.1025 + @since 7.0s
1.1026 + */
1.1027 + static CMMFControllerProxyServer* NewL(RServer2* aServer2 );
1.1028 +
1.1029 + /**
1.1030 + Destructor.
1.1031 +
1.1032 + @since 7.0s
1.1033 + */
1.1034 + ~CMMFControllerProxyServer();
1.1035 +
1.1036 + /**
1.1037 + Static thread function.
1.1038 +
1.1039 + The address of this function is passed into RThread::Create.
1.1040 +
1.1041 + Unpackages the startup parameters and calls DoStartThreadL().
1.1042 +
1.1043 + @param aAny
1.1044 + A pointer to the packaged startup parameters.
1.1045 +
1.1046 + @return One of the system-wide error codes.
1.1047 +
1.1048 + @since 7.0s
1.1049 + */
1.1050 + IMPORT_C static TInt StartThread(TAny* aParam);
1.1051 +
1.1052 + /**
1.1053 + Called by the active scheduler when the ServiceL of the session leaves.
1.1054 + Completes the message with the error and restarts the server.
1.1055 +
1.1056 + @param aError
1.1057 + The error that the session ServiceL left with.
1.1058 +
1.1059 + @return KErrNone
1.1060 + @since 7.0s
1.1061 + */
1.1062 + TInt RunError(TInt aError);
1.1063 +
1.1064 + /**
1.1065 + Signals that the session has been created.
1.1066 +
1.1067 + Stops the shutdown timer.
1.1068 +
1.1069 + @since 7.0s
1.1070 + */
1.1071 + void SessionCreated();
1.1072 +
1.1073 + /**
1.1074 + Signals that the session has been destroyed.
1.1075 + Causes the server to shut down immediately.
1.1076 +
1.1077 + @since 7.0s
1.1078 + */
1.1079 + void SessionDestroyed();
1.1080 +private:
1.1081 +
1.1082 + /**
1.1083 + Thread startup code.
1.1084 +
1.1085 + Creates the cleanup stack, installs the active scheduler and creates the server.
1.1086 + Once all this is completed successfully, it signals the success back to the client.
1.1087 +
1.1088 + This function may leave with one of the system-wide error codes.
1.1089 +
1.1090 + @param aParams
1.1091 + Used to signal startup success back to the client.
1.1092 +
1.1093 + @since 7.0s
1.1094 + */
1.1095 + static void DoStartThreadL(TAny* aParam);
1.1096 +
1.1097 + /**
1.1098 + Creates a new session. Only one session may be created with the ControllerProxyServer.
1.1099 +
1.1100 + This function may leave with one of the system-wide error codes.
1.1101 +
1.1102 + @param aVersion
1.1103 + The version number of the session.
1.1104 +
1.1105 + @return A pointer to the new session.
1.1106 +
1.1107 + @since 7.0s
1.1108 + */
1.1109 + CMmfIpcSession* NewSessionL(const TVersion& aVersion) const;
1.1110 +
1.1111 + /**
1.1112 + Constructor.
1.1113 +
1.1114 + @since 7.0s
1.1115 + */
1.1116 + CMMFControllerProxyServer();
1.1117 +
1.1118 + /**
1.1119 + Second phase constructor.
1.1120 +
1.1121 + @since 7.0s
1.1122 + */
1.1123 + void ConstructL(RServer2* aServer2);
1.1124 +
1.1125 + /**
1.1126 + Renaming Controller Proxy Server name
1.1127 +
1.1128 + @since 9.2
1.1129 + */
1.1130 + static void RenameControllerProxyThread();
1.1131 +
1.1132 +private:
1.1133 + /**
1.1134 + The timer used to shut down the server in case the client fails to connect a session.
1.1135 + */
1.1136 + CMMFControllerProxyShutdown* iShutdownTimer;
1.1137 + /**
1.1138 + Indicates whether we have a session connected. Only one session is allowed to connect to the server.
1.1139 + */
1.1140 + TBool iHaveSession;
1.1141 + };
1.1142 +
1.1143 +class CMMFController;
1.1144 +
1.1145 +/**
1.1146 +@internalComponent
1.1147 +
1.1148 +The controller proxy session.
1.1149 +
1.1150 +Only one session can be connected to a controller proxy server.
1.1151 +
1.1152 +@since 7.0s
1.1153 +*/
1.1154 +class CMMFControllerProxySession : public CMmfIpcSession, public MAsyncEventHandler
1.1155 + {
1.1156 +public:
1.1157 +
1.1158 + /**
1.1159 + Construct the session.
1.1160 +
1.1161 + This method may leave with one of the system-wide error codes.
1.1162 +
1.1163 + @return The newly created server.
1.1164 +
1.1165 + @since 7.0s
1.1166 + */
1.1167 + static CMMFControllerProxySession* NewL();
1.1168 +
1.1169 + /**
1.1170 + Second phase constructor called by the CServer base class.
1.1171 +
1.1172 + This function may leave with one of the system-wide error codes.
1.1173 +
1.1174 + @param aServer
1.1175 + A reference to the server to which this session is attached.
1.1176 +
1.1177 + @since 7.0s
1.1178 + */
1.1179 + void CreateL(const CMmfIpcServer& aServer);
1.1180 +
1.1181 + /**
1.1182 + Destructor.
1.1183 + */
1.1184 + ~CMMFControllerProxySession();
1.1185 +
1.1186 + /**
1.1187 + Called by the CServer baseclass when a request has been made by the client.
1.1188 +
1.1189 + This function may leave with on of the system-wide error codes. If
1.1190 + a leave occurs, the message will be automatically completed by the
1.1191 + RunError() of the Controller Proxy Server.
1.1192 +
1.1193 + @param aMessage
1.1194 + The request to be handled. The controller proxy session will create
1.1195 + a TMMFMessage from this, and pass on the request to the controller
1.1196 + base class to handle.
1.1197 +
1.1198 + @since 7.0s
1.1199 + */
1.1200 + void ServiceL(const RMmfIpcMessage& aMessage);
1.1201 +
1.1202 + /**
1.1203 + Derived from MAsyncEventHandler.
1.1204 +
1.1205 + @see MAsyncEventHandler
1.1206 +
1.1207 + @since 7.0s
1.1208 + */
1.1209 + TInt SendEventToClient(const TMMFEvent& aEvent);
1.1210 +private:
1.1211 + /**
1.1212 + Constructor
1.1213 + */
1.1214 + CMMFControllerProxySession();
1.1215 +
1.1216 + /**
1.1217 + Handle a request from the client to register to receive events from the controller framework.
1.1218 +
1.1219 + This function may leave with one of the system-wide error codes.
1.1220 +
1.1221 + @param aMessage
1.1222 + The request to be handled.
1.1223 +
1.1224 + @return ETrue if the message is to be completed now, EFalse if the message will be completed
1.1225 + later.
1.1226 + */
1.1227 + TBool ReceiveEventsL(TMMFMessage& aMessage);
1.1228 +
1.1229 + /**
1.1230 + Handle a request from the client to stop receiving events from the controller framework.
1.1231 +
1.1232 + This function may leave with one of the system-wide error codes.
1.1233 +
1.1234 + @param aMessage
1.1235 + The request to be handled.
1.1236 +
1.1237 + @return ETrue if the message is to be completed now, EFalse if the message will be completed later.
1.1238 + */
1.1239 + TBool CancelReceiveEvents(TMMFMessage& aMessage);
1.1240 +
1.1241 + /**
1.1242 + Handle a request from the client to load a controller plugin.
1.1243 +
1.1244 + This function may leave with one of the system-wide error codes.
1.1245 +
1.1246 + @param aMessage
1.1247 + The request to be handled.
1.1248 +
1.1249 + @return ETrue if the message is to be completed now, EFalse if the message will be completed later.
1.1250 + */
1.1251 + TBool LoadControllerL(TMMFMessage& aMessage);
1.1252 +private:
1.1253 + /**
1.1254 + The controller plugin.
1.1255 + */
1.1256 + CMMFController* iController;
1.1257 + /**
1.1258 + A pointer to the server.
1.1259 + */
1.1260 + CMMFControllerProxyServer* iServer;
1.1261 + /**
1.1262 + The event receiver. Used to send events to the client.
1.1263 + */
1.1264 + CMMFEventReceiver* iEventReceiver;
1.1265 + /**
1.1266 + The events waiting to be sent to the client.
1.1267 + */
1.1268 + RArray<TMMFEvent> iEvents;
1.1269 + };
1.1270 +
1.1271 +
1.1272 +#endif