<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept xml:lang="en" id="GUID-172F46C1-6066-57FA-A815-5AC23ACE159D"><title>Creating and Preparing a Video Player</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>This tutorial describes how to get started with the video player utility. </p> <section><title>Purpose</title> <p>The purpose of this tutorial is to show you how to create a new video player utility and prepare it for playing video data. </p> <p><b>Required Background</b> </p> <p>The <xref href="GUID-2DC80BA9-7AA2-5CD3-9105-1DE28CE196C1.dita">Video Client Overview</xref> introduces the video client utilities. </p> <p><b>Introduction</b> </p> <p>The video player utility is used to open, play, and obtain information from sampled video data. This functionality is implemented by the <xref href="GUID-0F1F8AC6-B99F-3274-A785-9977197AF762.dita"><apiname>CVideoPlayerUtility</apiname></xref> class. The video data can be supplied either in a file, a descriptor or a URL. </p> </section> <section><title>Using Video Player Utility</title> <p>The following tasks will be covered in this tutorial: </p> <ul><li id="GUID-DB660B71-77EE-5A67-A49A-6A150E3A6698"><p><xref href="GUID-172F46C1-6066-57FA-A815-5AC23ACE159D.dita#GUID-172F46C1-6066-57FA-A815-5AC23ACE159D/GUID-8A89116A-3D6E-5BB4-8A93-D37C0F654CBE">Create a Utility Object</xref>  </p> </li> <li id="GUID-DB5E2060-F2D3-5F84-A280-C7C4E4DE725F"><p><xref href="GUID-172F46C1-6066-57FA-A815-5AC23ACE159D.dita#GUID-172F46C1-6066-57FA-A815-5AC23ACE159D/GUID-8D395F1B-3C5A-5B5F-BB3F-87FE551D0670">Open a Video Source</xref>  </p> </li> <li id="GUID-5ABA016B-A90A-5591-8435-1E2D4E24E72B"><p><xref href="GUID-172F46C1-6066-57FA-A815-5AC23ACE159D.dita#GUID-172F46C1-6066-57FA-A815-5AC23ACE159D/GUID-A65713A3-2373-5DF0-85C6-5ADD83667C5C">Prepare to Play</xref>  </p> </li> </ul> <p id="GUID-8A89116A-3D6E-5BB4-8A93-D37C0F654CBE"><b>Creating a Utility Object</b> </p> <p>The high level steps to construct a video player utility object are shown here: </p> <ul><li id="GUID-B00A14AB-CB00-527B-B6FF-8B480362230F"><p>Create an object of this utility class using the <xref href="GUID-0F1F8AC6-B99F-3274-A785-9977197AF762.dita#GUID-0F1F8AC6-B99F-3274-A785-9977197AF762/GUID-012D95E1-609D-32FC-A8A4-2B109D51054D"><apiname>CVideoPlayerUtility::NewL</apiname></xref> function. </p> </li> </ul> <p id="GUID-8D395F1B-3C5A-5B5F-BB3F-87FE551D0670"><b>Opening a Video Source</b> </p> <p>The high level steps to open a video source are shown here: </p> <ol id="GUID-02B0CD7B-D2CF-57C7-898B-28E19A14FDB9"><li id="GUID-D4A33F3D-4E9B-5EA9-A0F6-88E10FDF2DC2"><p>Unlike <xref href="GUID-778D24B5-A68E-3C91-B66A-69007FBA4791.dita"><apiname>CMdaAudioPlayerUtility</apiname></xref>, video clips cannot be opened during instantiation of the <xref href="GUID-0F1F8AC6-B99F-3274-A785-9977197AF762.dita"><apiname>CVideoPlayerUtility</apiname></xref> class. Hence all the video clips must be opened using one of the following open functions: </p> <ul><li id="GUID-E2DF42A3-ADE6-5937-833F-D64439FB42E4"><p> <b>From a file </b>  </p> <codeblock id="GUID-814C00CA-4CFE-5801-8AE3-183F87526BE6" xml:space="preserve">OpenFileL(const TDesC&amp; aFileName, TUid aControllerUid=KNullUid);

</codeblock> <p>This method opens the video clip from a file. It uses an optionally specified plugin in the argument to load a controller. If no controller plugin is specified, it searches through the list of available plugins and attempts to use each one until successful or the end of the list is reached. </p> <p> <b>Note:</b> There is also another method to open a video clip from a file. It is strongly recommended to use this method. </p> <codeblock id="GUID-195F9272-6DD0-5914-BC7F-D921A82F7CD2" xml:space="preserve">OpenFileL(const TMMSource&amp; aSource, TUid aControllerUid);</codeblock> <p>Where <codeph>aSource</codeph> is a filename or an open handle to a file containing the video clip and <codeph>aControllerUid</codeph> is an optionally specified plugin. If specified, it will force the video player to use the controller with the given UID. If no controller plugin is specified, this function searches through a list of all available plugins and attempts to use each one until successful or the end of the list is reached. </p> </li> <li id="GUID-A990A556-819C-53B7-80DE-D414C18A9B4F"><p> <b>From a descriptor</b>  </p> <codeblock id="GUID-97A4E430-C3AD-5F63-9D74-99E36C2F7107" xml:space="preserve">OpenDesL(const TDesC8&amp; aDescriptor, TUid aControllerUid=KNullUid);</codeblock> <p>This method opens the video clip from a descriptor. It opens the video clip contained as binary data in a descriptor using an optionally specified plugin in the argument to load a controller. If no controller is specified, it searches through the list of available plugins and attempts to use each one until successful or the end of the list is reached. </p> </li> <li id="GUID-8FB9CAE7-B050-57A0-855D-62F9F364FDF9"><p> <b>From an URL</b>  </p> <codeblock id="GUID-DA97F2DF-A98C-5DEF-87B8-83088B45A095" xml:space="preserve">OpenUrlL(const TDesC&amp; aUrl, TInt aIapId = KUseDefaultIap, const TDesC8&amp; aMimeType=KNullDesC8, TUid aControllerUid=KNullUid);</codeblock> <p>This method opens the video clip from the specified URL and identified by the MIME type. In addition a plugin can be specified if necessary. If no controller plugin is specified, this function searches through a list of all available plugins and attempts to use each one until successful or the end of the list is reached. </p> </li> </ul> </li> <li id="GUID-662E06BE-A7E6-565F-80AF-266E6424B717"><p>As the opening of the video clip is complete, successfully or otherwise, the callback function <xref href="GUID-4D07E7B5-AFDD-3D55-8EB6-EDAB61F8C7F9.dita#GUID-4D07E7B5-AFDD-3D55-8EB6-EDAB61F8C7F9/GUID-E728A509-8651-365A-89BA-86486DD70D16"><apiname>MVideoPlayerUtilityObserver::MvpuoOpenComplete()</apiname></xref> is called. This notifies the client whether the video clip was successfully opened or not. </p> </li> </ol> <p> <b>Note:</b> To open and automatically play video clips, use the following open functions: </p> <codeblock id="GUID-DEA0B952-1B0E-5DE4-863A-107E2BCEEFFF" xml:space="preserve">OpenAndPlayFileL(const TDesC&amp; aFileName, TUid aControllerUid=KNullUid);

OpenAndPlayDesL(const TDesC8& aDescriptor, TUid aControllerUid=KNullUid);

OpenAndPlayUrlL(const TDesC&amp; aUrl, TInt aIapId = KUseDefaultIap, const TDesC8&amp; aMimeType=KNullDesC8, TUid aControllerUid=KNullUid);</codeblock> <p id="GUID-A65713A3-2373-5DF0-85C6-5ADD83667C5C"><b>Preparing to Play</b> </p> <p>The high level steps to prepare to play video are shown here: </p> <ol id="GUID-2FA8DE8B-59DB-5C90-9CD4-CDEFFFD99F30"><li id="GUID-AE8AE61F-D2EC-587C-8065-74E7D702AF11"><p>Once the video data is ready, call the <xref href="GUID-0F1F8AC6-B99F-3274-A785-9977197AF762.dita#GUID-0F1F8AC6-B99F-3274-A785-9977197AF762/GUID-B4FB00AA-A85B-3A3F-91BE-C5347462BA95"><apiname>CVideoPlayerUtility::Prepare()</apiname></xref> function. </p> <codeblock id="GUID-EDB242D1-96E8-591A-9E56-CA931EF9C42F" xml:space="preserve">void CVideoPlayerUtility::Prepare()

    {

    iBody->Prepare();