Функция ResUtilFindDependentDiskResourceDriveLetter (resapi.h)

Статья
08/25/2023

Извлекает букву диска, связанную с зависимостью физического диска ресурса. Тип 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 в качестве количества WCHARs. В выходных данных указывает размер результирующих данных в виде количества WCHARs, включая завершающее значение NULL.

Возвращаемое значение

Если операции выполняются успешно, функция возвращает ERROR_SUCCESS (0).

Если операция завершается сбоем, функция возвращает код системной ошибки. Ниже приведены возможные коды ошибок.

Код возврата	Описание
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 Корпоративная, Windows Server 2008 Datacenter
Целевая платформа	Windows
Header	resapi.h
Библиотека	ResUtils.lib
DLL	ResUtils.dll