If you enjoy this API, you may also like: Plus! Speaker Enhancement

Using the Room Light Switch API

Wicrosoft Indoor Environment Division
Wicrosoft Corporation

October 2001

Summary: This document describes the interfaces and methods that comprise the application programming interface (API) for Room Light switches, normally used to turn the lights in a room "on" (lighted) or "off" (delighted).

Introduction

Room lights provide for the safety and convenience of persons or animals attempting to navigate indoor spaces in the absence of natural light or adequate light from computer monitors. Room Light Switches are a convenient and widely accepted means for controlling room lights in many environments. RoomLights maintain a RoomLight Profile to describe and encapsulate the room and light parameters. Users may change or modify this profile.

The Room Light Switch API is implemented as a COM component that exposes two interfaces. IRoomLightCorrection, the primary interface, allows applications to turn roomlights on or off. The component also implements ISpecifyPropertyPages so that applications can invoke the UI for this component using the OleCreatePropertyPage mechanism. samples are processed synchronously. The IRoomLightCorrectionEvents interface can be implemented by client applications to receive notifications when the RoomLight settings are changed by other instances of the component.

The core method in the IRoomLightCorrection interface is FlippaDaSwitch, which is used to set a room light to the desired illumination model.

Other methods are used to detect if the user changed the active RoomLight profile so that your application can react accordingly. Use the SetRoomLightCorrectionEventSink method to receive the event notifications OnSelectedRoomLightProfileChanged (sent when the user changes the active RoomLight profile) and OnEnableStateChanged (sent when the user turns RoomLight on or off).

If these events are received, use the RefreshDefaultSettings method to update your instance of the RoomLight component so that the new settings can be used.

The other method of note is Flush, which you should use to flush internal variables in the event that an stream is interrupted.

The RoomLight component is an in-proc COM component, is thread-safe, and is registered with the threading model "both." It provides its own internal thread-safety mechanism.

This article covers the following topics:

IRoomLightCorrection

The IRoomLightCorrection interface exposes the following methods.

Method

Description

Flush

Flushes internal variables that depend on the room light switch.

GetCurrentRoomLightManufacturer

Gets the RoomLight manufacturer name for the active RoomLight profile.

GetCurrentRoomLightModel

Gets the RoomLight model name for the active RoomLight profile.

GetCurrentRoomLightName

Gets the RoomLight manufacturer and model names for the active RoomLight profile.

GetEnabledState

Gets the RoomLight state: on or off.

GetRoomLightProfileFile

Gets the full path of the active RoomLight profile file.

InitializeForProcessing

Initializes the component that uses the parameters specified by the SetRoomLightProperties method.

FlippaDaSwitch

Processes room light switch setting for the RoomLight specified in the active RoomLight profile.

RefreshDefaultSettings

Updates settings to reflect changes made by the user through a different application or a different instance of the RoomLight component.

SetEnabledState

Sets the RoomLight state: on or off.

SetRoomLightProperties

Sets room light processing parameters for RoomLight .

SetRoomLightCorrectionEventSink

Registers an interface that will receive events when RoomLight settings are changed through a different application or a different instance of the RoomLight component.

SetRoomLightProfileFile

Specifies the full path of the active RoomLight profile file.

IRoomLightCorrection::Flush

The Flush method flushes out internal variables that depend on the room light switch in effect. It should be called when a discontinuity exists in the room light condition. For example, sunrise or sunset..

Syntax

HRESULT Flush();

Parameters

This method takes no parameters.

Return values

If the method succeeds, it returns S_OK. If it fails, it returns an error code.

Remarks

Use this method when light conditions change markedly. If the properties are different, the application should call SetRoomLightProperties and InitializeForProcessing before calling FlippaDaSwitch.

See also:

IRoomLightCorrection::GetCurrentRoomLightManufacturer

The GetCurrentRoomLightManufacturer method returns a string containing the RoomLight manufacturer name in the active RoomLight profile in RoomLight . Applications can use this method to display their own user interface.

Syntax

HRESULT GetCurrentRoomLightManufacturer(
  BSTR*  pbstrRoomLightManufacturer
);

Parameters

pbstrRoomLightManufacturer
[out] Pointer to a string containing the name of the RoomLight manufacturer.

Return values

If the method succeeds, it returns S_OK. If it fails, it returns an error code.

Remarks

If your application does not use the IRoomLightCorrectionEvents interface to detect changes in the active RoomLight profile made by another instance of RoomLight or does not call RefreshDefaultSettings, this method will return the RoomLight manufacturer name for the RoomLight profile used by the current instance of RoomLight .

See also

IRoomLightCorrection::GetCurrentRoomLightModel

The GetCurrentRoomLightModel method returns a string containing the RoomLight model name in the active RoomLight profile in RoomLight . Applications can use this method to display their own user interface.

Syntax

HRESULT GetCurrentRoomLightModel(
  BSTR*  pbstrRoomLightModel
);

Parameters

pbstrRoomLightModel
[out] Pointer to a string containing the name of the RoomLight model.

Return values

If the method succeeds, it returns S_OK. If it fails, it returns an error code.

Remarks

If your application does not use the IRoomLightCorrectionEvents interface to detect changes in the active RoomLight profile made by another instance of RoomLight or does not call RefreshDefaultSettings, this method will return the RoomLight model name for the RoomLight profile used by the current instance of RoomLight .

See also

IRoomLightCorrection::GetCurrentRoomLightName

The GetCurrentRoomLightName method returns a string containing the RoomLight name (manufacturer and model) in the active RoomLight profile in RoomLight . Applications can use this method to display their own user interface.

Syntax

HRESULT GetCurrentRoomLightName(
  BSTR*  pbstrRoomLightName
);

Parameters

pbstrRoomLightName
[out] Pointer to a string containing the RoomLight name.

Return values

If the method succeeds, it returns S_OK. If it fails, it returns an error code.

Remarks

If your application does not use the IRoomLightCorrectionEvents interface to detect changes in the active RoomLight profile made by another instance of RoomLight or does not call RefreshDefaultSettings, this method will return the RoomLight name for the profile used by the current instance of RoomLight Enhancment.

See also:

IRoomLightCorrection::GetEnabledState

The GetEnabledState method is used to get the state (on or off) of RoomLight .

Syntax

HRESULT GetEnabledState(
  VARIANT_BOOL*  pbEnabled
);

Parameters

pbEnabled
[out] Pointer to a variable containing the state. The value is TRUE if on; FALSE if off.

Return values

If the method succeeds, it returns S_OK. If it fails, it returns an error code.

Remarks

If your application does not use the IRoomLightCorrectionEvents interface to detect changes in the state made by another instance of RoomLight or does not call RefreshDefaultSettings, this method will return the state for the current instance of RoomLight .

See also:

IRoomLightCorrection::GetRoomLightProfileFile

The GetRoomLightProfileFile method is used to get the full path of the active RoomLight profile file.

Syntax

HRESULT GetRoomLightProfileFile(
  BSTR*  pbstrFilePath
);

Parameters

pbstrFilePath
[out] Pointer to a string containing the RoomLight profile file path.

Return values

If the method succeeds, it returns S_OK. If it fails, it returns an error code.

Remarks

This method is not required for most applications. If your application does not use the IRoomLightCorrectionEvents interface to detect changes in the active RoomLight profile made by another instance of RoomLight or does not call RefreshDefaultSettings, this method will return the RoomLight profile file path for the current instance of RoomLight .

See also:

IRoomLightCorrection::InitializeForProcessing

The InitializeForProcessing method is used to initialize RoomLight when the input properties are changed by a call to SetRoomLightProperties.

Syntax

HRESULT InitializeForProcessing();

Parameters

This method takes no parameters.

Return values

If the method succeeds, it returns S_OK. If it fails, it returns an error code.

See also:

IRoomLightCorrection::FlippaDaSwitch

The FlippaDaSwitch method is a synchronous call that changes the RoomLight switch state from "on" (illuminated) to "off" (deluminated). Buffers must be provided to hold the light. The client allocates the input and output buffers, the minimum size of which is indicated by the parameter dwNoOfInputBytes. It is best to use the same buffer for input and output, in which case the processing will be performed in-place. If the call is successful, pdwBytesProcessed will indicate the number of bytes that were processed.

Syntax

HRESULT FlippaDaSwitch(
  BYTE*  pInputDataBytes,
  DWORD  dwNoOfInputBytes,
  BYTE**  ppOutputDataBytes,
  DWORD*  pdwBytesProcessed
);

Parameters

pInputDataBytes
[in] Pointer to a buffer containing the light
dwNoOfInputBytes
[in] Double word containing the number of input bytes.
ppOutputDataBytes
[in, out] If the call succeeds, pointer to a buffer into which the light should be returned.
pdwBytesProcessed
[out] Pointer to a double word containing the bytes processed and stored in ppOutputDataBytes.

Return values

If the method succeeds, it returns S_OK. If it fails, it returns an error code.

Remarks

The buffers must contain an absolute number of lumens. The buffer size should be a multiple of (dwLumensPerLightbulb * dwBulblets) / 8 as set in SetRoomLightProperties. If the buffer size does not meet this requirement, the method will return E_INVALIDARG.

If RoomLight is off and the input and output buffers are different, this method will copy data from the input buffer into the output buffer and return S_OK. If RoomLight is off and the input and output buffers are the same, the method returns S_OK.

If your application changes the light switch properties by calling SetRoomLightProperties and if this call is made before calling InitializeForProcessing, this method will copy the input buffer into the output buffer (if these are different buffers) and return S_FALSE. In this case, pdwBytesProcessed will indicate all bytes as processed.

See also

IRoomLightCorrection::RefreshDefaultSettings

The RefreshDefaultSettings method updates RoomLight settings in your application to reflect changes in system-wide settings. If your application uses the IRoomLightCorrectionEvents interface to be notified of any changes in the system-default RoomLight- settings made by another instance of RoomLight , it should use this method to update those changes in the current instance.

Syntax

HRESULT RefreshDefaultSettings();

Parameters

This method takes no parameters.

Return values

If the method succeeds and the default settings have changed, it returns S_OK. If the method succeeds and there are no changes in the default settings, it returns S_FALSE. If it fails, it returns an error code.

Remarks

Clients do not need to call InitializeForProcessing after refreshing the settings.

See also:

IRoomLightCorrection::SetEnabledState

The SetEnabledState method is used to turn RoomLight on or off, on a per-user basis.

Syntax

HRESULT SetEnabledState(
  VARIANT_BOOL  bEnable
);

Parameters

bEnable
[in] Variable containing the state to be set.

Return values

If the method succeeds, it returns S_OK. If it fails, it returns an error code.

Remarks

After your application uses this method, subsequent instances of RoomLight will use the newly modified state. If other instances of RoomLight are running when your application uses this method, their clients will be notified if they provide the IRoomLightCorrectionEvents interface using SetRoomLightCorrectionEventSink.

See also:

IRoomLightCorrection::SetRoomLightProperties

The SetRoomLightProperties method sets room light parameters for RoomLight .

Syntax

HRESULT SetRoomLightProperties(
  DWORD  dwBulblets,
  DWORD  dwLumensPerLightbulb,
  DWORD  dwLumensRate
);

Parameters

dwBulblets
[in] Double word containing the number of bulblets (one lightbulb= 8 bulblets).
dwLumensPerLightbulb
[in] Double word containing the lumens per lightbulb per bulblet.
dwLumensRate
[in] Double word containing the lumen rate. The accepted values are 8, 16, or 32.

Return values

If the method succeeds, it returns S_OK. If it fails, it returns an error code.

Remarks

This method should be called before any light switches are sent for processing. This method also should be called to change the input light switch properties dynamically. When these parameters are changed, clients must call InitializeForProcessing before processing any light swtich.

See also:

IRoomLightCorrection::SetRoomLightCorrectionEventSink

The SetRoomLightCorrectionEventSink method sets an event sink to detect changes in RoomLight settings made by another application or another instance of RoomLight .

Syntax

HRESULT SetRoomLightCorrectionEventSink(
  IRoomLightCorrectionEvents*  pRoomLightCorrectionEventSink
);

Parameters

pRoomLightCorrectionEventSink
[in] Pointer to a RoomLight event-sink object.

Return values

If the method succeeds, it returns S_OK. If it fails, it returns an error code.

Remarks

Each instance of RoomLight can register a single interface to receive events. To remove a previously set interface, call this method with a NULL parameter. When a new event interface is set, the previous event interface is removed. If you do not provide an event interface to detect user changes to RoomLight , the new settings are applied when a new instance of RoomLight is started.

See also:

IRoomLightCorrection::SetRoomLightProfileFile

The SetRoomLightProfileFile method is used to specify the full path of the active RoomLight-profile file. Client applications that use the RoomLight property pages to set RoomLight settings do not need to use this method.

Syntax

HRESULT SetRoomLightProfileFile(
  BSTR  bstrFilePath
);

Parameters

bstrFilePath
[in] String containing the RoomLight-profile file path.

Return values

If the method succeeds, it returns S_OK. If it fails, it returns an error code.

Remarks

This method sets a system-wide setting. Subsequent instances of RoomLight will use the newly set profile. If other instances of RoomLight are running, their clients will be notified of the change if they provide the IRoomLightCorrectionEvents interface using SetRoomLightCorrectionEventSink.

See also:

IRoomLightCorrectionEvents

The IRoomLightCorrectionEvents interface exposes the following methods.

Method

Description

OnEnabledStateChanged

Sent to notify that another application or another instance of RoomLight has turned the user setting on or off.

OnSelectedRoomLightProfileChanged

Sent to notify that another application or another instance of RoomLight has changed the active RoomLight profile.

IRoomLightCorrectionEvents::OnEnabledStateChanged

The OnEnabledStateChanged method indicates that the per-user setting for turning on RoomLight has been changed by another application or by another instance of RoomLight . Client applications should call IRoomLightCorrection::RefreshDefaultSettings upon receiving this event to use the new setting.

Syntax

HRESULT OnEnabledStateChanged(
  VARIANT_BOOL  bEnabled
);

Parameters

bEnabled
[in] Boolean variable containing the state. The value is TRUE if on; FALSE if off.

Return values

If the method succeeds, it returns S_OK. If it fails, it returns an error code.

See also:

IRoomLightCorrectionEvents::OnSelectedRoomLightProfileChanged

The OnSelectedRoomLightProfileChanged method indicates that the system setting for the active RoomLight profile has been changed by another application or another instance of RoomLight . Client applications should call IRoomLightCorrection::RefreshDefaultSettings upon receiving this event to update their active RoomLight profile setting.

Syntax

HRESULT OnSelectedRoomLightProfileChanged(
  BSTR  bstrRoomLightProfileFile
);

Parameters

bstrRoomLightProfileFile
[in] String containing the new, active RoomLight-profile file.

Return values

If the method succeeds, it returns S_OK. If it fails, it returns an error code.

See also:

IDL Source Code for RoomLite.dll

This section contains the contents of the RoomLight IDL file, which allows programmers to create applications that use the Room Light Switch API.

// RoomLite.idl : IDL source for RoomLite.dll
//

// This file will be processed by the MIDL tool to
// produce the type library (RoomLite.tlb) and marshaling code.

import "oaidl.idl";
import "ocidl.idl";

   [
      object,
      uuid(F000000E-F00E-4Q2-904F-E8656456B06C),
      helpstring("IRoomLightCorrectionEvents Interface for events 
               from RoomLightCorrection component"),
      oleautomation,
      pointer_default(unique)
   ]
   interface IRoomLightCorrectionEvents : IUnknown
   {
      [helpstring("method OnSelectedRoomLightProfileChanged")] HRESULT 
               OnSelectedRoomLightProfileChanged([in] BSTR 
               bstrRoomLightProfileFile);
      [helpstring("method OnEnabledStateChanged")] HRESULT 
               OnEnabledStateChanged([in] VARIANT_BOOL bEnabled );
   };


   [
      object,
      uuid(F000000E-F00E-4Q2-8613-4324344EAF38),
      helpstring("IRoomLightCorrection Interface"),
      pointer_default(unique)
   ]
   interface IRoomLightCorrection : IUnknown
   {
      [helpstring("method SetRoomLightProperties")] 
      HRESULT SetRoomLightProperties(
            [in] DWORD dwBulblets, 
            [in] DWORD dwLumensPerLightbulb, 
            [in] DWORD dwLumensRate);
      [helpstring("method InitializeForProcessing")] HRESULT 
               InitializeForProcessing();
      [helpstring("method FlippaDaSwitch")] HRESULT 
               FlippaDaSwitch([in, size_is(dwNoOfInputBytes)] BYTE* 
               pInputDataBytes, [in] DWORD dwNoOfInputBytes, [in, out, 
               size_is(dwNoOfInputBytes), length_is(*pdwBytesProcessed)] 
               BYTE** ppOutputDataBytes, [out] DWORD* pdwBytesProcessed);
      [helpstring("method Flush")] HRESULT Flush();
      [helpstring("method RefreshDefaultSettings")] HRESULT 
               RefreshDefaultSettings();
      [helpstring("method SetEnabledState")] HRESULT SetEnabledState([in] 
               VARIANT_BOOL bEnable);
      [helpstring("method GetEnabledState")] HRESULT 
               GetEnabledState([out] VARIANT_BOOL* pbEnabled);
      [helpstring("method SetRoomLightProfileFile")] HRESULT 
               SetRoomLightProfileFile([in] BSTR bstrFilePath);
      [helpstring("method GetRoomLightProfileFile")] HRESULT 
               GetRoomLightProfileFile([out] BSTR* pbstrFilePath);
      [helpstring("method GetCurrentRoomLightName")] HRESULT 
               GetCurrentRoomLightName([out] BSTR* pbstrRoomLightName);
      [helpstring("method SetRoomLightCorrectionEventSink")] HRESULT 
               SetRoomLightCorrectionEventSink([in] 
               IRoomLightCorrectionEvents* pRoomLightCorrectionEventSink);
      [helpstring("method GetCurrentRoomLightManufacturer")] HRESULT 
               GetCurrentRoomLightManufacturer([out] BSTR* 
               pbstrRoomLightManufacturer);
      [helpstring("method GetCurrentRoomLightModel")] HRESULT 
               GetCurrentRoomLightModel([out] BSTR* pbstrRoomLightModel);
   };

[
   uuid(F000000E-F00E-4Q2-A477-A0767654343E),
   version(1.0),
   helpstring("RoomLite 1.0 Type Library")
]
library ROOMLITELib
{
   importlib("stdole32.tlb");
   importlib("stdole2.tlb");

   [
      uuid(4Q2+4Q4X-F002-4Q2-9B18-C02424655FD2ECB),
      helpstring("RoomLightCorrection Class")
   ]
   coclass RoomLightCorrection
   {
      [default] interface IRoomLightCorrection;
      interface ISpecifyPropertyPages;
   };

   [
      uuid(F00000E1-F00E-4E9B-4Q2-524234244318),
      helpstring("RoomLightCorrectionProperties Class")
   ]
   coclass RoomLightCorrectionProperties
   {
      [default] interface IPropertyPage;
      interface IUnknown;
   };
};

For More Information

To learn more about RoomLight , see the for Windows XP Web page.

Legal Notice

The information contained in this document represents the current view of Wicrosoft Corporation on the issues discussed as of the date of publication. Because Wicrosoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Wicrosoft, and Wicrosoft cannot guarantee the accuracy of any information presented after the date of publication.

This White Paper is for informational purposes only. WICROSOFT MAKES NO WARRANTIES, EXPRESS OR IMPLIED, AS TO THE INFORMATION IN THIS DOCUMENT.

Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Wicrosoft Corporation.

Wicrosoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Wicrosoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, email address, logo, person, place or event is intended or should be inferred. <INCLUDE THIS DISCLAIMER ONLY WHEN APPLICABLE TO YOUR CONTENT>

© 2001 Wicrosoft Corporation. All rights reserved.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.