ホーム › Networking.Clustering › ResUtilFindDependentDiskResourceDriveLetter

ResUtilFindDependentDiskResourceDriveLetter

関数

依存先ディスクリソースのドライブ文字を取得する。

DLLRESUTILS.dll呼出規約winapiSetLastErrorあり対応OSwindowsserver2008

シグネチャ

// RESUTILS.dll
#include <windows.h>

DWORD ResUtilFindDependentDiskResourceDriveLetter(
    HCLUSTER hCluster,
    HRESOURCE hResource,
    LPWSTR pszDriveLetter,
    DWORD* pcchDriveLetter
);

パラメーター

名前	型	方向	説明
hCluster	HCLUSTER	in	クラスターのハンドル。
hResource	HRESOURCE	in	依存関係を照会するリソースのハンドル。
pszDriveLetter	LPWSTR	out	ドライブ文字を格納するバッファー。
pcchDriveLetter	DWORD*	inout	入力時には、pszDriveLetter バッファーのサイズを WCHAR 単位の個数で指定します。出力時には、終端の NULL を含む結果データのサイズが WCHAR 単位の個数で格納されます。

戻り値の型: DWORD

公式ドキュメント

リソースの Physical Disk 依存関係に関連付けられているドライブ文字を取得します。PRESUTIL_FIND_DEPENDENT_DISK_RESOURCE_DRIVE_LETTER 型は、この関数へのポインターを定義します。

戻り値

操作が成功した場合、この関数は ERROR_SUCCESS (0) を返します。

操作が失敗した場合、この関数はシステムエラーコードを返します。次のエラーコードが返される可能性があります。

戻り値	説明
ERROR_NO_MORE_ITEMS	指定されたリソースの依存関係の一覧に Physical Disk の依存関係が見つかりませんでした。
ERROR_RESOURCE_NOT_PRESENT	ドライブ文字を返すことができませんでした。
ERROR_MORE_DATA	渡されたバッファーが小さすぎます。pcchDriveLetter パラメーターに必要なサイズが格納されます。

解説(Remarks)

この関数をリソース DLL から呼び出さないでください。デッドロックの原因となります。リソース拡張からこの関数を呼び出し、その結果をプライベートプロパティとして書き出し、リソース DLL がそれを読み取れるようにしてください。

hResource で識別されるリソースが複数の Physical Disk リソースに依存している場合、 ResUtilFindDependentDiskResourceDriveLetter は、そのリソースに対して最初に列挙された Physical Disk 依存関係のドライブ文字を返します。

例

次の例では、リソース名をコマンドライン引数として受け取り、そのリソースの Physical Disk 依存関係に関連付けられたドライブ文字がある場合にそれを表示します。この例では、フェールオーバークラスターのドキュメントで定義されている 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 という形式になります。これは有効なデータですが、CreateFile などのファイルシステム API に直接渡すことはできません。

次の例では、 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;
 }

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// RESUTILS.dll
#include <windows.h>

DWORD ResUtilFindDependentDiskResourceDriveLetter(
    HCLUSTER hCluster,
    HRESOURCE hResource,
    LPWSTR pszDriveLetter,
    DWORD* pcchDriveLetter
);

[DllImport("RESUTILS.dll", SetLastError = true, ExactSpelling = true)]
static extern uint ResUtilFindDependentDiskResourceDriveLetter(
    IntPtr hCluster,   // HCLUSTER
    IntPtr hResource,   // HRESOURCE
    [MarshalAs(UnmanagedType.LPWStr)] System.Text.StringBuilder pszDriveLetter,   // LPWSTR out
    ref uint pcchDriveLetter   // DWORD* in/out
);

<DllImport("RESUTILS.dll", SetLastError:=True, ExactSpelling:=True)>
Public Shared Function ResUtilFindDependentDiskResourceDriveLetter(
    hCluster As IntPtr,   ' HCLUSTER
    hResource As IntPtr,   ' HRESOURCE
    <MarshalAs(UnmanagedType.LPWStr)> pszDriveLetter As System.Text.StringBuilder,   ' LPWSTR out
    ByRef pcchDriveLetter As UInteger   ' DWORD* in/out
) As UInteger
End Function

' hCluster : HCLUSTER
' hResource : HRESOURCE
' pszDriveLetter : LPWSTR out
' pcchDriveLetter : DWORD* in/out
Declare PtrSafe Function ResUtilFindDependentDiskResourceDriveLetter Lib "resutils" ( _
    ByVal hCluster As LongPtr, _
    ByVal hResource As LongPtr, _
    ByVal pszDriveLetter As LongPtr, _
    ByRef pcchDriveLetter As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

ResUtilFindDependentDiskResourceDriveLetter = ctypes.windll.resutils.ResUtilFindDependentDiskResourceDriveLetter
ResUtilFindDependentDiskResourceDriveLetter.restype = wintypes.DWORD
ResUtilFindDependentDiskResourceDriveLetter.argtypes = [
    ctypes.c_ssize_t,  # hCluster : HCLUSTER
    ctypes.c_ssize_t,  # hResource : HRESOURCE
    wintypes.LPWSTR,  # pszDriveLetter : LPWSTR out
    ctypes.POINTER(wintypes.DWORD),  # pcchDriveLetter : DWORD* in/out
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('RESUTILS.dll')
ResUtilFindDependentDiskResourceDriveLetter = Fiddle::Function.new(
  lib['ResUtilFindDependentDiskResourceDriveLetter'],
  [
    Fiddle::TYPE_INTPTR_T,  # hCluster : HCLUSTER
    Fiddle::TYPE_INTPTR_T,  # hResource : HRESOURCE
    Fiddle::TYPE_VOIDP,  # pszDriveLetter : LPWSTR out
    Fiddle::TYPE_VOIDP,  # pcchDriveLetter : DWORD* in/out
  ],
  -Fiddle::TYPE_INT)

#[link(name = "resutils")]
extern "system" {
    fn ResUtilFindDependentDiskResourceDriveLetter(
        hCluster: isize,  // HCLUSTER
        hResource: isize,  // HRESOURCE
        pszDriveLetter: *mut u16,  // LPWSTR out
        pcchDriveLetter: *mut u32  // DWORD* in/out
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("RESUTILS.dll", SetLastError = true)]
public static extern uint ResUtilFindDependentDiskResourceDriveLetter(IntPtr hCluster, IntPtr hResource, [MarshalAs(UnmanagedType.LPWStr)] System.Text.StringBuilder pszDriveLetter, ref uint pcchDriveLetter);
"@
$api = Add-Type -MemberDefinition $sig -Name 'RESUTILS_ResUtilFindDependentDiskResourceDriveLetter' -Namespace Win32 -PassThru
# $api::ResUtilFindDependentDiskResourceDriveLetter(hCluster, hResource, pszDriveLetter, pcchDriveLetter)

#uselib "RESUTILS.dll"
#func global ResUtilFindDependentDiskResourceDriveLetter "ResUtilFindDependentDiskResourceDriveLetter" sptr, sptr, sptr, sptr
; ResUtilFindDependentDiskResourceDriveLetter hCluster, hResource, varptr(pszDriveLetter), varptr(pcchDriveLetter)   ; 戻り値は stat
; hCluster : HCLUSTER -> "sptr"
; hResource : HRESOURCE -> "sptr"
; pszDriveLetter : LPWSTR out -> "sptr"
; pcchDriveLetter : DWORD* in/out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "RESUTILS.dll"
#cfunc global ResUtilFindDependentDiskResourceDriveLetter "ResUtilFindDependentDiskResourceDriveLetter" sptr, sptr, var, var
; res = ResUtilFindDependentDiskResourceDriveLetter(hCluster, hResource, pszDriveLetter, pcchDriveLetter)
; hCluster : HCLUSTER -> "sptr"
; hResource : HRESOURCE -> "sptr"
; pszDriveLetter : LPWSTR out -> "var"
; pcchDriveLetter : DWORD* in/out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "RESUTILS.dll"
#cfunc global ResUtilFindDependentDiskResourceDriveLetter "ResUtilFindDependentDiskResourceDriveLetter" sptr, sptr, sptr, sptr
; res = ResUtilFindDependentDiskResourceDriveLetter(hCluster, hResource, varptr(pszDriveLetter), varptr(pcchDriveLetter))
; hCluster : HCLUSTER -> "sptr"
; hResource : HRESOURCE -> "sptr"
; pszDriveLetter : LPWSTR out -> "sptr"
; pcchDriveLetter : DWORD* in/out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。