Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
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 de driver em um parâmetro para sua rotina de
[in] DeviceExtensionSize
Especifica o número determinado pelo driver de bytes a serem alocados para o
[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 de IoCreateDevice.)
[in] DeviceType
Especifica uma das constantes de 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 INF AddReg.)
[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 do dispositivo é derivada dessa cadeia de caracteres, a menos que o administrador do sistema coloque uma substituição na seção do registro identificada 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 são fornecidos. Para obter mais informações, consulte Como proteger 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, DeviceCharacteristicse Exclusive.
Observação Você sempre deve especificar um GUID de classe personalizado. Você não deve especificar um GUID de classe existente. Se você especificar um GUID de classe existente, outros drivers que tentam especificar que o GUID de classe existente poderá falhar ao instalar ou instalar com configurações de segurança incorretas.
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.
Valor de retorno
WdmlibIoCreateDeviceSecure retorna STATUS_SUCCESS com êxito ou o código de erro NTSTATUS apropriado sobre falha. Uma lista parcial dos códigos de falha que podem ser retornados por essa função incluem:
Observações
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 Windows Driver Kit [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 de dispositivo. 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
O chamador é responsável por definir determinados campos no objeto de dispositivo retornado, como o campo Flags 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 instalação do dispositivo para o objeto do dispositivo. (Para obter mais informações sobre classes de instalaçã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 o acesso a determinados usuários). Para obter mais informações, consulte Definindo propriedades do Registro de Objeto do Dispositivo após a instalação.
Drivers não WDM especificam um novo GUID, que ainda não está 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 instalação do dispositivo, mas somente se essa classe tiver garantia de já ter sido criada. Caso contrário, crie um novo GUID.
Objetos de dispositivo para discos, fitas, CD-ROMs e discos de RAM recebem um VPB (Bloco de Parâmetros de Volume) que é 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 |
|---|---|
| de cliente com suporte mínimo | Consulte a seção Comentários. |
| da Plataforma de Destino | Desktop |
| cabeçalho | wdmsec.h (include Wdmsec.h) |
| Biblioteca | Wdmsec.lib |
| IRQL | PASSIVE_LEVEL |
| regras de conformidade de DDI | AddDevice(wdm), HwStorPortProhibitedDIs(storport), IrqlIoPassive1(wdm), MiniportOnlyWdmDevice |