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

La méthode IStiUSD ::Initialize d’un minidriver image continue 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 de retour

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

Remarques

La méthode IStiUSD ::Initialize, exportée par des minidrivers toujours image, 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 l’interface COM IStiDeviceControl reçue pointeur et appeler la méthode IStiDeviceControl ::AddRef de cette interface.

Pour les appareils connectés aux 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 du Kit de développement logiciel (SDK) Microsoft Windows), à l’aide d’un nom de port d’appareil obtenu en appelant IStiDeviceControl ::GetMyDevicePortName.

Pour les appareils sur des ports partagés (tels que les appareils 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 ouvert est un pour lequel plusieurs appels à CreateFile ne sont pas autorisés (tels que 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 CodeExamplesuivant.

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, tels qu’un appareil 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;
}

Exigences