StartXpsPrintJob 함수(xpsprint.h)
[StartXpsPrintJob은 지원되지 않으며 나중에 변경되거나 사용할 수 없습니다. ]
XPS 문서 스트림을 프린터로 인쇄하기 시작합니다.
구문
HRESULT StartXpsPrintJob(
[in] LPCWSTR printerName,
[in] LPCWSTR jobName,
[in] LPCWSTR outputFileName,
[in] HANDLE progressEvent,
[in] HANDLE completionEvent,
[in] UINT8 *printablePagesOn,
[in] UINT32 printablePagesOnCount,
[out] IXpsPrintJob **xpsPrintJob,
[out] IXpsPrintJobStream **documentStream,
[out] IXpsPrintJobStream **printTicketStream
);
매개 변수
[in] printerName
이 작업이 연결될 프린터의 이름입니다.
[in] jobName
이 작업과 연결할 사용자 지정 작업 이름입니다. 작업에 별도의 사용자 지정 이름이 필요하지 않은 경우 이 매개 변수를 NULL로 설정할 수 있습니다.
[in] outputFileName
이 작업의 출력을 리디렉션할 파일 또는 포트의 파일 이름입니다. 이 값을 설정하면 인쇄 작업의 출력이 지정된 파일 또는 포트로 전달됩니다. printerName으로 지정된 프린터로 인쇄 작업을 보내려면 이 매개 변수를 NULL로 설정해야 합니다.
[in] progressEvent
다음 인쇄 작업이 변경될 때 신호를 수신하는 이벤트 핸들입니다.
- 인쇄 작업에 작업 ID가 할당됨
- 페이지 인쇄가 완료되었습니다.
- 문서 인쇄가 완료되었습니다.
- 인쇄 작업이 취소되었거나 오류로 인해 종료되었습니다.
XPS Print API는 호출자의 책임인 이 이벤트를 다시 설정하지 않습니다.
진행률 알림이 필요하지 않은 경우 이 매개 변수를 NULL로 설정할 수 있습니다.
[in] completionEvent
인쇄 작업이 완료될 때 신호를 수신하는 이벤트 핸들입니다. 이 이벤트는 StartXpsPrintJob 호출당 정확히 한 번 신호를 받을 수 있습니다. XPS Print API는 호출자의 책임인 이 이벤트를 다시 설정하지 않습니다.
완료 알림이 필요하지 않은 경우 이 매개 변수를 NULL로 설정할 수 있습니다.
[in] printablePagesOn
매개 변수는 요소가 인쇄할 문서 페이지의 하위 집합을 지정하는 UINT8 배열을 참조합니다. 다음 표에 표시된 것처럼 각 요소의 값은 페이지를 인쇄할지 여부를 나타냅니다.
| Array 요소 값 | 의미 |
|---|---|
|
페이지를 인쇄하지 마세요. |
|
페이지를 인쇄합니다. |
진행률 이벤트는 인쇄용으로 지정된 페이지에 대해서만 신호를 보냅니다.
배열의 요소는 XPS 패키지의 모든 문서에서 인쇄를 위해 지정된 모든 페이지를 나타냅니다. 예를 들어 패키지에 각각 3페이지가 있는 두 개의 문서가 포함된 경우 다음 표에 표시된 배열은 문서 1의 페이지 0과 2, 문서 2의 페이지 0 및 2 인쇄를 지정합니다.
| 요소 인덱스 | 요소 값 | 인쇄? | 문서 번호 | 페이지 번호 |
|---|---|---|---|---|
| 5 | 1 | 예 | 2 | 2 |
| 4 | 0 | 예 | 2 | 1 |
| 3 | 1 | 예 | 2 | 0 |
| 2 | 1 | 예 | 1 | 2 |
| 1 | 0 | 예 | 1 | 1 |
| 0 | 1 | 예 | 1 | 0 |
printablePagesOn이 NULL이면 패키지의 모든 페이지가 인쇄됩니다.
printablePagesOn에 패키지에 페이지가 있는 것보다 많은 요소가 있는 경우 불필요한 요소는 무시됩니다.
배열에 문서에 있는 페이지보다 적은 요소가 있는 경우 배열의 마지막 배열 요소 값이 나머지 페이지에 적용됩니다. 이 규칙을 사용하면 개방형이거나 인쇄된 큰 문서의 몇 페이지만 가져오는 범위를 쉽게 지정할 수 있습니다.
[in] printablePagesOnCount
printablePagesOn에서 참조하는 배열의 요소 수입니다. printablePagesOn이 NULL이면 이 매개 변수는 무시됩니다.
[out] xpsPrintJob
StartXpsPrintJob에서 만든 인쇄 작업을 나타내는 IXpsPrintJob 인터페이스에 대한 포인터입니다. 인쇄 작업의 상태 가져오거나 취소하려면 IXpsPrintJob 인터페이스를 사용합니다. IXpsPrintJob이 필요하지 않은 경우 이 매개 변수를 NULL로 설정할 수 있습니다.
[out] documentStream
호출자가 이 인쇄 작업에서 인쇄할 XPS 문서를 작성하는 IXpsPrintJobStream 인터페이스에 대한 포인터입니다.
[out] printTicketStream
호출자가 이 작업과 연결할 작업 수준 인쇄 티켓을 작성하는 데 사용하는 IXpsPrintJobStream 인터페이스에 대한 포인터입니다. 이 매개 변수가 NULL로 설정된 경우 documentStream 에 기록된 XPS 문서의 인쇄 티켓(있는 경우)이 사용됩니다.
반환 값
이 메서드는 HRESULT를 반환합니다. 가능한 값에는 다음 표에 있는 값이 포함되지만, 이에 국한되는 것은 아닙니다.
| 반환 코드 | 설명 |
|---|---|
|
메서드가 성공했습니다. |
|
printerName 또는 documentStream 이 NULL입니다. |
|
메모리가 부족하여 새 IXpsPrintJob 개체를 만들 수 없습니다. |
설명
StartXpsPrintJob 은 인쇄 스풀러가 인쇄 작업을 만들거나 시작하기 전에 반환할 수 있는 비동기 함수입니다.
XpsPrintJob, documentStream 및 printTicketStream에서 반환되는 인터페이스는 StartXpsPrintJob이 성공적으로 반환될 때까지 사용해서는 안 됩니다.
호출자가 데이터 전송을 시작한 후에는 progressEvent에서 전달된 이벤트에 신호를 보내는 진행률 이벤트를 모니터링해야 합니다. 이벤트가 신호를 받으면 호출자는 IXpsPrintJob::GetJobStatus를 호출하여 인쇄 작업의 현재 상태 가져와야 합니다.
인쇄 작업이 성공적으로 완료되었는지 여부에 관계없이 completionEvent 에 전달된 이벤트는 한 번만 신호를 보냅니다. 데이터 손실을 방지하기 위해 호출자는 이 이벤트를 모니터링해야 하며 이벤트가 신호를 받을 때까지 호출자의 스레드 또는 애플리케이션을 종료하지 않아야 합니다.
작업 상태는 인쇄 스풀러에 의해 저장되거나 큐에 대기되지 않습니다. 작업 처리는 이벤트가 신호를 받은 후 상태 읽을 때까지 기다리지 않으므로 애플리케이션이 변경 알림을 받은 시간과 IXpsPrintJob::GetJobStatus라는 시간 사이의 지연에 따라 호출자가 일부 상태 변경을 놓칠 수 있습니다. 후속 알림을 받으려면 애플리케이션이 알림을 받은 후 진행률 이벤트를 다시 설정해야 합니다.
StartXpsPrintJob에 대한 호출이 실패하면 작업 상태 업데이트되고 완료 및 진행률 이벤트가 신호를 받고 오류 코드가 반환됩니다. 실패한 인쇄 작업의 상태 가져오려면 IXpsPrintJob::GetJobStatus를 호출합니다.
StartXpsPrintJob은completionEvent 및 progressEvent에서 DuplicateHandle을 호출하여 작업의 수명 동안 유효한 상태를 유지하도록 합니다. 인쇄 스풀러는 이벤트에 중복 핸들을 사용하므로 호출자는 작업 실행에 영향을 주지 않고 언제든지 이러한 핸들을 닫을 수 있습니다. 그러나 호출자가 completionEvent 이벤트가 신호를 받고 호출자가 관찰한 후에만 호출자가 이러한 핸들을 닫는 것이 좋습니다.
documentStream 및 printTicketStream에 반환되는 IXpsPrintJobStream 인터페이스는 검색을 허용하지 않지만 닫을 수 있는 쓰기 전용 스트림입니다. 호출자는 XPS 문서를 작성하고 티켓 콘텐츠를 이러한 스트림에 인쇄한 다음 모든 데이터가 기록된 후 Close 를 호출합니다. 스트림의 Write 메서드에 대한 호출은 스레드로부터 안전합니다. 그러나 이러한 호출이 다른 스레드에서 수행되는 경우 예상되는 순서로 스트림에 커밋되는 것은 보장되지 않습니다.
요구 사항
| 지원되는 최소 클라이언트 | Windows 7 [데스크톱 앱만 해당] |
| 지원되는 최소 서버 | Windows Server 2008 R2 [데스크톱 앱만 해당] |
| 대상 플랫폼 | Windows |
| 헤더 | xpsprint.h |
| 라이브러리 | XpsPrint.lib |
| DLL | XpsPrint.dll |