Função WdmlibIoCreateDeviceSecure (wdmsec.h)
A função WdmlibIoCreateDeviceSecure (ou IoCreateDeviceSecure) cria um objeto de dispositivo nomeado e aplica as configurações de segurança especificadas.
Sintaxe
NTSTATUS WdmlibIoCreateDeviceSecure(
[in] PDRIVER_OBJECT DriverObject,
[in] ULONG DeviceExtensionSize,
[in, optional] PUNICODE_STRING DeviceName,
[in] DEVICE_TYPE DeviceType,
[in] ULONG DeviceCharacteristics,
[in] BOOLEAN Exclusive,
[in] PCUNICODE_STRING DefaultSDDLString,
[in, optional] LPCGUID DeviceClassGuid,
PDEVICE_OBJECT *DeviceObject
);
Parâmetros
[in] DriverObject
Ponteiro para o objeto driver do chamador. Cada driver recebe um ponteiro para seu objeto driver em um parâmetro para sua rotina DriverEntry . Os drivers de função e filtro do WDM também recebem um ponteiro de objeto de driver em suas rotinas AddDevice .
[in] DeviceExtensionSize
Especifica o número determinado pelo driver de bytes a serem alocados para a extensão do dispositivo do objeto do dispositivo. A estrutura interna da extensão do dispositivo é definida pelo driver.
[in, optional] DeviceName
Opcionalmente, aponta para um buffer que contém uma cadeia de caracteres Unicode terminada em nulo que nomeia o objeto do dispositivo. A cadeia de caracteres deve ser um nome de caminho completo. Se um nome não for fornecido, o sinalizador FILE_AUTOGENERATED_DEVICE_NAME deverá estar presente no parâmetro DeviceCharacteristics . (Para criar um objeto de dispositivo sem nome, use a rotina IoCreateDevice .)
[in] DeviceType
Especifica uma das constantes FILE_DEVICE_XXX definidas pelo sistema que indicam o tipo de dispositivo (como FILE_DEVICE_DISK, FILE_DEVICE_KEYBOARD e assim por diante) ou um valor definido pelo fornecedor para um novo tipo de dispositivo. Para obter mais informações, consulte Especificando tipos de dispositivo. (Como um driver de barramento pode não ter informações sobre o tipo de um dispositivo, um valor de tipo de dispositivo para um PDO pode ser especificado em uma diretiva AddReg inf.)
[in] DeviceCharacteristics
Especifica uma ou mais constantes definidas pelo sistema, ORed juntas, que fornecem informações adicionais sobre o dispositivo do driver. Para obter uma lista de possíveis características do dispositivo, consulte DEVICE_OBJECT. Para obter mais informações sobre como especificar características do dispositivo, consulte Especificando características do dispositivo. A maioria dos drivers especifica FILE_DEVICE_SECURE_OPEN para esse parâmetro.
[in] Exclusive
Especifica se o objeto do dispositivo representa um dispositivo exclusivo. A maioria dos drivers define esse valor como FALSE. Para obter mais informações, consulte Especificando o acesso exclusivo a objetos de dispositivo.
[in] DefaultSDDLString
Especifica uma representação de cadeia de caracteres para as configurações de segurança padrão do objeto do dispositivo. A segurança aplicada ao objeto de dispositivo é derivada dessa cadeia de caracteres, a menos que o administrador do sistema coloque uma substituição na seção do registro identificado pelo parâmetro DeviceClassGuid .
A configuração de segurança é especificada em um subconjunto de SDDL (Linguagem de Definição de Descritor de Segurança). Um conjunto de constantes predefinidas (SDDL_DEVOBJ_XXX) também é fornecido. Para obter mais informações, consulte Protegendo objetos de dispositivo.
[in, optional] DeviceClassGuid
Ponteiro para um GUID que identifica uma seção do registro que contém possíveis substituições para os parâmetros DefaultSDDLString, DeviceType, DeviceCharacteristics e Exclusive .
DeviceObject
Ponteiro para uma variável que recebe um ponteiro para a estrutura de DEVICE_OBJECT recém-criada. A estrutura de DEVICE_OBJECT é alocada do pool nãopagado.
Retornar valor
WdmlibIoCreateDeviceSecure retorna STATUS_SUCCESS com êxito ou o código de erro NTSTATUS apropriado em caso de falha. Uma lista parcial dos códigos de falha que podem ser retornados por essa função inclui:
Comentários
WdmlibIoCreateDeviceSecure cria um objeto de dispositivo nomeado, aplica as configurações de segurança especificadas e retorna um ponteiro para o objeto . O chamador é responsável por excluir o objeto quando ele não é mais necessário chamando IoDeleteDevice.
Essa rotina não faz parte do sistema operacional. Os drivers podem usar a rotina vinculando-se ao Wdmsec.lib no Microsoft Windows 2000 e versões posteriores do Windows. (A biblioteca Wdmsec.lib foi enviada pela primeira vez com as edições Microsoft Windows XP Service Pack 1 [SP1] e Windows Server 2003 do Kit de Desenvolvimento de Driver [DDK] e também é fornecida com o Kit de Driver do Windows [WDK].)
Qualquer driver que crie um objeto de dispositivo nomeado que não tenha a garantia de ter seu descritor de segurança definido pelo arquivo INF deve usar WdmlibIoCreateDeviceSecure. Para obter mais informações, consulte Criando um objeto device. O chamador é responsável por definir determinados membros do objeto de dispositivo retornado. Para obter mais informações, consulte Inicializando um objeto de dispositivo e a documentação específica do tipo de dispositivo para seu dispositivo.
Tenha cuidado para especificar os valores DeviceType e DeviceCharacteristics nos parâmetros corretos. Ambos os parâmetros usam constantes FILE_XXX definidas pelo sistema e alguns gravadores de driver especificam os valores nos parâmetros errados por engano.
O chamador é responsável por definir determinados campos no objeto de dispositivo retornado, como o campo Sinalizadores , e por inicializar a extensão do dispositivo com qualquer informação definida pelo driver. Para outras operações necessárias em novos objetos de dispositivo, consulte Inicializando um objeto de dispositivo e a documentação específica do tipo de dispositivo para seu dispositivo.
O GUID especificado pelo parâmetro DeviceClassGuid determina a classe de configuração do dispositivo para o objeto do dispositivo. (Para obter mais informações sobre classes de configuração de dispositivo, consulte Classes de instalação de dispositivo.) Os chamadores devem fornecer um valor para que os administradores do sistema possam alterar as configurações de segurança do dispositivo (por exemplo, para negar acesso a determinados usuários). Para obter mais informações, consulte Configurando propriedades do registro de objeto do dispositivo após a instalação.
Drivers não WDM especificam um novo GUID, um ainda não em uso por uma classe de configuração de dispositivo existente. Gere um novo GUID usando a ferramenta GuidGen.exe incluída no SDK do Microsoft Windows.
Os drivers de barramento WDM que lidam com dispositivos compatíveis com o modo bruto podem especificar a classe de configuração do dispositivo, mas somente se essa classe já tiver sido criada. Caso contrário, crie um novo GUID.
Os objetos de dispositivo para discos, fitas, CD-ROMs e discos de RAM recebem um VPB (Bloco de Parâmetros de Volume) inicializado para indicar que o volume nunca foi montado no dispositivo.
Se a chamada de um driver para WdmlibIoCreateDeviceSecure retornar um erro, o driver deverá liberar todos os recursos alocados para esse dispositivo.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Consulte a seção Observações. |
| Plataforma de Destino | Área de Trabalho |
| Cabeçalho | wdmsec.h (inclua Wdmsec.h) |
| Biblioteca | Wdmsec.lib |
| IRQL | PASSIVE_LEVEL |
| Regras de conformidade de DDI | AddDevice(wdm), HwStorPortProhibitedDIs(storport), IrqlIoPassive1(wdm), MiniportOnlyWdmDevice |