Description This function stores the PIN entry via the PIN pad. From the point this function is invoked, PIN digit entries are not passed to the application. For each PIN digit, or any other active key entered, an execute notification event is sent in order to allow an application to perform the appropriate display action (i.e. when the PIN pad has no integrated display). The application is not informed of the value entered, the execute notification only informs that a key has been depressed.
Some PIN pad devices do not inform the application as each PIN digit is entered, but locally process the PIN entry based upon minimum PIN length and maximum PIN length input parameters. These PIN pad devices which provide local PIN entry management and optional display tracking may or may not notify the application of a minimum PIN length violation.
When the maximum number of PIN digits is entered, or a completion key is pressed after the minimum number of PIN digits is entered, a WFS_EXEC_COMPLETE event message is sent to the application. Once this notification is received, the output parameters are then returned to the application from this function call. The depression of the <Cancel> key is also passed to the application via the WFS_EXEC_COMPLETE event message.
If usMaxLen is zero, the service provider does not terminate the command unless the application sets ulTerminateKeys or ulTerminateFDKs. In the event that ulTerminateKeys or ulTerminateFDKs are not set and usMaxLen is zero, the command will not terminate and the application must issue a WFSCancel command.
Input Param LPWFSPINGETPIN lpGetPin;
typedef struct _wfs_pin_getpin
{
USHORT usMinLen; USHORT usMaxLen;
BOOL bAutoEnd;
CHAR cEcho;
ULONG ulActiveFDKs;
ULONG ulActiveKeys;
ULONG ulTerminateFDKs;
ULONG ulTerminateKeys;
} WFSPINGETPIN, * LPWFSPINGETPIN;
usMinLen
Specifies the minimum number of digits which must be entered for the PIN. A value of zero indicates no minimum PIN length verification.
usMaxLen
Specifies the maximum number of digits which can be entered for the PIN.
bAutoEnd
If bAutoEnd is set to true, the service provider terminates the command when the maximum number of digits are entered. Otherwise, the input is terminated by the user using one of the termination keys. When usMaxLen is reached, the service provider will disable all numeric keys. bAutoEnd is ignored when usMaxLen is set to 0.
cEcho
Specifies the replace character to be echoed on a local display for the PIN digit.
ulActiveFDKs
Specifies those FDKs which are active during the execution of the command.
ulActiveKeys
Specifies those (other) Function Keys which are active during the execution of the command.
ulTerminateFDKs
Specifies those FDKs which must terminate the execution of the command.
ulTerminateKeys
Specifies those (other) Function Keys which must terminate the execution of the command.
Output Param LPWFSPINENTRY lpEntry;
typedef struct _wfs_pin_entry
{
USHORT usDigits;
WORD wCompletion;
} WFSPINENTRY, * LPWFSPINENTRY;
usDigits
Specifies the number of PIN digits entered.
wCompletion
Specifies the reason for completion of the entry. Possible values are:
Value Meaning
WFS_PIN_COMPAUTO The command terminated automatically, because maximum PIN length was reached.
WFS_PIN_COMPENTER The ENTER Function Key was pressed.
WFS_PIN_COMPCANCEL The CANCEL Function Key was pressed.
WFS_PIN_COMPCONTINUE Input continues (this value is only used in the execute event WFS_EXEE_PIN_KEY).
WFS_PIN_COMPCLEAR The CLEAR Function Key was pressed and the previous input is cleared (this value is only used in the execute event WFS_EXEE_PIN_KEY).
WFS_PIN_COMPBACKSPACE The last input digit was cleared (this value is only used in the execute event WFS_EXEE_PIN_KEY).
WFS_PIN_COMPFDK An FDK was pressed.
WFS_PIN_COMPHELP The HELP Function Key was pressed..
WFS_PIN_COMPFK A Function Key (FK) other than ENTER, CLEAR, CANCEL, BACKSPACE, HELP was pressed.
Error Codes The following additional error codes can be generated by this command:
Value Meaning
WFS_ERR_PIN_KEYINVALID At least one of the specified function keys or FDKs is invalid.
WFS_ERR_PIN_KEYNOTSUPPORTED At least one of the specified function keys or FDKs is not supported by the service provider.
WFS_ERR_PIN_NOACTIVEKEYS There are no active function keys specified.
WFS_ERR_PIN_NOTERMINATEKEYS There are no terminate keys specified and usMaxLen is set to 0.
WFS_ERR_PIN_MINIMUMLENGTH The minimum PIN length field is invalid or greater than the maximum PIN length field.
Events The following additional events can be generated by this command:
Value Meaning
WFS_EXEE_PIN_KEY A key has been pressed at the PIN pad.
Comments None.