KsAllocateObjectHeader 함수(ks.h)

아티클
02/07/2025

KsAllocateObjectHeader 함수는 필요한 파일 컨텍스트 헤더를 초기화합니다.

통사론

KSDDKAPI NTSTATUS KsAllocateObjectHeader(
  [out]          KSOBJECT_HEADER        *Header,
  [in]           ULONG                  ItemsCount,
  [in, optional] PKSOBJECT_CREATE_ITEM  ItemsList,
  [in]           PIRP                   Irp,
  [in]           const KSDISPATCH_TABLE *Table
);

매개 변수

[out] Header

성공한 경우 초기화된 KSOBJECT_HEADER 대한 포인터를 반환할 호출자가 할당한 위치를 가리킵니다.

[in] ItemsCount

헤더가 할당되면 개체 헤더에 추가할 ItemsList 개체 만들기 항목 수를 지정합니다. ItemsList NULL 경우 이 값은 0이어야 합니다.

[in, optional] ItemsList

필요에 따라 개체 헤더에 추가할 일련의 KSOBJECT_CREATE_ITEM 구조를 포함하는 호출자 할당 버퍼에 대한 포인터를 지정합니다. 개체 만들기 항목이 없는 경우 NULL 설정해야 합니다.

[in] Irp

개체 헤더 만들기를 완료하는 데 필요한 정보가 포함된 주요 함수 IRP_MJ_CREATEIRP를 가리킵니다.

[in] Table

이 파일 개체의 초기화된 디스패치 테이블을 가리킵니다.

반환 값

KsAllocateObjectHeader 함수는 성공하면 STATUS_SUCCESS 반환하고, 요청을 처리할 수 있는 리소스가 충분하지 않은 경우 STATUS_INSUFFICIENT_RESOURCES.

발언

이 루틴을 호출하기 전에 드라이버는 KSDISPATCH_TABLE 대한 시스템 상주 스토리지를 할당하고 디스패치 테이블을 초기화해야 합니다. KsFreeObjectHeader 호출될 때까지 이 디스패치 테이블에 대한 메모리를 해제할 수 없습니다.

KsAllocateObjectHeaderKSOBJECT_HEADER 구조체에 대한 메모리를 할당하고 헤더헤더에 대한 포인터를 반환합니다. 드라이버는 메모리 자체를 해제하려고 시도하지 말고 이 개체 헤더가 필요한 모든 작업이 완료되면 KsFreeObjectHeader 호출해야 합니다.

지정된 디바이스에 대해 하위 개체가 있는 경우 드라이버는 KsAllocateObjectHeader호출하기 전에 각 하위 개체에 대한 KSOBJECT_CREATE_ITEM 구조를 보유하기에 충분한 크기의 페이징된 메모리 또는 비페이지 메모리의 버퍼를 할당해야 합니다. 예를 들어:

/* Allocate a buffer for 4 subobjects for a given streaming device */
PKSOBJECT_CREATE_ITEM createBuffer ;
ULONG bufferSize  = (sizeof (KSOBJECT_CREATE_ITEM)) * 4 ;

createBuffer = (PKSOBJECT_CREATE_ITEM)
               ExAllocatePoolWithTag (PagedPool, bufferSize) ;

드라이버는 KsFreeDeviceHeader호출할 때까지 하위 개체 KSOBJECT_CREATE_ITEM 목록에 할당된 메모리를 해제해서는 안 됩니다. 이렇게 하지 않으면 버그 검사 조건이 발생할 수 있습니다.