WlxGetOption Documentation

Environment: Visual C++

GINA's WlxGetOption function is not well documented on MSDN. I need to write GINA using smartcards, so I wanted to get information about the smartcards inserted during logon. Simply said, I want to use WlxGetOption to get some information. But what parameters have the function? When you look into the MSDN, you'll see something like:

BOOL WlxGetOption( HANDLE hWlx, DWORD Option, ULONG_PTR* Value);

where hWlx is the Winlogon handle. Option is one of these:

• WLX_OPTION_USE_CTRL_ALT_DEL
• WLX_OPTION_CONTEXT_POINTER
• WLX_OPTION_USE_SMART_CARD
• WLX_OPTION_SMART_CARD_PRESENT
• WLX_OPTION_SMART_CARD_INFO
• WLX_OPTION_DISPATCH_TABLE_SIZE

Value = current value of the option

I don't think "current value of the option" is the exact definition. There are six options; does each option has the same type of current value? After experimenting, I found the the sense of the "Value" parameter:

The "Value" type always points to DWORD.

1. When one of these {WLX_OPTION_USE_CTRL_ALT_DEL, WLX_OPTION_USE_SMART_CARD, WLX_OPTION_SMART_CARD_PRESENT} options is used, the return value is BOOLEAN:

     DWORD dwX = 0;
     g_pWlxFuncs->WlxGetOption( g_hWlx,
                                WLX_OPTION_USE_SMART_CARD,
                                &dwX))
     if (dwX)
     {
       ASSERT(dwX==1);
       LOG("User can log on using smartcard");
     }
     else
     {
       ASSERT(dwX==0);
       LOG("User cannot use smartcard");
     }
   

   I found no differences between these options {WLX_OPTION_USE_SMART_CARD, WLX_OPTION_SMART_CARD_PRESENT}. It always returns the same values. Option WLX_OPTION_USE_CTRL_ALT_DEL always returns TRUE(?).


2. When the WLX_OPTION_CONTEXT_POINTER option is used, the return value is a pointer to the GINA context. (This context pointer is the value often used as an input parameter for GINA's function, such as WlxDisplaySASNotice, WlxLoggedOutSAS, and so forth...)


3. When the WLX_OPTION_SMART_CARD_INFO option is used, the return value is a pointer to the WLX_SC_NOTIFICATION_INFO structure. This structure is defined in the newer version of WinWlx.h as:

     typedef struct _WLX_SC_NOTIFICATION_INFO {
       PWSTR   pszCard ;
       PWSTR   pszReader ;
       PWSTR   pszContainer ;
       PWSTR   pszCryptoProvider ;
     } WLX_SC_NOTIFICATION_INFO, * PWLX_SC_NOTIFICATION_INFO ;
   

   If the smartcard is not acceptable, the return value is NULL:

     dwX = 0;
     PWLX_SC_NOTIFICATION_INFO pInfo = NULL;
     g_pWlxFuncs->WlxGetOption( g_hWlx,
                                   WLX_OPTION_SMART_CARD_INFO,
                                   &dwX) 
     if (dwX==0) LOG("Smart card is not acceptable");
     else
     {
       pInfo = (PWLX_SC_NOTIFICATION_INFO)dwX;
       LOG_FORMAT1("Card = %ws",pInfo->pszCard);
       LOG_FORMAT1("Reader = %ws",pInfo->pszReader);
       LOG_FORMAT1("Container = %ws",pInfo->pszContainer);
       LOG_FORMAT1("CSP = %ws",pInfo->pszCryptoProvider);
     }
   

   The pszContainer value was allways NULL in my experiments(?).

   WlxGetOption ret
   

4. When the WLX_OPTION_DISPATCH_TABLE_SIZE option is used, the return value is a dispatch table sized in bytes.

The code was tested on Windows 2000, and dispatch version WLX_VERSION_1_3. I hope this article will save time for someone who wants to use WlxGetOption and looks for documentation about it. If you have some other experiences or suggestions, please add your comment.