1 /*

     2 * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of the License "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

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

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:    My Videos Client API header file*

    15 */

    16 

    17 

    18 

    19 

    20 #ifndef MIPTVMYVIDEOS_H

    21 #define MIPTVMYVIDEOS_H

    22 

    23 #include <e32base.h>

    24 #include "CIptvUtil.h"

    25 

    26 class CIptvMyVideosVideoBriefDetails;

    27 class CIptvMyVideosVideoFullDetails;

    28 class CIptvMyVideosFolder;

    29 class CIptvMyVideosGlobalFileId;

    30 class CIptvMyVideosGlobalFolderId;

    31 class MIptvMyVideosClientObserver;

    32 

    33 /**

    34  * My Videos Client API

    35  *

    36  * @lib IptvEngineClient.dll

    37  */

    38 class MIptvMyVideos

    39     {

    40 

    41 public: // Enumerations

    42 

    43     /**

    44      * TVideoType

    45      *

    46      * @since R2.0

    47      */

    48     enum TVideoType

    49         {

    50         EUndefined   = 0, // Type undefined.

    51         EVodDownload = 1, // Video originated from VoD/VodCast download.

    52         ERecording   = 2, // Video originated from Mobile TV recording.

    53         EMtpVideo    = 3, // Deprecated.

    54         EBrowser     = 4  // Video originated from external source (Browser).

    55         };

    56     

    57 public: // Video Center API

    58     

    59     /**

    60      * Gets folder list in the alphabetical order.

    61      * 

    62      * @param aParentFolderId Points to folder ID which sub-folders should be listed. Note that

    63      *        the root folder ID is generated by CIptvMyVideosGlobalFolderId::NewRootFolderL().

    64      * @param aFrom The start index for listed folders.

    65      * @param aAmount Amount of folders to be listed. If zero, all are listed.

    66      * @param aTotalAmount Reference to a variable where total amount of folders is returned.

    67      * @param aFolderList Reference to a list of items returned.

    68      * @return Error code, KErrNone if no errors, otherwise one of the system wide error codes.

    69      */

    70     virtual TInt GetFolderListL(

    71         CIptvMyVideosGlobalFolderId& aParentFolderId,

    72         TUint32 aFrom,

    73         TUint32 aAmount,

    74         TUint32& aTotalAmount,

    75         RPointerArray<CIptvMyVideosFolder>& aFolderList ) = 0;

    76 

    77     /**

    78      * Gets parent forlder ID identifier. 

    79      * Note that at the beginning of the browse operation, the root folder ID is generated by

    80      * CIptvMyVideosGlobalFolderId::NewRootFolderL().

    81      * 

    82      * @param aFolderId Points to a folder ID which parent folder is requested.

    83      * @param aParentFolder Reference to a storage where to parent folder ID is returned.

    84      * @return Error code, KErrNone if no errors, otherwise one of the system wide error codes.

    85      */

    86     virtual TInt GetParentFolderL(

    87         CIptvMyVideosGlobalFolderId& aFolderId, 

    88         CIptvMyVideosGlobalFolderId& aParentFolder ) = 0;

    89 

    90     /**

    91      * Gets folder name.

    92      *

    93      * @param aFolderId ID of the folder which name is requested.

    94      * @param aName On return, name of the folder.

    95      * @return KErrNone or one of the system wide error codes.

    96      */

    97     virtual TInt GetFolderNameL(

    98         CIptvMyVideosGlobalFolderId& aFolderId, 

    99         TDes& aName ) = 0;

   100 

   101     /**

   102      * Delete folder asynchronously.

   103      * Deletion includes all sub forlders and files at the tree.

   104      * MIptvMyVideosClientObserver::DeleteResponse is called when operation is finished.

   105      * 

   106      * @param aFolderId Points to folder ID to be deleted.

   107      * @return Error code, KErrNone if no errors, otherwise one of the system wide error codes.

   108      */

   109     virtual TInt DeleteFolderReqL(

   110         CIptvMyVideosGlobalFolderId& aFolderId ) = 0;

   111 

   112     /**

   113      * Delete folder.

   114      * Deletion includes all sub forlders and files at the tree.

   115      * 

   116      * @param aFolderId Points to folder ID to be deleted.

   117      * @return Error code, KErrNone if no errors, otherwise one of the system wide error codes.

   118      */

   119     virtual TInt DeleteFolderL(

   120         CIptvMyVideosGlobalFolderId& aFolderId ) = 0;

   121  

   122     /**

   123      * Gets a video list in a chronological order.

   124      * 

   125      * @param aParentFolderId Points to folder ID which video files should be listed.

   126      *                        Note that the root folder ID is generated by

   127      *                        CIptvMyVideosGlobalFolderId::NewRootFolderL().

   128      * @param aFrom           The start index for listed folders.

   129      * @param aAmount         Amount of folders to be listed. If zero, all listed.

   130      * @param aTotalAmount    Reference to a variable where total amount of folders is returned.

   131      * @param aVideoList      Reference to a list of items returned.

   132      * @return Error code, KErrNone if no errors, otherwise one of the system wide error codes.

   133      */

   134     virtual TInt GetVideoListL(

   135         CIptvMyVideosGlobalFolderId& aParentFolderId,

   136         TUint32 aFrom,

   137         TUint32 aAmount,

   138         TUint32& aTotalAmount,

   139         RPointerArray<CIptvMyVideosVideoBriefDetails>& aVideoList ) = 0;

   140 

   141     /**

   142      * Gets full video details.

   143      * 

   144      * @param aFileId Identifier to a video file requested.

   145      * @param aFullDetails Reference to a list of items returned.

   146      * @return Error code, KErrNone if no errors, otherwise one of the system wide error codes.

   147      */

   148     virtual TInt GetVideoDetailsL(

   149         CIptvMyVideosGlobalFileId& aFileId, 

   150         CIptvMyVideosVideoFullDetails& aFullDetails ) = 0;

   151 

   152     /**

   153      * Gets full video details by file localpath

   154      * 

   155      * @since R2.0

   156      * @param aLocalPath Path to video file, used as search key.

   157      * @param aFullDetails Reference to a item to be returned.

   158      * @return Error code, KErrNone if no errors, KErrNotFound if there is no such

   159      *         video. On unexpected error, one of the other system wide error codes.

   160      */

   161     virtual TInt GetVideoDetailsForPathL(

   162         const TDesC& aLocalPath, 

   163         CIptvMyVideosVideoFullDetails& aFullDetails ) = 0;

   164 

   165     /**

   166      * Requests total video lengt and total file size (sum of all videos). 

   167      * The result is returned asynchronously trough observer callback.

   168      * 

   169      * @return Error code, KErrNone if no errors, otherwise one of the system wide error codes.

   170      */

   171     virtual TInt GetTotalVideoLengthRequestL() = 0;

   172 

   173     /**

   174      * Sets video details information.

   175      * 

   176      * @param aVideoFullDetails New video details information.

   177      * @return Error code, KErrNone if no errors, otherwise one of the system wide error codes.

   178      */

   179     virtual TInt SetVideoDetailsL(

   180         CIptvMyVideosVideoFullDetails& aVideoFullDetails ) = 0;

   181 

   182     /**

   183      * Deletes a video asynchronously.

   184      * Operation includes clean up that removes files from file system,

   185      * deletes data related to FileId and releases FileId identifier.

   186      * MIptvMyVideosClientObserver::DeleteResponse is called when operation is finished.

   187      *

   188      * @param aFileId File ID identifier for the video to be deleted.

   189      * @return Error code, KErrNone if no errors, otherwise one of the system wide error codes.

   190      */

   191     virtual TInt DeleteVideoReqL(

   192         CIptvMyVideosGlobalFileId& aFileId ) = 0;

   193 

   194     /**

   195      * Deletes a video.

   196      * Operation includes clean up that removes files from file system,

   197      * deletes data related to FileId and releases FileId identifier.

   198      * 

   199      * @param aFileId File ID identifier for the video to be deleted.

   200      * @return Error code, KErrNone if no errors, otherwise one of the system wide error codes.

   201      */

   202     virtual TInt DeleteVideoL(

   203         CIptvMyVideosGlobalFileId& aFileId ) = 0;

   204 

   205     /**

   206      * Copy video file asynchronously to another My Videos Folder.

   207      * Target drive must be different that source drive.

   208      * MIptvMyVideosClientObserver::CopyOrMoveComplete is called when operation is finished.

   209      *

   210      * @param aSourceFileId Source video file ID to be copied.

   211      * @param aTargetFolderId My Videos target folder where to be copied. Note if target is a root,

   212      *        that root folder ID is generated by CIptvMyVideosGlobalFolderId::NewRootFolderL() with a drive letter.

   213      * @return Error code, KErrNone if no errors, otherwise one of the system wide error codes.

   214      */

   215     virtual TInt CopyReqL(

   216         CIptvMyVideosGlobalFileId& aSourceFileId, 

   217         CIptvMyVideosGlobalFolderId& aTargetFolderId ) = 0;

   218 

   219     /**

   220      * Copy video file synchronously to another My Videos Folder.

   221      * Target drive must be different that source drive.

   222      *

   223      * @param aSourceFileId Source video file ID to be copied.

   224      * @param aTargetFolderId My Videos target folder where to be copied. Note if target is a root,

   225      *        that root folder ID is generated by CIptvMyVideosGlobalFolderId::NewRootFolderL() with a drive letter.

   226      * @return Error code, KErrNone if no errors, otherwise one of the system wide error codes.

   227      */

   228     virtual TInt CopyL(

   229         CIptvMyVideosGlobalFileId& aSourceFileId, 

   230         CIptvMyVideosGlobalFolderId& aTargetFolderId ) = 0;

   231 

   232     /**

   233      * Copy My Videos folder tree and videos asynchronously.

   234      * Target drive must be different that source drive.

   235      * MIptvMyVideosClientObserver::CopyOrMoveComplete is called when operation is finished.

   236      *

   237      * @param aSourceFolderId Source folder ID to be copied.

   238      * @param aTargetFolderId My Videos target folder where to be copied. Note if target is a root, 

   239      *        that root folder ID is generated by CIptvMyVideosGlobalFolderId::NewRootFolderL() with a drive letter.

   240      * @return Error code, KErrNone if no errors, otherwise one of the system wide error codes.

   241      */

   242     virtual TInt CopyReqL(

   243         CIptvMyVideosGlobalFolderId& aSourceFolderId, 

   244         CIptvMyVideosGlobalFolderId& aTargetFolderId ) = 0;

   245 

   246     /**

   247      * Copy My Videos folder tree and videos synchronously.

   248      * Target drive must be different that source drive.

   249      *

   250      * @param aSourceFolderId Source folder ID to be copied.

   251      * @param aTargetFolderId My Videos target folder where to be copied. Note if target is a root,

   252      *        that root folder ID is generated by CIptvMyVideosGlobalFolderId::NewRootFolderL() with a drive letter.

   253      * @param aFailed On return, count of items that could not be copied.

   254      * @return Error code, KErrNone if no errors, otherwise one of the system wide error codes.

   255      */

   256     virtual TInt CopyL(

   257         CIptvMyVideosGlobalFolderId& aSourceFolderId,

   258         CIptvMyVideosGlobalFolderId& aTargetFolderId,

   259         TUint32& aFailed ) = 0;

   260 

   261     /**

   262      * Move video file to another My Videos Folder asynchronously.

   263      * If target is in an another physical file system drive, actual video contents is also moved.

   264      * MIptvMyVideosClientObserver::CopyOrMoveComplete is called when operation is finished.

   265      *

   266      * @param aSourceFileId Source video file ID to be moved.

   267      * @param aTargetFolderId My Videos target folder where to be moved. Note if target is a root,

   268      *        that root folder ID is generated by CIptvMyVideosGlobalFolderId::NewRootFolderL() with a drive letter.

   269      * @return Error code, KErrNone if no errors, otherwise one of the system wide error codes.

   270      */

   271     virtual TInt MoveReqL(

   272         CIptvMyVideosGlobalFileId& aSourceFileId, 

   273         CIptvMyVideosGlobalFolderId& aTargetFolderId ) = 0;

   274 

   275     /**

   276      * Move video file to another My Videos Folder synchronously.

   277      * If target is in an another physical file system drive, actual video contents is also moved.

   278      *

   279      * @param aSourceFileId Source video file ID to be moved.

   280      * @param aTargetFolderId My Videos target folder where to be moved. Note if target is a root,

   281      *        that root folder ID is generated by CIptvMyVideosGlobalFolderId::NewRootFolderL() with a drive letter.

   282      * @return Error code, KErrNone if no errors, otherwise one of the system wide error codes.

   283      */

   284     virtual TInt MoveL(

   285         CIptvMyVideosGlobalFileId& aSourceFileId, 

   286         CIptvMyVideosGlobalFolderId& aTargetFolderId ) = 0;

   287 

   288     /**

   289      * Move My Videos folder tree and videos asynchronously.

   290      * If target is in an another physical file system drive, actual video contents is also moved.

   291      * MIptvMyVideosClientObserver::CopyOrMoveComplete is called when operation is finished.

   292      *

   293      * @param aSourceFolderId Source folder ID to be moved.

   294      * @param aTargetFolderId My Videos target folder where to be moved. Note if target is a root,

   295      *        that root folder ID is generated by CIptvMyVideosGlobalFolderId::NewRootFolderL() with a drive letter.

   296      * @return Error code, KErrNone if no errors, otherwise one of the system wide error codes.

   297      */

   298     virtual TInt MoveReqL(

   299         CIptvMyVideosGlobalFolderId& aSourceFolderId, 

   300         CIptvMyVideosGlobalFolderId& aTargetFolderId ) = 0;

   301 

   302     /**

   303      * Move My Videos folder tree and videos synchronously.

   304      * If target is in an another physical file system drive, actual video contents is also moved.

   305      *

   306      * @param aSourceFolderId Source folder ID to be moved.

   307      * @param aTargetFolderId My Videos target folder where to be moved. Note if target is a root,

   308      *        that root folder ID is generated by CIptvMyVideosGlobalFolderId::NewRootFolderL() with a drive letter.

   309      * @param aFailed On return, count of items that could not be moved.

   310      * @return Error code, KErrNone if no errors, otherwise one of the system wide error codes.

   311      */

   312     virtual TInt MoveL(

   313         CIptvMyVideosGlobalFolderId& aSourceFolderId,

   314         CIptvMyVideosGlobalFolderId& aTargetFolderId,

   315         TUint32& aFailed ) = 0;

   316 

   317     /**

   318      * Cancels any ongoing move or copy operation.

   319      * MIptvMyVideosClientObserver::CopyOrMoveComplete is called when cancel is actually done.

   320      *

   321      * @return Error code, KErrNone if no errors, otherwise one of the system wide error codes.

   322      */

   323     virtual TInt CancelCopyOrMoveL() = 0;

   324 

   325     /**

   326      * Rename My Videos folder.

   327      *

   328      * @param aFolderId Folder to be renamed.

   329      * @param aName New name string.

   330      * @return Error code, KErrNone if no errors, otherwise one of the system wide error codes.

   331      */

   332     virtual TInt RenameDatabaseFolderL(

   333         CIptvMyVideosGlobalFolderId& aFolderId, 

   334         TDesC& aName ) = 0;

   335 

   336     /**

   337      * Create a new My Videos folder.

   338      *

   339      * @param aParentFolderId Parent folder ID where the new folder is created. Note if the parent

   340      *        folder is a root, that root folder ID is generated by 

   341      *        CIptvMyVideosGlobalFolderId::NewRootFolderL() with a drive letter.

   342      * @param aName Name fot the new folder.

   343      * @param aNewFolderId Reference to a storage where new folder ID is returned.

   344      * @return Error code, KErrNone if no errors, otherwise one of the system wide error codes.

   345      */

   346     virtual TInt NewDatabaseFolderL(

   347         CIptvMyVideosGlobalFolderId& aParentFolderId,

   348         TDesC& aName,

   349         CIptvMyVideosGlobalFolderId& aNewFolderId ) = 0;

   350     

   351     /**

   352      * Adds a new video entry to the database.

   353      * 

   354      * @since R2.0

   355      * @param aFullDetails             Full details structure of the video to be added to database.

   356      *                                 Note, this parameter is both input and output parameter.

   357      * @param aVideoType               Type of video, see enumeration TVideoType.

   358      * @param aSizeEstimateInKiloBytes Estimate of the size of the new video. Method will ensure 

   359      *                                 that there is enough free space on disk for the video.

   360      * @return Error code, KErrNone if no errors, KErrNotSupported if video type to add is not supported,

   361      *         KErrArgument if arguments are invalid, KErrDiskFull if there is no space for new video,

   362      *         KErrNotReady if external resources are not available, and possibly other error in 

   363      *         unexpected error  cases.

   364      */

   365     virtual TInt CreateVideoL(

   366         CIptvMyVideosVideoFullDetails& aFullDetails,

   367         TVideoType aVideoType,

   368         TUint32 aSizeEstimateInKiloBytes ) = 0;

   369 

   370     /**

   371      * Ensures that there is enough of free space on disk for new video. This version of the

   372      * method cannot change the used drive, it just tries to free space on current drive.

   373      * 

   374      * @since R2.0

   375      * @param aFileId                   Global File ID of the file that needs the space.

   376      * @param aRequiredSpaceInKiloBytes Required space (size of file) in kilobytes.

   377      * @return Error code, KErrNone if no errors, KErrArgument if the argument is invalid,

   378      *         KErrDiskFull if cannot free enough space for video, and possibly other error

   379      *         in unexpected error cases.

   380      */

   381     virtual TInt EnsureFreeSpaceL(

   382         CIptvMyVideosGlobalFileId& aFileId, 

   383         TUint32 aRequiredSpaceInKiloBytes ) = 0;

   384 

   385     /**

   386      * Ensures that there is enough of free space on disk for new video. This version of the

   387      * method might transfer the video to another drive if current drive cannot provide enough

   388      * of free space. If the video is transferred, the original video entry is removed.

   389      * 

   390      * @since R2.0

   391      * @param aCurrentFileId            Global File ID of the file that needs the space.

   392      * @param aRequiredSpaceInKiloBytes Required space (size of file) in kilobytes.

   393      * @param aNewFileId                Possible new Global File ID of the file if file needs to

   394      *                                  be re-located on another drive. Matches original File ID

   395      *                                  if there is no need for re-location.

   396      * @return Error code, KErrNone if no errors, KErrArgument if the argument is invalid,

   397      *         KErrDiskFull if video needs to be re-located to another drive, KErrCancel if 

   398      *         cannot free enough space for video, and possibly other error in unexpected 

   399      *         error cases.

   400      */

   401     virtual TInt EnsureFreeSpaceL(

   402         CIptvMyVideosGlobalFileId& aCurrentFileId,

   403         TUint32 aRequiredSpaceInKiloBytes,

   404         CIptvMyVideosGlobalFileId& aNewFileId ) = 0;

   405 

   406     /**

   407      * Count total video length and total file size (sum of all videos).

   408      *

   409      * @param aTotalPlayTime Total play time (not used).

   410      * @param aTotalFileSize Total file size in kilo bytes.

   411      * @return Error code,

   412      *         KErrNone if no errors,

   413      *         otherwise one of the system wide error codes.

   414      */

   415     virtual TInt GetTotalVideoLengthL(

   416         TIptvPlayTime& aTotalPlayTime,

   417         TIptvFileSize& aTotalFileSize )= 0;

   418 

   419     /**

   420      * Deletes all videos which are under downloading.

   421      *

   422      * @return Error code,

   423      *         KErrNone if no errors,

   424      *         otherwise one of the system wide error codes.

   425      */

   426     virtual TInt DeleteAllDownloadsL() = 0;

   427     };

   428 

   429 #endif // MIPTVMYVIDEOS_H