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 |