Compartilhar via


Função KsCreateFilterFactory (ks.h)

A função KsCreateFilterFactory** adiciona uma fábrica de filtros a um determinado dispositivo.

Sintaxe

KSDDKAPI NTSTATUS KsCreateFilterFactory(
  [in]            PDEVICE_OBJECT            DeviceObject,
  [in]            const KSFILTER_DESCRIPTOR *Descriptor,
  [in, optional]  PWSTR                     RefString,
  [in, optional]  PSECURITY_DESCRIPTOR      SecurityDescriptor,
  [in]            ULONG                     CreateItemFlags,
  [in, optional]  PFNKSFILTERFACTORYPOWER   SleepCallback,
  [in, optional]  PFNKSFILTERFACTORYPOWER   WakeCallback,
  [out, optional] PKSFILTERFACTORY          *FilterFactory
);

Parâmetros

[in] DeviceObject

Um ponteiro para uma estrutura DEVICE_OBJECT para a qual adicionar uma fábrica de filtros.

[in] Descriptor

Um ponteiro para um KSFILTER_DESCRIPTOR que descreve as características de filtros individuais que essa fábrica pode criar.

[in, optional] RefString

Se esse argumento for fornecido, essa cadeia de caracteres será usada como a cadeia de caracteres de referência para filtros criados por essa fábrica. Caso contrário, o GUID de referência fornecido no descritor será usado.

[in, optional] SecurityDescriptor

O descritor de segurança a ser usado na criação de filtros por essa fábrica de filtros. Se FOR NULL, nenhum descritor será fornecido.

[in] CreateItemFlags

A tabela a seguir lista os sinalizadores que o gravador de minidriver usa para especificar as características dos filtros que a nova fábrica de filtros pode criar. Defina esse parâmetro como o OR bit a bit dos sinalizadores abaixo.

Sinalizador Significado
KSCREATE_ITEM_SECURITY_CHANGED Indica que o descritor de segurança nesse tipo de objeto foi alterado e deve ser persistido.
KSCREATE_ITEM_WILDCARD Indica que este item de criação representa um curinga que é usado para quaisquer solicitações de criação que não correspondam a nenhum outro item de criação. A ordenação da entrada curinga na lista de itens de criação é irrelevante. Somente uma única entrada curinga é válida em qualquer lista de itens de criação.
KSCREATE_ITEM_NOPARAMETERS Indica que esse item de criação não permite que nenhum parâmetro seja passado e falhará se algum for encontrado. (Normalmente, os parâmetros de criação são passados para o manipulador de criação.) Esse sinalizador não pode ser usado com um sinalizador curinga.
KSCREATE_ITEM_FREEONSTOP Indica que o item de criação deve ser liberado quando o gerenciador PnP envia IRP_MN_STOP_DEVICE. Observe que o AVStream libera automaticamente esses itens de criação quando o dispositivo recebe a parada PnP (depois que o cliente recebe a notificação de parada PnP).

[in, optional] SleepCallback

Um ponteiro para uma rotina fornecida pelo minidriver que recebe notificações de que o dispositivo associado a esse filtro vai entrar em suspensão. Protótipo da rotina da seguinte maneira:

void SleepCallback (IN PKSFILTERFACTORY FilterFactory,
    IN DEVICE_POWER_STATE State);

Se esse parâmetro for NULL, essa fábrica de filtros não será notificada de que o dispositivo será suspenso. Confira Estados de energia do dispositivo.

[in, optional] WakeCallback

Um ponteiro para uma rotina fornecida pelo minidriver que recebe notificações de que o dispositivo associado a esse filtro está acordando. Protótipo da rotina da seguinte maneira:

void WakeCallback (IN PKSFILTERFACTORY FilterFactory,
    IN DEVICE_POWER_STATE State);

Se esse parâmetro for NULL, essa fábrica de filtros não será notificada de que o dispositivo está acordando. Confira Estados de energia do dispositivo.

[out, optional] FilterFactory

Um ponteiro para uma estrutura KSFILTERFACTORY que o AVStream define para apontar para o objeto de fábrica de filtro recém-criado. Se esse parâmetro opcional não for especificado, o chamador não será informado sobre o objeto de fábrica de filtro resultante.

Retornar valor

Retorna STATUS_SUCCESS se a fábrica de filtros puder ser criada. Caso contrário, ele retornará um código de erro apropriado.

Comentários

Se você chamar KsCreateFilterFactory após AVStrMiniDevicePostStart), deverá chamar KsFilterFactorySetDeviceClassesState para habilitar a classe de dispositivo. (Chame também KsFilterFactorySetDeviceClassesState para desabilitar uma fábrica de filtros.)

Se você chamar KsCreateFilterFactory no contexto de AVStrMiniDevicePostStart ou antes, não precisará fazer isso.

Antes de chamar essa função, o minidriver deve obter o mutex do dispositivo. Para obter informações sobre como fazer isso, consulte Device Mutex in AVStream.

Essa função deve ser usada por minidrivers que se inicializam sem uma chamada para KsInitializeDriver ou que devem adicionar e remover novos tipos de filtro dinamicamente.

Requisitos

Requisito Valor
Cliente mínimo com suporte Disponível no Microsoft Windows XP e em sistemas operacionais posteriores e no DirectX 8.0 e versões posteriores do DirectX.
Plataforma de Destino Universal
Cabeçalho ks.h (inclua Ks.h)
Biblioteca Ks.lib
IRQL PASSIVE_LEVEL

Confira também

KSFILTER_DESCRIPTOR

KSNODE_DESCRIPTOR

KSPIN_DESCRIPTOR_EX

KsDeleteFilterFactory