INFO: Use the GetDiskFreeSpaceEx() Function Instead of the GetStorageInformation() Function (300082)

MORE INFORMATION

Because memory is frequently scarce on a Microsoft Windows CE-based device, you have to know how to determine the memory that is available. The Windows CE OS provides two functions to help you (developers) do this effectively:

• The GetDiskFreeSpaceEx function.
• The GetStoreInformation function.

Use GetDiskFreeSpaceEx instead of GetStoreInformation for the following reasons:

• GetDiskFreeSpaceEx was added in Windows CE 2.0 as a replacement for GetStoreInformation.
• GetDiskFreeSpaceEx is more versatile because it can return storage information for any location.
• GetDiskFreeSpaceEx duplicates the functionality of GetStoreInformation. When you want to obtain the size of the information store, and if you want to duplicate the functionality of GetStoreInformation, use GetDiskFreeSpaceEx with a NULL path.
• GetDiskFreeSpaceEx is preferred because newer devices may be larger than GetStoreInformation can report.
  
  For example, although GetStoreInformation can return a maximum information store size of a single DWORD byte, GetDiskFreeSpaceEx can return structures that contain two DWORD bytes. GetStoreInformation can return only the size of the information store. The GetStoreInformation function cannot return the size of any other storage areas (such as hard drives and flash media).
• GetDiskFreeSpaceEx returns the size of the device that is at the path that you specify in a parameter of this function.

The Interfaces

Both of these functions are implemented in the code library file, Coredll.lib, and their interfaces are as follows:

The GetDiskFreeSpaceEx Function

• GetDiskFreeSpaceEx can retrieve information about the object store or about other storage locations.
• TheGetDiskFreeSpaceEx function is defined as follows:

   BOOL GetDiskFreeSpaceEx( LPCWSTR lpDirectoryName, 
  			PULARGE_INTEGER lpFreeBytesAvailableToCaller, 
  			PULARGE_INTEGER lpTotalNumberOfBytes, 
  			PULARGE_INTEGER lpTotalNumberOfFreeBytes );

• lpDirectoryName is the name of the directory or of the Universal Naming Convention (UNC) path where you want to retrieve the storage information. If lpDirectoryName is NULL, the call returns the information for the object store.
• The other three parameters are out parameters, and they return the following information:
  • lpFreeBytesAvailableToCaller: Returns the number of bytes that are available to the calling function.
  • lpTotalNumberOfBytes: Returns the size of the storage device.
  • TotalNumberOfFreeBytes: Returns the number of free bytes.
• These parameters are pointers to the structure type ULARGE_INTEGER that contains two DWORD fields, LowPart and HighPart. This structure permits GetDiskFreeSpaceEx to return values for much larger storage devices.
• A non-ZERO return code indicates success. A ZERO return code indicates failure.

The GetStoreInformation Function

• GetStoreInformation can retrieve information about the object store
• TheGetStoreInformation function is defined as follows:

  BOOL GetStoreInformation(LPSTORE_INFORMATION lpsi ); 

• GetStoreInformation takes a pointer to a STORE_INFORMATION structure.
• The STORE_INFORMATION structure contains two DWORD members:
  • dwStoreSize: Returns the total size in bytes of the object store.
  • dwFreeSize: Returns the current free space in bytes in the object store.
• A TRUE return code indicates success. A FALSE return code indicates failure.