FltCreateCommunicationPort 함수(fltkernel.h)

아티클
08/07/2023

FltCreateCommunicationPort 는 미니필터 드라이버가 사용자 모드 애플리케이션에서 연결 요청을 받을 수 있는 통신 서버 포트를 만듭니다.

구문

NTSTATUS FLTAPI FltCreateCommunicationPort(
  [in]           PFLT_FILTER            Filter,
  [out]          PFLT_PORT              *ServerPort,
  [in]           POBJECT_ATTRIBUTES     ObjectAttributes,
  [in, optional] PVOID                  ServerPortCookie,
  [in]           PFLT_CONNECT_NOTIFY    ConnectNotifyCallback,
  [in]           PFLT_DISCONNECT_NOTIFY DisconnectNotifyCallback,
  [in, optional] PFLT_MESSAGE_NOTIFY    MessageNotifyCallback,
  [in]           LONG                   MaxConnections
);

매개 변수

[in] Filter

호출자에 대한 불투명 필터 포인터입니다.

[out] ServerPort

통신 서버 포트에 대한 불투명 포트 핸들을 수신하는 호출자가 할당한 변수에 대한 포인터입니다. 미니 필터 드라이버는 이 핸들을 사용하여 사용자 모드 애플리케이션에서 들어오는 연결 요청을 수신 대기합니다.

[in] ObjectAttributes

통신 서버 포트의 특성을 지정하는 OBJECT_ATTRIBUTES 구조체에 대한 포인터입니다. 이 구조체는 InitializeObjectAttributes에 대한 이전 호출에 의해 초기화되어야 합니다. 이 매개 변수는 필수이며 NULL일 수 없습니다. 통신 포트 개체에 대한 이 구조체의 멤버는 다음과 같습니다.

멤버	값
ULONG 길이	InitializeObjectAttributes는 이 멤버를 sizeof(OBJECT_ATTRIBUTES)로 설정합니다.
PUNICODE_STRING ObjectName	포트 개체의 고유한 이름(예: L"\\MyFilterPort")을 포함하는 UNICODE_STRING 구조체에 대한 포인터입니다.
PSECURITY_DESCRIPTOR SecurityDescriptor	포트 개체에 적용할 보안 설명자(SECURITY_DESCRIPTOR)에 대한 포인터입니다. 필요한 경우 FltBuildDefaultSecurityDescriptor를 호출하여 기본 보안 설명자를 만들 수 있습니다.
ULONG 특성	포트 핸들에 원하는 특성을 지정하는 플래그의 비트 마스크입니다. 이러한 플래그에는 OBJ_KERNEL_HANDLE 포함되어야 합니다. 호출자는 필요에 따라 OBJ_CASE_INSENSITIVE 플래그를 설정할 수 있습니다. 이는 이름 조회 코드가 정확한 일치 검색을 수행하는 대신 ObjectName 의 대/소문자를 무시해야 함을 나타냅니다.

[in, optional] ServerPortCookie

미니필터 드라이버에서 정의한 컨텍스트 정보에 대한 포인터입니다. 이 정보는 동일한 미니필터 드라이버에서 만든 여러 통신 서버 포트를 구분하는 데 사용할 수 있습니다. 필터 관리자는 이 컨텍스트 포인터를 ConnectNotifyCallback 루틴에 매개 변수로 전달합니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다.

[in] ConnectNotifyCallback

호출자가 제공한 콜백 루틴에 대한 포인터입니다. Filter Manager는 사용자 모드 애플리케이션이 FilterConnectCommunicationPort 를 호출하여 미니필터 드라이버에 연결 요청을 보낼 때마다 이 루틴을 호출합니다. 이 매개 변수는 필수이며 NULL일 수 없습니다. 이 루틴은 IRQL = PASSIVE_LEVEL 호출됩니다.

이 루틴은 다음과 같이 선언됩니다.

typedef NTSTATUS
(*PFLT_CONNECT_NOTIFY) (
      IN PFLT_PORT ClientPort,
      IN PVOID ServerPortCookie,
      IN PVOID ConnectionContext,
      IN ULONG SizeOfContext,
      OUT PVOID *ConnectionPortCookie
      );

ClientPort

사용자 모드 애플리케이션과 커널 모드 미니필터 드라이버 간에 설정된 새 클라이언트 포트에 대한 불투명 핸들입니다.

이 클라이언트 포트에서 메시지를 보내고 회신할 때 미니필터 드라이버는 이 핸들을 ClientPort 매개 변수로 FltSendMessage 에 전달해야 합니다. (FltCreateCommunicationPort에서 반환된 ServerPort 핸들과는 다릅니다.)

미니필터 드라이버는 결국 이 클라이언트 포트를 닫아야 합니다. 클라이언트 포트는 일반적으로 미니필터 드라이버의 DisconnectNotifyCallback 루틴에서 FltCloseClientPort를 호출하여 닫힙니다.

ServerPortCookie

미니필터 드라이버에서 정의한 컨텍스트 정보에 대한 포인터입니다. 이 정보는 동일한 미니필터 드라이버에서 만든 여러 통신 서버 포트를 구분하는 데 사용할 수 있습니다. 서버 포트를 만들 때 미니필터 드라이버는 이 컨텍스트 포인터를 FltCreateCommunicationPort에 매개 변수로 전달했습니다.

ConnectionContext

사용자 모드 애플리케이션이 lpContext 매개 변수에서 FilterConnectCommunicationPort에 전달한 컨텍스트 정보 포인터입니다.

SizeOfContext

ConnectionContext가 가리키는 버퍼의 크기(바이트)입니다.

ConnectionPortCookie

이 클라이언트 포트를 고유하게 식별하는 정보에 대한 포인터입니다. 이 정보는 미니필터 드라이버에 의해 정의됩니다. 필터 관리자는 이 컨텍스트 포인터를 미니필터 드라이버의 DisconnectNotifyCallback 및 MessageNotifyCallback 루틴에 매개 변수로 전달합니다.

[in] DisconnectNotifyCallback

클라이언트 포트의 사용자 모드 핸들 수가 0에 도달하거나 미니필터 드라이버가 언로드될 때마다 호출할 호출자가 제공하는 콜백 루틴에 대한 포인터입니다. 이 매개 변수는 필수이며 NULL일 수 없습니다. 이 루틴은 IRQL = PASSIVE_LEVEL 호출됩니다.

이 루틴은 다음과 같이 선언됩니다.

typedef VOID
(*PFLT_DISCONNECT_NOTIFY) (
      IN PVOID ConnectionCookie
      );

ConnectionCookie

이 클라이언트 포트를 고유하게 식별하는 정보에 대한 포인터입니다. 이 정보는 미니필터 드라이버에 의해 정의됩니다. 클라이언트 포트를 만들 때 미니필터 드라이버는 ConnectNotifyCallback 루틴의 ConnectionPortCookie 매개 변수에 이 컨텍스트 포인터를 반환했습니다.

[in, optional] MessageNotifyCallback

호출자가 제공한 콜백 루틴에 대한 포인터입니다. 필터 관리자는 사용자 모드 애플리케이션이 FilterSendMessage 를 호출하여 클라이언트 포트를 통해 미니필터 드라이버에 메시지를 보낼 때마다 IRQL = PASSIVE_LEVEL 이 루틴을 호출합니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다. NULL인 경우 포트에 데이터를 보내기 위해 사용자 모드에서 수행한 모든 요청에 오류가 발생합니다.

이 루틴은 다음과 같이 선언됩니다.

typedef NTSTATUS
(*PFLT_MESSAGE_NOTIFY) (
      IN PVOID PortCookie,
      IN PVOID InputBuffer OPTIONAL,
      IN ULONG InputBufferLength,
      OUT PVOID OutputBuffer OPTIONAL,
      IN ULONG OutputBufferLength,
      OUT PULONG ReturnOutputBufferLength
      );

PortCookie

InputBuffer

미니필터 드라이버로 보낼 메시지를 포함하는 호출자가 할당한 버퍼에 대한 포인터입니다.

InputBuffer는 잠금 해제된 원시 사용자 모드 버퍼에 대한 포인터입니다. 이 포인터는 사용자 모드 프로세스의 컨텍스트에서만 유효하며 블록을제외한try/ 내에서만 액세스해야 합니다.

필터 관리자는 ProbeForRead 를 호출하여 이 포인터의 유효성을 검사하지만 버퍼가 제대로 정렬되었는지는 확인하지 않습니다. 버퍼에 맞춤 요구 사항이 있는 구조체가 포함된 경우 미니필터 드라이버는 필요한 맞춤 검사를 수행해야 합니다. 이를 위해 미니필터 드라이버는 MiniSpy 샘플 미니필터 드라이버와 같이 IS_ALIGNED 매크로를 사용할 수 있습니다.

이 매개 변수는 선택 사항이며 NULL일 수 있습니다.

InputBufferLength

InputBuffer가 가리키는 버퍼의 크기(바이트)입니다. InputBuffer가 NULL인 경우 이 매개 변수는 무시됩니다.

OutputBuffer

미니필터 드라이버에서 회신(있는 경우)을 수신하는 호출자가 할당한 버퍼에 대한 포인터입니다.

OutputBuffer는 잠금 해제된 원시 사용자 모드 버퍼에 대한 포인터입니다. 이 포인터는 사용자 모드 프로세스의 컨텍스트에서만 유효하며 블록을제외한try/ 내에서만 액세스해야 합니다.

필터 관리자는 ProbeForWrite 를 호출하여 이 포인터의 유효성을 검사하지만 버퍼가 제대로 정렬되었는지는 확인하지 않습니다. 버퍼에 맞춤 요구 사항이 있는 구조체가 포함된 경우 미니필터 드라이버는 필요한 맞춤 검사를 수행해야 합니다. 이를 위해 미니필터 드라이버는 MiniSpy 샘플 미니필터 드라이버와 같이 IS_ALIGNED 매크로를 사용할 수 있습니다.

이 매개 변수는 선택 사항이며 NULL일 수 있습니다.

OutputBufferLength

OutputBuffer가 가리키는 버퍼의 크기(바이트)입니다. OutputBuffer가 NULL인 경우 이 매개 변수는 무시됩니다.

ReturnOutputBufferLength

OutputBuffer가 가리키는 버퍼에 반환된 바이트 수를 수신하는 호출자 할당 변수에 대한 포인터입니다.

[in] MaxConnections

이 서버 포트에 대해 허용되는 최대 동시 클라이언트 연결 수입니다. 이 매개 변수는 필수이며 0보다 커야 합니다.

반환 값

FltCreateCommunicationPort 는 STATUS_SUCCESS 또는 다음 중 하나와 같은 적절한 NTSTATUS 값을 반환합니다.

반환 코드	설명
STATUS_FLT_DELETING_OBJECT	지정한 필터 가 삭제되고 있습니다. 오류 코드입니다.
STATUS_INSUFFICIENT_RESOURCES	FltCreateCommunicationPort 에서 풀 할당 오류가 발생했습니다. 오류 코드입니다.
STATUS_OBJECT_NAME_COLLISION	이름이 같은 미니필터 드라이버 통신 포트가 이미 있습니다. 포트 이름은 고유해야 합니다. 오류 코드입니다.

설명

미니필터 드라이버는 FltCreateCommunicationPort 를 호출하여 통신 서버 포트 개체를 만듭니다.

서버 포트를 만든 후 사용자 모드 애플리케이션은 FilterConnectCommunicationPort를 호출하여 포트에 연결할 수 있습니다. 연결되면 사용자 모드 애플리케이션은 FilterSendMessage, FilterGetMessage 및 FilterReplyMessage와 같은 사용자 모드 메시징 함수를 호출하여 메시지를 보내고 받을 수 있습니다.

호출자는 FltCreateCommunicationPort의 ObjectAttributes 매개 변수에 대한 OBJ_KERNEL_HANDLE 특성 플래그를 설정해야 합니다. 이 플래그를 설정하면 FltCreateCommunicationPort 의 호출자가 실행될 수 있는 컨텍스트의 사용자 모드 프로세스에서 미니필터 드라이버 통신 서버 포트 핸들을 사용할 수 없습니다. 이 플래그가 설정되지 않은 경우 FltCreateCommunicationPort 는 STATUS_INVALID_PARAMETER 반환합니다.

FltCreateCommunicationPort에서 만든 모든 서버 포트는 FltCloseCommunicationPort를 호출하여 결국 닫혀야 합니다. 서버 포트가 닫히면 서버 포트에 대한 새 연결이 허용되지 않으며 FilterConnectCommunicationPort 에 대한 모든 호출이 실패합니다. 그러나 기존 연결은 사용자 모드 애플리케이션 또는 미니필터 드라이버에 의해 닫히거나 미니필터 드라이버가 언로드될 때까지 열려 있습니다.