CreateDCA

関数

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

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

シグネチャ

// GDI32.dll  (ANSI / -A)
#include <windows.h>

HDC CreateDCA(
    LPCSTR pwszDriver,   // optional
    LPCSTR pwszDevice,   // optional
    LPCSTR pszPort,   // optional
    const DEVMODEA* pdm   // optional
);

パラメーター

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

戻り値の型: HDC

公式ドキュメント

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

戻り値

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

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

解説(Remarks)

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

パラメーター lpszDriver および lpszDevice については、EnumDisplayDevices を呼び出して表示デバイスの有効な名前を取得してください。

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

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

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

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

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

例

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

メモ

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

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

各言語での呼び出し定義

// GDI32.dll  (ANSI / -A)
#include <windows.h>

HDC CreateDCA(
    LPCSTR pwszDriver,   // optional
    LPCSTR pwszDevice,   // optional
    LPCSTR pszPort,   // optional
    const DEVMODEA* pdm   // optional
);

[DllImport("GDI32.dll", CharSet = CharSet.Ansi, ExactSpelling = true)]
static extern IntPtr CreateDCA(
    [MarshalAs(UnmanagedType.LPStr)] string pwszDriver,   // LPCSTR optional
    [MarshalAs(UnmanagedType.LPStr)] string pwszDevice,   // LPCSTR optional
    [MarshalAs(UnmanagedType.LPStr)] string pszPort,   // LPCSTR optional
    IntPtr pdm   // DEVMODEA* optional
);

<DllImport("GDI32.dll", CharSet:=CharSet.Ansi, ExactSpelling:=True)>
Public Shared Function CreateDCA(
    <MarshalAs(UnmanagedType.LPStr)> pwszDriver As String,   ' LPCSTR optional
    <MarshalAs(UnmanagedType.LPStr)> pwszDevice As String,   ' LPCSTR optional
    <MarshalAs(UnmanagedType.LPStr)> pszPort As String,   ' LPCSTR optional
    pdm As IntPtr   ' DEVMODEA* optional
) As IntPtr
End Function

' pwszDriver : LPCSTR optional
' pwszDevice : LPCSTR optional
' pszPort : LPCSTR optional
' pdm : DEVMODEA* optional
Declare PtrSafe Function CreateDCA Lib "gdi32" ( _
    ByVal pwszDriver As String, _
    ByVal pwszDevice As String, _
    ByVal pszPort As String, _
    ByVal pdm As LongPtr) As LongPtr
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

CreateDCA = ctypes.windll.gdi32.CreateDCA
CreateDCA.restype = ctypes.c_void_p
CreateDCA.argtypes = [
    wintypes.LPCSTR,  # pwszDriver : LPCSTR optional
    wintypes.LPCSTR,  # pwszDevice : LPCSTR optional
    wintypes.LPCSTR,  # pszPort : LPCSTR optional
    ctypes.c_void_p,  # pdm : DEVMODEA* optional
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('GDI32.dll')
CreateDCA = Fiddle::Function.new(
  lib['CreateDCA'],
  [
    Fiddle::TYPE_VOIDP,  # pwszDriver : LPCSTR optional
    Fiddle::TYPE_VOIDP,  # pwszDevice : LPCSTR optional
    Fiddle::TYPE_VOIDP,  # pszPort : LPCSTR optional
    Fiddle::TYPE_VOIDP,  # pdm : DEVMODEA* optional
  ],
  Fiddle::TYPE_VOIDP)

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

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

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

出力引数:

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