ISensorDriver::OnClientConnect method

The ISensorDriver::OnClientConnect method notifies the sensor driver that a client application has connected.

Syntax


HRESULT OnClientConnect(
  [in]  IWDFFile *pClientFile,
  [in]  LPWSTR   pwszSensorID
);

Parameters

pClientFile [in]

Pointer to an IWDFFile interface that represents the file object for the application requesting the connection.

pwszSensorID [in]

LPWSTR that contains the ID for the sensor to which the client application is connecting.

Return value

If the operation succeeds, this method returns S_OK. Otherwise, this method returns one of the error codes that are defined in Winerror.h.

Remarks

The sensor class extension calls this method only if the specified client application has been given permission by the user to access the driver. If the user revokes this permission, the class extension immediately calls ISensorDriver::OnClientDisconnect for the same application/sensor pair.

The class extension always calls this method before calling ISensorDriver::OnSetProperties or ISensorDriver::OnGetDataFields for a particular sensor. We recommend that you maintain a reference count of connected applications to help to anticipate when calls to these three methods are possible. If no client applications are connected, you may want to change the behavior of the driver, for example, by taking steps to reduce power consumption.

You can use the pointer value (the address pointed to) provided by pClientFile as a kind of ID to keep track of connected applications. However, you must track these IDs separately for each sensor, not for each device, because the class extension may provide the same pointer value to multiple sensors on the same device.

For more information about how to use this method, see Filtering data.

Examples

The following example code demonstrates an implementation of ISensorDriver::OnClientConnect. This function uses an ATL simple map, named Clients, to keep track of connected clients. The ClientData structure is defined as follows.


// Struct to keep track of connected client status.
struct ClientData
{
    BOOL bListening;  // Client is listening to events.
    ULONG ulInterval;  // Interval requested by client.
};

The function definition follows.


HRESULT CSensorDdi:: OnClientConnect(
        __in IWDFFile* pClientFile,
        __in LPWSTR pwszSensorID
        )
{
    if(NULL == pClientFile ||
       NULL == pwszSensorID)
    {
        return E_POINTER;
    }

    HRESULT hr = S_OK;
    BOOL bRet = FALSE;

    // This memory freed in OnClientDisconnect.
    ClientData* cd = new ClientData();
 
    if(NULL == cd)
    {
        hr = E_OUTOFMEMORY;
    }

    if(SUCCEEDED(hr))
    {
        ::ZeroMemory(cd, sizeof(ClientData));

        // Add this client to the map.
        // Use the current report interval as the default.
        bRet = Clients.Add(pClientFile, cd);
        if(bRet == FALSE)
        {
            hr = E_OUTOFMEMORY;
        }
    }

    return hr;
}

Requirements

Minimum supported client

Windows 7

Minimum supported server

None supported

Target platform

Desktop

Version

Available in Windows 7.

Header

Sensorsclassextension.h

Library

SensorsClassExtension.lib

See also

ISensorDriver::OnClientDisconnect

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft