1 /*

     2 * Copyright (c) 2003-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:  Defines a class for accessing files via a file transport protocol

    15 *

    16 */

    17 

    18 

    19 #ifndef CRSFWREMOTEACCESS_H

    20 #define CRSFWREMOTEACCESS_H

    21 

    22 // INCLUDES

    23 #include <e32base.h>

    24 #include <uri16.h>

    25 

    26 //FORWARD DECLARATIONS

    27 class CRsfwDirEntAttr;

    28 class CRsfwDirEnt;

    29 

    30 // CONSTANTS

    31 // 

    32 // UID of this interface

    33 const TUid KCRemoteAccessUid = {0x101F96E3};

    34 // Default quota and free space sizes

    35 const TInt KMountReportedSize         = 10000000;

    36 const TInt KMountReportedFreeSize     = 5000000;

    37 

    38 // Operation option flags

    39 const TUint KRemoteAccessOptionGetToStartOfFile = 0x01;

    40 

    41 // DATA TYPES

    42 // Event types for MRsfwRemoteAccessObserver

    43 enum TRsfwRemoteAccessObserverEvent

    44     {

    45     ERsfwRemoteAccessObserverEventConnection = 1

    46     };

    47 

    48 // Connection events for MRsfwRemoteAccessObserver

    49 enum TRsfwRemoteAccessObserverEventConnection

    50     {

    51     ERsfwRemoteAccessObserverEventConnectionDisconnected = 0,

    52     ERsfwRemoteAccessObserverEventConnectionWeaklyConnected,

    53     ERsfwRemoteAccessObserverEventConnectionStronglyConnected

    54     };

    55 

    56 // CONSTANTS

    57 const TInt KMaxMatchStringSize = 64;

    58 

    59 // CLASS DECLARATION

    60 /**

    61  *  Class for handling remote access events

    62  *

    63  *  @lib rsfwcommon.lib

    64  *  @since Series 60 3.1

    65  */

    66 class MRsfwRemoteAccessObserver

    67     {

    68 public:

    69     /**

    70      * Handles an event emanating from a remote access module.

    71      *

    72      * @param aEventType type of the event

    73      * @param aEvent event code

    74      * @param aArg miscellaneous arguments

    75      */

    76     virtual void HandleRemoteAccessEventL(TInt aEventType,

    77                                           TInt aEvent,

    78                                           TAny* aArg) = 0;

    79     };

    80 

    81 // CLASS DECLARATION

    82 /**

    83  *  Class for handling remote access operation responses.

    84  *

    85  *  @lib rsfwcommon.lib

    86  *  @since Series 60 3.1

    87  */

    88 class MRsfwRemoteAccessResponseHandler

    89     {

    90 public:

    91     /**

    92      * Handles responses for requests to a remote access module.

    93      *

    94      * @param aId transaction id

    95      * @param aStatus return status

    96      */

    97     virtual void HandleRemoteAccessResponse(TUint aId, TInt aStatus) = 0;

    98     };

    99 

   100 

   101 // CLASS DECLARATION

   102 /**

   103  *  Class for accessing files via a file transport protocol, like WebDAV.

   104  *

   105  *  @lib rsfwcommon.lib

   106  *  @since Series 60 3.1

   107  *

   108  *  The derived classes are supposed to be registered and instantiated

   109  *  by using the the ECOM architecture.

   110  */

   111 class CRsfwRemoteAccess : public CBase

   112     {

   113 public:

   114     /**

   115      * Two-phased constructor.

   116      *

   117      * @param aProtocol protocol name, like "http", "https", or "ftp"

   118      * @return a pointer to an object instance that implements

   119      *   this interface by using the given protocol.

   120      */

   121     IMPORT_C static CRsfwRemoteAccess* NewL(const TDesC8& aProtocol);

   122     

   123     IMPORT_C virtual ~CRsfwRemoteAccess();

   124 

   125     /**

   126      * Set up parameters for operation.

   127      * @param aRsfwRemoteAccessObserver MRsfwRemoteAccessObserver for receiving

   128      *  asynchronous events from the accessor plugin,

   129      *  e.g. changes in connectivity.

   130      *  This parameter may be NULL

   131      */

   132     virtual void SetupL(

   133         MRsfwRemoteAccessObserver* aRsfwRemoteAccessObserver) = 0;

   134 

   135     /**

   136      * Opens a connection to the server given by aServerName parameter.

   137      *

   138      * @param aUri URI of the remote repository.

   139      *   The URI must not contain authority part (user name/password)

   140      * @param aFriendlyName friendly name for the server 

   141      *                      (for possible access control dialog) (can be empty)

   142      * @param aUserName user name for access control (can be empty)

   143      * @param aPassword password for access control (can be empty)

   144      * @param aAuxData auxiliary parameters for connection setup (eg IAP info)

   145      * @param aResponseHandler response handler

   146      * @return identifier of the created transaction 

   147      *		   (> 0 for async. operations, 0 if the operation is synchronous 

   148      *		   (has been completed when the call returns)

   149      */

   150     virtual TUint OpenL(const TUriC& aUri,

   151                         const TDesC& aFriendlyName,

   152                         const TDesC& aUserName,

   153                         const TDesC& aPassword,

   154                         const TDesC& aAuxData,

   155                         MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

   156 

   157     /**

   158      * Gets contents of the directory given by aPathName parameter.

   159      *

   160      * @param aPathName path name of the directory

   161      * @param aDirentsp an array of directory entries to be filled.

   162      *   Any pre-existing CRsfwDirEnt items in the array are destroyed 

   163      *   and the array is reset before filling it with pointers to 

   164      *   new entries. Within the created CRsfwDirEntAttr objects, pointers 

   165      *   to descriptors for meta-data items that are not available or 

   166      *   that are irrelevant are set to NULL value.

   167      *   The caller owns the array and thus also the entries.

   168      * @param aResponseHandler response handler

   169      * @return identifier of the created transaction

   170      *		   (> 0 for async. operations, 0 if the operation is synchronous 

   171      *		   (has been completed when the call returns)

   172      */

   173     virtual TUint GetDirectoryL(const TDesC& aPathName,

   174                                 RPointerArray<CRsfwDirEnt>& aDirEntsp,

   175                                 MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

   176 

   177     /**

   178      * Gets attributes of the directory given by aPathName parameter.

   179      * This function may also be called if the type of the object is

   180      * not yet known (e.g., the object could be a file).

   181      *

   182      * @param aPathName path name of the directory

   183      * @param aAttr A pointer to the attribute object to be filled. This 

   184      *   attribute is set to point to a newly created CRsfwDirEntAttr 

   185      *   object that will contain the directory attributes.

   186      *   In the created attribute object, pointers to descriptors for 

   187      *   meta-data items that are not available or that are irrelevant 

   188      *   are set to NULL value. The ownership of the object is 

   189      *   transferred to the caller. If the attributes cannot be defined, 

   190      *   the pointer will be set to NULL.

   191      * @param aResponseHandler response handler

   192      * @return identifier of the created transaction

   193      *		   (> 0 for async. operations, 0 if the operation is synchronous 

   194      *		   (has been completed when the call returns)

   195      */

   196     virtual TUint GetDirectoryAttributesL(const TDesC& aPathName,

   197                                           CRsfwDirEntAttr*& aAttr,

   198                                           MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

   199     

   200     /**

   201      * Gets attributes of the file given by aPathName parameter.

   202      *

   203      * @param aPathName path name of the file

   204      * @param aAttr A pointer to the attribute object to be filled. This 

   205      *   attribute is set to point to a newly created CRsfwDirEntAttr 

   206      *   object that will contain the file attributes.

   207      *   In the created attribute object, pointers to descriptors for 

   208      *   meta-data items that are not available or that are irrelevant 

   209      *   are set to NULL value. The ownership of the object is 

   210      *   transferred to the caller. If the attributes cannot be defined, 

   211      *   the pointer will be set to NULL.

   212      * @param aResponseHandler response handler

   213      * @return identifier of the created transaction

   214      *		   (> 0 for async. operations, 0 if the operation is synchronous 

   215      *		   (has been completed when the call returns)

   216      */

   217     virtual TUint GetFileAttributesL(const TDesC& aPathName,

   218                                      CRsfwDirEntAttr*& aAttr,

   219                                      MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

   220 

   221     /**

   222      * Sets attributes of the file or directory given by aPathName parameter.

   223      * This function is typically only used for files and even then

   224      * the implementation may do nothing since standard file attributes

   225      * are implied by the contents of the file or set in conjunction with

   226      * other operations on the file system object.

   227      *

   228      * @param aPathName path name of the file or directory

   229      * @param aAttr attribute structure

   230      * @param aResponseHandler response handler

   231      * @return identifier of the created transaction

   232      *		   (> 0 for async. operations, 0 if the operation is synchronous 

   233      *		   (has been completed when the call returns)

   234      */

   235     virtual TUint SetAttributesL(const TDesC& aPathName,

   236                                  CRsfwDirEntAttr& aAttr,

   237                                  MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

   238 

   239     /**

   240      * Gets a remote file and copies it to a local file.

   241      * Note that byte ranges are not be implemented by all

   242      * file access protocols. 

   243      * A non-zero aLength means partial get.

   244      * Caller can assume that either aLength remains intact 

   245      * in which case byte range offset + aLength was fetched,

   246      * or aLength is reset to the full length of the file, in which 

   247      * case aOffset is meaningless.

   248      *

   249      * @param aRemotePathName path name of the remote file

   250      * @param aLocalPathName path name of the local file

   251      * @param aOffset offset of the first byte to be accessed

   252      * @param aLength length of data to be accessed/was accessed

   253      * (on entry NULL or zero value means fetching the whole file -

   254      * on exit contains the length of fetched data, unless the pointer is NULL)

   255      * @param aFlags operation qualifier.

   256      *   The following flags have been defined:

   257      *   KRemoteAccessOptionGetToStartOfFile: even if an offset is specified

   258      *      the fetched data is still put at the beginning of the local file.

   259      * @param aResponseHandler response handler

   260      * @return identifier of the created transaction

   261      *		   (> 0 for async. operations, 0 if the operation is synchronous 

   262      *		   (has been completed when the call returns)

   263      */

   264     virtual TUint GetFileL(const TDesC& aRemotePathName,

   265                            const TDesC& aLocalPathName,

   266                            TInt aOffset,

   267                            TInt* aLength,

   268                            TUint aFlags,

   269                            MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

   270 

   271     /**

   272      * Puts a range of a file to the server.

   273      * A non-zero aLength means partial file putting.

   274      * The access protocol/server doesn't have to support partial file putting.

   275      * In this case, it should return KErrNotSupported (if aLength is not zero)

   276      *

   277      * @param aLocalPathName path name of the local file

   278      * @param aRemotePathName path name of the remote file

   279      * @param MIME-type of the file

   280      *   (will be put to Content-Type, e.g. text/plain or

   281      *   application/octet-stream)

   282      * @param aOffset offset of the first byte to be accessed

   283      * @param aLength length of data to be accessed/was accessed (NULL/0=all)

   284      * @param aTotalLength total length of the file, set to 0 if not known

   285      * @param aResponseHandler response handler

   286      * @return identifier of the created transaction 

   287      *		   (> 0 for async. operations, 0 if the operation is synchronous 

   288      *		   (has been completed when the call returns)

   289      */

   290     virtual TUint PutFileL(const TDesC& aLocalPathName,

   291                            const TDesC& aRemotePathName,

   292                            const TDesC8& aMimeType,

   293                            TInt aOffset,

   294                            TInt aLength,

   295                            TInt aTotalLength,

   296                            MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

   297 

   298     /**

   299      * Puts a file to the server.

   300      *

   301      * @param aLocalPathName path name of the local file

   302      * @param aRemotePathName path name of the remote file

   303      * @param MIME-type of the file (will be put to Content-Type,

   304      *   e.g. text/plain or application/octet-stream)

   305      * @param aResponseHandler response handler

   306      * @return identifier of the created transaction 

   307      *		   (> 0 for async. operations, 0 if the operation is synchronous 

   308      *		   (has been completed when the call returns)

   309      */

   310     virtual TUint PutFileL(const TDesC& aLocalPathName,

   311                            const TDesC& aRemotePathName,

   312                            const TDesC8& aMimeType,

   313                            MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

   314 

   315     /**

   316      * Creates an empty file on the remote server

   317      *

   318      * @param aPathName path name of the new file

   319      * @param aResponseHandler response handler

   320      * @param aOverWriting whether we are overwriting an existing file

   321      *        Note that the semantics of this operation is such that it must

   322      *        always overwrite an existing file. This boolean is for information.

   323      *        If the protocol requires additional parameter to allow overwriting,

   324      *        the parameter should be set if aOverWriting is TRUE.

   325      * @return identifier of the created transaction

   326      *		   (> 0 for async. operations, 0 if the operation is synchronous 

   327      *		   (has been completed when the call returns)

   328      */

   329     virtual TUint CreateFileL(const TDesC& aPathName,

   330                               TBool aOverWriting,

   331                               MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

   332 

   333     /**

   334      * Makes a directory.

   335      *

   336      * @param aPathName path name of the new directory

   337      * @param aResponseHandler response handler

   338      * @return identifier of the created transaction

   339      *		   (> 0 for async. operations, 0 if the operation is synchronous 

   340      *		   (has been completed when the call returns)

   341      */

   342     virtual TUint MakeDirectoryL(const TDesC& aPathName,

   343                                  MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

   344 

   345 

   346     /**

   347      * Deletes a directory.

   348      *

   349      * @param aPathName path name of the directory to be deleted

   350      * @param aResponseHandler response handler

   351      * @return identifier of the created transaction

   352      *		   (> 0 for async. operations, 0 if the operation is synchronous 

   353      *		   (has been completed when the call returns)

   354      */

   355 

   356     virtual TUint DeleteDirectoryL(const TDesC& aPathName,

   357                                    MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

   358 

   359     /**

   360      * Deletes a file.

   361      *

   362      * @param aPathName path name of the file to be deleted

   363      * @param aResponseHandler response handler

   364      * @return identifier of the created transaction

   365      *		   (> 0 for async. operations, 0 if the operation is synchronous 

   366      *		   (has been completed when the call returns)

   367      */

   368     virtual TUint DeleteFileL(const TDesC& aPathName,

   369                               MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

   370 

   371 

   372     /**

   373      * Renames a file or a directory.

   374      * (may involve movement to another directory).

   375      *

   376      * @param aSrcPathName path name of the object to be renamed

   377      * @param aDstPathName new path name of the object

   378      * @param aOverwrite allow overwriting an existing object

   379      * @param aResponseHandler response handler

   380      * @return identifier of the created transaction

   381      *		   (> 0 for async. operations, 0 if the operation is synchronous 

   382      *		   (has been completed when the call returns)

   383      */

   384     virtual TUint RenameL(const TDesC& aSrcPathName,

   385                           const TDesC& aDstPathName,

   386                           TBool aOverwrite,

   387                           MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

   388 

   389     /**

   390      * Obtains a lock for the given file system object

   391      * Note that this function is not be implemented by all

   392      * file access protocols (e.g. FTP), some protocols only

   393      * implement write locking (e.g. WebDAV).

   394      *

   395      * @param aPathName path name of the object to be locked

   396      * @param aLockFlags indicates whether a write or read lock is requested

   397      * @param aTimeout the timeout that is requested and granted (in seconds)

   398      * @param aLockToken acquired lock token - the caller gets ownership

   399      * @param aResponseHandler response handler

   400      * @return identifier of the created transaction

   401      *		   (> 0 for async. operations, 0 if the operation is synchronous 

   402      *		   (has been completed when the call returns)

   403      */

   404     virtual TUint ObtainLockL(const TDesC& aPathName,

   405                               TUint aLockFlags,

   406                               TUint& aTimeout,

   407                               TDesC8*& aLockToken,

   408                               MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

   409 

   410     /**

   411      * Releases the lock of the given file system object

   412      * Note that this function is not be implemented by all

   413      * file access protocols (e.g. FTP).

   414      *

   415      * @param aPathName path name of the object to be locked

   416      * @param aResponseHandler response handler

   417      * @return identifier of the created transaction

   418      *		   (> 0 for async. operations, 0 if the operation is synchronous 

   419      *		   (has been completed when the call returns)

   420      */

   421     virtual TUint ReleaseLockL(const TDesC& aPathName,

   422                                MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

   423 

   424     /**

   425      * Refreshes the lock of the given file system object

   426      * Note that this function is not be implemented by all

   427      * file access protocols (e.g. FTP).

   428      *

   429      * @param aPathName path name of the object to be locked

   430      * @param aTimeout the timeout that is requested and granted (in seconds)

   431      * @param aResponseHandler response handler

   432      * @return identifier of the created transaction

   433      *		   (> 0 for async. operations, 0 if the operation is synchronous 

   434      *		   (has been completed when the call returns)

   435      */

   436     virtual TUint RefreshLockL(const TDesC& aPathName,

   437                                TUint& aTimeout,

   438                                MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

   439 

   440     /**

   441      * Cancels a transaction

   442      * Eventually the HandleRemoteAccessResponseL will be called

   443      * with status KErrCancel

   444 

   445      * @param aId the identifier of the transaction to be canceled.

   446      *   If aId is zero, all pending requests are cancelled.

   447      */

   448     virtual void Cancel(TUint aId) = 0;

   449 

   450 		 /**

   451      * Cancels a transaction

   452      * Eventually the HandleRemoteAccessResponseL will be called

   453      * with status KErrCancel

   454 

   455      * @param aTargetPath the path of the target file or directory for the 

   456      * operation that shall be cancelled

   457      * 

   458      */

   459     virtual void Cancel(TDesC& aTargetPath) = 0;

   460 

   461 

   462     /**

   463      * Sets lock token for the a given resource

   464      * This lock token value replaces any previously cached token value

   465      *

   466      * @param aPathName path name

   467      * @param aLockToken lock token

   468      * @return error code

   469      */

   470     virtual TInt SetLockToken(const TDesC& aPathName,

   471                               const TDesC8& aLockToken) = 0;

   472                               

   473      /**

   474      * Gets quota and size.

   475      *

   476      * @param aQuota  The maximum size of the drive for this user in bytes,

   477      * @param aSize  The amount of free space for this user on the disk in bytes.

   478      * @return identifier of the created transaction

   479      *		   (> 0 for async. operations, 0 if the operation is synchronous 

   480      *		   (has been completed when the call returns)

   481      */

   482     IMPORT_C virtual TInt GetQuotaAndSizeL(TInt& aQuota, TInt& aSize);

   483                      

   484 

   485 private:

   486     // Unique instance identifier key

   487     TUid iDtor_ID_Key;

   488     };

   489 

   490 #endif // CRSFWREMOTEACCESS_H

   491 

   492 // End of File