Win32 API 64bit完全対応：PtrSafeとLongPtrの実践活用ガイド

Tech

  • TYPE: VBA_TECHNICAL_GUIDE

  • CATEGORY: Win32_API_COMPATIBILITY

  • TARGET_OS: Windows_64bit_Office

  • KEY_CONCEPTS: PtrSafe, LongPtr, Conditional_Compilation

本記事はGeminiの出力をプロンプト工学で整理した業務ドラフト（未検証）です。

Win32 API 64bit完全対応：PtrSafeとLongPtrの実践活用ガイド

【背景と目的】

Officeの64bit化に伴い、従来の32bit向けAPI宣言は動作しません。本ガイドでは「PtrSafe」と「LongPtr」を使い、エラーのない安定したAPI呼び出しを実現します。（68文字）

【処理フロー図】

graph TD
A["VBA実行開始"] --> B{"VBAのバージョン判定"}
B -->|VBA7以上| C["PtrSafe宣言 + LongPtrを使用"]
B -->|VBA6以下| D["従来のDeclare宣言を使用"]
C --> E["API関数の呼び出し"]
D --> E["API関数の呼び出し"]
E --> F["ハンドルやポインタの処理"]
F --> G["終了"]

【実装：VBAコード】

Option Explicit

' --- Win32 API 宣言セクション ---
' VBA7（Office 2010以降）かそれ以前かで宣言を切り分けます。
#If VBA7 Then

    ' 64bit/32bit両対応の宣言
    ' PtrSafe: 64bit環境での実行を許可するキーワード
    ' LongPtr: 32bitならLong(32bit)、64bitならLongLong(64bit)に自動変調される型
    Declare PtrSafe Function FindWindow Lib "user32" Alias "FindWindowA" ( _
        ByVal lpClassName As String, _
        ByVal lpWindowName As String) As LongPtr

    Declare PtrSafe Function SetWindowText Lib "user32" Alias "SetWindowTextA" ( _
        ByVal hwnd As LongPtr, _
        ByVal lpString As String) As Long
#Else

    ' 旧バージョン（32bit専用）の宣言
    Declare Function FindWindow Lib "user32" Alias "FindWindowA" ( _
        ByVal lpClassName As String, _
        ByVal lpWindowName As String) As Long

    Declare Function SetWindowText Lib "user32" Alias "SetWindowTextA" ( _
        ByVal hwnd As Long, _
        ByVal lpString As String) As Long
#End If

''' <summary>
''' ExcelのメインウィンドウタイトルをAPI経由で変更するサンプル
''' </summary>
Public Sub UpdateExcelWindowTitle()
    Dim hWndExcel As LongPtr ' ウィンドウハンドルは必ずLongPtrで受ける
    Dim newTitle As String

    ' 高速化設定
    On Error GoTo ErrorHandler
    Application.ScreenUpdating = False

    newTitle = "API制御実行中 - " & Format(Now, "yyyy/mm/dd HH:mm:ss")

    ' 1. 自ウィンドウのハンドルを取得（クラス名: XLMAIN）
    hWndExcel = FindWindow("XLMAIN", Application.Caption)

    ' 2. ハンドルが取得できた場合のみタイトル書き換えを実行
    If hWndExcel <> 0 Then
        SetWindowText hWndExcel, newTitle
        MsgBox "ウィンドウタイトルを更新しました。", vbInformation
    Else
        MsgBox "ハンドル取得に失敗しました。", vbCritical
    End If

CleanUp:
    ' 終了処理
    Application.ScreenUpdating = True
    Exit Sub

ErrorHandler:
    MsgBox "エラーが発生しました: " & Err.Description, vbExclamation
    Resume CleanUp
End Sub

【技術解説】

  1. PtrSafeキーワード: 64bit版VBAでAPIを呼び出す際、「この宣言は64bitで動作するように考慮されている」ことをコンパイラに伝える必須の記述です。

  2. LongPtr型: 最も重要なポイントです。メモリのアドレス（ポインタ）やウィンドウハンドル（HWND）を格納するために使用します。実行環境のビット数に合わせてサイズが自動調整されるため、型変換エラー（オーバーフロー）を防ぎます。

  3. 条件付きコンパイル (#If VBA7): 32bit版の古いOffice（Excel 2007以前）と互換性を保つための手法です。現代の業務環境ではほぼVBA7が通りますが、汎用ライブラリ化する場合は必須の作法です。

【注意点と運用】

  • 戻り値の型に注意: ハンドルやポインタを返す関数は LongPtr ですが、単なる数値（成功/失敗のフラグやカウント数など）を返す関数は、64bit環境でも Long (32bit整数) のままにする必要があります。

  • 構造体の位置合わせ: APIにユーザー定義型（Type）を渡す際、64bit環境ではメモリ上のアライメント（境界）が変わるため、構造体内の型定義も LongPtr への置き換えが必要です。

  • 参照設定の不要化: 本コードのように Declare 文を使用すれば、特定のDLLへの参照設定（References）を汚さずに配布可能です。

【まとめ】

  • API宣言には必ず PtrSafe を付与し、64bit対応を明示する。

  • ハンドル（HWND）やポインタを扱う変数は、LongPtr 型で定義する。

  • #If VBA7 を活用し、古いバージョンとの互換性と安全性を両立させる。

ライセンス：本記事のテキスト/コードは特記なき限り CC BY 4.0 です。引用の際は出典URL（本ページ）を明記してください。
利用ポリシー もご参照ください。

コメント

タイトルとURLをコピーしました