diff -r 4122176ea935 -r 56f325a607ea userlibandfileserver/fileserver/sfsrv/cl_cli.cpp --- a/userlibandfileserver/fileserver/sfsrv/cl_cli.cpp Mon Dec 21 16:14:42 2009 +0000 +++ b/userlibandfileserver/fileserver/sfsrv/cl_cli.cpp Wed Dec 23 11:43:31 2009 +0000 @@ -3479,26 +3479,54 @@ /** -Sets up a pending dismount notifier, the type of which is specified by TNotifyDismountMode. - - EFsDismountRegisterClient - Sets up a notifier to signal the client when a dismount has been requested. - EFsDismountNotifyClients - Notifies all clients (who registered using EFsDismountRegisterClient) of a pending dismount, - signalling the caller when all clients have responded. - EFsDismountForceDismount - Forcibly dismounts the file system without signalling any registered clients. - -This API is intended to be used to allow applications and servers to commit their data to -the media prior to the file system being dismounted. The application forcing the dismount -should first attempt to notify all clients. If all clients don't respond in a a reaonable -time, the dismount request may be cancelled, followed by a forced dismount. - -Any handles left open on the file system shall be disassociated from the media. Attempts to -access these resources shall return with the KErrDismounted error code. - -@param aDriveNo The drive on which to request dismount -@param aMode A TNotifyDismountMode specifying the behaviour of the notification API -@param aStat Completed when all clients have indicated that it is safe to remove the media + Controls file system dismounting on the specified drive, the way of control depends on the parameter TNotifyDismountMode. + + This API allows interested parties to: + 1. Subscribe for notification of file system dismounting events. + This allows subscribers to commit their data to the media prior to the file system being dismounted. + See TNotifyDismountMode::EFsDismountRegisterClient + + 2. Make a graceful attempt to dismount the file system by notifying the subscribers about a pending file system dismount + and waiting until all subscribers have finished processing the notification and have signaled that they are ready. + If all clients don't respond in a reasonable time, the dismount request may be cancelled, followed by a forced dismount. + If some client does not subscribe for dismounting notification and keeps handles opened, then after the file system dismounting all these + handles will become invalid, any subsequent attempts to use them will result in KErrDismounted, and they should be closed(e.g. RFile::Close()). + See TNotifyDismountMode::EFsDismountNotifyClients + + 3. Dismount the file system by force even if there are opened handles (files, directories) on the volume being dismounted. + Any clients that kept handles opened, after forced file system dismounting will have them invalidated. And any further attempts to use + these handles will result in KErrDismounted, and they should be closed(e.g. RFile::Close()). + See TNotifyDismountMode::EFsDismountForceDismount + + * If there are clamped files on the volume, the file system dismounting will not happen until these files are unclamped. + + + The use case scenario: + A 'Master' application that wants to dismount the file system on some drive 'aDrive' + 'Client1' and 'Client2' applications interested in file system dismount event notifications, because they need to commit their data before the file system is dismounted. + + 1. 'Client1' and 'Client2' subscribe to the FS dismount notification using EFsDismountRegisterClient and start waiting on the request status objects. + 2. 'Master' decides to dismount the file system on the drive 'aDrive'. + 2.1 Graceful attempt: 'Master' calls RFs::NotifyDismount() with EFsDismountNotifyClients and starts waiting on 'aStat' for some time until all 'Client1' and 'Client2' respond or timeout occurs. + + 3. 'Client1' and 'Client2' have their 'aStat' completed as the result of the 'Master' calling EFsDismountNotifyClients. + 3.1 'Client1' and 'Client2' flush data and close file handles. + 3.2 as soon as 'Client1' and 'Client2' decide that they are ready for the pending FS dismount, they signal the 'Master' that they are ready by calling RFs::AllowDismount() + + 4. As soon as _all_ subscribed clients ('Client1' and 'Client2') have called RFs::AllowDismount(), the file system on drive 'aDrive' is + dismounted and 'Master' has 'aStat' completed. + + If, for example, 'Client2' hasn't responded in a reasonable time by calling RFs::AllowDismount(), the 'Master' can cancel the pending 'aStat' and + dismount the file system by force by calling this API with EFsDismountForceDismount. + In this case all subsequent attempts by 'Client2' to use its opened handles will result in KErrDismounted; these handles should be closed. + + + + @param aDriveNo The drive on which to request dismount + @param aMode specifies the behaviour of the notification API + @param aStat Asynchronous request state. */ -EFSRV_EXPORT_C void RFs::NotifyDismount(TInt aDrive, TRequestStatus& aStat, TNotifyDismountMode aMode) const +EFSRV_EXPORT_C void RFs::NotifyDismount(TInt aDrive, TRequestStatus& aStat, TNotifyDismountMode aMode /*=EFsDismountRegisterClient*/) const { TRACE4(UTF::EBorder, UTraceModuleEfsrv::EFsNotifyDismount, MODULEUID, Handle(), aDrive, &aStat, aMode); aStat = KRequestPending; @@ -3514,14 +3542,14 @@ +/** + Cancels the oustanding dismount notifier, completing with KErrCancel. + + @param aStat The request status object associated with the request to be cancelled. + + @see RFs::NotifyDismount +*/ EFSRV_EXPORT_C void RFs::NotifyDismountCancel(TRequestStatus& aStat) const -/** -Cancels the oustanding dismount notifier, completing with KErrCancel. - -@param aStat The request status object associated with the request to be cancelled. - -@see RFs::NotifyDismount -*/ { TRACE2(UTF::EBorder, UTraceModuleEfsrv::EFsNotifyDismountCancel1, MODULEUID, Handle(), &aStat); @@ -3533,13 +3561,12 @@ - +/** + Cancels all oustanding dismount notifiers for this session, completing with KErrCancel. + + @see RFs::NotifyDismount +*/ EFSRV_EXPORT_C void RFs::NotifyDismountCancel() const -/** -Cancel all oustanding dismount notifiers for this session, completing with KErrCancel. - -@see RFs::NotifyDismount -*/ { TRACE1(UTF::EBorder, UTraceModuleEfsrv::EFsNotifyDismountCancel2, MODULEUID, Handle()); @@ -3551,21 +3578,19 @@ +/** + Used by a client to indicate that it is safe to dismount the file system. This should be called after receiving a pending media removal notification. + + Not calling this does not guarantee that the dismount will not occur as the application requesting the dismount may decide to forcibly dismount + after a given timeout period. + + @param aDriveNo The drive on which to allow the dismount. + + @return KErrNone if successful + + @see RFs::NotifyDismount +*/ EFSRV_EXPORT_C TInt RFs::AllowDismount(TInt aDrive) const -/** -Used by a client to indicate that it is safe to dismount the file system. -This should be called after receiving a pending media removal notification. - -Not calling this does not guarantee that the dismount will not occur -as the application requesting the dismount may decide to forcibly dismount -after a given timeout period. - -@param aDriveNo The drive on which to allow the dismount. - -@return KErrNone if successful - -@see RFs::NotifyDismount -*/ { TRACE2(UTF::EBorder, UTraceModuleEfsrv::EFsAllowDismount, MODULEUID, Handle(), aDrive); TInt r = SendReceive(EFsAllowDismount, TIpcArgs(aDrive));