diff -r 000000000000 -r 3ad9d5175a89 remotestoragefw/remotefileengine/inc/rsfwremoteaccess.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/remotestoragefw/remotefileengine/inc/rsfwremoteaccess.h Thu Dec 17 09:07:59 2009 +0200 @@ -0,0 +1,492 @@ +/* +* 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 +#include + +//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& 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