WinBioControlUnitPrivileged function

Allows the caller to perform privileged vendor-defined control operations on a biometric unit. The client must call this function to perform extended vendor operations that require elevated access rights. If no privileges are required, the client can call the WinBioControlUnit function.

Syntax


HRESULT WINAPI WinBioControlUnitPrivileged(
  _In_       WINBIO_SESSION_HANDLE SessionHandle,
  _In_       WINBIO_UNIT_ID UnitId,
  _In_       WINBIO_COMPONENT Component,
  _In_       ULONG ControlCode,
  _In_reads_bytes_(SendBufferSize)PUCHAR SendBuffer,
  _In_       SIZE_T SendBufferSize,
  _Out_writes_bytes_to_(ReceiveBufferSize,*ReceiveDataSize)PUCHAR ReceiveBuffer,
  _In_       SIZE_T ReceiveBufferSize,
  _Out_range_(<=,ReceiveBufferSize)SIZE_T *ReceiveDataSize,
  _Out_opt_  ULONG *OperationStatus
);

Parameters

SessionHandle [in]

A WINBIO_SESSION_HANDLE value that identifies an open biometric session. Open a synchronous session handle by calling WinBioOpenSession. Open an asynchronous session handle by calling WinBioAsyncOpenSession.

UnitId [in]

A WINBIO_UNIT_ID value that identifies the biometric unit. This value must correspond to the unit ID used previously in the WinBioLockUnit function.

Component [in]

A WINBIO_COMPONENT value that specifies the component within the biometric unit that should perform the operation. This can be one of the following values.

ValueMeaning
WINBIO_COMPONENT_SENSOR

Send the command to the sensor adapter.

WINBIO_COMPONENT_ENGINE

Send the command to the engine adapter.

WINBIO_COMPONENT_STORAGE

Send the command to the storage adapter.

 

ControlCode [in]

A vendor-defined code recognized by the biometric unit specified by the UnitId parameter and the adapter specified by the Component parameter.

SendBuffer

Address of the buffer that contains the control information to be sent to the adapter specified by the Component parameter. The format and content of the buffer is vendor-defined.

SendBufferSize [in]

Size, in bytes, of the buffer specified by the SendBuffer parameter.

ReceiveBuffer

Address of the buffer that receives information sent by the adapter specified by the Component parameter. The format and content of the buffer is vendor-defined.

ReceiveBufferSize [in]

Size, in bytes, of the buffer specified by the ReceiveBuffer parameter.

ReceiveDataSize

Pointer to a SIZE_T value that contains the size, in bytes, of the data written to the buffer specified by the ReceiveBuffer parameter.

OperationStatus [out, optional]

Pointer to an integer that contains a vendor-defined status code that specifies the outcome of the control operation.

Return value

If the function succeeds, it returns S_OK. If the function fails, it returns an HRESULT value that indicates the error. Possible values include, but are not limited to, those in the following table. For a list of common error codes, see Common HRESULT Values.

Return codeDescription
E_HANDLE

The session handle is not valid.

E_INVALIDARG

The value specified in the ControlCode parameter is not recognized.

E_POINTER

The SendBuffer, ReceiveBuffer, ReceiveDataSize, OperationStatus parameters cannot be NULL.

E_ACCESSDENIED

The caller does not have permission to perform the operation, or the session was not opened by using WINBIO_FLAG_MAINTENANCE.

E_INVALIDARG

The value specified in the ControlCode parameter is not recognized.

WINBIO_E_LOCK_VIOLATION

The biometric unit specified by the UnitId parameter must be locked before any control operations can be performed.

 

Remarks

Vendors who create plug-ins must decide which extended operations are privileged and which are available to all clients. To perform a privileged operation, the client application must call the WinBioControlUnitPrivileged function. The Windows Biometric Framework allows only clients that have the appropriate access rights to call this function. To perform an operation that does not require privileges, the client should call the WinBioControlUnit function.

You must call WinBioLockUnit before calling WinBioControlUnitPrivileged. The WinBioLockUnit function creates a locked region in which vendor-defined operations can be securely performed.

To call this function successfully, the session handle must have been opened by specifying WINBIO_FLAG_MAINTENANCE. Only the Administrators and Local System accounts have the necessary privileges.

To use WinBioControlUnitPrivileged synchronously, call the function with a session handle created by calling WinBioOpenSession. The function blocks until the operation completes or an error is encountered.

To use WinBioControlUnitPrivileged asynchronously, call the function with a session handle created by calling WinBioAsyncOpenSession. The framework allocates a WINBIO_ASYNC_RESULT structure and uses it to return information about operation success or failure. The WINBIO_ASYNC_RESULT structure is returned to the application callback or to the application message queue, depending on the value you set in the NotificationMethod parameter of the WinBioAsyncOpenSession function.

  • If you choose to receive completion notices by using a callback, you must implement a PWINBIO_ASYNC_COMPLETION_CALLBACK function and set the NotificationMethod parameter to WINBIO_ASYNC_NOTIFY_CALLBACK.
  • If you choose to receive completion notices by using the application message queue, you must set the NotificationMethod parameter to WINBIO_ASYNC_NOTIFY_MESSAGE. The framework returns a WINBIO_ASYNC_RESULT pointer to the LPARAM field of the window message.

To prevent memory leaks, you must call WinBioFree to release the WINBIO_ASYNC_RESULT structure after you have finished using it.

Requirements

Minimum supported client

Windows 7 [desktop apps only]

Minimum supported server

Windows Server 2008 R2 [desktop apps only]

Header

Winbio.h (include Winbio.h)

Library

Winbio.lib

DLL

Winbio.dll

See also

WinBioControlUnit
WinBioLockUnit

 

 

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.