Función ResUtilFindDependentDiskResourceDriveLetter (resapi.h)

Artículo
08/25/2023

Recupera la letra de unidad asociada a una dependencia de disco físico de un recurso. El tipo PRESUTIL_FIND_DEPENDENT_DISK_RESOURCE_DRIVE_LETTER define un puntero a esta función.

Sintaxis

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

Parámetros

[in] hCluster

Identificador del clúster.

[in] hResource

Controle el recurso para consultar las dependencias.

[out] pszDriveLetter

Búfer en el que se va a almacenar la letra de unidad.

[in, out] pcchDriveLetter

En la entrada, especifica el tamaño del búfer pszDriveLetter como recuento de WCHARs. En la salida, especifica el tamaño de los datos resultantes como un recuento de WCHARs que incluye el valor NULL de terminación.

Valor devuelto

Si las operaciones se realizan correctamente, la función devuelve ERROR_SUCCESS (0).

Si se produce un error en la operación, la función devuelve un código de error del sistema. A continuación se muestran códigos de error posibles.

Código devuelto	Descripción
ERROR_NO_MORE_ITEMS	No se encontró ninguna dependencia de disco físico en la lista de dependencias del recurso especificado.
ERROR_RESOURCE_NOT_PRESENT	No se pudo devolver ninguna letra de unidad.
ERROR_MORE_DATA	El búfer pasado era demasiado pequeño. El parámetro pcchDriveLetter especifica el tamaño necesario.

Comentarios

No llame a esta función desde un archivo DLL de recursos. Provocará un interbloqueo. Debe hacer que la extensión de recursos llame a esta función y escriba los resultados como una propiedad privada que el archivo DLL de recursos puede leer.

Si el recurso identificado por hResource depende de más de un recurso de disco físico, ResUtilFindDependentDiskResourceDriveLetter devuelve la letra de unidad de la primera dependencia de disco físico que se enumera para el recurso.

Ejemplos

En el ejemplo siguiente se toma un nombre de recurso como argumento de línea de comandos y se muestra la letra de unidad asociada a la dependencia de disco físico del recurso (si existe). En este ejemplo se usa el archivo de encabezado ClusDocEx.h definido en la documentación del clúster de conmutación por error.

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

#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;
 }

Si el recurso identificado por hResource hace referencia a un disco de punto de montaje, puede haber o no una letra de unidad asociada al recurso de disco. Si el disco del punto de montaje no tiene ninguna letra de unidad asociada, el valor devuelto por ResUtilFindDependentDiskResourceDriveLetter tendrá el formato DiskXPartitionY, que es datos válidos, pero no se puede pasar directamente a las API del sistema de archivos como CreateFile.

En el ejemplo siguiente se toma la cadena de salida de ResUtilFindDependentDiskResourceDriveLetter y se transforma en formato Win32. La cadena de salida de esta función se puede pasar a CreateFile. Si se produce un error en la función, el valor devuelto es NULL; llame a GetLastError para obtener información de error extendida. Si la función se realiza correctamente, el usuario tiene que liberar el búfer devuelto mediante 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;
 }

Requisitos

Requisito	Value
Cliente mínimo compatible	No se admite ninguno
Servidor mínimo compatible	Windows Server 2008 Enterprise, Windows Server 2008 Datacenter
Plataforma de destino	Windows
Encabezado	resapi.h
Library	ResUtils.lib
Archivo DLL	ResUtils.dll