Funzione WinBioLocateSensor (winbio.h)
Recupera il numero ID di un'unità biometrica selezionata in modo interattivo da un utente.
Sintassi
HRESULT WinBioLocateSensor(
[in] WINBIO_SESSION_HANDLE SessionHandle,
[out, optional] WINBIO_UNIT_ID *UnitId
);
Parametri
[in] SessionHandle
Valore WINBIO_SESSION_HANDLE che identifica una sessione biometrica aperta. Aprire un handle di sessione sincrono chiamando WinBioOpenSession. Aprire un handle di sessione asincrono chiamando WinBioAsyncOpenSession.
[out, optional] UnitId
Puntatore a un valore ULONG che specifica l'unità biometrica.
Valore restituito
Se la funzione ha esito positivo, restituisce S_OK. Se la funzione ha esito negativo, restituisce un valore HRESULT che indica l'errore. I valori possibili includono, ma non sono limitati a, quelli indicati nella tabella seguente. Per un elenco di codici di errore comuni, vedere Valori HRESULT comuni.
| Codice restituito | Descrizione |
|---|---|
|
L'handle di sessione non è valido. |
|
Il puntatore specificato dal parametro UnitId non può essere NULL. |
|
Impossibile completare l'operazione perché l'unità biometrica è attualmente usata per una transazione di registrazione (solo pool di sistema). |
Commenti
È possibile usare questa funzione nei sistemi con più sensori per determinare quale sensore è preferito per la registrazione dall'utente. Nessuna informazione di identificazione viene restituita da questa funzione. Viene fornito solo per indicare la selezione del sensore utente.
Le chiamate a questa funzione usando il pool di sistema verranno bloccate finché l'applicazione acquisisce lo stato attivo della finestra e l'utente ha fornito un esempio biometrico. È quindi consigliabile che l'applicazione non chiami WinBioLocateSensor finché non ha acquisito lo stato attivo. Il modo in cui si acquisisce lo stato attivo dipende dal tipo di applicazione che si scrive. Ad esempio, se si sta creando un'applicazione GUI, è possibile implementare un gestore messaggi che acquisisce un WM_ACTIVATE, WM_SETFOCUS o un altro messaggio appropriato. Se si scrive un'applicazione CUI, chiamare GetConsoleWindow per recuperare un handle nella finestra della console e passare tale handle alla funzione SetForegroundWindow per forzare la finestra della console in primo piano e assegnarla lo stato attivo. Se l'applicazione è in esecuzione in un processo scollegato e non ha una finestra o è un servizio Windows, usare WinBioAcquireFocus e WinBioReleaseFocus per controllare manualmente lo stato attivo.
Per usare WinBioLocateSensor in modo sincrono, chiamare la funzione con un handle di sessione creato chiamando WinBioOpenSession. La funzione blocca finché l'operazione non viene completata o viene rilevato un errore.
Per usare WinBioLocateSensor in modo asincrono, chiamare la funzione con un handle di sessione creato chiamando WinBioAsyncOpenSession. Il framework alloca una struttura WINBIO_ASYNC_RESULT e la usa per restituire informazioni sull'esito positivo o negativo dell'operazione. La struttura WINBIO_ASYNC_RESULT viene restituita al callback dell'applicazione o alla coda dei messaggi dell'applicazione, a seconda del valore impostato nel parametro NotificationMethod della funzione WinBioAsyncOpenSession :
- Se si sceglie di ricevere avvisi di completamento usando un callback, è necessario implementare una funzione PWINBIO_ASYNC_COMPLETION_CALLBACK e impostare il parametro NotificationMethod su WINBIO_ASYNC_NOTIFY_CALLBACK.
- Se si sceglie di ricevere avvisi di completamento usando la coda di messaggi dell'applicazione, è necessario impostare il parametro NotificationMethod su WINBIO_ASYNC_NOTIFY_MESSAGE. Il framework restituisce un puntatore WINBIO_ASYNC_RESULT al campo LPARAM del messaggio della finestra.
Windows 7: È possibile eseguire questa operazione in modo asincrono usando la funzione WinBioLocateSensorWithCallback . La funzione verifica gli argomenti di input e restituisce immediatamente. Se gli argomenti di input non sono validi, la funzione restituisce un codice di errore. In caso contrario, il framework avvia l'operazione in un altro thread. Al termine dell'operazione asincrona o si verifica un errore, il framework invia i risultati alla funzione PWINBIO_LOCATE_SENSOR_CALLBACK implementata dall'applicazione.
Esempio
La funzione seguente chiama WinBioLocateSensor per individuare un sensore biometrico installato. Collegare alla libreria statica Winbio.lib e includere i file di intestazione seguenti:
- Windows.h
- Stdio.h
- Conio.h
- Winbio.h
HRESULT LocateSensor( )
{
HRESULT hr = S_OK;
WINBIO_SESSION_HANDLE sessionHandle = NULL;
WINBIO_UNIT_ID unitId = 0;
// Connect to the system pool.
hr = WinBioOpenSession(
WINBIO_TYPE_FINGERPRINT, // Service provider
WINBIO_POOL_SYSTEM, // Pool type
WINBIO_FLAG_DEFAULT, // Configuration and access
NULL, // Array of biometric unit IDs
0, // Count of biometric unit IDs
NULL, // Database ID
&sessionHandle // [out] Session handle
);
if (FAILED(hr))
{
wprintf_s(L"\n WinBioEnumBiometricUnits failed. hr = 0x%x\n", hr);
goto e_Exit;
}
// Locate the sensor.
wprintf_s(L"\n Tap the sensor once...\n");
hr = WinBioLocateSensor( sessionHandle, &unitId);
if (FAILED(hr))
{
wprintf_s(L"\n WinBioLocateSensor failed. hr = 0x%x\n", hr);
goto e_Exit;
}
wprintf_s(L"\n Sensor located successfully. ");
wprintf_s(L"\n Unit ID = %d \n", unitId);
e_Exit:
if (sessionHandle != NULL)
{
WinBioCloseSession(sessionHandle);
sessionHandle = NULL;
}
wprintf_s(L"\n Hit any key to exit...");
_getch();
return hr;
}
Requisiti
| Client minimo supportato | Windows 7 [solo app desktop] |
| Server minimo supportato | Windows Server 2008 R2 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | winbio.h (include Winbio.h) |
| Libreria | Winbio.lib |
| DLL | Winbio.dll |