Método IVdsSubSystem::CreateLun (vds.h)
[Começando com Windows 8 e Windows Server 2012, a interface COM do Serviço de Disco Virtual é substituída pela API de Gerenciamento de Armazenamento do Windows.]
O método CreateLun cria um LUN (número de unidade lógica).
Sintaxe
HRESULT CreateLun(
[in] VDS_LUN_TYPE type,
[in] ULONGLONG ullSizeInBytes,
[in] VDS_OBJECT_ID *pDriveIdArray,
[in] LONG lNumberOfDrives,
[in] LPWSTR pwszUnmaskingList,
[in] VDS_HINTS *pHints,
[out] IVdsAsync **ppAsync
);
Parâmetros
[in] type
Um VDS_LUN_TYPE valor de enumeração que especifica o tipo LUN. O novo LUN pode ser um tipo automatizado ou um tipo RAID específico, mas não ambos. Se o chamador especificar um tipo automatizado, uma ou mais dicas automatizadas deverão ser especificadas no parâmetro pHints .
O ponteiro de interface para o novo objeto LUN pode ser recuperado chamando o método IVdsAsync::Wait no ponteiro de interface retornado no parâmetro ppAsync . A estrutura VDS_ASYNC_OUTPUT retornada por Wait contém o ponteiro da interface do objeto LUN no membro cl.pLunUnk .
[in] ullSizeInBytes
O tamanho, em bytes, do novo LUN. O provedor pode arredondar o tamanho para cima ou para baixo para atender aos requisitos de alinhamento ou outras restrições. (Na maioria dos casos, o provedor arredonda para cima, garantindo que, com raras exceções, o LUN seja pelo menos tão grande quanto solicitado.)
Depois que o LUN é criado, o chamador pode determinar o tamanho real do LUN chamando o método IVdsLun::GetProperties .
[in] pDriveIdArray
Um ponteiro para uma matriz que contém um VDS_OBJECT_ID para cada uma das unidades a serem usadas para criar o LUN. Ao especificar um valor não NULL para esse parâmetro, o chamador está solicitando que o provedor use todas as unidades, na ordem fornecida, usando todas as extensões em uma unidade antes de passar para a próxima e parando quando o LUN atingir o tamanho solicitado.
Como alternativa, o chamador pode direcionar o provedor para selecionar as unidades automaticamente passando NULL nesse parâmetro e 0 em lNumberOfDrives. (Passe NULL se e somente se lNumberOfDrives for 0.)
Se o parâmetro de tipo especificar um tipo automatizado, esse parâmetro deverá ser NULL.
[in] lNumberOfDrives
O número de unidades especificadas em pDriveIdArray. Se o chamador passar 0, o provedor selecionará as unidades.
Se o parâmetro de tipo especificar um tipo automatizado, esse parâmetro deverá ser 0.
Depois que o LUN é criado, o chamador pode determinar quais unidades estão em uso chamando o método IVdsLunPlex::QueryExtents .
[in] pwszUnmaskingList
Uma lista que especifica os computadores a serem concedidos acessa o LUN. A lista é uma cadeia de caracteres delimitada por ponto e vírgula, terminada em NULL e legível por humanos.
Se o valor for "", todos os computadores que têm uma porta HBA anexada ao subsistema de armazenamento receberão acesso ao LUN. Se o valor for "", nenhum computador terá acesso ao LUN.
Se "*" ou "" for especificado, nenhum outro valor poderá ser especificado.
Para redes Fibre Channel e redes SAS (SCS) anexadas em série, cada entrada é um WWN (Nome mundial) de 64 bits de cada porta à qual o LUN é desmascarado, formatado como uma cadeia de caracteres hexadecimal (16 caracteres de comprimento), primeiro byte mais significativo. Por exemplo, um endereço WWN de 01:23:45:67:89:AB:CD:EF é representado como "0123456789ABCDEF". Para obter mais informações, consulte as especificações T10 para Fibre Channel e SAS.
Para redes iSCSI, cada entrada é um IQN (nome qualificado iSCSI) de cada iniciador no qual o LUN é desmascarado. Um LUN desmascarado para um iniciador específico é considerado associado a esse iniciador.
[in] pHints
Ponteiro para uma estrutura VDS_HINTS que especifica as dicas a serem usadas na criação do LUN. O provedor não é necessário para aplicar as dicas ao LUN. As dicas especificadas na estrutura VDS_HINTS são apenas uma solicitação para o provedor.
Depois que o LUN é criado, o chamador pode determinar as dicas que o provedor aplicou chamando o método IVdsLun::QueryHints ou o método IVdsLunPlex::QueryHints .
Se o parâmetro de tipo especificar um tipo não automatizado, esse parâmetro deverá ser NULL.
[out] ppAsync
O endereço de um ponteiro de interface IVdsAsync , que o VDS inicializa no retorno. Os chamadores devem liberar a interface. Use essa interface para cancelar, aguardar ou consultar o status da operação.
Se IVdsAsync::Wait for chamado no ponteiro de interface retornado e um valor HRESULT bem-sucedido for retornado, as interfaces retornadas na estrutura VDS_ASYNC_OUTPUT deverão ser liberadas chamando o método IUnknown::Release em cada ponteiro de interface. No entanto, se Wait retornar um valor HRESULT de falha ou se o parâmetro pHrResult de Wait receber um valor HRESULT de falha, os ponteiros de interface na estrutura VDS_ASYNC_OUTPUT serão NULL e não precisarão ser liberados. Você pode testar valores HRESULT com êxito ou falha usando as macros SUCCEEDED e FAILED definidas em Winerror.h.
Retornar valor
Esse método pode retornar valores HRESULT padrão, como E_INVALIDARG ou E_OUTOFMEMORY, e valores retornados específicos do VDS. Ele também pode retornar códigos de erro do sistema convertidos usando a macro HRESULT_FROM_WIN32 . Os erros podem se originar do próprio VDS ou do provedor de VDS subjacente que está sendo usado. Os possíveis valores retornados incluem o seguinte.
| Valor/código retornado | Descrição |
|---|---|
|
Esse valor retornado sinaliza um problema de software ou comunicação dentro de um provedor que armazena em cache informações sobre a matriz. Use o método IVdsHwProvider::Reenumerate seguido pelo método IVdsHwProvider::Refresh para restaurar o cache. |
|
O objeto de subsistema não está mais presente. |
|
O subsistema está em um estado de falha e não consegue executar a operação solicitada. |
|
Outra operação está em andamento; essa operação não pode continuar até que a operação ou as operações anteriores sejam concluídas. |
|
Pode ser retornado de qualquer método que usa uma constante VDS_OBJECT_ID . Esse valor retornado indica que o identificador não se refere a um objeto existente. |
|
Essa operação ou combinação de parâmetros não é compatível com esse provedor. |
|
Não há espaço utilizável suficiente para esta operação. |
|
Poucas unidades gratuitas estão presentes no subsistema para concluir essa operação. |
Comentários
Ao escolher valores apropriados para os parâmetros type e pHints , o chamador pode especificar os atributos do LUN totalmente, parcial ou minimamente. O provedor pode incluir automaticamente atributos não especificados, com base nas dicas automatizadas especificadas na estrutura VDS_HINTS para a qual o parâmetro pHints aponta.
Se o provedor VDS der suporte apenas a configurações de destino simples, o subsistema deverá associar automaticamente o objeto LUN recém-criado a um objeto de destino iSCSI. Consulte o valor VDS_SF_SUPPORTS_SIMPLE_TARGET_CONFIG da enumeração VDS_SUB_SYSTEM_FLAG .
A lista de WWNs e IQNs no parâmetro pwszUnmaskingList pode conter nomes duplicados. É responsabilidade do provedor validar todos os nomes na lista e remover duplicatas, se necessário.
O provedor de hardware é responsável por remover as informações de partição do LUN para que o LUN possa ser reutilizado. Se o LUN for um disco MBR, isso será feito gravando zeros no primeiro e no último 1 MB do disco. Para um disco GPT, zeros devem ser gravados no primeiro e últimos 16 KB do disco.
Há uma diferença sutil entre o E_INVALIDARG e VDS_E_NOT_SUPPORTED valores retornados. Não se espera que os provedores implementem todos os recursos que a API do VDS pode apresentar a um cliente. Por exemplo, o método CreateLun expõe a capacidade de criar muitos tipos diferentes de LUNs (por exemplo, simples, espelho, distribuídos e paridade). No entanto, os provedores não são necessários para dar suporte a todos os tipos de LUNs. Se o chamador especificar um valor para o parâmetro de tipo que não é um valor de enumeração VDS_LUN_TYPE válido, o provedor deverá retornar E_INVALIDARG. Se o chamador especificar um valor de tipo válido que o provedor não dá suporte, o provedor deverá retornar VDS_E_NOT_SUPPORTED.
Observações aos implementadores: O provedor deve retornar um ponteiro de interface IVdsAsync no parâmetro ppAsync , mesmo que a chamada para esse método não inicie uma operação assíncrona.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows Vista [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2003 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | vds.h |
| Biblioteca | Uuid.lib |