642 |
642 |
643 |
643 |
644 |
644 |
645 /** |
645 /** |
646 Gets the name of the file system mounted on the specified drive. |
646 Gets the name of the file system mounted on the specified drive. |
647 |
|
648 The function can be called before calling DismountFileSystem(). |
647 The function can be called before calling DismountFileSystem(). |
649 |
648 |
650 @param aName On successful return, contains the name of the file system. |
649 @param aName On successful return, contains the name of the file system. |
651 @param aDrive The drive for which the file system name is required. |
650 @param aDrive The drive for which the file system name is required. |
|
651 |
|
652 Note that the file system name, returned in the aName descriptor shall be threated as case-insensitive string. I.e. |
|
653 "fileSystem" and "FILESYSTEM" mean absolutely the same. Therefore, case-insensitive string methods (like TDesC::FindF(), TDesC::CompareF()) |
|
654 shall be used to deal with the names. |
652 |
655 |
653 @return KErrNone, if successful; |
656 @return KErrNone, if successful; |
654 KErrNotFound if aFileSystemName is not found, or the drive does not have a file system mounted on it; |
657 KErrNotFound if aFileSystemName is not found, or the drive does not have a file system mounted on it; |
655 KErrArgument, if the drive value is outside the valid range, i.e. zero to KMaxDrives-1 inclusive. |
658 KErrArgument, if the drive value is outside the valid range, i.e. zero to KMaxDrives-1 inclusive. |
656 |
659 |
673 file systems that can be recognised and mounted automatically, without user's interaction. |
676 file systems that can be recognised and mounted automatically, without user's interaction. |
674 If the automatic recognition and mountng some known file systems is supported on the specified drive, there |
677 If the automatic recognition and mountng some known file systems is supported on the specified drive, there |
675 shall be at least 2 names in the list. For example "FAT" and "exFAT". |
678 shall be at least 2 names in the list. For example "FAT" and "exFAT". |
676 If "automatic file system recognising" feature is not supported, the list will consist of just one name, and |
679 If "automatic file system recognising" feature is not supported, the list will consist of just one name, and |
677 this will be the name returned by RFs::FileSystemName() API. |
680 this will be the name returned by RFs::FileSystemName() API. |
|
681 |
|
682 Note that the file system name, returned in the aName descriptor shall be threated as case-insensitive string. I.e. |
|
683 "fileSystem" and "FILESYSTEM" mean absolutely the same. Therefore, case-insensitive string methods (like TDesC::FindF(), TDesC::CompareF()) |
|
684 shall be used to deal with the names. |
678 |
685 |
679 @param aName On successful return, contains the name of the file system that correspond to the aFsEnumerator value. |
686 @param aName On successful return, contains the name of the file system that correspond to the aFsEnumerator value. |
680 m@param aDrive The drive number |
687 m@param aDrive The drive number |
681 @param aFsEnumerator The supported file system enumerator. can be: |
688 @param aFsEnumerator The supported file system enumerator. can be: |
682 KRootFileSystem a special value; in this case the returned name will be the same as obtained by FileSystemName() |
689 KRootFileSystem a special value; in this case the returned name will be the same as obtained by FileSystemName() |
2643 3, if successful but an unallocated cluster contains a value; |
2648 3, if successful but an unallocated cluster contains a value; |
2644 4, if successful but the size of a file is not equal to the number of clusters in chain; |
2649 4, if successful but the size of a file is not equal to the number of clusters in chain; |
2645 KErrNotReady, if the specified drive is empty; |
2650 KErrNotReady, if the specified drive is empty; |
2646 KErrNotSupported, if the drive cannot handle this request; |
2651 KErrNotSupported, if the drive cannot handle this request; |
2647 KErrPermissionDenied, if the caller doesn't have DiskAdmin capability; |
2652 KErrPermissionDenied, if the caller doesn't have DiskAdmin capability; |
2648 KErrTooBig, if the drives folder depth exceeds maximum allowed. For the current FAT file system implementation this limit is 50. |
|
2649 Other system wide error codes may also be returned. |
2653 Other system wide error codes may also be returned. |
2650 |
2654 |
2651 @capability DiskAdmin |
2655 @capability DiskAdmin |
2652 */ |
2656 */ |
|
2657 EFSRV_EXPORT_C TInt RFs::CheckDisk(const TDesC& aDrive) const |
2653 { |
2658 { |
2654 TRACEMULT2(UTF::EBorder, UTraceModuleEfsrv::EFsCheckDisk, MODULEUID, Handle(), aDrive); |
2659 TRACEMULT2(UTF::EBorder, UTraceModuleEfsrv::EFsCheckDisk, MODULEUID, Handle(), aDrive); |
2655 TInt r = SendReceive(EFsCheckDisk,TIpcArgs(&aDrive)); |
2660 TInt r = SendReceive(EFsCheckDisk,TIpcArgs(&aDrive)); |
2656 |
2661 |
2657 TRACERET1(UTF::EBorder, UTraceModuleEfsrv::EFsCheckDiskReturn, MODULEUID, r); |
2662 TRACERET1(UTF::EBorder, UTraceModuleEfsrv::EFsCheckDiskReturn, MODULEUID, r); |
3477 |
3482 |
3478 |
3483 |
3479 |
3484 |
3480 |
3485 |
3481 /** |
3486 /** |
3482 Sets up a pending dismount notifier, the type of which is specified by TNotifyDismountMode. |
3487 Controls file system dismounting on the specified drive, the way of control depends on the parameter TNotifyDismountMode. |
3483 |
3488 |
3484 EFsDismountRegisterClient - Sets up a notifier to signal the client when a dismount has been requested. |
3489 This API allows interested parties to: |
3485 EFsDismountNotifyClients - Notifies all clients (who registered using EFsDismountRegisterClient) of a pending dismount, |
3490 1. Subscribe for notification of file system dismounting events. |
3486 signalling the caller when all clients have responded. |
3491 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. |
3492 See TNotifyDismountMode::EFsDismountRegisterClient |
3488 |
3493 |
3489 This API is intended to be used to allow applications and servers to commit their data to |
3494 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 |
3495 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 |
3496 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. |
3497 If some client does not subscribe for dismounting notification and keeps handles opened, then after the file system dismounting all these |
3493 |
3498 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 |
3499 See TNotifyDismountMode::EFsDismountNotifyClients |
3495 access these resources shall return with the KErrDismounted error code. |
3500 |
3496 |
3501 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 |
3502 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 |
3503 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 |
3504 See TNotifyDismountMode::EFsDismountForceDismount |
3500 */ |
3505 |
3501 EFSRV_EXPORT_C void RFs::NotifyDismount(TInt aDrive, TRequestStatus& aStat, TNotifyDismountMode aMode) const |
3506 * If there are clamped files on the volume, the file system dismounting will not happen until these files are unclamped. |
|
3507 |
|
3508 |
|
3509 The use case scenario: |
|
3510 A 'Master' application that wants to dismount the file system on some drive 'aDrive' |
|
3511 'Client1' and 'Client2' applications interested in file system dismount event notifications, because they need to commit their data before the file system is dismounted. |
|
3512 |
|
3513 1. 'Client1' and 'Client2' subscribe to the FS dismount notification using EFsDismountRegisterClient and start waiting on the request status objects. |
|
3514 2. 'Master' decides to dismount the file system on the drive 'aDrive'. |
|
3515 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. |
|
3516 |
|
3517 3. 'Client1' and 'Client2' have their 'aStat' completed as the result of the 'Master' calling EFsDismountNotifyClients. |
|
3518 3.1 'Client1' and 'Client2' flush data and close file handles. |
|
3519 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() |
|
3520 |
|
3521 4. As soon as _all_ subscribed clients ('Client1' and 'Client2') have called RFs::AllowDismount(), the file system on drive 'aDrive' is |
|
3522 dismounted and 'Master' has 'aStat' completed. |
|
3523 |
|
3524 If, for example, 'Client2' hasn't responded in a reasonable time by calling RFs::AllowDismount(), the 'Master' can cancel the pending 'aStat' and |
|
3525 dismount the file system by force by calling this API with EFsDismountForceDismount. |
|
3526 In this case all subsequent attempts by 'Client2' to use its opened handles will result in KErrDismounted; these handles should be closed. |
|
3527 |
|
3528 |
|
3529 |
|
3530 @param aDriveNo The drive on which to request dismount |
|
3531 @param aMode specifies the behaviour of the notification API |
|
3532 @param aStat Asynchronous request state. |
|
3533 */ |
|
3534 EFSRV_EXPORT_C void RFs::NotifyDismount(TInt aDrive, TRequestStatus& aStat, TNotifyDismountMode aMode /*=EFsDismountRegisterClient*/) const |
3502 { |
3535 { |
3503 TRACE4(UTF::EBorder, UTraceModuleEfsrv::EFsNotifyDismount, MODULEUID, Handle(), aDrive, &aStat, aMode); |
3536 TRACE4(UTF::EBorder, UTraceModuleEfsrv::EFsNotifyDismount, MODULEUID, Handle(), aDrive, &aStat, aMode); |
3504 aStat = KRequestPending; |
3537 aStat = KRequestPending; |
3505 RSessionBase::SendReceive(EFsNotifyDismount, TIpcArgs(aDrive,aMode,&aStat), aStat); |
3538 RSessionBase::SendReceive(EFsNotifyDismount, TIpcArgs(aDrive,aMode,&aStat), aStat); |
3506 // This call is to synchronise with the driver thread as the corresponding cancel function (NotifyDismountCancel) |
3539 // This call is to synchronise with the driver thread as the corresponding cancel function (NotifyDismountCancel) |
3512 } |
3545 } |
3513 |
3546 |
3514 |
3547 |
3515 |
3548 |
3516 |
3549 |
|
3550 /** |
|
3551 Cancels the oustanding dismount notifier, completing with KErrCancel. |
|
3552 |
|
3553 @param aStat The request status object associated with the request to be cancelled. |
|
3554 |
|
3555 @see RFs::NotifyDismount |
|
3556 */ |
3517 EFSRV_EXPORT_C void RFs::NotifyDismountCancel(TRequestStatus& aStat) const |
3557 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 { |
3558 { |
3526 TRACE2(UTF::EBorder, UTraceModuleEfsrv::EFsNotifyDismountCancel1, MODULEUID, Handle(), &aStat); |
3559 TRACE2(UTF::EBorder, UTraceModuleEfsrv::EFsNotifyDismountCancel1, MODULEUID, Handle(), &aStat); |
3527 |
3560 |
3528 if (aStat == KRequestPending) |
3561 if (aStat == KRequestPending) |
3529 SendReceive(EFsNotifyDismountCancel, TIpcArgs(&aStat)); |
3562 SendReceive(EFsNotifyDismountCancel, TIpcArgs(&aStat)); |
3549 } |
3581 } |
3550 |
3582 |
3551 |
3583 |
3552 |
3584 |
3553 |
3585 |
|
3586 /** |
|
3587 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. |
|
3588 |
|
3589 Not calling this does not guarantee that the dismount will not occur as the application requesting the dismount may decide to forcibly dismount |
|
3590 after a given timeout period. |
|
3591 |
|
3592 @param aDriveNo The drive on which to allow the dismount. |
|
3593 |
|
3594 @return KErrNone if successful |
|
3595 |
|
3596 @see RFs::NotifyDismount |
|
3597 */ |
3554 EFSRV_EXPORT_C TInt RFs::AllowDismount(TInt aDrive) const |
3598 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 { |
3599 { |
3570 TRACE2(UTF::EBorder, UTraceModuleEfsrv::EFsAllowDismount, MODULEUID, Handle(), aDrive); |
3600 TRACE2(UTF::EBorder, UTraceModuleEfsrv::EFsAllowDismount, MODULEUID, Handle(), aDrive); |
3571 TInt r = SendReceive(EFsAllowDismount, TIpcArgs(aDrive)); |
3601 TInt r = SendReceive(EFsAllowDismount, TIpcArgs(aDrive)); |
3572 |
3602 |
3573 TRACERET1(UTF::EBorder, UTraceModuleEfsrv::EFsAllowDismountReturn, MODULEUID, r); |
3603 TRACERET1(UTF::EBorder, UTraceModuleEfsrv::EFsAllowDismountReturn, MODULEUID, r); |
3714 r, aParamInfo.iBlockSize, aParamInfo.iClusterSize, aParamInfo.iRecReadBufSize, aParamInfo.iRecWriteBufSize); |
3744 r, aParamInfo.iBlockSize, aParamInfo.iClusterSize, aParamInfo.iRecReadBufSize, aParamInfo.iRecWriteBufSize); |
3715 return r; |
3745 return r; |
3716 } |
3746 } |
3717 |
3747 |
3718 |
3748 |
|
3749 /** |
|
3750 This function queries the sub type of the file system mounted on the specified volume. For example, 'FAT16' of the Fat file system. |
|
3751 TFSName is recommended as the type for aName when using this function. |
|
3752 |
|
3753 NOTE: For the file systems without a sub type (e.g. ROM file system), the the file system name is returned (For example, 'Rom'). |
|
3754 Examples: |
|
3755 "FAT" file system; the subtypes can be "fat12", "fat16" or "fat32" |
|
3756 "ROFS" file system; the subtype will be "ROFS" |
|
3757 |
|
3758 Note also that the file system name, returned in the aName descriptor shall be threated as case-insensitive string. I.e. |
|
3759 "fileSystem" and "FILESYSTEM" mean absolutely the same. Therefore, case-insensitive string methods (like TDesC::FindF(), TDesC::CompareF()) |
|
3760 shall be used to deal with the names. |
|
3761 |
|
3762 |
|
3763 @param aDrive drive number, specifies which volume to query. |
|
3764 @param aName descriptor containing the returned sub type name or file system name. |
|
3765 |
|
3766 @return KErrNone if successful; KErrNotSuppoted if sub type is not supported; |
|
3767 otherwise another system-wide error code is returned. |
|
3768 |
|
3769 @see TFSName |
|
3770 */ |
3719 EFSRV_EXPORT_C TInt RFs::FileSystemSubType(TInt aDrive, TDes& aName) const |
3771 EFSRV_EXPORT_C TInt RFs::FileSystemSubType(TInt aDrive, TDes& aName) const |
3720 /** |
|
3721 This function queries the sub type of the file system mounted on the specified volume. For example, 'FAT16' |
|
3722 of the Fat file system. |
|
3723 |
|
3724 TFSName is recommended as the type for aName when using this function. |
|
3725 |
|
3726 NOTE: File systems without a sub type (For example, a ROM file system), the name of the file system is |
|
3727 returned (For example, 'Rom'). |
|
3728 |
|
3729 @param aDrive A drive number, specifies which volume to query. |
|
3730 @param aName A descriptor containing the returned sub type name or file system name. |
|
3731 |
|
3732 @return KErrNone if successful; KErrNotSuppoted if sub type is not supported; |
|
3733 otherwise another system-wide error code is returned. |
|
3734 |
|
3735 @see TFSName |
|
3736 */ |
|
3737 { |
3772 { |
3738 TRACEMULT3(UTF::EBorder, UTraceModuleEfsrv::EFsFileSystemSubType, MODULEUID, Handle(), aDrive, aName); |
3773 TRACEMULT3(UTF::EBorder, UTraceModuleEfsrv::EFsFileSystemSubType, MODULEUID, Handle(), aDrive, aName); |
3739 |
3774 |
3740 TInt r = KErrNone; |
3775 TInt r = KErrNone; |
3741 |
3776 |