/*

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

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "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:

*

* Description:  Defines a class for accessing files via a file transport protocol

*

*/

#ifndef CRSFWREMOTEACCESS_H

#define CRSFWREMOTEACCESS_H

// INCLUDES

#include <e32base.h>

#include <uri16.h>

//FORWARD DECLARATIONS

class CRsfwDirEntAttr;

class CRsfwDirEnt;

// CONSTANTS

// 

// UID of this interface

const TUid KCRemoteAccessUid = {0x101F96E3};

// Default quota and free space sizes

const TInt KMountReportedSize         = 10000000;

const TInt KMountReportedFreeSize     = 5000000;

// Operation option flags

const TUint KRemoteAccessOptionGetToStartOfFile = 0x01;

// DATA TYPES

// Event types for MRsfwRemoteAccessObserver

enum TRsfwRemoteAccessObserverEvent

    {

    ERsfwRemoteAccessObserverEventConnection = 1

    };

// Connection events for MRsfwRemoteAccessObserver

enum TRsfwRemoteAccessObserverEventConnection

    {

    ERsfwRemoteAccessObserverEventConnectionDisconnected = 0,

    ERsfwRemoteAccessObserverEventConnectionWeaklyConnected,

    ERsfwRemoteAccessObserverEventConnectionStronglyConnected

    };

// CONSTANTS

const TInt KMaxMatchStringSize = 64;

// CLASS DECLARATION

/**

 *  Class for handling remote access events

 *

 *  @lib rsfwcommon.lib

 *  @since Series 60 3.1

 */

class MRsfwRemoteAccessObserver

    {

public:

    /**

     * Handles an event emanating from a remote access module.

     *

     * @param aEventType type of the event

     * @param aEvent event code

     * @param aArg miscellaneous arguments

     */

    virtual void HandleRemoteAccessEventL(TInt aEventType,

                                          TInt aEvent,

                                          TAny* aArg) = 0;

    };

// CLASS DECLARATION

/**

 *  Class for handling remote access operation responses.

 *

 *  @lib rsfwcommon.lib

 *  @since Series 60 3.1

 */

class MRsfwRemoteAccessResponseHandler

    {

public:

    /**

     * Handles responses for requests to a remote access module.

     *

     * @param aId transaction id

     * @param aStatus return status

     */

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

    };

// CLASS DECLARATION

/**

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

 *

 *  @lib rsfwcommon.lib

 *  @since Series 60 3.1

 *

 *  The derived classes are supposed to be registered and instantiated

 *  by using the the ECOM architecture.

 */

class CRsfwRemoteAccess : public CBase

    {

public:

    /**

     * Two-phased constructor.

     *

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

     * @return a pointer to an object instance that implements

     *   this interface by using the given protocol.

     */

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

    IMPORT_C virtual ~CRsfwRemoteAccess();

    /**

     * Set up parameters for operation.

     * @param aRsfwRemoteAccessObserver MRsfwRemoteAccessObserver for receiving

     *  asynchronous events from the accessor plugin,

     *  e.g. changes in connectivity.

     *  This parameter may be NULL

     */

    virtual void SetupL(

        MRsfwRemoteAccessObserver* aRsfwRemoteAccessObserver) = 0;

    /**

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

     *

     * @param aUri URI of the remote repository.

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

     * @param aFriendlyName friendly name for the server 

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

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

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

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

     * @param aResponseHandler response handler

     * @return identifier of the created transaction 

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

     *		   (has been completed when the call returns)

     */

    virtual TUint OpenL(const TUriC& aUri,

                        const TDesC& aFriendlyName,

                        const TDesC& aUserName,

                        const TDesC& aPassword,

                        const TDesC& aAuxData,

                        MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

    /**

     * Gets contents of the directory given by aPathName parameter.

     *

     * @param aPathName path name of the directory

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

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

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

     *   new entries. Within the created CRsfwDirEntAttr objects, pointers 

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

     *   that are irrelevant are set to NULL value.

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

     * @param aResponseHandler response handler

     * @return identifier of the created transaction

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

     *		   (has been completed when the call returns)

     */

    virtual TUint GetDirectoryL(const TDesC& aPathName,

                                RPointerArray<CRsfwDirEnt>& aDirEntsp,

                                MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

    /**

     * Gets attributes of the directory given by aPathName parameter.

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

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

     *

     * @param aPathName path name of the directory

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

     *   attribute is set to point to a newly created CRsfwDirEntAttr 

     *   object that will contain the directory attributes.

     *   In the created attribute object, pointers to descriptors for 

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

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

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

     *   the pointer will be set to NULL.

     * @param aResponseHandler response handler

     * @return identifier of the created transaction

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

     *		   (has been completed when the call returns)

     */

    virtual TUint GetDirectoryAttributesL(const TDesC& aPathName,

                                          CRsfwDirEntAttr*& aAttr,

                                          MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

    /**

     * Gets attributes of the file given by aPathName parameter.

     *

     * @param aPathName path name of the file

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

     *   attribute is set to point to a newly created CRsfwDirEntAttr 

     *   object that will contain the file attributes.

     *   In the created attribute object, pointers to descriptors for 

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

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

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

     *   the pointer will be set to NULL.

     * @param aResponseHandler response handler

     * @return identifier of the created transaction

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

     *		   (has been completed when the call returns)

     */

    virtual TUint GetFileAttributesL(const TDesC& aPathName,

                                     CRsfwDirEntAttr*& aAttr,

                                     MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

    /**

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

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

     * the implementation may do nothing since standard file attributes

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

     * other operations on the file system object.

     *

     * @param aPathName path name of the file or directory

     * @param aAttr attribute structure

     * @param aResponseHandler response handler

     * @return identifier of the created transaction

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

     *		   (has been completed when the call returns)

     */

    virtual TUint SetAttributesL(const TDesC& aPathName,

                                 CRsfwDirEntAttr& aAttr,

                                 MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

    /**

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

     * Note that byte ranges are not be implemented by all

     * file access protocols. 

     * A non-zero aLength means partial get.

     * Caller can assume that either aLength remains intact 

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

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

     * case aOffset is meaningless.

     *

     * @param aRemotePathName path name of the remote file

     * @param aLocalPathName path name of the local file

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

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

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

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

     * @param aFlags operation qualifier.

     *   The following flags have been defined:

     *   KRemoteAccessOptionGetToStartOfFile: even if an offset is specified

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

     * @param aResponseHandler response handler

     * @return identifier of the created transaction

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

     *		   (has been completed when the call returns)

     */

    virtual TUint GetFileL(const TDesC& aRemotePathName,

                           const TDesC& aLocalPathName,

                           TInt aOffset,

                           TInt* aLength,

                           TUint aFlags,

                           MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

    /**

     * Puts a range of a file to the server.

     * A non-zero aLength means partial file putting.

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

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

     *

     * @param aLocalPathName path name of the local file

     * @param aRemotePathName path name of the remote file

     * @param MIME-type of the file

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

     *   application/octet-stream)

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

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

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

     * @param aResponseHandler response handler

     * @return identifier of the created transaction 

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

     *		   (has been completed when the call returns)

     */

    virtual TUint PutFileL(const TDesC& aLocalPathName,

                           const TDesC& aRemotePathName,

                           const TDesC8& aMimeType,

                           TInt aOffset,

                           TInt aLength,

                           TInt aTotalLength,

                           MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

    /**

     * Puts a file to the server.

     *

     * @param aLocalPathName path name of the local file

     * @param aRemotePathName path name of the remote file

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

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

     * @param aResponseHandler response handler

     * @return identifier of the created transaction 

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

     *		   (has been completed when the call returns)

     */

    virtual TUint PutFileL(const TDesC& aLocalPathName,

                           const TDesC& aRemotePathName,

                           const TDesC8& aMimeType,

                           MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

    /**

     * Creates an empty file on the remote server

     *

     * @param aPathName path name of the new file

     * @param aResponseHandler response handler

     * @param aOverWriting whether we are overwriting an existing file

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

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

     *        If the protocol requires additional parameter to allow overwriting,

     *        the parameter should be set if aOverWriting is TRUE.

     * @return identifier of the created transaction

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

     *		   (has been completed when the call returns)

     */

    virtual TUint CreateFileL(const TDesC& aPathName,

                              TBool aOverWriting,

                              MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

    /**

     * Makes a directory.

     *

     * @param aPathName path name of the new directory

     * @param aResponseHandler response handler

     * @return identifier of the created transaction

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

     *		   (has been completed when the call returns)

     */

    virtual TUint MakeDirectoryL(const TDesC& aPathName,

                                 MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

    /**

     * Deletes a directory.

     *

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

     * @param aResponseHandler response handler

     * @return identifier of the created transaction

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

     *		   (has been completed when the call returns)

     */

    virtual TUint DeleteDirectoryL(const TDesC& aPathName,

                                   MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

    /**

     * Deletes a file.

     *

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

     * @param aResponseHandler response handler

     * @return identifier of the created transaction

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

     *		   (has been completed when the call returns)

     */

    virtual TUint DeleteFileL(const TDesC& aPathName,

                              MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

    /**

     * Renames a file or a directory.

     * (may involve movement to another directory).

     *

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

     * @param aDstPathName new path name of the object

     * @param aOverwrite allow overwriting an existing object

     * @param aResponseHandler response handler

     * @return identifier of the created transaction

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

     *		   (has been completed when the call returns)

     */

    virtual TUint RenameL(const TDesC& aSrcPathName,

                          const TDesC& aDstPathName,

                          TBool aOverwrite,

                          MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

    /**

     * Obtains a lock for the given file system object

     * Note that this function is not be implemented by all

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

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

     *

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

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

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

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

     * @param aResponseHandler response handler

     * @return identifier of the created transaction

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

     *		   (has been completed when the call returns)

     */

    virtual TUint ObtainLockL(const TDesC& aPathName,

                              TUint aLockFlags,

                              TUint& aTimeout,

                              TDesC8*& aLockToken,

                              MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

    /**

     * Releases the lock of the given file system object

     * Note that this function is not be implemented by all

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

     *

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

     * @param aResponseHandler response handler

     * @return identifier of the created transaction

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

     *		   (has been completed when the call returns)

     */

    virtual TUint ReleaseLockL(const TDesC& aPathName,

                               MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

    /**

     * Refreshes the lock of the given file system object

     * Note that this function is not be implemented by all

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

     *

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

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

     * @param aResponseHandler response handler

     * @return identifier of the created transaction

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

     *		   (has been completed when the call returns)

     */

    virtual TUint RefreshLockL(const TDesC& aPathName,

                               TUint& aTimeout,

                               MRsfwRemoteAccessResponseHandler* aResponseHandler) = 0;

    /**

     * Cancels a transaction

     * Eventually the HandleRemoteAccessResponseL will be called

     * with status KErrCancel

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

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

     */

    virtual void Cancel(TUint aId) = 0;

		 /**

     * Cancels a transaction

     * Eventually the HandleRemoteAccessResponseL will be called

     * with status KErrCancel

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

     * operation that shall be cancelled

     * 

     */

    virtual void Cancel(TDesC& aTargetPath) = 0;

    /**

     * Sets lock token for the a given resource

     * This lock token value replaces any previously cached token value

     *

     * @param aPathName path name

     * @param aLockToken lock token

     * @return error code

     */

    virtual TInt SetLockToken(const TDesC& aPathName,

                              const TDesC8& aLockToken) = 0;

     /**

     * Gets quota and size.

     *

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

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

     * @return identifier of the created transaction

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

     *		   (has been completed when the call returns)

     */

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

private:

    // Unique instance identifier key

    TUid iDtor_ID_Key;

    };

#endif // CRSFWREMOTEACCESS_H

// End of File