IStiUSD::Initialize-Methode (stiusd.h)

Artikel
02/26/2024

Die IStiUSD::Initialize-Methode eines Standbildminidrivers initialisiert eine instance des COM-Objekts, das die IStiUSD-Schnittstelle definiert.

Syntax

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

Parameter

pHelDcb

Vom Aufrufer bereitgestellter Zeiger auf die IStiDeviceControl COM-Schnittstelle.

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 einer der in stierr.h definierten Fehlercodes mit STIERR-Präfix zurückgegeben werden.

Hinweise

Die IStiUSD::Initialize-Methode , die von Standbildminidrivern 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 den empfangenen IStiDeviceControl COM-Schnittstellenzeiger speichern und die IStiDeviceControl::AddRef-Methode dieser Schnittstelle aufrufen.

Für Geräte, die mit dedizierten Ports verbunden sind (z. B. SCSI-Geräte), erstellt die Methode in der Regel einen Lese-/Schreibpfad zum Gerät, indem CreateFile aufgerufen wird (in der Microsoft Windows SDK-Dokumentation beschrieben), wobei ein Geräteportname verwendet wird, der durch aufrufen von IStiDeviceControl::GetMyDevicePortName abgerufen wird.

Für Geräte an freigegebenen Ports (z. B. Geräte mit seriellem Port) wird das Öffnen des Ports in der IStiUSD::Initialize-Methode nicht empfohlen, da der Zugriff auf andere Geräte am Port gesperrt wird. Für solche Geräte ist es besser, CreateFile aus der IStiUSD::LockDevice-Methode aufzurufen.

Wenn es sich bei dem geöffneten Gerät um ein Gerät handelt, für das mehrere Aufrufe von CreateFile nicht zulässig sind (z. B. Geräte, die mit einem seriellen Port verbunden sind), ruft der Treiber CreateFile in der Regel nicht auf, es sei denn, der Aufrufer hat das Gerät für Datenübertragungen geöffnet, wie im folgenden CodeExample veranschaulicht.

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ützen kann, z. B. ein Gerät mit seriellem Port.

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

Anforderung	Wert
Zielplattform	Desktop
Kopfzeile	stiusd.h (einschließlich Stiusd.h)

Freigeben über