ResUtilFindDependentDiskResourceDriveLetter 函式 (resapi.h)

發行項
03/01/2024

擷取與資源實體磁碟相依性相關聯的驅動器號。 PRESUTIL_FIND_DEPENDENT_DISK_RESOURCE_DRIVE_LETTER類型會定義此函式的指標。

語法

DWORD ResUtilFindDependentDiskResourceDriveLetter(
  [in]      HCLUSTER  hCluster,
  [in]      HRESOURCE hResource,
  [out]     LPWSTR    pszDriveLetter,
  [in, out] DWORD     *pcchDriveLetter
);

參數

[in] hCluster

叢集句柄。

[in] hResource

要查詢相依性的資源句柄。

[out] pszDriveLetter

用來儲存驅動器號的緩衝區。

[in, out] pcchDriveLetter

在輸入上，將 pszDriveLetter 緩衝區的大小指定為 WCHAR 的計數。在輸出上，將產生的數據大小指定為包含終止 NULL 的 WCHAR 計數。

傳回值

如果作業成功，函式會傳回 ERROR_SUCCESS ( 0) 。

如果作業失敗，函式會傳回系統錯誤碼。以下是可能的錯誤碼。

傳回碼	Description
ERROR_NO_MORE_ITEMS	在指定的資源相依性清單中找不到實體磁碟相依性。
ERROR_RESOURCE_NOT_PRESENT	無法傳回驅動器號。
ERROR_MORE_DATA	傳入的緩衝區太小。 pcchDriveLetter 參數會指定所需的大小。

備註

請勿從資源 DLL 呼叫此函式。這會導致死結。您應該讓資源延伸模組呼叫此函式，並將結果寫入為資源 DLL 接著可讀取的私人屬性。

如果 hResource 所識別的資源相依於多個實體磁碟資源， ResUtilFindDependentDiskResourceDriveLetter 會傳回資源所列舉之第一個實體磁碟相依性的驅動器號。

範例

下列範例會採用資源名稱作為命令行自變數，並在有任何) 時顯示與資源實體磁碟相依性相關聯的驅動器號 (。此範例使用故障轉移叢集檔中定義的 ClusDocEx.h 頭檔。

//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

int main( int argc, char argv[] )
 {
  HCLUSTER  hCluster     = NULL;
  HRESOURCE hRes         = NULL;
  DWORD     dw;
  DWORD     cchResDrive  = ClusDocEx_DEFAULT_CCH;
  DWORD     cchResName   = ClusDocEx_DEFAULT_CCH;
  WCHAR     *pszResDrive = new WCHAR[cchResDrive];
  WCHAR     *pszResName  = new WCHAR[cchResName];

  dw = ClusDocEx_ConvertArg( argv[1], pszResName, cchResName );

  if( dw == ERROR_SUCCESS )
   {
    hCluster = ClusDocEx_OpenLocalClusterWithName();
    if( hCluster != NULL )
     {
      hRes = OpenClusterResource( hCluster, pszResName );
      if( hRes != NULL )
       {
        dw = ResUtilFindDependentDiskResourceDriveLetter( hCluster,
                                                          hRes,
                                                          pszResDrive,
                                                          &cchResDrive );

        if( dw == ERROR_MORE_DATA )
         {
          delete [] pszResDrive;
          pszResDrive = new WCHAR[cchResDrive];
          dw = ResUtilFindDependentDiskResourceDriveLetter( hCluster,
                                                            hRes,
                                                            pszResDrive,
                                                            &cchResDrive );
         }

        switch( dw )
         {
          case ERROR_SUCCESS:    
            wprintf( L"%ls depends on drive %ls.\n", pszResName, pszResDrive );
            break;

          case ERROR_NO_MORE_ITEMS:
          case ERROR_RESOURCE_NOT_PRESENT:
            wprintf( L"No Physical Disk dependency found for %ls.\n", pszResName );
            break;

          default:    
            ClusDocEx_DebugPrint( L"Could not obtain drive information", dw );
            break;
         }
        CloseClusterResource( hRes );
       }
      else // if hRes == NULL
       {
        ClusDocEx_DebugPrint( L"Could not open a resource handle", GetLastError() );
       }
      CloseCluster( hCluster );
     }
    else // if hCluster == NULL
     {
      ClusDocEx_DebugPrint( L"Could not open a cluster handle", GetLastError() );
     }

   }
  delete [] pszResName;
  delete [] pszResDrive;
  return 0;
 }

如果 hResource 識別的資源是指裝入點磁碟，則可能沒有與磁碟資源相關聯的驅動器號。如果裝入點磁碟沒有相關聯的驅動器號， ResUtilFindDependentDiskResourceDriveLetter 所傳回的值會採用 DiskXPartitionY 的格式，這是有效的數據，但無法直接傳遞至文件系統 API，例如 CreateFile。

下列範例會採用 ResUtilFindDependentDiskResourceDriveLetter 的輸出字串，並將其轉換成 Win32 格式。此函式的輸出字串可以傳遞至 CreateFile。如果函式失敗，則傳回值為 NULL;呼叫 GetLastError 以取得擴充的錯誤資訊。如果函式成功，用戶必須釋放使用 LocalFree 傳回的緩衝區。

#define UNICODE 1
#define _UNICODE 1
#pragma comment(lib, "ResUtils.lib")

#include <windows.h>
#include <stdlib.h>
#include <ResApi.h>
#include <strsafe.h>

#define IS_DRIVELETTER(x) ((iswalpha((x)[0])) && ((x)[1] == L':'))
#define IS_NTPATH(x) ((wcsstr((x), L"Disk") != NULL) && (wcsstr((x), L"Partition") != NULL)) 
#define GLOBALROOT_DISK_FORMAT L"\\\\\?\\GLOBALROOT\\Device\\Harddisk%u\\Partition%u"

LPWSTR ConvertNtDiskPathToW32DiskPath( LPCWSTR InputString )
 {
  LPWSTR outputString=NULL;
  DWORD status=ERROR_INVALID_PARAMETER;
  DWORD len;
  DWORD diskNum, partNum;

  if ((InputString == NULL) || (InputString[0] == 0))
   {
    goto Error_exit;
   }

  // Find out the required buffer size.
  len = 0;
  if (IS_DRIVELETTER(InputString))
   {
    len = wcslen(InputString) + 4;
   }
  else if (IS_NTPATH(InputString))
   {
    len = wcslen(GLOBALROOT_DISK_FORMAT) + 16;
   }
  else
   {
    //Malformed string.
    goto Error_exit;
   } 

  if ((outputString = (LPWSTR)LocalAlloc(LPTR, len * sizeof(WCHAR))) == NULL)
   {
    status = GetLastError();
    goto Error_exit;
   }

  if (IS_DRIVELETTER(InputString))
   {
    StringCchCopyW(outputString, len, InputString);
   }
  else
   {
    //Has to be NT path format.
    swscanf_s(InputString, L"Disk%uPartition%u", &diskNum, &partNum);
    StringCchPrintfW(outputString, len, GLOBALROOT_DISK_FORMAT, diskNum, partNum);
   }
    
  status = ERROR_SUCCESS;
    
Error_exit: 

  if (status != ERROR_SUCCESS)
   {
    if (outputString)
     {
      LocalFree(outputString);
     }
    SetLastError(status);
    return NULL;
   }

  return outputString;
 }

規格需求

需求	值
最低支援的用戶端	都不支援
最低支援的伺服器	Windows Server 2008 Enterprise、Windows Server 2008 Datacenter
目標平台	Windows
標頭	resapi.h
程式庫	ResUtils.lib
Dll	ResUtils.dll