CreateDCW

関数

指定したデバイス用のデバイスコンテキストを作成する(Unicode版)。

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

シグネチャ

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

HDC CreateDCW(
    LPCWSTR pwszDriver,   // optional
    LPCWSTR pwszDevice,   // optional
    LPCWSTR pszPort,   // optional
    const DEVMODEW* pdm   // optional
);

パラメーター

名前	型	方向	説明
pwszDriver	LPCWSTR	inoptional	DISPLAY または特定の表示デバイスの名前を指定する、null 終端の文字列へのポインターです。印刷の場合、GDI はプリンターデバイスに対して lpszDriver を無視するため、lpszDriver に NULL を渡すことをお勧めします。
pwszDevice	LPCWSTR	inoptional	使用する特定の出力デバイスの名前を指定する、null 終端の文字列へのポインターです。この名前は、プリントマネージャーに表示されるもの (例: Epson FX-80) であり、プリンターのモデル名ではありません。lpszDevice パラメーターは必ず指定する必要があります。ディスプレイの有効な名前を取得するには、EnumDisplayDevices を呼び出します。 lpszDriver が DISPLAY または特定の表示デバイスのデバイス名である場合、lpszDevice は NULL または同じデバイス名でなければなりません。lpszDevice が NULL の場合、プライマリ表示デバイスに対して DC が作成されます。システムに複数のモニターがある場合、`CreateDC(TEXT("DISPLAY"),NULL,NULL,NULL)` を呼び出すと、すべてのモニターを覆う DC が作成されます。
pszPort	LPCWSTR	inoptional	このパラメーターは無視されるため、NULL に設定する必要があります。16 ビット版 Windows との互換性のためにのみ提供されています。
pdm	DEVMODEW*	inoptional	デバイスドライバー用のデバイス固有の初期化データを格納する DEVMODE 構造体へのポインターです。DocumentProperties 関数は、指定したデバイスに合わせて値が設定されたこの構造体を取得します。デバイスドライバーがユーザーによって指定された既定の初期化 (存在する場合) を使用する場合、pdm パラメーターは NULL でなければなりません。 lpszDriver が DISPLAY の場合、pdm は NULL でなければなりません。この場合、GDI は表示デバイスの現在の DEVMODE を使用します。

戻り値の型: HDC

公式ドキュメント

CreateDC 関数は、指定した名前を使用してデバイスのデバイスコンテキスト (DC) を作成します。(Unicode)

戻り値

関数が成功した場合、戻り値は指定したデバイスの DC のハンドルです。

関数が失敗した場合、戻り値は NULL です。

解説(Remarks)

DC のハンドルは、いかなる時点でも単一のスレッドからのみ使用できることに注意してください。

パラメーター lpszDriver および lpszDevice について、ディスプレイの有効な名前を取得するには EnumDisplayDevices を呼び出します。

DC が不要になったら、DeleteDC 関数を呼び出します。

lpszDriver または lpszDevice が DISPLAY の場合、CreateDC を呼び出したスレッドが、作成された HDC を所有します。このスレッドが破棄されると、HDC は無効になります。したがって、HDC を作成して別のスレッドに渡し、最初のスレッドを終了すると、2 番目のスレッドはその HDC を使用できなくなります。

表示デバイス用の HDC を作成するために CreateDC を呼び出す場合、pdm には NULL を渡すか、lpszDevice が指定する表示デバイスの現在の DEVMODE と一致する DEVMODE へのポインターを渡す必要があります。現在の表示デバイスの DEVMODE を厳密に一致させようとせず、NULL を渡すことをお勧めします。

プリンターデバイス用の HDC を作成するために CreateDC を呼び出す場合、プリンタードライバーは DEVMODE を検証します。プリンタードライバーが DEVMODE を無効 (つまり、プリンタードライバーが DEVMODE を変換または処理できない) と判断した場合、プリンタードライバーは既定の DEVMODE を提供して、プリンターデバイス用の HDC を作成します。

ICM: ICM を有効にするには、DEVMODE 構造体 (pInitData パラメーターが指すもの) の dmICMMethod メンバーを適切な値に設定します。

例

例については、Capturing an Image を参照してください。

メモ

wingdi.h ヘッダーは CreateDC をエイリアスとして定義しており、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)

各言語での呼び出し定義

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

HDC CreateDCW(
    LPCWSTR pwszDriver,   // optional
    LPCWSTR pwszDevice,   // optional
    LPCWSTR pszPort,   // optional
    const DEVMODEW* pdm   // optional
);

[DllImport("GDI32.dll", CharSet = CharSet.Unicode, ExactSpelling = true)]
static extern IntPtr CreateDCW(
    [MarshalAs(UnmanagedType.LPWStr)] string pwszDriver,   // LPCWSTR optional
    [MarshalAs(UnmanagedType.LPWStr)] string pwszDevice,   // LPCWSTR optional
    [MarshalAs(UnmanagedType.LPWStr)] string pszPort,   // LPCWSTR optional
    IntPtr pdm   // DEVMODEW* optional
);

<DllImport("GDI32.dll", CharSet:=CharSet.Unicode, ExactSpelling:=True)>
Public Shared Function CreateDCW(
    <MarshalAs(UnmanagedType.LPWStr)> pwszDriver As String,   ' LPCWSTR optional
    <MarshalAs(UnmanagedType.LPWStr)> pwszDevice As String,   ' LPCWSTR optional
    <MarshalAs(UnmanagedType.LPWStr)> pszPort As String,   ' LPCWSTR optional
    pdm As IntPtr   ' DEVMODEW* optional
) As IntPtr
End Function

' pwszDriver : LPCWSTR optional
' pwszDevice : LPCWSTR optional
' pszPort : LPCWSTR optional
' pdm : DEVMODEW* optional
Declare PtrSafe Function CreateDCW Lib "gdi32" ( _
    ByVal pwszDriver As LongPtr, _
    ByVal pwszDevice As LongPtr, _
    ByVal pszPort As LongPtr, _
    ByVal pdm As LongPtr) As LongPtr
' 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

CreateDCW = ctypes.windll.gdi32.CreateDCW
CreateDCW.restype = ctypes.c_void_p
CreateDCW.argtypes = [
    wintypes.LPCWSTR,  # pwszDriver : LPCWSTR optional
    wintypes.LPCWSTR,  # pwszDevice : LPCWSTR optional
    wintypes.LPCWSTR,  # pszPort : LPCWSTR optional
    ctypes.c_void_p,  # pdm : DEVMODEW* optional
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('GDI32.dll')
CreateDCW = Fiddle::Function.new(
  lib['CreateDCW'],
  [
    Fiddle::TYPE_VOIDP,  # pwszDriver : LPCWSTR optional
    Fiddle::TYPE_VOIDP,  # pwszDevice : LPCWSTR optional
    Fiddle::TYPE_VOIDP,  # pszPort : LPCWSTR optional
    Fiddle::TYPE_VOIDP,  # pdm : DEVMODEW* optional
  ],
  Fiddle::TYPE_VOIDP)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "gdi32")]
extern "system" {
    fn CreateDCW(
        pwszDriver: *const u16,  // LPCWSTR optional
        pwszDevice: *const u16,  // LPCWSTR optional
        pszPort: *const u16,  // LPCWSTR optional
        pdm: *const DEVMODEW  // DEVMODEW* optional
    ) -> *mut core::ffi::c_void;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("GDI32.dll", CharSet = CharSet.Unicode)]
public static extern IntPtr CreateDCW([MarshalAs(UnmanagedType.LPWStr)] string pwszDriver, [MarshalAs(UnmanagedType.LPWStr)] string pwszDevice, [MarshalAs(UnmanagedType.LPWStr)] string pszPort, IntPtr pdm);
"@
$api = Add-Type -MemberDefinition $sig -Name 'GDI32_CreateDCW' -Namespace Win32 -PassThru
# $api::CreateDCW(pwszDriver, pwszDevice, pszPort, pdm)

#uselib "GDI32.dll"
#func global CreateDCW "CreateDCW" wptr, wptr, wptr, wptr
; CreateDCW pwszDriver, pwszDevice, pszPort, varptr(pdm)   ; 戻り値は stat
; pwszDriver : LPCWSTR optional -> "wptr"
; pwszDevice : LPCWSTR optional -> "wptr"
; pszPort : LPCWSTR optional -> "wptr"
; pdm : DEVMODEW* optional -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "GDI32.dll"
#cfunc global CreateDCW "CreateDCW" wstr, wstr, wstr, var
; res = CreateDCW(pwszDriver, pwszDevice, pszPort, pdm)
; pwszDriver : LPCWSTR optional -> "wstr"
; pwszDevice : LPCWSTR optional -> "wstr"
; pszPort : LPCWSTR optional -> "wstr"
; pdm : DEVMODEW* optional -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "GDI32.dll"
#cfunc global CreateDCW "CreateDCW" wstr, wstr, wstr, sptr
; res = CreateDCW(pwszDriver, pwszDevice, pszPort, varptr(pdm))
; pwszDriver : LPCWSTR optional -> "wstr"
; pwszDevice : LPCWSTR optional -> "wstr"
; pszPort : LPCWSTR optional -> "wstr"
; pdm : DEVMODEW* optional -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。