DrvDocumentEvent 함수(winddiui.h)

아티클
02/06/2022
읽는 데 13분 걸림

프린터 인터페이스 DLL의 DrvDocumentEvent 함수는 문서 인쇄와 관련된 특정 이벤트를 처리할 수 있습니다.

구문

int DrvDocumentEvent(
        HANDLE hPrinter,
        HDC    hdc,
        int    iEsc,
        ULONG  cbIn,
  [in]  PVOID  pvIn,
        ULONG  cbOut,
  [out] PVOID  pvOut
);

매개 변수

hPrinter

발신자가 제공한 프린터 핸들입니다.

hdc

CreateDC(Windows SDK 설명서에 설명됨) 호출에 의해 생성된 호출자 제공 디바이스 컨텍스트 핸들입니다. iEsc를 DOCUMENTEVENT_CREATEDCPRE 설정하면 0입니다. 64비트 버전의 Windows 32비트 애플리케이션에서 인쇄에 대한 제한 사항은 다음 주의 섹션을 참조하세요.

iEsc

처리할 이벤트를 식별하는 호출자 제공 이스케이프 코드입니다. 이 매개 변수는 다음 정수 상수 중 하나일 수 있습니다. 이벤트 열에 나열된 함수에 대한 설명은 Windows SDK 설명서를 참조하세요.

64비트 버전의 Windows 32비트 애플리케이션에서 인쇄에 대한 제한 사항은 다음 주의 섹션을 참조하세요.

iEsc 상수	이벤트
DOCUMENTEVENT_ABORTDOC	GDI는 AbortDoc 함수에 대한 호출을 처리하려고 합니다.
DOCUMENTEVENT_CREATEDCPOST	GDI는 CreateDC 또는 CreateIC 함수에 대한 호출을 방금 처리했습니다. iEsc가 DOCUMENTEVENT_CREATEDCPRE 설정된 DrvDocumentEvent에 대한 이전 호출이 없으면 이 이스케이프 코드를 사용하면 안 됩니다.
DOCUMENTEVENT_CREATEDCPRE	GDI는 CreateDC 또는 CreateIC 함수에 대한 호출을 처리하려고 합니다.
DOCUMENTEVENT_DELETEDC	GDI가 DeleteDC 함수에 대한 호출을 처리하려고 합니다.
DOCUMENTEVENT_ENDDOCPOST	GDI는 EndDoc 함수에 대한 호출을 방금 처리했습니다.
DOCUMENTEVENT_ENDDOCPRE 또는 DOCUMENTEVENT_ENDDOC	GDI는 EndDoc 함수에 대한 호출을 처리하려고 합니다.
DOCUMENTEVENT_ENDPAGE	GDI가 EndPage 함수에 대한 호출을 처리하려고 합니다.
DOCUMENTEVENT_ESCAPE	GDI는 해당 ExtEscape 함수에 대한 호출을 처리하려고 합니다.
DOCUMENTEVENT_QUERYFILTER	DOCUMENTEVENT_QUERYFILTER 이벤트는 스풀러가 드라이버가 응답할 DOCUMENTEVENT_XXX 이벤트 목록을 드라이버에 쿼리할 수 있는 기회를 나타냅니다. 이 이벤트는 DOCUMENTEVENT_CREATEDCPRE 이벤트를 전달하는 DrvDocumentEvent 호출 직전에 발생합니다.
DOCUMENTEVENT_RESETDCPOST	GDI는 ResetDC 함수에 대한 호출을 방금 처리했습니다. iEsc가 DOCUMENTEVENT_RESETDCPRE 설정된 DrvDocumentEvent에 대한 이전 호출이 없으면 이 이스케이프 코드를 사용하면 안 됩니다.
DOCUMENTEVENT_RESETDCPRE	GDI는 ResetDC 함수에 대한 호출을 처리하려고 합니다.
DOCUMENTEVENT_STARTDOCPOST	GDI가 StartDoc 함수에 대한 호출을 방금 처리했습니다.
DOCUMENTEVENT_STARTDOCPRE 또는 DOCUMENTEVENT_STARTDOC	GDI가 StartDoc 함수에 대한 호출을 처리하려고 합니다.
DOCUMENTEVENT_STARTPAGE	GDI가 StartPage 함수에 대한 호출을 처리하려고 합니다.

cbIn

pvIn에서 가리키는 버퍼의 호출자 제공 크기(바이트 )입니다.

[in] pvIn

호출자 제공 포인터는 다음과 같이 iEsc에 제공된 값에 따라 달라집니다.

iEsc 상수	pvIn 내용을
DOCUMENTEVENT_ABORTDOC	사용되지 않습니다.
DOCUMENTEVENT_CREATEDCPOST	pvIn은 iEsc 매개 변수가 DOCUMENTEVENT_CREATEDCPRE 설정된 이 함수에 대한 이전 호출에서 pvOut 매개 변수에 지정된 DEVMODEW 구조체에 대한 포인터의 주소를 포함합니다.
DOCUMENTEVENT_CREATEDCPRE	pvIn은 DOCEVENT_CREATEDCPRE 구조를 가리킵니다.
DOCUMENTEVENT_DELETEDC	사용되지 않습니다.
DOCUMENTEVENT_ENDDOCPOST	사용되지 않습니다.
DOCUMENTEVENT_ENDDOCPRE 또는 DOCUMENTEVENT_ENDDOC	사용되지 않습니다.
DOCUMENTEVENT_ENDPAGE	사용되지 않습니다.
DOCUMENTEVENT_ESCAPE	pvIn은 DOCEVENT_ESCAPE 구조를 가리킵니다.
DOCUMENTEVENT_QUERYFILTER	DOCUMENTEVENT_CREATEDCPRE 경우와 동일합니다.
DOCUMENTEVENT_RESETDCPOST	pvIn은 iEsc 매개 변수가 DOCUMENTEVENT_RESETDCPRE 설정된 이 함수에 대한 이전 호출에서 pvOut 매개 변수에 지정된 DEVMODEW 구조체에 대한 포인터의 주소를 포함합니다.
DOCUMENTEVENT_RESETDCPRE	pvIn은 ResetDC 호출자가 제공하는 DEVMODEW 구조체에 대한 포인터의 주소를 포함합니다(Windows SDK 설명서에 설명되어 있습니다).
DOCUMENTEVENT_STARTDOCPOST	pvIn은 StartDoc에서 반환된 인쇄 작업 식별자를 지정하는 LONG을 가리킵니다(Windows SDK 설명서에 설명되어 있습니다).
DOCUMENTEVENT_STARTDOCPRE 또는 DOCUMENTEVENT_STARTDOC	pvIn은 StartDoc 호출자가 제공하는 DOCINFO 구조체에 대한 포인터의 주소를 포함합니다(둘 다 Windows SDK 설명서에 설명되어 있습니다).
DOCUMENTEVENT_STARTPAGE	사용되지 않습니다.

cbOut

iEsc가 DOCUMENTEVENT_ESCAPE 경우:

ExtEscape에 대한 cbOutput 매개 변수로 사용되는 함수 제공 값입니다.

iEsc가 DOCUMENTEVENT_QUERYFILTER 경우:

pvOut에 의해 버퍼 포인터의 호출자 제공 크기(바이트)입니다.

다른 모든 iEsc 값의 경우:

사용되지 않습니다.

[out] pvOut

다음과 같이 iEsc에 제공된 값에 따라 달라지는 출력 버퍼에 대한 함수 제공 포인터입니다. CreateDC, ExtEscape 및 ResetDC는 Windows SDK 설명서에 설명되어 있습니다.

iEsc 상수	pvOut 내용을
DOCUMENTEVENT_CREATEDCPRE	GDI가 CreateDC 호출자가 제공하는 구조 대신 사용하는 드라이버 제공 DEVMODEW 구조체에 대한 포인터입니다. ( NULL인 경우 GDI는 호출자가 제공한 구조를 사용합니다.)
DOCUMENTEVENT_ESCAPE	ExtEscape에 대한 lpszOutData 매개 변수로 사용되는 버퍼 포인터입니다.
DOCUMENTEVENT_QUERYFILTER	DOCEVENT_FILTER 구조체를 포함하는 버퍼에 대한 호출자 제공 포인터입니다.
DOCUMENTEVENT_RESETDCPRE	드라이버 제공 DEVMODEW 구조에 대한 포인터로, GDI는 ResetDC 호출자가 제공하는 구조 대신 사용합니다. ( NULL인 경우 GDI는 호출자가 제공한 구조를 사용합니다.)
기타 모든 iEsc 값	사용되지 않습니다.

반환 값

함수의 반환 값은 iEsc에 제공된 이스케이프에 따라 달라집니다. 일부 이스케이프 코드의 경우 반환 값이 사용되지 않습니다(두 번째 값 목록 참조). 함수가 반환 값을 제공하는 경우 다음 중 하나여야 합니다.

반환 코드	설명
DOCUMENTEVENT_FAILURE	드라이버는 iEsc로 식별된 이스케이프 코드를 지원하지만 오류가 발생했습니다.
DOCUMENTEVENT_SUCCESS	드라이버가 iEsc로 식별된 이스케이프 코드를 성공적으로 처리했습니다.
DOCUMENTEVENT_UNSUPPORTED	드라이버는 iEsc로 식별된 이스케이프 코드를 지원하지 않습니다.

설명

프린터 인터페이스 DLL은 필요에 따라 DrvDocumentEvent 함수를 제공하여 문서 렌더링과 관련된 GDI 호출의 전처리 또는 후처리를 수행할 수 있습니다. DrvDocumentEvent 함수에 대한 호출은 애플리케이션이 GDI 클라이언트를 호출할 때 사용자 모드 GDI 클라이언트에서 이루어집니다.

DOCUMENTEVENT_QUERYFILTER iEsc 값의 경우 스풀러는 드라이버가 DOCEVENT_FILTER 구조체의 특정 멤버를 수정했는지 여부에 따라 DrvDocumentEvent 에서 반환하는 DOCUMENTEVENT_SUCCESS 값을 두 가지 방법으로 해석할 수 있습니다. (pvOut 매개 변수는 이 구조를 가리킵니다.) 스풀러는 이 형식의 구조에 대한 메모리를 할당할 때 이 구조체의 두 멤버인 cElementsReturned 및 cElementsNeeded를 알려진 값으로 초기화합니다. DrvDocumentEvent가 반환된 후 스풀러는 이러한 멤버의 값이 변경되었는지 여부를 확인하고 해당 정보를 사용하여 DrvDocumentEvent 반환 값을 해석합니다. 다음 표에서는 이 상황을 요약합니다.

반환 값	cElementsReturned의 상태,	의미
반환 값	cElementsNeeded	의미
DOCUMENTEVENT_SUCCESS	드라이버는 두 멤버를 변경하지 않았습니다.	스풀러는 이 반환 값을 DOCUMENTEVENT_UNSUPPORTED 동일한 값으로 해석합니다. 스풀러는 드라이버에서 이벤트 필터를 검색할 수 없으므로 모든 이벤트에 대해 DrvDocumentEvent 를 계속 호출합니다.
DOCUMENTEVENT_SUCCESS	드라이버는 하나 또는 두 멤버에게 썼다.	스풀러는 해석 없이 이 반환 값을 허용합니다. 드라이버가 cElementsNeeded 및 cElementsReturned 중 하나에만 쓴 경우 스풀러는 변경되지 않은 멤버의 값이 0인 것으로 간주합니다. 스풀러는 DOCEVENT_FILTER aDocEventCall 멤버에 나열된 모든 이벤트를 필터링합니다.
DOCUMENTEVENT_UNSUPPORTED	적용할 수 없음	드라이버는 DOCUMENTEVENT_QUERYFILTER 지원하지 않습니다. 스풀러는 드라이버에서 이벤트 필터를 검색할 수 없으므로 모든 이벤트에 대해 DrvDocumentEvent 를 계속 호출합니다.
DOCUMENTEVENT_FAILURE	적용할 수 없음	드라이버는 DOCUMENTEVENT_QUERYFILTER 지원하지만 내부 오류가 발생했습니다. 스풀러는 드라이버에서 이벤트 필터를 검색할 수 없으므로 모든 이벤트에 대해 DrvDocumentEvent 를 계속 호출합니다.

이스케이프 코드 이름에 접미사가 없거나 PRE 접미사가 있는 경우 GDI 클라이언트는 커널 모드 GDI 렌더링 엔진을 호출하기 직전에 DrvDocumentEvent 를 호출합니다. 이스케이프 코드 이름에 POST 접미사가 있는 경우 GDI 클라이언트는 커널 모드 GDI 렌더링 엔진이 반환 된 직후 DrvDocumentEvent 를 호출합니다.

iEsc 매개 변수에 제공된 이스케이프 코드가 DOCUMENTEVENT_CREATEDCPRE 경우 다음 규칙이 적용됩니다.

작업이 스풀링하지 않고 프린터로 직접 전송되는 경우 pvIn --> pszDevice는 프린터 이름을 가리킵니다. 자세한 내용은 DOCEVENT_CREATEDCPRE 구조를 참조하세요.
작업이 스풀되는 경우 pvIn --> pszDevice는 프린터 포트 이름을 가리킵니다.

DrvDocumentEvent 함수는 GDI 클라이언트 함수의 사용자 모드 호출자의 컨텍스트에서 실행됩니다. EMF 스풀링을 사용하지 않도록 설정하면 함수가 사용자 인터페이스를 표시할 수 있습니다. 예를 들어 FAX 드라이버에 대한 DrvDocumentEvent 함수는 GDI의 StartDoc 함수(Microsoft Windows SDK 설명서에 설명됨)가 처리되기 전에 사용자에게 대화 상자를 표시할 수 있습니다.

참고 64비트 버전의 Windows 32비트 애플리케이션을 실행하는 경우 다음과 같은 제한 사항이 적용됩니다. DrvDocumentEvent에서 호출해야 하는 유일한 GDI 함수는 ExtEscape이며 프라이빗 이스케이프만 사용해야 합니다. 다른 GDI 함수에 대한 DrvDocumentEvent 호출은 정의되지 않은 동작을 생성할 수 있습니다.