VerFindFileW

関数

インストール先となるファイルの配置場所を判定する。

DLLVERSION.dll文字セットUnicode (-W)呼出規約winapi対応OSWindows 2000 以降

シグネチャ

// VERSION.dll  (Unicode / -W)
#include <windows.h>

VER_FIND_FILE_STATUS VerFindFileW(
    VER_FIND_FILE_FLAGS uFlags,
    LPCWSTR szFileName,
    LPCWSTR szWinDir,   // optional
    LPCWSTR szAppDir,
    LPWSTR szCurDir,
    DWORD* puCurDirLen,
    LPWSTR szDestDir,
    DWORD* puDestDirLen
);

パラメーター

名前型方向説明

uFlags

VER_FIND_FILE_FLAGS

このパラメーターには次の値を指定できます。それ以外のすべてのビットは予約されています。

値	意味
VFFF_ISSHAREDFILE 0x0001	ソースファイルは複数のアプリケーションで共有できます。アプリケーションはこの情報を使用して、ファイルのコピー先を決定できます。

szFileName LPCWSTR in インストールするファイルの名前。パスは含めず、ファイル名と拡張子のみを指定します。

szWinDir LPCWSTR inoptional Windows が実行されている、または実行されるディレクトリ。この文字列は GetWindowsDirectory 関数によって返されます。

szAppDir LPCWSTR in インストールプログラムが一連の関連ファイルをインストールするディレクトリ。インストールプログラムがアプリケーションをインストールする場合、これはそのアプリケーションが配置されるディレクトリです。特に指定がない限り、このパラメーターはアプリケーションのカレントディレクトリも指します。

szCurDir LPWSTR out インストール対象ファイルの現在のバージョンへのパスを受け取るバッファー。パスはゼロで終端された文字列です。現在のバージョンがインストールされていない場合、バッファーには長さ 0 の文字列が格納されます。バッファーは少なくとも _MAX_PATH 文字の長さがあることが望ましいですが、必須ではありません。

puCurDirLen

DWORD*

inout

                <i>szCurDir</i> バッファーの長さ。このポインターは <b>NULL</b> であってはなりません。

関数が返るとき、 lpuCurDirLen には終端の null 文字を含めた、 szCurDir に返されたデータのサイズ(文字数)が格納されます。バッファーがすべてのデータを格納するには小さすぎる場合、 lpuCurDirLen にはパスを保持するために必要なバッファーのサイズが格納されます。

szDestDir LPWSTR out VerFindFile が推奨するインストール先へのパスを受け取るバッファー。パスはゼロで終端された文字列です。バッファーは少なくとも _MAX_PATH 文字の長さがあることが望ましいですが、必須ではありません。

puDestDirLen

DWORD*

inout

                <i>szDestDir</i> バッファーの長さを指定する変数へのポインター。このポインターは <b>NULL</b> であってはなりません。

関数が返るとき、 lpuDestDirLen には終端の null 文字を含めた、 szDestDir に返されたデータのサイズ(文字数)が格納されます。バッファーがすべてのデータを格納するには小さすぎる場合、 lpuDestDirLen にはパスを保持するために必要なバッファーのサイズが格納されます。

戻り値の型: VER_FIND_FILE_STATUS

公式ドキュメント

システム内に別バージョンのファイルが存在するかどうかに基づいて、ファイルのインストール先を決定します。VerFindFile が指定されたバッファーに返す値は、後続の VerInstallFile 関数の呼び出しで使用されます。(Unicode)

戻り値

型: DWORD

戻り値はファイルの状態を示すビットマスクです。次の値の 1 つ以上を取り得ます。それ以外のすべての値は予約されています。

リターンコード/値	説明
VFF_CURNEDEST 0x0001	現在インストールされているバージョンのファイルが、推奨されるインストール先にありません。
VFF_FILEINUSE 0x0002	システムが現在インストールされているバージョンのファイルを使用しているため、そのファイルを上書きまたは削除できません。
VFF_BUFFTOOSMALL 0x0004	対応する文字列を格納するには、少なくとも 1 つのバッファーが小さすぎました。アプリケーションは出力バッファーを確認して、どのバッファーが小さすぎたかを判断する必要があります。

解説(Remarks)

この関数は 16 ビット、32 ビット、64 ビットのファイルイメージで動作します。

VerFindFile は OpenFile 関数を使用して指定されたファイルのコピーを検索します。ただし、システムディレクトリは指定された Windows ディレクトリから判断するか、パスを検索して決定します。

            <i>dwFlags</i> パラメーターがファイルをこのアプリケーション専用(<b>VFFF_ISSHAREDFILE</b> ではない)であることを示している場合、<b>VerFindFile</b> はアプリケーションのディレクトリへのインストールを推奨します。それ以外の場合、システムが共有コピーのシステムを実行しているときは、関数は Windows ディレクトリへのインストールを推奨します。システムが専用コピーのシステムを実行しているときは、関数はシステムディレクトリへのインストールを推奨します。

メモ

winver.h ヘッダーは VerFindFile を、UNICODE プリプロセッサ定数の定義に基づいてこの関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして定義しています。エンコーディング非依存のエイリアスの使用を、エンコーディング非依存でないコードと混在させると、不一致が生じてコンパイルエラーや実行時エラーを引き起こす可能性があります。詳細については、Conventions for Function Prototypes を参照してください。

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

各言語での呼び出し定義

// VERSION.dll  (Unicode / -W)
#include <windows.h>

VER_FIND_FILE_STATUS VerFindFileW(
    VER_FIND_FILE_FLAGS uFlags,
    LPCWSTR szFileName,
    LPCWSTR szWinDir,   // optional
    LPCWSTR szAppDir,
    LPWSTR szCurDir,
    DWORD* puCurDirLen,
    LPWSTR szDestDir,
    DWORD* puDestDirLen
);

[DllImport("VERSION.dll", CharSet = CharSet.Unicode, ExactSpelling = true)]
static extern uint VerFindFileW(
    uint uFlags,   // VER_FIND_FILE_FLAGS
    [MarshalAs(UnmanagedType.LPWStr)] string szFileName,   // LPCWSTR
    [MarshalAs(UnmanagedType.LPWStr)] string szWinDir,   // LPCWSTR optional
    [MarshalAs(UnmanagedType.LPWStr)] string szAppDir,   // LPCWSTR
    [MarshalAs(UnmanagedType.LPWStr)] System.Text.StringBuilder szCurDir,   // LPWSTR out
    ref uint puCurDirLen,   // DWORD* in/out
    [MarshalAs(UnmanagedType.LPWStr)] System.Text.StringBuilder szDestDir,   // LPWSTR out
    ref uint puDestDirLen   // DWORD* in/out
);

<DllImport("VERSION.dll", CharSet:=CharSet.Unicode, ExactSpelling:=True)>
Public Shared Function VerFindFileW(
    uFlags As UInteger,   ' VER_FIND_FILE_FLAGS
    <MarshalAs(UnmanagedType.LPWStr)> szFileName As String,   ' LPCWSTR
    <MarshalAs(UnmanagedType.LPWStr)> szWinDir As String,   ' LPCWSTR optional
    <MarshalAs(UnmanagedType.LPWStr)> szAppDir As String,   ' LPCWSTR
    <MarshalAs(UnmanagedType.LPWStr)> szCurDir As System.Text.StringBuilder,   ' LPWSTR out
    ByRef puCurDirLen As UInteger,   ' DWORD* in/out
    <MarshalAs(UnmanagedType.LPWStr)> szDestDir As System.Text.StringBuilder,   ' LPWSTR out
    ByRef puDestDirLen As UInteger   ' DWORD* in/out
) As UInteger
End Function

' uFlags : VER_FIND_FILE_FLAGS
' szFileName : LPCWSTR
' szWinDir : LPCWSTR optional
' szAppDir : LPCWSTR
' szCurDir : LPWSTR out
' puCurDirLen : DWORD* in/out
' szDestDir : LPWSTR out
' puDestDirLen : DWORD* in/out
Declare PtrSafe Function VerFindFileW Lib "version" ( _
    ByVal uFlags As Long, _
    ByVal szFileName As LongPtr, _
    ByVal szWinDir As LongPtr, _
    ByVal szAppDir As LongPtr, _
    ByVal szCurDir As LongPtr, _
    ByRef puCurDirLen As Long, _
    ByVal szDestDir As LongPtr, _
    ByRef puDestDirLen As Long) As Long
' Unicode(W): 文字列は ByVal As LongPtr とし StrPtr(unicodeStr) を渡す
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

VerFindFileW = ctypes.windll.version.VerFindFileW
VerFindFileW.restype = wintypes.DWORD
VerFindFileW.argtypes = [
    wintypes.DWORD,  # uFlags : VER_FIND_FILE_FLAGS
    wintypes.LPCWSTR,  # szFileName : LPCWSTR
    wintypes.LPCWSTR,  # szWinDir : LPCWSTR optional
    wintypes.LPCWSTR,  # szAppDir : LPCWSTR
    wintypes.LPWSTR,  # szCurDir : LPWSTR out
    ctypes.POINTER(wintypes.DWORD),  # puCurDirLen : DWORD* in/out
    wintypes.LPWSTR,  # szDestDir : LPWSTR out
    ctypes.POINTER(wintypes.DWORD),  # puDestDirLen : DWORD* in/out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('VERSION.dll')
VerFindFileW = Fiddle::Function.new(
  lib['VerFindFileW'],
  [
    -Fiddle::TYPE_INT,  # uFlags : VER_FIND_FILE_FLAGS
    Fiddle::TYPE_VOIDP,  # szFileName : LPCWSTR
    Fiddle::TYPE_VOIDP,  # szWinDir : LPCWSTR optional
    Fiddle::TYPE_VOIDP,  # szAppDir : LPCWSTR
    Fiddle::TYPE_VOIDP,  # szCurDir : LPWSTR out
    Fiddle::TYPE_VOIDP,  # puCurDirLen : DWORD* in/out
    Fiddle::TYPE_VOIDP,  # szDestDir : LPWSTR out
    Fiddle::TYPE_VOIDP,  # puDestDirLen : DWORD* in/out
  ],
  -Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "version")]
extern "system" {
    fn VerFindFileW(
        uFlags: u32,  // VER_FIND_FILE_FLAGS
        szFileName: *const u16,  // LPCWSTR
        szWinDir: *const u16,  // LPCWSTR optional
        szAppDir: *const u16,  // LPCWSTR
        szCurDir: *mut u16,  // LPWSTR out
        puCurDirLen: *mut u32,  // DWORD* in/out
        szDestDir: *mut u16,  // LPWSTR out
        puDestDirLen: *mut u32  // DWORD* in/out
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("VERSION.dll", CharSet = CharSet.Unicode)]
public static extern uint VerFindFileW(uint uFlags, [MarshalAs(UnmanagedType.LPWStr)] string szFileName, [MarshalAs(UnmanagedType.LPWStr)] string szWinDir, [MarshalAs(UnmanagedType.LPWStr)] string szAppDir, [MarshalAs(UnmanagedType.LPWStr)] System.Text.StringBuilder szCurDir, ref uint puCurDirLen, [MarshalAs(UnmanagedType.LPWStr)] System.Text.StringBuilder szDestDir, ref uint puDestDirLen);
"@
$api = Add-Type -MemberDefinition $sig -Name 'VERSION_VerFindFileW' -Namespace Win32 -PassThru
# $api::VerFindFileW(uFlags, szFileName, szWinDir, szAppDir, szCurDir, puCurDirLen, szDestDir, puDestDirLen)

#uselib "VERSION.dll"
#func global VerFindFileW "VerFindFileW" wptr, wptr, wptr, wptr, wptr, wptr, wptr, wptr
; VerFindFileW uFlags, szFileName, szWinDir, szAppDir, varptr(szCurDir), varptr(puCurDirLen), varptr(szDestDir), varptr(puDestDirLen)   ; 戻り値は stat
; uFlags : VER_FIND_FILE_FLAGS -> "wptr"
; szFileName : LPCWSTR -> "wptr"
; szWinDir : LPCWSTR optional -> "wptr"
; szAppDir : LPCWSTR -> "wptr"
; szCurDir : LPWSTR out -> "wptr"
; puCurDirLen : DWORD* in/out -> "wptr"
; szDestDir : LPWSTR out -> "wptr"
; puDestDirLen : DWORD* in/out -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "VERSION.dll"
#cfunc global VerFindFileW "VerFindFileW" int, wstr, wstr, wstr, var, var, var, var
; res = VerFindFileW(uFlags, szFileName, szWinDir, szAppDir, szCurDir, puCurDirLen, szDestDir, puDestDirLen)
; uFlags : VER_FIND_FILE_FLAGS -> "int"
; szFileName : LPCWSTR -> "wstr"
; szWinDir : LPCWSTR optional -> "wstr"
; szAppDir : LPCWSTR -> "wstr"
; szCurDir : LPWSTR out -> "var"
; puCurDirLen : DWORD* in/out -> "var"
; szDestDir : LPWSTR out -> "var"
; puDestDirLen : DWORD* in/out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "VERSION.dll"
#cfunc global VerFindFileW "VerFindFileW" int, wstr, wstr, wstr, sptr, sptr, sptr, sptr
; res = VerFindFileW(uFlags, szFileName, szWinDir, szAppDir, varptr(szCurDir), varptr(puCurDirLen), varptr(szDestDir), varptr(puDestDirLen))
; uFlags : VER_FIND_FILE_FLAGS -> "int"
; szFileName : LPCWSTR -> "wstr"
; szWinDir : LPCWSTR optional -> "wstr"
; szAppDir : LPCWSTR -> "wstr"
; szCurDir : LPWSTR out -> "sptr"
; puCurDirLen : DWORD* in/out -> "sptr"
; szDestDir : LPWSTR out -> "sptr"
; puDestDirLen : DWORD* in/out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。