ホーム › Storage.FileSystem › VerInstallFileW

VerInstallFileW

関数

バージョンを確認しながらファイルをインストールする。

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

シグネチャ

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

VER_INSTALL_FILE_STATUS VerInstallFileW(
    VER_INSTALL_FILE_FLAGS uFlags,
    LPCWSTR szSrcFileName,
    LPCWSTR szDestFileName,
    LPCWSTR szSrcDir,
    LPCWSTR szDestDir,
    LPCWSTR szCurDir,
    LPWSTR szTmpFile,
    DWORD* puTmpFileLen
);

パラメーター

名前型方向説明

uFlags

VER_INSTALL_FILE_FLAGS

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

値	意味
VIFF_FORCEINSTALL 0x0001	バージョン番号の不一致に関係なくファイルをインストールします。この関数は、インストール中の物理的なエラーのみをチェックします。
VIFF_DONTDELETEOLD 0x0002	以前にインストールされたファイルがインストール先ディレクトリにない場合、そのファイルを削除せずにファイルをインストールします。

szSrcFileName LPCWSTR in インストールするファイルの名前です。これは szSrcDir パラメーターが指すディレクトリ内のファイル名です。ファイル名にはファイル名と拡張子のみを含めることができ、パスは含められません。

szDestFileName LPCWSTR in インストール時に VerInstallFile が新しいファイルに付ける名前です。このファイル名は、 szSrcFileName ディレクトリ内のファイル名と異なっていてもかまいません。新しい名前にはファイル名と拡張子のみを含め、パスは含めないでください。

szSrcDir LPCWSTR in ファイルが存在するディレクトリの名前です。

szDestDir LPCWSTR in ファイルをインストールするディレクトリの名前です。VerFindFile がこの値を szDestDir パラメーターで返します。

szCurDir LPCWSTR in このファイルの既存バージョンが存在するディレクトリの名前です。VerFindFile がこの値を szCurDir パラメーターで返します。

szTmpFile LPWSTR out ソースファイルの一時コピーの名前です。バッファーの長さは少なくとも _MAX_PATH 文字にすることが推奨されますが、必須ではありません。入力時には空である必要があります。

puTmpFileLen

DWORD*

inout

                <i>szTmpFile</i> バッファーの長さです。このポインターを <b>NULL</b> にすることはできません。

関数が返ると、 lpuTmpFileLen は szTmpFile に返されたデータのサイズ(終端の null 文字を含む、文字数単位)を受け取ります。バッファーがすべてのデータを格納するには小さすぎる場合、 lpuTmpFileLen はデータを格納するために必要なバッファーのサイズになります。

戻り値の型: VER_INSTALL_FILE_STATUS

公式ドキュメント

VerFindFile 関数から返された情報に基づいて、指定したファイルをインストールします。VerInstallFile は、必要に応じてファイルを展開し、一意のファイル名を割り当て、古いファイルなどのエラーをチェックします。(Unicode)

戻り値

Type: DWORD

戻り値は、例外を示すビットマスクです。次の値の1つ以上になります。その他のすべての値は予約されています。

リターンコード/値	説明
VIF_ACCESSVIOLATION 0x00000200L	アクセス違反のため、読み取り、作成、削除、または名前変更操作が失敗しました。
VIF_BUFFTOOSMALL 0x00040000L	szTmpFile バッファーが一時ソースファイルの名前を格納するには小さすぎました。関数が返ると、lpuTmpFileLen にファイル名を格納するために必要なバッファーのサイズが格納されます。
VIF_CANNOTCREATE 0x00000800L	関数は一時ファイルを作成できません。具体的なエラーは別のフラグで示される場合があります。
VIF_CANNOTDELETE 0x00001000L	関数はインストール先ファイルを削除できないか、別のディレクトリにあるファイルの既存バージョンを削除できません。VIF_TEMPFILE ビットが設定されている場合、インストールは失敗しており、インストール先ファイルはおそらく削除できません。
VIF_CANNOTDELETECUR 0x00004000L	ファイルの既存バージョンを削除できず、かつ VIFF_DONTDELETEOLD が指定されていませんでした。
VIF_CANNOTLOADCABINET 0x00100000L	関数はキャビネットファイルを読み込めません。
VIF_CANNOTLOADLZ32 0x00080000L	関数は圧縮ファイルを読み込めません。
VIF_CANNOTREADDST 0x00020000L	関数はインストール先(既存)ファイルを読み取れません。このため、関数はファイルの属性を調べることができません。
VIF_CANNOTREADSRC 0x00010000L	関数はソースファイルを読み取れません。これは、パスが正しく指定されていなかったことを意味する場合があります。
VIF_CANNOTRENAME 0x00002000L	関数は一時ファイルの名前を変更できませんが、インストール先ファイルは既に削除されています。
VIF_DIFFCODEPG 0x00000010L	新しいファイルには、現在実行中のシステムのバージョンでは表示できないコードページが必要です。このエラーは、VIFF_FORCEINSTALL フラグを設定して VerInstallFile を呼び出すことで上書きできます。
VIF_DIFFLANG 0x00000008L	新しいファイルと既存のファイルで言語またはコードページの値が異なります。このエラーは、VIFF_FORCEINSTALL フラグを設定して VerInstallFile を再度呼び出すことで上書きできます。
VIF_DIFFTYPE 0x00000020L	新しいファイルは、既存のファイルとは異なる種類、サブタイプ、またはオペレーティングシステムを持っています。このエラーは、VIFF_FORCEINSTALL フラグを設定して VerInstallFile を再度呼び出すことで上書きできます。
VIF_FILEINUSE 0x00000080L	既存のファイルはシステムによって使用中であり、削除できません。
VIF_MISMATCH 0x00000002L	新しいファイルと既存のファイルが1つ以上の属性で異なります。このエラーは、VIFF_FORCEINSTALL フラグを設定して VerInstallFile を再度呼び出すことで上書きできます。
VIF_OUTOFMEMORY 0x00008000L	メモリ不足のため、関数は要求された操作を完了できません。一般的に、これはアプリケーションが圧縮ファイルを展開しようとしてメモリを使い果たしたことを意味します。
VIF_OUTOFSPACE 0x00000100L	インストール先ドライブのディスク容量が不足しているため、関数は一時ファイルを作成できません。
VIF_SHARINGVIOLATION 0x00000400L	共有違反のため、読み取り、作成、削除、または名前変更操作が失敗しました。
VIF_SRCOLD 0x00000004L	インストールするファイルが既存のファイルよりも古いです。このエラーは、VIFF_FORCEINSTALL フラグを設定して VerInstallFile を再度呼び出すことで上書きできます。
VIF_TEMPFILE 0x00000001L	新しいファイルの一時コピーがインストール先ディレクトリにあります。失敗の原因は他のフラグに反映されます。
VIF_WRITEPROT 0x00000040L	既存のファイルは書き込み禁止です。このエラーは、VIFF_FORCEINSTALL フラグを設定して VerInstallFile を再度呼び出すことで上書きできます。

解説(Remarks)

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

VerInstallFile は、ソースディレクトリからインストール先ディレクトリにファイルをコピーします。 szCurDir がシステム上にファイルの以前のバージョンが存在することを示している場合、VerInstallFile はファイルのバージョンスタンプ情報を比較します。以前にインストールされたバージョンのファイルが新しいバージョンよりも新しい場合、またはファイルの属性が大きく異なる場合(たとえば言語が異なる場合)、VerInstallFile は1つ以上の回復可能なエラーコードを返します。

VerInstallFile は一時ファイルをインストール先ディレクトリに残します。アプリケーションは、エラーを上書きするか、一時ファイルを削除できます。アプリケーションがエラーを上書きすると、VerInstallFile は以前にインストールされたバージョンを削除し、一時ファイルの名前を元のファイル名に変更します。

メモ

winver.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして VerInstallFile を定義しています。エンコーディング中立のエイリアスの使用と、エンコーディング中立でないコードを混在させると、不一致が生じ、コンパイルエラーや実行時エラーを引き起こす可能性があります。詳細については、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_INSTALL_FILE_STATUS VerInstallFileW(
    VER_INSTALL_FILE_FLAGS uFlags,
    LPCWSTR szSrcFileName,
    LPCWSTR szDestFileName,
    LPCWSTR szSrcDir,
    LPCWSTR szDestDir,
    LPCWSTR szCurDir,
    LPWSTR szTmpFile,
    DWORD* puTmpFileLen
);

[DllImport("VERSION.dll", CharSet = CharSet.Unicode, ExactSpelling = true)]
static extern uint VerInstallFileW(
    uint uFlags,   // VER_INSTALL_FILE_FLAGS
    [MarshalAs(UnmanagedType.LPWStr)] string szSrcFileName,   // LPCWSTR
    [MarshalAs(UnmanagedType.LPWStr)] string szDestFileName,   // LPCWSTR
    [MarshalAs(UnmanagedType.LPWStr)] string szSrcDir,   // LPCWSTR
    [MarshalAs(UnmanagedType.LPWStr)] string szDestDir,   // LPCWSTR
    [MarshalAs(UnmanagedType.LPWStr)] string szCurDir,   // LPCWSTR
    [MarshalAs(UnmanagedType.LPWStr)] System.Text.StringBuilder szTmpFile,   // LPWSTR out
    ref uint puTmpFileLen   // DWORD* in/out
);

<DllImport("VERSION.dll", CharSet:=CharSet.Unicode, ExactSpelling:=True)>
Public Shared Function VerInstallFileW(
    uFlags As UInteger,   ' VER_INSTALL_FILE_FLAGS
    <MarshalAs(UnmanagedType.LPWStr)> szSrcFileName As String,   ' LPCWSTR
    <MarshalAs(UnmanagedType.LPWStr)> szDestFileName As String,   ' LPCWSTR
    <MarshalAs(UnmanagedType.LPWStr)> szSrcDir As String,   ' LPCWSTR
    <MarshalAs(UnmanagedType.LPWStr)> szDestDir As String,   ' LPCWSTR
    <MarshalAs(UnmanagedType.LPWStr)> szCurDir As String,   ' LPCWSTR
    <MarshalAs(UnmanagedType.LPWStr)> szTmpFile As System.Text.StringBuilder,   ' LPWSTR out
    ByRef puTmpFileLen As UInteger   ' DWORD* in/out
) As UInteger
End Function

' uFlags : VER_INSTALL_FILE_FLAGS
' szSrcFileName : LPCWSTR
' szDestFileName : LPCWSTR
' szSrcDir : LPCWSTR
' szDestDir : LPCWSTR
' szCurDir : LPCWSTR
' szTmpFile : LPWSTR out
' puTmpFileLen : DWORD* in/out
Declare PtrSafe Function VerInstallFileW Lib "version" ( _
    ByVal uFlags As Long, _
    ByVal szSrcFileName As LongPtr, _
    ByVal szDestFileName As LongPtr, _
    ByVal szSrcDir As LongPtr, _
    ByVal szDestDir As LongPtr, _
    ByVal szCurDir As LongPtr, _
    ByVal szTmpFile As LongPtr, _
    ByRef puTmpFileLen 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

VerInstallFileW = ctypes.windll.version.VerInstallFileW
VerInstallFileW.restype = wintypes.DWORD
VerInstallFileW.argtypes = [
    wintypes.DWORD,  # uFlags : VER_INSTALL_FILE_FLAGS
    wintypes.LPCWSTR,  # szSrcFileName : LPCWSTR
    wintypes.LPCWSTR,  # szDestFileName : LPCWSTR
    wintypes.LPCWSTR,  # szSrcDir : LPCWSTR
    wintypes.LPCWSTR,  # szDestDir : LPCWSTR
    wintypes.LPCWSTR,  # szCurDir : LPCWSTR
    wintypes.LPWSTR,  # szTmpFile : LPWSTR out
    ctypes.POINTER(wintypes.DWORD),  # puTmpFileLen : DWORD* in/out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('VERSION.dll')
VerInstallFileW = Fiddle::Function.new(
  lib['VerInstallFileW'],
  [
    -Fiddle::TYPE_INT,  # uFlags : VER_INSTALL_FILE_FLAGS
    Fiddle::TYPE_VOIDP,  # szSrcFileName : LPCWSTR
    Fiddle::TYPE_VOIDP,  # szDestFileName : LPCWSTR
    Fiddle::TYPE_VOIDP,  # szSrcDir : LPCWSTR
    Fiddle::TYPE_VOIDP,  # szDestDir : LPCWSTR
    Fiddle::TYPE_VOIDP,  # szCurDir : LPCWSTR
    Fiddle::TYPE_VOIDP,  # szTmpFile : LPWSTR out
    Fiddle::TYPE_VOIDP,  # puTmpFileLen : DWORD* in/out
  ],
  -Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "version")]
extern "system" {
    fn VerInstallFileW(
        uFlags: u32,  // VER_INSTALL_FILE_FLAGS
        szSrcFileName: *const u16,  // LPCWSTR
        szDestFileName: *const u16,  // LPCWSTR
        szSrcDir: *const u16,  // LPCWSTR
        szDestDir: *const u16,  // LPCWSTR
        szCurDir: *const u16,  // LPCWSTR
        szTmpFile: *mut u16,  // LPWSTR out
        puTmpFileLen: *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 VerInstallFileW(uint uFlags, [MarshalAs(UnmanagedType.LPWStr)] string szSrcFileName, [MarshalAs(UnmanagedType.LPWStr)] string szDestFileName, [MarshalAs(UnmanagedType.LPWStr)] string szSrcDir, [MarshalAs(UnmanagedType.LPWStr)] string szDestDir, [MarshalAs(UnmanagedType.LPWStr)] string szCurDir, [MarshalAs(UnmanagedType.LPWStr)] System.Text.StringBuilder szTmpFile, ref uint puTmpFileLen);
"@
$api = Add-Type -MemberDefinition $sig -Name 'VERSION_VerInstallFileW' -Namespace Win32 -PassThru
# $api::VerInstallFileW(uFlags, szSrcFileName, szDestFileName, szSrcDir, szDestDir, szCurDir, szTmpFile, puTmpFileLen)

#uselib "VERSION.dll"
#func global VerInstallFileW "VerInstallFileW" wptr, wptr, wptr, wptr, wptr, wptr, wptr, wptr
; VerInstallFileW uFlags, szSrcFileName, szDestFileName, szSrcDir, szDestDir, szCurDir, varptr(szTmpFile), varptr(puTmpFileLen)   ; 戻り値は stat
; uFlags : VER_INSTALL_FILE_FLAGS -> "wptr"
; szSrcFileName : LPCWSTR -> "wptr"
; szDestFileName : LPCWSTR -> "wptr"
; szSrcDir : LPCWSTR -> "wptr"
; szDestDir : LPCWSTR -> "wptr"
; szCurDir : LPCWSTR -> "wptr"
; szTmpFile : LPWSTR out -> "wptr"
; puTmpFileLen : DWORD* in/out -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

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