1 /** @file

     2 * Copyright (c) 2005-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 "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:  File sharing interface class

    15 *

    16 */

    17 

    18 

    19 #ifndef C_CUPNPFILESHARING_H

    20 #define C_CUPNPFILESHARING_H

    21 

    22 #include <e32base.h>

    23 #include "upnpobject.h"

    24 

    25 // FORWARD DECLARATIONS

    26 class CUpnpFileSharingBody;

    27 class CUpnpItem;

    28 class CUpnpContainer;

    29 class CUpnpBrowseCriteria;

    30 class CUpnpItemList;

    31 class CUpnpContainerList;

    32 class RUpnpMediaServerClient;

    33 /**

    34  *  Interface class for UPnP File Sharing

    35  *

    36  *  @lib MediaServerClient.lib

    37  *  @since S60 v3.1

    38  */

    39 class CUpnpFileSharing : public CBase

    40     {

    41 

    42 public:

    43     

    44     /**

    45     * Two-phased constructor.

    46     */

    47     IMPORT_C static CUpnpFileSharing* NewL();

    48     

    49     /**

    50     * Destructor.

    51     */

    52     virtual ~CUpnpFileSharing();

    53 

    54 public:     // Interface methods

    55     /**

    56     * Database Clearing function

    57     * Stops mediaserver, delete database file and starts mediaserver

    58     *

    59     * @since S60 3.1

    60     * @param aStatus reference to TRequestStatus which is completed when procedure is over

    61     */

    62     IMPORT_C void DropAllContentL(TRequestStatus& aStatus);

    63     

    64     /**

    65     * Shares a single item asynchronously to Media Server.

    66     * Symbian data base doesn't support foreign key constraints. In order to avoid  

    67     * adding item with nonexistent parent container, parent id existence is checked 

    68     * by Media Server. 

    69     * The item is created with parent id passed as an argument to this operation 

    70     * (object field iParentId value is ignored). 

    71     * After creation input object is updated with:

    72     * - iId - generated object identifier

    73     * - "res" element value - in offline sharing there is no possible to set ip:port 

    74     *    information in URL. "Res" value example: http:///00000001/filename. 

    75     *    For consistency the same approach will be used in online mode.

    76     *

    77     * @since S60 3.1

    78     * @param aContainerId information to which container the item is shared.

    79     * @param aItem reference to item which is shared.

    80     * @param aStatus reference to TRequestStatus which is completed when procedure is over

    81     */

    82     IMPORT_C void ShareItemL( const TDesC8& aContainerId, 

    83                               CUpnpItem& aItem,

    84                               TRequestStatus& aStatus ); 

    85 

    86     /**

    87     * Shares a single container asynchronously to Media Server.

    88     * Nested container and items are ignored.  The container is created with parent id 

    89     * passed as an argument to this operation (object field iParentId value is ignored). 

    90     * Parent id existence is checked by Media Server. 

    91     * After creation input object is updated with the current:

    92     * - iId

    93     *

    94     * @since S60 3.1

    95     * @param aContainerId information to which container the item is shared.

    96     * @param aContainer reference to container which is shared.

    97     * @param aStatus reference to TRequestStatus which is completed when procedure is over

    98     */

    99     IMPORT_C void ShareContainerL( const TDesC8& aParentId, 

   100                                    CUpnpContainer& aContainer,

   101                                    TRequestStatus& aStatus ); 

   102     

   103     /**

   104     * Shares a list of items asynchronously to Media Server. 

   105     * Each CUpnpItem of CUpnpItemList is created with the same parent id passed as 

   106     * an argument to this operation (object field iParentId value is ignored). 

   107     * Parent id existence is checked by Media Server - only once for this operation. 

   108     * Database transaction is committed each 11 objects created into database. 

   109     * This empirical value is hard coded in current implementation. 

   110     * If an execution of task fails when creating object (e.g. 776-th item on list) 

   111     * error code is retuned (aExecStatus), which points to last successfully created item index [1...total count] 

   112     * (e.g. aExecutionStatus = 770 last item in database is object number 770, 

   113     * if no object is cretated index = 0, if all are created index = total count).

   114     *

   115     * Note: There is no support for chunked operations (splitting long operation 

   116     * into sequence of asynchronical calls). Each operation is atomic from 

   117     * Media Server Engine perspective. Long lasting operations may block Media Server Engine. 

   118     * In such case switching Media Server to offline mode is recommended.

   119     *

   120     * For each created item respective input object is updated with:

   121     * - iId

   122     * - "res" element value

   123     *

   124     * @since S60 3.1

   125     * @param aContainerId information to which container the item is shared.

   126     * @param aItemList reference to item list which are to be shared.

   127     * @param aExecStatus reference pointing to the index of item list

   128     * @param aStatus reference to TRequestStatus which is completed when procedure is over

   129     */

   130     IMPORT_C void ShareItemListL( const TDesC8& aContainerId, 

   131                                   CUpnpItemList& aItemList,

   132                                   TInt& aExecStatus,

   133                                   TRequestStatus& aStatus ); 

   134                                     

   135     /**

   136     * Unshares existing item from the Media Server.

   137     * Item with specified id is removed from database regardless "restricted" property value.

   138     * Note: This method removes uploaded file associated with item being destroyed. 

   139     *       Shared files are never removed.

   140     *       

   141     *

   142     * @since S60 3.1

   143     * @param aItemId item which is unshared

   144     * @param aStatus reference to TRequestStatus which is completed when procedure is over

   145     */

   146     IMPORT_C void UnshareItemL( TInt aItemId,

   147                                 TRequestStatus& aStatus);

   148        

   149      

   150     /**

   151     * Unshares existing container from the Media Server.

   152     * Container with its whole branch is removed from database regardless "restricted" 

   153     * property value for this container and any object in branch.

   154     * Object removing is a bottom-up process. If removing of particular object fails 

   155     * whole operation is broken and error is returned. 

   156     *

   157     * Note: This method removes uploaded file associated with item being destroyed. 

   158     *       Shared files are never removed.

   159     *

   160     * Note: The iId value is not verified whether it points to a container or item. 

   161     * Therefore, clients must not use UnshareContainer method with ids pointing to an 

   162     * item or other way round. 

   163     *    

   164     * @since S60 3.1

   165     * @param aContainerId container which is unshared

   166     * @param aStatus reference to TRequestStatus which is completed when procedure is over

   167     */

   168     IMPORT_C void UnshareContainerL( TInt aItemId,

   169                                      TRequestStatus& aStatus );

   170      

   171     /**

   172     * Unshares existing items from the MediaServer.

   173     * Each Item from list is removed from database regardless "restricted" property value.

   174     * Database transaction is committed each 11 objects removed database. 

   175     * If an execution of task fails when creating object error code is retuned, 

   176     * which points to last successfully removed item index.

   177     *

   178     * Note: This method removes uploaded file associated with item being destroyed. 

   179     *       Shared files are never removed.

   180     *

   181     * @since S60 3.1

   182     * @param aItemList list of items which are to be unshared

   183     * @param aExecStatus reference pointing to the index of item list    

   184     * @param aStatus reference to TRequestStatus which is completed when procedure is over

   185     */

   186     IMPORT_C void UnshareItemListL( CUpnpItemList& aItemList,

   187                                 TInt& aExecStatus,

   188                                 TRequestStatus& aStatus);

   189 

   190     /**

   191     * Gets shared item information from MediaServer. 

   192     * This operation returns all properties. Browse criteria is not used.

   193     * Information is returned to item reference.

   194     *

   195     * @since S60 3.1

   196     * @param aItemId item id

   197     * @param aItem reference to item where information is updated.

   198     * @param aStatus reference to TRequestStatus which is completed when procedure is over

   199     */

   200     IMPORT_C void GetSharedItemL( TInt aItemId,

   201                                   CUpnpItem& aItem,

   202                                   TRequestStatus& aStatus );

   203     

   204     

   205     /**

   206     * Gets shared container information from Media Server. 

   207     * Nested container and items are not returned.

   208     * This operation returns all properties. Browse criteria is not used.

   209     * Information is returned to container reference.

   210     *

   211     * @since S60 3.1

   212     * @param aContainerId container id

   213     * @param aContainer reference to container where information is updated.

   214     * @param aStatus reference to TRequestStatus which is completed when procedure is over

   215     */

   216     IMPORT_C void GetSharedContainerL( TInt aItemId,

   217                                        CUpnpContainer& aContainer,

   218                                        TRequestStatus& aStatus );

   219 

   220     /**

   221     * Gets shared items information from Media Server according to supported browse criteria.

   222     * Note: There are only two possible values of filter:

   223     * -    "" (empty filter) only required properties will be returned

   224     * -    "*" (asterisk)  all properties will be returned

   225     * Information is returned to container reference.    

   226     *

   227     * @since S60 3.1

   228     * @param aContainerId id of the container of which items are to be returned

   229     * @param aBrowseCriteria specifies request details, such as requestCount, startingIndes, filter

   230     * @param aItemList reference to item list where information is updated.

   231     * @param aStatus reference to TRequestStatus which is completed when procedure is over

   232     */

   233     IMPORT_C void GetSharedItemListL( TInt aContainerId,

   234                                     CUpnpBrowseCriteria& aBrowseCriteria,

   235                                     CUpnpItemList& aItemList,

   236                                     TInt& aTotalMatches,

   237                                     TRequestStatus& aStatus );

   238     

   239     /**

   240     * Gets shared containers information from Media Server according to supported browse criteria.

   241     * Note: There are only two possible values of filter:

   242     * -    "" (empty filter) only required properties will be returned

   243     * -    "*" (asterisk)  all properties will be returned

   244     * Information is returned to container reference. 

   245     * Nested container are not returned.   

   246     *

   247     * @since S60 3.1

   248     * @param aContainerId id of the container of which items are to be returned

   249     * @param aBrowseCriteria specifies request details, such as requestCount, startingIndes, filter

   250     * @param aItemList reference to item list where information is updated.

   251     * @param aStatus reference to TRequestStatus which is completed when procedure is over

   252     */

   253     IMPORT_C void GetSharedContainerListL( TInt aContainerId,

   254                                     CUpnpBrowseCriteria& aBrowseCriteria,

   255                                     CUpnpContainerList& aItem,

   256                                     TInt& aTotalMatches,

   257                                     TRequestStatus& aStatus );

   258     

   259     /**

   260     * Creates a single reference upon passed item asynchronously in Media Server.    

   261     *

   262     * @since S60 5.0 HN

   263     * @param aContainerId - container id upon which the reference will be located.

   264     * @param aObjectId - the reference is created on the basis of passed object id

   265     * @param aItem reference item to be filled

   266     * @param aStatus reference to TRequestStatus which is completed when procedure is over

   267     */

   268     IMPORT_C void ShareReferenceL( TInt aContainerId, 

   269                             TInt aObjectId,

   270                             CUpnpItem& aItem,

   271                             TRequestStatus& aStatus );

   272 

   273     /**

   274     * Creates some reference items, located at specific container, pointing specific objects

   275     *

   276     * @since S60 5.0 HN

   277     * @param aItemList 'reference item' list which are to be shared

   278     * @param aExecStatus reference pointing to the index of item list

   279     * @param aStatus reference to TRequestStatus which is completed when procedure is over

   280     */

   281     IMPORT_C void ShareReferenceListL( CUpnpItemList& aItemList,

   282                                   TInt& aExecStatus,

   283                                   TRequestStatus& aStatus ); 

   284     /**

   285     * Returns reference to media server client

   286     *

   287     * @since S60 5.0 HN

   288     * @return media server client refernce

   289     */                              

   290     IMPORT_C RUpnpMediaServerClient& CUpnpFileSharing::MediaServerClient( );

   291 

   292 private:

   293 

   294 	/**

   295     * C++ default constructor.

   296     */

   297     CUpnpFileSharing();

   298 	

   299 	/**

   300     * By default Symbian 2nd phase constructor is private.

   301     */

   302     void ConstructL();

   303 

   304 private: // data

   305 

   306     /**

   307      * Actual implementation class for the interface

   308      * Own.

   309      */

   310      CUpnpFileSharingBody* iBody;

   311     };

   312 

   313 

   314 #endif // C_CUPNPFILESHARING_H