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".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 #include "mmfcontroller.h"

    17 #include "mmfcontrollerpluginresolver.h"

    18 

    19 #ifdef SYMBIAN_ENABLE_SPLIT_HEADERS

    20 #include <mmf/common/mmfcontrollerextendeddata.h>

    21 #include <mmf/common/mmfcustomcommandparsermanager.h>

    22 #endif

    23 

    24 /**

    25 Constructor.

    26 

    27 @since 7.0s

    28 */

    29 EXPORT_C RMMFController::RMMFController() :

    30 	iDestinationPckg(TMMFMessageDestination(KUidInterfaceMMFController, KMMFObjectHandleController))

    31 	{

    32 	}

    33 

    34 /**

    35 Loads a controller plugin by specifying the UID of the plugin to load.

    36 

    37 Creates a new thread and loads the specified controller into the new thread.  Use the classes

    38 CMMFControllerPluginSelectionParameters and CMMFFormatSelectionParamters

    39 to find the uid of the controller to load.

    40 

    41 @param  aControllerUid

    42         The UID of the controller plugin to be loaded.

    43 @param  aPrioritySettings

    44         The priority settings for this plugin, used by the policy

    45         component to arbitrate between different controllers that are

    46         attempting to use the same hardware resource simultaneously.

    47 @param	aUseSharedHeap

    48 		If this value is EFalse each controller is created with its own heap. The alternative,

    49 		if the value is ETrue, is that controllers share a special heap with other controllers

    50 		created the same way. Each heap uses a chunk, so this avoids situations where the

    51 		number of chunks per process is limited. The default behaviour is generally to be

    52 		preferred, and should give lower overall memory usage. However, if many controllers are

    53 		to be created for a particular thread, then ETrue should be provided to prevent running

    54 		out of heaps or chunks.

    55 

    56 @return An error code indicating if the function call was successful. KErrNone on success, otherwise

    57         another of the system-wide error codes.

    58 

    59 @see    CMMFControllerPluginSelectionParamters

    60 @since  7.0s

    61 

    62 */

    63 EXPORT_C TInt RMMFController::Open(TUid aControllerUid, const TMMFPrioritySettings& aPrioritySettings, TBool aUseSharedHeap)

    64 	{

    65 	// Load Controller

    66 	TInt err = iControllerProxy.LoadController(aControllerUid, aUseSharedHeap);

    67 	if (!err)

    68 		{

    69 		err = SetPrioritySettings(aPrioritySettings);

    70 		}

    71 	return err;

    72 	}

    73 

    74 /**

    75 Loads a controller plugin by specifying a CMMFControllerImplementationInformation object.

    76 

    77 CMMFControllerImplementationInformation is passed as a parameter to allow

    78 the controller thread's heap size to be determined without a further query to ECOM.

    79 

    80 The function creates a new thread and loads the specified controller into the new thread.  The classes

    81 CMMFControllerPluginSelectionParameters and CMMFFormatSelectionParamters are used

    82 to find the UID of the controller to load.

    83 

    84 @param  aControllerInfo

    85         A reference to a CMMFControllerImplementationInformation object

    86         used for determining the controller's UID & heap size

    87 @param  aPrioritySettings

    88         The priority settings for this plugin, used by the policy

    89         component to arbitrate between different controllers that are

    90         attempting to use the same hardware resource simultaneously.

    91 @param	aUseSharedHeap

    92 		If this value is EFalse each controller is created with its own heap. The alternative,

    93 		if the value is ETrue, is that controllers share a special heap with other controllers

    94 		created the same way. Each heap uses a chunk, so this avoids situations where the

    95 		number of chunks per process is limited. The default behaviour is generally to be

    96 		preferred, and should give lower overall memory usage. However, if many controllers are

    97 		to be created for a particular thread, then ETrue should be provided to prevent running

    98 		out of heaps or chunks.

    99 

   100 @return An error code indicating if the function call was successful. KErrNone on success, otherwise

   101         another of the system-wide error codes.

   102 

   103 @see CMMFControllerPluginSelectionParamters

   104 @since 7.0s

   105 

   106 */

   107 EXPORT_C TInt RMMFController::Open(

   108 	const CMMFControllerImplementationInformation& aControllerInfo,

   109 	const TMMFPrioritySettings& aPrioritySettings,

   110 	TBool aUseSharedHeap)

   111 	{

   112 	// Load Controller

   113 	TInt err = iControllerProxy.LoadController(aControllerInfo, aUseSharedHeap);

   114 	if (!err)

   115 		err = SetPrioritySettings(aPrioritySettings);

   116 	return err;

   117 	}

   118 

   119 /**

   120 Loads a controller plugin by specifying the UID of the plugin to load.

   121 

   122 Creates a new thread and loads the specified controller into the new thread.  Use the classes

   123 CMMFControllerPluginSelectionParameters and CMMFFormatSelectionParamters

   124 to find the uid of the controller to load.

   125 This version of Open() will give each controller its own heap which will consume one chunk. Use the

   126 overloaded version of Open() to create controllers that share a single heap.

   127 

   128 @param  aControllerUid

   129         The UID of the controller plugin to be loaded.

   130 @param  aPrioritySettings

   131         The priority settings for this plugin, used by the policy

   132         component to arbitrate between different controllers that are

   133         attempting to use the same hardware resource simultaneously.

   134 

   135 @return An error code indicating if the function call was successful. KErrNone on success, otherwise

   136         another of the system-wide error codes.

   137 

   138 @see    CMMFControllerPluginSelectionParamters

   139 @since  7.0s

   140 

   141 */

   142 EXPORT_C TInt RMMFController::Open(TUid aControllerUid, const TMMFPrioritySettings& aPrioritySettings)

   143 	{

   144 	// Load Controller

   145 	return Open( aControllerUid, aPrioritySettings, EFalse ); // give controllers their own heaps

   146 	}

   147 

   148 /**

   149 Loads a controller plugin by specifying a CMMFControllerImplementationInformation object.

   150 

   151 CMMFControllerImplementationInformation is passed as a parameter to allow

   152 the controller thread's heap size to be determined without a further query to ECOM.

   153 

   154 The function creates a new thread and loads the specified controller into the new thread.  The classes

   155 CMMFControllerPluginSelectionParameters and CMMFFormatSelectionParamters are used

   156 to find the UID of the controller to load.

   157 This version of Open() will give each controller its own heap which will consume one chunk. Use the

   158 overloaded version of Open() to create controllers that share a single heap.

   159 

   160 @param  aControllerInfo

   161         A reference to a CMMFControllerImplementationInformation object

   162         used for determining the controller's UID & heap size

   163 @param  aPrioritySettings

   164         The priority settings for this plugin, used by the policy

   165         component to arbitrate between different controllers that are

   166         attempting to use the same hardware resource simultaneously.

   167 

   168 @return An error code indicating if the function call was successful. KErrNone on success, otherwise

   169         another of the system-wide error codes.

   170 

   171 @see CMMFControllerPluginSelectionParamters

   172 @since 7.0s

   173 

   174 */

   175 EXPORT_C TInt RMMFController::Open(

   176 		const CMMFControllerImplementationInformation& aControllerInfo,

   177 		const TMMFPrioritySettings& aPrioritySettings)

   178 	{

   179 		// Load Controller

   180 		return Open( aControllerInfo, aPrioritySettings, EFalse ); // give controllers their own heaps

   181 	}

   182 

   183 /**

   184 Same as RMMFController::Open(TUid, const TMMFPrioritySettings&) which loads a controller plugin by 

   185 specifying the UID of the plugin to load, except that this is expected to be called by user thread 

   186 without DRM Capability.

   187 

   188 Creates a new thread through DRM Plugin Server and loads the specified controller into the new thread.  

   189 Use the classes CMMFControllerPluginSelectionParameters and CMMFFormatSelectionParamters

   190 to find the uid of the controller to load.

   191 This version of Open() will give each controller its own heap which will consume one chunk. Use the

   192 overloaded version of Open() to create controllers that share a single heap.

   193 

   194 @param  aControllerUid

   195         The UID of the controller plugin to be loaded.

   196 @param  aPrioritySettings

   197         The priority settings for this plugin, used by the policy

   198         component to arbitrate between different controllers that are

   199         attempting to use the same hardware resource simultaneously.

   200 

   201 @return An error code indicating if the function call was successful. KErrNone on success, otherwise

   202         another of the system-wide error codes.

   203 

   204 @see    CMMFControllerPluginSelectionParamters

   205 

   206 */

   207 EXPORT_C TInt RMMFController::OpenInSecureDRMProcess(TUid aControllerUid, const TMMFPrioritySettings& aPrioritySettings)

   208 	{

   209 	return OpenInSecureDRMProcess(aControllerUid, aPrioritySettings, EFalse);

   210 	}

   211 

   212 /**

   213 Same as Open(const CMMFControllerImplementationInformation&, const TMMFPrioritySettings&) which loads a 

   214 controller plugin by specifying a CMMFControllerImplementationInformation object.

   215 

   216 CMMFControllerImplementationInformation is passed as a parameter to allow

   217 the controller thread's heap size to be determined without a further query to ECOM.

   218 

   219 The function creates a new thread through DRM Plugin server and loads the specified controller into 

   220 the new thread.  The classes CMMFControllerPluginSelectionParameters and CMMFFormatSelectionParamters are used

   221 to find the UID of the controller to load.

   222 This version of Open() will give each controller its own heap which will consume one chunk. Use the

   223 overloaded version of Open() to create controllers that share a single heap.

   224 

   225 @param  aControllerInfo

   226         A reference to a CMMFControllerImplementationInformation object

   227         used for determining the controller's UID & heap size

   228 @param  aPrioritySettings

   229         The priority settings for this plugin, used by the policy

   230         component to arbitrate between different controllers that are

   231         attempting to use the same hardware resource simultaneously.

   232 

   233 @return An error code indicating if the function call was successful. KErrNone on success, otherwise

   234         another of the system-wide error codes.

   235 

   236 @see CMMFControllerPluginSelectionParamters

   237 

   238 */	

   239 EXPORT_C TInt RMMFController::OpenInSecureDRMProcess(const CMMFControllerImplementationInformation& aControllerInfo, const TMMFPrioritySettings& aPrioritySettings)

   240 	{

   241 	return OpenInSecureDRMProcess(aControllerInfo, aPrioritySettings, EFalse);

   242 	}

   243 

   244 /**

   245 Same as RMMFController::Open(TUid, const TMMFPrioritySettings&, TBool) which loads a controller 

   246 plugin by specifying the UID of the plugin to load, except that this is expected to be called by user thread 

   247 without DRM Capability.

   248 

   249 Creates a new thread through DRM Plugin server and loads the specified controller into the new thread.  

   250 Use the classes CMMFControllerPluginSelectionParameters and CMMFFormatSelectionParamters

   251 to find the uid of the controller to load.

   252 

   253 @param  aControllerUid

   254         The UID of the controller plugin to be loaded.

   255 @param  aPrioritySettings

   256         The priority settings for this plugin, used by the policy

   257         component to arbitrate between different controllers that are

   258         attempting to use the same hardware resource simultaneously.

   259 @param	aUseSharedHeap

   260 		If this value is EFalse each controller is created with its own heap. The alternative,

   261 		if the value is ETrue, is that controllers share a special heap with other controllers

   262 		created the same way. Each heap uses a chunk, so this avoids situations where the

   263 		number of chunks per process is limited. The default behaviour is generally to be

   264 		preferred, and should give lower overall memory usage. However, if many controllers are

   265 		to be created for a particular thread, then ETrue should be provided to prevent running

   266 		out of heaps or chunks.

   267 

   268 @return An error code indicating if the function call was successful. KErrNone on success, otherwise

   269         another of the system-wide error codes.

   270 

   271 @see    CMMFControllerPluginSelectionParamters

   272 

   273 */

   274 EXPORT_C TInt RMMFController::OpenInSecureDRMProcess(TUid aControllerUid, const TMMFPrioritySettings& aPrioritySettings, TBool aUseSharedHeap )

   275 	{

   276 	// Load Controller

   277 	TInt err = iControllerProxy.LoadControllerInSecureDRMProcess(aControllerUid, aUseSharedHeap);

   278 	if (!err)

   279 		{

   280 		err = SetPrioritySettings(aPrioritySettings);

   281 		}

   282 	return err;

   283 	}

   284 

   285 /**

   286 Same as Open(const CMMFControllerImplementationInformation&, const TMMFPrioritySettings&, TBool) which 

   287 loads a controller plugin by specifying a CMMFControllerImplementationInformation object.

   288 

   289 CMMFControllerImplementationInformation is passed as a parameter to allow

   290 the controller thread's heap size to be determined without a further query to ECOM.

   291 

   292 The function creates a new thread through DRM Plugin Server and loads the specified controller into 

   293 the new thread.  The classes CMMFControllerPluginSelectionParameters and CMMFFormatSelectionParamters are used

   294 to find the UID of the controller to load.

   295 

   296 @param  aControllerInfo

   297         A reference to a CMMFControllerImplementationInformation object

   298         used for determining the controller's UID & heap size

   299 @param  aPrioritySettings

   300         The priority settings for this plugin, used by the policy

   301         component to arbitrate between different controllers that are

   302         attempting to use the same hardware resource simultaneously.

   303 @param	aUseSharedHeap

   304 		If this value is EFalse each controller is created with its own heap. The alternative,

   305 		if the value is ETrue, is that controllers share a special heap with other controllers

   306 		created the same way. Each heap uses a chunk, so this avoids situations where the

   307 		number of chunks per process is limited. The default behaviour is generally to be

   308 		preferred, and should give lower overall memory usage. However, if many controllers are

   309 		to be created for a particular thread, then ETrue should be provided to prevent running

   310 		out of heaps or chunks.

   311 

   312 @return An error code indicating if the function call was successful. KErrNone on success, otherwise

   313         another of the system-wide error codes.

   314 

   315 @see CMMFControllerPluginSelectionParamters

   316 

   317 */

   318 EXPORT_C TInt RMMFController::OpenInSecureDRMProcess(const CMMFControllerImplementationInformation& aControllerInfo, const TMMFPrioritySettings& aPrioritySettings, TBool aUseSharedHeap )

   319 	{

   320 	// Load Controller

   321 	TInt err = iControllerProxy.LoadControllerInSecureDRMProcess(aControllerInfo, aUseSharedHeap);

   322 	if (!err)

   323 		err = SetPrioritySettings(aPrioritySettings);

   324 	return err;

   325 	

   326 	}

   327 	

   328 /**

   329 Closes the controller plugin.

   330 

   331 Calling this method will unload the controller plugin and close down the controller thread.

   332 

   333 @since	7.0s

   334 */

   335 EXPORT_C void RMMFController::Close()

   336 	{

   337 	iControllerProxy.Close();

   338 	}

   339 

   340 /**

   341 Sets the priority settings for this controller.

   342 

   343 @param  aPrioritySettings

   344         The priority settings for this plugin, used by the policy

   345         component to arbitrate between different controllers that are

   346         attempting to use the same hardware resource simultaneously.

   347 

   348 @return An error code indicating if the function call was successful. KErrNone on success, otherwise

   349         another of the system-wide error codes.

   350 @since	7.0s

   351 

   352 */

   353 EXPORT_C TInt RMMFController::SetPrioritySettings(const TMMFPrioritySettings& aPrioritySettings) const

   354 	{

   355 	TMMFPrioritySettingsPckg pckg(aPrioritySettings);

   356 	return iControllerProxy.SendSync(iDestinationPckg, 

   357 									 EMMFControllerSetPrioritySettings, 

   358 									 pckg, 

   359 									 KNullDesC8);

   360 	}

   361 

   362 /**

   363 Adds a data source to the controller.

   364 

   365 A typical data source would be a file, descriptor, audio input (microphone) or camera.

   366 A controller plugin may require multiple data sources to be added (for example a video

   367 recorder controller would require two); the exact number is plugin-specific.

   368 Data sources are plugins themselves, and are loaded by the controller framework

   369 inside the controller thread.

   370 

   371 @param  aSourceUid

   372         The uid of the data source to be added. For more information,

   373         see the documentation for the data source you wish to add.

   374 @param  aSourceInitData

   375         The data used to initialise the data source.  The exact contents

   376         of this data are dependent on the type of data source. For more

   377         information, see the documentation for the data source you wish

   378         to add.

   379 

   380 @return An error code indicating if the function call was successful. KErrNone on success, otherwise

   381         another of the system-wide error codes.

   382 @since	7.0s

   383 */

   384 EXPORT_C TInt RMMFController::AddDataSource(TUid aSourceUid, const TDesC8& aSourceInitData)

   385 	{

   386 	TMMFMessageDestination handleInfo;

   387 	return AddDataSource(aSourceUid, aSourceInitData, handleInfo);

   388 	}

   389 

   390 /**

   391 Adds a data sink to the controller.

   392 

   393 A typical data sink would be a file, descriptor, audio output (speaker) or display.

   394 A controller plugin may require multiple data sinks to be added (for example a video

   395 playing controller would require two); the exact number is plugin-specific.

   396 Data sinks are plugins themselves, and are loaded by the controller framework

   397 inside the controller thread.

   398 

   399 @param  aSinkUid

   400         The UID of the data sink to be added. For more information,

   401         see the documentation for the data sink you wish to add.

   402 @param  aSinkInitData

   403         The data used to initialise the data sink.  The exact contents

   404         of this data are dependent on the type of data sink. For more

   405         information, see the documentation for the data sink you wish

   406         to add.

   407 

   408 @return An error code indicating if the function call was successful. KErrNone on success, otherwise

   409         another of the system-wide error codes.

   410 @since  7.0s

   411 */

   412 EXPORT_C TInt RMMFController::AddDataSink(TUid aSinkUid, const TDesC8& aSinkInitData)

   413 	{

   414 	TMMFMessageDestination handleInfo;

   415 	return AddDataSink(aSinkUid, aSinkInitData, handleInfo);

   416 	}

   417 

   418 /**

   419 Adds a data source to the controller, and receive a handle to allow removal and direct

   420 communication with that data source.

   421 

   422 A typical data source would be a file, descriptor, audio input (microphone) or camera.

   423 A controller plugin may require multiple data sources to be added (for example a video

   424 recorder controller would require two); the exact number is plugin-specific.

   425 Data sources are plugins themselves, and are loaded by the controller framework

   426 inside the controller thread.

   427 

   428 @param  aSourceUid

   429         The uid of the data source to be added. For more information,

   430         see the documentation for the data source you wish to add.

   431 @param  aSourceInitData

   432         Data used to initialise the data source.  The exact contents

   433         of this data is dependent on the type of data source. For more

   434         information, see the documentation for the data source you wish

   435         to add.

   436 @param  aHandleInfo

   437         This object is filled in by the controller framework, and identifies

   438         the data source inside the controller framework.  This allows

   439         the caller to send custom commands directly to the data source, and

   440         to also remove the data source from the controller.  Note that

   441         not all data sources support custom commands, and not all

   442         controller plugins support the removal of a data source.

   443 

   444 @return An error code indicating if the function call was successful. KErrNone on success, otherwise

   445         another of the system-wide error codes.

   446 @since  7.0s

   447 */

   448 EXPORT_C TInt RMMFController::AddDataSource(TUid aSourceUid, const TDesC8& aSourceInitData,

   449 											TMMFMessageDestination& aHandleInfo)

   450 	{

   451 	TMMFMessageDestinationPckg pckg;

   452 	TMMFUidPckg uidPckg(aSourceUid);

   453 	TInt error = iControllerProxy.SendSync(iDestinationPckg,

   454 										   EMMFControllerAddDataSource,

   455 										   uidPckg,

   456 										   aSourceInitData,

   457 										   pckg);

   458 	if (!error)

   459 		{

   460 		aHandleInfo = pckg();

   461 		}

   462 	return error;

   463 	}

   464 

   465 /**

   466 Add a file handle data source, together with its source info, to the controller asynchronously, 

   467 and receive a handle to allow removal and directcommunication with that data source.

   468 

   469 Note: only one call to this method can be outstanding at any time.

   470 

   471 The data source would be a file for this API.

   472 A controller plugin may require multiple data sources to be added (for example a video

   473 recorder controller would require two); the exact number is plugin-specific.

   474 Data sources are plugins themselves, and are loaded by the controller framework

   475 inside the controller thread.

   476 

   477 @param "aFile"				"The shared session file handle source to be added."

   478 @param "aSourceInitData"	"Data used to initialise the data source.  The reference must remain valid 

   479 							until the command has been completed or cancelled. The exact contents

   480 							of this data is dependent on the type of data source. For more

   481 							information, see the documentation for the data source you wish

   482 							to add."

   483 @param "aHandleInfoPckg"	"This object is filled in by the controller framework, and identifies

   484 							the data source inside the controller framework.  This allows

   485 							the caller to send custom commands directly to the data source, and

   486 							to also remove the data source from the controller.  Note that

   487 							not all data sources support custom commands, and not all

   488 							controller plugins support the removal of a data source."

   489 @param "aStatus"			"TRequestStatus of the active object to be signalled on completion

   490 							of this request."

   491 

   492 @return An error code indicating if the function call was successful. 

   493 		KErrBadHandle if the file handle is not shared through the call RFs::ShareProtected().

   494 		KErrNone on success, otherwise another of the system-wide error codes.

   495 */

   496 EXPORT_C void RMMFController::AddFileHandleDataSource(const RFile& aFile, const TDesC8& aSourceInitData, 

   497 													  TMMFMessageDestinationPckg& aHandleInfoPckg, 

   498 													  TRequestStatus& aStatus)

   499 	{

   500 	TInt error = iControllerProxy.SendSync(iDestinationPckg,

   501 										   EMMFControllerSourceSinkInitDataPreload,

   502 										   aSourceInitData,

   503 										   KNullDesC8);

   504 	TIpcArgs ipcArgs(&iDestinationPckg, NULL, NULL, &aHandleInfoPckg);

   505 	if (error == KErrNone)

   506 		{

   507 		error = aFile.TransferToServer(ipcArgs, 1, 2);

   508 		}

   509 		

   510 	if (error == KErrNone)

   511 		{

   512 		iControllerProxy.SendAsync(EMMFControllerAddFileHandleDataSourceWithInitData,

   513 								   ipcArgs,

   514 								   aStatus);

   515 		}

   516 	else

   517 		{

   518 		TRequestStatus* status = &aStatus;

   519 		User::RequestComplete(status, error);

   520 		}

   521 	}

   522 	

   523 /**

   524 Add a file handle data source to the controller asynchronously, and receive a handle to allow 

   525 removal and directcommunication with that data source.

   526 

   527 Note: only one call to this method can be outstanding at any time.

   528 

   529 The data source would be a file for this API.

   530 A controller plugin may require multiple data sources to be added (for example a video

   531 recorder controller would require two); the exact number is plugin-specific.

   532 Data sources are plugins themselves, and are loaded by the controller framework

   533 inside the controller thread.

   534 

   535 @param "aFile"				"The shared session file handle source to be added."

   536 @param "aHandleInfoPckg"	"This object is filled in by the controller framework, and identifies

   537 							the data source inside the controller framework.  This allows

   538 							the caller to send custom commands directly to the data source, and

   539 							to also remove the data source from the controller.  Note that

   540 							not all data sources support custom commands, and not all

   541 							controller plugins support the removal of a data source."

   542 @param "aStatus"			"TRequestStatus of the active object to be signalled on completion

   543 							of this request."

   544 

   545 @return An error code indicating if the function call was successful. 

   546 		KErrBadHandle if the file handle is not shared through the call RFs::ShareProtected().

   547 		KErrNone on success, otherwise another of the system-wide error codes.

   548 */

   549 EXPORT_C void RMMFController::AddFileHandleDataSource(const RFile& aFile,

   550 											TMMFMessageDestinationPckg& aHandleInfo, TRequestStatus& aStatus)

   551 	{

   552 	TIpcArgs ipcArgs(&iDestinationPckg, NULL, NULL, &aHandleInfo);

   553 	TInt error = aFile.TransferToServer(ipcArgs, 1, 2);

   554 	

   555 	if (!error)

   556 		{

   557 		iControllerProxy.SendAsync(EMMFControllerAddFileHandleDataSource,

   558 											   ipcArgs,

   559 											   aStatus);		

   560 		}

   561 	else

   562 		{

   563 		TRequestStatus* status = &aStatus;

   564 		User::RequestComplete(status, error);

   565 		}

   566 

   567 	}

   568 

   569 /**

   570 Adds a file handle data sink, together with its source info, to the controller, and receives 

   571 a handle to allow removal and direct communication with that data sink.

   572 

   573 Note: only one call to this method can be outstanding at any time.

   574 

   575 The data sink would be a file for this API.

   576 A controller plugin may require multiple data sinks to be added (for example a video

   577 playing controller would require two); the exact number is plugin-specific.

   578 Data sinks are plugins themselves, and are loaded by the controller framework

   579 inside the controller thread.

   580 

   581 @param  aFile

   582         The shared session file handle sink to be added.

   583 @param  aSinkInitData

   584         Data used to initialise the data sink.  The exact contents

   585         of this data are dependent on the type of data sink. For more

   586         information, see the documentation for the data sink you wish

   587         to add.

   588 @param  aHandleInfo

   589         This object is filled in by the controller framework, and identifies

   590         the data sink inside the controller framework.  This allows

   591         the caller to send custom commands directly to the data sink, and

   592         to also remove the data sink from the controller.  Note that

   593         not all data sinks support custom commands, and not all

   594         controller plugins support the removal of a data sink.

   595 @param 	aStatus

   596 		TRequestStatus of the active object to be signalled on completion

   597 		of this request.

   598 

   599 @return An error code indicating if the function call was successful. 

   600 		KErrBadHandle if the file handle is not shared through the call RFs::ShareProtected().

   601 		KErrNone on success, otherwise another of the system-wide error codes.

   602 */

   603 EXPORT_C void RMMFController::AddFileHandleDataSink(const RFile& aFile, const TDesC8& aSinkInitData, 

   604 													TMMFMessageDestinationPckg& aHandleInfoPckg, 

   605 													TRequestStatus& aStatus)

   606 	{

   607 	TInt error = iControllerProxy.SendSync(iDestinationPckg,

   608 										   EMMFControllerSourceSinkInitDataPreload,

   609 										   aSinkInitData,

   610 										   KNullDesC8);

   611 	TIpcArgs ipcArgs(&iDestinationPckg, NULL, NULL, &aHandleInfoPckg);

   612 	if (!error)

   613 		{

   614 		error = aFile.TransferToServer(ipcArgs, 1, 2);

   615 		}

   616  	

   617 	if (!error)

   618 		{

   619 		iControllerProxy.SendAsync(EMMFControllerAddFileHandleDataSinkWithInitData,

   620 								   ipcArgs,

   621 								   aStatus);

   622 		}

   623 	else

   624 		{

   625 		TRequestStatus* status = &aStatus;

   626 		User::RequestComplete(status, error);

   627 		}

   628 	}

   629 

   630 /**

   631 Adds a file handle data sink, together with its source info, to the controller, and receives 

   632 a handle to allow removal and direct communication with that data sink.

   633 

   634 Note: only one call to this method can be outstanding at any time.

   635 

   636 The data sink would be a file for this API.

   637 A controller plugin may require multiple data sinks to be added (for example a video

   638 playing controller would require two); the exact number is plugin-specific.

   639 Data sinks are plugins themselves, and are loaded by the controller framework

   640 inside the controller thread.

   641 

   642 @param  aFile

   643         The shared session file handle sink to be added.

   644 @param  aHandleInfo

   645         This object is filled in by the controller framework, and identifies

   646         the data sink inside the controller framework.  This allows

   647         the caller to send custom commands directly to the data sink, and

   648         to also remove the data sink from the controller.  Note that

   649         not all data sinks support custom commands, and not all

   650         controller plugins support the removal of a data sink.

   651 @param 	aStatus

   652 		TRequestStatus of the active object to be signalled on completion

   653 		of this request.

   654 

   655 @return An error code indicating if the function call was successful. 

   656 		KErrBadHandle if the file handle is not shared through the call RFs::ShareProtected().

   657 		KErrNone on success, otherwise another of the system-wide error codes.

   658 */

   659 EXPORT_C void RMMFController::AddFileHandleDataSink(const RFile& aFile,

   660 											TMMFMessageDestinationPckg& aHandleInfo, TRequestStatus& aStatus)

   661 	{

   662 	TIpcArgs ipcArgs(&iDestinationPckg, NULL, NULL, &aHandleInfo);

   663 	TInt error = aFile.TransferToServer(ipcArgs, 1, 2);

   664 	

   665 	if (!error)

   666 		{

   667 		iControllerProxy.SendAsync(EMMFControllerAddFileHandleDataSink,

   668 											   ipcArgs,

   669 											   aStatus);		

   670 		}

   671 	else

   672 		{

   673 		TRequestStatus* status = &aStatus;

   674 		User::RequestComplete(status, error);

   675 		}

   676 

   677 	}

   678 

   679 

   680 /**

   681 Adds a data sink to the controller, and receives a handle to allow removal and direct

   682 communication with that data sink.

   683 

   684 A typical data sink would be a file, descriptor, audio output (speaker) or display.

   685 A controller plugin may require multiple data sinks to be added (for example a video

   686 playing controller would require two); the exact number is plugin-specific.

   687 Data sinks are plugins themselves, and are loaded by the controller framework

   688 inside the controller thread.

   689 

   690 @param  aSinkUid

   691         The UID of the data sink to be added. For more information,

   692         see the documentation for the data sink you wish to add.

   693 @param  aSinkInitData

   694         Data used to initialise the data sink.  The exact contents

   695         of this data are dependent on the type of data sink. For more

   696         information, see the documentation for the data sink you wish

   697         to add.

   698 @param  aHandleInfo

   699         This object is filled in by the controller framework, and identifies

   700         the data sink inside the controller framework.  This allows

   701         the caller to send custom commands directly to the data sink, and

   702         to also remove the data sink from the controller.  Note that

   703         not all data sinks support custom commands, and not all

   704         controller plugins support the removal of a data sink.

   705 

   706 @return An error code indicating if the function call was successful. KErrNone on success, otherwise

   707         another of the system-wide error codes.

   708 @since  7.0s

   709 */

   710 EXPORT_C TInt RMMFController::AddDataSink(TUid aSinkUid, const TDesC8& aSinkInitData,

   711 										  TMMFMessageDestination& aHandleInfo)

   712 	{

   713 	TMMFMessageDestinationPckg pckg;

   714 	TMMFUidPckg uidPckg(aSinkUid);

   715 	TInt error = iControllerProxy.SendSync(iDestinationPckg,

   716 										   EMMFControllerAddDataSink,

   717 										   uidPckg,

   718 										   aSinkInitData,

   719 										   pckg);

   720 	if (!error)

   721 		{

   722 		aHandleInfo = pckg();

   723 		}

   724 	return error;

   725 	}

   726 

   727 

   728 /**

   729 Add a data source to the controller asynchronously, and receive a handle to allow removal and direct

   730 communication with that data source.

   731 

   732 Note: only one call to this method can be outstanding at any time.

   733 

   734 A typical data source would be a file, descriptor, audio input (microphone) or camera.

   735 A controller plugin may require multiple data sources to be added (for example a video

   736 recorder controller would require two); the exact number is plugin-specific.

   737 Data sources are plugins themselves, and are loaded by the controller framework

   738 inside the controller thread.

   739 

   740 @param "aSourceUid"			"The uid of the data source to be added, packaged for async data transfer. 

   741 							The reference must remain valid until the command has been completed or 

   742 							cancelled."

   743 @param "aSourceInitData"	"Data used to initialise the data source.  The reference must remain valid 

   744 							until the command has been completed or cancelled. The exact contents

   745 							of this data is dependent on the type of data source. For more

   746 							information, see the documentation for the data source you wish

   747 							to add."

   748 @param "aHandleInfoPckg"	"This object is filled in by the controller framework, and identifies

   749 							the data source inside the controller framework.  This allows

   750 							the caller to send custom commands directly to the data source, and

   751 							to also remove the data source from the controller.  Note that

   752 							not all data sources support custom commands, and not all

   753 							controller plugins support the removal of a data source."

   754 @param "aStatus"			"TRequestStatus of the active object to be signalled on completion

   755 							of this request."

   756 @since	8.0

   757 */

   758 EXPORT_C void RMMFController::AddDataSource(const TMMFUidPckg& aSourceUid, const TDesC8& aSourceInitData, 

   759 											TMMFMessageDestinationPckg& aHandleInfoPckg, 

   760 											TRequestStatus& aStatus)

   761 	{

   762 	iControllerProxy.SendAsync(iDestinationPckg,

   763 							   EMMFControllerAddDataSource,

   764 							   aSourceUid,

   765 							   aSourceInitData,

   766 							   aHandleInfoPckg,

   767 							   aStatus);

   768 	}

   769 

   770 /**

   771 Cancels an outstanding call to the asynchronous version of AddDataSource().

   772 @since	8.0

   773 */

   774 EXPORT_C void RMMFController::CancelAddDataSource()

   775 	{

   776 	iControllerProxy.SendSync(iDestinationPckg,

   777 							  EMMFControllerCancelAddDataSource,

   778 							  KNullDesC8,

   779 							  KNullDesC8);

   780 	}

   781 

   782 /**

   783 Add a data sink to the controller asynchronously, and receive a handle to allow removal and direct

   784 communication with that data sink.

   785 

   786 A typical data sink would be a file, descriptor, audio output (speaker) or display.

   787 A controller plugin may require multiple data sinks to be added (for example a video

   788 playing controller would require two); the exact number is plugin-specific.

   789 Data sinks are plugins themselves, and are loaded by the controller framework

   790 inside the controller thread.

   791 

   792 @param "aSinkUid"			"The uid of the data sink to be added, packaged for async data transfer. 

   793 							The reference must remain valid until the command has been completed or 

   794 							cancelled."

   795 @param "aSinkInitData"		"Data used to initialise the data sink.  The reference must remain valid 

   796 							until the command has been completed or cancelled. The exact contents

   797 							of this data are dependent on the type of data sink. For more

   798 							information, see the documentation for the data sink you wish

   799 							to add."

   800 @param "aHandleInfoPckg"	"This object is filled in by the controller framework, and identifies

   801 							the data sink inside the controller framework.  This allows

   802 							the caller to send custom commands directly to the data sink, and

   803 							to also remove the data sink from the controller.  Note that

   804 							not all data sinks support custom commands, and not all

   805 							controller plugins support the removal of a data sink."

   806 @param "aStatus"			"TRequestStatus of the active object to be signalled on completion

   807 							of this request."

   808 @since	8.0

   809 */

   810 EXPORT_C void RMMFController::AddDataSink(const TMMFUidPckg& aSinkUid, const TDesC8& aSinkInitData, 

   811 										  TMMFMessageDestinationPckg& aHandleInfoPckg, 

   812 										  TRequestStatus& aStatus)

   813 	{

   814 	iControllerProxy.SendAsync(iDestinationPckg,

   815 							   EMMFControllerAddDataSink,

   816 							   aSinkUid,

   817 							   aSinkInitData,

   818 							   aHandleInfoPckg,

   819 							   aStatus);

   820 	}

   821 

   822 

   823 /**

   824 Cancels an outstanding call to the asynchronous version of AddDataSink().

   825 @since	8.0

   826 */

   827 EXPORT_C void RMMFController::CancelAddDataSink()

   828 	{

   829 	iControllerProxy.SendSync(iDestinationPckg,

   830 							  EMMFControllerCancelAddDataSink,

   831 							  KNullDesC8,

   832 							  KNullDesC8);

   833 	}

   834 

   835 /**

   836 Removes a data source from the controller.

   837 

   838 In certain situations, it may be necessary to remove a data source from a controller, for

   839 example when you need to play a different file of the same format as the current one.

   840 

   841 It should be noted that not all controller plugins will support the removal of a data source.

   842 

   843 @param  aHandleInfo

   844         The handle object returned by the controller framework when the

   845         data source was added.

   846 

   847 @return An error code indicating if the function call was successful. KErrNone on success, otherwise

   848         another of the system-wide error codes.

   849 @since  7.0s

   850 */

   851 EXPORT_C TInt RMMFController::RemoveDataSource(const TMMFMessageDestination& aHandleInfo)

   852 	{

   853 	TMMFMessageDestinationPckg pckg(aHandleInfo);

   854 	TInt error = iControllerProxy.SendSync(iDestinationPckg,

   855 										   EMMFControllerRemoveDataSource,

   856 										   pckg,

   857 										   KNullDesC8);

   858 	return error;

   859 	}

   860 

   861 /**

   862 Removes a data sink from the controller.

   863 

   864 In certain situations, it may be necessary to remove a data sink from a controller, for

   865 example when you need change output devices on the fly.

   866 

   867 It should be noted that not all controller plugins will support the removal of a data sink.

   868 

   869 @param  aHandleInfo

   870         The handle object returned by the controller framework when the

   871         data sink was added.

   872 

   873 @return An error code indicating if the function call was successful. KErrNone on success, otherwise

   874         another of the system-wide error codes.

   875 @since  7.0s

   876 */

   877 EXPORT_C TInt RMMFController::RemoveDataSink(const TMMFMessageDestination& aHandleInfo)

   878 	{

   879 	TMMFMessageDestinationPckg pckg(aHandleInfo);

   880 	TInt error = iControllerProxy.SendSync(iDestinationPckg,

   881 										   EMMFControllerRemoveDataSink,

   882 										   pckg,

   883 										   KNullDesC8);

   884 	return error;

   885 	}

   886 

   887 /**

   888 Reverts the controller plugin back to the state it was in just after it had been Opened.

   889 

   890 Note: All sources and sinks will be removed from the controller.

   891 

   892 @return An error code indicating if the function call was successful. KErrNone on success, otherwise

   893         another of the system-wide error codes.

   894 @since  7.0s

   895 */

   896 EXPORT_C TInt RMMFController::Reset()

   897 	{

   898 	return iControllerProxy.SendSync(iDestinationPckg,

   899 									 EMMFControllerReset,

   900 									 KNullDesC8,

   901 									 KNullDesC8);

   902 	}

   903 

   904 /**

   905 Prepares the controller to start playing.

   906 

   907 The controller should initialise its sources, sinks and buffers. This moves the controller

   908 from the STOPPED to the PRIMED state.

   909 

   910 @return An error code indicating if the function call was successful. KErrNone on success, otherwise

   911         another of the system-wide error codes.

   912 @since  7.0s

   913 */

   914 EXPORT_C TInt RMMFController::Prime()

   915 	{

   916 	return iControllerProxy.SendSync(iDestinationPckg,

   917 									 EMMFControllerPrime,

   918 									 KNullDesC8,

   919 									 KNullDesC8);

   920 	}

   921 

   922 /**

   923 Starts the controller playing.

   924 The controller will begin transferring data from its data source(s) to its data sink(s).

   925 

   926 This moves the controller from the PRIMED to the PLAYING state.

   927 

   928 Play() means "Start Playing" - i.e. this method will return as soon as

   929 playback has begun.

   930 

   931 If the data transfer comes to an end due to an internal event (e.g. source runs out of data),

   932 the caller will be notified via the ReceiveEvents() interface.

   933 

   934 Note: 

   935 Prime() must have been called prior to calling Play().

   936 

   937 @return An error code indicating if the function call was successful. KErrNone on success, otherwise

   938         another of the system-wide error codes.

   939 @since  7.0s

   940 */

   941 EXPORT_C TInt RMMFController::Play()

   942 	{

   943 	return iControllerProxy.SendSync(iDestinationPckg,

   944 									 EMMFControllerPlay,

   945 									 KNullDesC8,

   946 									 KNullDesC8);

   947 	}

   948 

   949 /**

   950 Pauses the controller.

   951 

   952 The controller will cease transferring data from its data source(s) to its data sink(s).

   953 A subsequent call to Play() will result in the data transfer resuming from the

   954 same place as when the Pause() was called.

   955 

   956 This moves the controller from the PLAYING back to the PRIMED state.

   957 

   958 Note: 

   959 Play() must have been called prior to calling Pause().

   960 

   961 @return An error code indicating if the function call was successful. KErrNone on success, otherwise

   962         another of the system-wide error codes.

   963 @since  7.0s

   964 */

   965 EXPORT_C TInt RMMFController::Pause()

   966 	{

   967 	return iControllerProxy.SendSync(iDestinationPckg,

   968 									 EMMFControllerPause,

   969 									 KNullDesC8,

   970 									 KNullDesC8);

   971 	}

   972 

   973 /**

   974 Stops the controller.

   975 

   976 The controller will cease transferring data from its data source(s) to its data sink(s), reset

   977 its position and delete any allocated buffers.

   978 In effect, calling Stop() undoes any actions performed by the controller

   979 during the call to Prime().

   980 

   981 This moves the controller from the PRIMED back to the STOPPED state.

   982 

   983 @return An error code indicating if the function call was successful. KErrNone on success, otherwise

   984         another of the system-wide error codes.

   985 @since	7.0s

   986 */

   987 EXPORT_C TInt RMMFController::Stop()

   988 	{

   989 	return iControllerProxy.SendSync(iDestinationPckg,

   990 									 EMMFControllerStop,

   991 									 KNullDesC8,

   992 									 KNullDesC8);

   993 	}

   994 	

   995 /**

   996 Gets the current position microseconds.

   997 

   998 Note: The controller must be in the PRIMED or PLAYING state before this can be called.

   999 

  1000 @param  aPosition

  1001         The current position in microseconds, filled in by the controller framework.

  1002 

  1003 @return An error code indicating if the function call was successful. KErrNone on success, otherwise

  1004         another of the system-wide error codes.

  1005 @since	7.0s

  1006 */

  1007 EXPORT_C TInt RMMFController::GetPosition(TTimeIntervalMicroSeconds& aPosition) const

  1008 	{

  1009 	TMMFTimeIntervalMicroSecondsPckg pckg;

  1010 	TInt err = iControllerProxy.SendSync(iDestinationPckg,

  1011 										 EMMFControllerGetPosition,

  1012 										 KNullDesC8,

  1013 										 KNullDesC8,

  1014 										 pckg);

  1015 	if (!err)

  1016 		aPosition = pckg();

  1017 	return err;

  1018 	}

  1019 

  1020 /**

  1021 Sets the current position microseconds.

  1022 

  1023 Note: The controller must be in the PRIMED or PLAYING state before this can be called.

  1024 

  1025 @param  aPosition

  1026         The new transfer position in microseconds.

  1027 

  1028 @return An error code indicating if the function call was successful. KErrNone on success, otherwise

  1029         another of the system-wide error codes.

  1030 @since  7.0s

  1031 */

  1032 EXPORT_C TInt RMMFController::SetPosition(const TTimeIntervalMicroSeconds& aPosition) const

  1033 	{

  1034 	TMMFTimeIntervalMicroSecondsPckg pckg(aPosition);

  1035 	return iControllerProxy.SendSync(iDestinationPckg,

  1036 									 EMMFControllerSetPosition,

  1037 									 pckg,

  1038 									 KNullDesC8);

  1039 	}

  1040 

  1041 /**

  1042 Gets the duration of the clip in microseconds.

  1043 

  1044 Note: The controller must be in the PRIMED or PLAYING state before this can be called.

  1045 

  1046 @param  aDuration

  1047         The duration of the clip in microseconds, filled in by the

  1048         controller framework.

  1049 

  1050 @return An error code indicating if the function call was successful. KErrNone on success, otherwise

  1051         another of the system-wide error codes.

  1052 @since	7.0s

  1053 */

  1054 EXPORT_C TInt RMMFController::GetDuration(TTimeIntervalMicroSeconds& aDuration) const

  1055 	{

  1056 	TMMFTimeIntervalMicroSecondsPckg pckg;

  1057 	TInt err = iControllerProxy.SendSync(iDestinationPckg,

  1058 										 EMMFControllerGetDuration,

  1059 										 KNullDesC8,

  1060 										 KNullDesC8,

  1061 										 pckg);

  1062 	if (!err)

  1063 		aDuration = pckg();

  1064 	return err;

  1065 	}

  1066 

  1067 /**

  1068 Sends a custom command synchronously to the controller plugin.

  1069 

  1070 Custom commands allow controller plugins to extend the standard API.

  1071 

  1072 Note: This method will not return until the controller plugin has serviced the command.

  1073 

  1074 @param  aDestination

  1075         The destination of the custom command, consisting of the UID of

  1076         the interface of this custom command and a special handle ID,

  1077         KMMFObjectHandleController to indicate that the custom

  1078         command is to be handled by the controller plugin.

  1079 @param  aFunction

  1080         The function number to indicate which function is to be called

  1081         on the controller's custom command interface.

  1082 @param  aDataTo1

  1083         A reference to data to be copied to the controller plugin. The exact

  1084         contents of the data are dependent on the custom command interface

  1085         of the controller.  Use a value of KNullDesC8 if you have no data to send.

  1086 @param  aDataTo2

  1087         A reference to data to be copied to the controller plugin. The exact

  1088         contents of the data are dependent on the custom command interface

  1089         of the controller.  Use a value of KNullDesC8 if you have no data to send.

  1090 @param  aDataFrom

  1091         A reference to an area of memory to which the controller plugin will

  1092         write any data to be passed back to the client.

  1093 

  1094 @return The result of the custom command. Exact range of values is dependent on the custom command interface.

  1095 @since  7.0s

  1096 */

  1097 EXPORT_C TInt RMMFController::CustomCommandSync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2, TDes8& aDataFrom)

  1098 	{

  1099 	return iControllerProxy.SendSync(aDestination,

  1100 									 aFunction,

  1101 									 aDataTo1,

  1102 									 aDataTo2,

  1103 									 aDataFrom);

  1104 	}

  1105 

  1106 /**

  1107 Sends a custom command synchronously to the controller plugin.

  1108 

  1109 Custom commands allow controller plugins to extend the standard API.

  1110 

  1111 Note: This method will not return until the controller plugin has serviced the command.

  1112 

  1113 @param  aDestination

  1114         The destination of the custom command, consisting of the UID of

  1115         the interface of this custom command and a special handle ID,

  1116         KMMFObjectHandleController to indicate that the custom

  1117         command is to be handled by the controller plugin.

  1118 @param  aFunction

  1119         The function number to indicate which function is to be called

  1120         on the controller's custom command interface.

  1121 @param  aDataTo1

  1122         A reference to data to be copied to the controller plugin. The exact

  1123         contents of the data are dependent on the custom command interface

  1124         of the controller. Use a value of KNullDesC8 if you have no data to send.

  1125 @param  aDataTo2

  1126         A reference to data to be copied to the controller plugin. The exact

  1127         contents of the data are dependent on the custom command interface

  1128         of the controller. Use a value of KNullDesC8 if you have no data to send.

  1129 

  1130 @return The result of the custom command. Exact range of values is dependent on the custom command interface.

  1131 @since  7.0s

  1132 */

  1133 EXPORT_C TInt RMMFController::CustomCommandSync(const TMMFMessageDestinationPckg& aDestination, TInt aFunction, const TDesC8& aDataTo1, const TDesC8& aDataTo2)

  1134 	{

  1135 	return iControllerProxy.SendSync(aDestination,