IStiUSD::Initialize-Methode (stiusd.h)

Die IStiUSD::Initialize Methode eines Stillbild-Minidrivers initialisiert eine Instanz des COM-Objekts, die die IStiUSD- Schnittstelle definiert.

Syntax

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

Parameter

pHelDcb

Vom Aufrufer bereitgestellter Zeiger auf die IStiDeviceControl COM Interface.

dwStiVersion

Vom Anrufer bereitgestellte STI-Versionsnummer. Dieser Wert wird durch STI_VERSION in Sti.h-definiert.

hParametersKey

Vom Aufrufer bereitgestelltes Handle für den Registrierungsschlüssel, unter dem gerätespezifische Informationen gespeichert werden sollen.

Rückgabewert

Wenn der Vorgang erfolgreich ist, sollte die Methode S_OK zurückgeben. Andernfalls sollte eine der STIERR-präfixierten Fehlercodes zurückgegeben werden, die in stierr.hdefiniert sind.

Bemerkungen

Die IStiUSD::Initialize-Methode, die von immer noch Bild-Minidrivern exportiert wird, ist die erste IStiUSD--Methode, die aufgerufen wird, nachdem ein Minidriver geladen wurde. Die Methode muss den Treiber und das Gerät initialisieren.

Die Methode sollte die empfangene IStiDeviceControl COM-Schnittstelle Zeiger speichern, und sie sollte die IStiDeviceControl::AddRef-Methode aufrufen.

Für Geräte, die mit dedizierten Ports (z. B. SCSI-Geräten) verbunden sind, erstellt die Methode in der Regel einen Lese-/Schreibpfad zum Gerät, indem sie CreateFile- aufruft (in der Dokumentation des Microsoft Windows SDK beschrieben), mithilfe eines Geräteportnamens, der durch Aufrufen von IStiDeviceControl::GetMyDevicePortNameabgerufen wird.

Für Geräte auf gemeinsam genutzten Ports (z. B. serielle Portgeräte) wird das Öffnen des Ports im IStiUSD::Initialize Methode nicht empfohlen, da der Zugriff auf andere Geräte auf dem Port gesperrt wird. Für solche Geräte ist es besser, CreateFile- innerhalb der IStiUSD::LockDevice-Methode aufzurufen.

Wenn das geöffnete Gerät einer ist, für den mehrere Aufrufe an CreateFile- nicht zulässig sind (z. B. Geräte, die mit einem seriellen Anschluss verbunden sind), ruft der Treiber in der Regel nicht CreateFile auf, es sei denn, der Aufrufer hat das Gerät für Datenübertragungen geöffnet, wie im folgenden CodeExampledargestellt.

Die IStiUSD::Initialize Methode sollte die empfangene STI-Versionsnummer überprüfen und einen Fehler zurückgeben, wenn die empfangene Version nicht mit der Version des Treibers übereinstimmt.

Im folgenden Beispiel wird ein Geräteport nur geöffnet, wenn ein Aufruf von IStiDeviceControl::GetMyDeviceOpenMode angibt, dass eine Anwendung das Gerät für Datenübertragungen geöffnet hat. Dieser Code kann für ein Gerät verwendet werden, das nicht mehrere CreateFile- Aufrufe unterstützt, z. B. ein serielles Portgerät.

Beispiele

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

Anforderungen