Fonction ResUtilFindDependentDiskResourceDriveLetter (resapi.h)

Article
08/25/2023

Récupère la lettre de lecteur associée à une dépendance de disque physique d’une ressource. Le type PRESUTIL_FIND_DEPENDENT_DISK_RESOURCE_DRIVE_LETTER définit un pointeur vers cette fonction.

Syntaxe

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

Paramètres

[in] hCluster

Handle de cluster.

[in] hResource

Gérez la ressource pour interroger les dépendances.

[out] pszDriveLetter

Mémoire tampon dans laquelle stocker la lettre de lecteur.

[in, out] pcchDriveLetter

Lors de l’entrée, spécifie la taille de la mémoire tampon pszDriveLetter en tant que nombre de WCHAR. Lors de la sortie, spécifie la taille des données résultantes sous la forme d’un nombre de WCHARqui inclut la valeur NULL de fin.

Valeur retournée

Si les opérations réussissent, la fonction retourne ERROR_SUCCESS (0).

Si l’opération échoue, la fonction retourne un code d’erreur système. Voici les codes d’erreur possibles.

Code de retour	Description
ERROR_NO_MORE_ITEMS	Aucune dépendance de disque physique n’a été trouvée dans la liste des dépendances de la ressource spécifiée.
ERROR_RESOURCE_NOT_PRESENT	Aucune lettre de lecteur n’a pu être retournée.
ERROR_MORE_DATA	La mémoire tampon passée était trop petite. Le paramètre pcchDriveLetter spécifie la taille requise.

Remarques

N’appelez pas cette fonction à partir d’une DLL de ressource. Cela provoquera un interblocage. Votre extension de ressource doit appeler cette fonction et écrire les résultats en tant que propriété privée que votre DLL de ressource peut ensuite lire.

Si la ressource identifiée par hResource dépend de plusieurs ressources de disque physique, ResUtilFindDependentDiskResourceDriveLetter retourne la lettre de lecteur de la première dépendance de disque physique énumérée pour la ressource.

Exemples

L’exemple suivant prend un nom de ressource comme argument de ligne de commande et affiche la lettre de lecteur associée à la dépendance de disque physique de la ressource (le cas échéant). Cet exemple utilise le fichier d’en-tête ClusDocEx.h défini dans la documentation du cluster de basculement.

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

#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 la ressource identifiée par hResource fait référence à un disque de point de montage, il peut y avoir ou non une lettre de lecteur associée à la ressource de disque. Si le disque de point de montage n’a pas de lettre de lecteur associée, la valeur retournée par ResUtilFindDependentDiskResourceDriveLetter est au format DiskXPartitionY, qui est des données valides, mais ne peut pas être transmise directement aux API de système de fichiers telles que CreateFile.

L’exemple suivant prend la chaîne de sortie de ResUtilFindDependentDiskResourceDriveLetter et la transforme au format Win32. La chaîne de sortie de cette fonction peut être passée à CreateFile. Si la fonction échoue, la valeur de retour est NULL ; appelez GetLastError pour obtenir des informations d’erreur étendues. Si la fonction réussit, l’utilisateur doit libérer la mémoire tampon retournée à l’aide de 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;
 }

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Aucun pris en charge
Serveur minimal pris en charge	Windows Server 2008 Entreprise, Windows Server 2008 Datacenter
Plateforme cible	Windows
En-tête	resapi.h
Bibliothèque	ResUtils.lib
DLL	ResUtils.dll