XcvDataPort 함수(winsplp.h)

아티클
03/13/2023

포트 모니터 서버 DLL의 XcvDataPort 함수는 포트 모니터의 UI DLL에서 정보를 수신하고 정보를 반환합니다.

구문

DWORD XcvDataPort(
  _In_  HANDLE  hXcv,
  _In_  LPCWSTR pszDataName,
  _In_  PBYTE   pInputData,
        DWORD   cbInputData,
  _Out_ PBYTE   pOutputData,
        DWORD   cbOutputData,
  _Out_ PDWORD  pcbOutputNeeded
);

매개 변수

[in] hXcv

OpenPrinter(Microsoft Windows SDK 설명서에 설명됨)를 호출하여 가져온 호출자 제공 프린터 핸들입니다. 이 핸들은 XcvOpenPort 함수에 의해 만들어지고 반환됩니다.

[in] pszDataName

요청되는 데이터의 이름을 나타내는 문자열에 대한 호출자 제공 포인터입니다. 자세한 내용은 아래 설명 부분을 참조하십시오.

[in] pInputData

입력 데이터를 포함하는 버퍼에 대한 호출자 제공 포인터입니다.

cbInputData

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

[out] pOutputData

출력 데이터를 수신하는 버퍼에 대한 호출자 제공 포인터입니다.

cbOutputData

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

[out] pcbOutputNeeded

pOutputData가 가리키는 버퍼에 필요한 최소 크기(바이트)를 받을 위치에 대한 호출자 제공 포인터입니다.

반환 값

작업이 성공하면 이 함수는 ERROR_SUCCESS 반환해야 합니다. 그렇지 않으면 ERROR_ 접두사 Win32 오류 코드를 반환해야 합니다. 인쇄 모니터 UI DLL은 XcvData에 지정된 pdwStatus 위치에서 이 값을 받습니다.

설명

포트 모니터 서버 DLL은 포트 모니터 UI DLL에서 정보를 수신하고 정보를 반환할 수 있도록 XcvDataPort 함수를 정의해야 합니다. 함수의 주소는 MONITOR2 구조에 포함되어야 합니다.

XcvDataPort 함수는 스풀러의 XcvData 함수에 의해 호출됩니다. XcvDataPort 및 XcvData에 대한 함수 매개 변수는 거의 동일합니다. (XcvData에는 XcvDataPort에 없는 추가 매개 변수 pdwStatus가 있습니다.)

pszDataName에서 가리키는 문자열은 수행할 작업을 지정합니다. 함수는 다음 데이터 이름 문자열을 인식해야 합니다.

데이터 이름 문자열	작업
L"AddPort"	포트를 추가하는 데 필요한 모든 정보가 전송되었습니다. 함수는 포트 키 아래에 레지스트리에 포트 이름을 쓰는 등 지정된 포트를 추가하는 데 필요한 작업을 수행해야 합니다. pInputData 매개 변수는 NULL로 끝나는 포트 이름 문자열을 가리킵니다. 함수가 ERROR_SUCCESS 반환하면 스풀러는 포트를 추가된 것으로 표시합니다. 이 문자열은 AddPortUI 함수 내에서 인쇄 모니터 UI DLL에 의해 지정됩니다.
L"DeletePort"	포트를 삭제하는 데 필요한 모든 정보가 전송되었습니다. 함수는 레지스트리의 포트 키에서 포트 이름을 제거하는 등 지정된 포트를 삭제하는 데 필요한 작업을 수행해야 합니다. pInputData 매개 변수는 NULL로 끝나는 포트 이름 문자열을 가리킵니다. 함수가 ERROR_SUCCESS 반환하면 스풀러는 포트를 삭제된 것으로 표시합니다. 이 문자열은 DeletePortUI 함수 내에서 인쇄 모니터 UI DLL에 의해 지정됩니다.
L"MonitorUI"	함수는 pOutputData 를 사용하여 연결된 포트 모니터 UI DLL의 이름을 반환해야 합니다. 이 문자열은 애플리케이션이 Microsoft Windows SDK AddPort 함수를 호출할 때 인쇄 스풀러에 의해 지정됩니다.

일반적으로 함수는 AddPortUI,ConfigurePortUI 및 DeletePortUI 함수 내에서 UI DLL에 의해 전송되는 추가 사용자 지정 문자열을 인식하도록 작성됩니다. 이러한 문자열은 서버 DLL에서 현재 구성 값을 요청하거나 새 값을 제공하는 명령을 나타낼 수 있습니다. 예를 들어 XcvDataPort 함수는 UI DLL이 현재 저장된 전송 재시도 시간 제한 값을 요청하기 위해 서버 DLL에 보낼 수 있는 "GetTransmissionRetryTimeout" 문자열을 인식할 수 있습니다. 또는 "AddPort" 또는 "DeletePort"를 보내기 전에 전송해야 하는 문자열 집합을 정의할 수 있습니다. 여기서 문자열은 추가 또는 삭제할 포트를 식별하는 정보를 제공하는 데 사용됩니다.

지정된 pszDataName 문자열 및 입력 버퍼의 경우 먼저 cbOutputData 값이 0인 XcvDataPort를 호출할 수 있습니다. 함수는 pcbOutputNeeded의 필수 버퍼 크기와 ERROR_INSUFFICIENT_BUFFER 반환 값을 반환해야 합니다. 호출자는 pcbOutputNeeded에서 받은 값을 사용하여 적절한 크기의 출력 버퍼를 할당한 다음, 이번에는 cbOutputData에서 할당된 버퍼 크기를 지정하여 XcvDataPort를 다시 호출할 수 있습니다.

XcvDataPort 함수는 모든 입력 인수의 유효성을 검사해야 합니다. 특히 함수는 다음을 수행해야 합니다.

pszDataName 매개 변수가 가리키는 문자열의 내용의 유효성을 검사합니다. 이 문자열이 관리 작업(일반적으로 포트 추가, 삭제 또는 구성)을 나타내는 경우 XcvDataPort 함수는 이전에 XcvOpenPort 함수에서 받은 부여된 액세스 마스크를 SERVER_ACCESS_ADMINISTER 비교해야 합니다. 비교에 실패하면 XcvDataPort 는 ERROR_ACCESS_DENIED 반환해야 합니다.
pInputData 매개 변수가 가리키는 버퍼의 내용의 유효성을 검사합니다. 스풀러가 XcvOpenPort 함수를 호출하면 이 버퍼의 내용에 대한 유효성 검사를 수행하지 않습니다. 모니터는 악의적인 애플리케이션에서 올 수 있는 이 데이터의 유효성을 가정할 수 없습니다.

TCPMON과 통신할 포트 모니터를 작성하는 경우 TCPMON Xcv 인터페이스를 참조하세요.