SetPrinter 함수
SetPrinter 함수는 지정한 프린터의 데이터를 설정하거나 인쇄를 일시 중지하거나 인쇄를 다시 시작하거나 모든 인쇄 작업을 지워 지정된 프린터의 상태를 설정합니다.
구문
BOOL SetPrinter(
_In_ HANDLE hPrinter,
_In_ DWORD Level,
_In_ LPBYTE pPrinter,
_In_ DWORD Command
);
매개 변수
-
hPrinter [in]
-
프린터에 대한 핸들입니다. OpenPrinter, OpenPrinter2 또는 AddPrinter 함수를 사용하여 프린터 핸들을 검색합니다.
-
수준 [in]
-
함수가 pPrinter가 가리키는 버퍼에 저장하는 데이터 형식입니다. Command 매개 변수가 0과 같지 않으면 Level 매개 변수는 0이어야 합니다.
이 값은 0, 2, 3, 4, 5, 6, 7, 8 또는 9일 수 있습니다.
-
pPrinter [in]
-
프린터에 대해 설정할 데이터를 포함하거나 Command 매개 변수로 지정된 명령에 대한 정보를 포함하는 버퍼에 대한 포인터입니다. 버퍼의 데이터 형식은 Level 값에 따라 결정 됩니다.
Level 구조체 - 0
Command 매개 변수가 PRINTER_CONTROL_SET_STATUS 경우 pPrinter에는 설정할 새 프린터 상태 지정하는 DWORD 값이 포함되어야 합니다. 가능한 상태 값 목록은 PRINTER_INFO_2 구조체의 상태 멤버를 참조하세요. PRINTER_STATUS_PAUSED 및 PRINTER_STATUS_PENDING_DELETION 설정할 상태 값이 잘못되었습니다.
Level이 0이지만 Command 매개 변수가 PRINTER_CONTROL_SET_STATUS 않으면 pPrinter는 NULL이어야 합니다.- 2
프린터에 대한 자세한 정보를 포함하는 PRINTER_INFO_2 구조체입니다. - 3
프린터의 보안 정보를 포함하는 PRINTER_INFO_3 구조체입니다. - 4
프린터 이름, 서버 이름, 프린터가 원격인지 로컬인지 여부 등 최소 프린터 정보를 포함하는 PRINTER_INFO_4 구조체입니다. - 5
프린터 특성 및 시간 제한 설정과 같은 프린터 정보를 포함하는 PRINTER_INFO_5 구조체입니다. - 6
프린터의 상태 값을 지정하는 PRINTER_INFO_6 구조체입니다. - 7
PRINTER_INFO_7 구조체입니다. 이 구조체의 dwAction 멤버는 SetPrinter 가 디렉터리 서비스에서 프린터의 데이터를 게시, 게시 취소, 다시 게시 또는 업데이트해야 하는지 여부를 나타냅니다. - 8
전역 기본 프린터 설정을 지정하는 PRINTER_INFO_8 구조체입니다. - 9
사용자별 기본 프린터 설정을 지정하는 PRINTER_INFO_9 구조체입니다. -
명령 [in]
-
수행할 작업입니다.
Level 매개 변수가 0이 아닌 경우 이 매개 변수의 값을 0으로 설정합니다. 이 경우 프린터는 현재 상태를 유지하고 함수는 Level 및 pPrinter 매개 변수에 지정된 대로 프린터 데이터를 다시 구성합니다.
Level 매개 변수가 0이면 이 매개 변수의 값을 다음 값 중 하나로 설정합니다.
값 의미 - PRINTER_CONTROL_PAUSE
프린터를 일시 중지합니다. - PRINTER_CONTROL_PURGE
프린터의 모든 인쇄 작업을 삭제합니다. - PRINTER_CONTROL_RESUME
일시 중지된 프린터를 다시 시작합니다. - PRINTER_CONTROL_SET_STATUS
프린터 상태 설정합니다.
pPrinter 매개 변수를 새 프린터 상태 지정하는 DWORD 값에 대한 포인터로 설정합니다.
반환 값
함수가 성공하면 반환 값은 0이 아닌 값입니다.
함수가 실패하면 반환 값은 0입니다.
Level이 7이고 게시 작업이 실패한 경우 SetPrinter는 ERROR_IO_PENDING 반환하고 백그라운드에서 작업을 완료하려고 시도합니다. Level이 7이고 업데이트 작업이 실패한 경우 SetPrinter는 ERROR_FILE_NOT_FOUND 반환합니다.
설명
참고
이는 차단 또는 동기 함수이며 즉시 반환되지 않을 수 있습니다. 이 함수가 반환되는 빈도는 애플리케이션을 작성할 때 예측하기 어려운 네트워크 상태, 인쇄 서버 구성 및 프린터 드라이버 구현 요소와 같은 런타임 요인에 따라 달라집니다. 사용자 인터페이스와의 상호 작용을 관리하는 스레드에서 이 함수를 호출하면 애플리케이션이 응답하지 않는 것처럼 보일 수 있습니다.
SetPrinter를 사용하여 기본 프린터를 변경할 수 없습니다.
현재 프린터 설정을 수정하려면 GetPrinter 함수를 호출하여 현재 설정을 PRINTER_INFO_2 구조체로 검색하고 필요에 따라 해당 구조체의 멤버를 수정한 다음 SetPrinter를 호출합니다.
SetPrinter 함수는 PRINTER_INFO_2 구조체의 pServerName, AveragePPM, Status 및 cJobs 멤버를 무시합니다.
프린터를 일시 중지하면 현재 인쇄할 수 있는 인쇄 작업 하나를 제외하고 해당 프린터에 대한 모든 인쇄 작업의 예약이 일시 중단됩니다. 인쇄 작업은 일시 중지된 프린터에 제출할 수 있지만 인쇄가 다시 시작될 때까지 해당 프린터에서 인쇄하도록 예약된 작업은 없습니다. 프린터가 지워지면 현재 인쇄 작업을 제외하고 해당 프린터에 대한 모든 인쇄 작업이 삭제됩니다.
SetPrinter를 사용하여 프린터의 기본 DEVMODE 구조를 수정하는 경우(전역적으로 프린터 기본값 설정) 먼저 DocumentProperties 함수를 호출하여 DEVMODE 구조의 유효성을 검사해야 합니다.
보안 설명자에 대한 포인터를 포함하는 PRINTER_INFO_2 및 PRINTER_INFO_3 구조체의 경우 함수는 호출자가 수정할 수 있는 권한이 있는 보안 설명자의 구성 요소만 설정할 수 있습니다. 특정 보안 설명자 구성 요소를 설정하려면 OpenPrinter 또는 OpenPrinter2 함수를 호출하여 프린터에 대한 핸들을 검색할 때 필요한 액세스 권한을 지정해야 합니다. 다음 표에서는 다양한 보안 설명자 구성 요소를 수정하는 데 필요한 액세스 권한을 보여 줍니다.
| 액세스 권한 | 보안 설명자 구성 요소 |
|---|---|
| WRITE_OWNER | 소유자 기본 그룹 |
| WRITE_DAC | DACL(임의 액세스 제어 목록) |
| ACCESS_SYSTEM_SECURITY | SACL(시스템 액세스 제어 목록) |
보안 설명자에 호출자에게 수정할 수 있는 액세스 권한이 없는 구성 요소가 포함되어 있으면 SetPrinter가 실패합니다. 수정하지 않으려는 보안 설명자의 구성 요소는 NULL 이거나 적절하지 않아야 합니다. 보안 설명자를 수정하지 않고 PRINTER_INFO_2 구조를 사용하여 SetPrinter를 호출하는 경우 해당 구조체의 pSecurityDescriptor 멤버를 NULL로 설정합니다.
ICF(인터넷 연결 방화벽)는 기본적으로 프린터 포트를 차단하지만 파일 및 인쇄 공유에 대한 예외를 사용하도록 설정할 수 있습니다. 컴퓨터 관리자가 SetPrinter 를 호출하면 예외가 활성화됩니다. 관리자가 아닌 사용자가 호출하고 예외가 아직 사용하도록 설정되지 않은 경우 호출이 실패합니다.
PRINTER_INFO_7 구조와 함께 수준 7을 사용하여 프린터에 대한 디렉터리 서비스 데이터를 게시, 게시 취소 또는 업데이트할 수 있습니다. 프린터의 디렉터리 서비스 데이터에는 프린터의 SetPrinterDataEx 함수를 호출하여 SPLDS_* 키 아래에 저장된 모든 데이터가 포함됩니다. SetPrinter를 호출하기 전에 PRINTER_INFO_7pszObjectGUID 멤버를 NULL로 설정하고 dwAction 멤버를 다음 값 중 하나로 설정합니다.
| 값 | Description |
|---|---|
|
DSPRINT_PUBLISH |
디렉터리 서비스 데이터를 게시합니다. |
|
DSPRINT_REPUBLISH |
프린터의 디렉터리 서비스 데이터가 게시되지 않은 다음 다시 게시되어 게시된 프린터의 모든 속성을 새로 고칩니다. 다시 게시하면 게시된 프린터의 GUID도 변경됩니다. 프린터의 게시된 데이터가 손상된 것으로 의심되는 경우 이 값을 사용합니다. |
|
DSPRINT_UNPUBLISH |
디렉터리 서비스 데이터를 게시 취소합니다. |
|
DSPRINT_UPDATE |
디렉터리 서비스 데이터를 업데이트. 프린터가 아직 게시되지 않은 경우 SetPrinter가 ERROR_FILE_NOT_FOUND 실패한다는 점을 제외하면 DSPRINT_PUBLISH 동일합니다. DSPRINT_UPDATE 사용하여 게시된 속성을 업데이트하지만 강제로 게시하지는 않습니다. 프린터 드라이버는 항상 DSPRINT_PUBLISH 대신 DSPRINT_UPDATE 사용해야 합니다. |
DSPRINT_PENDINGSetPrinter에 대한 유효한 dwAction 값이 아닙니다.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 |
Windows 2000 Professional[데스크톱 앱만] |
| 지원되는 최소 서버 |
Windows 2000 Server[데스크톱 앱만] |
| 헤더 |
|
| 라이브러리 |
|
| DLL |
|
| 유니코드 및 ANSI 이름 |
SetPrinterW (유니코드) 및 SetPrinterA (ANSI) |