createDCA 函数 (wingdi.h)

项目
08/27/2023

CreateDC 函数使用指定名称为设备创建设备上下文 (DC) 。

语法

HDC CreateDCA(
       LPCSTR         pwszDriver,
  [in] LPCSTR         pwszDevice,
       LPCSTR         pszPort,
  [in] const DEVMODEA *pdm
);

参数

pwszDriver

指向以 null 结尾的字符串的指针，该字符串指定 DISPLAY 或特定显示设备的名称。对于打印，建议将 NULL 传递给 lpszDriver ，因为 GDI 忽略打印机设备的 lpszDriver 。

[in] pwszDevice

指向以 null 结尾的字符串的指针，该字符串指定正在使用的特定输出设备的名称，如打印管理器 (所示，例如 Epson FX-80) 。它不是打印机型号名称。必须使用 lpszDevice 参数。

若要获取显示器的有效名称，请调用 EnumDisplayDevices。

如果 lpszDriver 为 DISPLAY 或特定显示设备的设备名称，则 lpszDevice 必须为 NULL 或相同的设备名称。如果 lpszDevice 为 NULL，则为主显示设备创建 DC。

如果系统上有多个监视器，则调用 CreateDC(TEXT("DISPLAY"),NULL,NULL,NULL) 将创建涵盖所有监视器的 DC。

pszPort

此参数将被忽略，应设置为 NULL。它仅用于与 16 位 Windows 兼容。

[in] pdm

指向 DEVMODE 结构的指针，其中包含设备驱动程序的特定于设备的初始化数据。 DocumentProperties 函数检索为指定设备填充的此结构。如果设备驱动程序要使用默认初始化 (（如果用户指定了任何) ， 则 pdm 参数必须为 NULL 。

如果 lpszDriver 为 DISPLAY， 则 pdm 必须为 NULL;然后，GDI 使用显示设备的当前 DEVMODE。

返回值

如果函数成功，则返回值是指定设备的 DC 的句柄。

如果函数失败，则返回值为 NULL。

注解

请注意，DC 的句柄在任何时候只能由单个线程使用。

对于参数 lpszDriver 和 lpszDevice，请调用 EnumDisplayDevices 以获取显示的有效名称。

如果不再需要 DC，请调用 DeleteDC 函数。

如果 lpszDriver 或 lpszDevice 为 DISPLAY，则调用 CreateDC 的线程拥有创建的 HDC 。销毁此线程时， HDC 不再有效。因此，如果创建 HDC 并将其传递给另一个线程，然后退出第一个线程，则第二个线程将无法使用 HDC。

调用 CreateDC 为显示设备创建 HDC 时，必须传递给 pdm NULL 或指向 DEVMODE 的指针，该指针与 lpszDevice 指定的显示设备的当前 DEVMODE 匹配。建议传递 NULL ，不要尝试与当前显示设备的 DEVMODE 完全匹配。

调用 CreateDC 为打印机设备创建 HDC 时，打印机驱动程序会验证 DEVMODE。如果打印机驱动程序确定 DEVMODE 无效 (即打印机驱动程序无法转换或使用 DEVMODE) ，则打印机驱动程序会提供默认 DEVMODE 来为打印机设备创建 HDC。

Icm：若要启用 ICM，请将 pInitData 参数 (指向的 DEVMODE 结构的 dmICMMethod 成员) 设置为适当的值。

示例

有关示例，请参阅捕获图像。

注意

wingdi.h 标头将 CreateDC 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。

要求

要求	值
最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	wingdi.h (包括 Windows.h)
Library	Gdi32.lib
DLL	Gdi32.dll