Metodo IStiUSD::Initialize (stiusd.h)

Il metodo IStiUSD::Initialize di un'immagine continua dell'immagine inizializza un'istanza dell'oggetto COM che definisce l'interfaccia IStiUSD .

Sintassi

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

Parametri

pHelDcb

Puntatore fornito dal chiamante all'interfaccia COM IStiDeviceControl.

dwStiVersion

Numero di versione STI fornito dal chiamante. Questo valore è definito da STI_VERSION in Sti.h.

hParametersKey

Handle fornito dal chiamante alla chiave del Registro di sistema in cui archiviare informazioni specifiche del dispositivo.

Valore restituito

Se l'operazione ha esito positivo, il metodo deve restituire S_OK. In caso contrario, deve restituire uno dei codici di errore con prefisso STIERR definiti in stierr.h.

Commenti

Il metodo IStiUSD::Initialize , esportato da minidriver di immagini, è il primo metodo IStiUSD chiamato dopo il caricamento di un minidriver. Il metodo deve inizializzare il driver e il dispositivo.

Il metodo deve archiviare il puntatore dell'interfaccia COM IStiDeviceControl ricevuto e deve chiamare il metodo IStiDeviceControl::AddRef dell'interfaccia.

Per i dispositivi connessi a porte dedicate (ad esempio dispositivi SCSI), il metodo crea in genere un percorso di lettura/scrittura per il dispositivo chiamando CreateFile (descritto nella documentazione di Microsoft Windows SDK), usando un nome di porta del dispositivo ottenuto chiamando IStiDeviceControl::GetMyDevicePortName.

Per i dispositivi su porte condivise (ad esempio i dispositivi porta seriale), l'apertura della porta nel metodo IStiUSD::Initialize non è consigliata, perché l'accesso ad altri dispositivi sulla porta verrà bloccato. Per tali dispositivi, è preferibile chiamare CreateFile dall'interno del metodo IStiUSD::LockDevice .

Se il dispositivo aperto è uno per il quale non sono consentite più chiamate a CreateFile (ad esempio i dispositivi connessi a una porta seriale), il driver in genere non chiama CreateFile a meno che il chiamante non abbia aperto il dispositivo per i trasferimenti di dati, come illustrato nell'esempio CodeExample seguente.

Il metodo IStiUSD::Initialize deve convalidare il numero di versione sti ricevuto e restituire un errore se la versione ricevuta non corrisponde alla versione del driver.

L'esempio seguente apre una porta del dispositivo solo se una chiamata a IStiDeviceControl::GetMyDeviceOpenMode indica che un'applicazione ha aperto il dispositivo per i trasferimenti di dati. Tale codice può essere usato per un dispositivo che non può supportare più chiamate CreateFile , ad esempio un dispositivo porta seriale.

Esempio

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;
}

Requisiti

Requisito	Valore
Piattaforma di destinazione	Desktop
Intestazione	stiusd.h (include Stiusd.h)