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

Un minidriver de imagen fija IStiUSD::Initialize método inicializa una instancia del objeto COM que define la interfaz IStiUSD.

Sintaxis

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

Parámetros

pHelDcb

Puntero proporcionado por el autor de la llamada al interfaz COM IStiDeviceControl.

dwStiVersion

Número de versión de STI proporcionado por el autor de la llamada. Este valor se define mediante STI_VERSION en Sti.h.

hParametersKey

Identificador proporcionado por el autor de la llamada a la clave del Registro en la que se va a almacenar información específica del dispositivo.

Valor devuelto

Si la operación se realiza correctamente, el método debe devolver S_OK. De lo contrario, debe devolver uno de los códigos de error con prefijo STIERR definidos en stierr.h.

Observaciones

El método IStiUSD::Initialize, que se exporta mediante minidriveres de imágenes, es el primer método IStiUSD llamado después de cargar un minidriver. El método debe inicializar el controlador y el dispositivo.

El método debe almacenar el IStiDeviceControl COM Interface puntero y debe llamar al método IStiDeviceControl::AddRef.

En el caso de los dispositivos conectados a puertos dedicados (por ejemplo, dispositivos SCSI), el método normalmente crea una ruta de acceso de lectura y escritura al dispositivo llamando a CreateFile (que se describe en la documentación del SDK de Microsoft Windows), mediante una llamada a IStiDeviceControl::GetMyDevicePortName.

En el caso de los dispositivos en puertos compartidos (como los dispositivos de puerto serie), no se recomienda abrir el puerto en el método IStiUSD::Initialize, ya que el acceso a otros dispositivos del puerto se bloqueará. Para estos dispositivos, es mejor llamar a CreateFile desde el método IStiUSD::LockDevice.

Si el dispositivo que se abre es uno para el que no se permiten varias llamadas a CreateFile (por ejemplo, los dispositivos conectados a un puerto serie), el controlador normalmente no llama a CreateFile a menos que el autor de la llamada haya abierto el dispositivo para las transferencias de datos, como se muestra en el siguiente CodeExample.

El método IStiUSD::Initialize debe validar el número de versión de STI recibido y devolver un error si la versión recibida no coincide con la versión del controlador.

En el ejemplo siguiente se abre un puerto de dispositivo solo si una llamada a IStiDeviceControl::GetMyDeviceOpenMode indica que una aplicación ha abierto el dispositivo para las transferencias de datos. Este código puede usarse para un dispositivo que no pueda admitir varias llamadas CreateFile, como un dispositivo de puerto serie.

Ejemplos

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