IStiUSD ::Initialize, méthode (stiusd.h)

La méthode IStiUSD ::Initialize d’un minidriver d’image fixe initialise une instance de l’objet COM qui définit l’interface IStiUSD.

Syntaxe

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

Paramètres

pHelDcb

Pointeur fourni par l’appelant vers l’interface COM IStiDeviceControl.

dwStiVersion

Numéro de version STI fourni par l’appelant. Cette valeur est définie par STI_VERSION dans Sti.h.

hParametersKey

Handle fourni par l’appelant à la clé de Registre sous laquelle les informations spécifiques à l’appareil doivent être stockées.

Valeur retournée

Si l’opération réussit, la méthode doit retourner S_OK. Sinon, elle doit retourner l’un des codes d’erreur préfixés STIERR définis dans stierr.h.

Remarques

La méthode IStiUSD ::Initialize , qui est exportée par des minidrivers d’images fixes, est la première méthode IStiUSD appelée après le chargement d’un minidriver. La méthode doit initialiser le pilote et le périphérique.

La méthode doit stocker le pointeur d’interface COM IStiDeviceControl reçu, et elle doit appeler la méthode IStiDeviceControl ::AddRef de cette interface.

Pour les appareils connectés à des ports dédiés (tels que les appareils SCSI), la méthode crée généralement un chemin d’accès en lecture/écriture à l’appareil en appelant CreateFile (décrit dans la documentation Microsoft Windows SDK), à l’aide d’un nom de port d’appareil obtenu en appelant IStiDeviceControl ::GetMyDevicePortName.

Pour les appareils sur des ports partagés (par exemple, les périphériques de port série), l’ouverture du port dans la méthode IStiUSD ::Initialize n’est pas recommandée, car l’accès à d’autres appareils sur le port sera verrouillé. Pour ces appareils, il est préférable d’appeler CreateFile à partir de la méthode IStiUSD ::LockDevice .

Si l’appareil en cours d’ouverture est un appareil pour lequel plusieurs appels à CreateFile ne sont pas autorisés (par exemple, les appareils connectés à un port série), le pilote n’appelle généralement pas CreateFile , sauf si l’appelant a ouvert l’appareil pour les transferts de données, comme illustré dans le CodeExample suivant.

La méthode IStiUSD ::Initialize doit valider le numéro de version STI reçu et retourner une erreur si la version reçue ne correspond pas à la version du pilote.

L’exemple suivant ouvre un port d’appareil uniquement si un appel à IStiDeviceControl ::GetMyDeviceOpenMode indique qu’une application a ouvert l’appareil pour les transferts de données. Ce code peut être utilisé pour un appareil qui ne peut pas prendre en charge plusieurs appels CreateFile , comme un périphérique de port série.

Exemples

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

Configuration requise