Partager via

PIBIO_STORAGE_CONTROL_UNIT_FN fonction de rappel (winbio_adapter.h)

  • Article

Appelé par l’infrastructure biométrique Windows pour effectuer une opération de contrôle définie par le fournisseur qui ne nécessite pas de privilèges élevés. Appelez la fonction StorageAdapterControlUnitPrivileged pour effectuer une opération de contrôle définie par le fournisseur qui nécessite des privilèges élevés.

Syntaxe

PIBIO_STORAGE_CONTROL_UNIT_FN PibioStorageControlUnitFn;

HRESULT PibioStorageControlUnitFn(
  [in, out] PWINBIO_PIPELINE Pipeline,
  [in]      ULONG ControlCode,
  [in]      PUCHAR SendBuffer,
  [in]      SIZE_T SendBufferSize,
  [in]      PUCHAR ReceiveBuffer,
  [in]      SIZE_T ReceiveBufferSize,
  [out]     PSIZE_T ReceiveDataSize,
  [out]     PULONG OperationStatus
)
{...}

Paramètres

[in, out] Pipeline

Pointeur vers la structure WINBIO_PIPELINE associée à l’unité biométrique effectuant l’opération.

[in] ControlCode

Valeur ULONG qui spécifie l’opération définie par le fournisseur à effectuer.

[in] SendBuffer

Pointeur vers une mémoire tampon qui contient les informations de contrôle envoyées à l’adaptateur de stockage. Le format et le contenu de la mémoire tampon sont définis par le fournisseur.

[in] SendBufferSize

Taille, en octets, de la mémoire tampon spécifiée par le paramètre SendBuffer .

[in] ReceiveBuffer

Pointeur vers la mémoire tampon qui reçoit les informations envoyées par l’adaptateur de stockage en réponse à l’opération de contrôle. Le format de la mémoire tampon est défini par le fournisseur.

[in] ReceiveBufferSize

Taille, en octets, de la mémoire tampon spécifiée par le paramètre ReceiveBuffer .

[out] ReceiveDataSize

Pointeur vers une variable qui reçoit la taille, en octets, des données écrites dans la mémoire tampon spécifiée par le paramètre ReceiveBuffer .

[out] OperationStatus

Pointeur vers une variable qui reçoit un code status défini par le fournisseur qui spécifie le résultat de l’opération de contrôle.

Valeur retournée

Si la fonction réussit, elle retourne S_OK. Si la fonction échoue, elle doit retourner l’une des valeurs HRESULT suivantes pour indiquer l’erreur.

Code de retour Description
E_POINTER
 Un argument pointeur obligatoire est NULL.
E_INVALIDARG
 La taille ou le format de la mémoire tampon spécifiée par le paramètre SendBuffer n’est pas correct, ou la valeur spécifiée dans le paramètre ControlCode n’est pas reconnue par l’adaptateur.
E_NOT_SUFFICIENT_BUFFER
 La mémoire tampon spécifiée par le paramètre ReceiveBuffer est trop petite.
WINBIO_E_CANCELED
 L'opération a été annulée.
WINBIO_E_DEVICE_FAILURE
 Il y a eu une défaillance matérielle.
WINBIO_E_INVALID_CONTROL_CODE
 La valeur spécifiée dans le paramètre ControlCode n’est pas reconnue par l’adaptateur.
Note À compter de Windows 8, utilisez uniquement E_INVALIDARG pour signaler cette condition.
 

Remarques

Votre implémentation de cette fonction doit être identique à votre implémentation de la fonction StorageAdapterControlUnitPrivileged , sauf que des privilèges élevés ne sont pas nécessaires pour effectuer les opérations spécifiées par le paramètre ControlCode . Vous êtes responsable de la définition des opérations et de la détermination de celles qui ne nécessiteront pas de privilèges élevés.

Cette fonction doit case activée la valeur du paramètre ReceiveBufferSize pour être certaine que la mémoire tampon spécifiée par le paramètre ReceiveBuffer est suffisamment grande pour contenir les données retournées.

Exemples

Le pseudo-code suivant montre une implémentation possible de cette fonction. L’exemple ne se compile pas. Vous devez l’adapter à votre objectif.

/////////////////////////////////////////////////////////////////////////////////////////
//
// StorageAdapterControlUnit
//
// Purpose:
//       Performs a vendor-defined control operation that does not require 
//       elevated privilege.
//
// Parameters:
//      Pipeline            - Pointer to a WINBIO_PIPELINE structure associated 
//                            with the biometric unit performing the operation.
//      ControlCode         - Specifies the vendor-defined operation to perform.
//      SendBuffer          - Contains the control information sent to the 
//                            storage adapter.
//      SendBufferSize      - Size, in bytes, of the buffer specified by the 
//                            SendBuffer parameter.
//      ReceiveBuffer       - Receives information returned by the storage adapter
//                            in response to the control operation.
//      ReceiveBufferSize   - Size, in bytes, of the buffer specified by the 
//                            ReceiveBuffer parameter.
//      ReceiveDataSize     - Receives the size, in bytes, of the data written to 
//                            the buffer specified by the ReceiveBuffer parameter.
//      OperationStatus     - Receives a vendor-defined status code that specifies 
//                            the outcome of the control operation.
//
//
static HRESULT
WINAPI
StorageAdapterControlUnit(
    __inout PWINBIO_PIPELINE Pipeline,
    __in ULONG ControlCode,
    __in PUCHAR SendBuffer,
    __in SIZE_T SendBufferSize,
    __in PUCHAR ReceiveBuffer,
    __in SIZE_T ReceiveBufferSize,
    __out PSIZE_T ReceiveDataSize,
    __out PULONG OperationStatus
    )
{
    HRESULT hr = S_OK;
    BOOL result = TRUE;

    // Verify that pointer arguments are not NULL.
    if (!ARGUMENT_PRESENT(Pipeline) ||
        !ARGUMENT_PRESENT(SendBuffer) ||
        !ARGUMENT_PRESENT(ReceiveBuffer) ||
        !ARGUMENT_PRESENT(ReceiveDataSize) ||
        !ARGUMENT_PRESENT(OperationStatus))
    {
        hr = E_POINTER;
        goto cleanup;
    }

    // Retrieve the context from the pipeline.
    PWINBIO_STORAGE_CONTEXT storageContext = 
           (PWINBIO_STORAGE_CONTEXT)Pipeline->StorageContext;

    // Verify the state of the pipeline.
    if (storageContext == NULL ||
        Pipeline->StorageHandle == INVALID_HANDLE_VALUE)
    {
        hr = WINBIO_E_INVALID_DEVICE_STATE;
        goto cleanup;
    }

    switch (ControlCode)
    {
    case MY_NONPRIVILEGED_CTRL_CODE_NP1:
        {
            CTRL_CODE_NP1_SEND_BUFFER *sendBuffer = (CTRL_CODE_NP1_SEND_BUFFER*)SendBuffer;

            // Verify the size of the send buffer.
            if (SendBufferSize < sizeof(CTRL_CODE_NP1_SEND_BUFFER))
            {
                hr = E_INVALIDARG;
                break;
            }

            // Perform any other checks that may be required on the buffer 
            // contents. Return E_INVALIDARG if any of the checks fail.
            if (sendBuffer->SomeField != SomeSpecialValue ||
                sendBuffer->SomeOtherField != SomeOtherSpecialValue)
            {
                hr = E_INVALIDARG;
                break;
            }

            if (ReceiveBufferSize < sizeof(CTRL_CODE_NP1_RECEIVE_BUFFER))
            {
                hr = E_NOT_SUFFICIENT_BUFFER;
                break;
            }
        }

        // Fall through and perform the control operation after the switch
        // statement. Alternatively, depending on your requirements, you can 
        // perform the control operation here.
        break;

    case MY_NONPRIVILEGED_CTRL_CODE_NP2:
        // Continue testing for other non-privileged control codes that your
        // adapter supports.
        {
            CTRL_CODE_NP2_SEND_BUFFER *sendBuffer = (CTRL_CODE_NP2_SEND_BUFFER*)SendBuffer;

            // Verify the size of the send buffer.
            if (SendBufferSize < sizeof(CTRL_CODE_NP2_SEND_BUFFER))
            {
                hr = E_INVALIDARG;
                break;
            }

            // Perform any other checks that may be required on the buffer 
            // contents. Return E_INVALIDARG if any of the checks fail.
            if (sendBuffer->SomeField != SomeSpecialValue ||
                sendBuffer->SomeOtherField != SomeOtherSpecialValue)
            {
                hr = E_INVALIDARG;
                break;
            }

            if (ReceiveBufferSize < sizeof(CTRL_CODE_NP2_RECEIVE_BUFFER))
            {
                hr = E_NOT_SUFFICIENT_BUFFER;
                break;
            }
        }
        break;

    default:
        // All unrecognized control code values should return an error.
        hr = WINBIO_E_INVALID_CONTROL_CODE;
        break;
    }
    if (FAILED(hr))
    {
        goto cleanup;
    }

    // If control code validation succeeds, perform the control operation. This
    // example assumes that your adapter has put an open handle to a storage 
    // device in the Pipeline structure. It also assumes that the driver performs
    // overlapped I/O and that a properly initialized OVERLAPPED structure is
    // contained in the storage context.
    result = DeviceIoControl(
                Pipeline->StorageHandle,
                ControlCode,
                SendBuffer,
                (DWORD)SendBufferSize,
                ReceiveBuffer,
                (DWORD)ReceiveBufferSize,
                (LPDWORD)ReceiveDataSize,
                &storageContext->Overlapped
                );
    if (result == FALSE && GetLastError() == ERROR_IO_PENDING)
    {
        SetLastError(ERROR_SUCCESS);

        result = GetOverlappedResult(
                    Pipeline->StorageHandle,
                    &storageContext->Overlapped,
                    (LPDWORD)ReceiveDataSize,
                    TRUE
                    );
    }
    *OperationStatus = GetLastError();

    if (!result)
    {
        hr = _AdapterGetHresultFromWin32(*OperationStatus);
    }

cleanup:

    return hr;
}

Configuration requise

   
Client minimal pris en charge Windows 7 [applications de bureau uniquement]
Serveur minimal pris en charge Windows Server 2008 R2 [applications de bureau uniquement]
Plateforme cible Windows
En-tête winbio_adapter.h (include Winbio_adapter.h)

Voir aussi

Fonctions de plug-in

StorageAdapterControlUnitPrivileged