Windows SideShow user models affect which user "owns" the Windows SideShow-compatible device and their interaction with that owned device. In this case, the term "own" means that you are the only user whose gadgets can send content to the device. These models allow a wide variety of devices with different user experience requirements to work with the Windows SideShow platform.

Console User Model

The console user (a person who is sitting in front of the machine and physically logged on to the console) always has control of the Windows SideShow-compatible device. The Windows SideShow platform filters out any data that is not the console user's data. This user model is well suited to devices which are physically co-located with the source computer, such as attached to a laptop, or sitting on a desk.

A remotely logged in user, such as someone using terminal server or Remote Desktop, cannot have their data appear on a Windows SideShow-compatible device that uses the console user model. However, a remote user would be able to configure which gadgets appear on their device, though none of the changes would be apparent on the device until that user becomes the current console user. A remote user cannot change any other per-user device settings for a console user model device.

Console user model devices are simpler to implement because the platform tells the driver when the user changes. Calls to ISideShowDriver::OnSetUserState can be safely ignored by these devices, because there is no need to maintain a list of available users. Instead, console user model devices should always return the well-known interactive user's security identifier (SID) when it receives calls from the ISideShowDriver::OnGetCurrentUser method. The appropriate SID can be automatically generated by using the Win32 CreateWellKnownSid method with a SID type of WinInteractiveSid. See the Windows SideShow sample driver for an example of how to do this. The String value of this SID is S-1-5-4. When the device receives a call to ISideShowDriver::OnSetCurrentUser, the device should compare the SID of the new user with the SID of the old user, and if they are not equal, wipe all metadata and content from the device. However, if the user credentials match, the device does not need to take any action. After the device has received the ISideShowDriver::OnSetCurrentUser call for the new user, the metadata and content is automatically sent by the platform to the device for the new user. For more information about SID values, see Security Identifiers.

Assigned User Model

In this user model, a device always receives the data for the assigned user, regardless of whether that user is logged on to the console or a remote session. The Windows SideShow platform filters out any data that does not come from the assigned user’s gadgets. This user model is useful for devices that may be personal devices, such as a cell phone, where they will only be associated with a single user. It is also useful for shared devices, such as remote controls and picture frames, where the current user may change at any time; in these cases, the device could show the appropriate user’s gadgets regardless of whether that user is physically logged on to the console of the computer. Note that the user must still be logged on to the computer in order to ensure his or her gadgets are running and actively providing content.

A device supporting the assigned user model will likely provide device-side UI that allows the device owner to be changed. This choice is passed back to the Windows SideShow platform, which will filter all non-owned user content to the device until the ownership changes again. Like the console user model, any user can configure which gadgets appear on the device, though none of the changes would be apparent on the device until that user becomes the owner of the device. A user who is not the owner cannot change any other per-user device settings for an assigned user model device.

The list of available users is maintained by the device by caching information from the ISideShowDriver::OnSetUserState method. This method will supply two values: the SID of the user whose state is changing and the new state of that user (AVAILABLE or UNAVAILABLE). This method will be called in response to users logging on and logging off of the PC.

When an owner change takes place on the device (typically by selecting a user from some device-side UI), the device needs to notify the Windows SideShow platform of the user change request, which will send the new user’s content and filter out all other users’ content. The device notifies the platform by posting a SIDESHOW_USER_CHANGE_REQUEST_EVENT from the driver, and passing the SID of the requested new user as the event data.

The following code illustrates how to send a user change event:

DEVICE_USER_CHANGE_EVENT_DATA* pEventData = NULL;
size_t cchUser  = 0;
cchUser = pCUPacket->m_cchStrLen;
                   
if (cchUser > 0)
{
     DWORD cbData = (DWORD)(sizeof(DEVICE_USER_CHANGE_EVENT_DATA) + (cchUser *                                                sizeof(WCHAR)));
     pEventData      = (DEVICE_USER_CHANGE_EVENT_DATA*)new BYTE[cbData];
                        
     if (NULL != pEventData)
     {
           pEventData->cbDeviceUserChangeEventData   = cbData;
                            
           //
           // Copy the string from the device packet into the
           // event data structure. Note that the string from the device
           // packet begins at the first byte proceeding the
           // structure, and that the string from the device is
           // NOT NULL terminated and must be manually terminated.
           //
           memcpy(&(pEventData->wszUser), (BYTE*)(pCUPacket + 1), sizeof(WCHAR) * cchUser);
           (&(pEventData->wszUser))[cchUser] = 0;
           
           &(pEventData->wszUser));
           hr = m_pWdfDevice->PostEvent(SIDESHOW_USER_CHANGE_REQUEST_EVENT,
                                                        WdfEventBroadcast,
                                                        (BYTE*)pEventData,
                                                        pEventData->cbDeviceUserChangeEventData);
                            
           delete[] pEventData;
      }
      else
      {
           hr = E_OUTOFMEMORY;
      }
}

In the previous example, a packet (pCUPacket) is received by the driver from the device that indicates who the requested new user of the device is by supplying the user’s SID. The driver then formulates a SIDESHOW_USER_CHANGE_REQUEST_EVENT and posts this event to the platform. When this event is successfully received, the platform will call the ISideShowDriver::OnSetCurrentUser method with the SID of the user requested by the device. After the ISideShowDriver::OnSetCurrentUser method has been called in response to the event, the device should compare the SID of the new user with the SID of the old user; if they are not equal – as mentioned earlier – wipe all metadata and content from the device. However, if the user credentials match, the device does not need to take any action. In addition, the device will now return the SID of the new user when the device receives calls of the ISideShowDriver::OnGetCurrentUser method.

It is important to note that the device should not report the SID of the selected user on the device until after it receives the ISideShowDriver::OnSetCurrentUser method in response to its user change event request. The event sent to the platform is only a user change request, and is not fully complete until ISideShowDriver::OnSetCurrentUser is called with the requested user. Until the device receives the current user’s SID from OnSetCurrentUser, the device should return the NULL SID (S-1-0-0) on calls to OnGetCurrentUser. After the device has received the ISideShowDriver::OnSetCurrentUser for the new user, metadata and content is automatically sent by the platform to the device for the new user.

Expected Behavior for User Models

User models control which user has control of a specific device. The following table shows when a particular user will have control of the device. When a user is not the current owner of the device, the user may still configure which gadgets appear on the device in the Windows SideShow Control Panel, which will take effect as soon as they become the owner of the device.