Método IStiUSD::Initialize (stiusd.h)

Um método IStiUSD::Initialize de um minidriver de imagem ainda inicializa uma instância do objeto COM que define a interface IStiUSD .

Sintaxe

HRESULT Initialize(
  PSTIDEVICECONTROL pHelDcb,
  DWORD             dwStiVersion,
  HKEY              hParametersKey
);

Parâmetros

pHelDcb

Ponteiro fornecido pelo chamador para a interface COM IStiDeviceControl.

dwStiVersion

Número de versão de STI fornecido pelo chamador. Esse valor é definido por STI_VERSION em Sti.h.

hParametersKey

Identificador fornecido pelo chamador para a chave do Registro na qual as informações específicas do dispositivo devem ser armazenadas.

Retornar valor

Se a operação for bem-sucedida, o método deverá retornar S_OK. Caso contrário, ele deverá retornar um dos códigos de erro prefixados por STIERR definidos em stierr.h.

Comentários

O método IStiUSD::Initialize , que é exportado por minidrivers de imagem ainda, é o primeiro método IStiUSD chamado depois que um minidriver é carregado. O método deve inicializar o driver e o dispositivo.

O método deve armazenar o ponteiro de interface COM IStiDeviceControl recebido e deve chamar o método IStiDeviceControl::AddRef dessa interface.

Para dispositivos conectados a portas dedicadas (como dispositivos SCSI), o método normalmente cria um caminho de leitura/gravação para o dispositivo chamando CreateFile (descrito na documentação do SDK do Microsoft Windows), usando um nome de porta do dispositivo obtido chamando IStiDeviceControl::GetMyDevicePortName.

Para dispositivos em portas compartilhadas (como dispositivos de porta serial), não é recomendável abrir a porta no método IStiUSD::Initialize , pois o acesso a outros dispositivos na porta será bloqueado. Para esses dispositivos, é melhor chamar CreateFile de dentro do método IStiUSD::LockDevice .

Se o dispositivo que está sendo aberto for aquele para o qual várias chamadas para CreateFile não são permitidas (como dispositivos conectados a uma porta serial), o driver normalmente não chama CreateFile , a menos que o chamador tenha aberto o dispositivo para transferências de dados, conforme ilustrado no CodeExample a seguir.

O método IStiUSD::Initialize deve validar o número de versão de STI recebido e retornar um erro se a versão recebida não corresponder à versão do driver.

O exemplo a seguir abre uma porta de dispositivo somente se uma chamada para IStiDeviceControl::GetMyDeviceOpenMode indicar que um aplicativo abriu o dispositivo para transferências de dados. Esse código pode ser usado para um dispositivo que não pode dar suporte a várias chamadas CreateFile , como um dispositivo de porta serial.

Exemplos

STDMETHODIMP MyUSDDevice::Initialize(
    PSTIDEVICECONTROL pDcb,
    DWORD             dwStiVersion,
    HKEY              hParametersKey)
{
    HRESULT hres = STI_OK;
    DWORD   dwMode = 0;
    if (!pDcb)
    {
        hres = STIERR_INVALID_PARAM;
    }
    else
    {
        // Store IStiDeviceControl object pointer
        m_pDcb = pDcb;
        m_pDcb->AddRef();
        // If we opened in data mode - should open device right now,
        // otherwise postpone open till lock
        m_pDcb->GetMyDeviceOpenMode(&dwMode);
        if (dwMode & STI_DEVICE_CREATE_DATA)
            hres = OpenMyPort();
    }
    return hres;
}

Requisitos

Requisito	Valor
Plataforma de Destino	Área de Trabalho
Cabeçalho	stiusd.h (inclua Stiusd.h)