3477 |
3477 |
3478 |
3478 |
3479 |
3479 |
3480 |
3480 |
3481 /** |
3481 /** |
3482 Sets up a pending dismount notifier, the type of which is specified by TNotifyDismountMode. |
3482 Controls file system dismounting on the specified drive, the way of control depends on the parameter TNotifyDismountMode. |
3483 |
3483 |
3484 EFsDismountRegisterClient - Sets up a notifier to signal the client when a dismount has been requested. |
3484 This API allows interested parties to: |
3485 EFsDismountNotifyClients - Notifies all clients (who registered using EFsDismountRegisterClient) of a pending dismount, |
3485 1. Subscribe for notification of file system dismounting events. |
3486 signalling the caller when all clients have responded. |
3486 This allows subscribers to commit their data to the media prior to the file system being dismounted. |
3487 EFsDismountForceDismount - Forcibly dismounts the file system without signalling any registered clients. |
3487 See TNotifyDismountMode::EFsDismountRegisterClient |
3488 |
3488 |
3489 This API is intended to be used to allow applications and servers to commit their data to |
3489 2. Make a graceful attempt to dismount the file system by notifying the subscribers about a pending file system dismount |
3490 the media prior to the file system being dismounted. The application forcing the dismount |
3490 and waiting until all subscribers have finished processing the notification and have signaled that they are ready. |
3491 should first attempt to notify all clients. If all clients don't respond in a a reaonable |
3491 If all clients don't respond in a reasonable time, the dismount request may be cancelled, followed by a forced dismount. |
3492 time, the dismount request may be cancelled, followed by a forced dismount. |
3492 If some client does not subscribe for dismounting notification and keeps handles opened, then after the file system dismounting all these |
3493 |
3493 handles will become invalid, any subsequent attempts to use them will result in KErrDismounted, and they should be closed(e.g. RFile::Close()). |
3494 Any handles left open on the file system shall be disassociated from the media. Attempts to |
3494 See TNotifyDismountMode::EFsDismountNotifyClients |
3495 access these resources shall return with the KErrDismounted error code. |
3495 |
3496 |
3496 3. Dismount the file system by force even if there are opened handles (files, directories) on the volume being dismounted. |
3497 @param aDriveNo The drive on which to request dismount |
3497 Any clients that kept handles opened, after forced file system dismounting will have them invalidated. And any further attempts to use |
3498 @param aMode A TNotifyDismountMode specifying the behaviour of the notification API |
3498 these handles will result in KErrDismounted, and they should be closed(e.g. RFile::Close()). |
3499 @param aStat Completed when all clients have indicated that it is safe to remove the media |
3499 See TNotifyDismountMode::EFsDismountForceDismount |
3500 */ |
3500 |
3501 EFSRV_EXPORT_C void RFs::NotifyDismount(TInt aDrive, TRequestStatus& aStat, TNotifyDismountMode aMode) const |
3501 * If there are clamped files on the volume, the file system dismounting will not happen until these files are unclamped. |
|
3502 |
|
3503 |
|
3504 The use case scenario: |
|
3505 A 'Master' application that wants to dismount the file system on some drive 'aDrive' |
|
3506 'Client1' and 'Client2' applications interested in file system dismount event notifications, because they need to commit their data before the file system is dismounted. |
|
3507 |
|
3508 1. 'Client1' and 'Client2' subscribe to the FS dismount notification using EFsDismountRegisterClient and start waiting on the request status objects. |
|
3509 2. 'Master' decides to dismount the file system on the drive 'aDrive'. |
|
3510 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. |
|
3511 |
|
3512 3. 'Client1' and 'Client2' have their 'aStat' completed as the result of the 'Master' calling EFsDismountNotifyClients. |
|
3513 3.1 'Client1' and 'Client2' flush data and close file handles. |
|
3514 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() |
|
3515 |
|
3516 4. As soon as _all_ subscribed clients ('Client1' and 'Client2') have called RFs::AllowDismount(), the file system on drive 'aDrive' is |
|
3517 dismounted and 'Master' has 'aStat' completed. |
|
3518 |
|
3519 If, for example, 'Client2' hasn't responded in a reasonable time by calling RFs::AllowDismount(), the 'Master' can cancel the pending 'aStat' and |
|
3520 dismount the file system by force by calling this API with EFsDismountForceDismount. |
|
3521 In this case all subsequent attempts by 'Client2' to use its opened handles will result in KErrDismounted; these handles should be closed. |
|
3522 |
|
3523 |
|
3524 |
|
3525 @param aDriveNo The drive on which to request dismount |
|
3526 @param aMode specifies the behaviour of the notification API |
|
3527 @param aStat Asynchronous request state. |
|
3528 */ |
|
3529 EFSRV_EXPORT_C void RFs::NotifyDismount(TInt aDrive, TRequestStatus& aStat, TNotifyDismountMode aMode /*=EFsDismountRegisterClient*/) const |
3502 { |
3530 { |
3503 TRACE4(UTF::EBorder, UTraceModuleEfsrv::EFsNotifyDismount, MODULEUID, Handle(), aDrive, &aStat, aMode); |
3531 TRACE4(UTF::EBorder, UTraceModuleEfsrv::EFsNotifyDismount, MODULEUID, Handle(), aDrive, &aStat, aMode); |
3504 aStat = KRequestPending; |
3532 aStat = KRequestPending; |
3505 RSessionBase::SendReceive(EFsNotifyDismount, TIpcArgs(aDrive,aMode,&aStat), aStat); |
3533 RSessionBase::SendReceive(EFsNotifyDismount, TIpcArgs(aDrive,aMode,&aStat), aStat); |
3506 // This call is to synchronise with the driver thread as the corresponding cancel function (NotifyDismountCancel) |
3534 // This call is to synchronise with the driver thread as the corresponding cancel function (NotifyDismountCancel) |
3512 } |
3540 } |
3513 |
3541 |
3514 |
3542 |
3515 |
3543 |
3516 |
3544 |
|
3545 /** |
|
3546 Cancels the oustanding dismount notifier, completing with KErrCancel. |
|
3547 |
|
3548 @param aStat The request status object associated with the request to be cancelled. |
|
3549 |
|
3550 @see RFs::NotifyDismount |
|
3551 */ |
3517 EFSRV_EXPORT_C void RFs::NotifyDismountCancel(TRequestStatus& aStat) const |
3552 EFSRV_EXPORT_C void RFs::NotifyDismountCancel(TRequestStatus& aStat) const |
3518 /** |
|
3519 Cancels the oustanding dismount notifier, completing with KErrCancel. |
|
3520 |
|
3521 @param aStat The request status object associated with the request to be cancelled. |
|
3522 |
|
3523 @see RFs::NotifyDismount |
|
3524 */ |
|
3525 { |
3553 { |
3526 TRACE2(UTF::EBorder, UTraceModuleEfsrv::EFsNotifyDismountCancel1, MODULEUID, Handle(), &aStat); |
3554 TRACE2(UTF::EBorder, UTraceModuleEfsrv::EFsNotifyDismountCancel1, MODULEUID, Handle(), &aStat); |
3527 |
3555 |
3528 if (aStat == KRequestPending) |
3556 if (aStat == KRequestPending) |
3529 SendReceive(EFsNotifyDismountCancel, TIpcArgs(&aStat)); |
3557 SendReceive(EFsNotifyDismountCancel, TIpcArgs(&aStat)); |
3549 } |
3576 } |
3550 |
3577 |
3551 |
3578 |
3552 |
3579 |
3553 |
3580 |
|
3581 /** |
|
3582 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. |
|
3583 |
|
3584 Not calling this does not guarantee that the dismount will not occur as the application requesting the dismount may decide to forcibly dismount |
|
3585 after a given timeout period. |
|
3586 |
|
3587 @param aDriveNo The drive on which to allow the dismount. |
|
3588 |
|
3589 @return KErrNone if successful |
|
3590 |
|
3591 @see RFs::NotifyDismount |
|
3592 */ |
3554 EFSRV_EXPORT_C TInt RFs::AllowDismount(TInt aDrive) const |
3593 EFSRV_EXPORT_C TInt RFs::AllowDismount(TInt aDrive) const |
3555 /** |
|
3556 Used by a client to indicate that it is safe to dismount the file system. |
|
3557 This should be called after receiving a pending media removal notification. |
|
3558 |
|
3559 Not calling this does not guarantee that the dismount will not occur |
|
3560 as the application requesting the dismount may decide to forcibly dismount |
|
3561 after a given timeout period. |
|
3562 |
|
3563 @param aDriveNo The drive on which to allow the dismount. |
|
3564 |
|
3565 @return KErrNone if successful |
|
3566 |
|
3567 @see RFs::NotifyDismount |
|
3568 */ |
|
3569 { |
3594 { |
3570 TRACE2(UTF::EBorder, UTraceModuleEfsrv::EFsAllowDismount, MODULEUID, Handle(), aDrive); |
3595 TRACE2(UTF::EBorder, UTraceModuleEfsrv::EFsAllowDismount, MODULEUID, Handle(), aDrive); |
3571 TInt r = SendReceive(EFsAllowDismount, TIpcArgs(aDrive)); |
3596 TInt r = SendReceive(EFsAllowDismount, TIpcArgs(aDrive)); |
3572 |
3597 |
3573 TRACERET1(UTF::EBorder, UTraceModuleEfsrv::EFsAllowDismountReturn, MODULEUID, r); |
3598 TRACERET1(UTF::EBorder, UTraceModuleEfsrv::EFsAllowDismountReturn, MODULEUID, r); |