Windows CE Software Developer's Kit, Auto PC Edition - Start Page

Welcome to Windows CE Platform Software Developer's Kit, Auto PC Edition

Auto PC is an in-vehicle information and entertainment system that runs the Microsoft® Windows® CE operating system. An Auto PC provides a single, integrated platform that supports entertainment and information management. Microsoft® Windows® CE for the Auto PC includes extensions that support features specific to an Auto PC, such as positioning and navigation.

This start page helps you navigate the documentation describing the Microsoft® Windows® CE Platform Software Developer's Kit (SDK), Auto PC Edition.

Introduction to the Auto PC
Introduction to the Auto PC provides an overview of the Auto PC, Windows CE for the Auto PC, and the Windows CE Platform SDK, Auto PC Edition.

Getting Started
When you create an Auto PC application, you must include certain elements. Getting Started and its subtopics discuss the required elements.

Programmer's Reference
Programmer's Reference provides information about the purpose, syntax, parameters, return values, and use of all programming elements of Windows CE for the Auto PC, such as interfaces, functions, structures, and enumerations.

Release Notes
For important changes and additions to this documentation, view the file Apcreadme.htm.


Introduction to the Auto PC

Auto PC is an in-vehicle information and entertainment system that runs the Microsoft® Windows® CE operating system. It provides a single, integrated platform that supports entertainment and information management. Microsoft® Windows® CE for the Auto PC includes extensions that support features specific to an Auto PC, such as positioning and navigation.

Windows CE has the following features:

  • The kernel supports basic services, such as process and thread handling and memory management.
  • The file system supports persistent storage of information with RAM or Compact Flash cards.
  • The Graphics, Windowing, and Events Subsystem (GWES) controls graphics and event handling.
  • Several communication interfaces support the exchange of information with other devices.

For information about the features of the Windows CE operating system, see the Microsoft Windows CE Programmer’s Guide.

Be sure to read the release notes located in the Apcreadme.htm file for important information about issues related to the use of the Microsoft® Windows® CE Platform Software Development Kit (SDK), Auto PC Edition, including the Auto PC emulator.

Note Artwork in this book are representations of an Auto PC screen. They are presented for example only, and may not represent actual product screens.


Hardware

Auto PC includes the following required hardware. Because each original equipment manufacturer (OEM) determines hardware design, device specifications vary.

  • A 60 MIPS or higher CPU
  • A faceplate and required keys
  • A color screen that is 256 x 64 x 3 pixels
  • 8 MB of ROM
  • 8 MB of RAM
  • A Compact Flash card slot
  • A CD ROM drive for data and music
  • A four or more channel preamplifier
  • A microphone
  • A serial port
  • A universal serial bus (USB) port
  • An infrared (IR) port
  • An AM/FM tuner


Faceplate

The faceplate provides direct, physical control over an Auto PC. It contains a color screen for visual output, a keypad, arrow keys, and several special purpose keys for user-input. This section discusses what you should know to program faceplate keys.

The following illustration shows an Auto PC faceplate.

The following table shows the required faceplate keys. When you design an Auto PC application, you must account for each faceplate key in your code, even if the key performs no action. You should also use the same keys for similar functions to maintain consistency with bundled applications.

Key
Description
START | Provides access to the Start menu, which contains icons that start Auto PC bundled applications. The user can press the START key repeatedly to move through the menu, then press and hold the START key to open the selected application.
ENTER | Confirms or toggles a selection, activates an application, or initiates and confirms an edit control entry, depending on the context in which the user presses it. The ENTER key accepts a selection or entry and dismisses the menu or control. Typically, pressing the ENTER key takes a user down one level within the system hierarchy.
BACK | Dismisses a dialog box or cancels an operation and moves up one level within the system hierarchy. It can also dismiss an application menu or dismiss the Start menu and return to the previously active application.
MENU | Displays and moves through a form’s Program menu. It also supports moving through the menu, if pressed repeatedly. When pressed and held, the MENU key starts the application in focus.
HELP | Activates the first level of context-sensitive help. It also supports moving through the menu if pressed repeatedly. When pressed and held, the HELP key starts the topic in focus.
UP ARROW, DOWN ARROW, LEFT ARROW, and RIGHT ARROW | Explores an Auto PC interface, selects application options, and sets edit control values. These keys enable a user to change screen focus. Together, the arrow keys are called the direction pad. A direction pad can be separate keys or an integrated one-touch control. In terms of usability, it makes no difference because each time a user presses an arrow key, the OS sends the corresponding keydown or keyup event pair to the foreground application.
POWER | Disables audio output and shifts the screen to the default clock display when an Auto PC is operating. Because memory content is retained, applications are instantly activated when an Auto PC is powered on again.
VOLUME UP and VOLUME DOWN | Controls the volume level for audio output
MUTE | Reduces the volume of the active audio source to zero. If speech feedback is active, the MUTE key stops speech feedback, and restores the system to its previous operational state.
0-9 | Enter values in an edit control, and can be used as application-specific shortcuts. The numeric keys are typically used in edit controls, radio station presets, and other limited user preference storage situations.
* Deletes in an edit control, and can be used for application-specific functions
# Inserts in an edit control; and can be used for application-specific functions

On the Start menu, the first ten applications are assigned a number key that users can press as a shortcut to start an application. The following table shows the default shortcut key assignments. The user can set which applications are preset for each number key.

Key
Assignment
1 | Radio
2 | CD Player
3 | Directions
4 | Address Book
5 | Audio
6 | Setup (Control Panel)
7 | Messages
8 | <no assignment>
9 | <no assignment>
0 | <no assignment>


Software

Windows CE for the Auto PC includes APIs adapted from Microsoft® Win32® APIs. For example, Windows CE for the Auto PC adapts the Win32 Speech API (SAPI) by adding the IAPSpeech interface. It adapts the navigation API by modifying the functions to work with COM objects.

The following table shows some of the APIs that Windows CE for the Auto PC supports.

API
Description
Address Book | Enables access to the Contacts database
Audio manager | Controls the audio system
Forms Manager | Manages forms that comprise an Auto PC application
Positioning and Navigation | Device interface for positioning, navigation, and GPS
Power Management | Supports power management
Speech (SAPI) | Controls speech and text to speech
Tuner | Supports the AM/FM tuner
WAV-in | Handles audio sources
WAV-out | Handles audio destinations
Win32 | Interface to the operating system


Development Tools

To create an application for an Auto PC, you must install the Microsoft® Visual C++® version 6.0 development system, the Microsoft® Windows NT® Workstation 4.0 operating system, the Windows CE Platform SDK for Auto PCs, and the Microsoft® Windows® CE Toolkit for Visual C++® 6.0 installed on your computer.

Microsoft Windows CE for the Auto PC does not support Microsoft Foundation Classes (MFC), Active Template Libraries (ATL), or Microsoft® Visual Basic®.


Bundled Applications

Windows CE for the Auto PC includes the following bundled applications:

  • Address Book

    Address Book records and manages contact information. It enables users to reference or access other applications.

  • Audio

    Audio adjusts audio output. It enables users to control balance, fade, bass, treble, center channel, subwoofer, surround sound, crossover filters, and equalizer settings.

  • AM/FM Tuner

    AM/FM Tuner enables the user to listen to AM and FM radio stations. It supports both manual and speech commands.

  • CD Player

    CD Player controls output and the user interface functions of the compact disc player and changer. It supports both manual and speech commands.

  • Directions

    Directions calculates routes using the current GPS location or an address as the starting point, and an address or point of interest as the destination.

  • Messages

    Messages enables the user to receive and review messages. It displays different types of wireless information, such as e-mail, news, and traffic information.


Getting Started

When you create an Auto PC application, you must include certain elements. The following sections discuss required elements: a message loop, a Forms Manager, a form, and a message sink. For information on how to program controls, see Working with Controls.


Writing an Application

The following table shows tasks involved in writing an Auto PC application. The second column indicates if a task is optional or required. After you complete the first five required tasks, you can complete the remaining tasks in any order.

Developer task
Optional
or required
Create a message loop using GetMessage and DispatchMessage to send and receive messages from application service routines. | Required
Create a Forms Manager to manage an application’s forms. | Required
Create a form to contain controls comprising the visual user interface. | Required
Add simple controls to forms, or design and code a custom control. | Required
Create a message sink to handle application messages. | Required
Implement speech for I/O. | Optional
Implement audio to access the speakers or Auto PC tuner. | Optional
Implement positioning and navigation to obtain location information and to direct a driver to a specific location. | Optional
Implement vehicle I/O to obtain diagnostic and maintenance data from a vehicle computer. | Optional
Implement infrared and wireless communications to send and retrieve data. | Optional
Create and enable visual and voice Help. | Optional
Create or configure Control Panel applications, including a clock screen. Register collections of .wav files to add soundscapes. | Optional
Use an emulator to test and debug your application. | Optional
Use CEI Builder to prepare your application files for distribution. | Required


Creating a Message Loop

The message loop sends and receives messages for your application.

To create a message loop

  • Create a WinMain function that contains a GetMessage and DispatchMessage message loop.

The following code example shows how to create a message loop.

   while (GetMessage(&msg, NULL, 0, 0))
    {
    DispatchMessage(&msg);
    }


Creating a Forms Manager

A Forms Manager is an ActiveX® control container that provides speech and keyboard navigation, input to all controls, and common services such as visual Help and application menus. A Forms Manager passes messages from one form to another and from the OS to a form.

An Auto PC application uses a Forms Manager to handle its forms, even if it uses only one form. The device context handle is derived from the form. An Auto PC application is composed of at least three COM objects:

  • A Forms Manager object controls application-wide functionality and its forms. You can only have one Forms Manager.
  • A Form object holds the controls for a screen. You can have multiple forms.
  • A Control object is placed on a form and displays information or receives user input. You can have multiple controls per form.

Create each object with CoCreateInstance and access its other interfaces through the IUnknown interface. A Forms Manager’s primary interface is IfmManage, which provides an application with methods and common services for an application and its forms. In addition, a Forms Manager exposes the following specialized interfaces:

  • IASActiveForms, which manages form focus when an application has multiple forms
  • IfmSystem, which contains system-level methods

The following illustration shows an Auto PC application architecture.

Because a Forms Manager consists of several interfaces, it performs the following tasks:

  • Displays one or more active device contexts
  • Creates and manages a single device context for all applications with activated faceplate forms
  • Manages device contexts internally rather than externally
  • Enables applications to specify the control layout for the information displayed on the faceplate while the faceplate has the input focus
  • Enables applications to dynamically interact with a control to change its appearance and internal data
  • Enables applications to receive events from active controls on a form
  • Provides tab and focus management between the controls on an active form
  • Enables you to add custom controls to an application
  • Handles speech-to-text input for controls and for navigation between controls

To create a Forms Manager

  1. Call CoCreateInstance to create an instance of a Forms Manager.
  2. Call RegisterStartedApplication to register your application with the Forms Manager.
  3. Call MoveAppToForeground to move your application to the foreground.

The following code example shows how to create a Forms Manager.

HRESULT GetFormsManager()
{
    HRESULT         hr;

    hr = CoCreateInstance(CLSID_FMMANAGE, NULL, CLSCTX_INPROC_SERVER,
        IID_FMMANAGE,
                            (PVOID *) &g_pManage);
    if (FAILED(hr)) goto LReturn;

 WCHAR wszAppName[ _MAX_PATH +1 ];

 //Use the name in the resource script with ID #1(STR_APP_SHELL_NAME)
    LoadString(g_hInst, STR_APP_SHELL_NAME, wszAppName,_MAX_PATH );

 g_bstrAppName = ::SysAllocString(wszAppName);

 if (g_bstrAppName){
 // Register the application as started with the Forms Manager.
 // Send the Forms Manager the name of the faceplate on
 // which to execute the application.
     g_pManage->RegisterStartedApplication(FC_MAINFACEPLATE,
            g_bstrAppName, 0, 0);
 }
 else {
  hr = E_OUTOFMEMORY;
 }

 hr = g_pManage->MoveAppToForeground(GetCurrentProcessId(), 0, 0);

LReturn:
 return hr;
}


Creating a Form

A form is an object you customize to create the user interface for your application. It contains a collection of controls, such as speech controls, power list boxes, audio controls, and tabber controls that display information on a screen. A form provides the following services to an Auto PC application:

  • Acts as a collection of controls
  • Dispatches messages to controls
  • Manages input focus
  • Provides methods for controls to invalidate and update themselves
  • Provides access to a device context so that a form can draw to the screen

A form is used instead of a window manager to display information on a screen. A form performs the same type of standard Microsoft® Windows® messaging tasks typically performed by HWND and message loop procedures, including automatic invalidation and message posting.

When you add a control to a form, an application must create one or more form objects to become a container for a control. An application uses the IASForm interface to manage the controls on a form.

To create a form

  1. Create the form object with CoCreateInstance.
  2. Call Init to initialize a form.
  3. Call Start to start a form.
  4. Call PutCaption to add a title to a form.
  5. Call put_Visible to make a form visible.

The following code example shows how to create a form.

HRESULT CreateMainForm(void)
{
    HRESULT hr = NOERROR;

    // Create the form.
    hr = CoCreateInstance(CLSID_ASFORM, NULL, CLSCTX_INPROC_SERVER,
        IID_ASFORM,
                            (PVOID *) &g_pForm);
    if (FAILED(hr)) return hr;

    hr = g_pForm->Init(ID_MAINFORM, NULL, g_pSink); // Initialize the
                                                    // form.
    if (FAILED(hr)) goto LReturn;

    hr = g_pManage->Start(g_pForm);                 // Start the form.
    if (FAILED(hr)) goto LReturn;

    IASControl* pControl;
    g_pForm->QueryInterface(IID_ASCONTROL,
        (PVOID*) & pControl);
    pControl->put_Caption(g_bstrAppName);          // Give the form
                                                   // a title.
    pControl->Release();

    hr = AddControls();                             // Add controls.
 if (FAILED(hr)) goto LReturn;

 // Make the form visible or there will be no display.
 hr = g_pForm->put_Visible(TRUE);

LReturn:
    if (FAILED(hr))             // There was an error. Cleanup.
        {
        g_pForm->Close();       // Close the form.
        g_pForm->Release();
        g_pForm = NULL;
        }

    return hr;
}


Creating a Message Sink

To handle messages and events, the Forms Manager delivers a control’s event and message data through a sink attached to an object when the application initializes. Many applications create an event sink as part of the initialization process. An event sink is an ActiveX object that exposes methods called by an OS to notify an application that an event has occurred. When an application thread calls DispatchMessage, the Forms Manager processes the message, and then routes the message through the appropriate application sink to the target control.

Microsoft® Windows® CE for the Auto PC contains two sink interfaces: IASEventSink and IASClassMsgSink. The IASEventSink interface delivers control commands, such as a WM_COMMAND message. The IASClassMsgSink interface delivers status messages, such as WM_ACTIVATE. A message sink must be placed on any object in a Forms Manager that requires a message. When you add a control to a form, the control inherits the form’s IASEventSink interface.

The Forms Manager first calls an application sink, then a control sink, and finally a form sink. By calling sinks in this order, the Forms Manager enables you to make controls into a subclass and override some OS default behavior. For example, if you must handle a prolonged keystroke at the application level, but you want to enable a short keystroke to pass to the control, you can process the keydown message at the application sink level.

An application implements one or more event or notification sinks to handle most messages. The following table shows the sinks that an application can implement.

Sink
Description
Primary event sink | Handles most messages. It performs the same tasks that a WndProc function performs in a Windows-based application. Most applications require a primary event sink.
Optional class message sink | Provides a way to receive messages, such as keystroke notifications, that are not sent to the primary event sink.

To create an event sink class

  1. Create a class inheriting from IASEventSink.
  2. Implement COM methods in the IUnknown interface.
  3. Create a token implementation of IDispatch. IDispatch methods are required for compilation.
  4. Implement IASEventSink::ReceiveMsg for application-specific message handling.

The following code example shows how to create an event sink class.

class CAppEventSink : public IASEventSink
{
public:

  CAppEventSink() { m_cRef = 0; }        // Constructor initializes
                                         // reference count
    ~CAppEventSink(void) {}              // Destructor does nothing

    // IUnknown implementation
    // Standard COM QueryInterface. This application supports
    // Iunknown, Idispatch, and IASEventSink.
   STDMETHODIMP QueryInterface(REFIID riid, PVOID *ppv)
      {
       if (!ppv) return E_INVALIDARG;  // Incoming pointer invalid

        // Return an interface pointer, if the requested interface is
        // implemented.
        if (riid == IID_ASEVENTSINK) *ppv = (PVOID) (IASEventSink *)
            this;
        else if (riid == IID_IUnknown) *ppv = (PVOID) (IUnknown *) this;
        else if (riid == IID_IDispatch) *ppv = (PVOID) (IDispatch *)
            this;
        else return E_NOINTERFACE;

        AddRef(); //Add to reference count.

        return NOERROR;
     }

    // Increment the object reference count.
    STDMETHODIMP_(ULONG) AddRef(void)
    {
     InterlockedIncrement(&m_cRef);
     return m_cRef;
    }

   // Decrease reference count. Delete this object, if necessary.
   STDMETHODIMP_(ULONG) Release(void)
   {
    if (InterlockedDecrement(&m_cRef) > 0)
    return m_cRef;

    delete this;
    return 0;
   }

 // IASEventSink
 // This method is invoked when an event is fired.
 // In this case, the application exits when it receives
 // the ID_EXIT command.
 STDMETHODIMP ReceiveMsg(long uMsg, long wParam, long lParam)
 {
     if(uMsg != WM_COMMAND) return S_FALSE; // Only WM_COMMAND
           // messages are processed.

  switch(HIWORD(lParam))
  {
   case ID_EXIT:
    PostThreadMessage(g_idThread, WM_QUIT, 0, 0);// Send the quit
                                                 // message to this
                                                 // application
                                                 // thread.
break;

   default:
    break;
  }
  return S_FALSE;
 }

 // IDispatch token implementation. All functions return E_NOTIMPL.
 STDMETHODIMP GetTypeInfoCount(UINT *pctInfo)
  { return E_NOTIMPL; }

 STDMETHODIMP GetTypeInfo(UINT itinfo, LCID lcid, ITypeInfo
    **pptinfo)
  { return E_NOTIMPL; }

 STDMETHODIMP GetIDsOfNames(REFIID riid, OLECHAR **rgszNames, UINT
       cNames, LCID lcid, DISPID *rgdispids)
  { return E_NOTIMPL; }

 STDMETHODIMP Invoke(DISPID dispid, REFIID riid, LCID lcid, WORD
      wFlags, DISPPARAMS *pdispparams,
      VARIANT *pVarResult, EXCEPINFO *pei, UINT
      *puArgErr)
  { return E_NOTIMPL; }

protected:
    long  m_cRef; // This object's reference count
};

To create an event sink object

  1. Use the new operator to create an event sink object.
  2. Call QueryInterface to get an interface.

The following code example shows how to create an event sink object.

HRESULT CreateEventSink(void)
{
    HRESULT hr;
    CAppEventSink *pSink;

    pSink = new CAppEventSink();  // Create an event sink object.
    if (!pSink) return E_OUTOFMEMORY;

    // Get an interface to keep
    hr = pSink->QueryInterface(IID_ASEVENTSINK, (PVOID *) &g_pSink);
    if (FAILED(hr)) delete pSink;

    return hr;
}


User Interface Design

An Auto PC interacts with a user through speech commands and auditory feedback, as well as key presses and images on the faceplate. Speech is the preferred interface because it enables a user to focus on driving. You must provide for both kinds of input and output.

An Auto PC visual interface is based on a form. A form is composed of a title bar and the application display area. The title bar provides limited user information concerning the active application and its function. The application display area contains controls that provide features such as lists, edit controls, and message text.

When you design an Auto PC application, follow these guidelines:

  • Design simple and non-distracting interfaces.

    If a task requires focused attention, disable the task while the vehicle is in motion.

  • Design graphics and use text that are easily visible at a glance.

    Consider the angle and distance of the driver in relation to the device.

  • Combine color and shape to communicate information.

    Do not use color as the only means of communication because color perception varies.

  • Be sure that your design works in the range of light and audio levels.
  • Test the application in actual driving conditions to ensure it does not distract the driver.


System Services

This chapter discusses two system services included in Microsoft® Windows® CE for the Auto PC: a critical process monitor and power management. Both services help ensure that an Auto PC is reliable and stable. You should only add a critical process monitor to your application if your application qualifies as a critical process.


Adding a Critical Process Monitor

A critical process monitor is a system service implemented as software, firmware, and hardware that keeps critical processes running at all times. If a critical process stops running, an Auto PC ceases to function fully. A critical process must regularly notify the critical process monitor that the process is running properly. If a process is not running properly, the OS can restart the improperly running process.

In addition to monitoring individual processes, a critical process monitor notifies a hardware watchdog timer at least once every four seconds to demonstrate that an Auto PC is still active. If the notification fails to occur, the hardware forces an Auto PC to reboot.

The following illustration shows the relationship between applications and the components of the critical process monitor.

You call critical process monitor functions to register your application with a critical process monitor and to regularly notify that critical process monitor. You can provide a callback function that the critical process monitor can call to clean up after your application, if the critical process monitor needs to terminate your application. When your application no longer qualifies as a critical process, you can also call a function to notify the critical process monitor of this change.

To register an application as a critical process

  1. Call GetCurrentProcessID to obtain the process identifer.
  2. Determine how many milliseconds should occur between each signal.

    If your application does not notify the critical process monitor within this interval, the critical process monitor considers your application to be an improperly running process.

  3. Determine a callback function to close your application, if your application must be terminated.
  4. Call CPMRegister to pass the parameters that you determined in the previous steps.

The following code example shows how to register an application as a critical process.

dwProcessId = GetCurrentProcessID ();

if (!CPMRegister (dwProcessId, 1000, CPM_RELAUNCH, szAppName, pCallback,
    CPM_RELAUNCH_FAIL_OK))
{
// If an error occurs, handle it here.
}

To create a notification loop

  1. Use a while loop statement to construct a notification loop.
  2. Specify the time between notifications by calling Sleep.
  3. Include code that determines if the process continues to run properly.
  4. Call CPMNotify with the process identifier to let the critical process monitor know that the process is still running properly.

The following code example shows how to create a notification loop.

while (TRUE)
{
Sleep(500);
// You must provide code that determines if the application
// continues to function properly.
CPMNotify (dwProcessId);
}

To create a callback function

  1. Create an application-defined callback function. CPMCallback shows the necessary parameters and is a placeholder for the application-defined function name. You may use any name that you prefer for your callback function.
  2. Include in the callback function, code to save open data files and save the status of the running application so that the application can be restarted in its current state.
  3. Be sure that you pass the callback function as a parameter when you invoke CPMRegister.

The following code example shows how to create a callback function. The name of the function is pCallback, rather than CPMCallback. The two parameters are specified in CPMCallback and the function is called with CPM_CLEANUP.

Void pCallback (DWORD dwCmd, DWORD dwCmdInfo)
{
ASSERT (dwCmd == CPM_CLEANUP);
// You must provide code to save open data files, and you
// must save the status of the running application.
}

To notify the critical process monitor that a process is no longer critical, call CPMUnRegister with the same process identifier that you used to register the process.


Managing Power

Managing power on an Auto PC is complex, due to several factors:

  • Because an Auto PC continually draws current from the vehicle battery, the battery may discharge if the vehicle is unused for an extended time.
  • Voltage normally drops when a vehicle starts.
  • A vehicle battery may fail or be disconnected.

To manage power successfully under these conditions, an Auto PC uses two power sources: the vehicle battery and a backup battery. The vehicle battery operates an Auto PC on a regular basis. A backup battery provides enough power for an Auto PC to shift to a power off state and to maintain the contents of dynamic RAM (DRAM) in that state. A backup battery is not intended to operate an Auto PC when the vehicle battery is in a low power state, and can only support the normal state of an Auto PC for a short period of time while the backup battery shifts an Auto PC to a power off state.


Monitoring Battery Status

Windows CE for the Auto PC monitors battery status and notifies a user if power drops below a critical level. It does not notify applications of battery status. An application must poll the OS for battery status by calling functions in the power management API. An original equipment manufacturer (OEM) determines what battery information is supplied to the polling application. Generally, the following information is available:

  • Alternating current (AC) line status
  • Battery status
  • Battery life remaining
  • Lifetime of the battery

The following list shows the battery status functions included in the power management API.

BatteryDrvrGetStatus
Returns the vehicle status and the backup batteries in a BATTERY_STATUS structure.
BatteryDrvrGetLevels
Returns the number of levels used by the BatteryFlag and BackupBatteryFlag members of the BATTERY_STATUS structure. The number of levels is determined by the OEM. The levels range from fully charged to fully discharged.
BatteryDrvrSupportsChangeNotification
Returns a value that indicates if the hardware can detect that the batteries have been changed.


Working with Controls

Microsoft® Windows® CE for the Auto PC supports a set of standard ActiveX® controls for use by application developers. These controls provide basic user interface (UI) elements from which you can develop forms. The controls are displayed in an Auto PC form and managed by the Forms Manager.

Windows CE for the Auto PC has UI elements developed specifically for the automobile environment. If none of these standard controls are sufficient, you can define custom controls by adhering to guidelines provided in the following sections.


Auto PC Standard Controls

Auto PC standard controls are the fundamental elements of the UI. The following table shows the standard controls and interfaces.

Control
Interface
Description
Canvas | IASCanvas | Enables you to draw an application-specific graphic on a control
Clock | IASClock | Displays a clock
Cross hairs | IASCrossHairs | Enables a user to set two-dimensional values
Edit | IASEditBox | Enables text editing
HTML | IASHTMLControl | Displays HTML text
Image menu | IASImageMenu | Manages a menu that uses images, rather than text strings, to display commands
Label | IASLabel | Displays static text
Memory slider | IASMemorySlider | Displays memory allocation data
Navigational Arrows | IASUserNavArrows | Indicates when the UP, DOWN, LEFT, RIGHT, or ENTER faceplate keys are enabled
Play list | IASPlayList | Sets and displays the current play list for a compact disc (CD)
Power list box | IASPowerListBox | Displays lists when used in combination with a spin box control and an edit control
Progress | IASProgressBar | Displays the progress of a process
Shell menu | IASShellMenu | Manages a shell menu object
Slider | IASSlider | Enables a user to set one-dimensional values
Spin box | IASCharSpinner | Cycles through available selections, such as letters, numbers, or months
Tabber | IASTabber | Selects a tabbed position in a list
Visual volume indicator | IASVVI | Enables selection of values, such as volume

The following sections provide examples of how standard controls are used in the applications bundled with Windows CE for the Auto PC.


Canvas Control

A canvas control enables you to send application-specific text or graphics to a screen. The IASCanvas interface provides the GetDC method to obtain a handle to a device context that enables you to create a bitmap and send it to the screen by calling Commit.

Equalizer settings are represented as a solid line that increments or decrements according to individual channel settings. It is drawn on a bitmap and sent to a canvas control. The following illustration shows a canvas control used to choose equalizer settings.


Cross Hairs Control

A cross hairs control enables two-dimensional settings. The IASCrossHairs interface implements methods, such as get_XPlus, get_XMinus, put_XPlus, and put_Xminus to retrieve and set x and y values.

The following illustration shows a cross hairs control used to adjust balance and fade settings.


Edit Control

When coupled with a spin box control, an edit control enables a user to edit text. The IASEditBox interface extends the IASCharSpinner interface and provides methods for managing an edit control.

The following illustration shows an edit control used to edit a name in the Address Book contacts database.


HTML Control

An HTML control enables a user to view content that does not fit on a single screen, such as an e-mail message, a news report, or a traffic report. The IASHTMLControl interface implements methods to display HTML text and handle scrolling.

The following illustration shows an HTML control used to display an e-mail message.

An Auto PC HTML control supports the following HTML tags:

<A> | <CODE> | <IMG> | <PLAINTEXT> | <TH>
<ADDRESS> | <DD> | <ISINDEX> | <PRE> | <TITLE>
<B> | <DFN> | <KBD> | <S> | <TR>
<BASE> | <DIR> | <LI> | <SAMP> | <TT>
<BASEFONT> | <DIV> | <LISTING> | <SELECT> | <U>
<BGSOUND> | <DL> | <MENU> | <SMALL> | <UL>
<BIG> | <DT> | <MAP> | <STRIKE> | <VAR>
<BLOCKQUOTE> | <EM> | <META> | <STRONG> | <WBR>
<BODY> | <FONT> | <NEXTID> | <SUB> | <XMP>
<BR> | <Hn> | <NOBR> | <SUP> |
<CAPTION> | <HEAD> | <OL> | <TABLE>
<CENTER> | <HR> | <OPTION> | <TD>
<CITE> | <HTML> | <P> | <TEXTAREA>


Label Control

A label control displays static text or graphics. This control does not support user input. The IASLabel interface provides methods to position text and graphics, such as put_CaptionAlign and put_ImageAlignH.

The following illustration shows a label control used to display the tuner frequency in text.


Memory Slider Control

A memory slider control enables the user to adjust memory allocation. It may be interactive or for display only. The IASMemeorySlider interface has two methods, put_RamUsed and put_StoreUsed, that set the values for memory usage.

The following illustration shows a memory slider control used to adjust memory allocation.


Navigational Arrows Control

A navigational arrows control indicates when UP, DOWN, LEFT, RIGHT, or ENTER keys are enabled. A navigational arrows control is placed on the right side of a form for consistency with other Auto PC applications. You can program the control using the IASUserNavArrows interface. However, because the control is used on many forms, the get_NavArrows method is also included in the IASForm interface.

The following illustration shows a navigational arrows control used to show which keys are active on this form.


Play List Control

The play list control sets and displays the current track on the CD player. The IASPlayList interface provides methods, such as get_NumTracks and get_CurrentTrack, to obtain information about the current CD player settings. It also provides methods, such as put_CurrentTrack and put_NumTracks, to set CD player options.

The following illustration shows a play list control used to display and set the playlist for the CD player.


Power List Box Control

A power list box is used to display menus that support the normal static text of a standard list box, plus interact with other controls, such as edit boxes and spin box controls. The IASPowerListBox interface implements the CreateItem method, which enables you to include other controls by setting one of the following item values:

  • ASFC_PWRLB_TYPE_COMMAND
  • ASFC_PWRLB_TYPE_EDIT
  • ASFC_PWRLB_TYPE_STRINGSPINNER
  • ASFC_PWRLB_TYPE_INTSPINNER

The following code example shows how to create a power list box that is combined with a menu control.

CoCreateInstance(CLSID_POWERMENU, NULL,
                CLSCTX_INPROC_SERVER, IID_ASPOWERLISTBOX,
                (PVOID *) &pPLB);

The following illustration shows a power list box control used to display and set CD Player options.


Slider Control

A slider control is used to show the progress of a process. Progress is represented by a series of bars. Each bar is a slider control. A slider control may be interactive or display only. To program a slider control, use the IASSlider interface, which contains methods, such as get_Incr and put_Incr, to specify the value of the slider increments.

The following illustration shows a slider control used to set frequency levels in the graphic equalizer.


Tabber Control

A tabber control enables a user to tab left or right and to choose a position in a list. It displays as a single row of tabs.

A tabber control is used to manipulate other controls. For example, in the application, Address Book, a tabber control displays letters of the alphabet on tabs. The IASTabber interface contains methods to manage this control.

The following illustration shows a tabber control used to select entries for a letter in an alphabetical list.


Visual Volume Indicator Control

The visual volume indicator control enables the selection of a value, such as volume, bass, or treble. This control produces a graph of positive or negative values relative to a known reference point. The IASVVI interface extends the IASProgressBar interface.

The following illustration shows a visual volume indicator control used to graphically display volume level.


Adding Standard Controls

You can add a standard control to a form in two ways: using a resource file, or creating an instance of a control with CoCreateInstance. With resource files, constraint-based layout is supported. Constraint-based layout enables you to program a UI that is more flexible than a layout programmed using CoCreateInstance. To use constraint-based layout, define the control in a resource file, then load the resource file.

Auto PC standard controls adhere to the ActiveX automation model and can be used by any ActiveX client. However, conventional ActiveX in-place activation and embedding are not supported by Windows CE for the Auto PC.


Using Constraint-Based Layout

A constraint is the relationship between a control and its parent form or its sibling controls. When you define a control using constraints, you avoid reprogramming the UI to accommodate differences in faceplate sizes. Additionally, when you specify a constraint for a control, the layout engine determines the control geometry, which reduces the need to change values and recompile.

Each control on a form has a position and a size. With constraint-based layout, you specify the size of a control, then position one or more of its edges in relation to the parent form or another control.

When you include a title bar, the top of the form is directly under the title bar. If you do not specify enough constraints to determine each edge , the natural size of the control is used. The natural size of a control is the size necessary to display its contents. For example, the natural width of a label control is the width required to display its caption fully.

To specify a constraint

  1. Use the BEGIN..END constructs supported by the DIALOGEX resource type to specify the constraints.
  2. Create a resource file that defines the form.
  3. After you have created the resource file, call the LoadFormResource function to load the resource.

    Use the hInstance cast to an OLE handle and the identifier of the main form.

The following code example shows how to define a label control that fills a form.

IDF_MAIN DIALOGEX DISCARDABLE 0,0,0,0 //Full display
CAPTION “My Form”
STYLE WS_VISIBLE
BEGIN
    // The position and dimensions are left as 0 because they
    // will be specified by constraints.
    CONTROL “Hello”, IDC_CTRL, “APC_Label”, ASFC_ALIGN_LEFT, 0,0,0,0
    BEGIN
        // These are the constraints.
        FA_TOP_OF_FORM,        // Attach the top edge of the control to the
                            // top edge of the form.
        FA_LEFT_OF_FORM        // Attach the left edge of the control to
                            // the left edge of the form.
        FA_RIGHT_OF_FORM        // Attach the right edge of the control to
                            // the right edge of the form.
        FA_BOTTOM_OF_FORM    // Attach the bottom edge of the control
                            // to the bottom edge of the form.
    END
END

The following code example shows a meal order application that uses constraint-based resource scripts. It is part of a complete sample application, FormRC.dsp, is included in the SDK. This resource script defines a dinner order form with a navigational arrows control on the right and a menu control implemented as a power list box. The power list box uses a spin box control to display food selections.

//////
//
// Forms
//
ID_MAINFORM DIALOGEX DISCARDABLE  0, 0, 0, 0
STYLE  WS_VISIBLE
CAPTION "Dinner Order"
// Attaches a navigational arrows control to the right side of the form
// The control is centered vertically and has a five-pixel offset
// on the right and left sides.
BEGIN
    CONTROL         "Nav Arrows", IDC_NAVARROWS, "APC_NavArrows",
                    WS_VISIBLE, 0, 0, 0, 0
    BEGIN
        FA_VERTICAL_CENTER, FA_RIGHT_OF_FORM,
        FA_RIGHT_OFFSET, -5, FA_LEFT_OFFSET, -5
    END

// Defines the power list box
    CONTROL         "Menu", IDC_LIST,"APC_PwrListBox", WS_VISIBLE,
                    0,0,0,0
    BEGIN
        FA_TOP_OF_FORM,
        FA_LEFT_OF_FORM,
// Aligns the right side of the power list box control to the left
//side of the navigational arrows control
        FA_RIGHT_TO_LEFT_OF_CONTROL, IDC_NAVARROWS
        FA_BOTTOM_OF_FORM
    END
END

The following code example shows how to call LoadFormResource to load a resource.

hr = g_pManage->LoadFormResource((OLE_HANDLE)g_hInst,
        ID_MAINFORM,             // Identifier for form in
                                 // RC file
        (IDispatch**)&g_pForm,   // Form
        (IASEventSink*)g_pSink); // Sink
    if(FAILED(hr)) goto LReturn;


Creating an Instance of a Control

You can add a standard control by creating an instance of a control using CoCreateInstance.

To add a standard control using CoCreateInstance

  1. Create an instance of a control with CoCreateInstance, and get a pointer to IASControl.

    Because Windows CE for the Auto PC supports only InProc servers, the dwClsContext parameter of CoCreateInstance must be CLSCTX_INPROC_SERVER.

    The following code example shows how to create a power list box control.

    hr = CoCreateInstance(CLSID_ASPOWERLISTBOX, NULL,
                      CLSCTX_INPROC_SERVER, IID_ASPOWERLISTBOX,
                      (PVOID *) &pPLB);
if (FAILED(hr))    goto LReturn;
  2. Use the IASControl property methods to configure such parameters as color, size, and position.

    The following code example shows how to size and align an IASControl control.

    pPLB->SetBounds(0,18,225,45);
pPLB->put_Alignment(ASFC_ALIGN_CENTER);

    This code example uses an IASControl method, SetBounds, to specify the dimensions of the control in relation to its form. The values passed to SetBounds describe a control whose x-coordinate begins at the left edge of the form and whose y-coordinate begins 18 pixels from the top of the form. The control is 225 x 45 pixels. To specify that the power list box should be centered, the code example uses put_Alignment, which is a method in the IASPowerListBox interface.

  3. Use the form’s IASControl::put_ClassMsgSink, with the sink object’s pointer as a parameter, to assign a class message sink to the form.

    When an action occurs, such as a keystroke or focus change, the form notifies the active control by calling one of several messages, such as IASClassMsgSink::HandleGotFocus or IASClassMsgSink::HandleKeyPress. These notifications are handled by the control, and are not passed to the application. If your application needs to handle such actions, you must implement a class message sink. To assign a class message sink to a form, use IASControl::put_ClassMsgSink.

    The following code example shows how to add a class message sink.

    hr = m_pForm->put_ClassMsgSink((IASClassMsgSink *)this);
  4. Add the standard control to the form with IASForm::Add.

    The following code example shows how to use the Add method.

    g_pForm->Add(pPLB, IDC_PLB);


Designing a Custom Control

A custom control must adhere to the ActiveX automation model; however, conventional ActiveX in-place activation and embedding are not supported by Windows CE for the Auto PC.

When you create a custom ActiveX control, it must meet the following requirements:

  • Run on a form rather than a window

    An Auto PC uses a form instead of a window to display information. There are no HWND data types, and the windowing facilities of the User32.dll are not used. For example, obtain a handle to a device context from a form rather than from a window.

  • Implement a dual interface

    When an interface is implemented as a dual interface, the methods in that interface can be invoked using IDispatch::Invoke or direct vtable calls. For an object created with Visual Basic, using IDispatch::Invoke enables access the object methods. However, if an object is created with C or C++, vtables are typically used.

  • Implement the IClassFactory interface
  • Implement the IASControl interface

    IASControl contains methods that enable an application to specify basic properties, such as size, placement, or color, as well as methods that the form control uses.

  • Be aware of IASClassMsgSink and IASEventSink

    A control may be passed a pointer to these interfaces.

  • Implement the control as a self-registering InProc server

    A control must be designed to register itself as an in-process server when initialized.

You can develop your own control interfaces. These interfaces must follow the control guidelines, and must be speech-enabled. Because most existing ActiveX controls do not meet these requirements, you must custom-create many controls.


Initializing Controls

Once you have created a custom control, your application must add the control to a form with IASForm::Add. After a control is added, the form initializes the control by invoking the IASControl::Init method. This method provides the control with the following data:

  • The custom control identifier
  • A pointer to the form’s IDispatch interface

    The control can obtain this pointer by calling QueryInterface on the form’s IASForm interface.

  • A pointer to the form’s default event sink

    This pointer is NULL if the form has not implemented an event sink.

The form can also set one or more of the control properties with the appropriate IASControl::put_* method. Methods commonly invoked include: IASControl::put_Visible and IASControl::SetBounds. These methods can be invoked later.

Controls should not start processing until their form invokes IASControl::Start. To verify if a control has been started, invoke the IASControl::IsStarted method. To shut the control down, a form invokes the control’s IASControl::Close method. When this occurs, a control should take the following actions:

  1. Stop processing
  2. Release any resources
  3. Release any reference counts that it has on other objects

A control should not release itself until all external reference counts on it have been released.


Setting Properties

Auto PC standard controls support properties that can be set when the control is initialized or at any time during its existence. A number of commonly used properties have been defined as part of the IASControl interface. Each standard property has associated get_ and put_ methods: IASControl::get_<property> and IASControl::put_<property>. The exceptions are HasUI, ID, and TabStop, which are read-only and have no put_* method.

A control must expose IASControl::get_* and IASControl::put_* methods for all standard properties. However, controls are required to fully implement only the five standard properties: CLSID, Enable, HasUI, ID, Parent, and Visible. Only IASControl::get_* and IASControl::put_* methods must provide substantive responses. The remaining methods can return E_NOTIMPL.


Receiving the Focus

Only one control can have the focus at a time. Focus changes in response to such events as a user pressing a key or speaking a command. The form is responsible for managing which control has focus. To receive the focus, a control must meet the following criteria:

  • The Visible property must be set to TRUE
  • The Enable property must be set to TRUE
  • The TabStop property must be set to TRUE

When a control receives the input focus, its form invokes IASControl::GotFocus. When a control loses focus, the form invokes IASControl::LostFocus.

A control can determine which control currently has focus by invoking its form’s IASForm::GetFocus method. It can request the focus by invoking its form’s IASForm::SetFocus method.


Receiving Messages

A control can receive messages from a variety of sources. A form sends a message to a control by invoking its IASControl::ReceiveMsg method. A control should return NOERROR if it handles the message. Otherwise, it should return S_FALSE.

Keystroke, or WM_CHAR, messages are sent by invoking a control’s IASControl::Keypress method. A control can send a message to another control by invoking the target’s IASControl::ReceiveMsg method.


Handling Events

Auto PC controls can trigger events by invoking the ReceiveMsg method on the application’s default IASEventSink interface.

To handle events, applications implement an object that exposes the IASEventSink interface. A pointer to IASEventSink is passed to each form when the form is initialized. A form then passes the pointer to its controls. If a control needs to use the event sink, the pointer should be placed in the EventSink property with IASControl::put_EventSink. It can be retrieved with IASControl::get_EventSink.

To handle events, a control invokes IASEventSink::ReceiveMsg. This method is designed to handle events that use the Win32® format: Msg/wParam/lParam.


Redrawing the Screen

The simplest way for a control to redraw the screen is by invalidating the relevant region with IASForm::Invalidate or IASForm::InvalidateAll. If a control needs more flexible and efficient drawing capability, it must obtain a pointer to an IFMDraw interface from its form. This interface provides access to the device context, along with a number of related methods.

Only a control with its form is in the foreground can create a drawing that appears on the screen. If a form is not in the foreground, any attempt to draw to the screen is ignored and drawing is rendered to a default bitmap associated with the device context. Although the code executes properly, the image does not appear on the screen.

To draw, a control must have a device context. When all or part of a form is repainted, the form obtains the device context. It then passes the device context to a control when it invokes the control’s IASControl::Draw method. A control can obtain a device context directly by obtaining a pointer to an IFMDraw interface and invoking the IFMDraw::GetDC method.

If a control has invoked IFMDraw::GetDC, it should release it when it is finished by invoking IFMDraw::ReleaseDC.

When a control’s IASControl::Draw method is invoked by a form, it should update its screen image. When the DeferDraw property is set to TRUE, no redrawing can take place. When it is set to FALSE, the screen updates immediately. In the case of a form, drawing is deferred for all controls on the form. This permits an application to complete all drawing before updating the screen. This approach is much faster than repeatedly updating the screen as individual elements are redrawn.

The coordinates of an Auto PC control are defined relative to the x- and y-coordinates of its form, not the screen coordinates. A control’s screen size is defined by its Top, Left, Height, and Width properties. A control with its Top and Left properties both set to 0 is drawn in the upper-left corner of the form. The on-screen location of the control depends on the location of the form.

Note Every IFMDraw::GetDC method must be matched by an IFMDraw::ReleaseDC method. If the device context is not released, subsequent calls to IFMDraw::GetDC will fail.

Blitting Images to the Screen

Blitting images to the screen requires an IFMDraw pointer. Drawing is rendered to the system’s off-screen bitmap. To transfer the contents of the bitmap to the screen, a control invokes IFMDraw::Commit. To blit to only a portion of the screen, define a clipping rectangle and invoke IFMDraw::ClipAndCommit. To blit only a portion of the bitmap, use IASCanvas::CommitFrom or IASCanvas::CommitAt.

Note The IFMDraw and IASCanvas methods succeed only if the form has focus. If it does not, no errors are generated, but nothing appears on the screen.


Providing Support for Subclassing

An application can support subclassing through the IASClassMsgSink interface. The IASClassMsgSink interface contains all the IASControl methods necessary to duplicate the messaging and drawing capabilities of an IASControl, for example handling keystrokes. By subclassing the IASControl::KeyPress method of a form or control, the keystroke message can be handled by the application’s IASClassMsgSink::HandleKeyPress method. ActiveX does not provide for run time inheritance from existing controls. A pointer to the default IASClassMsgSink interface is stored in the control’s ClassMsgSink property.

An application can verify if subclassing is supported by invoking IASControl::get_ClassMsgSink. Controls that do not support subclassing return E_NOTIMPL when this method or the corresponding put method is invoked.

If a class message sink is implemented, the associated IASControl methods should immediately pass the necessary data to a IASClassMsgSink equivalent. If no further processing is needed, the IASClassMsgSink method returns S_OK. If the method returns S_FALSE, the control should perform default processing.


Using Hit Testing

Hit testing is used to determine the result of user input using a mouse or touch screen, and is not currently supported on Windows CE for the Auto PC. Hit testing is accomplished by means of the IASControl::HitTest method. When the form invokes the method, it passes in a set of coordinates that define a rectangle. The HitTest method should return either S_FALSE or NOERROR, depending on whether or not the coordinates fall within the control boundaries.


Implementing Speech

Microsoft® Windows® CE for the Auto PC includes speech recognition and text-to-speech (TTS) technologies. These technologies enable an Auto PC to respond to user-spoken commands and provide the user verbal feedback. The voice-controlled user interface (UI) enables hands-free, eyes-free Auto PC operation.

Speech recognition resolves user-spoken commands into a control for your application. Windows CE for the Auto PC uses discrete speech recognition, which recognizes words delineated by pauses.

TTS resolves text into synthesized speech. An Auto PC can read text using the TTS algorithms to determine phrasing, or you can adjust the phrasing that an Auto PC uses with control codes.

Speech recognition and TTS are exposed on an Auto PC through the Speech API (SAPI), which enables you to implement these technologies in your application. SAPI facilitates communication between your application and a speech recognition engine. Windows CE for the Auto PC uses a subset of SAPI for discrete speech recognition. It also adds interfaces that extend the SAPI features available for use in an automobile.


Speech Recognition

Windows CE for the Auto PC provides SAPI to simplify interaction between applications and the speech recognition engine. SAPI provides a standard by which applications integrate speech features.

The following illustration shows a basic speech recognition system.

Object
Function
Voice Command | Provides a high-level interface for discrete speech recognition
Speech Recognition Engine | Provides a low-level speech recognition interface
Audio Source | Enables the speech recognition engine to obtain standard audio input from a WAV input device. The engine does not have to consider what kind of WAV input device is available or what kind of audio drivers or APIs are supported. Windows CE for the Auto PC supports a WAV format quality of 11.025 kHz, 16-bit, mono.

A speech recognition engine recognizes speech commands and sends the results to applications. On an Auto PC, the speech recognition engine supports discrete speech recognition, which resolves a speech command delineated by pauses. A speech command can be one word, such as Radio, or a short phrase, such as What Can I Say? Discrete speech recognition does not require complex computation because pauses signify the start and end of speech commands. Discrete speech recognition allows for higher accuracy and lower memory requirements than continuous speech recognition, that recognizes uninterrupted speech.

Discrete speech recognition imitates a desktop computer menu, providing users with a list of commands to choose from. Discrete speech recognition users speak a command, where desktop computer users select a command from a visual menu. A speech recognition engine resolves audio input from a microphone into text or symbols that map to the speech command menu for the application.

To perform speech recognition, an application requires:

  • An audio source object to accept waveform input.
  • A speech recognition engine that resolves waveform input into text.
  • A list of speech commands, called a grammar, supplied to the speech recognition engine.

The audio source object and speech recognition engine object are included in Windows CE for the Auto PC. Your application must provide only the grammar to the speech recognition engine and handle the results returned.

The following illustration shows how an application sends a grammar to the speech recognition engine.

Note An original equipment manufacturer (OEM) supplies the speech recognition engine for Windows CE for the Auto PC. Although an OEM can install a speech recognition engine for continuous speech or for discrete speech, both function as a discrete speech recognition engine on an Auto PC.

If an OEM chooses to supply an alternate speech recognition engine, the engine must export a specified set of Microsoft Component Object Model (COM) interfaces that permit communication with SAPI, applications, and an audio source object that handles the details of taking input from a microphone and converting it into digital form.


Vocabularies and Templates

The words that a discrete speech recognition engine resolves are its vocabulary. A vocabulary consists of one or more templates for each word in the vocabulary. In speech recognition, a template is a pattern that can be used to identify or match a speaker’s pronunciation of a word. When a speech recognition engine tries to resolve a word, it compares the audio input stream to its templates until it finds a match or determines no match is available. The engine notifies the application when a speech command is recognized.

The following table shows templates supported by Windows CE for the Auto PC.

Template
Description
Speaker-independent Combines multiple pronunciations of a word or phrase, and requires no user training.

The speaker-independent templates for the vocabulary used for speech control of an Auto PC bundled applications is stored in ROM. You can install additional templates for your application in RAM. The Microsoft® Windows® CE Platform SDK for Auto PCs contains speaker-independent templates you can use in your application. You can also supply your own templates.

Although speaker-independent templates are accurate for 95% of users, they may not be accurate when used by some users.
Speaker-dependent Uses a single word or phrase pronunciation. Word pronunciations are trained by the application user. Training must be completed before the speech command is used. Call the IVCmdUserWord::Train function to set up user training in your application.

Although training can take some time, speaker-dependent templates can be useful if the user has a non-native accent or other speech patterns that do not reliably match the speaker-independent templates.


Grammar

A grammar is a subset of the available vocabulary that contains only the words used by your application. Create a grammar to avoid comparing a user’s speech command to all the words in a vocabulary. A grammar can contain words from the vocabularies included in ROM or RAM, as well as user-trained words. It should contain only those words that the application requires.

An active grammar is a subset of the grammar for your application available for a device context. When a user moves from one application context to another, the active grammar should change to the commands required for the new context. Managing grammars efficiently makes speech-enabled applications easier to use and speech recognition more accurate. The smaller the active grammar, the better the speech recognition.

Active grammar includes global command grammar and application command grammar. Global command grammar is continually active. It provides quick access to favorite applications and system controls, such as volume, time, and Help. Application command grammar is active only when a particular application is in focus. For example, application commands for the radio are active only when the radio is in focus.

For speech recognition to work effectively, consider the following guidelines when you choose a grammar:

  • Choose grammars consistent with other Auto PC applications.
  • Use intuitive words for commands.
  • Use words that identify the tasks that your application performs.
  • Keep speech menus short and use easy to remember words.
  • Avoid using commands that sound alike, which can result in false matches.
  • Use vocabulary included with Windows CE for the Auto PC when possible.

When an application receives focus, it notifies the speech recognition engine of the active grammar. The application’s active grammar is then added to the global command grammar.

When the audio source recognizes a speech command, it sends the WAV data to the speech recognition engine. The speech recognition engine attempts to match the WAV data to a speech command in the active grammar. If it succeeds, it passes the text to the application.


Enabling Speech

You enable speech for your application to provide users with speech command control over your application. To enable speech for your application, you must complete the following tasks:

  • Get the speech interface using IfmManage::get_Speech.
  • Create a voice menu and add words to initialize your application grammar.
  • Create a sink to handle speech recognition messages.


Creating a Voice Menu

When you create a voice menu, you initialize your application grammar to let the speech recognition engine know what words your application handles for each device context.

The code examples used in this section are part of a complete sample application, SRapp.dsp, included in the SDK. SRapp.dsp demonstrates how to use speech recognition to input user commands into an application. It contains the C++ file App.cpp, which contains the code for setting up a voice menu for an application, and Appsink.cpp, which programs a message sink. Like all Auto PC applications, SRapp.dsp creates a forms manager and forms using GetFormsManager and CreateForms.

To create a voice menu

  1. Call CreateVMenu with your application name and the menu name.
  2. Add words to your applications’s menu in one of the following ways:
    • Pass a resource identifier table directly when calling CreateVMenu.
    • Call AddVMenuCommand to add words individually.
    • Call AddVMenuCommandFromResource to add words from a resource file.
  3. Call put_VoiceMenu to associate the voice menu with a form in your application.
  4. Be sure to handle the WM_SPCH_RECOG message in the HandleMessage attached to your form or WM_COMMAND messages in the form’s event sink (IASEventSink::ReceiveMsg).

If you want to access other interfaces on the voice command object, call IAPCSpeech::QuerySpeechInterface to get the IVoiceCmd, IVCmdAttributes, and IVCmdUserWord interfaces.

The following code example shows how to create a voice menu from a resouce file using CreateColorsVoiceMenu.

HRESULT
CSRApp::CreateColorsVoiceMenu()
{
    HRESULT hr;

    if(!IsColorWordsTrained()) return E_FAIL;

    VCMDNAME vnColors;
    memset(&vnColors, NULL, sizeof(VCMDNAME));
    lstrcpy(vnColors.szApplication, L"SR App");
    lstrcpy(vnColors.szState, L"SR App - Colors");

// Creates the color menu
    hr = m_pSpeech->CreateVMenu(
        NULL,
        &vnColors,
        m_hInst,
        0,
        NULL,
        APCSPCH_VM_USEEXISTING,
        &m_pVMColorsForm);
    if(FAILED(hr))
        return E_FAIL;

// Adds names of colors to the menu from a resource file
    hr = m_pSpeech->AddVMenuCommandsFromResource(
        m_pVMColorsForm,
        m_hInst,
        MAKEINTRESOURCE(IDVM_COLORS),
        0,
        APCSPCH_VM_USEEXISTING);
    if(FAILED(hr))
        return E_FAIL;

    hr = m_pSpeech->AddVMenuCommandsFromResource(
        m_pVMColorsForm,
        m_hInst,
        MAKEINTRESOURCE(IDVM_COLORS_END),
        0,
        APCSPCH_VM_USEEXISTING);
    if(FAILED(hr))
        return E_FAIL;

The following code example shows how to associate a voice menu with a form.

    hr = m_pColorsForm->put_VoiceMenu(m_pVMColorsForm);
    if(FAILED(hr))
        return E_FAIL;

    return NOERROR;

The following code example shows the message handler for SRapp.dsp, contained in Appsink.cpp.

STDMETHODIMP CAppMessageSink::HandleMessage(IDispatch* pdispControl,
LONG uMsg, LONG wParam, LONG lParam)
{
    switch (uMsg)
    {
    default:
        break;

    case WM_SPCH_RECOG:
        switch (lParam)
        {
        default:
            break;

        case IDVMI_BLACK:
            g_pApp->m_pColorsForm->put_BackColor(BLACK);
            break;
        case IDVMI_RED:
            g_pApp->m_pColorsForm->put_BackColor(RED);
            break;
        case IDVMI_GREEN:
            g_pApp->m_pColorsForm->put_BackColor(GREEN);
            break;
...
        case IDVMI_WHITE:
            g_pApp->m_pColorsForm->put_BackColor(WHITE);
            break;

        case IDVMI_ZERO:
        case IDVMI_ONE:
...
        case IDVMI_NINE:
            g_pApp->AddNumber(lParam - IDVMI_NUMBERS_BASE);
            break;

        case IDVMI_NUMBERS_END:
            g_pApp->m_pActiveForms->SetFocus(g_pApp->m_pMainForm);
            break;

        case IDVMI_COLORS_END:
            g_pApp->m_pActiveForms->SetFocus(g_pApp->m_pMainForm);
            break;

        }
        break;
    }

    return S_FALSE;
}


Training Words

If your application requires users to train speaker-dependent speech commands, write your application to access the training function. Use the interface IVCmdUserWord to enable user training for speech commands.

To enable user training of speech commands

  1. Call IVCmdUserWord::QueryPhrase to find out if a speaker-independent or speaker-dependent template exists for the word.
  2. Call IVCmdUserWord::Train and pass the words or phrase to train.

Call IVCmdUserWord::ModifyTraining to delete a speaker-dependent template or to enable an application to specify templates to enable for a particular phrase.

The speaker-independent and speaker-dependent templates operate independently of each other. If your application enables both templates for a word or phrase, you may achieve better recognition accuracy.

The IVCmdUserWord::AddSIFile and IVCmdUserWord::RemoveSIFile functions are called by the APCLoad to add or remove application-specific, speaker-independent templates. For more information on APCLoad, see Preparing an Application for Distribution.


Speech Feedback

Auto PC applications must provide some form of audible feedback for speech recognition. Feedback informs the user a response or command has been recognized. Speech feedback supplements faceplate navigation.

The following table shows the speech recognition tones played after each successful recognition of a speech command.

Tone
Description
On | Plays when an Auto PC wakes up, prior to application-specific feedback
Confirm | Plays when an Auto PC is awake, after each successful recognition
Off | Plays when speech recognition goes to sleep, followed by an immediate return to normal audio output volume

To hear the current application status, a user can use the Read speech command. In a bundled application, the Read speech command reads the title bar text and the item in focus. For example, in Address Book, when a user says Read, the application replies Address Book, pauses, and then provides the contact name in focus.

By default, the confirm tone sound is enabled for all the commands. You can use the function AddVMenuCommand to disable the Confirm tone sound for individual commands.


Text-to-Speech

The TTS engine takes text input from your application and synthesizes speech output. It then sends the speech output to the speakers.

Your application communicates with the voice text object to provide TTS codes, as well as control codes, to adjust the speed, pitch, or cadence of the text spoken. The voice text object controls the TTS engine that sends synthesized speech output to speakers. If you create a TTS notification sink, the voice text object sends detailed information to your application about the timing of the text as played.

The following illustration shows a basic TTS system.

The voice text object exposes methods your application can use to implement TTS. Its interfaces provide a high-level API that isolates applications from the details of the TTS engine and the audio destination.


Enabling TTS

You enable TTS for your application to provide verbal feedback to your users about your application.

To enable TTS

  1. Get the speech interface using IfmManage::get_Speech.
  2. Call the IAPCSpeech::Speak or IAPCSpeech::SpeakEx function to speak a sentence.
  3. Create a sink to handle TTS messages.

    Note If you use IAPCSpeech::SpeakEx and want to do text normalization (changing word pronunciation based on context), call IAPCSpeech::CreateSpkContext.

  4. If you want to use the voice text interfaces, call IAPCSpeech::QuerySpeechInterface to get the IVTxtAttributes and IVoiceText interfaces. The following table shows these interfaces.
Interface
Description
IVTxtAttributes | Controls the attributes of a voice text object
IVoiceText | Registers an application to use a voice text object and controls playback of text

The code examples used in this section are part of a complete sample application, TTS.dsp, included in the SDK. TTS.dsp shows a TTS application that reads the user-selected information from the menu.

The following code example shows how the Read Menu command is implemented.

VOID CTTSApp::ProcessMessage(LONG uMsg, LONG wParam, LONG lParam)
{
    long lCurSel = 0;
    long lCount = 0;
    long lId = 0;
    int i;
    BSTR bstr;
    IASPowerListBoxItem *pItem = NULL;
    long lItemData = NULL;

    if(uMsg == WM_COMMAND && LOWORD(wParam) == IDC_LISTBOX &&
        HIWORD(wParam) == LBN_DBLCLK) // Some menu option is
                                      // selected
    {
        switch (HIWORD(lParam)) // Identifier of the item that
                                // is selected
// in HIWORD(lParam)
        {
        // When the user selects the Read Menu command the application
        // passes each command and its identifier to the Speak
        // function. When the Speak function is about to say each
        // command, it initiates a VTXTF_SPEAK message with the bookmark
        // identifier in the lParam.

        case IDM_READMENU:
            m_pListBox->get_Count(&lCount);
            for(i=0; i<lCount; i++)
            {
                m_pListBox->ItemAt(i, (IDispatch **)&pItem);
                pItem->get_Caption(&bstr);
                pItem->get_ItemId(&lId);
                m_pSpeech->Speak(bstr, lId);
            }
            break;

        // When the Exit command is selected, a flag is set so that
        // the application can exit after the VTXTF_SPEAKDONE message
        // is received.

        case IDM_EXIT:
            m_bExiting = TRUE;
:
        default:
            break;
        } // end switch
    } //end if command
}

The following code example shows how the TTS notification sink is handled.

STDMETHODIMP
CAppMessageSink::HandleMessage(IDispatch* pdispControl, LONG uMsg, LONG wParam, LONG lParam)
{
    switch(uMsg)
    {
    default:
        break;

    case WM_SPCH_NOTIFY:    // Notifications from TTS engine
        switch(wParam)
        {
        default:
            break;

        case VTXTF_SPEAKDONE:    // When a TTS phrase is done, this is called
            g_pApp->OnSpeakDone();    // Call a CTTSApp function to handle this
            break;

        case VTXTF_SPEAK:    // Messages fired while TTS engine is speaking, holds
                            // the bookmark identifier passed to the Speak function
            g_pApp->SetFocusOnId(lParam);    // in this App, the bookmark identifier is the
            break;                            // Identifier of the menu item about to be spoken
        } //end switch(wParam)
        break;

    case WM_SETTINGCHANGE:        // Fired when a system setting changed
        if(wParam == SPI_SETAPCFEEDBACK) g_pApp->GetFeedbackLevels();    // Feedback level changed
        break;                                                            // Refresh our applications variables

    } //end switch(uMsg)

    return S_FALSE; // return S_FALSE to keep message processing down the hierarchy
}


Controlling the Audio System

An Auto PC audio system is a full-featured, digital audio system. Compared to a conventional car audio system, an Auto PC audio system has more audio sound input sources. These sources include an AM/FM radio tuner, a compact disc (CD) player, CD changer, OS output, such as tone feedback and text-to-speech (TTS), a microphone, USB, phone, and auxiliary input devices.

An Auto PC audio system architecture provides an audio manager API for applications. The Audio Manager object coordinates and controls the flow of audio input sources. It also communicates audio status with an Auto PC shell and applications and accepts audio control changes sent from the shell and applications.

The audio driver model defines the basic interface layer between the audio device drivers and the audio manager object. It provides the hardware abstraction layer (HAL) interfaces for the high-level audio control APIs. The applications use the high-level audio APIs to access, control, and coordinate the various audio devices.

The following illustration shows an Auto PC audio system architecture.

Audio input sources can have different formats, such as pulse code modulation (PCM) mono, PCM stereo, Motion Picture Experts Group (MPEG) standard MPEG-4, or Dolby AC-3 streams. The audio system provides sound equalization, Surround Sound decoding and volume, balance, and fade controls. Audio output can be played to up to six speakers, or to any universal serial bus (USB) client.

An audio source can be categorized as a foreground audio source or a background audio source. Foreground audio sources, such as system sounds and TTS, are audio sounds that play over background audio sources. Foreground audio sources include computer waveform (WAV) file output and TTS output. These sources are controlled by the WAV-out API. Foreground audio sources can play simultaneously, and are combined with the active background audio source.

Background audio sources are controlled by the audio source control API. They include the AM/FM tuner, CD player, auxiliary input devices, and USB clients. Only one background audio source can be sent to the speakers at a time. The background audio source is sometimes partially or fully muted if TTS or speech recognition is active.

Whether or not a specific audio control is exposed to a user depends on a device’s hardware configuration. Some hardware configurations may not include all of the capabilities supported by the operating system (OS). Be sure that your application identifies each device’s capabilities before exposing or adjusting audio settings.

Microsoft® Windows® CE for the Auto PC supports digital signal processor (DSP) and other audio systems that control equalization, Surround Sound, crossovers, and mixing. For systems with a DSP, the DSP becomes the central piece of the audio system. A DSP enables Surround Sound decoding and controls the equalization settings from one device driver. For systems without a DSP, audio equalization is either analog or digital and may require communication with more than one device driver. In either system, the audio manager reads the registry settings when the system searches for which audio drivers are supported. Volume, balance, and fade are controlled through the coder-decoder (CODEC) devices in an Auto PC.

To control audio in your application, use the audio manager and tuner APIs.


Audio Manager API

The audio manager API enables you to coordinate audio devices and control the flow of audio sources. It enables you to control sound quality, including balance, fade, bass, treble, center channel, sub-woofer, surround sound, crossover filtering, and equalization.

The audio manager works with the audio driver model. The audio manager API includes the following APIs: audio source control, WAV-in, WAV-out, Equalization, Surround Sound, and Volume. An Auto PC audio system can have more than one output destination, including a speaker, a USB device, and a computer. Because the most common destination is a speaker, the audio manager API does not include an API to control the selection of the audio output destination. If your application requires destination control, access the applicable audio device driver directly to choose the audio destination.

The following illustration shows how the audio manager API controls the audio system.


Equalization

Equalization enables you to control the equalization settings. You first should query the equalization capabilities, since different device drivers may provide different equalization capabilities. These capabilities can include multiple fixed-band equalization or parametric equalization, as well as various treble, bass, and volume settings.

To determine what equalization features are supported

  • Call AAM_GetEQCaps and verify selected capabilities.

The following code example shows how to verify specific equalization capabilities supported for a device.

if (AAM_GetEQCaps(&dwCap) == 0) {
    // Verify equalization support.
    if (dwCap & AAM_FLAG_NUMBAND_MASK) {
      fHasEq = TRUE;
      // Set the number of equalization bands.
     lNumEqBands = dwCap&AAM_FLAG_NUMBAND_MASK;
    }
    // Verify loudness support.
    if (dwCap & AAM_FLAG_LOUDNESS) {
    fHasLoudness = TRUE;
    }

To modify equalization settings

  1. To get the setting for the band, pass AAM_FLAG_GET to the function.
  2. To change the value of the band, pass AAM_FLAG_SET to the function.

The following code example shows how to modify equalization settings.

DWORD dwBand = 2;
LONG lGain;
if (AAM_EQBandControl(dwBand,
    AAM_FLAG_GAIN | AAM_FLAG_GET,
    &lGain) != 0)
{
    lGain ++;
    // Give the equalizer a new band setting.
    AAM_EQBandControl(dwBand,
        AAM_FLAG_GAIN |
        AAM_FLAG_SET, &lGain)
}


Surround-Sound Decoding

Surround-sound decoding contains member functions to enable and disable decoding, set the Surround Sound delay time, and set the cut-off frequency of the low-pass filter.

To modify Surround Sound decoding settings

  1. Call AAM_GetSSDCaps to query the Surround Sound capabilities.
  2. Call AAM_SSDControl to modify the settings.

The following code example shows how to modify Surround Sound decoding settings.

if (AAM_SSDControl(AAM_FLAG_SSD_TYPE
    | AAM_FLAG_GET, &lSurround) == 0)
{
    fSurroundOn = (lSurround != AAM_SSD_DISABLED);
}
AAM_EnableSSD(!fSurround)


Volume, Balance, and Fade

The volume, balance, and fade functions control volume, balance, and fade settings.

To modify volume settings

  • Call AAM_VolumeControl.

The following code example shows how to modify volume settings.

Long lVol = 8;
AAM_VolumeControl(AAM_FLAG_MASTER
    | AAM_FLAG_SET, &lVol)
AAM_VolumeControl(AAM_FLAG_CENTER
     | AAM_FLAG_SET, &lVol)
AAM_VolumeControl(AAM_FLAG_WOOFER
    | AAM_FLAG_SET, &lVol)

Note Volume is measured in levels of attenuation, so a volume of 0 is the loudest value.

To modify bass, treble, loudness, and crossover settings

  1. To get the setting, pass AAM_FLAG_GET to the function.
  2. To change the setting, pass AAM_FLAG_SET to the function.

The following code example shows how to change bass, treble, loudness, and crossover settings.

AAM_EQPreset(AAM_FLAG_BASS |
    AAM_FLAG_SET, &lBass)
AAM_EQPreset(AAM_FLAG_TREBLE |
    AAM_FLAG_SET, &lTreble)
AAM_EQPreset(AAM_FLAG_LOUDNESS |
    AAM_FLAG_SET, (long *)&bLoudness)
AAM_FilterControl(AAM_FLAG_CROSSOVER_HPF |
    AAM_FLAG_SET, &dwEnable, &dwCrossoverFreq)


Audio Source Control API

The audio source control API enables an application to control and query the audio input source in the following ways:

  • Select an audio source
  • Receive a list of registered audio sources
  • Receive notifications when an audio source changes
  • Relay messages directly to audio device drivers

The audio source control API functions are exported through Apcdll.dll, so your application must link with Apcdll.lib.


WAV-in and WAV-out APIs

The WAV-in and WAV-out APIs enable you to control foreground audio sources, such as .wav file output and TTS output. These APIs are compatible with Win32® WAV APIs and communicate directly with the WAV-out device driver. Before playing or recording sound, you must access an audio device and query its capabilities. You must also coordinate the various devices in the system by using device handles and device identifiers. For more information about the WAV-in and WAV-out APIs, see the Microsoft® Windows® CE Software Developer’s Kit documentation.


Tuner API

The tuner API enables you to set or modify band settings to provide access to public or custom radio bands. It provides a unified interface for applications to access and control tuner resources. With the tuner API, you can control public and custom bands, enumerate tuners, query the attributes of tuners, and change tuner settings.

The following table shows tuner API functions.

Function
Description
TunerQuery | Identifies the tuner devices registered in the system
TunerGetDevCaps | Determines the capabilities of a specific tuner, including the bands supported
TunerGetBandInfo | Determines the size and identification of the current band
TunerOpen | Gets a handle to a tuner resource
TunerGetConfig TunerSetConfig | Gets or modifies the current tuner settings
TunerGetSignalInfo | Obtains signal information, such as whether or not a stereo signal is present, whether or not the frequency setting is valid, and signal strength
TunerClose | Releases the device resource

The following code example shows how to initialize and set up a tuner.

// Get the tuner device capabilities. The application is using
// tuner device 1.
if(!TunerGetDevCaps(1, &CapTuner))
{
  return    FALSE;
}

// Be sure that the tuner supports both AM and FM.
if((CapTuner.dwTunerCaps&(BAND_AM|BAND_FM)) != (BAND_AM|BAND_FM))
{
return    FALSE;
}

// Open the tuner. The application is using tuner device 1.
m_hTuner = TunerOpen(1);
if(m_hTuner == INVALID_HANDLE_VALUE) return E_FAIL; //No tuner

hr = SetBand(m_dwCurrentBand);
if(FAILED(hr)) return E_FAIL;
  return NOERROR;
}


Creating an Audio Application

When you create an audio application, the steps are the same as for other applications, except for additional steps that add audio features.

To create an audio application

  1. Create a message loop that uses GetMessage or DispatchMessage.
  2. Call GetFormsManager to create an instance of a Forms Manager.
    • Use CoCreateInstance to create a Forms Manager.
    • Get a context handle.
    • Attach a class message sink to a Forms Manager.
    • Register the application.
  3. Call the function CreateFormRadio to create a form.

    CreateFormRadio creates a form by loading it from the resource file and getting all the interfaces for the controls contained in the form. As you create a form, get the interface pointers to access the controls. Each Auto PC application must have at least one form.

  4. Start the form.
  5. Add menus.
    • Call BuildSettingsMenu to load the settings menu from a resource file and get an interface to each of the menu items. In this function, set the maximum, minimum, and current values for all the integer spin box controls.

      Integer spin box controls are used with each menu item to provide a method for changing settings.

  6. Add controls and strings.
  7. Initialize the audio manager.

    The audio manager gives you access and control over audio sources. For example, if you want to use the CD player and the radio is running, you need software that stops the radio before starting the CD player.

  8. Initialize the AM/FM tuner.
  9. Create an event sink.

This procedure uses code examples from a sample audio application, Tuneit.cpp, included in the SDK. Tuneit.cpp highlights the use of tuner and audio manager APIs.

In the Tuneit.cpp file, the WinMain function shows how to program a message loop, and the GetFormsManager function shows how the Forms Manager is created. The TuneSink.cpp and TuneSink.h files show how to create an event sink.

Tuneit.cpp has only one form: form radio. The CreateFormRadio function creates a form by loading it from the resource file and getting all the interfaces for the controls contained in the form.

The following code example shows how to set up and initialize an audio manager. It shows only bass and treble; you need to cover all other application settings.

HRESULT
CTuneitApp::InitAudioManager()
{
    long lRet;
    long bMute = FALSE;
    DWORD dwEQCaps = NULL;

    // Verify support for bass and treble
    if(AAM_GetEQCaps(&dwEQCaps))
    {
        return E_FAIL;
    }
    // Set local audio manager storage variables using
    // local flags understood by your resource script
    // menu-loading function.
    if(dwEQCaps & AAM_FLAG_BASS) m_dwfAudioCaps |= FLAG_BASS;
    if(dwEQCaps & AAM_FLAG_TREBLE) m_dwfAudioCaps |= FLAG_TREBLE;

    // Get minimum, maximum, and current bass values.
    if(!AAM_EQPreset(AAM_FLAG_BASS | AAM_FLAG_GET, &lRet))
    {
        m_lSetting[BASS] = lRet;
        AAM_EQPreset(AAM_FLAG_BASS | AAM_FLAG_GET | AAM_FLAG_RANGE, &lRet);
        m_lSettingMin[BASS] = -LOWORD(lRet);
        m_lSettingMax[BASS] = LOWORD(lRet);
    }

    // Get minimum, maximum, and current treble values.
    if(!AAM_EQPreset(AAM_FLAG_TREBLE | AAM_FLAG_GET, &lRet))
    {
        m_lSetting[TREBLE] = lRet;
        AAM_EQPreset(AAM_FLAG_TREBLE | AAM_FLAG_GET | AAM_FLAG_RANGE, &lRet);
        m_lSettingMin[TREBLE] = -LOWORD(lRet);
        m_lSettingMax[TREBLE] = LOWORD(lRet);
    }

    // Turn off mute.
    AAM_VolumeControl(AAM_FLAG_MUTE | AAM_FLAG_SET, &bMute);

    // Set the source to radio.
    AAM_SelectSource(AAM_SRC_TUNER);

    return NOERROR;
}


Controlling a CD Player

An Auto PC includes a CD player and an optional CD changer. You control these devices with the Advanced Technology Attachment (ATA) packet interface driver. This driver provides a standard set of I/O control codes that enable you to obtain disc and track information, and to start and stop the CD player.

To control the CD player

  • Call AAM_GetSourceCap and pass it the flag for the device you want to control.

    The flags are AAM_SRC_CD for the CD player and AAM_SRC_CDCHANGER for the CD changer.

    AAM_GetSourceCap provides you with a device driver, such as CDR1, you can use to open the device. You open the device by calling CreateFile, which returns a device handle.

The following code example shows how to use CreateFile to obtain a device handle.

g_hDev = CreateFile (TEXT("CDR1:"), GENERIC_READ,
                       FILE_SHARE_READ|FILE_SHARE_WRITE,
                       NULL, OPEN_EXISTING, 0, 0);
    if (INVALID_HANDLE_VALUE == g_hDev)
    {
        return FALSE;
    }


Getting Disc Information

Once you get a CD device handle, call CDROM_IOCTL_DISC_INFO to get the table of contents for the disc. The table of contents (TOC) is contained in the Q-channel data on the lead-in track. It provides the starting and ending track numbers and the starting address of the lead-out track. The starting and ending track numbers are binary values, not binary-coded decimals. Read and cache TOC information when you initialize the drive, so that when CDROM_IOCTL_DISC_INFO is called, the application will not interrupt play to get this information. The first and last track numbers do not include the lead-in and lead-out tracks of the session.

After getting the disc TOC, call the CDROM_IOCTL_TRACK_INFO function to find out the track starting address and control information. This function takes a binary track number in the range specified by the first and last track number for the disc. It returns the Red Book address for the starting point and control information for the track. The Red Book address, one of two formats used to specify an address, specifies the data location in minutes, seconds, and frames (MSF). The other address format is the High Sierra Specification format, which displays data as a logical block address.

Note MSF contains 75 frames per second. To convert address data from one format to the other, use the following formula:

Sector = (((Minute*60) + Second)*75) + Frame

The control information for the track is contained in the four most significant bits of the control information byte. The following table shows the bit field definitions.

Bit
Definition
0–3 Automatic dialog replacement (ADR) information
4 0 No pre-emphasis on audio channels
1 Pre-emphasis on audio channels
5 0 Digital copy prohibited
1 Digital copy enabled
6 0 Audio track
1 Data track
7 0 Two audio channels
1 Four audio channels

Pre-emphasis, increases the magnitude of the higher signal frequencies, improving the signal-to-noise ratio. De-emphasis resets the signal magnitude. When verifying track information, if pre-emphasis is specified, you can turn it off by calling AAM_EQPreset and setting AAM_FLAG_DEEMPHASIS.

The following code example shows how to use CDROM_IOCTL_DISC_INFO and CDROM_IOCTL_TRACK_INFO to obtain information about a CD player.

BOOL cdGetDiskInfo( void)
{
    DWORD                           RetDataLen;
    WORD                            wTrackIdx;
    CDROM_TRACKINFO         TrackInfo;

    g_DiskValid = FALSE;              // Assume no disc information.

    g_DiscInfo.Reserved = 0;
    g_DiscInfo.ReqSession = 0xff;     // Do you want the last session?

    if (DeviceIoControl(g_hDev,       // Obtains the disc TOC
            CDROM_IOCTL_DISC_INFO,
            &g_DiscInfo,
            sizeof(g_DiscInfo),
            NULL, 0,
            &RetDataLen, NULL) == FALSE)
    {
         return( FALSE);
    }

    g_nTracks = (WORD)g_DiscInfo.LastTrack + 1 - g_DiscInfo.FirstTrack;

    for( wTrackIdx = 0; wTrackIdx < g_nTracks; wTrackIdx++)
    {
        TrackInfo.TrackNumber = g_DiscInfo.FirstTrack + wTrackIdx;

        if (DeviceIoControl(g_hDev,
                CDROM_IOCTL_TRACK_INFO, // Obtains the track starting
                                        // address and control
                                        // information
                &TrackInfo,
                sizeof(TrackInfo),
                NULL, 0,
                &RetDataLen, NULL) == FALSE)
    {
        return( FALSE);
        }

        g_Tracks[wTrackIdx].ti_msfaddr = TrackInfo.TrackAddr;
        g_Tracks[wTrackIdx].ti_ctl = TrackInfo.TrackControl;
    }
    g_DiskValid = TRUE;     // Assume no disc information.
    return(TRUE);
}


Starting and Stopping a CD Player

You can start, stop, pause, and resume playing the CD Player. Calling the CDROM_IOCTL_AUDIO_PLAY and CDROM_IOCTL_AUDIO_STOP functions automatically sets or clears the CDAUDSTAT_PAUSED flag returned by the CDROM_IOCTL_GET_AUDIO_STATE function and the CDDEVSTAT_PLAYING_AUDIO flag returned by the CDROM_IOCTL_GET_DEVICE_STATUS function.

If the drive does not support audio, ERROR_UNKNOWN_COMMAND is returned. If the starting or ending addresses are outside of the track play area, ERROR_INVALID_PARAMETER is returned.

To start and stop a CD Player

  1. Call CDROM_IOCTL_AUDIO_PLAY to play selected audio tracks until the requested sectors have finished or until play is interrupted.

    The following code example shows how to start a CD player.

    if (DeviceIoControl(g_hDev,
            CDROM_IOCTL_AUDIO_PLAY,
            &PlayInfo,
            sizeof(PlayInfo),
            NULL, 0,
            &RetDataLen, NULL) == FALSE)
    {
         return( FALSE);
    }
  2. Call CDROM_IOCTL_AUDIO_STOP to stop playing audio tracks.

    This function either pauses or stops the CD drive. If the CD player is playing, the function pauses the CD drive and updates the starting and ending addresses for the CDROM_IOCTL_AUDIO_RESUME function. If the CD player is paused, the function resets the starting and ending addresses for the CDROM_IOCTL_AUDIO_RESUME function.

    The following code example shows how to stop a CD player.

    BOOL    cdStop( void)
{
    DWORD                   RetDataLen;

    if( !g_DiskValid)
        return( FALSE);

    if (DeviceIoControl(g_hDev,
            CDROM_IOCTL_AUDIO_STOP,
            NULL, 0,
            NULL, 0,
            &RetDataLen, NULL) == FALSE)
    {
         return( FALSE);
    }

    return( TRUE);
}

    The following code example shows how to resume play on a CD device a user has stopped.

    BOOL    cdResume( void)
{
    DWORD                   RetDataLen;

    if( !g_DiskValid)
        return( FALSE);

    if (DeviceIoControl(g_hDev,
            CDROM_IOCTL_AUDIO_RESUME,
            NULL, 0,
            NULL, 0,
            &RetDataLen, NULL) == FALSE)
    {
         return( FALSE);
    }
    g_Playing = 1;
    return( TRUE);
}


Interacting with a Vehicle Computer

Note The vehicle I/O APIs documented here are preliminary and subject to change.

The vehicle I/O API includes methods used to obtain diagnostic and maintenance data. You can write applications that retrieve and analyze this data and notify the vehicle driver of a mechanical malfunction or required maintenance. The vehicle I/O API enables you to control vehicle operations, such as locking and unlocking doors. You can also display data obtained from a vehicle computer or engine control unit to aide the driver to make driving decisions, for example, notifying the driver when to shift for optimal fuel efficiency or optimal acceleration. The following sections discuss the hardware and vehicle I/O API that enable such communication.

An Auto PC is equipped with a universal serial bus (USB) connected to a vehicle’s on-board diagnostic level II (OBD II) port by means of hardware known as a vehicle bus bridge. These hardware connections establish data flow between the vehicle on-board computer and an Auto PC.

The following illustration shows the vehicle I/O API and the hardware interface.

Interface
Description
VIOInitialize | Initializes the vehicle I/O API for a process or thread
VIOUninitialize | Uninitializes the vehicle I/O API for a process or the current thread and frees resources that it was using
IVIO_Vehicle | Retrieves pointers to the interfaces IVIO_EnumMetrics, IVIO_EnumDevices, and IVIO_EnumMaintenanceItems.
IVIO_EnumMetrics | Enumerates basic vehicle data such as manufacturer, make, model, year, vehicle identification number (VIN), transmission, fuel system, and engine type
IVIO_EnumMaintenanceItems | Enumerates a schedule of maintenance items
IVIO_EnumMaintenanceEntry | Enumerates when a scheduled maintenance item was completed
IVIO_EnumDevices | Enumerates a list of devices, such as sensors from which data can be retrieved
IVIO_Device | Interfaces with vehicle hardware devices, such as sensors, from which data can be retrieved, for example, engine RPM or coolant temperature
IVIO_DataValue | Returns data values from the enumeration interfaces to an application
IVIO_EventSink | Notifies an application of an event
IVIO_Ioctl | Communicates with a device driver
IVIO_MiniDriver | Connects vehicle hardware and Auto PC software

Note Many vehicle I/O API methods use a VARIANT as a parameter. A VARIANT is a special data type that can contain any kind of data except fixed-length string data and user-defined data types. A VARIANT enables different data types to be passed to a method. Many methods have a numeric parameter that is the time-out interval in milliseconds.


Initializing COM and Vehicle I/O

Because the vehicle I/O API is a COM interface, when you write an application, you must first initialize COM and then initialize the vehicle I/O interface. The following code example, shows how to initialize and uninitialize COM and vehicle I/O.

// Initialize COM.
CoInitializeEx(NULL, COINIT_MULTITHREADED);
// Initialize the vehicle I/O interface.
// This initializes any necessary driver structures.
VIOInitialize(NULL);

// The rest of your Auto PC application goes here.
.
.
.
// The application is now complete.

VIOUninitialize();
CoUninitialize();


Obtaining Vehicle Data

The vehicle I/O API enables you to write applications that obtain data from a vehicle’s on-board computers and present that data to the driver. You can write diagnostic, maintenance, and other informational applications.


Obtaining Vehicle Attributes

The IVIO_EnumMetrics interface, which you obtain from a IVIO_Vehicle interface, enumerates vehicle attributes, such as manufacturer, model number, number of cylinders, and transmission type. The following code example shows how to create an instance of a vehicle interface and how to get an enumeration interface from the vehicle interface. You then use IVIO_DataValue methods to obtain vehicle attributes.

IVIO_Vehicle            *pVehicle;
IVIO_EnumMetrics        *pVehicleMetrics;
IVIO_DataValue        *pDataValue[1];
VARIANT                vAttributeValue;

// Create an instance of an IVIO_Vehicle interface.
hr = CoCreateInstance (CLSID_VIOVEHICLE, NULL, CLSCTX_INPROC_SERVER,
                       IID_VIOVEHICLE, (PVOID *) &pVehicle);
// Retrieve a IVIO_EnumMetrics interface from the IVIO_Vehicle interface.
hrMetrics = pVehicle->get_Metrics (&pVehicleMetrics);
VariantInt(&vAttributeValue);
// Get the first element of the metrics list. This may be a loop to
// access all attributes.
hrMetrics = pVehicleMetrics->Next(1, pDataValue, NULL);
if (hrMetrics == S_OK)
  {
  // Read the next vehicle attribute.
  pDataValue[0]->get_ItemID(&dwAttributeID);
  // Copy the attribute data.
  pDataValue[0]->get_DataValue(&vAttributeValue);

  // Process the attribute.

  // Release the reference that was returned.
  pDataValue[0]->Release();
  }
// Clear the VARIANT buffer.
VariantClear(&vAttributeValue);
// Release the metrics enumerator.
pVehicleMetrics->Release;


Obtaining Operating Condition Data

Vehicle status data is obtained from the IVIO_Device interface to two types of vehicle devices: polled devices and streaming devices. Polled devices provide relatively static data, such as coolant temperature. Streaming devices provide dynamic data, such as RPM.

To retrieve data from a polled device

  1. Obtain a reference to the interface for the device with CoCreateInstance.
  2. Retrieve the data by calling the appropriate method calls for the device, such as GetData.
  3. Release the reference to the device interface.

To set up data retrieval from a streaming device

  1. Write a callback object for the device to invoke.
  2. Obtain a reference to the interface for the device using CoCreateInstance.
  3. Obtain a reference to an instance of the callback object’s IUnknown interface.
  4. Obtain a reference to the callback object’s IVioEventSink inteface.
  5. Release the reference to the callback object’s IUnknown interface.
  6. Set the device’s notification routine to be the callback object’s IVioEventSink interface.

To terminate data retrieval from a streaming device

  1. Set the device’s notification routine to NULL.
  2. Release the reference to the callback object’s IVioEventSink interface.
  3. Release the reference to the device.

The following code example shows how to obtain a polled device interface and how to retrieve data from that device.

IVIO_Device          *pDevice;
VARIANT              vCoolantTemp;
LONG                     lCoolantTemp;

hr = CoCreateInstance(CLSID_VIO_COOLANT_TEMP, NULL,
                      CLSCTX_INPROC_SERVER, IID_VIODEVICE,
                      (PVOID *) &pDevice);
VariantInit(&vCoolantTemp);
// Read the coolant temperature from the vehicle.
hr = pDevice->GetData(&vCoolantTemp, 2000);
// If you read the coolant temperature successfully, save it.
lCoolantTemp = V_I4(&vCoolantTemp);
// Free the resources of the VARIANT.
VariantClear(&vCoolantTemp);
// Release the reference to the device.
pDevice->Release();

If you need data from a device that provides streaming data, you must not only obtain an interface to the device, but also create a callback object. The following code example shows how to obtain the necessary interface and how to invoke the callback object.

IVIO_Device         *pDevice;
IVIO_EventSink      *pEventSink;

hr = CoCreateInstance(CLSID_VIO_VEHICLE_SPEED, NULL,
                      CLSCTX_INPROC_SERVER, IID_VIODEVICE,
                      (PVOID *) &pDevice);

CVioSpeedCallBack *pCallback = new CVioSpeedCallback;
pCallback->QueryInterface(IID_VIOEVENTSINK, (PVOID *) &pEventSink);
// Release the callback object.
pCallback->Release();
// Start the streaming vehicle speedometer device.
hr = pDevice->SetNotify(NULL, pEventSink, 0);

// Other code

// Before exiting the application, turn off the streaming device.
hr = pDevice->SetNotify(NULL, NULL, 0);
// Release the reference to the event sink object.
pEventSink->Release();
// Release the reference to the device.
pDevice->Release();

The following code example shows how to create a callback object.

class CVioSpeedCallBack : public IVIO_EventSink
{
public:
  CVioSpeedCallback();
  virtual ~CVioSpeedCallback();
// Standard IUnknown methods.
// IVIO_EventSink method.
  STDMETHOD (ReceiveMsg) (LPVARIANT pData, LPARAM lParam);
};
// Note: The callback function returns  on its own thread.
STDMETHODIMP CVioSpeedCallback::ReceiveMsg(LPVARIANT pData, LPARAM
                                           lParam)
  {
  USHORT usVehicleSpeed;
  // Get the speed from the VARIANT.
  usVehicleSpeed = V_UI2(pData);
  return S_OK;
  }


Controlling Powered Vehicle Mechanisms

Vehicle I/O API enables you to write code to control powered vehicle mechanisms, such as door locks and windows.

To control powered vehicle mechanisms with code

  1. Obtain a reference to the mechanism’s IVioDevice interface.
  2. Set the state of the device using the interface’s SetData method.
  3. Release the reference to the mechanism’s IVioDevice interface.

The following code example shows how to control vehicle door locks.

IVIO_Device     *pDevice;
VARIANT         vLockState;

// Create a lock state IVIO_Device.
hr = CoCreateInstance(CLSID_VIO_LOCK_STATE, NULL, CLSCTX_INPROC_SERVER,
                      IID_VIODEVICE, (PVOID *) &pDevice);
VariantInit(&vLockState);
// Set the state of the locks to toggle.
V_UI4(&vLockState) = VIOLOCK_TOGGLE;
// Call the vehicle I/O API to toggle the power lock.
hr = pDevice->SetData(&vLockState, 2000);
// Free the resources of the VARIANT.
VariantClear(&vLockState);
// Release the reference to the device.
pDevice->Release();


Obtaining Vehicle Specific I/O

The vehicle I/O API enables you to access confidential or proprietary device information. The IVIO_Ioctl interface communicates directly with the vehicle I/O device driver and enables you to access information beyond standard diagnostics. The DoCommand method enables direct communication with the device driver.

The following code example shows how to use an IVIO_Ioctl interface to execute an IOCTL command. The first parameter of DoCommand, IOCTL_CMD_xxx, is a command identifier specific to the device driver. You must obtain this identifier from the provider of the device driver. The second parameter is the address of a buffer that contains driver-specific data for the specified command referenced by IOCTL_CMD_xxx.

IVIO_Ioctl      *pIoctl;
BYTE             bInputBuffer[64];
BYTE                 bReplyBuffer[64];
DWORD            cbReply;

// Create an IVIO_IOCTL interface.
hr = CoCreateInstance(CLSID_VIOIOCTL, NULL, CLSCTX_INPROC_SERVER,
                      IID_VIOIOCTL, (PVOID *) &pIoctl);
// Initialize the input buffer. You must write code to correspond to the
// device driver command you are accessing.
MyInitializeInputBuffer(bInputBuffer);
// Pass the I/O control data to the mini-driver.
pIoctl->DoCommand(IOCTL_CMD_xxx, bInputBuffer, 64, bReplyBuffer, 64,
                  &cbReply);
// Parse the reply.
MyParseReply(pReplyBuffer, cbReply);
// Release the reference to IOCTL.
pIoctl->Release();


Device Sharing and Exclusivity

Applications can share vehicle data or jointly control vehicle mechanisms. For example, multiple applications may use vehicle speed data or control door locks. Multiple applications can also restrict control over, or access to, vehicle mechanisms.

The following code example shows how to maintain exclusive control of vehicle door locks until a specific process is performed. Once the process is performed, the access mode must be reset to shared so that other applications can access the mechanism.

IVIO_Device      *pDevice;

// Create a door lock IVIO_Device interface.
hr = CoCreateInstance(CLSID_VIO_DOOR_LOCKS, NULL, CLSCTX_INPROC_SERVER,
                      IID_VIODEVICE, (PVOID *) &pDevice);
// Set the read access mode to exclusive.
pDevice->set_AccessMode(VIODEVICEMODE_READ, VIODEVACCESS_EXCLUSIVE);

// You can perform any operations on the device that require exclusive
// access now. When done, reset the device access mode to shared access.

pDevice->set_AccessMode(VIODEVICEMODE_READ, VIODEVACCESS_SHARED);
// Release the reference to the device.
pDevice->Release();


Using Positioning and Navigation

An Auto PC provides the driver positioning and navigation assistance by using a Global Positioning System (GPS) receiver. A GPS receiver determines vehicle location by measuring the vehicle distance and angle from multiple GPS satellites that orbit Earth. Your application can use position data to find a detour from a vehicle’s current position to a specific destination when the vehicle’s route is impassable.

Applications written for an Auto PC can use the positioning and navigation API (PNAPI) to enable communication between an application and a GPS device. PNAPI is implemented as a COM object. The methods available for handling GPS devices are exposed through the IPosNav interface. These methods enable an application to perform the following:

  • Communicate with a GPS device
  • Retrieve data from a PNAPI data structure
  • Send data to a GPS device
  • Format data using conversion utilities


Communicating with a GPS Device

You can use the methods of the IPosNav interface to communicate with a GPS device.

To communicate with a GPS device

  1. Initialize COM and obtain a handle to an IPosNav interface.

    The following code example shows how to do this:

    HRESULT hResult = CoCreateInstance(CLSID_PosNav, NULL,
                                   CLSCTX_INPROC_SERVER, IID_IPosNav,
                                   (LPLPVOID) &pPosNav);
  2. Call FindDevices to obtain a list of installed GPS devices, then select a device to use.

    The following code example shows how to do this:

    hres = pPosNav->FindDevices(&pDevice, &dwNumDev);
if(FAILED (hres) || dwNumDev == 0)
  {
  pPosNav->Release();
  // Insert error handling here.
  }

// Call your selection function to choose one device.
PNDEVICE *pDeviceOfChoice = MySelectDevice(pDevice);
  3. Call OpenDevice to open the selected device for communication.

    The following code example shows how to do this:

    hres = pPosNav->OpenDevice(&hPNAPI, pDeviceOfChoice);
  4. Call DeleteDeviceList to delete the device list after the selected device is open.

    The following code example shows how to do this:

    pPosNav->DeleteDeviceList(pDevice);
if(FAILED (hres))
  {
  g_pPosNav->Release();
  // Insert error handling here.
  }
  5. Call StartCall to retrieve data from the device.
  6. Call CloseDevice to close the device.

    The following code example shows how to do this:

    hres = pPosNav->CloseDevice(hPNAPI);
// Release the interface.
pPosNav->Release();


Retrieving and Sending GPS Data

The GPS returns the following data:

  • Position, velocity, and time
  • Accuracy of data
  • Device status and settings
  • Almanac data, such as data that describes the satellite orbit

You can retrieve this data by using the StartCall method to fill PNAPI structures at specified intervals. You then access the required data from these structures. This approach supplies instant data, but the data might be obsolete if not updated frequently.

To get data from a PNAPI structure

  1. Call StartCall to request that data be placed in PNAPI structures.

    This approach specifies which structures to update and how frequently to update them. You have the following update options:

    • Update structures once
    • Update structures at specified intervals
    • Update structures as rapidly as the GPS device can produce them
  2. Call GetData to retrieve data as required.
  3. Call StopCall to terminate updates.

To send data to a GPS device

  1. Use the SetData method to send data, such as time or position.
  2. Use the SetData method to send configuration data to the registry.

    Do not alter almanac data; it contains GPS satellite location data.

To format data using the conversion utilities

  1. Retrieve data from a PNAPI structure.
  2. Convert the data to the appropriate format.

    The following table shows the conversion methods that you can use to transform data between different formats.

Method
Description
DegreesToRadians | Converts latitude, longitude, and altitude data from degrees to radians
RadiansToDegrees | Converts latitude, longitude, and altitude data from radians to degrees
BearingToVelocity | Converts one bearing and two speeds to east, north, and up velocities
VelocityToBearing | Converts east, north, and up velocities to one bearing and two speeds
PNTMToWintm | Converts time from the format specified by the PNAPI PNTM structure to the format specified by the Microsoft® Windows® CE SYSTEMTIME structure
WintmToPNTM | Converts time from the format specified by the Windows CE SYSTEMTIME structure to the format specified by the PNAPI PNTM structure


Using the Address Book API

Address Book is an application that enables a user to save addresses, telephone numbers, and other contact information in an Auto PC running Microsoft® Windows® CE for the Auto PC. With Address Book, a user can dial a cellular phone number or look up an address. Address Book stores the information in Contacts, the Windows CE personal information manager (PIM) database.

The Address Book API is a simplified interface to a device’s Contacts database. It is a set of wrapper functions built around the Contacts database API. A wrapper function is a function that provides a simple interface to another function, for example by changing the order of some parameters or by interpreting the return code. The Address Book API enables youto display Address Book dialog boxes that allow a user to read and write records in the Contacts database. However, if you need to use contact information for more complex tasks, or if you do not intend to use dialog boxes, you can use the Contacts database API directly. For example, you must use the Contacts database API to search for or delete records from your application without prompting the user, or to add customized fields to the Contacts database. For more information about working with databases, see the Windows CE Programmer’s Guide in the documentation for the Microsoft® Windows® CE Platform SDK for Auto PCs.

The following table shows the Address Book API functions and their descriptions.

Function
Description
abOpen | Starts Address Book and opens the Contacts database
abRead | Reads a specified record from the Contacts database
abWrite | Updates an existing record or creates a new record in the Contacts database
abDialog | Displays one of nine predefined dialog boxes on an Auto PC screen, and returns the results of the user interaction
abClose | Quits Address Book


Opening and Closing Address Book

You must call abOpen before you can use other functions. Pass it a pointer to IfmManage. The following code example shows how to get the interface pointer, and how to open and close Address Book.

#include <asfc.h>
#include <abapi.h>

// . . .

IfmManage        *pFMM;        // The Forms Manager object
HRESULT             hr;            // A result handle
hr = CoCreateInstance(CLSID_FMMANAGE, NULL, CLSCTX_INPROC_SERVER,
                        IID_FMMANAGE, (PVOID *) &pFMM);
if (FAILED(hr)) {
        return E_FAIL ; //
}

abOpen(pFMM); // Open the Contacts database using the Address Book API.

// . . . You can call other Address Book API functions now.

abClose(); // Close the Contacts database using the Address Book API.

return S_OK ;


Using Dialog Boxes

All user interaction in the Address Book API is performed through abDialog. This function takes a pointer to an ABDIALOGINFO structure as its only parameter. The structure is used to pass in arguments and to get results back. As its return value, abDialog returns an HRESULT.

Before calling abDialog, you must set up an ABDIALOGINFO structure with the initial dialog box that you want to show and any other information that that initial dialog box requires.

The following table shows the available initial dialog boxes.

Initial view
Description
Dialog box
ABV_MAINVIEW | Displays the Address Book List dialog box with an index and with the view set to the current contact
ABV_LOCATE | Displays the Address Book List dialog box with an index, and sets an Auto PC mode to “locate.” The user can now say a custom command to find a contact.
ABV_CARDPHONE | Displays the card view showing the Telephone tab
ABV_CARDHOME | Displays the card view showing the Home Information tab
ABV_CARDWORK | Displays the card view showing the Work Information tab
ABV_DIAL | Displays the Dial dialog box, which asks the user if an Auto PC should dial the preferred telephone number for the current contact. If the user says No, the display returns to the ABV_CARDPHONE view.
ABV_RECEIVE | Displays the Receive Address dialog box with an Auto PC looking for an infrared connection
ABV_SEND | Displays the Send Address dialog box with an Auto PC attempting to send a specified number of contacts beginning at the current contact
ABV_NEW | Displays the New Entry Wizard form.

For all views except ABV_RECEIVE and ABV_NEW, set the object identifier (CEOID) of the record that you want to display in the CEOID field of the ABDIALOGINFO structure. If you use ABV_SEND, you must set the number of records to transmit and specify the CEOID of the first record. For ABV_MAINVIEW, ABV_LOCATE, and ABV_CARD*, you can set a caption to display at the top of the screen.

In all cases, you can restrict the user’s ability to navigate to other screens by setting the ABE_* flags in the dwEnabled member of the ABDIALOGINFO structure. For example, you can block a user from deleting a record by not enabling navigation to the Delete dialog box in Address Book.

The structure returns the CEOID of the last contact record the user accessed and the identifier of the last view the user accessed.

For a code example that uses abDialog, see Reading and Writing Records.


Reading and Writing Records

You can read and write Address Book records by calling abRead and abWrite. Both functions take the CEOID of the record you want to read or write as their first parameter, and return a HRESULT that indicates success or failure.

To read a record using abRead

  1. Specify the CEOID of the record to read, or specify NULL to read the current record.
  2. Specify the number of properties to read from this record.

    This parameter is also used to return the number of properties actually read.

  3. Specify an array of HPR_* identifiers that indicates the properties to retrieve.
  4. Specify a pointer to an array of CEPROPVAL structures that will receive the properties read.
  5. Call abRead.
  6. Check the return value to verify if the call succeeded.

To create or update a record using abWrite

  1. Specify the CEOID of the record to update, or specify NULL to create a new record.
  2. Specify the number of properties to write.
  3. Specify a pointer to the array of CEPROPVAL structures that contain the properties to write.
  4. Call abWrite.
  5. Check the return value to verify if the call succeeded.

The following code example shows how to call abDialog to have the user find a record, and how to call abRead to read two properties from the selected record.

HRESULT            hr;
ABDIALOGINFO        abDI;
static char        sCaption[80] = “Where do you want to go today?”;

// Set the caption to use at the top of the screen.
abDI.bstrMainFormCaption = &sCaption;

abDI.ceoid = NULL; // Do not use a default record.

// Set the initial view to be the Address Book List dialog box
// and put an Auto PC into locate mode.
abDI.wInitView = ABV_LOCATE;

// Make an Auto PC behave as if it were put
// into locate mode by voice commands.
abDI.dwEnabled = ABE_TTS ;

hr = abDialog(&abDI); // Enable the user to pick a contact.

if (SUCCEEDED(hr))
{
    // The user has picked a contact. Read the record’s properties.
    // The list of properties to read
    CEPROPID rgidProps[] = { HHPR_GIVEN_NAME, HHPR_SURNAME };

    // The pointer in which abRead returns a pointer to the list of
    // properties that were read
    PCEPROPVAL prgProps = NULL;

    // The number of properties to read
    WORD cProps = sizeof(rgidProps)/sizeof(CEPROPID);

    hr = abRead(abDI.ceoid, &cProps, rgidProps, &prgProps);
    if(SUCCEEDED(hr))
    {
        // Copy the first name to m_bstrName.
        wcscpy(m_bstrName, prgProps->val.lpwstr);

        prgProps++;        // Go to the next property.

        // Copy the last name to m_bstrlastname.
        wcscpy(m_bstrLastName, prgProps->val.lpwstr);
    }
    else hr = E_FAIL;
}

return;


Adding Control Panel Applications

Control Panel applications configure and review system-wide settings, such as sound schemes, clock forms, passwords, and regional settings. A user can change settings when the system starts and during normal operation. You can use settings from the Control Panel applications that are part of Microsoft® Windows® CE for the Auto PC or write additional Control Panel applications to meet the application needs.

When a Control Panel application starts, it searches the Windows directory for any files with a .cpl extension. The Control Panel displays all applications with .cpl extensions. If the Control Panel fails to load a particular .cpl file, this file is skipped and the remaining applications are loaded. If an application has been updated during run time, Control Panel detects this and loads the updated application.

The following table shows Control Panel applications included with Windows CE for the Auto PC.

Application
File name
Description
About Auto PC | Aboutapc.cpl | Provides information that includes the system copyright, memory information, battery power status, and system information, such as, processor type. It also informs the user of installed PC cards and what the respective software version number.
Backup and Restore | Backrest.cpl | Initiates a file system backup or restore operation. It is a password-protected application. If a password is set, password validation forms appear when the application starts. Backup and Restore is the only way for a user to back up volatile data in RAM.
Clock | Clock.cpl | Enables users to set clock display options such as current date, time, time zone, and daylight savings time
Display | Display.cpl | Toggles the backlight between bright and dim
Password | Password.cpl | Enables a user to set or clear a password for access to information on an Auto PC
Regional Setup | Regset.cpl | Enables the user to specify regional settings
Remove Program | Uninstal.cpl | Removes an application from RAM
Sounds | Sounds.cpl | Enables the user to customize audio output
Speech Commands | Speechcmd.cpl | Enables a user to select options for speech recognition and TTS
Timeout | Timeouts.cpl | Enables a user to set timers

Your application can alter or access data from some of these Control Panel applications. For example, you can install a custom clock form, access settings in regional setup, or install a new sound scheme.


Installing a Custom Clock Form

The Clock application enables a user to set clock display options such as current date, time, time zone, and daylight savings time. A user enables the Clock application by setting the Activate In option to any setting other than Never, or by saying the speech command Clock.

When active, Clock supports the Read speech command, which results in audible speech feedback of the time, day, and date. A user can also say “What time is it?” to get the time, day, and date at any time, even if Clock is not activated.

When Clock is active, it is in the foreground. When a user presses any key except the VOLUME UP, VOLUME DOWN, or MUTE key, Clock is dismissed and control returns to the previously active application.

The Clock application, when enabled, shows the clock form after a period of inactivity. A clock form is an .scr file identified by a registry entry. To replace the existing clock form, install your own .scr file.

The following illustration shows the default clock form displaying the current time and date.

If your application should not be interrupted, you may temporarily disable the Clock application while your application has control. You can also create and install your own clock form.

To create and install a clock form

  1. Write an executable application.
  2. Rename the .exe file as a screen saver file with an .scr extension.

    –Or–

    Compile the file as an .scr file.

  3. Design your install program to copy the .scr file to the Windows directory.


Accessing Settings in Regional Setup

Regional Setup enables the user to specify regional settings. The following table shows the Regional Setup options available to a user.

Option
Description
Currency | U.S. dollars or Canadian dollars. U.S. dollars is the default setting
Date style | Short date format or long date format
Distance | Miles or kilometers. Miles is the default setting.
Time format | 12-hour or 24-hour
Time style | h:mm:ss tt, hh:mm:ss tt, h:mm:ss, or hh:mm:ss
Volume or fuel | Gallons or liters. Gallons is the default setting.

The regional settings information is stored in the registry. Your application can retrieve the settings for currency and volume.

To retrieve the currency or volume information

  • Access the following registry keys:
    Currency:
    HKEY_CURRENT_USER\SYSTEM\RegionalSettings\Currency

    The value is 0 for Dollars (U.S.), or 1 for Dollars (CAN).

    Volume (Fuel Measurement):
    HKEY_CURRENT_USER\SYSTEM\RegionalSettings\Fuel

    The value is 0 for Gallons (U.S.), or 1 for Liters.


Installing a Custom Sound Scheme

The Sounds control panel application enables the user to customize audio output. The following table shows Sounds options available to a user.

Option
Description
Key feedback | Enables a user to choose more or less feedback when using faceplate keys to navigate the Start menu
Computer voice | Enables a user to set text-to-speech (TTS) pitch, speed, and volume
Sound scheme | Enables a user to select a specific sound scheme if multiple sound schemes are loaded
Speech feedback | Enables a user to choose more or less speech feedback when using voice commands

An Auto PC supports various sound events that play waveform (.wav) files. Windows CE for the Auto PC includes one sound scheme loaded into ROM, but you can write other schemes and add them into RAM. A sound scheme is a collection of audio effects, such as clicks and beeps, that associate .wav files with system and application key events. Some uses for sound schemes are:

  • Attention getting cues, for example low fuel
  • Transient events that the driver may miss if displayed on the screen
  • Information the driver may need while his attention is directed to driving such as faceplate key press feedback

The following table shows the sound events in the default sound scheme. Speech Active, Speech Inactive, and Button Hold events have replaced the Windows CE events Remote Network Begin, Remote Network End, and Remote Network Interrupt.

Event
File
Description
Key Click | Keyclick.wav | Plays when a user presses a key. This sound repeats when the key is held, if the application requests; otherwise, it plays once on the initial button down event.
Alert | Asterisk.wav | Plays when the system displays a system message box
Button Hold | Lngkyack.wav | Plays after a long key press, for example when reconfiguring the Start menu
Default | Sysdefault.wav | Generic system sound
Exclamation | Exclamation.wav | Plays when the system displays an exclamation message box
Infrared Begin | Infbeg.wav | Plays at the start of an IrDA transfer
Infrared End | Infend.wav | Plays at the end of an IrDA transfer
Infrared Interrupt | Infintr.wav | Plays when an IrDA transfer is interrupted
Message Box | Hand.wav | Plays when a critical system event occurs
Question | Question.wav | Plays when a question event occurs
Speech Active | Listen.wav | Plays when the speech recognition engine is ready to recognize another word
Speech Confirm | Tone.wav | Plays when the system recognizes a speech command
Speech Inactive | Nolisten.wav | Plays when the speech recognition engine goes to sleep
Startup | Startup.wav | Plays when the system starts

To install a sound scheme

  1. Collect .wav files.

    You can record new files or secure prerecorded files.

  2. Install the .wav files to the device.
  3. Register your sound scheme by including the following Registry keys:
    • HKEY_LOCAL_MACHINE\Snd\Scheme

      “Test Snds” = “Test Scheme”

      Test Snds is the name of your sound scheme. Test Scheme is the name of the sound scheme listed in the Sounds Control Panel application.

    • HKEY_LOCAL_MACHINE\Snd\Settings

      “Test Snds” = dword:0003F020

      The DWORD contains the bit flags that show whether a particular event sound will be played or not. When a sound scheme Sound is chosen, the event sound can be turned on or off. The on or off state of an event sound is stored in bits from 0 through 18 of the DWORD. The state of the key clicks is stored in bits 30 and 31 of the DWORD.

    • HKEY_LOCAL_MACHINE\Snd\Event

      “Test Snds” = multi_sz:”asterisk”,

      “close”,
      “critical”,
      “default”,
      “empty”,
      ““,
      “infbeg”,
      “infend”,
      “menupop”,
      “menusel”,
      “openprog”,
      “question”,
      “listen”,
      ““,
      “tone”,
      “ingkyack”,
      “startup”,
      “WindMin”

      HKEY_LOCAL_MACHINE\Snd\Event contains the names of the .wav files. You must have 19 entries. If you do not want to associate some event with a .wav file, enter a blank entry.

After your application has entered the correct Registry keys, Sounds handles switching sound schemes and turning sound on and off.


Adding a Control Panel Application

This section describes how you can add an application to the Control Panel either as a stand-alone application, or as an extension of another application.

The code examples are part of a complete sample application, Sysinfo.dsp, included in the SDK. Sysinfo.dsp creates a display-only Control Panel application that provides information about system memory.

In Sysinfo.dsp, the three .cpp files are:

C++ files
Description
Syssink.cpp | Implements the application message sink
Sysapp.cpp | Implements the application CSysInfoApp class
Sysmain.cpp | Provides the entry point into the application

To create a Control Panel application

  1. Call CoCreateInstance to create an instance of a Forms Manager.
  2. Call LoadFormResource to load a form from a resource file.
  3. Create a message sink.
    • Implement a COM object with IASEventSink, IASClassMsgSink, IUnknown and IDispatch interfaces.
    • Create a function to handle VK_ESCAPE key messages.
  4. Call DllMain to create a DLL that is the entry point to the application and handles all Control Panel messages.
  5. Use the CALLBACK CplApplet prototype to create a callback function.
  6. Compile your application as a .cpl file instead of a .dll file.

    Design your application install program to copy your .cpl file into the Windows directory.

The following table show the messages the application callback function must process.

Message
Description
CPL_INIT | Sent to a Control Panel application to prompt it to perform global initialization, especially memory allocation. Returns 1 when it succeeds.
CPL_GETCOUNT | Sent to a Control Panel application to retrieve the number of applications supported by the application. Returns the number of applications.
CPL_NEWINQUIRE | Sent to a Control Panel application to request information about a dialog box that the application supports
CPL_APCINQUIRE | Requests data from the application
CPL_DBLCLK | Sent to a Control Panel application when the user double-clicks an icon in the Control Panel
CPL_STOP | Sent once for each application when the application that controls the Control Panel closes
CPL_EXIT | Sent once to a Control Panel application before the controlling application releases the DLL that contains the application

The following code example shows how to create a message sink that handles VK_ESCAPE messages.

STDMETHODIMP
CSysInfoSink::HandleKeyPress(IDispatch *pdispControl, long lKeyDown)
{
   switch(lKeyDown)
   {
    case VK_ESCAPE:
       // Send a quit message to the current thread.
       PostThreadMessage(GetCurrentThreadId(), WM_QUIT, 0, 0);
       return S_OK; // Returns S_OK if message should stop here
   }

   return S_FALSE; // Returns S_FALSE, if the message should continue
                   // down the message path
}

The following code example shows how to create a callback function that processes Control Panel messages for Sysinfo.dsp.

LONG CALLBACK CPlApplication(HWND hwndCPL, UINT uMsg, LONG lParam1, LONG
                             lParam2)
{
    DEBUGMSG(ZONE_FUNCTION,(TEXT("+CPlApplication(0x%x, 0x%x, 0x%x,
             0x%x)\r\n"), hwndCPL, uMsg, lParam1, lParam2));

   int iStringLen;
   NEWCPLINFO* pCPLInfo;
   APCCPLINFO* pAPCInfo;

    switch (uMsg)
    {
    case CPL_INIT:              // The first message received from
                                // Control Panel.exe is sent once.
        return TRUE;                // Return success

    case CPL_GETCOUNT:          // The second message is sent once.
        return 1;               // Only one application is in this DLL.

    case CPL_NEWINQUIRE:           // Query for information on the
                               // application.
        pCPLInfo = (NEWCPLINFO*) lParam2;            // Where to
                                                     // put inquiry
                                                     // information
        memset(pCPLInfo, NULL, sizeof(NEWCPLINFO));  // Clear out
                                                     // inquiry
                                                     // structure

        // Fill NEWCPLINFO with required information
        pCPLInfo->dwSize  = (DWORD) sizeof(NEWCPLINFO);

        // The display cpl supports a faceplate, but not a VGA screen.
        pCPLInfo->dwFlags = CPL_DISPLAY_FACEPLATE | CPL_DISPLAY_NOVGA;

        // Load the icon that Control Panel uses.
        pCPLInfo->hIcon   = LoadIcon(g_hInst,
        (LPWSTR)MAKEINTRESOURCE(ICON_APP_SHELL));

        // Load the application name into NEWCPLINFO.szName
        // with a maximum of 32 characters.
        iStringLen = 32;
        LoadString(g_hInst, STR_APP_SHELL_NAME, pCPLInfo->szName,
                   iStringLen );

        if( pCPLInfo->hIcon == NULL || pCPLInfo->szName == NULL )
          {
            DEBUGCHK(0);
            return E_FAIL;    //Return Error.
          }
          return NOERROR;

    case CPL_APCINQUIRE:
        pAPCInfo = (APCCPLINFO*) lParam2;
        memset(pAPCInfo, NULL, sizeof(APCCPLINFO));

        // Fill APCINQUIRE with the required data.
        pAPCInfo->dwSize = (DWORD) sizeof(APCCPLINFO);

        // Load the application name into APCCPLINFO.szTTSName with a
        // maximum of 32 characters.
        iStringLen = 32;
        LoadString(g_hInst, STR_APP_SHELL_NAME, pAPCInfo->szTTSName,
                   iStringLen );
        return NOERROR;

/***********************************************************************
*CPL_DBLCLK message
*   This application should act just as it would in a WinMain.
*   Create a message loop, a Forms Manager, a form, and so on.
----------------------------------------------------------------------*/
    case CPL_DBLCLK:
        MSG     msg;

        // Create a new application class instance.
        g_pApp = new CSysInfoApp(g_hInst);
        if( g_pApp == NULL )
          {
            DEBUGCHK(0);
            return FALSE;
          }

        if(FAILED(g_pApp->Init()))
          {
            DEBUGCHK(0);
            delete g_pApp;
            return FALSE;
          }

    // Start a message loop.
        while (GetMessage(&msg, NULL, 0, 0))
        {
            if (msg.hwnd)
            {
                DispatchMessage(&msg);
            }
        }

        delete g_pApp;
        return TRUE;

    case CPL_STOP:              // Sent once per application before
                                // CPL_EXIT
    break;

    case CPL_EXIT:             // Sent once before FreeLibrary called
    break;

    default:
    break;
    }

    DEBUGMSG(ZONE_FUNCTION,(TEXT("-CPlApplication(0x%x)\r\n")));

    return TRUE;
}


Writing Help

Microsoft® Windows CE® for the Auto PC provides user Help through visual Help that displays on the screen and voice Help through prerecorded speech or text-to-speech (TTS). Visual Help provides information on using applications and is available by pressing the HELP key on the faceplate. Voice Help provides information on using an application speech commands, and is available by saying What can I say? and Help.

Visual Help and voice Help are context-sensitive only. In visual Help, the context is usually the entire screen, because the screen has no focus to provide a specific context. Visual Help for a context can contain an index of topics, and users can browse available topics.

In voice Help, the context is the active speech commands. Voice Help has two parts: long voice Help, which provides task-based information on speech commands, and short voice Help, which provides a list of available speech commands. Windows CE for the Auto PC builds short voice Help automatically from prerecorded speech templates you install for the active speech commands for your application. You must provide long voice Help strings for each available application speech command. Windows CE for the Auto PC reads the strings for the active speech commands when the user requests long voice Help.

To provide visual Help for your application, you must create visual Help files, then provide function calls to these files for each form that requires Help. To provide voice Help for your application, you must create long voice Help strings for each speech command available in your application and include them in your application’s resource files.


Visual Help

Visual Help provides task-based information for a context on an Auto PC screen. Visual Help must have at least one topic, or it can have multiple topics and one index. The character set must be Unicode, and the first word must be the Unicode byte order mark 0xFEFF.

A visual Help topic has a title bar that describes the task followed by procedures for accomplishing the task. Users pick a topic by pressing the UP ARROW and DOWN ARROW keys on the faceplate, then pressing the ENTER key. The following table shows the characteristics of an effective visual Help topic.

Topic feature
Description
Title | Matches the topic named in the index
Line length | Has a line limit of about 30 characters, and up to three lines. Help scrolls topics longer than three lines. Test text on an emulator or a device to ensure that formatting is adequate.
Bitmaps | Supports small inline bitmaps with a maximum size of 40 x 11 pixels, as well as full-screen bitmaps with a maximum size of 223 x 44 pixels

A visual Help index looks and functions like an option list for an application. An index has a title bar followed by a list of jumps to the topics available for that context. Indexes cannot call other indexes.

The following table shows the characteristics of an effective visual Help index.

Index feature
Description
Title | Describes a Help topic and includes the words “Help Tips,” for example, “Address Book Help Tips.”
Topic jump line length | Has a line limit of 23 characters. The default font is Tahoma Bold, 13 point. Test text on an emulator or a device to ensure lines do not wrap.
Index | Lists the topics available for the device context. For usability, limit the number of topics provided for each device context.
Bitmaps | Does not support bitmaps


Bitmaps

Visual Help uses inline bitmaps and full-screen bitmaps. The following table shows the characteristics of these bitmaps.

Bitmap
Size (width by height)
Description
Inline | 40 x 11 pixels maximum | Includes text. Bitmap is placed on a black background.
Full-screen | 223 x 44 pixels exactly | Does not include text. The bitmap uses the entire screen for the topic.

All bitmaps must use the eight-color palette supported by an Auto PC display. However, they must be saved as 16-color bitmaps; this includes monochrome (black and white) bitmaps. The following table shows the supported colors and their common uses.

Color
Use
White | Editable text
Black | Background
Cyan | Non-editable text and unselected items
Magenta | Not used
Red | Alerts and warnings
Green | ENTER key and enabled items
Yellow | Selected items
Blue | Unavailable or unselected items

All bitmaps must be installed in the same directory as your application executable file.

The following table shows the bitmaps included with Windows CE for the Auto PC.

Bitmap
Image
Indicates
Wince.bmp | START key
Updwn.bmp | UP ARROW and DOWN ARROW key
Lftrt.bmp | LEFT ARROW and RIGHT ARROW key
Entr.bmp | ENTER key
Lftvce.bmp | Left speech command quotation mark
Rgtvce.bmp | Right speech command quotation mark
Note.bmp I’m ready beep (single note)
I’m listening beep (double note)
Asterisk.bmp | ASTERISK key
Pound.bmp | # key
Backi.bmp | BACK key
Help.bmp | HELP key
Menu.bmp | MENU key
Mute.bmp | MUTE key
Numkeys.bmp | Number keys


Authoring Indexes and Topics

Visual Help highlights complex or unusual application features. It does not need to discuss every task a user can perform in a specified context.

To create effective visual Help:

  • Use the specified HTML tags as described in this section.
  • Where possible, limit topics to three lines to avoid scrolling.
  • Limit indexes to 10 topics or less.
  • Use a title and bitmaps to provide additional information.
  • Use the bitmaps provided for faceplate keys.
  • When you use a bitmap, provide alternate text for the TTS engine.

Windows CE for the Auto PC uses a subset of standard HTML tags for authoring visual Help. Using this subset ensures that visual Help displays correctly on an Auto PC. Each topic or index is authored in a separate HTML file with an .html extension. The following table shows the HTML tags that visual Help supports.

HTML
Description
<HTML></HTML> | Begins and ends the file
<HEAD></HEAD> | Defines the file heading
<TITLE></TITLE> | Defines the title for Help indexes and topics
<BODY></BODY> | Defines the body of the file
<IMG> | Positions bitmaps; Only the SRC and ALT attributes are supported
<A HREF></A> | Jumps to topics from the Help index
<MENU></MENU> | Lists the Help index jumps
<LI></LI> | Lists each jump
<BR> | Breaks a topic text line
<TABLE></TABLE> | Creates a table.

The Help index is a list of links to visual Help topics for an application screen. A visual Help topic can be text only, text with inline bitmaps, a full-screen bitmap, or a table with bitmap bullets or numbered steps. Windows CE for the Auto PC automatically adds navigational arrows to the visual Help screen based on the active keys for an index or topic.

Inline bitmaps for faceplate keys are included in Windows CE for the Auto PC and can be used in Help. For the bitmap file names, see the section “Bitmaps.”

All HTML files and bitmaps must be installed in the same directory as the application executable file.

To code a Help index

  1. Enclose the index title in <TITLE> tags.
  2. Enclose the list of links in <MENU> tags.
  3. Use an <LI> tag to start each link as a list item.

The following code example show how to code an index in HTML.

<HTML>
<HEAD>
<TITLE>Radio Help Tips</TITLE>
</HEAD>
<BODY>
<menu>
<li><a href="rad-main-am.html">Change radio bands</a>
<li><a href="rad-main-intro.html">Seek for a station</a>
<li><a href="rad-main-manual.html">Enter station numbers</a>
<li><a href="rad-main-preset.html">Add a preset station</a>
<li><a href="rad-main-goto-preset.html">Go to a preset station</a>
<LI><a href="com-goto-audio.html">Change audio settings</a>
<li><a href="rad-main-off.html">Turn off the radio</a>
<Li><a href="com-menu-show.html">Show program options</a>
<Li><a href="com-menu-dismiss.html">Hide program options</a>
</menu>
</BODY>
</HTML>

To code a text Help topic

  1. Enclose the topic title in <TITLE> tags.
  2. Enclose the topic text in <BODY> tags.

    Be sure no spaces or carriage returns appear before the first line of text.

  3. Check that lines of text wrap correctly on the emulator or a device, adding a <BR> tag where necessary to force wrapping.

To code a Help topic with inline bitmaps

  1. Enclose the topic title in <TITLE> tags.
  2. Enclose the topic text in <BODY> tags.

    Be sure no spaces or carriage returns appear before the first line of text.

  3. Use an <IMG> tag to include inline bitmaps.

    In the <IMG> tag, provide the source file (SRC) and alternate text strings (ALT). Be sure the alternate text you provide makes a complete sentence for the TTS engine.

  4. Use Nbsp.bmp to include a space after a bitmap.
  5. Check that lines of text wrap correctly on the emulator or a device, adding a <BR> tag where necessary to force wrapping.

The following code example shows how to code a topic with text and inline bitmaps in HTML.

<HTML>
<HEAD>
<TITLE>Change to AM or FM</TITLE>
</HEAD>
<BODY topmargin=0 leftmargin=0>
Press <img src="entr.bmp" alt="the enter key">.<br>
Or, say <img src="lftvce.bmp">AM<img src="rtvce.bmp"><img src="nbsp.bmp"> or <img src="lftvce.bmp">FM<img src="rtvce.bmp">.
</BODY>
</HTML>

Note This example shows line breaks for clarity. The HTML engine does not support line breaks or spaces before the first line of text in the topic body.

To code a Help topic with a full-screen bitmap

  1. Enclose the topic title in <TITLE> tags.
  2. Include one or more full-screen bitmaps in the <BODY> tag. In the <IMG> tag provide the source file (SRC) and alternate text strings (ALT). Be sure the alternate text you provide makes a complete sentence for the TTS engine.

The following code example shows how to code a topic that is a full-screen bitmap in HTML.

<HTML>
<HEAD>
<TITLE>CD Player keys</TITLE>
</HEAD>
<BODY topmargin=0 leftmargin=0>
<img src="dp-main-keys-1.bmp" border=0 width=223 height=44 alt="To play or pause, press Enter. To enter a track, press the number keys.">
</BODY>
</HTML>

Note You can perform preliminary testing of the visual Help in an Internet browser.

To code a Help topic with numbered steps or bullets

  1. Enclose the index title in <TITLE> tags.
  2. Enclose a two-column table in <BODY> tags.

    Using <TABLE> tags provides a consistent text indent. Specify the width of the table as 220 and the width of the columns to add up to 220. For numbered steps or bullets, use column widths of 15 and 205.

  3. Place a bitmap bullet or step numbers in the left column, and place the procedure text in the right column.

    Do not use symbols as bullets.

  4. Use an <IMG> tag to include inline bitmaps.

    In the <IMG> tag, provide the source file (SRC) and alternate text strings (ALT). Be sure the alternate text you provide for the TTS engine is a complete sentence.

  5. Use Nbsp.bmp to include a space after a bitmap.
  6. At the end of each step, add the Pau.bmp bitmap with alternate text to force a pause from the TTS engine.

    The Pau.bmp bitmap is 1 x 1 pixel and black and should not be visible in visual Help. The following code example shows how to add this bitmap.

    <img src="pau.bmp" alt="\pau=800\">

    If a numbered step ends with a bitmap, you can add the \pau=800\ code to the end of the alternate text for that bitmap.

  7. Check that lines of text wrap correctly on the emulator or a device, adding a <BR> tag where necessary to force wrapping.

The following code example shows how to code a topic with numbered steps in HTML.

<HTML>
<HEAD>
<TITLE>Go to a program</TITLE>
</HEAD>
<BODY topmargin=0 leftmargin=0>
<TABLE valign=top cellspacing=0 cellpadding=0 BORDER=0 WIDTH=220>
<TR>
<TD valign=top height=44 WIDTH=15>1.</TD>
<TD valign=top height=44 WIDTH=205>Press <img src="wince.bmp" alt="the Start key"><img src="nbsp.bmp"> to move to a program icon.<br>
Or, press <img src="lftrt.bmp" alt="the left and right arrow keys \pau=800\">. </TD>
</TR>
<TR>
<TD valign=top height=44 WIDTH=15>2.</TD>
<TD valign=top height=44 WIDTH=205>Press <img src="entr.bmp" alt="the Enter key"><img src="nbsp.bmp"> to go to that program.</TD>
</TR>
</TABLE>
</BODY>
</HTML>


Adding Visual Help to an Application

There are two ways to implement visual Help in an application. You can associate a help topic or index with an application using the IfmManage::put_HelpContext method, or you can associate a help topic or index with a form using the IASForm::put_HelpContext method. The two put_HelpContext methods use the same parameters.

The following code example shows the syntax for calling a visual Help index or topic file.

put_HelpContext(bstrIndexFile, bstrTopicFile);

To call a Help index

  1. Before your application initializes, call put_HelpContext to call a Help index for an object.

    When you call put_HelpContext, the Forms Manager automatically handles the VK_HELP event.

  2. Call the SysAllocString function to allocate a string and copy the Help index file name into it. The Help files must be in the same directory as your executable file.
  3. SysAllocString returns NULL if there is insufficient memory.
  4. Call put_HelpContext for your application’s IfmManage object, and specify the file name of the Help index.
  5. Call SysFreeString to free the string allocated previously by SysAllocString.

The following code example shows how to set up a Help context with a Help index file by calling put_HelpContext. Again, check the memory allocation return value to ensure it did not fail.

BSTR bstrIndexFile = SysAllocString(L"\\path\\help-index.html");
pManage->put_HelpContext(bstrIndexFile, NULL);
SysFreeString(bstrIndexFile);

To call a Help topic

  1. Before your application initializes, call put_HelpContext to call a Help topic.
  2. Call the SysAllocString function to allocate a string and copy the Help topic file name into it. The Help files must be in the same directory as your executable file.

    SysAllocString returns NULL if there is insufficient memory.

  3. Call put_HelpContext for your application’s IfmManage object, and specify the file name of the Help topic.
  4. Call SysFreeString to free the string allocated previously by SysAllocString.

The following code example shows how to set up a Help context with a Help topic file by calling put_HelpContext. Again, check the memory allocation return value to ensure it did not fail.

BSTR bstrTopicFile = SysAllocString(L"\\path\\help-topic.html");
pManage->put_HelpContext(NULL, bstrTopicFile);
SysFreeString(bstrTopicFile);


Voice Help

Voice Help provides spoken Help for speech commands active in the application. Voice Help includes short voice Help, that provides only a list of the active speech commands using prerecorded speech, and long voice Help, that provides task-based information for each active speech command using the text-to-speech (TTS) engine. A user can stop short and long voice Help by pressing any key on the faceplate or the PTT key.

A user accesses short voice Help by saying What can I say? An Auto PC lists active speech commands by playing waveform (WAV) files that you provide. These files contain a recording of each speech command that is used in your application. These recordings are called prerecorded speech templates. For example, if an application has the speech commands Hot, Warm, and Cool, you could record an 11-kHz, 8-bit mono WAV file for each of these words to create a prerecorded speech template. You could then install the WAV files with your application to provide short voice Help.

For example, an Auto PC reads the following in prerecorded speech for short voice Help for Radio.exe, an AM/FM radio application.

“The speech commands are AM, Preset, Read, Next, Previous, <plus global speech commands>.”

Long voice Help is accessed when the user says Help. You provide strings for each speech command with the text that you want an Auto PC to read to the user. When a user says Help, Windows CE for the Auto PC reads the strings for the speech commands active in the application. The long voice Help strings are read through the TTS engine. They can include code to assist the TTS engine in timing and pronunciation of the string. If you do not provide a string for long voice Help, it is disabled for that speech command.

When writing the strings for long voice Help, limit information to quick, task-based information on the available speech commands. The following text is read in TTS for long voice Help for Radio.exe:

“To change the radio band, say AM or FM. To seek for a radio station, say Next or Previous. To go to a radio preset, say Preset, and then say the number or voice tag. To read back the selected audio setting, say Read.”

The application-specific long voice help is followed by the long voice Help for global commands.


Authoring and Coding Voice Help

The WAV file names for short voice Help and strings for long voice Help are included in the resource file where you specify the speech commands supported by your application.

Note Short voice Help is disabled if you do not provide a prerecorded speech WAV file for a word, or if you have added speech commands that do not have a speaker-independent template, and if these words have not been trained by the user. For more information on speaker-dependent speech commands, see Voice Help for Speaker-dependent Speech Commands.


Specifying Voice Help in a Resource File

You can add text for long voice Help text strings or customize short voice Help in the resource file where you specify the speech commands. Voice Help reads the voice Help strings only for the speech commands that are enabled in the application when the user says What can I say? or Help.

The following code example shows how to specify long and short voice Help.

<speech command identifier> "<speech command>[\tLong Help text string] [\tShort Help .wav file name]"

If you do not specify a string to read, long voice Help is disabled. If you do not specify a WAV file name, short voice Help looks for a WAV file with the same name as the command.

Short voice Help starts with the phrase, “The speech commands are . . .” When you record short voice Help, be sure that it makes sense with this phrase.

To enable long voice Help for a speech command

  • Provide a long help text string when declaring the speech command.

    You provide a long voice Help string when you declare your speech commands. The string is read through the TTS engine.

The following code example shows how to specify long voice Help. Because the short voice Help WAV file is not specified, short voice Help defaults to the WAV file Directions.wav in the Windows directory.

IDS_SPEECH_DIRECTIONS "Directions \tTo go to Directions, say Directions"

To enable short voice Help for speech commands

  1. Create a prerecorded speech template for each speech command by recording an 11-kHz, 8-bit mono WAV file that states, at a minimum, the speech command.
  2. Specify the file name when declaring the speech command only if the WAV file name is different from the speech command. If the WAV file name is exactly the same as the speech command, short voice Help is automatically enabled.
  3. Install the prerecorded speech template WAV files in the Windows directory during installation of your application.

Note You must record and install a WAV file to enable short voice Help.

The following code example shows how to specify a file name for short voice Help. For this example, short voice Help uses the file Dir.wav, rather than the default file Directions.wav.

IDS_SPEECH_DIRECTIONS "Directions \tTo go to Directions, say Directions \tDir"


Combining Voice Help for Related Speech Commands

If you have closely related speech commands, you can combine voice Help for these words into a single string. How you combine them depends on whether the words are mutually-exclusive or inclusive.

For related, but mutually-exclusive speech commands only one speech command is active at a time. For these, add the combined Help text to all of the speech commands. You may want to combine both long and short Help for large groups of related, inclusive speech commands, such as the alphabet.

To combine long voice Help for mutually-exclusive speech commands

  1. Write one long voice Help string that explains the related speech commands.
  2. Repeat this long voice Help string for each speech command referred to.

The following code example shows how to combine long voice Help only and use the default WAV file names, AM.wav and FM.wav, for short voice Help for the speech commands AM and FM.

IDS_SPEECH_AM  "AM \tTo change radio bands, say AM or FM"
IDS_SPEECH_FM  "FM \tTo change radio bands, say AM or FM"

Because only one speech command is available at a time, a user hears this string only once in long voice Help. Because no string is specified for short voice Help, the user hears only the available command.

For speech commands that are related but inclusive, all of the speech commands are available at the same time. For these, add the combined Help text to one command, then disable Help for the rest of the speech commands.

To combine long voice Help for inclusive speech commands

  1. Write one long voice Help string that explains the related speech commands.
  2. Include this long voice Help string for the first speech command referred to only.
  3. Disable long voice Help for all but the first speech command referred to.

The following code example shows how to combine long voice Help only and keep short Help as the default for the speech commands Next and Previous.

IDS_SPEECH_NEXT "Next \tTo go to a different track, say Next or Previous"
IDS_SPEECH_PREVIOUS "Previous \t"    //Disable long voice Help.

Because both Next and Previous are available at the same time, the user hears the string for Next, but not for Previous. Short voice Help lists both Next and Previous because only long voice Help is disabled for Previous.

To combine both long and short voice Help for inclusive speech commands

  1. Write two strings that explain the related speech commands, one for long voice Help and one for short voice Help.
  2. Include both the long and short voice Help strings for the first speech command referred to only.
  3. Disable both long and short voice Help for all but the first speech command referred to.

The following code example shows how to combine both long and short voice Help for the speech commands from A through Z. The second parameter specifies that the WAV file named AtoZ.wav is played for short voice Help for A.

IDS_SPEECH_A  "A     \tYou can say A through Z\tAtoZ"  //Play AtoZ.wav for short Help
IDS_SPEECH_B  "B     \t\t"  // Disable long and short voice Help
IDS_SPEECH_C  "C     \t\t"  // for the rest of the alphabet.
:
IDS_SPEECH_Z  "Z     \t\t"


Disabling Voice Help

You can disable voice Help for a speech command by specifying null strings. Usually, you disable voice Help for a speech command only when the voice Help is included in the string for another speech command.

To disable both long and short voice Help for a speech command

  • Specify a null string, \t, for long and short voice Help.

The following code example shows how to disable long and short voice Help for the speech command Next, and how to disable short voice Help only for the speech command Previous.

IDS_SPEECH_NEXT "Next \t\t"
IDS_SPEECH_PREVIOUS "Previous \tTo go to the previous item, say Previous\t"


Voice Help for Speaker-dependent Speech Commands

If you want to use a speech command that does not have a speaker-independent template, you must have the user train the word. If the word is not trained, the speech command is not included when the user asks for voice Help. If you add a speech command without a speaker-independent template, and the user has not trained the word, short voice Help is disabled and long voice Help defaults to the following string, read after the other long voice Help strings: “You need to train the custom command <command> before you can use it.”


Preparing an Application for Distribution

This chapter describes how to create and test an installation for your application, and how to prepare the installation media.


Creating an Installation Application

The Microsoft® Windows® CE Platform Software Development Kit (SDK) for Auto PCs includes an application called CEIBuild that allows you to produce a CEI file that installs your application to an Auto PC. Along with the CEIBuild the Auto PC SDK contains the necessary include (.h) files necessary to create custom setup DLLs.

Note Using CEIBuild to create application installations is highly recommended, because using CEIBuild ensures the proper installation and uninstallation of an application. In addition, the CEI file must contain all files, components, directories and registry entries that the application uses. If the Auto PC RAM is initialized by a process, an Auto PC attempts to reinstall the application from information contained in backup CEI files. This reinstallation process uses information in the original CEI file to recover files, data, and registry settings, potentially long after the user originally installed the application. An Auto PC recursively saves registry keys under HKEY_CURRENT_USER and directories under My Documents if you created those keys and directories in the CEI file and flagged the keys and directories as containing dynamic data. If you create files, directories, or registry keys in other parts of Auto PC directory and registry key structure and do not reference those files and directories in the CEI file, you will lose those files and directories during operating system recovery or upgrade.

You can use CEIBuild to add files and directories to the Auto PC object store. To facilitate repeated cycles of testing and fixing applications, CEIBuild maintains a link to the original file to allow updating rather than recreating CEI files when the source files change. You define how the installation process handles files when an existing file is detected during installation onto the Auto PC by using one of the following options:

  • Never replace if the file exists.
  • Always replace if the file exists.
  • Replace if newer. (Default)

The Auto PC installation system supports registering COM objects during installation. When you add a DLL that has the DllRegisterServer and DllUnregisterServer entry points, CEIBuild automatically flags the component for self-registration. You can also designate EXE files as self registering. The Auto PC Load program, which reads and executes the data stored in the CEI file generated by CEIBuild, calls the registration entry point or starts the executable program with the /REGSVR registration switch. The Auto PC Load program calls or starts the DLL or .EXE file to allow the update of registration information when the application is removed.

Creating a Shortcut

You can use CEIBuild to specify that a shell shortcut for your application be created during installation. This option is only be available to valid EXE files that meet the following criteria:

  • The ICON resource with ID of 1 contains a 32 x 32 16-color image
  • The ICON resource with ID of 1 also has a 32 x 32 monochrome mask
  • The string resource with ID of 1 contains the application’s friendly name

Note The shell icon must be the resource identifier ICON_APP_SHELL, and must contain 32x32 16-color and mono images. When you create your application’s icon, the 16-color image must be created first.

Updating an Application Version Number

The version information used for installation is the image version defined in the PE file header. CEIBuild ensures that all binaries have a version number in them. In the CEIBuild setup options, you can include a master version number for the entire CEI file. All application components that do not have an image version—those with image version equal to 0.0—are updated to have the master version number when you add those components to the CEI file.

For those modules that you are shipping in multiple products or that you have not changed from previous products, you can set the version number before including the module in a CEI file. Use the /VERSION:major[.minor] switch of the LINK command to set the version number. The major and minor elements of the switch are decimal values between 0 and 65535.

Multiple Use Counting

If the Auto PC Load program attempts to install a file or directory over an existing file or directory, that file or directory is reference counted automatically. During an uninstall, the Auto PC Load program checks for counted files and updates the reference count appropriately.

Speech Templates

CEI Builder allows you to specify a speaker independent template file for installation. The file is installed into the speech engine of the Auto PC during setup and removed during uninstall. The speech engine keeps reference counts for these templates.

Speech Phrases

CEI Builder allows you to specify a text phrase for which there is no speaker independent template. The user trains the phrase during installation and can retrain it later by using the Auto PC control panels in Setup.

Saving Dynamic Data and Registry Information

CEIBuild can create directories and registry keys on the target platform for use by your application. You can mark these directories and registry keys as a destination for the dynamic data in your application. All directories and data contained in marked directories and all registry keys and registry values contained under marked registry keys are saved during upgrade and operating system (OS) updates. These marked directories, data, registry keys, and registry values are removed during uninstallation of your application. If you do no mark these directories and registry keys for saving, all data in these locations is lost during OS upgrades.

Note If your application creates any directories and registry keys that you do not reference in the CEI file, you will lose those files and directories during upgrades. Also, those files and registry keys are not deleted during uninstallation and remain on the operating system.

To mark a directory for saving, choose Application will save dynamic data in this directory/registry key when you create the directory or registry key.

Your application must use marked directories for all user data that you want to save during upgrades or remove during uninstallation. Your application can create directories, files, and registry keys under any parent directories and registry keys marked for saving.


Creating an Installation CD

To create an installation compact disc (CD) for your application, you must copy the following files to the CD:

  • An Autorun.inf file that opens the .cei file.
  • A .cei file containing your application files.

Writing an Autorun script

The syntax of the AutoRun.inf file is similar to win32 desktop systems, but uses an Auto PC-specific section header to allow one piece of installation media to contain autorun components for both desktop operating systems and the Auto PC. To include desktop support, use the standard desktop sections like [autorun].

You need to place an Autorun.inf file in the root of the installation media (CD or CompactFlash™ card). Microsoft® Windows® CE for the Auto PC looks at the following section names of the autorun.inf file:

[AutoPC]
[AutoPC.shx]
[AutoPC.intel]
[AutoPC.mips]
[AutoPC.ppc]
[AutoPC.arm]

The [AutoPC]and [AutoPC.shx] section names are only supported for version 1.0, because all Auto PCs contain a Hitachi SH3 processor for version 1.0.

If a section for the specific Auto PC device processor can be found, it is used and all others are ignored. If there isn't a matching section for the specific processor family, the generic [AutoPC] section is used.

For example, the Clarion Auto PC uses a Hitachi SH3 processor which is part of the SHx processor family. If present, the [AutoPC.shx] section is used when installing to Clarion's Auto PC.

You can include the following items within each section:

Function
Description
open=command line with arguments If you include the open command line, it is passed to the ShellExecute function and all other lines are ignored. If the command line contains an absolute path to a file to be executed — that is, the command line begins with a backslash — the command line is passed unchanged to the ShellExecuteEx function. If not, the path to the autorun.inf is prepended onto the command line before passing it to ShellExecuteEx. This behavior allows you to execute documents located on your media without having to know whether the media is named "\storage card" or "\storage card2" or "\cd dash". If you try to run an EXE or a shortcut, the user is presented with a security warning dialog asking the user to confirm that they want to run it.

If you do not include an open command line, a menu is built with the remaining lines.
title=menu caption | Optional. Specifies the title for the menu.
Item X=menu display text | * Optional. Displays a text string for the menu selection. If item X is not provided, the open X line is displayed.
Open X=menu command line with arguments | * Specifies which file to open when the menu item is selected.
* X can be any number greater than or equal to one, but for memory efficiency reasons X should be kept as small as possible.

To install your application .cei file

  1. Place your application’s .cei file in the root directory on your installation media.
  2. Create an Autorun.inf file.
  3. Under the appropriate autorun sections, include an open command line containing a pointer to your application’s .cei file.

The following example shows an Autorun.inf file that automatically starts the installation of a CEI file:

[AutoPC.shx]
open=example1.cei

The following example shows how to put more than one .cei file installation file on the same installation media:

[AutoPC.shx]
title=MS Arcade
item1=Blackjack
open1=blackjack.cei
item2=Roulette
open2=roulette.cei
item3=Crazy Eights
open3=crazy8.cei

To create nested menus

  1. Place your application .cei files in subdirectories on your installation media.
  2. Place an Autorun.inf file for each application in each subdirectory on your installation media.
  3. Create a root Autorun.inf file that creates a menu to the other autorun.inf files.

The following example shows an Autorun.inf file that calls another Autorun.inf file.

[AutoPC]
title=Microsoft Sampler
item1=Arcade
open1=arcade\autorun.inf
item2=Return of Arcade
open2=retarcade\autorun.inf

The following example shows the Autorun.inf file that is located in the \arcade sub-directory of the installation media: It also shows how to provide multiple processor support on your installation media and have autorun automatically install the correct CEI for the user’s Auto PC device. The autorun code checks for SHx, Intel®, Mips and ARM processor types.

[AutoPC.shx]
title=Arcade
item1=Blackjack
open1=shx\blackjack.cei
item2=Roulette
open2=shx\roulette.cei

[Auto PC.intel]
title=Arcade
item1=Blackjack
open1=intel\blackjack.cei
item2=Roulette
open2=intel\roulette.cei

This autorun.inf file presents the user with a menu where they can go to the Arcade or Return of Arcade menu. If they choose Arcade, the arcade\autorun.inf is run and they see its menu. The user can press the BACK key to return to the main menu.


Testing your Installation

Once you’ve created an installation application, you should test the installation to ensure it runs smoothly and your application functions as expected.

The following procedures outline how to test that your installation is stable and will install reliably on an Auto PC.

To install and debug your application

  1. Build a CEI file containing all application files using CEIBuild.
  2. Create a CD or CompactFlash card that contains the CEI file and a corresponding Autorun.inf file.
  3. Turn on the Auto PC.
  4. Insert the CD or CompactFlash card into an Auto PC.
  5. Follow the instructions that appear on the screen of the Auto PC to install your application.
  6. Use the Windows CE Remote File Viewer to verify the construction of directories and the placement of files.
  7. Use the Windows CE Remote Registry Editor to verify that the installation program updated the registry settings properly.


Testing Uninstallation

In addition to testing your installation, you should also verify that you can remove your application easily without disrupting other applications.

Note Auto PC uses a skeleton CEI file to determine which component to remove. If your application creates files, directories, or registry keys during execution that are not specified in the CEI file, those files, directories, and registry keys are not removed during uninstallation. You may also be unable to recover those files, directories, and registry keys if you restore files from a backup. If your application creates these items at run time, place these items under the directory or registry key in the CEI for which you have specified the dynamic data flag. For version 1.0 of the Auto PC, uninstalling an application does not remove this dynamic data.

To uninstall your application

  1. Select Remove Program in the Auto PC control panels in Setup.
  2. Verify your application name is in the list.
  3. Choose your application and press ENTER.

To verify uninstallation

  1. Use the Windows CE Remote File Viewer to verify that all files and directories are removed.
  2. Go to Remove Programs in Setup to verify application list is updated to reflect the removal of your application.
  3. Use the Windows CE Remote Registry Editor to verify the registry has been updated to reflect the removal of your application.

You may also want to attempt to uninstall your application while it is running by starting it before uninstalling.


Installing and Uninstalling Applications

The Auto PC components described in this section are included in Windows CE for the Auto PC.


Application Installation

The Auto PC Load program reads and executes the data stored in the CEI file generated by the CEI Builder. Auto PC Load performs the following tasks.

  • Creates folders
  • Moves files from the CEI file into the object store
  • Adds registry information
  • Installs speaker independent templates
  • Adds speech phrases to list of phrases that can be trained and invokes training for any phrase not yet trained
  • Invokes pre-entry and post-entry points from the installation DLL provided by the installation developer

The Auto PC Load application also checks the following to ensure proper installation:

  • Error Conditions.

    Auto PC Load detects installation requests that require more memory than is currently available, and informs the user that the Auto PC Load cannot complete the installation if the installation requires too much memory. Memory requirements are calculated from the original list of files that need to be installed on the target device, excluding already installed components with the same version number as the component supplied in the CEI file.

    Auto PC Load also catches installation application errors and informs the user of these errors.

  • Version numbers.

    Auto PC Load performs version checking on all PE (portable executable) file replacements. The version number of the replacement file must be greater than the version number of the original file for Auto PC Load to start the replacement process.

  • Certification.

    Auto PC Load detects components that contain a Auto PC installation certificate. The Auto PC installation certificate indicates that the file may be a valid ROM replacement component. During installation, Auto PC Load validates the certificate and uses version checking to determine if Auto PC Load should replace the component. If all checks pass, Auto PC Load copies the replacement file to the RAM object store. After you reboot the Auto PC, the replacement file supercedes the old ROM component.

    Only Microsoft can distribute certified components. Certified components will be distributed as a part of subsequent SDK packages to allow third party developers access to the latest Auto PC components.

  • Multiple Use Counting.

    When Auto PC Load installs a component, Auto PC Load increments the use count of the component. When Auto PC Load uninstalls a component, Auto PC Load decrements the use count. Auto PC Load uses a scheme that minimizes the number of use counts that must be stored while still ensuring that every installed file—not just every PE file—is subject to use counting.

  • Backup.

    Auto PC Load prompts the user to perform a backup prior to installing or uninstalling any package.

    The backup operation is the same as the standard backup initiated in Setup.

  • Existing Installations.

    If a CEI file is already installed on an Auto PC, one of the following occurs, depending on the version numbers of the two CEI files:

    • If the version number of the previously installed version of the CEI file is greater than the version number of the CEI file that user is trying to install, Auto PC Load displays a warning to the user that the user is trying to install an older version of the package and exits.
    • If the version numbers of the two CEI files are identical, Auto PC Load prompts the user to uninstall the package.
    • If the version number of the previously installed version of the CEI file is less than the version number of the CEI file that user is trying to install, Auto PC Load uses a special upgrade mode to install the new CEI file. The next section describes this special upgrade mode.
  • Upgrading Installations.

    Auto PC Load supports upgrading an installed package (CEI). If Auto PC Load attempts to install a newer version of a previously installed package, Auto PC Load performs a special “upgrade” uninstall of the earlier package. Auto PC Load then performs a normal installation of the newer version. In this special "upgrade" mode, Auto PC Load does not install files or registry values marked as “Never replace” or “Leave Existing Value” in the earlier CEI. This mode leaves these files and registry values intact. If those same files and registry values are specified the same way in the newer CEI, those files and values remain when the new CEI is installed. An application developer should specify these flags only for files and registry values that contain user data. In this way, Auto PC Load preserves an application’s user settings and documents across a version upgrade.

  • Speech Training.

    Auto PC Load makes interface calls to incorporate the information from a speaker independent template file into the speech engine. Auto PC Load removes the template during uninstall.

Custom Setup DLL

You can include custom setup DLLs in your installation. Two DLLs are supported, install and uninstall.

The install custom setup DLL exports the following entry points:

  • install_init()
  • install_exit()

The uninstall custom setup DLL exports the following entry points:

  • uninstall_init()
  • uninstall_exit()

Note If you provide the uninstall custom setup DLL, this DLL is saved along with the uninstall script in the \Windows\uninstall directory. The install custom setup DLL is never retained after installation is complete.


Application Uninstallation

When the user attempts to uninstall a package by selecting the package from the Setup application for removing programs, the Setup application invokes the Auto PC Load program. Auto PC Load operates on a skeleton CEI file that was created during the original installation and placed into the windows\uninstall directory. Auto PC Load performs the reverse process from the original installation by doing the following tasks:

  • Deletes any files that Auto PC Load installed
  • Deletes any directories that Auto PC load created during the installation but are now empty
  • Deletes any registry values that Auto PC Load created during install
  • Deletes any registry keys that Auto PC Load created during the install that are now empty
  • Uninstalls speaker independent templates that Auto PC Load installed. The speech engine performs reference counting on these templates.
  • Removes speech phrases that Auto PC Load added during installation – deletes any speaker dependent phrases that were trained if the phrase now has a zero reference count.
  • Invokes pre-entry and post-entry points from the uninstallation DLL provided by the installation developer
  • If a ROM file had been superceded by a file that just got uninstalled, a reboot may occur to reinstate the ROM file.


IASClassMsgSink

This interface provides methods used to subclass the messaging and drawing functions of IASControl.

Method
Description
IASClassMsgSink::HandleClose | Enables a control to notify its sink when a form closes the control.
IASClassMsgSink::HandleDraw | Enables a control to notify its sink when drawing takes place.
IASClassMsgSink::HandleGotFocus | Enables a control to notify its sink when the control gains focus.
IASClassMsgSink::HandleKeyPress | Enables a control to notify its sink when a character key is pressed.
IASClassMsgSink::HandleLostFocus | Enables a control to notify its sink when the control loses focus.
IASClassMsgSink::HandleMessage | Enables a control to notify its sink when a message is received.
IASClassMsgSink::HandleStart | Notifies the application that the control has started.

Remarks

The IASClassMsgSink interface extends the IDispatch interface.

To use this sink, create an object that exposes the IASClassMsgSink interface and place a pointer to it in the IASControl ClassMsgSink property. The control passes information on to the appropriate IASClassMsgSink method for processing. To implement only a subset of the IASClassMsgSink methods, have the remainder return S_FALSE. This indicates to the IASControl method that no processing has taken place.

See Also

IASControl


IASClassMsgSink::HandleClose

This method enables a control to notify its sink when a form closes the control.

Syntax

HRESULT HandleClose( IDispatch *pdispControl );

Parameters

pdispControl
Pointer to the control that is calling the method.

Return Values

NOERROR indicates that the sink handled the message to close the control. S_FALSE indicates that the sink did not handle the message to close the control. If an error occurs, the appropriate HRESULT value is returned.

Remarks

A control invokes this method when its own IASControl::Close method is invoked. This takes place when a form shuts down a control. Processing subsequently stops and any needed shutdown procedures are performed.

See Also

IASControl::Close, IASClassMsgSink::HandleStart


IASClassMsgSink::HandleDraw

This method enables a control to notify its sink when drawing takes place.

Syntax

HRESULT HandleDraw( IDispatch *pdispControl, OLE_HANDLE hDC );

Parameters

pdispControl
Pointer to the control that is calling the method.
hDC
Handle to a device context (DC).

Return Values

NOERROR indicates that the sink handled the message. S_FALSE indicates that the sink did not handle the message. If an error occurs, the appropriate HRESULT value is returned.

Remarks

A control invokes this method when its own IASControl::Draw method is invoked.

See Also

IASControl::Draw


IASClassMsgSink::HandleGotFocus

This method enables a control to notify its sink when the control gains focus.

Syntax

HRESULT HandleGotFocus( IDispatch *pdispControl );

Parameters

pdispControl
Pointer to the control that is calling the method.

Return Values

NOERROR indicates that the sink handled the message. S_FALSE indicates that the sink did not handle the message. If an error occurs, the appropriate HRESULT value is returned.

Remarks

A control invokes this method when its own IASControl::GotFocus method is invoked.

See Also

IASControl::GotFocus, IASClassMsgSink::HandleLostFocus


IASClassMsgSink::HandleKeyPress

This method enables a control to notify its sink when a character key is pressed.

Syntax

HRESULT HandleKeyPress( IDispatch *pdispControl, long lKeyDown );

Parameters

pdispControl
Pointer to the control that is calling the method.
lKeyDown
Long integer that contains the Unicode keycode.

Return Values

NOERROR indicates that the sink handled the message. S_FALSE indicates that the sink did not handle the message. If an error occurs, the appropriate HRESULT value is returned.

Remarks

A control invokes this method when its own IASControl::KeyPress method is invoked.

Pressing a key that does not map to a character, such as VK_LEFT, does not invoke this method.

See Also

IASControl::KeyPress


IASClassMsgSink::HandleLostFocus

This method enables a control to notify its sink when the control loses focus.

Syntax

HRESULT HandleLostFocus( IDispatch *pdispControl );

Parameters

pdispControl
Pointer to the control that is calling the method.

Return Values

NOERROR indicates that the sink handled the message. S_FALSE indicates that the sink did not handle the message. If an error occurs, the appropriate HRESULT value is returned.

Remarks

A control invokes this method when its own IASControl::LostFocus method is invoked.

See Also

IASControl::LostFocus, IASClassMsgSink::HandleGotFocus.


IASClassMsgSink::HandleMessage

This method enables a control to notify its sink when a message is received.

Syntax

HRESULT HandleMessage( IDispatch *pdispControl, long uMsg, long wParam, long lParam );

Parameters

pdispControl
Pointer to the control that is calling the method.
uMsg
Specifies the message to process.
wParam
Long integer that contains the wParam of the message.
lParam
Long integer that contains the lParam of the message.

Return Values

NOERROR indicates that the sink handled the message. S_FALSE indicates that the sink did not handle the message. If an error occurs, the appropriate HRESULT value is returned.

Remarks

A control invokes this method when its own IASControl::ReceiveMsg method is invoked.

See Also

IASControl::ReceiveMsg


IASClassMsgSink::HandleStart

This method notifies the application that the control has started.

Syntax

HRESULT HandleStart( IDispatch *pdispControl );

Parameters

pDispControl
Pointer to the control to which this sink belongs.

Return Values

NOERROR indicates that the sink handled the message. S_FALSE indicates that the sink did not handle the message. If an error occurs, the appropriate HRESULT value is returned.

Remarks

A control invokes this method when its own IASControl::Start method is invoked. A control can also use it if the control has already been started, and needs to make this sink its message sink.

See Also

IASControl::Start, IASClassMsgSink::HandleClose


IASActiveForms

This interface is exposed by the Forms Manager object , and provides methods that enable an application to manage its forms.

Method
Description
IASActiveForms::get_Count | Retrieves the number of active forms for the application.
IASActiveForms::GetFocus | Retrieves a pointer to the form that currently has the focus
IASActiveForms::Item | Retrieves a pointer to an active form specified by its index.
IASActiveForms::ItemFromID | Retrieves a pointer to an active form specified by its identifier.
IASActiveForms::SetFocus | Sets the focus to a specified form.

Remarks

The IASActiveForms interface extends the IDispatch interface.


IASActiveForms::get_Count

This method retrieves the number of active forms for the application.

Syntax

HRESULT get_Count( long *pcItems );

Parameters

pcItems
Pointer to the number of active forms for the application.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASActiveForms::GetFocus

This method retrieves a pointer to the form that currently has the focus.

Syntax

HRESULT GetFocus( IDispatch ** ppdispForm );

Parameters

ppdispForm
Pointer to the pointer to the form that currently has the focus.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASActiveForms::Item

This method retrieves a pointer to an active form specified by its index.

Syntax

HRESULT Item( VARIANT index, IDispatch ** ppdispForm );

Parameters

index
Index of the form.
ppdispForm
Pointer to the pointer to the form.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

The index is not fixed, and can change as forms are added or removed. The identifier does not change.


IASActiveForms::ItemFromID

This method retrieves a pointer to an active form specified by its identifier.

Syntax

HRESULT ItemFromID( short wID, IDispatch**ppdispForm );

Parameters

wID
Short integer that contains the identifier of the form.
ppdispForm
Pointer to the pointer to the form.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASActiveForms::SetFocus

This method sets the focus to a specified form.

Syntax

HRESULT SetFocus( IDispatch*pdispForm );

Parameters

pdispForm
Pointer to the pointer to the form.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASControl

This interface provides methods that manage communication between a form and an individual control.

Method
Description
IASControl::Close | Shuts down the control when it is removed from the form.
IASControl::Draw | Repaints the form.
IASControl::get_BackColor | Retrieves the background color of the control.
IASControl::get_BackGroundBrush | Retrieves the current background brush.
IASControl::get_Border | Indicates whether or not the control has a border.
IASControl::get_Caption | Gets the caption associated with a particular control.
IASControl::get_CLSID | Gets the class identifier of the Auto PC simple form.
IASControl::get_ClassMsgSink | Gets a pointer to the message sink of a control.
IASControl::get_Color | Gets the color that corresponds to a specified index.
IASControl::get_DeferDraw | Indicates whether or not drawing has been deferred.
IASControl::get_Delegate | Retrieves the current delegate control of the current control.
IASControl::get_Enable | Indicates whether or not the control is enabled.
IASControl::get_EventSink | Gets the event sink of a control
IASControl::get_Font | Gets the font of a control.
IASControl::get_ForeColor | Gets the foreground color of a control.
IASControl::get_HasUI | Indicates whether or not the control has a user interface (UI).
IASControl::get_Height | Retrieves the height of a control.
IASControl::get_ID | Retrieves the identifier of a control.
IASControl::get_Left | Retrieves the x-coordinate of the control’s left edge.
IASControl::get_NaturalSize | Gets the natural size of a control.
IASControl::get_Opaque | Indicates whether control is drawn opaque or transparent.
IASControl::get_Parent | Retrieves a pointer to the control’s parent form.
IASControl::get_TabStop | Indicates whether or not the control is a tabstop.
IASControl::get_Top | Retrieves the y-coordinate of the top of the control.
IASControl::get_UserData | Retrieves data stored by the user.
IASControl::get_Visible | Indicates whether or not the control is visible.
IASControl::get_Width | Retrieves the width of a control.
IASControl::GetBounds | Retrieves the dimensions of a control.
IASControl::GetCommonBoolProperties | Returns the common Boolean properties
IASControl::GotFocus | Notifies a control that the control is gaining focus
IASControl::HitTest | Tests whether coordinates fall within a control.
IASControl::Init | Initializes a new control.
IASControl::IsStarted | Checks to see if the control has been started.
IASControl::KeyPress | Handles WM_CHAR messages.
IASControl::LostFocus | Notifies a control that it is losing focus.
IASControl::put_BackColor | Sets the background color of the control.
IASControl::put_BackGroundBrush | Sets the current background brush of the control.
IASControl::put_Border | Sets whether or not the control has a border.
IASControl::put_Caption | Sets the caption associated with a particular control.
IASControl::put_ClassMsgSink | Sets the message sink of a control.
IASControl::put_Color | Sets a color specified by a color index.
IASControl::put_DeferDraw | Sets whether or not drawing is deferred.
IASControl::put_Delegate | Specifies the delegate control that receives messages that the current control does not handle.
IASControl::put_Enable | Sets whether or not the control is enabled
IASControl::put_EventSink | Sets the event sink of a control.
IASControl::put_Font | Sets the font of a control.
IASControl::put_ForeColor | Sets the foreground color of a control.
IASControl::put_Height | Sets the height of a control.
IASControl::put_Left | Sets the x-coordinate of the left edge of a control.
IASControl::put_Opaque | Sets whether the control is drawn opaque or transparent.
IASControl::put_Parent | Sets the parent of a control.
IASControl::put_Top | Sets the y-coordinate of the top of the control.
IASControl::put_UserData | Sets user-defined data.
IASControl::put_Visible | Sets whether or not the control is visible.
IASControl::put_Width | Sets the width of a control.
IASControl::PutCommonBoolProperties | Sets common Boolean properties.
IASControl::ReceiveMsg | Allows a control to receive messages.
IASControl::Redraw | Redraws a control.
IASControl::SetBounds | Sets the dimensions of a control.
IASControl::Speak | Provides speech feedback.
IASControl::Start | Called internally by the parent form of the control when the form starts.

Remarks

The IASControl interface extends the IDispatch interface. If an application subclasses this interface by exposing an IASClassMsgSink interface, many of these methods subsequently invoke the related IASClassMsgSink method. A pointer to the IASClassMsgSink interface is stored in the control’s ClassMsgSink property.

Some IASClassMsgSink methods can have only a token implementation. They return S_FALSE, indicating that no processing takes place. The IASControl method should be prepared to handle processing in this event.

See Also

IASClassMsgSink


IASControl::Close

This method shuts down a control when it is removed from the form.

Syntax

HRESULT Close( void );

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

A form invokes this method when it wishes to close a control. The control frees all resources and releases all external reference counts. You must call this method for any initialized form, even if you have not called IASControl::Start on the form

If a message sink exists, this method invokes IASClassMsgSink::HandleClose.

See Also

IASControl::Init, IASClassMsgSink::HandleClose


IASControl::Draw

This method repaints the form.

Syntax

HRESULT Draw( OLE_HANDLE hDC );

Parameters

hDC
Handle to a device context (DC) returned by a call to IFMDraw::GetDC.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method is usually invoked by the form when some portion of the form has been invalidated, and the screen needs to be repainted. When this method is invoked, it finishes any drawing necessary in the device context that the method receives. The method then returns control to the form, which handles the actual screen repainting.

If a message sink exists, this method forwards the call to the IASClassMsgSink::Draw method.

See Also

IFMDraw::Commit, IFMDraw::ClipAndCommit, IFMDraw::GetDC, IASClassMsgSink::HandleDraw


IASControl::get_BackColor

This method retrieves the background color of the control.

Syntax

HRESULT get_BackColor( OLE_COLOR *pclr );

Parameters

pclr
Pointer to the background color of the control.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method must be implemented, but can return E_NOTIMPL.

See Also

IASControl::put_BackColor, IASControl::get_ForeColor


IASControl::get_BackGroundBrush

This method retrieves the current background brush.

Syntax

HRESULT get_BackGroundBrush( OLE_HANDLE *phBrush );

Parameters

phBrush
Pointer to the handle to the background brush of the control.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method must be implemented, but can return E_NOTIMPL.

See Also

IASControl::put_BackGroundBrush


IASControl::get_Border

This method indicates whether or not the control has a border.

Syntax

HRESULT get_Border( VARIANT_BOOL *pfBorder );

Parameters

pfBorder
Pointer to a Boolean that is set to TRUE if the control has a border, or to FALSE if it does not.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method must be implemented, but can return E_NOTIMPL.

See Also

IASControl::put_Border


IASControl::get_Caption

This method gets the caption associated with a particular control.

Syntax

HRESULT get_Caption( BSTR *pbstrCaption );

Parameters

pbstrCaption
Pointer to the Unicode string to be displayed as the caption.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method must be implemented, but can return E_NOTIMPL.

See Also

IASControl::put_Caption


IASControl::get_CLSID

This method gets the class identifier of the Auto PC simple form.

Syntax

HRESULT get_CLSID( BSTR *pbstrCLSID );

Parameters

pbstrCLSID
Pointer to the Unicode string that contains the class identifier.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASControl::get_ClassMsgSink

This method gets a pointer to the message sink of a control.

Syntax

HRESULT get_ClassMsgSink( IDispatch **ppdispSink );

Parameters

ppdispSink
Pointer to the pointer to the control’s IASClassMsgSink interface.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method must be implemented, but can return E_NOTIMPL.

See Also

IASControl::put_ClassMsgSink


IASControl::get_Color

This method gets the color that corresponds to a specified index.

Syntax

HRESULT get_Color( int nColorIndex, OLE_COLOR *pclr );

Parameters

nColorIndex
Color index.
pclr
Pointer to an OLE_COLOR.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IASControl::put_Color


IASControl::get_DeferDraw

This method indicates whether or not drawing has been deferred.

Syntax

HRESULT get_DeferDraw( BOOL *pfDeferDraw );

Parameters

pfDeferDraw
Pointer to a Boolean that is set to TRUE if drawing has been deferred, or to FALSE if is not.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

An application can defer drawing until it is ready. If this property is TRUE for a form, drawing is deferred for all controls on the form until it is set to FALSE.

See Also

IASControl::put_DeferDraw


IASControl::get_Delegate

This method retrieves the current delegate control of the current control.

Syntax

HRESULT get_Delegate( IDispatch **ppdispDelegate );

Parameters

ppdispDelegate
Pointer to the pointer to the IDispatch interface.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

See Also

IASControl::put_Delegate


IASControl::get_Enable

This method indicates whether or not the control is enabled.

Syntax

HRESULT get_Enabled( VARIANT_BOOL *pfEnabled );

Parameters

pfEnabled
Pointer to a Boolean that is set to TRUE if the control is enabled, or to FALSE if it is disabled.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method is required.

See Also

IASControl::put_Enable


IASControl::get_EventSink

This method gets the event sink of a control.

Syntax

HRESULT get_EventSink( IDispatch **ppdispSink );

Parameters

ppdispSink
Pointer to the pointer that receives the control’s IASCEventSink interface. If the sink is not implemented, ppdispSink receives a null pointer.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method must be implemented, but can return E_NOTIMPL.

See Also

IASControl::put_EventSink


IASControl::get_Font

This method gets the font of a control.

Syntax

HRESULT get_Font( IFontDisp **ppFontDisp );

Parameters

ppFontDisp
Pointer to the pointer to the control’s display font.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method must be implemented, but can return E_NOTIMPL.

For Microsoft Windows CE for the Auto PC, the font size is 10000 times value of the lower 32 bits of the psize variable used in the Component Object Module (COM) IFont:get_Size and IFont:put_Size methods.

See Also

IASControl::put_Font


IASControl::get_ForeColor

This method gets the foreground color of a control.

Syntax

HRESULT get_ForeColor( OLE_COLOR *pclr );

Parameters

pclr
Pointer to the foreground color of the control.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method must be implemented, but can return E_NOTIMPL.

See Also

IASControl::put_ForeColor


IASControl::get_HasUI

This method indicates whether or not the control has a user interface (UI).

Syntax

HRESULT get_HasUI( VARIANT_BOOL *pfHasUI );

Parameters

pfHasUI
Pointer to a Boolean that is set to TRUE if the control has a UI, or to FALSE if it does not.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method is required.


IASControl::get_Height

This method retrieves the height of a control.

Syntax

HRESULT get_Height( long *pdy );

Parameters

pdy
Pointer to the control’s height.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method must be implemented, but can return E_NOTIMPL. However, it should be fully implemented if IASControl::get_Bounds is implemented.

See Also

IASControl::put_Height, IASControl::GetBounds


IASControl::get_ID

This method retrieves the identifier of a control.

Syntax

HRESULT get_ID( short *pwID );

Parameters

pwID
Pointer to the short integer that contains the identifier of the control.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method is required.

An identifier is unique to a control, and does not change.


IASControl::get_Left

This method retrieves the x-coordinate of the left edge of the control.

Syntax

HRESULT get_Left( long *px );

Parameters

px
Pointer to the x-coordinate of the control’s left edge.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method must be implemented, but can return E_NOTIMPL. However, it should be fully implemented if IASControl::GetBounds is implemented.

See Also

IASControl::put_Left, IASControl::GetBounds


IASControl::get_NaturalSize

This method gets the natural size of a control.

Syntax

HRESULT get_NaturalSize( long *plWidth, long *plHeight);

Parameters

plWidth
Pointer to a long integer that contains the natural width of a control.
plHeight
Pointer to a long integer that contain the natural height of a control.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

The natural size of a control typically consists of the dimensions a control would need to display its contents. For example, the natural size of a label control with a ASFC_ALIGN_SINGLELINE format is the width required to display the control’s full caption.


IASControl::get_Opaque

This method indicates whether the control is drawn opaque or transparent.

Syntax

HRESULT get_Opaque( VARIANT_BOOL *pfOpaque );

Parameters

pfOpaque
Pointer to a Boolean that is set to TRUE if the control is opaque, or to FALSE if it is transparent.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method must be implemented, but can return E_NOTIMPL.

See Also

IASControl::put_Opaque


IASControl::get_Parent

This method retrieves a pointer to the control’s parent form.

Syntax

HRESULT get_Parent( IDispatch **ppdispParent );

Parameters

ppdispParent
Pointer to the pointer to the control’s parent.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method is required.

See Also

IASControl::put_Parent


IASControl::get_TabStop

This method indicates whether or not the control is a tabstop.

Syntax

HRESULT get_TabStop( VARIANT_BOOL *pfTabStop );

Parameters

pfTabStop
Pointer to a Boolean that is set to TRUE if the control is a tabstop, or to FALSE if the control is not.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method must be implemented, but can return E_NOTIMPL.


IASControl::get_Top

This method retrieves the y-coordinate of the top of the control.

Syntax

HRESULT get_Top( long *py );

Parameters

py
Pointer to the y-coordinate of the top of the control.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method must be implemented, but can return E_NOTIMPL. However, it should be fully implemented if IASControl::GetBounds is implemented.

See Also

IASControl::put_Top, IASControl::GetBounds


IASControl::get_UserData

This method retrieves data stored by the user.

Syntax

HRESULT get_UserData( long *plData );

Parameters

plData
Pointer to a long integer containing data that a user wants to associate with the control.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method must be implemented, but can return E_NOTIMPL.

See Also

IASControl::put_UserData


IASControl::get_Visible

This method indicates whether or not the control is visible.

Syntax

HRESULT get_Visible( VARIANT_BOOL *pfVisible );

Parameters

pfVisible
Pointer to a Boolean that is set to TRUE if the control is visible, or to FALSE if is hidden.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method is required.

See Also

IASControl::put_Visible


IASControl::get_Width

This method retrieves the width of a control.

Syntax

HRESULT get_Width( long *pdx );

Parameters

pdx
Pointer to the control’s width.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method must be implemented, but can return E_NOTIMPL. However, it should be fully implemented if IASControl::GetBounds is implemented.

See Also

IASControl::put_Width, IASControl::GetBounds


IASControl::GetBounds

This method retrieves the dimensions of a control.

Syntax

HRESULT GetBounds( long *plxLeft, long *plyTop, long *pldxWidth, long *pldyHeight );

Parameters

plxLeft
Pointer to the long integer that contains the x-coordinate of the left edge of the control.
plyTop
Pointer to the long integer that contains the y-coordinate of the top of the control.
pldxWidth
Pointer to the long integer that contains the width of the control.
pldyHeight
Pointer to the long integer that contains the height of the control.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

If you implement this method, then you must implement IASControl::get_Height, IASControl::get_Top, IASControl::get_Width, and IASControl::get_Left.

See Also

IASControl::get_Height, IASControl::get_Top, IASControl::get_Width, IASControl::get_Left, IASControl::SetBounds


IASControl::GetCommonBoolProperties

This method returns the common Boolean properties.

Syntax

HRESULT GetCommonBoolProperties( short *pwProps );

Parameters

pwProps
Pointer to a short integer that contains one or more of the following flags, which indicate the status of the control’s Boolean properties:
ASFC_CTRL_VISIBLE
Control is visible.
ASFC_CTRL_ENABLE
Control is enabled.
ASFC_CTRL_OPAQUE
Control is opaque.
ASFC_CTRL_BORDER
Control has a border.
ASFC_CTRL_DEFERDRAW
Control defers drawing until the deferdraw bit is cleared.
ASFC_CTRL_HASUI
Control has a user interface.
ASFC_CTRL_TABSTOP
Control is a tabstop.
ASFC_CTRL_SPEECHENABLED
Control is speech enabled.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IASControl::PutCommonBoolProperties


IASControl::GotFocus

This method notifies a control that the control is gaining focus.

Syntax

HRESULT GotFocus( void );

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

If a message sink exists, the control forwards this call to the IASClassMsgSink::GotFocus method.

See Also

IASControl::LostFocus, IASClassMsgSink::HandleGotFocus


IASControl::HitTest

This method tests whether coordinates fall within a control.

Syntax

HRESULT HitTest( long lx, long ly );

Parameters

lx
Long integer that contains the x-coordinate.
ly
Long integer that contains the y-coordinate.

Return Values

NOERROR indicates that the hit text succeeded. S_FALSE indicates that the hit test failed. If an error occurs, the appropriate HRESULT value is returned.


IASControl::Init

This method initializes a new control.

Syntax

HRESULT Init( short wID, IDispatch *pdispParent, IDispatch pdispEventSink );

Parameters

wID
Short integer that contains the identifier of the control.
pdispParent
Pointer to the object that owns the control.
pdispEventSink
Pointer to the default event sink for the control. Use NULL if the owner is not to receive events.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

Following initialization, the control must be started with IASControl::Start before processing can start. An application does not call IASControl::Start explicitly. The parent form of the control calls IASControl::Start when the form starts, or the IASForm::Add method calls IASControl::Start internally when you add a control to a form you have already started.

See Also

IFMDraw, IASControl::Start, IASEventSink, IASControl::Close, IASForm::Add


IASControl::IsStarted

This method checks to see if the control has been started.

Syntax

HRESULT IsStarted( void );

Return Values

NOERROR indicates that the control has been started. S_FALSE indicates that the control has not been started.


IASControl::KeyPress

This method handles WM_CHAR messages.

Syntax

HRESULT KeyPress( long lKeyDown );

Parameters

lKeyDown
Long integer that contains the Unicode keycode.

Return Values

NOERROR indicates that the control handled the message. S_FALSE indicates that the control did not handle the message. If an error occurs, the appropriate HRESULT value is returned.

Remarks

If a message sink exists, the control forwards the message to the IASClassMsgSink::KeyPress method.

See Also

IASClassMsgSink::HandleKeyPress


IASControl::LostFocus

This method notifies a control that it is losing focus.

Syntax

HRESULT LostFocus( void );

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

If a message sink exists, the method forwards the message to its IASClassMsgSink::LostFocus method.

See Also

IASControl::GotFocus, IASClassMsgSink::HandleLostFocus


IASControl::put_BackColor

This method sets the background color of the control.

Syntax

HRESULT put_BackColor( OLE_COLOR clr );

Parameters

clr
Background color of the control.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method must be implemented, but can return E_NOTIMPL.

See Also

IASControl::get_BackColor


IASControl::put_BackGroundBrush

This method sets the current background brush of the control.

Syntax

HRESULT put_BackGroundBrush( OLE_HANDLE hBrush );

Parameters

hBrush
Handle to the control’s background brush.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method is not required, and can return E_NOTIMPL.

See Also

IASControl::get_BackGroundBrush


IASControl::put_Border

This method sets whether or not the control has a border.

Syntax

HRESULT put_Border( VARIANT_BOOL fBorder );

Parameters

fBorder
Boolean that is set to TRUE if the control has a border, or to FALSE if it does not.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method must be implemented, but can return E_NOTIMPL.

See Also

IASControl::get_Border


IASControl::put_Caption

This method sets the caption associated with a particular control.

Syntax

HRESULT put_Caption( BSTR bstrCaption );

Parameters

bstrCaption
Unicode string to be displayed as the caption.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method must be implemented, but can return E_NOTIMPL.

See Also

IASControl::get_Caption


IASControl::put_ClassMsgSink

This method sets the message sink of a control.

Syntax

HRESULT put_ClassMsgSink( IDispatch *ppdispSink );

Parameters

ppdispSink
Pointer to the pointer to the control’s IASClassMsgSink interface.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method must be implemented, but can return E_NOTIMPL.

See Also

IASControl::get_ClassMsgSink


IASControl::put_Color

This method sets a color specified by a color index.

Syntax

HRESULT put_Color( int nColorIndex, OLE_COLOR clr );

Parameters

nColorIndex
Color index.
clr
Color to set.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IASControl::get_Color


IASControl::put_DeferDraw

This method sets whether or not drawing is deferred.

Syntax

HRESULT put_DeferDraw( BOOL fDeferDraw );

Parameters

fDeferDraw
Boolean that is set to TRUE to defer drawing, or to FALSE otherwise.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

An application can defer drawing until it is ready. If this property is TRUE for a form, drawing is deferred for all controls on the form until it is set to FALSE.

See Also

IASControl::get_DeferDraw


IASControl::put_Delegate

This method specifies the delegate control that receives messages that the current control does not handle.

Syntax

HRESULT put_Delegate( IDispatch *pdispDelegate );

Parameters

pdispDelegate
Pointer to the IDispatch interface.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

See Also

IASControl::get_Delegate


IASControl::put_Enable

This method sets whether or not the control is enabled.

Syntax

HRESULT put_Enable( VARIANT_BOOL fEnabled );

Parameters

fEnabled
Boolean that is set to TRUE to enable the control, or to FALSE to disable it.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method is required.

See Also

IASControl::get_Enable


IASControl::put_EventSink

This method sets the event sink of a control.

Syntax

HRESULT put_EventSink( IDispatch *pdispSink );

Parameters

pdispSink
Pointer to the control’s IASCEventSink interface.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method must be implemented, but can return E_NOTIMPL.

See Also

IASControl::get_EventSink


IASControl::put_Font

This method sets the font of a control.

Syntax

HRESULT put_Font( IFontDisp *pFontDisp );

Parameters

pFontDisp
Pointer to the control’s display font.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method must be implemented, but can return E_NOTIMPL.

For Microsoft Windows CE for the Auto PC, the font size is 10000 times value of the lower 32 bits of the psize variable used in the Component Object Module (COM) IFont:get_Size and IFont:put_Size methods.

See Also

IASControl::get_Font


IASControl::put_ForeColor

This method sets the foreground color of the control.

Syntax

HRESULT put_ForeColor( OLE_COLOR clr );

Parameters

clr
Foreground color of the control.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method must be implemented, but can return E_NOTIMPL.

See Also

IASControl::get_ForeColor


IASControl::put_Height

This method sets the height of a control.

Syntax

HRESULT put_Height( long dy );

Parameters

dy
Specifies the control’s height.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method must be implemented, but can return E_NOTIMPL.

See Also

IASControl::get_Height


IASControl::put_Left

This method sets the x-coordinate of the left edge of a control.

Syntax

HRESULT put_Left( long x );

Parameters

x
Specifies the x-coordinate of the control’s left edge.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method must be implemented, but can return E_NOTIMPL.

See Also

IASControl::get_Left


IASControl::put_Opaque

This method sets whether control is drawn opaque or transparent.

Syntax

HRESULT put_Opaque( VARIANT_BOOL fOpaque );

Parameters

fOpaque
Boolean that is set to TRUE if the control is opaque, or to FALSE if it is transparent.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method must be implemented, but can return E_NOTIMPL.

See Also

IASControl::get_Opaque


IASControl::put_Parent

This method sets the parent of a control.

Syntax

HRESULT put_Parent( IDispatch *pdispParent );

Parameters

pdispParent
Pointer to the control’s parent.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

An application should not call this method directly. This method is called internally when you associate a control with a form.

See Also

IASControl::get_Parent


IASControl::put_Top

This method sets the y-coordinate of the top of the control.

Syntax

HRESULT put_Top( long y );

Parameters

y
Specifies the y-coordinate of the top of the control.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method must be implemented, but can return E_NOTIMPL.

See Also

IASControl::get_Top


IASControl::put_UserData

This method sets user-defined data.

Syntax

HRESULT put_UserData( long lData );

Parameters

lData
Long integer that contains data that a user wants to associate with the control.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IASControl::get_UserData


IASControl::put_Visible

This method sets whether or not the control is visible.

Syntax

HRESULT put_Visible( VARIANT_BOOL fVisible );

Parameters

fVisible
Boolean that is set to TRUE if the control is visible, or to FALSE if it is hidden.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method is required.

See Also

IASControl::get_Visible


IASControl::put_Width

This method sets the width of a control.

Syntax

HRESULT put_Width( long dx );

Parameters

dx
Specifies the control’s width.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method must be implemented, but can return E_NOTIMPL.

See Also

IASControl::get_Width


IASControl::PutCommonBoolProperties

This method sets common Boolean properties.

Syntax

HRESULT PutCommonBoolProperties( short pwProps );

Parameters

pwProps
Pointer to a short integer that contains one of the following flags, which indicate the status of a control’s Boolean properties:
ASFC_CTRL_VISIBLE
Control is visible.
ASFC_CTRL_ENABLE
Control is enabled.
ASFC_CTRL_OPAQUE
Control is opaque.
ASFC_CTRL_BORDER
Control has a border.
ASFC_CTRL_DEFERDRAW
Control defers drawing until this bit is cleared.
ASFC_CTRL_HASUI
Control has a user interface.
ASFC_CTRL_TABSTOP
Control is a tabstop.
ASFC_CTRL_SPEECHENABLED
Control is speech enabled.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method combines the flags passed to the method in pwProps with property flags already set before the call to this method by using an OR operation.

See Also

IASControl::GetCommonBoolProperties


IASControl::ReceiveMsg

This method allows a control to receive messages.

Syntax

HRESULT ReceiveMsg( long uMsg, long wParam, long lParam );

Parameters

uMsg
Specifies the message to process.
wParam
Long integer that contains the wParam of a message.
lParam
Long integer that contains the lParam of a message.

Return Values

NOERROR indicates success. S_FALSE indicates that the control did not handle the message. If an error occurs, the appropriate HRESULT value is returned.

Remarks

If a message sink exists, the control forwards the message to its IASEventSink::ReceiveMsg method. WM_CHAR messages are handled by IASControl::KeyPress.

See Also

IASControl::KeyPress, IASEventSink::ReceiveMsg


IASControl::Redraw

This method redraws a control.

Syntax

HRESULT Redraw( void );

Return Values

NOERROR indicates success. S_FALSE indicates that the control did not handle the message. If an error occurs, the appropriate HRESULT value is returned.

Remarks

The IASControl::Redraw method is used to notify a form to redraw itself. It can do this by invoking one of its form’s invalidation methods, or by requesting an IFMDraw interface pointer. IFMDraw enables IASControl::Redraw to handle repainting by itself.

See Also

IASControl::Draw, IASForm::Invalidate


IASControl::SetBounds

This method sets the dimensions of a control.

Syntax

HRESULT SetBounds( long lxLeft, long lyTop, long ldxWidth, long ldyHeight );

Parameters

lxLeft
Long integer that contains the x-coordinate of the left edge of the control.
lyTop
Long integer that contains the y-coordinate of the top of the control.
ldxWidth
Long integer that contains the width of the control.
ldyHeight
Long integer that contains the height of the control.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IASControl::GetBounds


IASControl::Speak

This method provides speech feedback.

Syntax

HRESULT Speak( DWORD dwSpeechContext, DWORD dwMode, DWORD dwReserved );

dwSpeechContext
Specifies a DWORD that contains the speech context.
dwMode
Specifies a DWORD that contains the speech feedback mode. It is one of the following values.
ASFC_SPEAK_CAPTION
Speech feedback includes the caption text.
ASFC_SPEAK_FOCUSITEM
Speech feedback includes the text of the item that has the focus.
ASFC_SPEAK_ALLITEMS
Speech feedback includes all items.
ASFC_SPEAK_ASFORMFOCUS
Used when a form calls this method on the control that has the focus.
ASFC_SPEAK_ITEMBYID
Speech feedback includes the text of the item that has the item identifier specified in dwReserved.
ASFC_SPEAK_ITEMATINDEX
Speech feedback includes the text of the item that has the item index specified in dwReserved.
dwReserved
Reserved.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASControl::Start

This method is called internally by the parent form of the control when the form starts.

Syntax

HRESULT Start( void );

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

An application should not directly call this method. After a form initializes a control by calling IASControl::Init, it invokes this method internally to start processing. A control should not start processing until this method has been invoked. A form notifies a control to stop processing with a call to IASControl::Close. If a message sink exists, the control forwards the message to its IASClassMsgSink::Start method.

See Also

IASControl::Init, IASControl::Close, IASClassMsgSink::HandleClose


IASEventSink

This optional interface provides a simple way for controls to fire events.

Method
Description
IASEventSink::ReceiveMsg Allows a control to receive a message when a message event is fired.

Remarks

The IASEventSink interface extends the IDispatch interface. If an application does not need to receive events, this interface is unnecessary. To implement IASEventSink, create an object that exposes the interface, and place a pointer to it in the IASControl EventSink property. If this interface is not adequate, create a custom IConnectionPoint interface.

See Also

IASControl::get_EventSink, IASControl::put_EventSink


IASEventSink::ReceiveMsg

This method allows a control to receive a message when a message event is fired.

Syntax

HRESULT ReceiveMsg( long uMsg, long wParam, long lParam );

Parameters

uMsg
Specifies the message to process.
wParam
Long integer that contains the wParam of the message.
lParam
Long integer that contains the lParam of the message.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASTitleBar

This interface provides methods for managing a title bar.

Method
Description
IASTitleBar::get_Icon | Gets a title bar icon.
IASTitleBar::get_MaxTitleWidth | Gets the maximum width of the title bar text.
IASTitleBar::get_StatusFlags | Gets the title bar status flags that control the images displayed from the image list.
IASTitleBar::get_StatusImageList | Gets the status of the title bar image list.
IASTitleBar::get_SubCaption | Gets the title bar subcaption.
IASTitleBar::put_Icon | Sets the title bar icon.
IASTitleBar::put_MaxTitleWidth | Sets the maximum width of the title bar text.
IASTitleBar::put_StatusFlags | Sets the title bar status flags that control the images displayed from the image list.
IASTitleBar::put_StatusImageList | Sets the status of the title bar image list.
IASTitleBar::put_SubCaption | Sets the title bar subcaption.

Remarks

The IASTitleBar interface extends the IASControl interface. The title bar has a programmatic identifier equal to APC_Titlebar.

See Also

IASControl


IASTitleBar::get_Icon

This method gets the title bar icon.

Syntax

HRESULT get_Icon( OLE_HANDLE *phIcon );

Parameters

phIcon
Pointer to the handle of the icon.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IASTitleBar::put_Icon


IASTitlebar::get_MaxTitleWidth

This method gets the maximum width of the title bar text.

Syntax

HRESULT get_MaxTitleWidth( long *plMaxTitleWidth);

Parameters

plMaxTitleWidth
Pointer to a long integer that contains the maximum width allowed for the title bar.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IASTitleBar::put_MaxTitleWidth


IASTitleBar::get_StatusFlags

This method gets the title bar status flags that control the images displayed from the image list.

Syntax

HRESULT get_StatusFlags( long *plStatusFlags );

Parameters

plStatusFlags
Pointer to a long integer that contains the status flags. The first image is displayed if bit 0 is set. The second image is displayed if bit 1 is set.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IASTitleBar::put_StatusFlags


IASTitleBar::get_StatusImageList

This method gets the status of the title bar image list.

Syntax

HRESULT get_StatusImageList( OLE_HANDLE *phbmImage, OLE_HANDLE *phbmImageMask, long *pcxImage, long *pcyImage );

Parameters

phbmImage
Pointer to an OLE_HANDLE to a bitmap image.
phbmImageMask
Pointer to an OLE_HANDLE to a bitmap image mask.
pcxImage
Pointer to a long integer that contains the x-coordinate of the image.
pcyImage
Pointer to a long integer that contains the y-coordinate of the image.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IASTitleBar::put_StatusImageList


IASTitleBar::get_SubCaption

This method gets the title bar subcaption.

Syntax

HRESULT get_SubCaption( BSTR *pbstrSubCaption );

Parameters

pbstrSubCaption
Pointer to a Unicode string that contains the title bar’s subcaption.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IASTitleBar::put_SubCaption


IASTitleBar::put_Icon

This method sets the title bar icon.

Syntax

HRESULT put_Icon( OLE_HANDLE hIcon );

Parameters

phIcon
Pointer to the OLE_HANDLE to the icon.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

The size of the title bar icon must be 16 pixels x 16 pixels.

See Also

IASTitleBar::get_Icon


IASTitleBar::put_MaxTitleWidth

This method sets the maximum width of title bar text.

Syntax

HRESULT put_MaxTitleWidth( long lMaxTitleWidth);

Parameters

lMaxTitleWidth
Long integer that contains the maximum width of the title bar title.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IASTitleBar::get_MaxTitleWidth


IASTitleBar::put_StatusFlags

This method sets the title bar status flags that control the images displayed from the image list.

Syntax

HRESULT put_StatusFlags( long lStatusFlags );

Parameters

lStatusFlags
Long integer that contains the status flags. The first image is displayed if bit 0 is set. The second image is displayed if bit 1 is set.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IASTitleBar::get_StatusFlags


IASTitleBar::put_StatusImageList

This method sets the status of the title bar image list.

Syntax

HRESULT put_StatusImageList( OLE_HANDLE hbmImage, OLE_HANDLE hbmImageMask, long cxImage, long cyImage );

Parameters

hbmImage
OLE_HANDLE to a bitmap image.
hbmImageMask
OLE_HANDLE to a bitmap image mask.
cxImage
Long integer that contains the x-coordinate of the image.
cyImage
Long integer that contains the y-coordinate of the image.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IASTitleBar::get_StatusImageList


IASTitleBar::put_SubCaption

This method sets the title bar subcaption.

Syntax

HRESULT put_SubCaption( BSTR bstrSubCaption );

Parameters

bstrSubCaption
Unicode string that contains the title bar’s subcaption.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IASTitleBar::get_SubCaption


IASUserNavArrows

This interface provides methods for managing a navigational arrows control.

Method
Description
IASUserNavArrows::get_NavState | Gets the state of the navigational arrows control.
IASUserNavArrows::put_NavState | Sets the state of the navigational arrows control.
IASUserNavArrows::QueryFormForNavState | Queries the form to determine the state of the navigational arrows control.

Remarks

The IASUserNavArrows interface extends the IASControl interface. The navigational arrows control has a programmatic identifier equal to APC_NavArrows.

See Also

IASControl


IASUserNavArrows::get_NavState

This method gets the state of the navigational arrows control.

Syntax

HRESULT get_NavState( long *plNavState );

Parameters

plNavState
Pointer to a long integer that contains the state of the navigational arrows control. It is one or a combination of the following flags.
Flag
Value
Description
USER_NAV_LEFT | 0x0001 | Control displays the left arrow.
USER_NAV_UP | 0x0002 | Control displays the up arrow.
USER_NAV_RIGHT | 0x0004 | Control displays the right arrow.
USER_NAV_DOWN | 0x0008 | Control displays the down arrow.
USER_NAV_ENTER | 0x0010 | Control displays the center dot that represents the ENTER key.
USER_NAV_SMALL | 0x4000 | Control displays a smaller, 19 x 19 version of the navigational arrows control.
USER_NAV_DISABLED | 0x8000 | Reserved for internal use.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IASUserNavArrows::put_NavState


IASUserNavArrows::put_NavState

This method sets the state of the navigational arrows control.

Syntax

HRESULT put_NavState( long lNavState );

Parameters

plNavState
Long integer that contains the state of the navigational arrows control. It is one or a combination of the following flags.
Flag
Value
Description
USER_NAV_LEFT | 0x0001 | Displays the left arrow.
USER_NAV_UP | 0x0002 | Displays the up arrow.
USER_NAV_RIGHT | 0x0004 | Displays the right arrow.
USER_NAV_DOWN | 0x0008 | Displays the down arrow.
USER_NAV_ENTER | 0x0010 | Displays the center dot that represents the ENTER key.
USER_NAV_SMALL | 0x4000 | Displays a smaller, 19 x 19 version of the navigational arrows control.
USER_NAV_DISABLED | 0x8000 | Reserved for internal use.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IASUserNavArrows::get_NavState


IASUserNavArrows::QueryFormForNavState

This method queries the form to determine the state of the navigational arrows control.

Syntax

HRESULT QueryFormForNavState( );

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IQueryKeyUsage

This interface provides a method to determine key usage.

Method
Description
IQueryKeyUsage::FlagKeysUsed Gets the flags of the keys used.


IQueryKeyUsage::FlagKeysUsed

This method gets the flags of the keys used.

Syntax

HRESULT FlagKeysUsed( long lKeysUsed, long lKeysEaten );

Parameters

lKeysUsed
Long integer that contains the keystrokes used. It is any combination of the following flags.
QKU_VK_LEFT
The LEFT ARROW key.
QKU_VK_UP
The UP ARROW key.
QKU_VK_RIGHT
The RIGHT ARROW key.
QKU_VK_DOWN
The DOWN ARROW key.
QKU_VK_RETURN
The ENTER key.
lKeysEaten
Long integer that contains the keystrokes discarded. It is any combination of the following flags.
QKU_VK_LEFT
The LEFT ARROW key.
QKU_VK_UP
The UP ARROW key.
QKU_VK_RIGHT
The RIGHT ARROW key.
QKU_VK_DOWN
The DOWN ARROW key.
QKU_VK_RETURN
The ENTER key.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method allows you to notify a NavArrow control that your form or application can handle particular keystrokes. The NavArrow control queries the Forms Manager about such keystrokes by posting a WM_QUERYKEYUSAGE message. The lparam of this message is a pointer to an IQueryKeyUsage interface. The form sink or application sink that processes keystrokes should call IQueryKeyUsage::FlagKeysUsed with the flags for each of the navigation keystrokes that the form or application can process or discard. Discarded keystrokes are keystrokes to which the sink does not respond but for which the sink will return S_FALSE, preventing other message handlers from having the opportunity to process the keystroke.

Only forms or applications that intercept arrow keystrokes or enter keystrokes need to process the WM_QUERYKEYUSAGE message.

The following code example shows how to use the WM_QUERYKEYUSAGE message and IQueryKeyUsage::FlagKeysUsed method.

if (WM_APCSYSMSG_QUERYKEYUSAGE == uMsg)
{
    IQueryKeyUsage *pqku = (IQueryKeyUsage*)lParam;

    // Return the result of FlagKeyUsed as the return value for
    // the current method.
    return pqku->FlagKeysUsed((QKU_VK_LEFT | QKU_VK_RIGHT), (QKU_VK_UP | QKU_VK_DOWN));
}

See Also

WM_QUERYKEYUSAGE


IASForm

This interface provides methods for managing controls on a form.

Method
Description
IASForm::Add | Adds a control to the form.
IASForm::GetFocus | Retrieves a pointer to the control that has the current focus.
IASForm::GetIFMDraw | Retrieves a pointer to the IFMDraw interface associated with a control.
IASForm::get_Count | Gets the number of controls on a form.
IASForm::get_HelpContext | Gets the current help file and topic associated with the form.
IASForm::get_NavArrows | Gets a navigational arrows control.
IASForm::get_Speech | Gets a pointer to the IAPCSpeech interface associated with a control.
IASForm::get_Titlebar | Gets a pointer to the title bar for the form.
IASForm::get_VoiceMenu | Gets the voice menu currently associated with the form.
IASForm::get_WaitStatus | Gets the status of the wait cursor.
IASForm::Invalidate | Invalidates a specified rectangle.
IASForm::InvalidateAll | Invalidates the entire form.
IASForm::IsControlOnForm | Checks whether a particular control is on a form.
IASForm::Item | Gets a pointer to a control on a form.
IASForm::ItemFromID | Gets a pointer to a specified control based on its identifier.
IASForm::KillTimer | Stops—or kills—a timer.
IASForm::put_HelpContext | Sets the specified help file.
IASForm::put_VoiceMenu | Sets the voice menu currently associated with the form.
IASForm::put_WaitStatus | Sets the wait cursor status.
IASForm::Remove | Removes a control from a form.
IASForm::RemoveAll | Removes all controls from a form.
IASForm::RemoveByID | Removes a control with a specified identifier from a form.
IASForm::RemoveAtIndex | Removes a control with a specified index from a form.
IASForm::SetFocus | Sets the focus to a specified control.
IASForm::SetFocusNext | Sets the focus to the next control.
IASForm::SetFocusPrev | Sets the focus to the previous control.
IASForm::SetTimer | Sets a timer.
IASForm::SetZOrder | Places a control in a specified position in the z-order.
IASForm::Update | Updates the controls that are in the update region.
IASForm::Uninitialize | Uninitializes a form that has not been started.

Remarks

The IASForm interface extends the IASControl interface.

See Also

IASControl


IASForm::Add

This method adds a control to the form.

Syntax

HRESULT Add( IDispatch *pdispControl, short wID );

Parameters

pdispControl
Pointer to the control to be added.
wID
Short integer that contains the identifier of the control.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASForm::GetFocus

This method retrieves a pointer to the control that has the current focus.

Syntax

HRESULT GetFocus( IDispatch **ppdispControl );

Parameters

ppdispControl
Pointer to the pointer to the control’s IASControl interface.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IASForm::SetFocus, IASControl


IASForm::GetIFMDraw

This method retrieves a pointer to the IFMDraw interface associated with a control.

Syntax

HRESULT GetIFMDraw( IDispatch **ppdispFMDraw, long lxLeft, long lyTop, long lxWidth, long lyHeight );

Parameters

ppdispFMDraw
Pointer to the pointer to an IFMDraw interface.
lxLeft
Long integer that contains the coordinate of the left edge of the drawing rectangle.
lyTop
Long integer that contains the coordinate of the upper edge of the drawing rectangle.
lxWidth
Long integer that contains the width of the drawing rectangle.
lyHeight
Long integer that contains the height of the drawing rectangle.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument was used. E_ACCESSDENIED indicates that no IFMDraw interface identifier (IID) is available. If an error occurs, the appropriate HRESULT value is returned.

Remarks

You should not use this method in most applications. Use this method only when designing custom controls.

See Also

IFMDraw


IASForm::get_Count

This method gets the number of controls on a form.

Syntax

HRESULT get_Count( long *pcItems );

Parameters

pcItems
Pointer to the number of controls on the form.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASForm::get_HelpContext

This method gets the current help file and topic associated with the form.

Syntax

HRESULT get_HelpContext( BSTR *pbstrHelpFile, BSTR *pbstrHelpTopic);

Parameters

pbstrHelpFiles
Pointer to a Unicode string that contains the name of the Help index file to retrieve.
pbstrHelpTopic
Pointer to a Unicode string that contains the name of the Help topic file to retrieve.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IASForm::put_HelpContext


IASForm::get_NavArrows

This method gets a pointer to a navigational arrows control.

Syntax

HRESULT get_NavArrows ( IASUserNavArrows **ppNavArrows );

Parameters

ppNavArrrows
Pointer to a pointer to a NavArrows control.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASForm::get_Speech

This method gets a pointer to the IAPCSpeech interface associated with a control.

Syntax

HRESULT get_Speech( IAPCSpeech **ppSpeech );

Parameters

ppSpeech
Pointer to the pointer to the IAPCSpeech interface.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASForm::get_Titlebar

This method gets a pointer to the title bar for the form.

Syntax

HRESULT get_Titlebar ( IASTitlebar **ppTitlebar);

Parameters

ppTitlebars
Pointer to a pointer to a title bar.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASForm::get_VoiceMenu

This method gets the voice menu currently associated with the form.

Syntax

HRESULT get_VoiceMenu( IUnknown **ppUnknownVoiceMenu );

Parameters

ppUnknownVoiceMenu
Pointer to the pointer to the voice menu.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

Once a voice menu is attached to a form, it is automatically activated or deactivated by the Forms Manager when focus changes for the form or application. This eliminates the need for applications to activate or deactivate their own voice menus when they receive a WM_ACTIVATE message.

See Also

IASForm::put_VoiceMenu


IASForm::get_WaitStatus

This method gets the status of the wait cursor.

Syntax

HRESULT get_WaitStatus( BOOL *pfWaitStatus );

Parameters

pfWaitStatus
Pointer to a Boolean that indicates the status of the wait cursor. TRUE indicates that the wait cursor is set. FALSE indicates that the wait cursor is not set.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

The hour glass or wait cursor shows that a process is taking place, such as copying a file. To ensure that an application does not interrupt the process, check the status of the wait cursor. When the wait cursor is set, a wait icon is displayed in the center of the form.

See Also

IASForm::put_WaitStatus


IASForm::Invalidate

This method invalidates a specified rectangle.

Syntax

HRESULT Invalidate( long xLeft, long yTop, long dxWidth, long dyHeight );

Parameters

xLeft
Specifies the x-coordinate of the left edge of the form.
yTop
Specifies the y-coordinate of the upper edge of the form.
dxWidth
Specifies the width of the form.
dyWidth
Specifies the height of the form.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method adds the specified rectangle to the forms update region. The update region is repainted the next time the offscreen bitmap is blitted to the screen.


IASForm::InvalidateAll

This method invalidates the entire form.

Syntax

HRESULT Add( void );

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IASForm::Invalidate


IASForm::IsControlOnForm

This method checks whether a particular control is on a form.

Syntax

HRESULT IsControlOnForm( IDispatch *pdispControl );

Parameters

pdispControl
Pointer to the control.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument was entered. S_FALSE indicates that a particular control is not on the form.


IASForm::Item

This method gets a pointer to a control on a form.

Syntax

HRESULT Item( VARIANT index, IDispatch **ppdispControl );

Parameters

index
Index of the control to be retrieved.
ppdisp
Pointer to the pointer to the control.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IASForm::ItemFromID


IASForm::ItemFromID

This method gets a pointer to a specified control based on its identifier.

Syntax

HRESULT ItemFromID( short ID, IDispatch **ppdispControl );

Parameters

ID
Identifier of the control.
ppdisp
Pointer to the pointer to the control.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IASForm::Item, IASControl::get_ID


IASForm::KillTimer

This method stops—or kills—a timer.

Syntax

HRESULT KillTimer( long lTimerID );

Parameters

lTimerID
Long integer that contains the identifier of the timer to be stopped.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method stops a timer started by a call to IASForm::SetTimer.

See Also

IASForm::SetTimer


IASForm::put_HelpContext

This method sets a specified help file.

Syntax

HRESULT put_HelpContext( BSTR bstrHelpFile, BSTR bstrHelpTopic);

Parameters

bstrHelpFiles
Unicode string that contains the name of the Help index file to set.
bstrHelpTopic
Unicode string that contains the name of the Help topic file to set.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IASForm::get_HelpContext


IASForm::put_VoiceMenu

This method sets the voice menu currently associated with the form.

Syntax

HRESULT put_VoiceMenu( IUnknown *pUnknownVoiceMenu );

Parameters

pUnknownVoiceMenu
Pointer to the voice menu.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

Once a voice menu is attached to a form, it is automatically activated or deactivated by the Forms Manager when focus changes for the form or application. This eliminates the need for applications to activate or deactivate their own voice menus when they receive a WM_ACTIVATE message.

See Also

IASForm::get_VoiceMenu


IASForm::put_WaitStatus

This method sets the status of the wait cursor.

Syntax

HRESULT put_WaitStatus( BOOL fWaitStatus );

Parameters

fWaitStatus
Boolean that is set to TRUE if the wait cursor is set or to FALSE if the wait cursor is not set.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

When the wait cursor is set, a wait icon is displayed in the center of the form.

See Also

IASForm::get_WaitStatus


IASForm::Remove

This method removes a control from a form.

Syntax

HRESULT Remove( IDispatch *pdispControl );

Parameters

pdispControl
Pointer to the control to be removed.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

IASForm::Remove calls IASControl::Close for the control being removed.

See Also

IASControl::Close


IASForm::RemoveAll

This method removes all controls from a form.

Syntax

HRESULT RemoveAll( void );

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

IASForm::RemoveAll calls IASControl::Close for each of the controls on the form.

See Also

IASControl::Close


IASForm::RemoveByID

The IASForm::RemoveByID method removes a control with a specified identifier from a form.

Syntax

HRESULT RemoveByID( short ID );

Parameters

ID
Identifier of a control.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

IASForm::RemoveByID calls IASControl::Close for the control to be removed.

See Also

IASControl::get_ID


IASForm::RemoveAtIndex

The IASForm::RemoveAtIndex method removes a control with a specified index from a form.

Syntax

HRESULT RemoveAtIndex( long index );

Parameters

index
Index of a control.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

A control’s index may change as controls are added or removed. Identifiers, however, do not change. IASForm::RemoveAtIndex calls IASControl::Close for the control to be removed.


IASForm::SetFocus

This method sets the focus to a specified control.

Syntax

HRESULT SetFocus( IDispatch *pdispControl );

Parameters

pdispControl
Pointer to the control.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

Controls that do not receive user input such as a Clock control or a Label control do not accept focus.


IASForm::SetFocusNext

This method sets the focus to the next control.

Syntax

HRESULT SetFocusNext( void );

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASForm::SetFocusPrev

This method sets the focus to the previous control.

Syntax

HRESULT SetFocusPrev( void );

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASForm::SetTimer

This method sets a timer.

Syntax

HRESULT SetTimer( IDispatch *pdispControl, UINT dMilliSecs, long *pTimerID );

Parameters

pdispControl
Pointer to the control the timer is associated with.
dMilliSecs
Specifies, in milliseconds, the timer setting.
pTimerID
Pointer to the long integer that contains the identifier of the timer.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

When the timer reaches 0, it fires a WM_TIMER message to the event sink. The control’s identifier is contained in the low-order word of the message’s wParam.

See Also

LOWORD


IASForm::SetZOrder

This method places a control in a specified position in the z-order.

Syntax

HRESULT SetZOrder( IDispatch *pdispControl, IDispatch *pdispControlAfter );

Parameters

pdispControl
Pointer to the control to be placed in the z-order.
pdispControlAfter
Pointer to the control that precedes the control specified in pdispControl. If this parameter is NULL, pdispControl becomes the first control in the z-order.

Return Values

NOERROR indicates success. ASFC_E_CTRL_NOSUCH indicates that one of the two controls is not on the form. If an error occurs, the appropriate HRESULT value is returned.


IASForm::Update

This method updates the controls that are in the update region.

Syntax

HRESULT Update( void );

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

To force a redraw of one control, the IASControl::Redraw method is more efficient because it does not have to search for outdated portions of the region. IASControl::Redraw completely redraws a region, while IASControl::Update refreshes a region by searching for outdated portions of the region.

See Also

IASControl::Redraw


IASForm::Uninitialize

This method uninitializes a form that has not been started.

Syntax

HRESULT Uninitialize( void );

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

While this method has the same effect as invoking IASControl::Close for the form, IASForm::Uninitialize works for forms that have not been started yet.

See Also

IASControl::Close, IfmManage::Start


IFMDraw

This interface provides indirect access to the screen device context (DC).

Method
Description
IFMDraw::ClipAndCommit | Takes a clipping region and blits that portion of the offscreen bitmap to the screen.
IFMDraw::Commit | Blits the entire offscreen bitmap to the screen.
IFMDraw::GetDC | Gets a screen device context (DC).
IFMDraw::GetDeviceCaps | Gets the capabilities of the screen device context (DC).
IFMDraw::ReleaseDC | Releases the device context (DC).

Remarks

The IFMDraw interface extends IDispatch. It is used by controls and forms to manage screen display when simply invalidating and redrawing regions is not sufficient.

A form receives a pointer to an IFMDraw interface when the form is created. A control must request the pointer from its form. The interface provides the control with a device context (DC) that the control can then use to draw to the system’s offscreen bitmap. When drawing is complete, one of two methods is then used to blit the bitmap to the screen.

Drawing to the screen only takes place if a control’s form has focus. If not, the control is not updated. The drawing process proceeds normally—no errors are generated—but the screen is not repainted.


IFMDraw::ClipAndCommit

This method takes a clipping region and blits that portion of the offscreen bitmap to the screen.

Syntax

HRESULT ClipAndCommit( OLE_HANDLE hDC, OLE_HANDLE hRgnClip );

Parameters

hDC
Handle to the screen device context (DC), as returned by IFMDraw::GetDC.
hRgnClip
Handle to a clipping region.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

The form must have focus for blitting to take place. If not, no errors are generated, but the image does not appear on the screen. This method fails if the DC passed to the method is not the one returned by a previous call to IFMDraw::GetDC. It also fails if the DC has been released by IFMDraw::ReleaseDC.

See Also

IFMDraw::GetDC, IFMDraw::Commit, IFMDraw::ReleaseDC


IFMDraw::Commit

This method blits the entire offscreen bitmap to the screen.

Syntax

HRESULT Commit( OLE_HANDLE hDC );

Parameters

hDC
Handle to a device context (DC), as returned by IFMDraw::GetDC.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

The form must have focus for blitting to take place. If not, no errors are generated, but the image does not appear on the screen. This method fails if the DC passed to the method is not the one returned by a previous call to IFMDraw::GetDC. It also fails if the DC has been released by IFMDraw::ReleaseDC.

See Also

IFMDraw::GetDC, IFMDraw::ClipAndCommit, IFMDraw::ReleaseDC


IFMDraw::GetDC

This method gets a screen device context (DC).

Syntax

HRESULT GetDC( OLE_HANDLE *phDC );

Parameters

phDC
Pointer to the handle to a screen DC.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

Every call to IFMDraw::GetDC must be matched by a call to IFMDraw::ReleaseDC.

See Also

IFMDraw::ReleaseDC


IFMDraw::GetDeviceCaps

This method gets the capabilities of the screen device context (DC).

Syntax

HRESULT GetDeviceCaps( long index, long *plDeviceCap );

Parameters

index
Specifies the index of the capability to return in plDeviceCap. It is one of the following values.
DRIVERVERSION
The device driver version.
HORZSIZE
Width of the physical screen, in millimeters.
VERTSIZE
Height of the physical screen, in millimeters.
HORZRES
Width of the screen, in pixels.
VERTRES
Height of the screen, in raster lines.
LOGPIXELSX
Number of pixels per logical inch along the width of the screen. If the device has multiple display monitors, this value is the same for all monitors.
LOGPIXELSY
Number of pixels per logical inch along the height of the screen. If the device has multiple display monitors, this value is the same for all monitors.
BITSPIXEL
Number of adjacent color bits for each pixel.
PLANES
Number of color planes.
NUMBRUSHES
Number of device-specific brushes.
NUMPENS
Number of device-specific pens.
NUMFONTS
Number of device-specific fonts.
NUMCOLORS
Number of entries in the color table for the device, if the device has a color depth of no more than 8 bits per pixel. For devices with greater color depths, this method sets plDeviceCap equal to -1.
ASPECTX
Relative width of a device pixel used for line drawing.
ASPECTY
Relative height of a device pixel used for line drawing.
ASPECTXY
Diagonal width of the device pixel used for line drawing.
PDEVICESIZE
Reserved.
CLIPCAPS
Flag that indicates the clipping capabilities of the device. If the device can clip to a rectangle, this method sets plDeviceCap equal to 1. Otherwise, this method sets plDeviceCap equal to 0.
SIZEPALETTE
Number of entries in the system palette. This index is valid only if the device driver sets the RC_PALETTE bit in the RASTERCAPS index and is available only if the driver is compatible with Windows 3.1 or earlier.
NUMRESERVED
Number of reserved entries in the system palette. This index is valid only if the device driver sets the RC_PALETTE bit in the RASTERCAPS index and is available only if the driver is compatible with Windows 3.1 or earlier.
COLORRES
Actual color resolution of the device, in bits per pixel. This index is valid only if the device driver sets the RC_PALETTE bit in the RASTERCAPS index and is available only if the driver is compatible with Windows 3.1 or earlier.
RASTERCAPS
Value that indicates the raster capabilities of the device. The following table shows the possible values of plDeviceCap for this index.
Value
Description
RC_BANDING | Device requires banding support.
RC_BITBLT | Device is capable of transferring bitmaps.
RC_BITMAP64 | Device is capable of supporting bitmaps larger than 64K.
RC_DI_BITMAP | Device is capable of supporting the SetDIBits and GetDIBits functions.
RC_DIBTODEV | Device is capable of supporting the SetDIBitsToDevice function.
RC_FLOODFILL | Device is capable of performing flood fills.
RC_GDI20_OUTPUT | Device is capable of supporting features of Windows 3.1 or earlier.
RC_PALETTE | Device is palette-based.
RC_SCALING | Device is capable of scaling.
RC_STRETCHBLT | Device is capable of performing the StretchBlt function.
RC_STRETCHDIB | Device is capable of performing the StretchDIBits function.

CURVECAPS
Value that indicates the capabilities of the device for drawing curves. The following table shows the possible values of plDeviceCap for this index.
Value
Description
CC_NONE | Device does not support curves.
CC_CHORD | Device can draw chord arcs.
CC_CIRCLES | Device can draw circles.
CC_ELLIPSES | Device can draw ellipses.
CC_INTERIORS | Device can draw interiors.
CC_PIE | Device can draw pie wedges.
CC_ROUNDRECT | Device can draw rounded rectangles.
CC_STYLED | Device can draw styled borders.
CC_WIDE | Device can draw wide borders.
CC_WIDESTYLED | Device can draw borders that are wide and styled.

LINECAPS
Value that indicates the capabilities of the device for drawing lines. The following table shows the possible values of plDeviceCap for this index.
Value
Description
LC_NONE | Device does not support lines.
LC_INTERIORS | Device can draw interiors.
LC_MARKER | Device can draw a marker.
LC_POLYLINE | Device can draw a polyline.
LC_POLYMARKER | Device can draw multiple markers.
LC_STYLED | Device can draw styled lines.
LC_WIDE | Device can draw wide lines.
LC_WIDESTYLED | Device can draw lines that are wide and styled.

POLYGONALCAPS
Value that indicates the capabilities of the device for drawing polygons. The following table shows the possible values of plDeviceCap for this index.
Value
Description
PC_NONE | Device does not support polygons.
PC_INTERIORS | Device can draw interiors.
PC_POLYGON | Device can draw alternate-fill polygons.
PC_RECTANGLE | Device can draw rectangles.
PC_SCANLINE | Device can draw a single scanline.
PC_STYLED | Device can draw styled borders.
PC_WIDE | Device can draw wide borders.
PC_WIDESTYLED | Device can draw borders that are wide and styled.
PC_WINDPOLYGON | Device can draw winding-fill polygons.

TEXTCAPS
Value that indicates the text capabilities of the device. The following table shows the possible values of plDeviceCap for this index.
Value
Description
TC_OP_CHARACTER | Device is capable of character output precision.
TC_OP_STROKE | Device is capable of stroke output precision.
TC_CP_STROKE | Device is capable of stroke clip precision.
TC_CR_90 | Device is capable of 90-degree character rotation.
TC_CR_ANY | Device is capable of any character rotation.
TC_SF_X_YINDEP | Device can scale independently in the x- and y-directions.
TC_SA_DOUBLE | Device is capable of doubled character for scaling.
TC_SA_INTEGER | Device uses integer multiples only for character scaling.
TC_SA_CONTIN | Device uses any multiples for exact character scaling.
TC_EA_DOUBLE | Device can draw double-weight characters.
TC_IA_ABLE | Device can italicize.
TC_UA_ABLE | Device can underline.
TC_SO_ABLE | Device can draw strikeouts.
TC_RA_ABLE | Device can draw raster fonts.
TC_VA_ABLE | Device can draw vector fonts.
TC_RESERVED | Reserved; must be zero.
TC_SCROLLBLT | Device cannot scroll using a bit-block transfer. Note that this meaning may be the opposite of what you expect.

plDeviceCap
Pointer to a long integer that receives the requested capability.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IFMDraw::ReleaseDC

This method releases the device context (DC).

Syntax

HRESULT ReleaseDC( OLE_HANDLE hDC );

Parameters

hDC
Handle to the DC to be released.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method fails if the DC is not one that was retrieved by a call to IFMDraw::GetDC. Every call to IFMDraw::GetDC must be matched by a call to IFMDraw::ReleaseDC.

See Also

IFMDraw::GetDC


IfmManage

This interface, exposed by the Forms Manager object, provides methods that are used to manage forms.

Method
Description
IfmManage::CloseAppByName | Closes an application.
IfmManage::DeregisterStartedApplication | Removes the registration of an application from the Forms Manager.
IfmManage::fmMessageBox | Displays an application-modal message box.
IfmManage::fmStartHelp | Causes the application to enter the help display mode.
IfmManage::fmStopHelp | Closes all help message boxes.
IfmManage::fmStopMessageBox | Closes the message box for an application if one is currently displayed.
IfmManage::fmVerifyLoginState | Verifies that the user has entered a password if a password is set.
IfmManage::get_AppName | Gets the name of the application
IfmManage::get_AppSmallIcon | Gets the small icon for an application.
IfmManage::get_ClassMsgSink | Gets a pointer to the IASClassMsgSink interface of an application.
IfmManage::get_EventSink | Gets a pointer to the IASEventSink interface of an application.
IfmManage::get_HelpContext | Gets the help file currently associated with the application.
IfmManage::get_Menu | Gets a pointer to the control that is currently selected as the menu control for the application.
IfmManage::get_MenuTitlebar | Gets the title bar menu .
IfmManage::get_MenuVisible | Indicates whether or not the menu is visible.
IfmManage::get_Parent | Gets the owner of the Forms Manager.
IfmManage::get_Speech | Gets a pointer to the IAPCSpeech interface.
IfmManage::GetAppAlertState | Gets the alert state of an application.
IfmManage::GetFormsContextHandle | Gets the context handle of the Forms Manager.
IfmManage::LoadFormResource | Loads a form from a resource file.
IfmManage::LoadMenuResource | Loads a menu from a resource file.
IfmManage::MoveAppToForeground | Moves an application to the foreground.
IfmManage::MoveToForeground | Moves the specified Forms Manager to the foreground and gives it the focus.
IfmManage::PostMsg | Asynchronously posts a message to the message sink of an application.
IfmManage::PostMessageToApp | Posts a message to a running application.
IfmManage::put_AppName | Sets the name of an application.
IfmManage::put_AppSmallIcon | Sets the small icon for an application.
IfmManage::put_ClassMsgSink | Registers the class message sink for an application with the Forms Manager.
IfmManage::put_EventSink | Registers the event sink for an application with the Forms Manager.
IfmManage::put_HelpContext | Sets the specified help file.
IfmManage::put_Menu | Places a specified menu control into the menu form.
IfmManage::put_MenuVisible | Sets whether or not a menu is visible.
IfmManage::RegisterStartedApplication | Registers an application with the Forms Manager, indicating that the application has started.
IfmManage::RestoreAppZOrder | Restores the z-order of an application.
IfmManage::RestoreZOrder | Restores the z-order for a Forms Manager to the value of the z-order before the last call to IfmManage::MoveToForeground.
IfmManage::SendMsg | Synchronously sends a message to the message sink.
IfmManage::SetAppAlertState | Sets the alert state of an application.
IfmManage::Start | Registers a form with the Forms Manager.
IfmManage::Stop | Removes the registration from a form with the Forms Manager.
IfmManage::StopAll | Removes the registration from all the forms for an application with the Forms Manager.

Remarks

The IfmManage interface extends the IDispatch interface.


IfmManage::CloseAppByName

This method closes an application.

Syntax

HRESULT CloseAppByName( BSTR bstrAppName, BOOL fTerminate );

Parameters

bstrAppName
Unicode string that contains the name of the application to shut down.
fTerminate
Boolean that indicates whether to terminate the specified application. TRUE indicates that the method terminates the application. FALSE indicates that the method does not terminate the application.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

Use this method only when reinstalling the .exe file of an application. Do not use this method during the normal operation of an application.


IfmManage::DeregisterStartedApplication

This method removes the registration of an application from the Forms Manager.

Syntax

HRESULT DeregisterStartedApplication( OLE_HANDLE hFC, BSTR bstrAppName );

Parameters

hFC
Handle to Forms Manager’s context. It is FC_MAINFACEPLATE.
bstrAppName
Unicode string that contains the name of the application.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

An application needs to register with the Forms Manager to get the focus. An application registered with the Forms Manager should call IfmManage::DeregisterStartedApplication to remove the registration from the application before exiting. Once an application is no longer registered with the Forms Manager, the shell needs to restart the application to restore the focus to that application.

Context handles are always to the faceplate screen.

See Also

IfmManage::RegisterStartedApplication


IfmManage::fmMessageBox

This method displays an application-modal message box.

Syntax

HRESULT fmMessageBox( BSTR bstrMsg, BSTR bstrCaption, LONG uType, LONG Flags, LONG *pRes );

Parameters

bstrMsg
Unicode string that contains text of the message. The message can be a file name if the flag FMMB_FLG_FILENAME is set in Flags, or in HTML if the flag FMMB_FLG_HTML is set in Flags.
bstrCaption
Unicode string that contains the caption to place in the title bar of the message box form. If bstrCaption is NULL, the application name property of the Forms Manager is used, and the AppSmallIcon from the application is displayed for the form icon.
uType
Specifies one of the following types:
MB_ABORTRETRYIGNORE
MB_NOBUTTONS
MB_OKCANCEL
MB_OK
MB_RETRYCANCEL
MB_YESNOCANCEL
MB_YESNO

The type flags can be combined with one of the following optional icons:
MB_APC_ICONCHECK
MB_ICONASTERISK
MB_ICONEXCLAMATION
MB_ICONHAND
MB_ICONQUESTION

Flags
Specifies how the message box is displayed. It is any combination of the following values:
FMMB_FLG_AUTODISMISS
Automatically dismisses the message box after a specified time.
FMMB_FLG_TTS
Reads the message aloud using text-to-speech.
FMMB_FLG_BEEP
Plays an audible beep when the message box appears.
FMMB_FLG_FILENAME
Specifies that bstrMsg is the name of a file that is opened to retrieve the actual text of the message.
FMMB_FLG_HTML
Treats the message as HTML text.
FMMB_FLG_OUTOFSTORAGE
Creates an out-of-storage message box. If this flag is set, bstrMsg and the FMMB_FLG_FILENAME flag are ignored.
pRes
Pointer to a long integer that contains the user’s response. It is one of the following values, depending on the type of message box:
IDABORT
IDCANCEL
IDIGNORE
IDNO
IDOK
IDRETRY
IDYES

Return Values

S_OK indicates success. E_INVALIDARG indicates that an invalid argument was entered. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method is a synchronous call that does not return until user finishes interacting with the message box.

You must call this method from the thread that created the Forms Manager object. While that thread executes this method, a dispatch loop within this method calls the sinks on the Forms Manager object. If a message is posted to the thread using the thread identifier while this method executes, the message is removed from the message queue internally.


IfmManage::fmStartHelp

This method causes the application to enter the help display mode.

Syntax

HRESULT fmStartHelp( BSTR bstrFileName, DWORD dwFlags, DWORD dwTopicID );

Parameters

bstrFileName
Unicode string that contains the name of the Help text file. If dwFlags is not APCHELP_INDEX, bstrFieldName can be 0.
dwFlags
Specifies one of the following flags:
APCHELP_INDEX
Shows the Help index.
APCHELP_TOPIC
Shows a Help topic.
dwTopicID
Specifies the topic file name if dwFlags is APCHELP_TOPIC. Otherwise, it is set to 0.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

When this method is called, it hides the form’s option menu.

See Also

IfmManage::fmStopHelp


IfmManage::fmStopHelp

This method closes all help message boxes.

Syntax

HRESULT fmStopHelp( );

Return Values

S_OK indicates that the method successfully stopped Help. S_FALSE indicates that an error occurred.

See Also

IfmManage::fmStartHelp


IfmManage::fmStopMessageBox

This method closes the message box for an application if one is currently displayed.

Syntax

HRESULT fmStopMessageBox( );

Return Values

S_OK indicates that the method successfully closed the message box. S_FALSE indicates that an error occurred.


IfmManage::fmVerifyLoginState

This method verifies that the user has entered a password if a password is set.

Syntax

HRESULT fmVerifyLoginState( BSTR bstrTitle, BOOL fDoLogin, BOOL fKeepFocusOnFail, BOOL *pfLoggedIn);

Parameters

bstrTitle
Unicode string that contains the title to display, usually the name of the application.
fDoLogin
Boolean that is set to TRUE if the user is not currently logged on and needs to be logged on, or to FALSE otherwise.
fKeepFocusOnFail
Boolean that indicates whether or not to keep the foreground focus if the log in fails. Set to TRUE if the current foreground focus should be kept, or to FALSE if not.
pfLoggedIn
Pointer to a Boolean that is set to TRUE if the user is logged on, or to FALSE otherwise.

Return Values

An appropriate HRESULT value is returned.


IfmManage::get_AppName

This method gets the name of the application.

Syntax

HRESULT get_AppName( BSTR *pbstrAppname );

Parameters

pbstrAppName
Pointer to a Unicode string that contains the name of the application.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IfmManage::put_AppName.


IfmManage::get_AppSmallIcon

This method gets the small icon for an application.

Syntax

HRESULT get_AppSmallIcon( OLE_HANDLE *phSmallIcon );

Parameters

phSmallIcon
Pointer to the handle of an icon.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IfmManage::put_AppSmallIcon


IfmManage::get_ClassMsgSink

This method gets a pointer to the IASClassMsgSink interface of an application.

Syntax

HRESULT get_ClassMsgSink( IDispatch **ppdispSink );

Parameters

ppdispSink
Pointer to the pointer to the application’s class message sink.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IfmManage::put_ClassMsgSink


IfmManage::get_EventSink

This method gets a pointer to the IASEEventSink interface of an application.

Syntax

HRESULT get_EventSink( IDispatch **ppdispSink );

Parameters

ppdispSink
Pointer to the pointer to the application’s event sink.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IfmManage::put_EventSink


IfmManage::get_HelpContext

This method gets the help file currently associated with the application.

Syntax

HRESULT get_HelpContext( BSTR *pbstrHelpFile, BSTR *pbstrHelpTopic );

Parameters

pbstrHelpFile
Pointer a Unicode string that contains the name of a Help index file.
pbstrHelpTopic
Pointer to a Unicode string that contains the name of a Help topic file.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IfmManage::put_HelpContext


IfmManage::get_Menu

This method gets a pointer to the control that is currently selected as the menu control for the application.

Syntax

HRESULT get_Menu( IDispatch **ppdispMenu );

Parameters

ppdispMenu
Pointer to a pointer to a power list box control.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

The only valid control that can be set on a menu is a power list box control.

See Also

IfmManage::put_Menu


IfmManage::get_MenuTitlebar

This method gets the title bar menu.

Syntax

HRESULT get_MenuTitlebar( IASTitlebar **ppTitlebar );

Parameters

ppTitlebar
Pointer to a pointer to a title bar.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IfmManage::get_MenuVisible

This method indicates whether or not the menu is visible.

Syntax

HRESULT get_MenuVisible( BOOL *pfVisible );

Parameters

pfVisible
Pointer to a Boolean that is set to TRUE if the menu is visible, or to FALSE if it is hidden.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IfmManage::put_MenuVisible


IfmManage::get_Parent

This method gets the owner of the Forms Manager.

Syntax

HRESULT get_Parent( IDispatch **ppdispParent );

Parameters

ppdispParent
Pointer to the pointer to the Forms Manager's parent.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IfmManage::get_Speech

This method gets a pointer to the IAPCSpeech interface.

Syntax

HRESULT get_Speech( IAPCSpeech **ppSpeech );

Parameters

ppSpeech
Pointer to the pointer to the form’s speech interface.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IfmManage::GetAppAlertState

This method retrieves the alert state of an application.

Syntax

HRESULT GetAppAlertState( OLE_HANDLE hFC, BOOL fCurrentUser, BSTR bstrAppName, BSTR bstrAlertName, BOOL *pfAlert, LONG *pAlertVal );

Parameters

hFC
Handle to the Forms Manager’s context. It is FC_MAINFACEPLATE.
fCurrentUser
Unsupported in this version.
bstrAppName
Unicode string that contains the name of application targeted by the alert state query.
bstrAlertName
Unicode string that contains the name of the alert being queried.
pfAlert
Pointer to a Boolean that indicates alert status. TRUE indicates that an alert was raised for the application. FALSE indicates that the alert was cleared.
pAlertVal
Pointer to a long integer that contains the value of the alert.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IfmManage::SetAppAlertState


IfmManage::GetFormsContextHandle

This method gets the context handle of the Forms Manager.

Syntax

HRESULT GetFormsContextHandle( OLE_HANDLE *phFC );

Parameters

phFC
Pointer to the handle to the Forms Manager’s context. It is FC_MAINFACEPLATE.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

Context handles are always to the faceplate screen.


IfmManage::LoadFormResource

This method loads a form from a resource file.

Syntax

HRESULT LoadFormResource( OLE_HANDLE hFC, long wRsrcID, IDispatch **ppForm, IDispatch *pDispSink );

Parameters

hFC
OLE_HANDLE to the Forms Manager context.
wRsrcID
Long integer that contains the identifier of the resource file.
ppForm
Pointer to the pointer to a form.
pDispSink
Pointer to an event sink.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument was entered. E_ACCESSDENIED indicates that access to the resource file was denied. If an error occurs, the appropriate HRESULT value is returned.

Remarks

For information about how to layout a resource, see Constraint-Based Layout and FA_* Values.‹For information about how to layout a resource, see Appendix F, "Constraint-Based Layout and FA_* Values."›


IfmManage::LoadMenuResource

This method loads a menu from a resource file.

Syntax

HRESULT LoadMenuResource(OLE_HANDLE hFC, long wRsrcID, IDispatch **ppMenu);

Parameters

hFC
OLE_HANDLE to the Forms Manager context.
wRsrcID
Long integer that contains the identifier of the resource file.
ppMenu
Pointer to the pointer to a menu.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument was entered. E_ACCESSDENIED indicates that access to the resource file was denied. If an error occurs, the appropriate HRESULT value is returned.

Remarks

For information about how to layout a resource, see Constraint-Based Layout and FA_* Values.‹For information about how to layout a resource, see Appendix F, "Constraint-Based Layout and FA_* Values."›


IfmManage::MoveAppToForeground

This method moves an application to the foreground.

Syntax

HRESULT MoveAppToForeground( LONG ProcID, LONG *pZOrder, LONG Flags );

Parameters

ProcID
The process identifier of the application.
pZOrder
Pointer to the current z-order of the process. It can be NULL.
Flags
Currently, there is only one flag, ASFC_APPSTYLEFLG_POPUP.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument was entered. If an error occurs, the appropriate HRESULT value is returned.

Remarks

The Forms Manager maintains a z-order for active, registered processes. If you want your application to present information to a user in a pop-up control, call this method with the ASFC_APPSTYLEFLG_POPUP flag. The application receives the current z-order of the application, and then moves to the foreground without sending a WM_APPACTIVATE message to the application that was in the foreground before the call to this method. Although this method changes the foreground application, this method does not change the application context in which the user works. When finished with the pop-up control, your application should call IfmManage::RestoreAppZOrder with the z-order that the application received from the original call to IfmManage::MoveAppToForeground.

See Also

IfmManage::RestoreAppZOrder, IfmManage::MoveToForeground


IfmManage::MoveToForeground

This method moves the specified Forms Manager to the foreground and gives it the focus.

Syntax

HRESULT MoveToForeground( BOOL fThis, LONG *pZOrder );

Parameters

fThis
Boolean that is set to TRUE to move the specified Forms Manager to the foreground, or to FALSE to move the default Forms Manager for the application to the foreground.
pZOrder
Pointer to the current z-order.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

Only complex applications that use multiple Forms Manager objects should use this method. Application that use a single Forms Manager object should use IfmManage::MoveAppToForeground.

This method only affects the z-order for a single Forms Manager. If the application does not have the foreground, the change in z-order is not visible until the application is brought to the foreground.

To restore the original z-order of your Forms Manager after using this method, your application should call IfmManage::RestoreZOrder with the z-order that the application received from the original call to IfmManage::MoveToForeground.

See Also

IfmManage::RestoreZOrder, IfmManage::MoveAppToForeground


IfmManage::PostMsg

This method asynchronously posts a message to the message sink of an application.

Syntax

HRESULT PostMsg( long uMsg, long wParam, long lParam );

Parameters

uMsg
Specifies the message identifier.
wParam
Long integer that contains the wParam of the message.
lParam
Long integer that contains the lParam of the message.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method places the message in the message queue for the application to handle in order.

See Also

IfmManage::PostMessageToApp, IfmManage::SendMsg


IfmManage::PostMessageToApp

This method posts a message to a running application.

Syntax

HRESULT PostMessageToApp( long uMsg, long wParam, long lParam );

Parameters

uMsg
Specifies the message identifier.
wParam
Long integer that contains the wParam of the message.
lParam
Long integer that contains the lParam of the message.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method provides a simple way to conduct communication between applications. To use PostMessageToApp, both applications must have the message name defined in a common header file. Both the client and server application must invoke RegisterWindowMessage to register the message name. To receive messages, the server application must call IfmManage::RegisterStartedApplication, with the message name as the third parameter. Any message with this name that is posted by the client application with PostMessageToApp is sent to the server’s event sinks.

If speed is important, memory-mapped files are a much faster way to implement interprocess communication.

See Also

IfmManage::RegisterStartedApplication


IfmManage::put_AppName

This method sets the name of an application.

Syntax

HRESULT put_AppName ( BSTR bstrAppName );

Parameters

bstrAppName
Unicode string that contains the application name to set.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IfmManage::get_AppName.


IfmManage::put_AppSmallIcon

This method sets the small icon for an application.

Syntax

HRESULT set_AppSmallIcon( OLE_HANDLE hSmallIcon );

Parameters

hSmallIcon
Handle of an icon.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IfmManage::get_AppSmallIcon


IfmManage::put_ClassMsgSink

This method registers the class message sink for an application with the Forms Manager.

Syntax

HRESULT put_ClassMsgSink( IDispatch *pdispSink );

Parameters

pdispSink
Pointer to the application’s class message sink. Set to NULL to clear the message sink.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

The application must support a class message sink or this method fails.

See Also

IASClassMsgSink, IfmManage::get_ClassMsgSink


IfmManage::put_EventSink

This method registers the event sink for an application with the Forms Manager.

Syntax

HRESULT put_EventSink( IDispatch *pdispSink );

Parameters

pdispSink
Pointer to the application’s event sink. Set to NULL to clear the event sink.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

The application must support an event sink or the method fails.

See Also

IASEventSink, IfmManage::get_EventSink


IfmManage::put_HelpContext

This method sets a specified help file.

Syntax

HRESULT put_HelpContext( BSTR bstrHelpFile, BSTR bstrHelpTopic );

Parameters

bstrHelpFile
Unicode string that contains the name of a Help index file.
bstrHelpTopic
Unicode string that contains the name of a Help topic file.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IfmManage::get_HelpContext


IfmManage::put_Menu

This method places a specified control into the menu form.

Syntax

HRESULT put_Menu( IDispatch *pdispMenu, short wID );

Parameters

pdispMenu
Pointer to the control to be placed in the menu form. The control must be a power list box control.
wID
Short integer that contains the menu identifier.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument was entered. E_ACCESSDENIED indicates that access to the resource file was denied. If an error occurs, the appropriate HRESULT value is returned.

Remarks

There can only be one menu control on the menu form at a time. This method releases the current menu control, if one is present, and replaces it with a new one.

See Also

IfmManage::get_Menu


IfmManage::put_MenuVisible

This method sets whether or not a menu is visible.

Syntax

HRESULT put_MenuVisible( BOOL pfVisible );

Parameters

pfVisible
Pointer to a Boolean that is set to TRUE for a visible menu, or to FALSE for an invisible menu.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method effectively allows an application to invoke or to dismiss a menu.

See Also

IfmManage::get_MenuVisible


IfmManage::RegisterStartedApplication

This method registers an application with the Forms Manager, indicating that the application has started.

Syntax

HRESULT RegisterStartedApplication( OLE_HANDLE hFC BSTR bstrAppName LONG AppMsgID LONG Flags );

Parameters

hFC
Handle to the Forms Manager’s context. It is FC_MAINFACEPLATE.
bstrAppName
Unicode string that contains the name of the application.
AppMsgID
Message identifier to be associated with this application.
Flags
Not currently implemented.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

An application needs to call this method to get the focus. This method associates a name for an application with a running process. The name should correspond the name of the application in the shell. While an application remains registered with the Forms Manager, the shell does not need to restart the application in order to restore the focus to that application. An application that is registered with the Forms Manager should call IfmManage::DeregisterStartedApplication to remove the registration from the application before exiting.

Context handles are always to the faceplate screen.

To enable message passing between applications

  1. Define the message name in a shared header file.
  2. The first application obtains a unique message identifier by calling RegisterWindowsMessage.

    The AppMsgID parameter is a Windows-based message identifier.

  3. A second application passes the unique message identifier to RegisteredStartedApplication.
  4. The second application invokes RegisterWindowsMessage.
  5. The second application uses PostMessageToApp to send messages to the first application.

See Also

IfmManage::DeregisterStartedApplication


IfmManage::RestoreAppZOrder

This method restores the z-order of an application.

Syntax

HRESULT RestoreAppZOrder( LONG ZOrder );

Parameters

ZOrder
Set to 0 to force the application to the background. Set to a nonzero value to restore the z-order of the application to a previous value obtained from a call to IfmManage::MoveAppToForeground.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

After calling IfmManage::MoveAppToForeground, your application should restore the z-order of the application by calling IfmManage::RestoreAppZOrder with the z-order that the application received from the call to IfmManage::MoveAppToForeground.

See Also

IfmManage::MoveAppToForeground


IfmManage::RestoreZOrder

This method resets the z-order for a Forms Manager to the value of the z-order before the last call to IfmManage::MoveToForeground.

Syntax

HRESULT RestoreZOrder( LONG ZOrder );

Parameters

ZOrder
Set to 0 to force the Forms Manager to the background. Set to a nonzero value to restore the ZOrder to a previous value obtained from IfmManage::MoveToForeground. This parameter is ignored if the default Forms Manager has the foreground.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

After calling IfmManage::MoveToForeground, your application can restore the z-order of the application by calling IfmManage::RestoreZOrder with the z-order that the application received from the call to IfmManage::MoveToForeground.

See Also

IfmManage::MoveToForeground


IfmManage::SendMsg

This method synchronously sends a message to the message sink.

Syntax

HREULT SendMsg( long uMsg, long wParam, long lParam );

Parameters

uMsg
Specifies the message identifier.
wParam
Long integer that contains the wParam of the message.
lParam
Long integer that contains the lParam of the message.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

Use this method to place a message at the head of the message queue.

See Also

IfmManage::PostMessageToApp, IfmManage::PostMsg


IfmManage::SetAppAlertState

This method sets the alert state of an application.

Syntax

HRESULT SetAppAlertState( OLE_HANDLE hFC, BOOL fCurrentUser, BSTR bstrAppName, BSTR bstrAlertName, LONG AlertAction, LONG AlertVal );

Parameters

hFC
Handle to the Forms Manager’s context. It is FC_MAINFACEPLATE.
fCurrentUser
Unsupported for this version.
bstrAppName
Unicode string that contains the name of the application whose alert state has been set.
bstrAlertName
Unicode string that contains the name of the type of alert.
AlertAction
Long integer that contains the type of alert action. It can be one of the following values:
Alert action
Value
FMAA_ACTION_CLEAR | 0
FMAA_ACTION_RAISE_VALUE | 1
FMAA_ACTION_CLEAR_MASK | 2
FMAA_ACTION_RAISE_MASK | 3

AlertVal
Long integer that contains the value of the alert. Ignored if AlertAction is FMAA_ACTION_CLEAR.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IfmManage::GetAppAlertState


IfmManage::Start

This method registers a form with the Forms Manager.

Syntax

HRESULT Start( IDispatch *pdispForm );

Parameters

pdispForm
Pointer to the form to be registered.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IfmManage::Stop


IfmManage::Stop

This method removes the registration from a form with the Forms Manager.

Syntax

HRESULT Stop( IDispatch *pdispForm );

Parameters

pdispForm
Pointer to the form from which you want to remove the registration.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IfmManage::Start, IfmManage::StopAll


IfmManage::StopAll

This method removes the registration from all of the forms for an application from the Forms Manager.

Syntax

HRESULT StopAll( void );

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IfmManage::Stop


IfmSystem

This interface is exposed by the Forms Manager and provides some system-level methods.

Method
Description
IfmSystem::CreateFMCompatibleBitMap | Creates a compatible bitmap.
IfmSystem::CreateFMCompatibleDC | Creates a compatible device context (DC).
IfmSystem::GetFMSystemFont | Retrieves one of the two system fonts.
IfmSystem::GetFormDisplayCaps | Retrieves the display capabilities.

Remarks

The IfmSystem interface extends the IDispatch interface.


IfmSystem::CreateFMCompatibleBitmap

This method creates a compatible bitmap.

Syntax

HRESULT CreateFMCompatibleBitmap( OLE_HANDLE hFC, OLE_HANDLE *phBitMap, LONG Width, LONG Height );

Parameters

hFC
Handle to the Forms Manager’s context. It is FC_MAINFACEPLATE.
phBitmap
Pointer to the handle to the created bitmap.
Width
Specifies the width of the bitmap.
Height
Specifies the height of the bitmap.

Return Values

S_OK indicates success. E_OUTOFMEMORY indicates that the system is out of memory. If an error occurs, the appropriate HRESULT value is returned.


IfmSystem::CreateFMCompatibleDC

This method creates a compatible device context (DC).

Syntax

HRESULT CreateFMCompatibleDC( OLE_HANDLE hFC, OLE_HANDLE *phDC );

Parameters

hFC
Handle to the Forms Manager’s context. It is FC_MAINFACEPLATE.
phDC
Pointer to the handle to the created DC.

Return Values

S_OK indicates success. E_OUTOFMEMORY indicates that the system is out of memory. If an error occurs, the appropriate HRESULT value is returned.


IfmSystem::GetFMSystemFont

This method retrieves one of the two system fonts.

Syntax

HRESULT GetFMSystemFont( OLE_HANDLE hFC, BOOL fSmall, IDispatch **ppdispFont);

Parameters

hFC
Handle to the Forms Manager’s context. It is FC_MAINFACEPLATE.
fSmall
Boolean that is set to TRUE for the small system font, or to FALSE for the large system font.
ppdispFont
Pointer to the pointer to the font.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

Context handles are always to the faceplate screen.

For Microsoft Windows CE for the Auto PC, the font size is 10000 times value of the lower 32 bits of the psize variable used in the Component Object Module (COM) IFont::get_Size and IFont::put_Size methods.


IfmSystem::GetFormDisplayCaps

This method retrieves the display capabilities.

Syntax

HRESULT GetFormDisplayCaps( OLE_HANDLE hFC, LONG nIndex, LONG *pRetInfo);

Parameters

hFC
Handle to the Forms Manager’s context. It is FC_MAINFACEPLATE.
nIndex
Specifies the index of the display capabilities item to return. See the GetDeviceCaps function for Windows-based desktop platforms for a list.
pRetInfo
Pointer to the long integer used to return the display capabilities.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IfmCollection

This interface is exposed by the Forms Manager collection object and provides methods for handling multiple Forms Managers.

Method
Description
IfmCollection::get_Count | Gets the number of Forms Managers in the collection.
IfmCollection::GetFocus | Gets which Forms Manager has focus.
IfmCollection::Item | Gets a pointer to a specified Forms Manager.
IfmCollection::SetFocus | Sets the focus to a specified Forms Manager.

Remarks

The IfmCollection interface extends the IDispatch interface.


IfmCollection::get_Count

This method gets the number of Forms Managers in the collection

Syntax

HRESULT get_Count( long *pcItems );

Parameters

pcItems
Pointer to the number of Forms Managers in the collection.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IfmCollection::GetFocus

This method gets which Forms Manager has focus.

Syntax

HRESULT GetFocus( IDispatch **ppdispfmManage );

Parameters

ppdispfmManage
Pointer to the pointer to the Forms Manager that currently has focus.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IfmCollection::SetFocus


IfmCollection::Item

This method gets a pointer to a specified Forms Manager.

Syntax

HRESULT Item( VARIANT index, IDispatch **ppdisp );

Parameters

index
Index of the specified Forms Manager.
ppdisp
Pointer to the pointer to the specified Forms Manager.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IfmCollection::SetFocus

This method sets the focus to a specified Forms Manager.

Syntax

HRESULT SetFocus( IDispatch *pdispfmManage );

Parameters

pdispfmManage
Pointer to the Forms Manager to receive focus.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IfmCollection::GetFocus


IVCmdAttributes

This interface provides methods to set various attributes of the voice command object, including audio output, recognition mode, and whether or not recognition is enabled.

Method
Description
IVCmdAttributes::AwakeStateGet | Retrieves the awake state for a voice command site
IVCmdAttributes::AwakeStateSet | Sets the awake state for a voice command site.
IVCmdAttributes::EnabledGet | Gets whether speech recognition is enabled or disabled for a voice command site.
IVCmdAttributes::EnabledSet | Sets whether speech recognition is enabled or disabled for a voice command site.
IVCmdAttributes::SpeakerGet | Gets the name of the current speaker for a voice command site.
IVCmdAttributes::SpeakerSet | Sets the name of the current speaker for a voice command site.
IVCmdAttributes::SRModeGet | Gets the globally unique identifier (GUID) of the speech-recognition mode used for the site.
IVCmdAttributes::SRModeSet | Sets the speech-recognition mode used by a voice command site.
IVCmdAttributes::ThresholdGet | Gets the threshold level of the speech-recognition engine used by a voice command site.
IVCmdAttributes::ThresholdSet | Sets the threshold level for the speech-recognition engine used by a voice command site.

Remarks

This interface is supported by all voice command objects.


IVCmdAttributes::AwakeStateGet

This method retrieves the awake state for a voice command site.

Syntax

HRESULT AwakeStateGet( DWORD*pdwAwake );

Parameters

pdwAwake
[out] Pointer to a DWORD that receives the current state of speech recognition for the site. Set to TRUE if the site is awake, or to FALSE if it is asleep.

Return Values

NOERROR
The method successfully retrieved the awake state for a voice command site.
E_INVALIDARG
The argument is invalid.
VCMDERR_INVALIDMODE
No site exists, the site does not support this attribute, or the voice command object is already registered with a site.
VCMDERR_OUTOFMEM
There is no more memory.
VCMDERR_VALUEOUTOFRANGE
The value is out of range.

Remarks

When the site is awake, it listens for commands from any active voice menu for the active application. When the site is asleep, it listens for commands only from sleep menus—those that were activated with the dwFlags parameter of the IVCmdMenu::Activate method set to VWGFLAG_ASLEEP. Commands from such menus become active only when the site is asleep, and they become inactive when the site is awake. A sleep menu typically contains at least a “Wake up” command that resumes speech recognition.

See Also

IVCmdAttributes::AwakeStateSet


IVCmdAttributes::AwakeStateSet

This method sets the awake state for a voice command site.

Syntax

HRESULT AwakeStateSet( DWORD dwAwake );

Parameters

dwAwake
[in] Specifies whether the awake state of the voice command site. Set to TRUE to cause the site to wake up, or to FALSE to cause it to go to sleep.

Return Values

NOERROR
The method successfully set the awake state for a voice command site.
E_INVALIDARG
The argument is invalid.
VCMDERR_INVALIDMODE
No site exists, the site does not support this attribute, or the voice command object is already registered with a site.
VCMDERR_OUTOFMEM
There is no more memory.
VCMDERR_VALUEOUTOFRANGE
The value is out of range.

Remarks

If a voice navigation application is installed on the user’s computer, suspending speech recognition by using AwakeStateSet typically causes the voice navigation application to activate a “wake up” menu.

Calling AwakeStateSet allows the user to temporarily suspend speech recognition for a site. For example, the user might want to suspend speech recognition from the computer microphone during a telephone conversation and resume recognition when the conversation is finished. The user resumes recognition by speaking an appropriate command from a sleep menu—for example, “Wake up.”

The sleep state for a site is saved between uses of the site, even if the user shuts down the computer in the meantime.

If a voice navigation application is installed on the user’s computer, an application may not need to set the sleep state. However, it may call this method to verify that speech recognition is awake. For example, if an application asks—using with voice text or text-to-speech—”Do you want to print the document?” it might enable and wake up speech recognition for the site to receive the user’s reply. The application should then restore speech recognition to its previous state.


IVCmdAttributes::EnabledGet

This method gets whether speech recognition is enabled or disabled for a voice command site.

Syntax

HRESULT EnabledGet( DWORD *dwEnabled );

Parameters

dwEnabled
[out] Specifies whether or not speech recognition is enabled. Set to TRUE if speech recognition is enabled for the site, or to FALSE if it is disabled.

Return Values

NOERROR
The method successfully retrieved whether speech recognition is enabled or disabled.
E_INVALIDARG
The argument is invalid.
VCMDERR_INVALIDMODE
No site exists, the site does not support this attribute, or the voice command object is already registered with a site.
VCMDERR_OUTOFMEM
There is no more memory.
VCMDERR_VALUEOUTOFRANGE
The value is out of range.

Remarks

When speech recognition is disabled, the engine does not recognize any command from any menu, whether speech recognition is awake or asleep or any menus are active. An application would use the IVCmdAttributes::EnabledSet method to allow the user to turn speech recognition completely off, as opposed to suspending speech recognition temporarily by putting the site to sleep.

The enabled state for a site is saved between uses of the site, even if the user shuts down the computer in the meantime.


IVCmdAttributes::EnabledSet

This method sets whether speech recognition is enabled or disabled for a voice command site.

Syntax

HRESULT EnabledSet( DWORD dwEnabled );

Parameters

dwEnabled
[out] Specifies whether or not speech recognition is enabled. Set to TRUE to enable speech recognition, or to FALSE to disable it.

Return Values

NOERROR
The method successfully sets whether speech recognition is enabled or disabled.
E_INVALIDARG
The argument is invalid.
VCMDERR_INVALIDMODE
No site exists, the site does not support this attribute, or the voice command object is already registered with a site.
VCMDERR_OUTOFMEM
There is no more memory.
VCMDERR_VALUEOUTOFRANGE
The value is out of range.

Remarks

Calling EnabledSet allows the user to completely turn off speech recognition for a site so that nothing is recognized, including commands on sleep menus. For example, the user might want to disable speech recognition from the computer microphone during a meeting so that speech recognition remains off, even if a particpant inadvertently speaks a command on a sleep menu.

The enabled state for a site is saved between uses of the site, even if the user shuts down the computer in the meantime.


IVCmdAttributes::SpeakerGet

This method gets the name of the current speaker for a voice command site.

Syntax

HRESULT SpeakerGet( PTSTR pszSpeaker, DWORD dwSize, DWORD *pdwNeeded);

Parameters

pszSpeaker
[in/out] Pointer to a buffer that stores the null-terminated string that contains the name of the current speaker.
dwSize
[in] Specifies, in bytes, the size of the buffer specified by pszSpeaker. If the buffer is too small, the member returns an error and fills pdwNeeded with the number of bytes needed to store the speaker string.
pdwNeeded
[out] Pointer to a DWORD that receives the number of bytes needed for the speaker string.

Return Values

NOERROR
The method successfully retrieved the name of the current speaker.
E_INVALIDARG
The argument is invalid.
VCMDERR_INVALIDMODE
No site exists, the site does not support this attribute, or the voice command object is already registered with a site.
VCMDERR_NOTSUPPORTED
The function is not supported by the engine.
VCMDERR_OUTOFMEM
There is no more memory.
VCMDERR_VALUEOUTOFRANGE
The value is out of range.

Remarks

Changing the speaker name unloads all training for the previous speaker and loads the training for the new speaker. If no training exists for the new speaker, the application starts with default training.

The speaker name for a site is saved between uses of the site, even if the user shuts down the computer in the meantime.


IVCmdAttributes::SpeakerSet

This method sets the name of the current speaker for a voice command site.

Syntax

HRESULT SpeakerSet( PTSTR pszSpeaker);

Parameters

pszSpeaker
[in] Pointer to the null-terminated string that contains the name of the speaker to set. If the speaker is unknown, this parameter can be an empty string.

Return Values

NOERROR
The method successfully set the name of the current speaker .
E_INVALIDARG
The argument is invalid.
VCMDERR_INVALIDMODE
No site exists, the site does not support this attribute, or the voice command object is already registered with a site.
VCMDERR_NOTSUPPORTED
The function is not supported by the engine.
VCMDERR_OUTOFMEM
There is no more memory.
VCMDERR_VALUEOUTOFRANGE
The value is out of range.

Remarks

The speaker name for a site is saved between uses of the site, even if the user shuts down the computer in the meantime.

The speaker string is not case sensitive.

If a voice navigation application is installed on the user’s computer, an application may not need to set the speaker name.


IVCmdAttributes::SRModeGet

This method gets the globally unique identifier (GUID) of the speech-recognition mode used for the site.

Syntax

HRESULT SRModeGet( GUID *pgMode);

Parameters

pgMode
[out] Pointer to the variable that receives the GUID assigned to the speech-recognition mode.

Return Values

NOERROR
The method successfully retrieved the GUID of the speech-recognition mode.
E_INVALIDARG
The argument is invalid.
VCMDERR_INVALIDMODE
No site exists, the site does not support this attribute, or the voice command object is already registered with a site.
VCMDERR_NOTSUPPORTED
The function is not supported by the engine.
VCMDERR_OUTOFMEM
There is no more memory.

Remarks

A speech-recognition engine typically provides an assortment of modes that it can use to recognize speech in different languages or dialects. A voice command site uses a single speech-recognition mode.

The speech-recognition mode for a site is saved between uses of the site, even if the user shuts down the computer in the meantime.

For an Auto PC, there is usually only one speech recognition mode.


IVCmdAttributes::SRModeSet

This method sets the speech-recognition mode used by a voice command site.

Syntax

HRESULT SRModeSet( GUID gMode);

Parameters

gMode
[in] Globally unique identifier (GUID) of the speech-recognition mode to set for the site. If the mode does not exist, an error is returned and the mode is not changed.

Return Values

NOERROR
The method successfully set the speech-recognition mode.
E_INVALIDARG
The argument is invalid.
VCMDERR_INVALIDMODE
No site exists, the site does not support this attribute, or the voice command object is already registered with a site.
VCMDERR_NOTSUPPORTED
The function is not supported by the engine.
VCMDERR_OUTOFMEM
There is no more memory.
VCMDERR_VALUEOUTOFRANGE
The value is out of range.

Remarks

The speech-recognition mode for a site is saved between uses of the site, even if the user shuts down the computer in the meantime.

If a voice navigation application is installed on the user’s computer, an application may not need to set the speech-recognition mode.

An application can use a speech-recognition enumerator to determine which speech-recognition modes are available.

For Auto PC, there is usually only one speech recognition mode.


IVCmdAttributes::ThresholdGet

This method gets the threshold level of the speech-recognition engine used by a voice command site.

Syntax

HRESULT ThresholdGet( DWORD *pdwThreshold);

Parameters

pdwThreshold
[out] Pointer to a DWORD that receives the threshold level.

Return Values

NOERROR
The method successfully retrieved the threshold level of the speech-recognition engine.
E_INVALIDARG
The argument is invalid.
VCMDERR_INVALIDMODE
No site exists, the site does not support this attribute, or the voice command object is already registered with a site.
VCMDERR_NOTSUPPORTED
The function is not supported by the engine.
VCMDERR_OUTOFMEM
There is no more memory.

Remarks

The threshold level is a value from 0 to 100 that indicates the point below which an engine rejects an utterance as unrecognized. A value of 0 indicates that the engine should match any utterance to the closest phrase match. A value of 100 indicates that the engine should be absolutely certain that an utterance is the recognized phrase. For example, suppose the engine is expecting “What is the time?” If the threshold is 100 and the user mumbles “What’z tha time” or has a cold, the command may not be recognized. However, if the threshold is too low and the user says a similar-sounding phrase that is not being listened for, such as “What is mine?,” the engine may recognize it as “What is the time?”

If the command spoken by the user is not close enough to what the speech-recognition engine expects, the voice command object notifies the application that the command was not recognized by calling IVCmdNotifySink::CommandOther with a NULL string.

The threshold for a site is saved between uses of the site, even if the user shuts down the computer in the meantime.


IVCmdAttributes::ThresholdSet

This method sets the threshold level for the speech-recognition engine used by a voice command site.

Syntax

HRESULT ThresholdSet( DWORD dwThreshold);

Parameters

dwThreshold
[in] Specifies the threshold level. An application can specify SRATTR_MINTHRESHOLD and SRATTR_MAXTHRESHOLD for minimum and maximum allowable values.

Return Values

NOERROR
The method successfully set the threshold level for the speech-recognition engine.
E_INVALIDARG
The argument is invalid.
VCMDERR_INVALIDMODE
No site exists, the site does not support this attribute, or the voice command object is already registered with a site.
VCMDERR_NOTSUPPORTED
The function is not supported by the engine.
VCMDERR_OUTOFMEM
There is no more memory.
VCMDERR_VALUEOUTOFRANGE
The value is out of range.

Remarks

The threshold level is a value from 0 to 100 that indicates the point below which an utterance is rejected as unrecognized. A threshold level of 0 indicates that the engine should match any utterance to the closest phrase match. A value of 100 indicates that the engine should be absolutely certain that an utterance is the recognized phrase. If the value is out of range for the engine, an error is returned and the attribute is not changed.

The threshold for a site is saved between uses of the site, even if the user shuts down the computer in the meantime.

If a voice navigation application is installed on the user’s computer, an application may not need to set the threshold.


IVCmdEnum

This interface is a standard OLE enumeration interface. Its methods are used by applications to enumerate the menus stored in the voice command database

Method
Description
IVCmdEnum::Clone | Retrieves another enumerator that contains the same enumeration state as the current one.
IVCmdEnum::Next | Retrieves the specified number of items in the enumeration sequence.
IVCmdEnum::Reset | Resets the enumeration sequence back to the beginning.
IVCmdEnum::Skip | Skips over a specified number of elements in the enumeration sequence.

Remarks

This interface is supported by all voice command objects.


IVCmdEnum::Clone

This method retrieves another enumerator that contains the same enumeration state as the current one.

Syntax

HRESULT Clone( IEnumXXX **ppenum);

Parameters

ppenum
[out] Pointer to a variable that receives the cloned enumerator. The type of this parameter is the same as the enumerator name. For example, if the enumerator name is IEnumFORMATETC, this parameter is of the IEnumFORMATETC type.

Return Values

NOERROR
The method successfully retrieved the enumerator.
E_INVALIDARG
The argument is invalid.
E_OUTOFMEMORY
The system is out of memory.
E_UNEXPECTED
An unexpected error occurred.

Remarks

Using Clone, it is possible to record a particular point in the enumeration sequence and then return to that point at a later time. The enumerator returned is of the same interface type as the one being cloned.


IVCmdEnum::Next

This method retrieves the specified number of items in the enumeration sequence.

Syntax

HRESULT IEnumX::Next( ULONG celt, Unknown **rgelt, ULONG *pceltFetched);

Parameters

celt
[in] Number of elements to retrieve. If the number of elements requested is more than remains in the sequence, only the remaining elements are retrieved.
rgelt
[out] Array that receives the elements. If an error value is returned, no entries in the array are valid.
pceltFetched
[out] Pointer to a variable that receives the number of array elements actually copied to the array. This parameter cannot be NULL if celt is greater than one. If this parameter is NULL, celt must be one.

Return Values

NOERROR
The method successfully retrieved the specified number of items in the enumeration sequence.
E_INVALIDARG
The argument is invalid.
E_OUTOFMEMORY
The system is out of memory.
E_UNEXPECTED
An unexpected error occurred.
S_FALSE
The method did not retrieve the specified number of items in the enumeration sequence.
S_OK
The method successfully retrieved the specified number of items in the enumeration sequence.


IVCmdEnum::Reset

This method resets the enumeration sequence back to the beginning.

Syntax

HRESULT IEnumX::Reset(void);

Return Values

NOERROR
The method successfully reset the enumeration sequence back to the beginning.
S_FALSE
The method did not reset the enumeration sequence back to the beginning.
S_OK
The method successfully reset the enumeration sequence back to the beginning.


IVCmdEnum::Skip

This method skips over a specified number of elements in the enumeration sequence.

Syntax

HRESULT IEnumX::Skip ( ULONG celt);

Parameters

celt
[in] Number of elements to be skipped.

Return Values

NOERROR
The method successfully skipped over the elements.
E_INVALIDARG
The argument is invalid.
E_OUTOFMEMORY
The system is out of memory.
E_UNEXPECTED
An unexpected error occurred.
S_FALSE
The method did not skip over the specified number of elements.
S_OK
The method successfully skipped over the elements.


IVCmdMenu

This interface allows an application to manage voice command menus. It includes methods for such tasks as activating and deactivating menus, and adding and deleting phrases.

Method
Description
IVCmdMenu::Activate | Activates a voice menu so that its commands can be recognized.
IVCmdMenu::Add | Adds one or more commands to a voice menu. The added commands are appended to any existing commands in the menu.
IVCmdMenu::Deactivate | Deactivates an active voice menu so that the application no longer listens for its commands.
IVCmdMenu::EnableItem | Permanently enables or disables a menu item. When a command is disabled by using EnableItem, it is not compiled into the menu.
IVCmdMenu::Get | Retrieves information about one or more commands in a voice menu.
IVCmdMenu::ListGet | Retrieves the phrases stored in the current list for the selected voice menu.
IVCmdMenu::ListSet | Sets the phrases in a list for a voice command.
IVCmdMenu::Num | Retrieves the total number of commands on a voice menu.
IVCmdMenu::Remove | Removes the specified commands from the voice menu.
IVCmdMenu::Set | Sets information for one or more commands in a voice menu.
IVCmdMenu::SetItem | Temporarily enables or disables a command on a voice menu.

Remarks

This interface is supported by all voice command objects.

The following flags are used with the methods of the IVCmdMenu interface to identify a command in a voice command menu:

VCMD_BY_IDENTIFIER
The dwCmdNum parameter is the identifier of the command.
VCMD_BY_POSITION
The dwCmdNum parameter is the position in the list of commands.


IVCmdMenu::Activate

This method activates a voice menu so that its commands can be recognized.

Syntax

HRESULT Activate( HWND hWndListening, DWORD dwFlags);

Parameters

hWndListening
[in] Handle to the window associated with the voice menu. Whenever this window is the foreground window, the voice menu is automatically activated. Otherwise, it is deactivated. If this parameter is NULL, the voice menu is global; that is, it remains active regardless of the foreground window, until the application explicitly deactivates it.

For the Auto PC, set this parameter to NULL. The application has to activate and deactivate the voice menu manually when the focus switches.

dwFlags
[in] Specifies how the menu should be active. It is one of the following values:
0 or NULL
The voice menu is active only when speech recognition is awake.
VWGFLAG_ASLEEP
The menu is active only when speech recognition is asleep and is automatically deactivated when speech recognition is awake.
VWGFLAG_BALLOON
This is a balloon grammar.

Most applications set this parameter to zero. Typically, a sleep menu contains a command to resume speech recognition, such as “Wake up.”

Return Values

NOERROR
Although this value indicates success, the voice command menu is not necessarily active. The menu is active only when speech recognition is enabled and put in the correct asleep or awake mode.
E_INVALIDARG
The argument is invalid.
VCMDERR_CANTCREATEDATASTRUCTURES
The internal data structures needed to build a grammar cannot be created.
VCMDERR_CANTINITDATASTRUCTURES
The internal data structures needed to build a grammar cannot be initialized.
VCMDERR_CANTXTRACTWORDS
The unique words needed by the engine grammar object cannot be extracted.
VCMDERR_INVALIDWINDOW
The window is invalid.
VCMDERR_MENUACTIVE
The menu is currently active and cannot be deleted.
VCMDERR_MENUTOOCOMPLEX
The menu is too complex to use.
VCMDERR_MENUWRONGLANGUAGE
The language is not supported by the speech recognition engine.
VCMDERR_NOCACHEDATA
There is no internal cache entry for this menu.
VCMDERR_NOCOMMANDS
The menu is active, but the menu does not yet contain any commands.
VCMDERR_NOENGINE
No speech recognition engine is active.
VCMDERR_NOGRAMMARINTERFACE
No engine grammar object is available.
VCMDERR_OUTOFMEM
There is no more memory.
VCMDERR_TOOMANYMENUS
There are too many active menus.

Remarks

If you set the VWGFLAG_BALLOON bit in dwFlags, this method activates the menu normally. The menu is automatically deactivated, however, after the speech recognition engine recognizes a word or after speech recognition enters sleep. The application does not need to deactivate the menu or check for notifications from IVCmdNotifySink::CommandOther once the automatic deactivation has occurred.

Only one balloon menu may be active at any time.

See Also

IVCmdNotifySink::CommandOther


IVCmdMenu::Add

This method adds one or more commands to a voice menu. The added commands are appended to any existing commands in the menu.

Syntax

HRESULT Add( DWORD dwCmdNum, SDATA dData, DWORD *pdwCmdStart);

Parameters

dwCmdNum
[in] Specifies the number of commands to add to the menu.
dData
[in] Specifies the SDATA structure that contains a list of VCMDCOMMAND structures that describe the voice commands to be added. Although they vary in size depending on the command data, the structures are contiguous within the list.
pdwCmdStart
[out] Pointer to a DWORD that receives the number of the first command added to the menu.

Return Values

NOERROR
The method successfully added the commands to the voice menu.
E_INVALIDARG
The argument is invalid.
VCMDERR_INVALIDCHAR
There is an invalid character in the voice menu.
VCMDERR_MENUTOOCOMPLEX
The menu is too complex to use.
VCMDERR_OUTOFMEM
There is no more memory.
VCMDERR_VALUEOUTOFRANGE
The value is out of range.

Remarks

For Auto PC, applications should use the IAPCSpeech::AddVMenuCommand method instead, but IVCmdMenu::Add is still available to Auto PC applications.

Commands are numbered sequentially from 1 to n. New commands are added to the end of the menu, so the first command added is numbered n+1.

For best results, deactivate the voice menu before calling Add. Otherwise, the menu must be deactivated, recompiled, and reactivated before Add returns. If the menu is already deactivated when Add is called, the menu is not recompiled until the application activates it again.

If a command string includes a list name, you can use IVCmdMenu::ListSet to set the phrases that the user can substitute for the list name when speaking the command.


IVCmdMenu::Deactivate

This method deactivates an active voice menu so that the application no longer listens for its commands.

Syntax

HRESULT Deactivate(void);

Return Values

NOERROR indicates success. VCMDERR_OUTOFMEM indicates that a low memory condition exists.

Remarks

After calling Deactivate, the menu remains open until it is released, so the application can start listening for the menu’s commands again by calling IVCmdMenu::Activate.


IVCmdMenu::EnableItem

This method permanently enables or disables a menu item. When a command is disabled by using EnableItem, it is not compiled into the menu.

Syntax

HRESULT EnableItem( DWORD dwEnable, DWORD dwCmdNum, DWORD dwFlag);

Parameters

dwEnable
[in] Specifies whether the command is enabled. Set to TRUE to enable the command, or to FALSE to disable it.
dwCmdNum
[in] Specifies the position or identifier of the command on the menu, depending on the value of dwFlag. Command positions are sequential, starting with 1 for the first command on the menu. The command identifier is specified in the dwID member of the VCMDCOMMAND structure that defines the command.
dwFlag
[in] Specifies the nature of dwCmdNum. It is one of the following flags:
VCMD_BY_IDENTIFIER
The dwCmdNum parameter is the identifier of the command.
VCMD_BY_POSITION
The dwCmdNum parameter is the position in the list of commands.

Return Values

NOERROR
The method successfully and permanently enabled or disabled the menu item.
E_INVALIDARG
The argument is invalid.
VCMDERR_OUTOFMEM
There is no more memory.

Remarks

For best results, deactivate the voice menu before calling EnableItem. Otherwise, the menu must be deactivated, recompiled, and reactivated before the method returns. If the menu is already deactivated when EnableItem is called, the menu is not recompiled until the application activates it again.


IVCmdMenu::Get

This method retrieves information about one or more commands in a voice menu.

Syntax

HRESULT Get( DWORD dwCmdStart, DWORD dwCmdNum, DWORD dwFlag, PSDATA pdData, DWORD *pdwCmdNum);

Parameters

dwCmdStart
[in] Specifies the number of the first command to retrieve. Commands are numbered sequentially from 1 to n. If dwFlag is the VCMD_BY_IDENTIFIER value, this parameter is ignored.
dwCmdNum
[in] Specifies either the number of commands to retrieve or the identifier of the commands, depending on the value of dwFlag. If the sum of dwCmdStart and dwCmdNum exceeds the total number of commands in the menu, the method returns as many commands as possible.
dwFlag
[in] Specifies the nature of dwCmdNum. It is one of the following flags:
VCMD_BY_IDENTIFIER
The dwCmdNum parameter is the identifier of the command.
VCMD_BY_POSITION
The dwCmdNum parameter is the position in the list of commands.
pdData
[out] Pointer to an SDATA structure that receives the address and size of a buffer. The buffer contains a list of VCMDCOMMAND structures that describe the commands retrieved. Although they vary in size depending on the command data, the structures are contiguous within the list.
pdwCmdNum
[out] Pointer to a DWORD that receives the number of commands actually copied to the buffer.

Return Values

NOERROR
The method successfully retrieved information about the commands.
E_INVALIDARG
The argument is invalid.
VCMDERR_INVALIDCHAR
There is an invalid character in the voice menu.
VCMDERR_MENUTOOCOMPLEX
The menu is too complex to use.
VCMDERR_OUTOFDISK
No disk space is left to write information.
VCMDERR_OUTOFMEM
There is no more memory.
VCMDERR_VALUEOUTOFRANGE
The value is out of range.

Remarks

The calling application allocates the SDATA structure and passes its address to Get. Using the OLE task allocator, Get allocates memory for the returned data and sets the pData member of SDATA to point to the memory. If the allocation fails, pData is set to NULL and the dwSize member is set to zero. The calling application must free the memory pointed to by pData, as well as the SDATA structure itself, by calling the CoTaskMemFree function.


IVCmdMenu::ListGet

This method retrieves the phrases stored in the current list for the selected voice menu.

Syntax

HRESULT ListGet( PTSTR pszList, PSDATA pdList, DWORD *pdwListNum);

Parameters

pszList
[in] Pointer to the null-terminated string that contains the name of the list, such as “name” or “weekday.” The list name must appear in the command string for at least one command on the menu. The command string is stored in the dwCommand member of the VCMDCOMMAND structure that defines the command.
pdList
[out] Pointer to an SDATA structure that receives the address and size of a buffer. The buffer contains a sequential list of null-terminated strings, one for each phrase in the list.
pdwListNum
[out] Pointer to a DWORD that receives the number of phrases that were copied to the buffer. If the list is empty, this parameter receives zero.

Return Values

NOERROR
The method successfully retrieved the phrases stored in the current list.
E_INVALIDARG
The argument is invalid.
VCMDERR_INVALIDLIST
An invalid list was passed.
VCMDERR_OUTOFMEM
There is no more memory.

Remarks

A list is associated with a menu rather than an individual command. The list must appear in at least one command string, but can be used by more than one command on the menu.

The calling application allocates the SDATA structure and passes its address to ListGet. Using the OLE task allocator, ListGet allocates memory for the returned data and sets the pData member of the SDATA structure to point to the memory. If the allocation fails, the pData member is set to NULL and the dwSize member is set to zero. The calling application must free the memory pointed to by pData, as well as the SDATA structure itself, by calling the CoTaskMemFree function.


IVCmdMenu::ListSet

This method sets the phrases in a list for a voice command.

Syntax

HRESULT ListSet( PTSTR pszList, DWORD dwListNum, SDATA dList);

Parameters

pszList
[in] Pointer to the null-terminated string contains the name of the list to set, such as “name” or “weekday.” The list name must appear in the command string for at least one command on the menu. The command string is specified in the dwCommand member of the VCMDCOMMAND structure that defines the command.
dwListNum
[in] Specifies the number of phrases in the list.
dList
[in] SDATA structure that contains a pointer to a data buffer and the size of the buffer. The data buffer contains a sequential list of null-terminated strings, one for each phrase in the list.

Return Values

NOERROR
The method successfully set the phrases in the list.
E_INVALIDARG
The argument is invalid.
VCMDERR_INVALIDCHAR
There is an invalid character in the voice menu.
VCMDERR_INVALIDLIST
An invalid list was passed.
VCMDERR_OUTOFMEM
There is no more memory.

Remarks

The user can speak any phrase in the list in place of the list name in the command string. A command that uses a list must have the list name in brackets—for example, “Send mail to <name>.”

Calling ListSet establishes a list of phrases that can be spoken in a voice command, such as “Send mail to name.” Typically, the list contains information that changes dynamically at run time, such as the ten people to whom the user most recently sent electronic mail. For best results, a list should have fewer than 20 entries. Having more than 20 entries in a list can reduce the accuracy of recognition.

The list persists until the voice menu object is released. List entries are not automatically saved to disk. To preserve the list, call the IVCmdMenu::ListGet method and take steps to store the result.

ListSet is much faster than the IVCmdMenu interface’s Add, Remove, or Set methods because list entries are substituted when a command is recognized and the menu is not recompiled. This means that ListSet can be called on an active menu without affecting performance.


IVCmdMenu::Num

This method retrieves the total number of commands on a voice menu.

Syntax

HRESULT Num( DWORD *pdwNumCmd);

Parameters

pdwNumCmd
[out] Pointer to a DWORD that receives the number of commands.

Return Values

NOERROR
The method successfully retrieved the total number of commands.
E_INVALIDARG
The argument is invalid.
VCMDERR_INVALIDCHAR
There is an invalid character in the voice menu.
VCMDERR_MENUTOOCOMPLEX
The menu is too complex to use.
VCMDERR_OUTOFMEM
There is no more memory.
VCMDERR_VALUEOUTOFRANGE
The value is out of range.


IVCmdMenu::Remove

This method removes the specified commands from the voice menu.

Syntax

HRESULT Remove( DWORD dwCmdStart, DWORD dwCmdNum, DWORD dwFlag);

Parameters

dwCmdStart
[in] Specifies the number of the first command in the menu to remove. Command positions are sequential, starting with 1 for the first command on the menu. If dwFlag is the VCMD_BY_IDENTIFIER value, dwCmdStart is ignored.
dwCmdNum
[in] Number of commands to remove or the identifier of the commands, depending on the value of dwFlag. If the sum of dwCmdStart and dwCmdNum exceeds the total number of commands in the menu, the method removes as many commands as possible.
dwFlag
[in] Specifies the nature of dwCmdNum. It is one of the following values:
VCMD_BY_IDENTIFIER
The dwCmdNum parameter is the identifier of the command.
VCMD_BY_POSITION
The dwCmdNum parameter is the position in the list of commands.

Return Values

NOERROR
The method successfully removed the specified commands.
E_INVALIDARG
The argument is invalid.
VCMDERR_INVALIDCHAR
There is an invalid character in the voice menu.
VCMDERR_MENUTOOCOMPLEX
The menu is too complex to use.
VCMDERR_OUTOFDISK
No disk space is left to write information.
VCMDERR_OUTOFMEM
There is no more memory.
VCMDERR_VALUEOUTOFRANGE
The value is out of range.

Remarks

For best results, deactivate the voice menu before calling Remove. Otherwise, the menu must be deactivated, recompiled, and reactivated before Remove returns. If the menu is already deactivated when Remove is called, the menu is not recompiled until the application activates it again.


IVCmdMenu::Set

This method sets information for one or more commands in a voice menu.

Syntax

HRESULT Set( DWORD dwCmdStart, DWORD dwCmdNum, DWORD dwFlag, SDATA dData);

Parameters

dwCmdStart
[in] Specifies the number of the first command to set in the voice menu. Command positions are sequential, starting with 1 for the first command on the menu. If dwFlag is the VCMD_BY_IDENTIFIER value, dwCmdStart is ignored.
dwCmdNum
[in] Specifies either the number of commands to set or the identifier of the commands, depending on the value of dwFlag. If the sum of dwCmdStart and dwCmdNum exceeds the number of commands in the menu, the method sets as many commands as possible.
dwFlag
[in] Specifies the nature of dwCmdNum. It is one of the following flags:
VCMD_BY_IDENTIFIER
The dwCmdNum parameter is the identifier of the command.
VCMD_BY_POSITION
The dwCmdNum parameter is the position in the list of commands.
dData
[in] SDATA structure that contains a pointer to a data buffer and the size of the buffer. The data buffer contains a list of VCMDCOMMAND structures that describe the voice commands to set. Although they vary in size depending on the command data, the structures are contiguous within the list.

Return Values

NOERROR
The method successfully set information for one or more commands in the voice menu.
E_INVALIDARG
The argument is invalid.
VCMDERR_INVALIDCHAR
There is an invalid character in the voice menu.
VCMDERR_MENUTOOCOMPLEX
The menu is too complex to use.
VCMDERR_OUTOFDISK
No disk space is left to write information.
VCMDERR_OUTOFMEM
There is no more memory.
VCMDERR_VALUEOUTOFRANGE
The value is out of range.

Remarks

For best results, deactivate the voice menu before calling Set. Calling Set on an active menu can be fairly slow because the menu must be deactivated, recompiled, and reactivated before Set returns. If the menu is already deactivated when Set is called, the menu is not recompiled until the application activates it again.


IVCmdMenu::SetItem

This method temporarily enables or disables a command on a voice menu.

Syntax

HRESULT SetItem( DWORD dwEnable, DWORD dwCmdNum, DWORD dwFlag);

Parameters

dwEnable
[in] Set to TRUE to enable the command, or to FALSE to disable it.
dwCmdNum
[in] Specifies the position or identifier of the command on the menu, depending on the value of dwFlag. Command positions are sequential, starting with 1 for the first command on the menu.
dwFlag
[in] Specifies the nature of dwCmdNum. It is one of the following flags:
VCMD_BY_IDENTIFIER
The dwCmdNum parameter is the identifier of the command.
VCMD_BY_POSITION
The dwCmdNum parameter is the position in the list of commands.

Return Values

NOERROR
The method successfully enabled or disabled a command on a voice menu temporarily.
E_INVALIDARG
The argument is invalid.
VCMDERR_OUTOFMEM
There is no more memory.

Remarks

If a command is disabled by using SetItem, the voice command object sends a CommandOther notification rather than a CommandRecognize notification when it recognizes the disabled command.

SetItem is much faster than the IVCmdMenu::EnableItem method because the menu is not recompiled. This means that SetItem can be called on an active menu without affecting performance.


IVCmdNotifySink

This interface must be implemented by an application in order to receive notifications from the voice command object. In addition to the recognized command, an application can also be notified of events such as beginning and ending of an utterance, menu activation, and the presence of interference.

Method
Description
IVCmdNotifySink::AttribChanged | Notifies applications on a voice command site that a site attribute has changed.
IVCmdNotifySink::CommandOther | Sent by the engine when a spoken phrase was either recognized as being from another application’s command set or was not recognized.
IVCmdNotifySink::CommandRecognize | Sent by the engine when a spoken phrase is recognized as being from the application’s command set.
IVCmdNotifySink::CommandStart | Sent by the engine when a spoken phrase is detected.
IVCmdNotifySink::Interference | Notifies the application that the engine cannot recognize speech properly for a known reason.


IVCmdNotifySink::AttribChanged

This method notifies applications on a voice command site that a site attribute has changed.

Syntax

HRESULT AttribChanged( DWORD dwAttribute);

Parameters

dwAttribute
[in] Specifies the site attribute that was changed. It is one of the following flags:
IVCNSAC_AWAKE
Specifies the awake state.
IVCNSAC_AUTOGAINENABLE
Specifies the automatic gain.
IVCNSAC_DEVICE
Specifies a wave-in audio device.
IVCNSAC_ENABLED
Specifies the enabled state.
IVCNSAC_MICROPHONE
Current microphone.
IVCNSAC_ORIGINAPP
The application receiving this notification originated the attribute change.
IVCNSAC_SPEAKER
Specifies the name of the current speaker.
IVCNSAC_SRMODE
Specifies speech-recognition mode.
IVCNSAC_THRESHOLD
Specifies the confidence threshold.

Return Values

The return value is ignored.

Remarks

The notification is sent only to applications that, when registered to use voice commands on the site, did one of the following:

  • Set the dwFlags parameter of the IVoiceCmd::Register method to the VCMDRF_ALLBUTVUMETER value.
  • Set the VCMDRF_ATTRIBCHANGE bit.

The dwAttribute parameter includes the IVCNSAC_ORIGINAPP value only if the application sets an attribute by calling the IVCmdAttributes interface’s EnabledSet, AwakeStateSet, DeviceSet, or SRModeSet method.


IVCmdNotifySink::CommandOther

This method notifies the application that the engine did not recognize a spoken phrase, or recognized it as being from another application’s command set.

Syntax

HRESULT CommandOther( PVCMDNAME pName, PTSTR pszCommand);

Parameters

pName
[in] Pointer to a VCMDNAME structure that contains the name of the voice menu that has the recognized command. If this parameter contains NULL, the command was not recognized.
pszCommand
[in] Pointer to the null-terminated string for the command. If this parameter contains NULL, the command was not recognized.

Return Values

The return value is ignored.

Remarks

Along with the notification method, the application receives the address of the phrase.

An application can use this notification to monitor utterances and inform the user what was heard. An application should not rely on this notification for information about the recognition of its own commands. Most applications ignore this notification.

The command string contains the words actually spoken by the user. If the command contains a list name, the command string may not match the words of the command. For example, the string pointed to by pszCommand might be “Send mail to Fred,” whereas the command string is “Send mail to name.”

The notification is sent only to applications that, when registered to use voice commands on the site, did one of the following:

  • Set the dwFlags parameter of the IVoiceCmd::Register method to the VCMDRF_ALLBUTVUMETER value.
  • Set the VCMDRF_CMDOTHER bit.

If two or more voice menus contain the same phrase and this phrase is recognized, it is indeterminate which of the menus causes the engine to call the IVCmdNotifySink::CommandRecognize notification and which causes it to call CommandOther. This happens only if the menus are all global or all window-specific.


IVCmdNotifySink::CommandRecognize

This method is sent by the engine when a spoken phrase is recognized as being from the application’s command set.

Syntax

HRESULT CommandRecognize( DWORD dwID, PVCMDNAME pvCmdName, DWORD dwFlags, DWORD dwActionSize, PVOID pAction, DWORD dwNumLists, PTSTR pszListValues, PTSTR pszCommand);

Parameters

dwID
[in] Specifies the identifier of the command that was recognized. The command identifier is stored in the dwID member of the VCMDCOMMAND structure that defines the command.
pvCmdName
[in] Void pointer to a VCMDNAME structure that contains the voice menu that has the recognized command.
dwFlags
[in] Specifies a bitmask of flags. Set to VCMDCMD_VERIFY if the application should request verification from the user, or to NULL if verification is not required. To request verification, the application should display a dialog box. An application would typically require verification for a destructive or irreversible command such as “Format disk.”
dwActionSize
[in] Specifies the size of the data in pAction.
pAction
[in] Pointer to a string that contains action data to accompany the recognized command. The action data is obtained from the VCMDCOMMAND structure for the command.
dwNumLists
[in] Specifies, in bytes, the size of the list data for the command. If a command does not contain any list fields, this parameter is zero.
pszListValues
[in] Pointer to a list of one or more null-terminated strings that correspond to the phrase from each list in the order that they occur in the command. For example, if the command is “Set the time to number AM or PM,” this parameter points to “Ten\0PM.” The last “\0” is implicit in C notation.
pszCommand
[in] Pointer to the null-terminated string for the command that was recognized.

Return Values

The return value is ignored.

Remarks

Along with the notification, the application receives the text of the phrase and the action data that was supplied by the application when it originally defined the command.

Do not use the contents of pszCommand to identify the recognized command. Instead, use the data in pAction or the identifier in dwID to determine which command was recognized.

The notification is sent to all applications that are registered on the voice command site, regardless of the what the dwFlags parameter of the IVoiceCmd::Register method was set to when the application registered to use voice commands.

If two or more global voice menus, or two or more window-specific voice menus, contain the same phrase and the engine recognizes that phrase, the engine calls CommandRecognize for one menu and IVCmdNotifySink::CommandOther for the other. The engine determines which notification to call for each menu; an application cannot determine which notification is called.


IVCmdNotifySink::CommandStart

This method is sent by the engine when a spoken phrase is detected.

Syntax

HRESULT CommandStart();

Return Values

The return value is ignored.

Remarks

The notification is sent only to applications that, when registered to use voice commands on the site, did one of the following:

  • Set the dwFlags parameter of the IVoiceCmd::Register method to the VCMDRF_ALLBUTVUMETER value.
  • Set the VCMDRF_CMDSTART bit.


IVCmdNotifySink::Interference

This method notifies the application that the engine cannot recognize speech properly for a known reason.

Syntax

HRESULT Interference( DWORD dwType);

Parameters

dwType
[in] Specifies the type of interference. It is one of the following flags:
SRMSGINT_AUDIODATA_STARTED
The engine has resumed receiving audio data from the audio source.
SRMSGINT_AUDIODATA_STOPPED
The engine has stopped receiving audio data from the audio source.
SRMSGINT_NOISE
The background noise is too high.
SRMSGINT_NOSIGNAL
The engine cannot detect a signal, possibly because the microphone is off or unplugged.
SRMSGINT_TOOLOUD
The speaker is too loud; recognition results may be degraded.
SRMSGINT_TOOQUIET
The speaker is too quiet; recognition results may be degraded.

Return Values

The return value is ignored.

Remarks

The notification is sent only to applications that set the dwFlags parameter of the IVoiceCmd::Register method to the VCMDRF_ALLBUTVUMETER value when the application registered to use voice commands on the site.


IVCmdUserWord

This interface allows an application to enable the speaker-dependent and speaker-independent templates, and to add new words to the speaker-dependent template.

Method
Description
IVCmdUserWord::AddSIFile | Installs speaker-independent template extension files.
IVCmdUserWord::GetPhraseList | Gets the words in the installed vocabulary.
IVCmdUserWord::ModifyTraining | Specifies which templates are enabled for a particular phrase.
IVCmdUserWord::QueryPhrase | Determines what kind of templates a phrase has and whether or not they are enabled.
IVCmdUserWord::RemoveSIFile | Uninstalls speaker-independent template extension files.
IVCmdUserWord::Train | Called by the application to train a list of user-defined phrases.

Remarks

This interface is an extension of the Speech API (SAPI), added to meet the needs of the Auto PC. It is designed specifically for an isolated-word recognizer. Any method call on this interface affects the current speaker only.

Templates hold information that the engine uses to recognize a phrase. There are two types of templates for the Auto PC: speaker independent and speaker dependent. There is one speaker-independent template for each phrase. Speaker independent recognition can only be enabled or disabled. It cannot be modified by the user. Each speaker can have one speaker-dependent template for each phrase. To create a speaker-dependent template, a user must train the object to recognize their particular speech pattern.

The two templates operate independently of each other. An application can enable a speaker-dependent template whether or not the speaker-independent template is available. Enabling both templates may achieve better recognition accuracy.


IVCmdUserWord::AddSIFile

This method installs speaker-independent template extension files.

Syntax

HRESULT AddSIFile( LPCWSTR lpszFileName, DWORD *pdwID, DWORD dwFlag );

Parameters

lpszFile
Long pointer to the null-terminated string that contains the path of the file to install.
pdwID
Pointer to a DWORD that contains an identification number of the independent template to install.
dwFlag
Reserved, must be 0.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

This method is usually called in the Auto PC setup program.

See Also

IVCmdUserWord::RemoveSIFile


IVCmdUserWord::GetPhraseList

This method gets the words in the installed vocabulary.

Syntax

HRESULT GetPhraseList( DWORD dwFlags, PWSTR pszBuf PDWORD *pdwSize);

Parameters

dwFlags
Specifies a bitmask of flags. It is one or a combination of the following flags:
SRPHRASE_SI
Returns the speaker-independent list.
SRPHRASE_SD
Returns the speaker-dependent list.

If both flags are set, the combined list is returned.

pszBuf
Pointer to the buffer where the phrase list is stored. The buffer contains a list of null-terminated strings. The list is terminated by two consecutive null characters.
pdwSize
Pointer to the size of the buffer allocated to hold the list, in bytes. If the method returns successfully, it holds the actual number of bytes in the buffer.

Return Values

NOERROR indicates success.

VCMDERR_VALUEOUTOFRANGE indicates that the buffer is too small. When this occurs, GetPhraseList sets pdwSize to the buffer size needed.

If dwFlags is set to SRPHRASE_SI and the speech engine supports any word—for example, if the engine is a phomeme-based continuous engine—the function returns S_FALSE.

If an error occurs, the appropriate HRESULT value is returned.

Remarks

If both SRPHRASE_SI and SRPHRASE_SD are set, and if a word has both speaker-independent and speaker-dependent templates, the same word appears twice in the buffer.


IVCmdUserWord::ModifyTraining

This method specifies which templates are enabled for a particular phrase.

Syntax

HRESULT ModifyTraining( LPTSTR lpszPhrase, DWORD dwFlags);

Parameters

lpszPhrase
Long pointer to the null-terminated string that contains the phrase of interest.
dwFlags
Specifies a bitmask of flags. It is one of the following values:
SRPHRASE_SI
Specifies the speaker independent template.
SRPHRASE_SD
Specifies the speaker dependent template.
SRPHRASE_SI_ENABLE
Enables or disables a phrase on the speaker-independent template.
SRPHRASE_SD_ENABLE
Enables or disables a phrase on the speaker-dependent template.
SRPHRASE_SD_ERASE
Erases the speaker-dependent template for a phrase.
SRPHRASE_PERMANENT
When set, makes any changes permanent.

Return Values

NOERROR
The method successfully specified the templates that are enabled for a particular phrase.
SRERR_PHRASENOTFOUND
The phrase was not found in either template.
SRERR_TEMPLATENOTFOUND
The template is not available.

Remarks

Templates are enabled independently of each other. Either or both may be enabled at any time. When setting a flag to enable or disable a template, the corresponding flag to select the template must also be set. For example, to enable the speaker-dependent template, use SRPHRASE_SD | SRPHRASE_SD_ENABLE.


IVCmdUserWord::QueryPhrase

This method determines what kind of templates a phrase has and whether or not they are enabled.

Syntax

HRESULT QueryPhrase( LPTSTR lpszPhrase, DWORD *pdwValue);

Parameters

lpszPhrase
Long pointer to the null-terminated string that contains the phrase of interest.
pdwValue
Pointer to the bitmask of flags that indicate the training templates associated with the phrase. It is one of the following values:
SRPHRASE_SI
Specifies the speaker independent template.
SRPHRASE_SD
Specifies the speaker dependent template.
SRPHRASE_SI_ENABLE
The speaker-independent template is enabled/disabled.
SRPHRASE_SD_ENABLE
The speaker-dependent template is enabled/disabled.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IVCmdUserWord::RemoveSIFile

This method removes speaker-independent template extension files.

Syntax

HRESULT RemoveSIFile( DWORD dwID, DWORD dwFlag );

Parameters

dwID
Specifies a DWORD that contains an identification number of the independent template to remove.
dwFlag
Reserved, must be 0.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

SeeAlso

IVCmdUserWord::AddSIFile


IVCmdUserWord::Train

This method is called by the application to train a list of user-defined phrases.

Syntax

HRESULT Train( PCWSTR lpPhrases, DWORD dwSize, PCWSTR lpCaption, DWORD dwSizeCap, DWORD hHandle, DWORD dwFlags);

Parameters

lpPhrases
Long pointer to a null-terminated text string consisting of the phrase to be trained.
dwSize
Specifies a DWORD that contains the number of bytes in the string pointed to by lpPhrases.
lpCaption
Long pointer to the string that contains the title caption of the training form.
dwSizeCap
Specifies a DWORD that contains the number of bytes in the caption string pointed to by lpCaption.
hHandle
Reserved, must be 0.
dwFlags
Reserved, must be 0.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IVoiceCmd

This interface registers an application with a voice command object. It is also used for tasks such as creating menus and menu enumerators.

Method
Description
IVoiceCmd::CmdMimic | Supplies a voice-aware application with the equivalent of a spoken voice command.
IVoiceCmd::MenuCreate | Creates a voice menu object to represent a new or existing voice menu for an application.
IVoiceCmd::MenuDelete | Deletes a menu from the voice menu database.
IVoiceCmd::MenuEnum | Creates a voice menu enumerator to enumerate menus in the voice menu database.
IVoiceCmd::Register | Is called by an application to register to use voice commands on a site.

Remarks

This interface is supported by all voice command objects.


IVoiceCmd::CmdMimic

This method supplies a voice-aware application with the equivalent of a spoken voice command.

Syntax

HRESULT CmdMimic( PVCMDNAME pMenu, PTSTR pszCommand);

Parameters

pMenu
[in] Pointer to a VCMDNAME structure identifying the menu that contains the command to mimic.
pszCommand
[in] Pointer to the null-terminated string that contains the command to mimic.

Return Values

NOERROR
The method successfully supplied a voice-aware application with the equivalent of a spoken voice command.
E_INVALIDARG
The argument is invalid.
VCMDERR_CANNOTMIMIC
No command was found to match the input string.
VCMDERR_INVALIDMODE
No site exists, the site does not support this attribute, or the voice command object is already registered with a site.
VCMDERR_MENUDOESNOTEXIST
The requested menu does not exist in the database.
VCMDERR_OUTOFMEM
There is no more memory.
VCMDERR_VALUEOUTOFRANGE
The value is out of range.

Remarks

CmdMimic parses the command string and eliminates white space and punctuation, then compares the result with each command on the voice menu until it finds a match. The comparison is case-insensitive, and the command string can include phrases from lists. If the string matches a command in the voice menu, it is recognized; otherwise, the method returns an error.

The VCMDERR_MENUDOESNOTEXIST error is returned if the menu does not exist or is not active.

An application can call CmdMimic to play back voice macros to another application, similar to playing back keystrokes and mouse messages in Windows.

The voice menu must be active before an application can mimic its commands.


IVoiceCmd::MenuCreate

This method creates a voice menu object to represent a new or existing voice menu for an application.

Syntax

HRESULT MenuCreate( PVCMDNAME pName, PLANGUAGE pLanguage, DWORD dwFlags, PIVCMDMENU *ppIVCmdMenu);

Parameters

pName
[in] Pointer to a VCMDNAME structure that identifies the menu to create. The VCMDNAME structure contains an application name, such as “Radio,” and a state name, such as “main form.”
pLanguage
[in] Pointer to a LANGUAGE structure that indicates the language to use for the menu. If this parameter is NULL, the default language for the site’s speech-recognition mode is used.
dwFlags
[in] Specifies how to create the menu. It is one of the following flags:
VCMDMC_CREATE_ALWAYS
Creates an empty menu with the specified name. If a menu by that name already exists in the voice menu database, it is erased. For Microsoft Windows CE for the Auto PC, the voice menu is removed from the database when the menu is released.
VCMDMC_CREATE_NEW
Creates an empty menu with the specified name. If a menu by that name already exists in the voice menu database, the method returns an error. The new menu is stored in the database when the menu object is released.
VCMDMC_CREATE_TEMP
Creates an empty menu with the specified name. If a menu by that name already exists in the voice menu database, the method returns an error. The new menu is temporary and is discarded when the menu object is released.
VCMDMC_OPEN_ALWAYS
Opens an existing menu with the specified name. If the menu does not exist, the method creates a new, empty menu. The new menu is stored in the database when the menu object is released.
ppIVCmdMenu
[out] Pointer to an IVCmdMenu interface for the newly created voice menu object. The application uses the pointer to this interface to call IVCmdMenu methods on the voice menu object. If an error occurs, this parameter receives NULL.

Return Values

NOERROR
The method successfully created a voice menu object.
E_INVALIDARG
The argument is invalid.
VCMDERR_CANTCREATESTORAGE
Space cannot be created in the database for the menu.
VCMDERR_MENUDOESNOTEXIST
The requested menu does not exist in the database.
VCMDERR_MENUEXIST
The requested new or temporary menu already exists in the database.
VCMDERR_OUTOFDISK
No disk space is left to write information.
VCMDERR_OUTOFMEM
There is no more memory.
VCMDERR_VALUEOUTOFRANGE
The value is out of range.

Remarks

An application can create a voice menu object by loading an existing voice menu from the voice menu database or creating a new voice menu. A voice menu does not need to be stored in the database; an application can create a temporary voice menu by setting dwFlags to the VCMDMC_CREATE_TEMP value. A temporary voice menu persists until the menu object is released.

An application can create more than one voice menu object to represent the same menu—either one of its own menus or a menu for another application. For example, one application might do this to enumerate another application’s menus.

More than one application can use the same voice menu object. For example, Application A might call the IVoiceCmd::CmdMimic method on a voice menu object that represents a menu for Application B, while Application B uses the same menu object to recognize commands spoken by the user.

For the Auto PC, developers should use IApcSpeech::CreateVMenu to create a voice menu instead.


IVoiceCmd::MenuDelete

This method deletes a menu from the voice menu database.

Syntax

HRESULT MenuDelete( PVCMDNAME pName);

Parameters

pName
[in] Pointer to a VCMDNAME structure that identifies the menu to delete.

Return Values

NOERROR
The method successfully deleted the menu.
E_INVALIDARG
The argument is invalid.
VCMDERR_MENUACTIVE
The menu is currently active and cannot be deleted.
VCMDERR_MENUDOESNOTEXIST
The requested menu does not exist in the database.
VCMDERR_MENUOPEN
The menu exists but has not been released, so it cannot be deleted.
VCMDERR_OUTOFMEM
There is no more memory.

Remarks

A menu cannot be deleted if it is currently open and the application is actively listening for its commands.

This method deletes the storage in the database for the menu, if the menu exists, and releases the voice menu object that was created by the IVoiceCmd::MenuCreate method. After a menu is deleted, the pointer to its IVCmdMenu interface is invalid, so set it to NULL.


IVoiceCmd::MenuEnum

This method creates a voice menu enumerator to enumerate menus in the voice menu database.

Syntax

HRESULT MenuEnum( DWORD dwFlags, PTSTR pszApplicationFilter, PTSTR pszStateFilter, PIVCMDENUM *ppiVCmdEnum);

Parameters

dwFlags
[in] Specifies whether to enumerate active menus or open menus, which have voice menu objects, but may or may not be active. It is a combination of some of the following flags:
VCMDEF_ACTIVE
Enumerates only active menus.
VCMDEF_DATABASE
Enumerates all menus in the voice menu database.
VCMDEF_PERMANENT
Enumerates only permanent menus.
VCMDEF_SELECTED
Enumerates open menus, whether or not they are also active.
VCMDEF_TEMPORARY
Enumerates only temporary menus.

VCMDEF_ACTIVE and VCMDEF_SELECTED are mutually exclusive, as are VCMDEF_TEMPORARY and VCMDEF_PERMANENT. If both VCMDEF_ACTIVE and VCMDEF_SELECTED are specified, the method returns an error. VCMDEF_TEMPORARY and VCMDEF_PERMANENT are ignored if neither VCMDEF_ACTIVE nor VCMDEF_SELECTED are specified. In other words, these flags do not apply if you want to enumerate the menus in the database.

By definition, if a menu is active, it is selected.

pszApplicationFilter
[in] Pointer to the null-terminated string that contains the name of the application whose menus are enumerated. This name is the same as that in the szApplication member of the VCMDNAME structure passed to the IVoiceCmd::MenuCreate method. If this parameter is NULL, menus for all applications, except those eliminated by dwFlags and pszStateFilter, are enumerated.
pszStateFilter
[in] Pointer to a null-terminated string that contains the name of the state whose menus are enumerated. This state is the same as that in the szState member of the VCMDNAME structure passed to MenuCreate. If this parameter is NULL, menus for all applications, except those eliminated by dwFlags and pszApplicationFilter, are enumerated.
ppiVCmdEnum
[out] Pointer to a variable that receives a pointer to an IVCmdEnum interface for the newly created voice menu enumerator. If an error occurs, this parameter receives NULL.

Return Values

NOERROR
The method successfully created a voice menu enumerator.
E_INVALIDARG
The argument is invalid.
VCMDERR_INVALIDMODE
No site exists, the site does not support this attribute, or the voice command object is already registered with a site.
VCMDERR_MENUDOESNOTEXIST
The requested menu does not exist in the database.
VCMDERR_OUTOFMEM
There is no more memory.
VCMDERR_VALUEOUTOFRANGE
The value is out of range.

Remarks

An application can use a voice menu enumerator to find and modify unknown menus or to show menu status to the user.

The voice menu enumerator persists until all references to it are released, even if the voice command object is released.


IVoiceCmd::Register

This method is called by an application to register to use voice commands on a site.

Syntax

HRESULT Register( PTSTR pszSite, PIVCMDNOTIFYSINK pNotifyInterface, IID IIDNotifyInterface, DWORD dwFlags, PVCSITEINFO pSiteInfo);

Parameters

pszSite
Ignored, because there is only one site: “Local PC.”
pNotifyInterface
[in] Pointer to the notification interface that receives notifications from the voice command object. The interface identifier is specified by IIDNotifyInterface. If this parameter is NULL, no notifications are sent.

Because passing the pointer to the voice command object does not transfer ownership of the notification interface, the voice command object must call the AddRef method of the notification interface before returning from the call to Register. The voice command object must also call the Release method of the notification interface when it closes. The calling application must release any reference counts it holds on the notification interface after calling Register, unless it needs the notification object to be valid when the voice command object releases it.

IIDNotifyInterface
[in] Interface identifier (IID) that uniquely identifies the type of notification sink being passed to the voice command object. It must be IID_IVCmdNotifySinkW.
dwFlags
[in] Specifies whether the application is to receive all notifications. It is one of the following flags:
VCMDRF_ALLBUTVUMETER
Sends all but VUMeter notifications to pNotifyInterface.
VCMDRF_NOMESSAGES
Does not send notifications.
VCMDRF_CMDOTHER
Sends CommandOther notifications to pNotifyInterface.
VCMDRF_CMDSTART
Sends CommandStart notifications to pNotifyInterface.
VCMDRF_ATTRIBCHANGE
Sends AttribChanged notifications to pNotifyInterface.
VCMDRF_CMDRECOG
Sends CommandRecognize notifications to pNotifyInterface.
pSiteInfo
[in] Pointer to a VCSITEINFO structure that contains settings to apply to the site, such as the speaker, confidence threshold, and speech-recognition mode. The settings are applied even if the site is already open. If this parameter is NULL, the voice command object uses the settings from the registry. If there are no registry settings, it uses the default settings, typically those for the computer.

Telephony applications pass this information to ensure that the proper settings are selected. Other applications set this parameter to NULL to leave the site settings unchanged from previous values.

Return Values

NOERROR
The method successfully registered to use voice commands on a site.
E_INVALIDARG
The argument is invalid.
VCMDERR_CANTCREATEAUDIODEVICE
An audio source object cannot be created for speech recognition.
VCMDERR_CANTCREATESRENUM
A speech recognition enumerator object cannot be created.
VCMDERR_CANTSELECTENGINE
A speech recognition engine cannot be selected.
VCMDERR_CANTSETDEVICE
The device identifier cannot be set into the audio source object.
VCMDERR_INVALIDMODE
No site exists, the site does not support this attribute, or the voice command object is already registered with a site.
VCMDERR_NOFINDINTERFACE
The speech recognition enumerator interface does not have a Find interface.
VCMDERR_NOSITEINFO
Information to open this site is not available.
VCMDERR_OUTOFMEM
There is no more memory.
VCMDERR_SRFINDFAILED
The speech recognition object could not find an appropriate mode.
VCMDERR_VALUEOUTOFRANGE
The value is out of range.

Remarks

An application cannot call Register a second time for the same voice command object. If a voice command object is already registered, calling Register returns an error. To change sites, the application must call the CoCreateInstance function to create a new voice command object for the desired site.

See Also

An application must call Register before it can call any of the following methods:

IVCmdMenu::Deactivate, IVCmdMenu::ListGet, IVCmdMenu::ListSet


IVoiceText

This interface registers an application to use the voice text object, and controls playback of text.

Method
Description
IVoiceText::AudioPause | Pauses text-to-speech output for a voice text site.
IVoiceText::AudioResume | Resumes text-to-speech output after it has been paused by the IVoiceText::AudioPause method.
IVoiceText::Register | Registers an application to use voice text on a site.
IVoiceText::Speak | Starts playing the specified text.
IVoiceText::StopSpeaking | Halts text that is currently being spoken and flushes all pending text from the playback queue.


IVoiceText::AudioPause

This method pauses text-to-speech output for a voice text site.

Syntax

HRESULT AudioPause(void);

Return Values

NOERROR
The method successfully paused the text-to-speech output.
VTXTERR_INVALIDMODE
The text-to-speech mode is invalid, or the application has not been registered to use the voice text on the site.
VTXTERR_NOTENABLED
Voice text is not enabled.
VTXTERR_OUTOFMEM
There is not enough memory.

Remarks

When a voice text object is first created, text-to-speech output is not paused. Because pausing text-to-speech output affects all applications that use voice text on the site, an application should resume text-to-speech output as soon as possible by calling the IVoiceText::AudioResume method.

When output has been paused, the IVTxtAttributes::IsSpeaking method returns FALSE, even though the voice text object still has data available in its queue and has not yet sent a IVTxtNotifySink::SpeakingDone notification.

No notifications are sent when audio is paused or resumed.

See Also

IVoiceText::AudioResume, IVTxtAttributes::IsSpeaking, IVTxtNotifySink::SpeakingDone


IVoiceText::AudioResume

This method resumes text-to-speech output after it has been paused by the IVoiceText::AudioPause method.

Syntax

HRESULT AudioResume(void);

Return Values

NOERROR
The method successfully resumed the text-to-speech output.
VTXTERR_INVALIDMODE
The text-to-speech mode is invalid, or the application has not been registered to use the voice text on the site.
VTXTERR_NOTENABLED
Voice text is not enabled.
VTXTERR_OUTOFMEM
There is not enough memory.

Remarks

The AudioResume method affects all applications using the site.

See Also

IVoiceText::AudioPause


IVoiceText::Register

This method registers an application to use voice text on a site.

Syntax

HRESULT Register( PTSTR pszSite, PTSTR pszApplication, PIVTXTNOTIFYSINK pNotifyInterface, IID IIDNotifyInterface, DWORD dwFlags, PVTSITEINFO pSiteInfo);

Parameters

pszSite
Ignored because there is only one site, “Local PC.”
pszApplication
[in] Pointer to a null-terminated string that identifies the application—for example, “Radio.” An application can use this information to display the source of text. This parameter must not be NULL.
pNotifyInterface
[in] Pointer to the notification interface through which the voice text object notifies the application about text-to-speech information. If this parameter is NULL, no notifications are sent. The interface identifier is specified by the IIDNotifyInterface parameter.

Because passing the pointer to the voice text object does not transfer ownership of the notification interface, the voice text object must call the AddRef method of the notification interface before returning from the call to Register. The voice text object must also call the Release method of the notification interface when it closes. The calling application must release any reference counts that the application holds on the notification interface after calling Register, unless the application needs the notification object to be valid when the voice text object releases notification interface.

IIDNotifyInterface
[in] Interface identifier of the interface used for notification. For Auto PC, this parameter must be IID_IVTxtNotifySinkW.
dwFlags
[in] Specifies whether the application is to receive all notifications. If this parameter is the VTXTF_ALLMESSAGES value, all notifications are sent to pNotifyInterface. The application can specify which notifications to receive by passing in the combination of the following values:
  • VTXTF_SPEAKDONE
  • VTXTF_SPEAKSTART
pSiteInfo
[in] Pointer to a VTSITEINFO structure that contains settings to apply to the site, such as the voice and talking speed. The settings are applied, even if the site is already open. If a VTSITEINFO structure is not specified, the voice text object uses the settings from the registry. If there are no registry settings, it uses the default settings, typically those for the computer.

Telephony applications pass this information to ensure that the proper settings are selected. Other applications set this parameter to NULL to leave the site settings unchanged.

Return Values

NOERROR
The method successfully registered an application to use voice text on a site.
VTXTERR_INVALIDPARAM
A parameter is invalid.
VTXTERR_OUTOFMEM
There is not enough memory.

Remarks

An application must call Register before it can call other methods in the IVoiceText interface.

An application cannot call Register a second time for the same voice text object. To change sites, the application must call the CoCreateInstance function to create a new voice text object for the desired site.

See Also

VTSITEINFO, IVTxtNotifySink::SpeakingStarted, IVTxtNotifySink::SpeakingDone


IVoiceText::Speak

This method starts playing the specified text.

Syntax

HRESULT Speak( PTSTR pszSpeak, DWORD dwFlags, PTSTR pszTags);

Parameters

pszSpeak
[in] Pointer to a buffer that contains the text to speak. The text is in the form of a null-terminated string. The length of the text string must be less than 2 kilobytes (KB). Strings longer than 2 KB cause unexpected speech behavior. An application can free or modify the buffer as soon as Speak returns. The string pointed to by this parameter can contain text-to-speech control tags. In Auto PC, this string can contain the TTS tags. For more information about tags, see Text-to-Speech Tags.
dwFlags
[in] Specifies priority of the text. It is one of the following values:
VTXTSP_HIGH
Play the text as soon as possible, after text that is currently being spoken but before any other text in the playback queue.
VTXTSP_NORMAL
Add the text to the end of the playback queue. This is the default priority.
VTXTSP_VERYHIGH
Play the text immediately, interrupting text that is currently being spoken, if any. The interrupted text resumes playing as soon as the very high priority text is finished, although the interrupted text may not be correctly synchronized.
pszTags
[in] Ignored.

Return Values

NOERROR
The method successfully started playing the specified text.
VTXTERR_INVALIDMODE
The text-to-speech mode is invalid, or the application has not been registered to use the voice text on the site.
VTXTERR_INVALIDPARAM
A parameter is invalid.
VTXTERR_NOTENABLED
Voice text is not enabled.
VTXTERR_OUTOFMEM
There is not enough memory.
VTXTERR_QUEUEFULL
The playback queue is full.
VTXTERR_WAVEDEVICEBUSY
The wave device is busy.

Remarks

If an application calls the Speak method when other text is being played, the specified text is added to the end of the playback queue, unless the application specifies a higher priorityfor the new text in dwFlags.

Calling Speak affects all applications using voice text on the site, because all applications share the same playback queue.

The type of speech specified by dwFlags is communicated to the text-to-speech engine though control tags. Support of most control tags is optional; the engine ignores unsupported tags.

See Also

IVoiceText::StopSpeaking


IVoiceText::StopSpeaking

This method halts text that is currently being spoken and flushes all pending text from the playback queue.

Syntax

HRESULT StopSpeaking(void);

Return Values

NOERROR
The method successfully halted the text being spoken and flushed all pending text from the playback queue.
VTXTERR_INVALIDMODE
The text-to-speech mode is invalid, or the application has not been registered to use the voice text on the site.
VTXTERR_NOTENABLED
Voice text is not enabled.
VTXTERR_OUTOFMEM
There is not enough memory.

Remarks

Calling the StopSpeaking method affects all applications using voice text on the site, because all applications share the same playback queue.

See Also

IVoiceText::Speak


IVTxtAttributes

This interface allows an application to control various aspects of the operation of a voice text object.

Method
Description
IVTxtAttributes::EnabledGet | Retrieves whether voice text is enabled for a voice text site.
IVTxtAttributes::EnabledSet | Sets whether voice text is enabled for a voice text site.
IVTxtAttributes::IsSpeaking | Indicates whether text is currently being spoken by a voice text site.
IVTxtAttributes::SpeedGet | Retrieves the current average talking speed for a voice text site, in words per minute.
IVTxtAttributes::SpeedSet | Sets the average talking speed for a voice text site, in words per minute.
IVTxtAttributes::TTSModeGet | Retrieves the globally unique identifier (GUID) of the current text-to-speech (TTS) mode for a voice text site.
IVTxtAttributes::TTSModeSet | Sets the globally unique identifier (GUID) of the current text-to-speech (TTS) mode for a voice text site.


IVTxtAttributes::EnabledGet

This method retrieves whether voice text is enabled for a voice text site.

Syntax

HRESULT EnabledGet( DWORD *dwEnabled);

Parameters

dwEnabled
[out] Specifies whether voice text is enabled. TRUE indicates that voice text is enabled for the site; FALSE indicates it is disabled.

Return Values

NOERROR
The method successfully retrieved whether voice text is enabled for a voice text site.
VTXTERR_INVALIDMODE
The text-to-speech mode is invalid, or the application has not been registered to use the voice text on the site.
VTXTERR_INVALIDPARAM
A parameter is invalid.
VTXTERR_OUTOFMEM
There is not enough memory.

Remarks

If voice text is disabled, no text-to-speech is played over the site. Enabling or disabling voice text for a site affects all applications using a voice text site.

Typically, an application disables voice text because the user does not want the computer to speak.

The enabled state for a site is saved between uses of the site, even if the user shuts down the computer in the meantime.

See Also

IVTxtAttributes::EnabledSet


IVTxtAttributes::EnabledSet

This method sets whether voice text is enabled for a voice text site.

Syntax

HRESULT EnabledSet( DWORD dwEnabled);

Parameters

dwEnabled
[in] Specifies whether voice text is enabled. TRUE indicates that voice text is enabled for the site; FALSE indicates it is disabled.

Return Values

NOERROR
The method successfully set whether voice text is enabled for a voice text site.
VTXTERR_INVALIDMODE
The text-to-speech mode is invalid, or the application has not been registered to use the voice text on the site.
VTXTERR_INVALIDPARAM
A parameter is invalid.
VTXTERR_OUTOFMEM
There is not enough memory.

Remarks

The enabled state for a site is saved between uses of the site, even if the user shuts down the computer in the meantime.

See Also

IVTxtAttributes::EnabledGet


IVTxtAttributes::IsSpeaking

This method indicates whether text is currently being spoken by a voice text site.

Syntax

HRESULT IsSpeaking( BOOL *pfSpeaking);

Parameters

pfSpeaking
[out] Pointer to a Boolean that receives the current speaking status. The Boolean is set to TRUE if the text-to-speech engine is speaking, or to FALSE if it is silent.

Return Values

NOERROR
The method successfully indicated whether text is currently being spoken by a voice text site.
VTXTERR_INVALIDMODE
The text-to-speech mode is invalid, or the application has not been registered to use the voice text on the site.
VTXTERR_INVALIDPARAM
A parameter is invalid.
VTXTERR_OUTOFMEM
There is not enough memory.

Remarks

The voice text object does not send data resulting from multiple calls to the IVoiceText::Speak method directly to the text-to-speech engine. Instead, the object keeps data from each call in a separate buffer so that the VTXTSP_HIGH and VTXTSP_VERYHIGH priority strings can be inserted into the queue at the proper positions.

For example, a VTXTSP_VERYHIGH priority string may interrupt a high or normal priority string. The interrupted string resumes after the very high priority string has finished. As a result of this implementation, IsSpeaking returns FALSE for a short time between the end of one buffer in the queue and the start of the next buffer, because audio output has been temporarily suspended.


IVTxtAttributes::SpeedGet

This method retrieves the current average talking speed for a voice text site, in words per minute.

Syntax

HRESULT SpeedGet( DWORD *pdwSpeed);

Parameters

pdwSpeed
[out] Pointer to a DWORD that receives the talking speed for a voice text site.

Return Values

NOERROR
The method successfully retrieved the current average talking speed for a voice text site.
VTXTERR_INVALIDMODE
The text-to-speech mode is invalid, or the application has not been registered to use the voice text on the site.
VTXTERR_INVALIDPARAM
A parameter is invalid.
VTXTERR_OUTOFMEM
There is not enough memory.

Remarks

The talking speed for a site is saved between uses of the site, even if the user shuts down the computer in the meantime.

See Also

IVTxtAttributes::SpeedSet


IVTxtAttributes::SpeedSet

This method sets the average talking speed for a voice text site, in words per minute.

Syntax

HRESULT SpeedSet( DWORD dwSpeed);

Parameters

dwSpeed
[in] Specifies the new talking speed for the site. An application can specify TTSATTR_MINSPEED or TTSATTR_MAXSPEED for the minimum or maximum allowable value, respectively.

Return Values

NOERROR
The method successfully set the average talking speed for a voice text site.
VTXTERR_INVALIDPARAM
A parameter is invalid.
VTXTERR_OUTOFMEM
There is not enough memory.

Remarks

The talking speed for a site is saved between uses of the site, even if the user shuts down the computer in the meantime.

If a voice-navigation application is installed on the user’s computer, an application may not need to set the speed.

See Also

IVTxtAttributes::SpeedGet


IVTxtAttributes::TTSModeGet

This method retrieves the globally unique identifier (GUID) of the current text-to-speech (TTS) mode for a voice text site.

Syntax

HRESULT TTSModeGet( GUID *pgVoice);

Parameters

pgVoice
[out] Pointer to a variable that receives the GUID assigned to the text-to-speech mode.

Return Values

NOERROR
The method successfully retrieved the GUID of the current TTS mode for a voice text site.
VTXTERR_INVALIDMODE
The text-to-speech mode is invalid, or the application has not been registered to use the voice text on the site.
VTXTERR_INVALIDPARAM
A parameter is invalid.
VTXTERR_OUTOFMEM
There is not enough memory.

Remarks

A text-to-speech engine typically provides an assortment of text-to-speech modes that can be used to play speech in different voices. A voice text site uses a single text-to-speech mode, represented internally by a low-level engine object.

The text-to-speech mode for a site is saved between uses of the site, even if the user shuts down the computer in the meantime.

In Auto PC, there is usually only one TTS mode.

See Also

IVTxtAttributes::TTSModeSet


IVTxtAttributes::TTSModeSet

This method sets the globally unique identifier (GUID) of the current text-to-speech (TTS) mode for a voice text site.

Syntax

HRESULT TTSModeSet( GUID gVoice);

Parameters

gVoice
[in] GUID of the TTS mode to set for the site. If the mode does not exist, an error is returned and the mode is not changed.

Return Values

NOERROR
The method successfully set the GUID of the current TTS mode for a voice text site.
VTXTERR_INVALIDMODE
The text-to-speech mode is invalid, or the application has not been registered to use the voice text on the site.
VTXTERR_INVALIDPARAM
A parameter is invalid.
VTXTERR_OUTOFMEM
There is not enough memory.

Remarks

The text-to-speech mode for a site is saved between uses of the site, even if the user shuts down the computer in the meantime.

If a voice-navigation application is installed on the user’s computer, an application may not need to set the mode.

There is usually only one TTS mode.

See Also

IVTxtAttributes::TTSModeGet


IVTxtNotifySink

This interface notifies an application of the status of the object.

Method
Description
IVTxtNotifySink::SpeakingDone | Notifies all applications on a voice text site that speaking is finished and no text remains in the playback queue.
IVTxtNotifySink::SpeakingStarted | Notifies all applications on a voice text site that speaking has started.


IVTxtNotifySink::SpeakingDone

This method notifies all applications on a voice text site that speaking is finished and no text remains in the playback queue.

Syntax

HRESULT SpeakingDone ( void );

Return Values

The return value is ignored.

See Also

IVTxtNotifySink::SpeakingStarted


IVTxtNotifySink::SpeakingStarted

This method notifies all applications on a voice text site that speaking has started.

Syntax

HRESULT SpeakingStarted(void);

Return Values

The return value is ignored.

See Also

IVTxtNotifySink::SpeakingDone


IASCanvas

This control interface allows direct graphical device interface (GDI) access to an area on the faceplate.

Method
Description
IASCanvas::ClipAndCommit | Sends the current contents of the device context (DC) to the screen while clipping against the supplied region.
IASCanvas::Commit | Sends the current contents of the device context (DC) to the screen.
IASCanvas::CommitAt | Sends a selected rectangle of the current off-screen bitmap to the screen.
IASCanvas::CommitFrom | Maps and sends the contents of an off-screen bitmap, starting at the specified coordinates, to the upper-left corner of a control.
IASCanvas::get_AutoCommit | Enables you to determine if the control is in the auto-commit mode and to determine the coordinates of the starting point for the off-screen bitmap from which auto-commit blits..
IASCanvas::GetDC | Gets a handle to the device context for a control, or creates a compatible off-screen bitmap and gets the device context of that bitmap.
IASCanvas::put_AutoCommit | Sets the auto-commit mode for a control and sets the coordinates of the starting point for an off-screen bitmap from which auto-commit blits.

Remarks

The IASCanvas interface, which has a global unique identifier equal to IID_ASCANVAS, extends the IASControl interface. The canvas control has a programmatic identifier equal to APC_Canvas.


IASCanvas::ClipAndCommit

This method sends the current contents of the device context (DC) to the screen while clipping against the supplied region.

Syntax

HRESULT ClipAndCommit( OLE_HANDLE hrgnClip );

Parameters

hrgnClip
Handle to the clipping region.

Return Values

NOERROR indicates success. E_UNEXPECTED indicates that something unexpected happened.

Remarks

Use CreateRectRgn to get a handle to the intended clipping region.

See Also

CreateRectRgn


IASCanvas::Commit

This method sends the current contents of the device context (DC) to the screen.

Syntax

HRESULT Commit( void );

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASCanvas::CommitAt

This method sends a selected rectangle of the current off-screen bitmap to the screen.

Syntax

HRESULT CommitAt( long xDest, long yDest, long xSrc, long ySrc, long dx, long dy );

Parameters

xDest
Specifies the left edge of the target rectangle.
yDest
Specifies the upper edge of the target rectangle.
xSrc
Specifies the left edge of the source rectangle.
ySrc
Specifies the upper edge of the source rectangle.
dx
Specifies the width of the source rectangle.
dy
Specifies the height of the source rectangle.

Return Values

NOERROR indicates success. E_UNEXPECTED indicates that something unexpected happened.

See Also

IASCanvas::ClipAndCommit, IASCanvas::CommitFrom


IASCanvas::CommitFrom

This method maps and sends the contents of an off-screen bitmap, starting at the specified coordinates, to the upper-left corner of a control.

Syntax

HRESULT CommitFrom( long xSrc, long ySrc );

Parameters

xSrc
[in] Specifies the left edge of the rectangle to be committed.
ySrc
[in] Specifies the upper edge of the rectangle to be committed.

Return Values

NOERROR indicates success. E_UNEXPECTED indicates that something unexpected happened.

Remarks

The specified starting corner of the bitmap is mapped to the upper-left corner of the control. If the committed portion of the bitmap is smaller than the control, the remainder of the control is painted in a default color. If the committed portion of the bitmap is larger than the control, the bitmap is clipped on the right and bottom sides.

See Also

IASCanvas::ClipAndCommit, IASCanvas::CommitAt


IASCanvas::get_AutoCommit

This method enables you to determine if the control is in the auto-commit mode and to determine the coordinates of the starting point for the off-screen bitmap from which auto-commit blits.

Syntax

HRESULT get_AutoCommit( BOOL *pfAutoCommit, long *pxSrc, long *pySrc );

Parameters

pfAutoCommit
Pointer to a Boolean that is set to TRUE if auto-commit is enabled, or to FALSE if auto-commit is disabled. The default setting is FALSE.
pxSrc
Pointer to the x-coordinate of the source bitmap from which auto-commit blits.
pySrc
Pointer to the y-coordinate of the source bitmap from which auto-commit blits.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the device is out of memory.

Remarks

If auto-commit is enabled, every time the screen is redrawn, the last bitmap that was set is used to redraw the screen. This is useful for handling form focus changes—for example, using a timer to move an application from the background to the foreground. Enabling auto-commit tells the forms manager to only repaint the last bitmap that was set when the Forms Manager redraws the screen.

In general, the purpose of the Canvas control is to give the application a substantial degree of control over drawing. For this reason, auto-commit is disabled by default. However, in some circumstances, enabling auto-commit can simplify your application by automating the painting process.


IASCanvas::GetDC

This method gets a handle to the device context for a control, or creates a compatible off-screen bitmap and gets the device context of that bitmap.

Syntax

HRESULT GetDC( OLE_HANDLE *phdc, BOOL fOffScreen );

Parameters

phdc
Pointer to the handle of a device context (DC).
fOffScreen
[in] Boolean that is set to TRUE to create an offscreen bitmap for the DC, or set to FALSE to get the DC of the control.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the device is out of memory.

Remarks

Conventional GDI drawing should be done to an offscreen bitmap. When complete, it is then transferred to the screen with either IASCanvas::ClipAndCommit or IASCanvas::Commit. For techniques where the bitmaps already exist, like sprite animation, the offscreen bitmap is not necessary, and should not be created.

See Also

IASCanvas::ClipAndCommit, IASCanvas::Commit


IASCanvas::put_AutoCommit

This method sets the auto-commit mode for a control and sets the coordinates of the starting point for an off-screen bitmap from which auto-commit blits.

Syntax

HRESULT put_AutoCommit( BOOL fAutoCommit, long xSrc, long ySrc );

Parameters

fAutoCommit
Boolean that is set to TRUE to enable auto-commit, or to FALSE to disable it. The default setting is FALSE.
pxSrc
Pointer to the starting x-coordinate of the source bitmap from which auto-commit blits.
pySrc
Pointer to the starting y-coordinate of the source bitmap from which auto-commit blits.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the device is out of memory.

Remarks

If auto-commit is enabled, every time the screen is redrawn, the last bitmap that was set is used to redraw the screen. This is useful for handling form focus changes— for example, using a timer to move an application from the background to the foreground. Enabling auto-commit tells the forms manager to only repaint the last bitmap that was set when the Forms Manager redraws the screen.

In general, the purpose of the Canvas control is to give the application a substantial degree of control over drawing. For this reason, auto-commit is disabled by default. However, in some circumstances, enabling auto-commit can simplify your application by automating the painting process.


IASClock

This interface provides methods to access the clock control.

Method
Description
IASClock::get_ClockFormat | Gets the time and date format for the clock display.
IASClock::get_LabelFormat | Gets the current label format.
IASClock::put_ClockFormat | Sets the time and date format for the clock display.
IASClock::put_ClockLabel | Specifies a label control to be used as a label field; usually, the label displays date information.
IASClock::put_LabelFormat | Sets the current label format.
IASClock::put_ClockLabel0 | Specifies a label control to be used as a label field; usually, the label displays time information.

Remarks

The IASClock interface, which has a global unique identifier equal to IID_ASCLOCK, extends the IASControl interface.

The clock control, which has a programmatic identifier equal to APC_Clock, can display either the time or the date. The clock control has two display regions: the clock proper and a label control that serves as the label. The clock control is an invisible control. The clock control displays the time in the label control attached by the put_ClockLabel0 method, and displays the date in the label control attached by the put_ClockLabel method.


IASClock::get_ClockFormat

This method gets the time and date format for the clock display.

Syntax

HRESULT get_ClockFormat( BOOL *pfTime, BSTR *pbstrFormat, LONG *pFormatFlags );

Parameters

pfTime
Pointer to a Boolean that is set to TRUE for the time, or to FALSE for the date.
pbstrFormat
Pointer to the Unicode string that defines the format of the time and date display. If pbstrFormat is NULL, the function uses the default format of the specified locale.

Use the following elements to construct a time format string:

h
The one- or two-digit hour in 12-hour format.
hh
The two-digit hour in 12-hour format. Single-digit values are preceded by a zero.
H
The one- or two-digit hour in 24-hour format.
HH
The two-digit hour in 24-hour format. Single-digit values are preceded by a zero.
m
The one- or two-digit minute.
mm
The two-digit minute. Single-digit values are preceded by a zero.
s
The one- or two-digit second.
ss
The two-digit second. Single-digit values are preceded by a zero.
t
The one-letter AM/PM abbreviation; that is, “AM” is displayed as “A.”
tt
The two-letter AM/PM abbreviation; that is, “AM” is displayed as “AM.”

Use the following elements to construct a date format string:

d
The one- or two-digit day.
dd
The two-digit day. Single-digit values are preceded by a zero.
ddd
The three-character weekday abbreviation. The function uses the LOCALE_SABBREVDAYNAME value associated with the specified locale.
dddd
The full weekday name. The function uses the LOCALE_SDAYNAME value associated with the specified locale.
M
The one- or two-digit month number.
MM
The two-digit month number. Single-digit values are preceded by a zero.
MMM
The three-character abbreviation. The function uses the LOCALE_SABBREVMONTHNAME value associated with the specified locale.
MMMM
The full month name. The function uses the LOCALE_SMONTHNAME value associated with the specified locale.
y
The year is displayed as the last two digits, but with no leading zero for years less than 10.
yy
The last two digits of the year; that is, 1996 is displayed as “96.”
yyyy
The full year; that is, 1996 is displayed as “1996.”
gg
Period/era string. The function uses the CAL_SERASTRING value associated with the specified locale. This element is ignored if the date to be formatted does not have an associated era or period string.

For example, to get the time display

“11:29:40 PM”

use the following format string:

"hh':'mm':'ss tt"

To get the date display

“Wed, Aug 31 94”

use the following format string:

"ddd',' MMM dd yy"

If you use spaces to separate the elements, they appear in the same location in the output string. The letters must be in uppercase or lowercase as shown, for example, “ss”, not “SS.” To have a character appear in the actual time string, enclose it in single quotes and it appears in the same location as it occupies in the format string.

pFormatFlags
Pointer to a bitmask of flags specifying the format.

The following formats are available for time display:

LOCALE_NOUSEROVERRIDE
If set, the function formats the string using the system default time format for the specified locale. If not set, the function formats the string using any user overrides to the locale’s default time format. This flag cannot be set if pbstrFormat is non-NULL.
TIME_NOMINUTESORSECONDS
Do not use minutes or seconds.
TIME_NOSECONDS
Do not use seconds.
TIME_NOTIMEMARKER
Do not use a time marker.
TIME_FORCE24HOURFORMAT
Always use a 24-hour time format.

The following formats are available for date display:

LOCALE_NOUSEROVERRIDE
If set, the function formats the string using the system default date format for the specified locale. If not set, the function formats the string using any user overrides to the locale’s default date format.
DATE_SHORTDATE
Use the short date format. This is the default. Cannot be used with DATE_LONGDATE.
DATE_LONGDATE
Use the long date format. Cannot be used with DATE_SHORTDATE.
DATE_USE_ALT_CALENDAR
Use the alternate calendar, if one exists, to format the date string. If this flag is set, the function uses the default format for that alternate calendar, rather than using any user overrides. The user overrides are used only in the event that there is no default format for the specified alternate calendar.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.


IASClock::get_LabelFormat

This method gets the current label format.

Syntax

HRESULT get_LabelFormat( BOOL *pfTime, BSTR *pbstrFormat, LONG *pFormatFlags );

Parameters

pfTime
Pointer to a Boolean that is set to TRUE for the time, or to FALSE for the date.
pbstrFormat
Pointer to the Unicode string that defines the format of the time and date display. If pbstrFormat is NULL, the function uses the default format of the specified locale.

Use the following elements to construct a time format string:

h
The one- or two-digit hour in 12-hour format.
hh
The two-digit hour in 12-hour format. Single-digit values are preceded by a zero.
H
The one- or two-digit hour in 24-hour format.
HH
The two-digit hour in 24-hour format. Single-digit values are preceded by a zero.
m
The one- or two-digit minute.
mm
The two-digit minute. Single-digit values are preceded by a zero.
s
The one- or two-digit second.
ss
The two-digit second. Single-digit values are preceded by a zero.
t
The one-letter AM/PM abbreviation; that is, “AM” is displayed as “A.”
tt
The two-letter AM/PM abbreviation.

Use the following elements to construct a date format string:

d
The one- or two-digit day.
dd
The two-digit day. Single-digit values are preceded by a zero.
ddd
The three-character weekday abbreviation. The function uses the LOCALE_SABBREVDAYNAME value associated with the specified locale.
dddd
The full weekday name. The function uses the LOCALE_SDAYNAME value associated with the specified locale.
M
The one- or two-digit month number.
MM
The two-digit month number. Single-digit values are preceded by a zero.
MMM
The three-character abbreviation. The function uses the LOCALE_SABBREVMONTHNAME value associated with the specified locale.
MMMM
The full month name. The function uses the LOCALE_SMONTHNAME value associated with the specified locale.
y
The year is displayed as the last two digits, but with no leading zero for years less than 10.
yy
The last two digits of the year; that is, 1996 is displayed as “96.”
yyyy
The full year; that is, 1996 is displayed as “1996.”
gg
Period/era string. The function uses the CAL_SERASTRING value associated with the specified locale. This element is ignored if the date to be formatted does not have an associated era or period string.

For example, to get the time display

“11:29:40 PM”

use the following format string:

"hh':'mm':'ss tt"

To get the date display

“Wed, Aug 31 94”

use the following format string:

"ddd',' MMM dd yy"

If you use spaces to separate the elements, they appear in the same location in the output string. The letters must be in uppercase or lowercase as shown, for example, “ss”, not “SS.” To have a character appear in the actual time string, enclose it in single quotes and it appears in the same location as it occupies in the format string.

pFormatFlags
Pointer to a bitmask of flags specifying the format.

The following formats are available for time display:

LOCALE_NOUSEROVERRIDE
If set, the function formats the string using the system default time format for the specified locale. If not set, the function formats the string using any user overrides to the locale’s default time format. This flag cannot be set if pbstrFormat is non-NULL.
TIME_NOMINUTESORSECONDS
Do not use minutes or seconds.
TIME_NOSECONDS
Do not use seconds.
TIME_NOTIMEMARKER
Do not use a time marker.
TIME_FORCE24HOURFORMAT
Always use a 24-hour time format.

The following formats are available for date display:

LOCALE_NOUSEROVERRIDE
If set, the function formats the string using the system default date format for the specified locale. If not set, the function formats the string using any user overrides to the locale’s default date format.
DATE_SHORTDATE
Use the short date format. This is the default. Cannot be used with DATE_LONGDATE.
DATE_LONGDATE
Use the long date format. Cannot be used with DATE_SHORTDATE.
DATE_USE_ALT_CALENDAR
Use the alternate calendar, if one exists, to format the date string. If this flag is set, the function uses the default format for that alternate calendar, rather than using any user overrides. The user overrides are used only in the event that there is no default format for the specified alternate calendar.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.


IASClock::put_ClockFormat

This method sets the time and date format for the clock display.

Syntax

HRESULT put_ClockFormat( BOOL fTime, BSTR bstrFormat, LONG FormatFlags );

Parameters

fTime
Boolean that is set to TRUE for the time, or to FALSE for the date.
bstrFormat
Unicode string that defines the format of the time and date display. If bstrFormat is NULL, the function uses the default format of the specified locale.

Use the following elements to construct a time format string:

h
The one- or two-digit hour in 12-hour format.
hh
The two-digit hour in 12-hour format. Single-digit values are preceded by a zero.
H
The one- or two-digit hour in 24-hour format.
HH
The two-digit hour in 24-hour format. Single-digit values are preceded by a zero.
m
The one- or two-digit minute.
mm
The two-digit minute. Single-digit values are preceded by a zero.
s
The one- or two-digit second.
ss
The two-digit second. Single-digit values are preceded by a zero.
t
The one-letter AM/PM abbreviation; that is, “AM” is displayed as “A.”
tt
The two-letter AM/PM abbreviation.

Use the following elements to construct a date format string:

d
The one- or two-digit day.
dd
The two-digit day. Single-digit values are preceded by a zero.
ddd
The three-character weekday abbreviation. The function uses the LOCALE_SABBREVDAYNAME value associated with the specified locale.
dddd
The full weekday name. The function uses the LOCALE_SDAYNAME value associated with the specified locale.
M
The one- or two-digit month number.
MM
The two-digit month number. Single-digit values are preceded by a zero.
MMM
The three-character abbreviation. The function uses the LOCALE_SABBREVMONTHNAME value associated with the specified locale.
MMMM
The full month name. The function uses the LOCALE_SMONTHNAME value associated with the specified locale.
y
The year is displayed as the last two digits, but with no leading zero for years less than 10.
yy
The last two digits of the year; that is, 1996 is displayed as “96.”
yyyy
The full year; that is, 1996 is displayed as “1996.”
gg
Period/era string. The function uses the CAL_SERASTRING value associated with the specified locale. This element is ignored if the date to be formatted does not have an associated era or period string.

For example, to get the time display

“11:29:40 PM”

use the following format string:

"hh':'mm':'ss tt"

To get the date display

“Wed, Aug 31 94”

use the following format string:

"ddd',' MMM dd yy"

If you use spaces to separate the elements, they appear in the same location in the output string. The letters must be in uppercase or lowercase as shown, for example, “ss”, not “SS.” To have a character appear in the actual time string, enclose it in single quotes and it appears in the same location as it occupies in the format string.

FormatFlags
Bitmask of flags specifying the format.

The following formats are available for time display:

LOCALE_NOUSEROVERRIDE
If set, the function formats the string using the system default time format for the specified locale. If not set, the function formats the string using any user overrides to the locale’s default time format. This flag cannot be set if bstrFormat is non-NULL.
TIME_NOMINUTESORSECONDS
Do not use minutes or seconds.
TIME_NOSECONDS
Do not use seconds.
TIME_NOTIMEMARKER
Do not use a time marker.
TIME_FORCE24HOURFORMAT
Always use a 24-hour time format.

The following formats are available for date display:

LOCALE_NOUSEROVERRIDE
If set, the function formats the string using the system default date format for the specified locale. If not set, the function formats the string using any user overrides to the locale’s default date format.
DATE_SHORTDATE
Use the short date format. This is the default. Cannot be used with DATE_LONGDATE.
DATE_LONGDATE
Use the long date format. Cannot be used with DATE_SHORTDATE.
DATE_USE_ALT_CALENDAR
Use the alternate calendar, if one exists, to format the date string. If this flag is set, the function uses the default format for that alternate calendar, rather than using any user overrides. The user overrides are used only in the event that there is no default format for the specified alternate calendar.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

Remarks

If any format flag is used for FormatFlags, NULL must be passed to bstrFormat.


IASClock::put_ClockLabel

This method specifies a label control to be used as a label field; usually, the label displays date information.

Syntax

HRESULT put_ClockLabel( IDispatch *pdispLabel );

Parameters

pdispLabel
Pointer to an Auto PC simple (AS) label control to be used as the label field.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.


IASClock::put_LabelFormat

This method sets the current label format.

Syntax

HRESULT put_LabelFormat( BOOL fTime, BSTR bstrFormat, LONG FormatFlags );

Parameters

fTime
Boolean that is set to TRUE for the time, or to FALSE for the date.
bstrFormat
Unicode string that defines the format of the time and date display. If bstrFormat is NULL, the function uses the default format of the specified locale.

Use the following elements to construct a time format string:

h
The one- or two-digit hour in 12-hour format.
hh
The two-digit hour in 12-hour format. Single-digit values are preceded by a zero.
H
The one- or two-digit hour in 24-hour format.
HH
The two-digit hour in 24-hour format. Single-digit values are preceded by a zero.
m
The one- or two-digit minute.
mm
The two-digit minute. Single-digit values are preceded by a zero.
s
The one- or two-digit second.
ss
The two-digit second. Single-digit values are preceded by a zero.
t
The one-letter AM/PM abbreviation; that is, “AM” is displayed as “A.”
tt
The two-letter AM/PM abbreviation.

Use the following elements to construct a date format string:

d
The one- or two-digit day.
dd
The two-digit day. Single-digit values are preceded by a zero.
ddd
The three-character weekday abbreviation. The function uses the LOCALE_SABBREVDAYNAME value associated with the specified locale.
dddd
The full weekday name. The function uses the LOCALE_SDAYNAME value associated with the specified locale.
M
The one- or two-digit month number.
MM
The two-digit month number. Single-digit values are preceded by a zero.
MMM
The three-character abbreviation. The function uses the LOCALE_SABBREVMONTHNAME value associated with the specified locale.
MMMM
The full month name. The function uses the LOCALE_SMONTHNAME value associated with the specified locale.
y
The year is displayed as the last two digits, but with no leading zero for years less than 10.
yy
The last two digits of the year; that is, 1996 is displayed as “96.”
yyyy
The full year; that is, 1996 is displayed as “1996.”
gg
Period/era string. The function uses the CAL_SERASTRING value associated with the specified locale. This element is ignored if the date to be formatted does not have an associated era or period string.

For example, to get the time display

“11:29:40 PM”

use the following format string:

"hh':'mm':'ss tt"

To get the date display

“Wed, Aug 31 94”

use the following format string:

"ddd',' MMM dd yy"

If you use spaces to separate the elements, they appear in the same location in the output string. The letters must be in uppercase or lowercase as shown, for example, “ss”, not “SS.” To have a character appear in the actual time string, enclose it in single quotes and it appears in the same location as it occupies in the format string.

FormatFlags
Bitmask of flags specifying the format.

The following formats are available for time display:

LOCALE_NOUSEROVERRIDE
If set, the function formats the string using the system default time format for the specified locale. If not set, the function formats the string using any user overrides to the locale’s default time format. This flag cannot be set if bstrFormat is non-NULL.
TIME_NOMINUTESORSECONDS
Do not use minutes or seconds.
TIME_NOSECONDS
Do not use seconds.
TIME_NOTIMEMARKER
Do not use a time marker.
TIME_FORCE24HOURFORMAT
Always use a 24-hour time format.

The following formats are available for date display:

LOCALE_NOUSEROVERRIDE
If set, the function formats the string using the system default date format for the specified locale. If not set, the function formats the string using any user overrides to the locale’s default date format.
DATE_SHORTDATE
Use the short date format. This is the default. Cannot be used with DATE_LONGDATE.
DATE_LONGDATE
Use the long date format. Cannot be used with DATE_SHORTDATE.
DATE_USE_ALT_CALENDAR
Use the alternate calendar, if one exists, to format the date string. If this flag is set, the function uses the default format for that alternate calendar, rather than using any user overrides. The user overrides are used only in the event that there is no default format for the specified alternate calendar.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.


IASClock::put_ClockLabel0

This method specifies a label control to be used as a label field; usually, the label displays time information.

Syntax

HRESULT put_ClockLabel0( Idispatch *pdispLabel );

Parameters

pdispLabel
Pointer to an Auto PC simple (AS) label control to be used as a label field.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.


IASCrossHairs

This interface provides methods to manage a crosshairs control.

Method
Description
IASCrossHairs::get_AxisColor | Gets the color used to draw the x-axis and the y-axis displayed in the cross hairs control.
IASCrossHairs::get_CrossHairBoxColor | Gets the color of the box in the middle of the cross hair.
IASCrossHairs::get_CrossHairColor | Gets the color of both axes of the cross hair itself.
IASCrossHairs::get_CrossHairHilite | Gets the status of the cross hair highlight.
IASCrossHairs::get_CrossHairHiliteColor | Gets the color of the cross hair axes when the axes are highlighted.
IASCrossHairs::get_XMinus | Gets the minimum value of the x-axis.
IASCrossHairs::get_XPlus | Gets the maximum positive value of the x-axis.
IASCrossHairs::get_XVal | Gets the current value of the x-axis.
IASCrossHairs::get_YMinus | Gets the minimum value of the y-axis.
IASCrossHairs::get_YPlus | Gets the maximum positive value of the y-axis.
IASCrossHairs::get_YVal | Gets the current value of the y-axis.
IASCrossHairs::put_AxisColor | Sets the color used to draw the x-axis and the y-axis displayed in the cross hairs control.
IASCrossHairs::put_CrossHairBoxColor | Sets the color of the box in the middle of the cross hair.
IASCrossHairs::put_CrossHairColor | Sets the color of both axes of the cross hair itself.
IASCrossHairs::put_CrossHairHilite | Sets the status of the cross hair highlight.
IASCrossHairs::put_CrossHairHiliteColor | Sets the color of the cross hair axes when the axes are highlighted.
IASCrossHairs::put_XMinus | Sets the minimum value of the x-axis.
IASCrossHairs::put_XPlus | Sets the maximum positive value of the x-axis.
IASCrossHairs::put_XVal | Sets the current value of the x-axis.
IASCrossHairs::put_YMinus | Sets the minimum value of the y-axis.
IASCrossHairs::put_YPlus | Sets the maximum positive value of the y-axis.
IASCrossHairs::put_YVal | Sets the current value of the y-axis.

Remarks

The crosshairs control, which has a programmatic identifier equal to APC_Crosshair, works like an x-y graph. Both x and y lines can be adjusted separately. There is a maximum and minimum x- and y-coordinate and the position of the cross hair is specified by two values that fall in this range.

The target box stays inside the bounding rectangle at the extremes. This means that four pixels must be added to the height and width. To calculate the target box, use the following equations:

Height = 4 + (<number of vertical steps> * <pixels per step>)

Width = 4 + (<number of horizontal steps> * <pixels per step>)

The IASCrossHair interface, which has a global unique identifier (GUID) equal to IID_ASCROSSHAIRS, inherits from IASControl.


IASCrossHairs::get_AxisColor

This method gets the color used to draw the x-axis and the y-axis displayed in the cross hairs control.

Syntax

HRESULT get_AxisColor( OLE_COLOR *pclr );

Parameters

pclr
[out] Pointer to the color of the x-axis and the y-axis displayed in the cross hairs control.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

Use the GetRValue, GetGValue, and GetBValue macros to get the color components of pclr.

See Also

GetRValue, GetGValue, GetBValue


IASCrossHairs::get_CrossHairBoxColor

This method gets the color of the box in the middle of the cross hair.

Syntax

HRESULT get_CrossHairBoxColor( OLE_COLOR *pclr );

Parameters

pclr
[out] Pointer to the color of the box in the middle of the cross hair.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

Use the GetRValue, GetGValue, and GetBValue macros to get the color components of pclr.

See Also

GetRValue, GetGValue, GetBValue


IASCrossHairs::get_CrossHairColor

This method gets color of both axes of the cross hair itself.

Syntax

HRESULT get_CrossHairColor( OLE_COLOR *pclr );

Parameters

pclr
[out] Pointer to the cross hair color.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

Use the GetRValue, GetGValue, and GetBValue macros to get the color components of pclr.

See Also

GetRValue, GetGValue, GetBValue


IASCrossHairs::get_CrossHairHilite

This method gets the status of the cross hair highlight.

Syntax

HRESULT get_CrossHairHilite( BOOL *pfHorz, BOOL *pfVert );

Parameters

pfHorz
Pointer to a Boolean that is set to TRUE if the horizontal axis of the cross hair is highlighted, or to FALSE if the horizontal axis of the cross hair is not highlighted.
pfVert
Pointer to a Boolean that is set to TRUE if the vertical axis of the cross hair is highlighted, or to FALSE if the vertical axis of the cross hair is not highlighted.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASCrossHairs::get_CrossHairHiliteColor

This method gets the color of the cross hair axes when the axes are highlighted.

Syntax

HRESULT get_CrossHairHiliteColor( OLE_COLOR *pclr );

Parameters

pclr
[out] Pointer to the cross hair highlight color.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

Use the GetRValue, GetGValue, and GetBValue macros to get the color components of pclr.

See Also

GetRValue, GetGValue, GetBValue


IASCrossHairs::get_XMinus

This method gets the minimum value of the x-axis.

Syntax

HRESULT get_XMinus( short *pwVal );

Parameters

pwVal
[out] Pointer to the short integer that contains the minimum value of the x-axis.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

The minimum value of the x-axis is usually a negative number.


IASCrossHairs::get_XPlus

This method gets the maximum positive value of the x-axis.

Syntax

HRESULT get_XPlus( short *pwVal );

Parameters

pwVal
[out] Pointer to the maximum positive value of the x-axis.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASCrossHairs::get_XVal

This method gets the current value of the x-axis.

Syntax

HRESULT get_XVal( short *pwVal );

Parameters

pwVal
[out] Pointer to the current value of the x-axis value.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASCrossHairs::get_YMinus

This method gets the minimum value of the y-axis.

Syntax

HRESULT get_YMinus( short *pwVal );

Parameters

pwVal
[out] Pointer to the minimum value of the y-axis.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

The minimum value of the y-axis is usually a negative number.


IASCrossHairs::get_YPlus

This method gets the maximum positive value of the y-axis.

Syntax

HRESULT get_YPlus( short *pwVal );

Parameters

pwVal
[out] Pointer to the maximum positive value of the y-axis.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASCrossHairs::get_YVal

This method gets the current value of the y-axis.

Syntax

HRESULT get_YVal( short *pwVal );

Parameters

pwVal
[out] Pointer to the current value of the y-axis.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASCrossHairs::put_AxisColor

This method sets the color used to draw the x-axis and the y-axis displayed in the cross hairs control.

Syntax

HRESULT put_AxisColor( OLE_COLOR clr );

Parameters

clr
[in] Color of the x-axis and the y-axis displayed in the cross hairs control.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

Use the RGB macro to set the components of clr before passing clr to the method.

See Also

RGB


IASCrossHairs::put_CrossHairBoxColor

This method sets the color of the box in the middle of the cross hair.

Syntax

HRESULT put_CrossHairBoxColor( OLE_COLOR clr );

Parameters

clr
[in] Color of the box in the middle of the cross hair.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

Use the RGB macro to set the components of clr before passing clr to the method.

See Also

RGB


IASCrossHairs::put_CrossHairColor

This method sets the color of both axes of the cross hair itself.

Syntax

HRESULT put_CrossHairColor( OLE_COLOR clr );

Parameters

clr
[in] Color of both axes of the cross hair itself.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

Use the RGB macro to set the components of clr before passing clr to the method.

See Also

RGB


IASCrossHairs::put_CrossHairHilite

This method sets the status of the cross hair highlight.

Syntax

HRESULT put_CrossHairHilite( BOOL fHorz, BOOL fVert );

Parameters

fHorz
Boolean that is set to TRUE to turn on the highlight for the horizontal axis of the cross hair, or FALSE to turn off the highlight for the horizontal axis of the crosshair.
fvert
Boolean that is set to TRUE to turn on the highlight for the vertical axis of the cross hair, or FALSE to turn off the highlight for the vertical axis of the crosshair.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASCrossHairs::put_CrossHairHiliteColor

This method sets the color of the cross hair axes when the axes are highlighted.

Syntax

HRESULT put_CrossHairHiliteColor( OLE_COLOR clr );

Parameters

clr
[in] Color of the cross hair axes when the axes are highlighted.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

Use the RGB macro to set the components of clr before passing clr to the method.

See Also

RGB


IASCrossHairs::put_XMinus

This method sets the minimum value of the x-axis.

Syntax

HRESULT put_XMinus( short wVal );

Parameters

wval
[in] Minimum value of the x-axis.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASCrossHairs::put_XPlus

This method sets the maximum positive value of the x-axis.

Syntax

HRESULT put_XPlus( short wval );

Parameters

wval
[in] Maximum positive value of the x-axis.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASCrossHairs::put_XVal

This method sets the current value of the x-axis.

Syntax

HRESULT put_XVal( short wVal );

Parameters

wval
[in] Current value of the x-axis.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASCrossHairs::put_YMinus

This method sets the minimum value of the y-axis.

Syntax

HRESULT put_YMinus( short wVal );

Parameters

wval
[in] Minimum value of the y-axis.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASCrossHairs::put_YPlus

This method sets the maximum positive value of the y-axis.

Syntax

HRESULT put_YPlus( short wval );

Parameters

wval
[in] Maximum positive value of the y-axis.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASCrossHairs::put_YVal

This method sets the current value of the y-axis.

Syntax

HRESULT put_YVal( short wVal );

Parameters

wval
[in] Current value of the y-axis.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASEditBox

This interface provides the methods to manage an Auto PC simple edit box control.

Method
Description
IASEditBox::Delete | Deletes the character currently selected for editing
IASEditBox::get_Editing | Checks to see if editing is enabled
IASEditBox::get_ItemWidth | Gets the width of an item.
IASEditBox::get_MaxChars | Gets the maximum number of characters allowed in the edit box.
IASEditBox::get_NumChars | Gets the number of characters in the edit box.
IASEditBox::get_ReadOnly | Retrieves whether or not the edit box is read-only.
IASEditBox::get_Selection | Gets the currently selected character.
IASEditBox::get_SelectionIndex | Gets the index of the currently selected character.
IASEditBox::get_Text | Gets a copy of the string currently in the edit box.
IASEditBox::get_TextPrivate | Indicates whether the edit control displays asterisks instead of the characters that the user enters.
IASEditBox::get_TrimRight | Retrieves whether or not white space is trimmed.
IASEditBox::Insert | Inserts a character to the left of the current character.
IASEditBox::put_Editing | Sets whether editing is enabled or not.
IASEditBox::put_ItemWidth | Sets the width of an item.
IASEditBox::put_MaxChars | Sets the maximum number of characters allowed in the edit box.
IASEditBox::put_ReadOnly | Sets whether an edit box is read-only or not.
IASEditBox::put_Selection | Sets the current item to the specified character.
IASEditBox::put_SelectionIndex | Sets the index of the currently selected item.
IASEditBox::put_Text | Replaces the current text string with another.
IASEditBox::put_TextPrivate | Specifies whether the edit control displays asterisks instead of the characters that the user enters.
IASEditBox::put_TrimRight | Sets whether or not trailing white spaces are trimmed.

Remarks

The IASEditBox interface, which has a global unique identifier (GUID) equal to IID_ASEDITBOX, extends the IASCharSpinner interface. An edit control has a programmatic identifier equal to APC_Edit.

Edit mode is entered when the user presses the ENTER key, or the application invokes IASEditBox::put_Editing(TRUE). When editing a particular character, the WM_COMMAND message is fired to the event sink whenever when the edit mode is exited. This happens when the user presses either the ENTER or ESCAPE key. The values of the wParam and lParam parameters that accompany the WM_COMMAND message are described in the following table.

Parameter
Description
LOWORD(wParam) | Control identifier
HIWORD(wParam) | EN_CHANGE
LOWORD(lParam) | Notification flags
HIWORD(lParam) | Form identifier

The low-order word of lParam is one of the following notification flags:

ASFC_EDITNOTIFY_COMMITTED
The user exited edit mode by pressing the ENTER key.
ASFC_EDITNOTIFY_CHANGED
The text has changed since edit mode was entered.

When using an edit control in a power list box, HIWORD(lParam) contains the power list box identifier instead of the form’s identifier.

See Also

IASCharSpinner, HIWORD, LOWORD


IASEditBox::Delete

This method deletes the character currently selected for editing.

Syntax

HRESULT Delete( void );

Return Values

NOERROR indicates success. S_FALSE indicates that there is nothing to delete.


IASEditBox::get_Editing

This method checks to see if editing is enabled.

Syntax

HRESULT get_Editing( BOOL *pfEditing );

Parameters

pfEditing
[out] Pointer to a Boolean that is set to TRUE if editing is enabled, or to FALSE if not.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.


IASEditBox::get_ItemWidth

This method gets the width of an item.

Syntax

HRESULT get_ItemWidth( long *plWidth );

Parameters

plWidth
[out] Pointer to the long integer that contains the width of an item.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

Remarks

When editing, text is drawn in a non-proportional font inside equally sized boxes. The box with focus becomes a spin box, so the user can cycle through the available characters. This method returns the width of a box.


IASEditBox::get_MaxChars

This method gets the maximum number of characters allowed in the edit box.

Syntax

HRESULT get_MaxChars( short *pwcchMax );

Parameters

pwcchMax
[out] Pointer to a short integer that contains the maximum number of characters in the edit box.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.


IASEditBox::get_NumChars

This method gets the number of characters in the edit box.

Syntax

HRESULT get_NumChars( short *pwcch );

Parameters

pwcch
[out] Pointer to the number of characters in the edit box.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.


IASEditBox::get_ReadOnly

This method retrieves whether or not the edit box is read-only.

Syntax

HRESULT get_ReadOnly( BOOL *pfReadOnly );

Parameters

pfReadOnly
[out] Pointer to a Boolean set to TRUE if the edit box is read-only, or FALSE if it is available for editing.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.


IASEditBox::get_Selection

This method gets the currently selected character.

Syntax

HRESULT get_Selection( wchar_t *pch );

Parameters

pch
[out] Pointer to the currently selected character.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid. E_ACCESSDENIED indicates that editing mode is not enabled.


IASEditBox::get_SelectionIndex

This method gets the index of the currently selected character.

Syntax

HRESULT get_SelectionIndex( short *pwich );

Parameters

pwich
[out] Pointer to the index of the character being edited.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid. E_ACCESSDENIED indicates that editing mode is not enabled.


IASEditBox::get_Text

This method gets a copy of the string currently in the edit box.

Syntax

HRESULT get_Text( BSTR *pbstr );

Parameters

pbstr
[out] Pointer to the Unicode text string currently in the edit box.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.


IASEditBox::get_TextPrivate

This method indicates whether the edit control displays asterisks instead of the characters that the user enters.

Syntax

HRESULT get_TextPrivate( BOOL * pfTextPrivate );

Parameters

pfTextPrivate
Pointer to a Boolean that is set to TRUE to specify that the edit control display asterisks instead of the actual characters that the user enters, or to FALSE to display the actual characters that the user enters.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.


IASEditBox::get_TrimRight

The method retrieves whether or not trailing white spaces are trimmed.

Syntax

HRESULT get_TrimRight( BOOL *pfTrimRight );

Parameters

pfTrimRight
[out] Pointer to a Boolean that is set to TRUE if the white spaces are trimmed, or to FALSE if not.

Return Values

An appropriate HRESULT value is returned.

Remarks

The pfTrimRight parameter is set to TRUE by default, which indicates that trailing white spaces are trimmed from the right side of a line of text in the edit box.


IASEditBox::Insert

This method inserts a character to the left of the current character.

Syntax

HRESULT Insert( short ch );

Parameters

ch
[in] Character to be inserted.

Return Values

S_FALSE indicates that the maximum number of characters has been reached. E_ACCESSDENIED indicates that editing mode is not enabled.


IASEditBox::put_Editing

This method sets whether editing is enabled or not.

Syntax

HRESULT put_Editing( BOOL fEditing );

Parameters

fEditing
[in] Boolean that is set to TRUE if editing is enabled, or to FALSE if not.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.


IASEditBox::put_ItemWidth

This method sets the width of an item.

Syntax

HRESULT put_ItemWidth( long lWidth );

Parameters

lWidth
[in] Long integer that contains the width of the item.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that lWidth is less than 0.

Remarks

When editing, text is drawn in a non-proportional font inside equally sized boxes. The box with focus becomes a spin box, so the user can cycle through the available characters.


IASEditBox::put_MaxChars

This method sets the maximum number of characters allowed in the edit box.

Syntax

HRESULT put_MaxChars( short wcchMax );

Parameters

wcchMax
[in] Short integer that contains the maximum number of characters in the edit box.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument exceeds the system-defined maximum for edit boxes.


IASEditBox::put_ReadOnly

This method sets whether an edit box is read-only or not.

Syntax

HRESULT put_ReadOnly( BOOL fReadOnly );

Parameters

fReadOnly
[in] Boolean that is set to TRUE to define the edit box as read-only, or FALSE to make it available for editing.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASEditBox::put_Selection

This method sets the current item to the specified character.

Syntax

HRESULT put_Selection( wchar_t ch );

Parameters

ch
[in] Character to be set.

Return Values

NOERROR indicated success. E_ACCESSDENIED indicates that editing mode is not enabled.

Remarks

If ch is 0, this method sets the current item equal to the first character in the character set.


IASEditBox::put_SelectionIndex

This method sets the index of the currently selected item.

Syntax

HRESULT put_SelectionIndex( short wich );

Parameters

wich
[in] Index to be set for the character being edited.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid. E_ACCESSDENIED indicates that editing mode is not enabled.


IASEditBox::put_Text

This method replaces the current text string with another.

Syntax

HRESULT put_Text( BSTR bstr );

Parameters

bstr
[in] Unicode string.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.


IASEditBox::put_TextPrivate

This method specifies whether the edit control displays asterisks instead of the characters that the user enters.

Syntax

HRESULT put_TextPrivate( BOOL fTextPrivate );

Parameters

fTextPrivate
Boolean that is set to TRUE to specify that the edit control display asterisks instead of the actual characters that the user enters, or to FALSE to display the actual characters that the user enters.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

Remarks

Use this method to protect the privacy of a user when the user enters text in a password field in an edit box.


IASEditBox::put_TrimRight

This method sets whether or not trailing white spaces are trimmed.

Syntax

HRESULT put_TrimRight( BOOL fTrimRight );

Parameters

fTrimRight
[in] Boolean that is set to TRUE if the white spaces are to be trimmed, or to FALSE if not.

Return Values

S_FALSE indicates there is nothing more to delete.

Remarks

This property is set to TRUE by default.


IASImageMenu

This interface provides methods to manage a menu that uses images rather than text strings to display its options.

Method
Description
IASImageMenu::Add | Adds an item and its associated image to the image menu.
IASImageMenu::get_CenteredFocus | Retrieves whether or not centered focus is enabled.
IASImageMenu::get_Count | Gets the number of items in the menu.
IASImageMenu::get_FocusColor | Gets the color assigned to an image that has the focus.
IASImageMenu::get_FocusIndex | Gets the index of the item with the focus.
IASImageMenu::get_Horizontal | Retrieves whether the menu scrolls horizontally or vertically.
IASImageMenu::get_ImageHeight | Gets the height of an image.
IASImageMenu::get_ImageWidth | Gets the width of an image.
IASImageMenu::get_ItemHeight | Gets the height of an item.
IASImageMenu::get_ItemWidth | Gets the width of an item.
IASImageMenu::get_MenuLabel | Gets the Auto PC label control associated with the image menu.
IASImageMenu::get_ID | Gets the identifier of a menu item, specified by its index.
IASImageMenu::get_Image | Gets the image associated with a menu item, specified by its menu index.
IASImageMenu::get_MenuWrap | Retrieves whether or not the menu should wrap at the end of a line of text.
IASImageMenu::get_NonFocusImageColor | Gets the color assigned to a non-focused image.
IASImageMenu::get_Overlay | Gets an image to display over a focus item or the entire image menu.
IASImageMenu::get_OverlayOffset | Gets pointers to the position of the overlay.
IASImageMenu::get_String | Gets the string associated with a menu item.
IASImageMenu::InsertAt | Inserts an item at a specified index.
IASImageMenu::put_CenteredFocus | Sets whether or not centered focus is enabled.
IASImageMenu::put_FocusColor | Sets the color assigned to an image that has the focus.
IASImageMenu::put_FocusIndex | Gives the focus to the item with the specified index
IASImageMenu::put_Horizontal | Sets scrolling to horizontal or vertical.
IASImageMenu::put_ImageHeight | Sets the height of an image.
IASImageMenu::put_ImageWidth | Sets the width of an image.
IASImageMenu::put_ItemHeight | Sets the height of an item.
IASImageMenu::put_ItemWidth | Sets the width of an item.
IASImageMenu::put_MenuLabel | Specifies an Auto PC label control to be associated with the image menu.
IASImageMenu::put_MenuWrap | Sets whether or not a menu should wrap.
IASImageMenu::put_NonFocusImageColor | Sets the color for a non-focused image.
IASImageMenu::put_Overlay | Sets an image to display over a focus item or the entire image menu.
IASImageMenu::put_OverlayOffset | Sets the position of the overlay.
IASImageMenu::RemoveAtIndex | Removes an item specified by its index.
IASImageMenu::RemoveByID | Removes an item specified by its identifier.
IASImageMenu::put_ID | Sets the identifier of a menu item.
IASImageMenu::put_Image | Replaces one item image with another.
IASImageMenu::put_String | Assigns a string to an item.

Remarks

The IASImageMenu interface, which has a global unique identifier (GUID) equal to IID_ASIMAGEMENU, extends the IASControl interface.

When an image item is selected, a WM_COMMAND event is sent to the event sink. The high-order word contains the control’s identifier and the low-order word contains the item’s identifier. The index of the menu item is sent in the lParam. When the focus changes from one item to the next, a WM_COMMAND message is fired to the event sink. The high-order word of wParam contains LBN_SELCHANGE, and the low-order word contains the control’s identifier.

See Also

IASControl, HIWORD, LOWORD


IASImageMenu::Add

This method adds an item and its associated image to the image menu.

Syntax

HRESULT Add( OLE_HANDLE hImage, OLE_HANDLE hImageMask, BSTR bstr, short wID, BOOL fBitmap );

Parameters

hImage
[in] Handle to the image to be added to the menu.
hImageMask
[in] Handle to the image mask. Masks are not needed for icons.
bstr
[in] Unicode string to be associated with the image.
wID
[in] User-defined item identifier.
fBitmap
[in] Boolean that is set to TRUE if the image is a bitmap, or to FALSE if it is an icon.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid. E_OUTOFMEMORY indicates that the device is out of memory.

Remarks

Images may be either bitmaps or icons. If the images are bitmaps, a mask must also be supplied.


IASImageMenu::get_CenteredFocus

This method retrieves whether or not centered focus is enabled.

Syntax

HRESULT get_CenteredFocus ( BOOL *pfFocus );

Parameters

pfFocus
[out] Pointer to a Boolean that is set to TRUE if centered focus is enabled, or to FALSE if not.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.


IASImageMenu::get_Count

This method gets the number of items in the menu.

Syntax

HRESULT get_Count( long *pcItems );

Parameters

pcItems
[out] Pointer to the number of items.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.


IASImageMenu::get_FocusColor

This method gets the color assigned to an image that has the focus.

Syntax

HRESULT get_FocusColor ( OLE_COLOR *pclr );

Parameters

pclr
Pointer to the color assigned to an image with focus.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

Remarks

Use the GetRValue, GetGValue, and GetBValue macros to get the color components of pclr.

See Also

GetRValue, GetGValue, GetBValue


IASImageMenu::get_FocusIndex

This method gets the index of the item with the focus.

Syntax

HRESULT get_FocusIndex( long *pIndex );

Parameters

pIndex
[out] Pointer to the index of the item that has focus.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.


IASImageMenu::get_Horizontal

This method retrieves whether the menu scrolls horizontally or vertically.

Syntax

HRESULT get_Horizontal( BOOL *pfHorizontal );

Parameters

pfHorizontal
[out] Pointer to a Boolean that is set to TRUE for horizontal scrolling, or to FALSE for vertical scrolling.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.


IASImageMenu::get_ImageHeight

This method gets the height of an image.

Syntax

HRESULT get_ImageHeight( long *plHeight );

Parameters

plHeight
[out] Pointer to the long integer that contains the height of an image.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

Remarks

All images in the menu must be the same height. Images are centered inside the box that constitutes the menu item.


IASImageMenu::get_ImageWidth

This method gets the width of an image.

Syntax

HRESULT get_ImageWidth( long *plWidth );

Parameters

plWidth
[out] Pointer to the long integer that contains the width of an image.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

Remarks

All images in a menu must have the same width. Images are centered inside the box that constitutes the menu item.


IASImageMenu::get_ItemHeight

This method gets the height of an item.

Syntax

HRESULT get_ItemHeight( long *plHeight );

Parameters

plHeight
[out] Pointer to the long integer that contains the height of an item.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

Remarks

All items must be the same height. Images are centered inside the box that constitutes the menu item.


IASImageMenu::get_ItemWidth

This method gets the width of an item.

Syntax

HRESULT get_ItemWidth( long *plWidth );

Parameters

plWidth
[out] Pointer to the long integer that contains the width of an item.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

Remarks

All items must be the same size. Images are centered inside the box that constitutes the menu item.


IASImageMenu::get_MenuLabel

This method gets the Auto PC label control associated with the image menu.

Syntax

HRESULT get_MenuLabel( IDispatch **ppdispLabel );

Parameters

ppdispLabel
[out] Pointer to a pointer to the label control that displays the menu’s label.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

Remarks

The label for the menu is displayed in a separate AS label control, which may be placed anywhere on the faceplate screen.

See Also

IASLabel


IASImageMenu::get_ID

This method gets the identifier of a menu item, specified by its index.

Syntax

HRESULT get_ID( long index short *pwID );

Parameters

index
[in] Index of the item.
pwID
[out] Pointer to the user-defined item identifier.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

Remarks

The index is based on the order in which the menu items are displayed. The identifier is assigned by the user when the item is added to the menu.

See Also

IASImageMenu::get_FocusIndex


IASImageMenu::get_Image

This method gets the image associated with a menu item, specified by its menu index.

Syntax

HRESULT get_Image( long index OLE_HANDLE *phImage OLE_HANDLE *phImageMask BOOL *pfBitmap );

Parameters

index
[in] Index of the item associated with the image.
phImage
[out] Pointer to a handle to an image.
phImageMask
[out] Pointer to the handle to the image mask. Masks are not needed for icons.
pfBitmap
[out] Pointer to a Boolean that is set to TRUE if the image is a bitmap, or to FALSE if it is an icon.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

Remarks

Images may be either bitmaps or icons. If the images are bitmaps, a mask must also be supplied.

See Also

IASImageMenu::get_FocusIndex


IASImageMenu::get_MenuWrap

This method retrieves whether or not the menu should wrap at the end of a line of text.

Syntax

HRESULT get_MenuWrap( BOOL *pfWrap );

Parameters

pfWrap
[out] Pointer to a Boolean that is set to TRUE if the menu should wrap, or to FALSE if the menu should not wrap.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

See Also

IASImageMenu::put_MenuWrap


IASImageMenu::get_NonFocusImageColor

This method gets the color assigned to a non-focused image.

Syntax

HRESULT get_NonFocusImageColor( OLE_COLOR *pclr, BOOL *pfSet );

Parameters

pclr
Pointer to the icon color.
pfSet
Pointer to a Boolean that is set to TRUE if the image does not have the focus, and to FALSE if the image has the focus.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

Remarks

This method retrieves single color version of non-focused images.

Use the GetRValue, GetGValue, and GetBValue macros to get the color components of pclr.

See Also

IASImageMenu::put_NonFocusImageColor, GetRValue, GetGValue, GetBValue


IASImageMenu::get_Overlay

This method gets an image to display over a focus item or the entire image menu.

Syntax

HRESULT get_Overlay( BOOL fFocus, OLE_HANDLE *phImage, OLE_HANDLE *phImageMask, BOOL *pfBitmap );

Parameters

fFocus
Boolean that is set to TRUE if the image has the focus, or to FALSE if the image does not have the focus.
phImage
[out] Pointer to the handle to the image bitmap.
phImageMask
[out] Pointer to the handle to the image mask. Masks are not needed for icons.
pfBitmap
[out] Pointer to a Boolean that is set to TRUE if the image is a bitmap, or to FALSE if it is an icon.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

See Also

IASImageMenu::put_Overlay


IASImageMenu::get_OverlayOffset

This method gets pointers to the position of the overlay.

Syntax

HRESULT get_OverlayOffset( BOOL fFocus, long *pleft, long *ptop );

Parameters

fFocus
Boolean that is set to TRUE if the image has the focus, or to false if the image does not have the focus.
pleft
[out] Pointer to the x-coordinate of the left edge of the overlay.
ptop
[out] Pointer to the y-coordinate of the upper edge of the overlay.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

See Also

IASImageMenu::put_OverlayOffset


IASImageMenu::get_String

This method gets the string associated with a menu item.

Syntax

HRESULT get_String( long index, BSTR *pbstr );

Parameters

index
[in] Index of the item associated with the image.
pbstr
[out] Pointer to the Unicode string.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

Remarks

The string associated with an image can be used to display text in the Auto PC label control associated with the image menu.


IASImageMenu::InsertAt

This method inserts an item at a specified index.

Syntax

HRESULT InsertAt( long index, OLE_HANDLE hImage, OLE_HANDLE hImageMask, BSTR bstr, short wID, BOOL fBitmap );

Parameters

index
[in] Index where the item is to be inserted.
hImage
[in] Handle to the image to be added to the menu.
hImageMask
[in] Handle to the image mask. Masks are not needed for icons.
bstr
[in] Unicode string to be associated with the image.
wID
[in] User-defined item identifier.
fBitmap
[in] Boolean that is set to TRUE if the image is a bitmap, or to FALSE if it is an icon.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid. E_OUTOFMEMORY indicates that the device is out of memory.

Remarks

Images may be either bitmaps or icons. If the images are bitmaps, a mask must also be supplied.


IASImageMenu::put_CenteredFocus

This method sets whether or not centered focus is enabled.

Syntax

HRESULT put_CenteredFocus ( BOOL fFocus );

Parameters

fFocus
[in] Boolean that is set to TRUE if centered focus is to be enabled, or to FALSE if not.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.


IASImageMenu::put_FocusColor

This method sets the color assigned to an image that has the focus.

Syntax

HRESULT put_FocusColor ( OLE_COLOR clr );

Parameters

clr
[in] Color for the focused image.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

Remarks

Use the RGB macro to set the components of clr before passing clr to the method.

See Also

RGB


IASImageMenu::put_FocusIndex

This method gives the focus to the item with the specified index.

Syntax

HRESULT put_FocusIndex( long lIndex );

Parameters

lIndex
[in] Long integer that contains the index of the item to receive focus.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.


IASImageMenu::put_Horizontal

This method sets scrolling to horizontal or vertical.

Syntax

HRESULT put_Horizontal( BOOL fHorizontal );

Parameters

fHorizontal
[in] Boolean that is set to TRUE for horizontal scrolling, or to FALSE for vertical scrolling

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASImageMenu::put_ImageHeight

This method sets the height of an image.

Syntax

HRESULT put_ImageHeight( long lHeight );

Parameters

lHeight
[in] Long integer that contains the height of an image.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

Remarks

All images in the menu must be the same height. Images are centered inside the box that constitutes the menu item.

See Also

IASImageMenu::get_ImageHeight


IASImageMenu::put_ImageWidth

This method sets the width of an image.

Syntax

HRESULT put_ImageWidth( long lWidth );

Parameters

lWidth
[in] Long integer that contains the width of an image.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

Remarks

All images in a menu must have the same width. Images are centered inside the box that constitutes the menu item.


IASImageMenu::put_ItemHeight

This method sets the height of an item.

Syntax

HRESULT put_ItemHeight( long lHeight );

Parameters

lHeight
[in] Long integer that contains the height of an item.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

Remarks

All items must be the same height. Images are centered inside the box that constitutes the menu item.

See Also

IASImageMenu::get_ItemHeight


IASImageMenu::put_ItemWidth

This method sets the width of an item.

Syntax

HRESULT put_ItemWidth( long lWidth );

Parameters

lWidth
[in] Long integer that contains the width of an item.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

Remarks

All items must have the same width. Images are centered inside the box that constitutes the menu item.

See Also

IASImageMenu::get_ItemWidth


IASImageMenu::put_MenuLabel

This method specifies an Auto PC label control to be associated with the image menu.

Syntax

HRESULT put_MenuLabel( IDispatch *pdispLabel );

Parameters

pdispLabel
[in] Pointer to an AS label control to be used as the label field.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

Remarks

The label is displayed in a separate AS label control, which may be placed anywhere on the faceplate screen. The control must have been created prior to the invocation of this method.

See Also

IASLabel


IASImageMenu::put_MenuWrap

This method sets whether or not the menu should wrap.

Syntax

HRESULT put_MenuWrap( BOOL fWrap );

Parameters

fWrap
[in] Boolean that is set to TRUE if menu should wrap, or to FALSE if menu should not wrap.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

See Also

IASImageMenu::get_MenuWrap


IASImageMenu::put_NonFocusImageColor

This method sets the color for an non-focused image.

Syntax

HRESULT put_NonFocusImageColor( OLE_COLOR clr, BOOL fSet );

Parameters

clr
[in] Color for the non-focused image.
fSet
Boolean that is set to TRUE if the image does not have the focus, or to FALSE is the image has the focus.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

Remarks

This method produces a single color version of an image for non-focused applications.

Use the RGB macro to set the components of clr before passing clr to the method.

See Also

RGB


IASImageMenu::put_Overlay

This method sets an image to display over a focus item or the entire image menu.

Syntax

HRESULT put_Overlay( BOOL fFocus, OLE_HANDLE hImage, OLE_HANDLE hImageMask, BOOL fBitmap );

Parameters

fFocus
Boolean that is set to TRUE if the image has the focus, and to FALSE if the image does not have the focus.
hImage
[in] Handle to the image bitmap.
hImageMask
[in] Handle to the image mask. Masks are not needed for icons.
fBitmap
[in] Boolean that is set to TRUE if the image is a bitmap, or to FALSE if it is an icon.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

See Also

IASImageMenu::get_Overlay


IASImageMenu::put_OverlayOffset

This method sets the position of the overlay.

Syntax

HRESULT put_OverlayOffset( BOOL fFocus, long left, long top );

Parameters

fFocus
Boolean that is set to TRUE if image has focus, or to FALSE if image does not have focus.
left
[in] Specifies the x-coordinate (left edge) of the overlay.
top
[in] Specifies the y-coordinate (upper edge) of the overlay.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

See Also

IASImageMenu::get_OverlayOffset


IASImageMenu::RemoveAtIndex

This method removes an item specified by its index.

Syntax

HRESULT RemoveAtIndex( long index );

Parameters

index
[in] Index of the item to be removed.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.


IASImageMenu::RemoveByID

This method removes an item specified by its identifier.

Syntax

HRESULT RemoveByID( short wID );

Parameters

wID
[in] User-defined image identifier.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.


IASImageMenu::put_ID

This method sets the identifier for a menu item.

Syntax

HRESULT put_ID( long index, short wID );

Parameters

index
[in] Index of the item.
wID
[in] User-defined item identifier.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.


IASImageMenu::put_Image

This method replaces one item image with another.

Syntax

HRESULT put_Image( long index, OLE_HANDLE hImage, OLE_HANDLE hImageMask, BOOL fBitmap );

Parameters

index
[in] Index of the item whose image is replaced.
hImage
[in] Handle to the new image.
hImageMask
[in] Handle to the image mask. Masks are not needed for icons.
fBitmap
[in] Boolean that is set to TRUE if the image is a bitmap, or to FALSE if it is an icon.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid. E_OUTOFMEMORY indicates that the device is out of memory.

Remarks

Images may be either bitmaps or icons. If the images are bitmaps, a mask must also be supplied.


IASImageMenu::put_String

This method assigns a string to an item.

Syntax

HRESULT put_String( long index, BSTR bstr );

Parameters

index
[in] Index of the item.
bstr
[in] Unicode string to be assigned.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

The string associated with an image can be used to display text in the Auto PC label control associated with the image menu.

See Also

IASLabel


IASLabel

This interface provides methods used to assign an image to an Auto PC simple (AS) label control.

Method
Description
IASLabel::get_CaptionAlign | Gets the caption alignment.
IASLabel::get_Format | Retrieves the text format of the label.
IASLabel::get_Image | Retrieves a handle to the control image and image mask, allowing a bitmap to be drawn on the label control.
IASLabel::get_ImageAlignH | Gets the horizontal alignment of the image.
IASLabel::get_ImageAlignV | Gets the vertical alignment of the image.
IASLabel::put_CaptionAlign | Sets the caption alignment.
IASLabel::put_Format | Changes the text format of the label.
IASLabel::put_ImageAlignH | Sets the horizontal alignment of the image.
IASLabel::put_ImageAlignV | Sets the vertical alignment of the image.
IASLabel::put_Image | Sets a new image and repaints the label.

Remarks

The IASLabel interface, which has a global unique identifier equal to IID ASLABEL, extends the IASControl interface. The label control has a programmatic identifier equal to APC_Label.


IASLabel::get_CaptionAlign

This method gets the caption alignment.

Syntax

HRESULT get_CaptionAlign ( short*pwAlign );

Parameters

pwAlign
[out] Pointer to the unsigned 16-bit value that contains alignment information. It is one of the following values:
ASFC_CAPTION_ALIGNNONE
Caption extends from the top of the control to the bottom.
ASFC_CAPTION_ALIGNTOP
Caption aligns with the top of the image.
ASFC_CAPTION_ALIGNBOTTOM
Caption aligns with the bottom of the image.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

See Also

IASLabel::get_CaptionAlign


IASLabel::get_Format

This method retrieves the text format of the label.

Syntax

HRESULT get_Format( UINT *pwFormat );

Parameters

pwFormat
[out] Pointer to the unsigned 16-bit value that contains text formatting. It is one of the following values:
ASFC_ALIGN_BOTTOM
When drawing text, align it with the bottom of the control.
ASFC_ALIGN_CENTER
When drawing text, center it.
ASFC_ALIGN_LEFT
When drawing text, align it to the left of the control.
ASFC_ALIGN_NOCLIP
Draw text without clipping it.
ASFC_ALIGN_RIGHT
When drawing text, align it to the right of the control.
ASFC_ALIGN_SINGLELINE
Draw text in a single line.
ASFC_ALIGN_TOP
When drawing text, align it with the top of the control.
ASFC_ALIGN_VCENTER
When drawing text, center it vertically.
ASFC_ALIGN_WORDBREAK
Draw text with word breaks.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

Remarks

By default, text wraps to the next line on a per-word basis. All carriage returns/line feeds (CR/LFs) are acknowledged. When the text reaches the edge of the region, it is clipped, with two periods appended to indicate additional undisplayed text, for example, “You have reached the en..” If the ASFC_ALIGN_NOCLIP flag is set, text still wraps, but it is clipped at the edge of the control without the periods.


IASLabel::get_Image

This method retrieves a handle to the control image and image mask, allowing a bitmap to be drawn on the label control.

Syntax

HRESULT get_Image( OLE_HANDLE *phImage OLE_HANDLE *phImageMask );

Parameters

phImage
[out] Pointer to the handle to a bitmap resource, cast to an OLE_HANDLE type.
phImageMask
[out] Pointer to the handle to the image mask that defines the transparent parts of the image.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

Remarks

This method allows a bitmap to be drawn on the label control. The image mask is an optional monochrome bitmap that defines the transparent areas in the bitmap to be displayed.

Because of Automation, bitmapped image pointers are passed as OLE_HANDLE types. You can cast a handle to and from a bitmap.


IASLabel::get_ImageAlignH

This method gets the horizontal alignment of the image.

Syntax

HRESULT get_ImageAlignH( short*pwAlign );

Parameters

pwAlign
[out] Pointer to the unsigned 16-bit value that contains alignment information. It is one of the following values:
ASFC_IMAGE_HCENTER
Image is centered.
ASFC_IMAGE_LEFT
Image is left-aligned.
ASFC_IMAGE_RIGHT
Image is right-aligned.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.


IASLabel::get_ImageAlignV

This method gets the vertical alignment of the image.

Syntax

HRESULT get_ImageAlignV( short *pwAlign );

Parameters

pwAlign
[out] Pointer to the unsigned 16-bit value that contains alignment information. It is one of the following values:
ASFC_IMAGE_VCENTER
Image is centered vertically.
ASFC_IMAGE_TOP
Image is aligned with the top.
ASFC_IMAGE_BOTTOM
Image is aligned with the bottom.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.


IASLabel::put_CaptionAlign

This method sets the caption alignment.

Syntax

HRESULT put_CaptionAlign( short wAlign );

Parameters

wAlign
[in] Unsigned 16-bit value that contains alignment information. It is one of the following values:
ASFC_CAPTION_ALIGNNONE
Caption extends from the top of the control to the bottom.
ASFC_CAPTION_ALIGNTOP
Caption aligns with the top of the image.
ASFC_CAPTION_ALIGNBOTTOM
Caption aligns with the bottom of the image.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.


IASLabel::put_Format

This method changes the text format of the label.

Syntax

HRESULT put_Format ( UINT wFormat );

Parameters

wFormat
[in] Unsigned 16-bit value that contains text formatting. It uses the same set of styles available with the Windows CE DrawText function, which include the following values:
ASFC_ALIGN_BOTTOM
When drawing text, align it with the bottom of the control.
ASFC_ALIGN_CENTER
When drawing text, center it.
ASFC_ALIGN_LEFT
When drawing text, align it to the left of the control.
ASFC_ALIGN_NOCLIP
Draw text without clipping it.
ASFC_ALIGN_RIGHT
When drawing text, align it to the right of the control.
ASFC_ALIGN_SINGLELINE
Draw text in a single line.
ASFC_ALIGN_TOP
When drawing text, align it with the top of the control.
ASFC_ALIGN_VCENTER
When drawing text, center it vertically.
ASFC_ALIGN_WORDBREAK
Draw text with word breaks.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

See Also

DrawText


IASLabel::put_ImageAlignH

This method sets the horizontal alignment of the image.

Syntax

HRESULT put_ImageAlignH( short wAlign );

Parameters

wAlign
[in] Unsigned 16-bit value that contains alignment information. It is one of the following values:
ASFC_IMAGE_HCENTER
Image is centered.
ASFC_IMAGE_LEFT
Image is left-aligned.
ASFC_IMAGE_RIGHT
Image is right-aligned.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.


IASLabel::put_ImageAlignV

This method sets the vertical alignment of the image.

Syntax

HRESULT get_ImageAlignV( short wAlign );

Parameters

wAlign
[in] Unsigned 16-bit value that contains alignment information. It is one of the following values:
ASFC_IMAGE_VCENTER
Image is centered vertically.
ASFC_IMAGE_TOP
Image is aligned with the top.
ASFC_IMAGE_BOTTOM
Image is aligned with the bottom.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.


IASLabel::put_Image

This method allows a bitmapped imaged to be drawn on the control.

Syntax

HRESULT put_Image ( OLE_HANDLE hImage, OLE_HANDLE hImageMask, long dx, long dy, long dxWidth, long dyHeight );

Parameters

hImage
[in] Handle to a bitmap resource, cast to an OLE_HANDLE type.
hImageMask
[in] Handle to a bitmap mask resource, cast to an OLE_HANDLE type.
dx
[in] Specifies the x-coordinate of the left edge of the image.
dy
[in] Specifies the y-coordinate of the upper edge of the image.
dxWidth
[in] Specifies the width of the image.
dyHeight
[in] Specifies the height of the image.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that the argument is invalid.

Remarks

The image mask is an optional monochrome bitmap that specifies which areas of the image are transparent. It must be the same size as the image referred to by hImage. For every black pixel in the mask, the corresponding pixel from hImage is drawn. White pixels are not drawn, and define transparent areas in the image. This function is similar in operation to BitBlt.

Because of Automation, bitmapped image pointers are passed as OLE_HANDLE types. You can cast a handle to and from a bitmap.

This method automatically repaints the control with the new bitmap.

The following code example shows how to call put_Image:

hBmp = LoadBitmapResource(hInst, MAKEINTRESOURCE(IDB_HOUSE));
hBmpMask = LoadBitmapResource(hInst, MAKEINTRESOURCE(IDB_HOUSEMASK));

pLabel -> put_Image((OLE_HANDLE) hBmp, (OLE_HANDLE) hBmpMask, 0, 0, 16, 16);


IASPlayList

This interface provides the methods to manage a PlayList object.

Method
Description
IASPlayList::get_TrackActive | Gets the active track.
IASPlayList::put_TrackActive | Sets the active track.
IASPlayList::get_ActiveBackColor | Gets the active background color.
IASPlayList::get_ActiveForeColor | Gets the active foreground color.
IASPlayList::get_BorderColor | Gets the border color of the play list grid lines
IASPlayList::get_CurrentTrack | Gets the number of the current track.
IASPlayList::get_HiliteBorderColor | Gets the highlight border color to be drawn around the current selection.
IASPlayList::get_InactiveBackColor | Gets the inactive background color.
IASPlayList::get_InactiveForeColor | Gets the inactive foreground color.
IASPlayList::get_ItemHeight | Gets the item height, which is the height of an individual box in a play list.
IASPlayList::get_ItemWidth | Gets the item width, which is the width of an individual box in a play list.
IASPlayList::get_NumTracks | Gets the number of tracks in the play list.
IASPlayList_put_ActiveBackColor | Sets the active background color.
IASPlayList_put_ActiveForeColor | Sets the active foreground color.
IASPlayList::put_BorderColor | Sets the border color of the play list grid lines.
IASPlayList::put_CurrentTrack | Sets the number of the current track.
IASPlayList::put_HiliteBorderColor | Sets the highlight border color to be drawn around the current selection.
IASPlayList::put_InactiveBackColor | Sets the inactive background color.
IASPlayList::put_InactiveForeColor | Sets the inactive foreground color.
IASPlayList::put_ItemHeight | Sets the item height, which is the height of an individual box in a play list.
IASPlayList::put_ItemWidth | Sets the item width, which is the width of an individual box in a play list.
IASPlayList::put_NumTracks | Sets the number of tracks in the play list.
IASPlayList::Reset | Resets the play list and turns off all active tracks.

Remarks

The IASPlayList interface, which has a global unique identifier equal to IID_ASPLAYLIST, extends the IASControl interface. The play list object has a programmatic identifier equal to APC_PlayList.


IASPlayList::get_TrackActive

This method gets the active track.

Syntax

HRESULT get_TrackActive( unsigned char biTrack );

Parameters

biTrack
Unsigned character that indicates the active track.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

The index of tracks in the play list begins at 1. If the index of the active track is equal to 0, the play list does not indicate an active track.

See Also

IASPlayList::put_TrackActive


IASPlayList::put_TrackActive

This method sets the active track.

Syntax

HRESULT put_TrackActive( unsigned char biTrack, BOOL fActive );

Parameters

biTrack
Unsigned character that indicates the active track.
fActive
Boolean that is set to TRUE for the active track, or to FALSE for a non-active track.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

The index of tracks in the play list begins at 1. If you set the index of the active track is equal to 0, the play list does not indicate an active track.

See Also

IASPlayList::get_TrackActive


IASPlayList::get_ActiveBackColor

This method gets the active background color.

Syntax

HRESULT get_ActiveBackColor( OLE_COLOR *pclr );

Parameters

pclr
Pointer to the active background color.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

Use the GetRValue, GetGValue, and GetBValue macros to get the color components of pclr.

See Also

IASPlayList::put_ActiveBackColor, GetRValue, GetGValue, GetBValue


IASPlayList::get_ActiveForeColor

This method gets the active foreground color.

Syntax

HRESULT get_ActiveForeColor( OLE_COLOR *pclr );

Parameters

pclr
Pointer to the active foreground color.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

Use the GetRValue, GetGValue, and GetBValue macros to get the color components of pclr.

See Also

IASPlayList::put_ActiveForeColor, GetRValue, GetGValue, GetBValue


IASPlayList::get_BorderColor

This method gets the border color of the play list grid lines.

Syntax

HRESULT get_BorderColor( OLE_COLOR *pclr );

Parameters

pclr
Pointer to the border color.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

Use the GetRValue, GetGValue, and GetBValue macros to get the color components of pclr.

See Also

IASPlayList::put_BorderColor, GetRValue, GetGValue, GetBValue


IASPlayList::get_CurrentTrack

This method gets the number of the current track.

Syntax

HRESULT get_CurrentTrack( unsigned char *pbcTrack );

Parameters

pbcTrack
Pointer to the current track number.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

The index of tracks in the play list begins at 1. If the index of the current track is equal to 0, the play list does not indicate a current track.

See Also

IASPlayList::put_CurrentTrack


IASPlayList::get_HiliteBorderColor

This method gets the highlight border color to be drawn around the current selection.

Syntax

HRESULT get_HiliteBorderColor( OLE_COLOR *pclr );

Parameters

pclr
Pointer to the highlight border color.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

Use the GetRValue, GetGValue, and GetBValue macros to get the color components of pclr.

See Also

IASPlayList::put_HiliteBorderColor, GetRValue, GetGValue, GetBValue


IASPlayList::get_InactiveBackColor

This method gets the inactive background color.

Syntax

HRESULT get_InactiveBackColor( OLE_COLOR *pclr );

Parameters

pclr
Pointer to the inactive background color.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

Use the GetRValue, GetGValue, and GetBValue macros to get the color components of pclr.

See Also

IASPlayList::put_InactiveBackColor, GetRValue, GetGValue, GetBValue


IASPlayList::get_InactiveForeColor

This method gets the inactive foreground color.

Syntax

HRESULT get_InactiveForeColor( OLE_COLOR *pclr );

Parameters

pclr
Pointer to the inactive foreground color.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

Use the GetRValue, GetGValue, and GetBValue macros to get the color components of pclr.

See Also

IASPlayList::put_InactiveForeColor, GetRValue, GetGValue, GetBValue


IASPlayList::get_ItemHeight

This method gets the item height, which is the height of an individual box in a play list.

Syntax

HRESULT get_ItemHeight( long *plHeight );

Parameters

plHeight
Pointer to a long integer that contains the height of the item.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

See Also

IASPlayList::put_ItemHeight


IASPlayList::get_ItemWidth

This method gets the item width, which is the width of an individual box in a play list.

Syntax

HRESULT get_ItemWidth( long *plWidth );

Parameters

plWidth
Pointer to a long integer that contains the width of the item.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

See Also

IASPlayList::put_ItemWidth


IASPlayList::get_NumTracks

This method gets the number of tracks in the play list.

Syntax

HRESULT get_NumTracks( unsigned char *pbcTracks );

Parameters

pbcTracks
Pointer to the number of tracks.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

The index of tracks in the play list begins at 1. If the number of tracks is equal to 0, the play list does not contain any tracks.

See Also

IASPlayList::put_NumTracks


IASPlayList::put_ActiveBackColor

This method sets the active background color.

Syntax

HRESULT put_ActiveBackColor( OLE_COLOR clr );

Parameters

clr
Active background color.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

Use the RGB macro to set the components of clr before passing clr to the method.

See Also

IASPlayList::get_ActiveBackColor, RGB


IASPlayList::put_ActiveForeColor

This method sets the active foreground color.

Syntax

HRESULT put_ActiveForeColor( OLE_COLOR clr );

Parameters

clr
Active foreground color.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

Use the RGB macro to set the components of clr before passing clr to the method.

See Also

IASPlayList::get_ActiveForeColor, RGB


IASPlayList::put_BorderColor

This method sets the border color of the play list grid lines.

Syntax

HRESULT put_BorderColor( OLECOLOR clr );

Parameters

clr
New border color.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

Use the RGB macro to set the components of clr before passing clr to the method.

See Also

IASPlayList::get_BorderColor, RGB


IASPlayList::put_CurrentTrack

This method sets the number of the current track.

Syntax

HRESULT put_CurrentTrack( unsigned char bcTrack );

Parameters

bcTrack
Unsigned character that contains the track number.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

The index of tracks in the play list begins at 1. If you set the index of the current track equal to 0, the play list does not indicate a current track.

See Also

IASPlayList::get_CurrentTrack


IASPlayList::put_HiliteBorderColor

This method sets the highlight border color to be drawn around the current selection.

Syntax

HRESULT put_HiliteBorderColor( OLE_COLOR clr );

Parameters

clr
Highlight border color.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

Use the RGB macro to set the components of clr before passing clr to the method.

See Also

IASPlayList::get_HiliteBorderColor, RGB


IASPlayList::put_InactiveBackColor

This method sets the inactive background color.

Syntax

HRESULT put_InactiveBackColor( OLE_COLOR clr );

Parameters

clr
Inactive background color.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

Use the RGB macro to set the components of clr before passing clr to the method.

See Also

IASPlayList::get_InactiveBackColor, RGB


IASPlayList::put_InactiveForeColor

This method sets the inactive foreground color.

Syntax

HRESULT put_InactiveForeColor( OLE_COLOR clr );

Parameters

clr
Inactive foreground color.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

Use the RGB macro to set the components of clr before passing clr to the method.

See Also

IASPlayList::get_InactiveForeColor, RGB


IASPlayList::put_ItemHeight

This method sets the item height, which is the height of an individual box in a play list.

Syntax

HRESULT put_ItemHeight( long lHeight );

Parameters

lHeight
Long integer that specifies the height of the item.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

See Also

IASPlayList::get_ItemHeight


IASPlayList::put_ItemWidth

The method sets the item width, which is the width of an individual box in a play list.

Syntax

HRESULT put_ItemWidth( long lWidth );

Parameters

lWidth
Long integer that specifies the width of the item.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

See Also

IASPlayList::get_ItemWidth


IASPlayList::put_NumTracks

This method sets the number of tracks in the play list.

Syntax

HRESULT put_NumTracks( unsigned char bcTracks );

Parameters

bcTracks
Number of tracks in the play list.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered—for example, if the number of tracks exceeds the maximum number allowed.

Remarks

The index of tracks in the play list begins at 1. If your application determines that no tracks are available, set the number of tracks equal to 0. The maximum number of tracks available is ASFC_PLAYLIST_TRACKSMAX, which is defined as 128.

See Also

IASPlayList::get_NumTracks


IASPlayList::Reset

This method resets the play list and turns off all active tracks.

Syntax

HRESULT Reset ( void );

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASProgressBar

This interface provides the methods to manage a progress bar.

Method
Description
IASProgressBar::get_Horizontal | Determines whether the progress bar is horizontal or vertical. The IASProgressBar interface does not implement this method; it is implemented by IASSlider, which derives from IASProgressBar.
IASProgressBar::get_Max | Gets the maximum value of the progress bar.
IASProgressBar::get_Min | Gets the minimum value of the progress bar.
IASProgressBar::get_RangeColor | Gets the color assigned to a range.
IASProgressBar::get_RangeCount | Gets the current number of ranges.
IASProgressBar::get_RangeValue | Gets the starting value for the specified range.
IASProgressBar::get_Steps | Gets the number of divisions for the progress bar.
IASProgressBar::get_Value | Gets the current value associated with the progress bar.
IASProgressBar::put_Horizontal | Specifies whether the progress bar is horizontal or vertical. The IASProgressBar interface does not implement this method; it is implemented by IASSlider, which derives from IASProgressBar.
IASProgressBar::put_Max | Specifies the maximum value of the progress bar.
IASProgressBar::put_Min | Specifies the minimum value of the progress bar.
IASProgressBar::put_RangeColor | Sets the color assigned to a range.
IASProgressBar::put_RangeCount | Sets the current number of ranges.
IASProgressBar::put_RangeValue | Sets the starting value for a specified range.
IASProgressBar::put_Steps | Specifies the number of divisions for the progress bar.
IASProgressBar::put_Value | Specifies the current value of the progress bar.

Remarks

The IASProgressBar interface, which has a global unique identifier (GUID) equal to IID_ASPROGRESSBAR, extends the IASControl interface. The progress bar has a programmatic identifier equal to APC_Progress.


IASProgressBar::get_Horizontal

This method determines whether the progress bar is horizontal or vertical. The IASProgressBar interface does not implement this method; it is implemented by IASSlider, which derives from IASProgressBar.

Syntax

HRESULT get_Horizontal( BOOL *pfHorizontal );

Parameters

pfHorizontal
Pointer to a Boolean that is set to TRUE for a horizontal bar, or to FALSE for a vertical bar.

Return Values

NOERROR indicates success. E_NOTIMPL indicates that this interface does not implement the get_Horizontal method.

See Also

IASProgressBar::put_Horizontal


IASProgressBar::get_Max

This method gets the maximum value of the progress bar.

Syntax

HRESULT get_Max( long *plMax );

Parameters

plMax
Pointer to a long integer that contains the maximum value of the progress bar.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

See Also

IASProgressBar::put_Max


IASProgressBar::get_Min

This method gets the minimum value of the progress bar.

Syntax

HRESULT get_Min( long *plMin );

Parameters

plMin
Pointer to a long integer that contains the minimum value of the progress bar.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

See Also

IASProgressBar::put_Min


IASProgressBar::get_RangeColor

This method gets the color assigned to a range.

Syntax

HRESULT get_RangeColor( long lRangeIndex, OLE_COLOR *pclr );

Parameters

lRangeIndex
Long integer that indicates the index of the desired range.
pclr
Pointer to the range color.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

Progress bars can be broken into two or more ranges, each of a different color. For example, if a progress bar can take a value between 0 and 10 and is divided into three ranges: red, green, and blue, then the RangeCount property is 3, and the related properties are listed in the following table.

Index
Color
RangeValue
Range
0 | Red | 0 | 0 - 3
1 | Green | 4 | 4 - 7
2 | Blue | 8 | 8-10

Use the GetRValue, GetGValue, and GetBValue macros to get the color components of pclr.

See Also

IASProgressBar, IASProgressBar::put_RangeColor, IASProgressBar::get_RangeValue, GetRValue, GetGValue, GetBValue


IASProgressBar::get_RangeCount

This method gets the current number of ranges.

Syntax

HRESULT get_RangeCount( long *plCount );

Parameters

plCount
Pointer to a long integer that contains the number of ranges that the progress bar is divided into.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

Progress bars can be broken into two or more ranges, each of a different color. For example, if a progress bar can take a value between 0 and 10 and is divided into three ranges: red, green, and blue, then the RangeCount property is 3, and the related properties are listed in the following table.

Index
Color
RangeValue
Range
0 | Red | 0 | 0 - 3
1 | Green | 4 | 4 - 7
2 | Blue | 8 | 8-10

See Also

IASProgressBar, IASProgressBar::put_RangeCount, IASProgressBar::get_RangeValue


IASProgressBar::get_RangeValue

This method gets the starting value for the specified range.

Syntax

HRESULT get_RangeValue( long lRangeIndex, long *plRangeValue );

Parameters

lRangeIndex
Long integer that indicates the index of the desired range.
plRangeValue
Pointer to a long integer that contains the starting value for the specified range.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

Progress bars can be broken into two or more ranges, each of a different color. For example, if a progress bar can take a value between 0 and 10 and is divided into three ranges: red, green, and blue, then the RangeCount property is 3, and the related properties are listed in the following table.

Index
Color
RangeValue
Range
0 | Red | 0 | 0 - 3
1 | Green | 4 | 4 - 7
2 | Blue | 8 | 8-10

See Also

IASProgressBar, IASProgressBar::put_RangeValue


IASProgressBar::get_Steps

This method gets the number of divisions for the progress bar.

Syntax

HRESULT get_Steps( long *plStep );

Parameters

plStep
Pointer to a long integer that contains the step value of the progress bar.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

See Also

IASProgressBar::put_Steps


IASProgressBar::get_Value

This method gets the current value associated with the progress bar.

Syntax

HRESULT get_Value( long *plValue );

Parameters

plValue
Pointer to a long integer that contains the current value of the progress bar.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

See Also

IASProgressBar::put_Value


IASProgressBar::put_Horizontal

This method specifies whether the progress bar is horizontal or vertical. The IASProgressBar interface does not implement this method; it is implemented by IASSlider, which derives from IASProgressBar.

Syntax

HRESULT put_Horizontal( BOOL fHorizontal );

Parameters

fHorizontal
Boolean that is set to TRUE for a horizontal bar, or to FALSE for a vertical bar.

Return Values

E_NOTIMPL indicates that this interface does not implement the put_Horizontal method.

See Also

IASProgressBar::get_Horizontal


IASProgressBar::put_Max

This method sets the maximum value of the progress bar.

Syntax

HRESULT put_Max( long lMax );

Parameters

lMax
Long integer that specifies the maximum value of the progress bar.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

If you set the maximum value of the progress bar to a value that is less than the current minimum value of the progress bar, the minimum value of the progress bar is reset to the value specified for the maximum value of the progress bar.

See Also

IASProgressBar::get_Max


IASProgressBar::put_Min

This method sets the minimum value of the progress bar.

Syntax

HRESULT put_Min( long lMin );

Parameters

lMin
Long integer that specifies the minimum value of the progress bar.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

If you set the minimum value of the progress bar to a value that is greater than the current maximum value of the progress bar, the maximum value of the progress bar is reset to the value specified for the minimum value of the progress bar.

See Also

IASProgressBar::get_Min


IASProgressBar::put_RangeColor

This method sets the color assigned to a range.

Syntax

HRESULT put_RangeColor( long lRangeIndex OLE_COLOR clr );

Parameters

lRangeIndex
Long integer that indicates the index of the desired range.
clr
Range color.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

Progress bars can be broken into two or more ranges, each of a different color. For example, if a progress bar can take a value between 0 and 10 and is divided into three ranges: red, green, and blue, then the RangeCount property is 3, and the related properties are listed in the following table.

Index
Color
RangeValue
Range
0 | Red | 0 | 0 - 3
1 | Green | 4 | 4 - 7
2 | Blue | 8 | 8-10

Use the RGB macro to set the components of clr before passing clr to the method.

See Also

IASProgressBar, IASProgressBar::get_RangeColor, IASProgressBar::get_RangeValue, RGB


IASProgressBar::put_RangeCount

This method gets the current number of ranges.

Syntax

HRESULT put_RangeCount( long lCount );

Parameters

lCount
Long integer that specifies the number of ranges that the progress bar is divided into.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

Progress bars can be broken into two or more ranges, each of a different color. For example, if a progress bar can take a value between 0 and 10 and is divided into three ranges: red, green, and blue, then the RangeCount property is 3, and the related properties are listed in the following table.

Index
Color
RangeValue
Range
0 | Red | 0 | 0 - 3
1 | Green | 4 | 4 - 7
2 | Blue | 8 | 8-10

See Also

IASProgressBar, IASProgressBar::get_RangeCount, IASProgressBar::get_RangeValue


IASProgressBar::put_RangeValue

This method sets the starting value for a specified range.

Syntax

HRESULT put_RangeValue( long lRangeIndex long lRangeValue );

Parameters

lRangeIndex
Long integer that specifies the index of the desired range.
lRangeValue
Long integer that specifies the starting value for the specified range.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

Progress bars can be broken into two or more ranges, each of a different color. For example, if a progress bar can take a value between 0 and 10 and is divided into three ranges: red, green, and blue, then the RangeCount property is 3, and the related properties are listed in the following table.

Index
Color
RangeValue
Range
0 | Red | 0 | 0 - 3
1 | Green | 4 | 4 - 7
2 | Blue | 8 | 8-10

See Also

IASProgressBar, IASProgressBar::get_RangeValue


IASProgressBar::put_Steps

This method sets the number of divisions for the progress bar.

Syntax

HRESULT put_Steps( long lStep );

Parameters

lStep
Long integer that specifies the step value of the progress bar.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

See Also

IASProgressBar::get_Steps


IASProgressBar::put_Value

This method sets the current value of the progress bar.

Syntax

HRESULT put_Value( long lValue );

Parameters

lValue
Long integer the specifies the current value associated with the progress bar.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

See Also

IASProgressBar::get_Value


IASShellMenu

This interface provides the methods to manage a shell menu object.

Method
Description
IASShellMenu::get_LabelBackColor | Gets the label background color.
IASShellMenu::get_LabelForeColor | Gets the label foreground color.
IASShellMenu::get_LabelHeight | Gets the label height.
IASShellMenu::get_HotKey | Gets the hot key associated with a shell menu item.
IASShellMenu::get_ItemFlags | Gets the flags associated with a shell menu item.
IASShellMenu::put_LabelBackColor | Sets the label background color.
IASShellMenu::put_LabelForeColor | Sets the label foreground color.
IASShellMenu::put_LabelHeight | Sets the label height.
IASShellMenu::put_HotKey | Assigns a hot key to a shell menu item.
IASShellMenu::put_ItemFlags | Sets the flags for the specified item.

Remarks

The IASShellMenu interface, which has a global unique identifier (GUID) equal to IID_ASSHELLMENU, extends the IASImageMenu interface. It is used to implement the Auto PC shell user interface (UI). When an item is selected from a shell menu, a WM_COMMAND event is fired to the event sink. The high-order word contains the control’s identifier, and the low-order word contains the item’s identifier. The index of the menu item is sent in lParam. When the focus changes from one item to the next, a WM_COMMAND message is fired to the event sink. LBN_SELCHANGE is in the high-order word of wParam, and the control’s identifier is in the low-order word.

See Also

HIWORD, LOWORD


IASShellMenu::get_LabelBackColor

This method gets the label background color.

Syntax

HRESULT get_LabelBackColor( OLE_COLOR *pclr );

Parameters

pclr
Pointer to the label background color.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

Use the GetRValue, GetGValue, and GetBValue macros to get the color components of pclr.

See Also

IASShellMenu::put_LabelBackColor, GetRValue, GetGValue, GetBValue


IASShellMenu::get_LabelForeColor

This method gets the label foreground color.

Syntax

HRESULT get_LabelForeColor( OLE_COLOR *pclr );

Parameters

pclr
Pointer to the label foreground color.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

Use the GetRValue, GetGValue, and GetBValue macros to get the color components of pclr.

See Also

IASShellMenu::put_LabelForeColor, GetRValue, GetGValue, GetBValue


IASShellMenu::get_LabelHeight

This method gets the label height.

Syntax

HRESULT get_LabelHeight( long *plHeight );

Parameters

plHeight
Pointer to a long integer that contains the height of the label.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

See Also

IASShellMenu::put_LabelHeight


IASShellMenu::get_HotKey

This method gets the hot key associated with a shell menu item.

Syntax

HRESULT get_HotKey( long index unsigned char *pbID );

Parameters

index
Index of the item.
pbID
Pointer to the hot key code identifier. The value of the identifier is between 0 and 255.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

Hot keys are numbers, entered through the keypad, that provide a direct link to a menu item. If a hot key is detected, focus is set to that menu item, and a WM_COMMAND is fired to the event sink.

See Also

IASShellMenu::put_HotKey


IASShellMenu::get_ItemFlags

This method gets the flags associated with a shell menu item.

Syntax

HRESULT get_ItemFlags( long index unsigned char *pbFlags );

Parameters

index
Index of the item.
pbFlags
Pointer to item flags. Currently, the only supported flag is ASFC_IMAGEMENU_OVERLAY.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

See Also

IASShellMenu::put_ItemFlags


IASShellMenu::put_LabelBackColor

This method sets the label background color.

Syntax

HRESULT put_LabelBackColor( OLE_COLOR clr );

Parameters

clr
Label background color.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

Use the RGB macro to set the components of clr before passing clr to the method.

See Also

IASShellMenu::put_LabelBackColor, RGB


IASShellMenu::put_LabelForeColor

This method sets the label foreground color.

Syntax

HRESULT put_LabelForeColor( OLE_COLOR clr );

Parameters

clr
Label foreground color.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

Use the RGB macro to set the components of clr before passing clr to the method.

See Also

IASShellMenu::put_LabelForeColor, RGB


IASShellMenu::put_LabelHeight

This method sets the label height.

Syntax

HRESULT put_LabelHeight( long lHeight );

Parameters

lHeight
Long integer that contains the height of the label.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

See Also

IASShellMenu::get_LabelHeight


IASShellMenu::put_HotKey

This method assigns a hot key to a shell menu item.

Syntax

HRESULT put_HotKey( long index unsigned char bID );

Parameters

index
Index of the item.
bID
Hot key code identifier, a value between 0 and 255.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

Hot keys are numbers, entered through the keypad, that provide a direct link to a menu item. If a hot key is detected, focus is set to that menu item, and a WM_COMMAND is fired to the event sink.

This method assigns a hot key value to a menu item. In horizontal display, the value appears above the item on the screen.

See Also

IASShellMenu::get_HotKey


IASShellMenu::put_ItemFlags

This method sets the flags for the specified item.

Syntax

HRESULT put_ItemFlags( long index, unsigned char bFlags, unsigned char bMask );

Parameters

index
Index of the item.
bFlags
Item flags. This flag must be ASFC_IMAGEMENU_OVERLAY.
bMask
Flag mask.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

See Also

IASShellMenu::get_ItemFlags


IASSlider

This interface provides the methods to manage Auto PC simple (AS) slider controls.

Method
Description
IASSlider::get_HiliteColor | Gets the highlight color.
IASSlider::put_HiliteColor | Sets the highlight color.
IASSlider::get_Incr | Gets the value in which to increment the slider.
IASSlider::put_Incr | Sets the value in which to increment the slider.

Remarks

The IASSlider interface, which has a global unique identifier equal to IID_ASSLIDER, extends the IASProgressBar interface. The slider control has a programmatic identifier equal to APC_Slider. Sliders—active controls designed to be moved by the user—are primarily managed with the methods inherited from IASProgressBar. When a slider is moved, it fires either a WM_HSCROLL or WM_VSCROLL command to the event sink. The WPARAM contains the control’s identifier. The LPARAM contains the slider value.

See Also

IASProgressBar


IASSlider::get_HiliteColor

This method gets the highlight color.

Syntax

HRESULT get_HiliteColor( OLE_COLOR *pclr );

Parameters

pclr
Pointer to the highlight color.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

Use the GetRValue, GetGValue, and GetBValue macros to get the color components of pclr.

See Also

IASSlider::put_HiliteColor, GetRValue, GetGValue, GetBValue


IASSlider::put_HiliteColor

This method sets the highlight color.

Syntax

HRESULT put_HiliteColor( OLE_COLOR pclr );

Parameters

Pointer to the highlight color.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

Use the RGB macro to set the components of clr before passing clr to the method.

See Also

IASSlider::get_HiliteColor, RGB


IASSlider::get_Incr

This method gets the value in which to increment the slider.

Syntax

HRESULT get_Incr( LONG *plIncr );

Parameters

plIncr
Pointer to a long integer that contains the increment value.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

See Also

IASSlider::put_Incr


IASSlider::put_Incr

This method sets the value in which to increment the slider.

Syntax

HRESULT put_Incr( LONG lIncr );

Parameters

lIncr
Long integer that specifies the increment value.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

See Also

IASSlider::get_Incr


IASCharSpinner

This interface provides the methods to manage a character spinner control.

Method
Description
IASCharSpinner::get_ItemHeight | Gets the item height.
IASCharSpinner::put_ItemHeight | Sets the item height.
IASCharSpinner::get_CharSet | Gets the character set.
IASCharSpinner::put_CharSet | Sets the character set.
IASCharSpinner::get_CurChar | Gets the current character.
IASCharSpinner::put_CurChar | Sets the current character.
IASCharSpinner::NextChar | Advances the position of the spin box to the next character.
IASCharSpinner::PrevChar | Retracts the position of the spin box to the previous character.
IASCharSpinner::get_SpinMode | Gets the spin mode.
IASCharSpinner::put_SpinMode | Sets the spin mode.

Remarks

The IASCharSpinner interface, which has a global unique identifier (GUID) equal to IID_ASCHARSPINNER, extends the IASControl interface.

The user inputs text into an application by means of a character spinner control. A WM_COMMAND message is fired to the event sink whenever the ENTER or ESCAPE is pressed. The high-order word of the wParam contains an EN_CHANGE message and the low-order word contains the control’s identifier. The high-order word of lParam contains zero if the character has been modified, and contains one if not. The low-order word of lParam contains the form’s identifier.

See Also

IASControl, HIWORD, LOWORD


IASCharSpinner::get_ItemHeight

This method gets the item height.

Syntax

HRESULT get_ItemHeight( long *plHeight );

Parameters

plHeight
Pointer to a long integer that contains the height of the item.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

All items must be the same height.

See Also

IASCharSpinner::put_ItemHeight


IASCharSpinner::put_ItemHeight

This method sets the item height.

Syntax

HRESULT put_ItemHeight( long lHeight );

Parameters

lHeight
Long integer that specifies the height of the item.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

Remarks

All items must be the same height.

See Also

IASCharSpinner::get_ItemHeight


IASCharSpinner::get_CharSet

This method gets the character set.

Syntax

HRESULT get_CharSet( BSTR *pbstr );

Parameters

pbstr
Pointer to the character set.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

See Also

IASCharSpinner::put_CharSet


IASCharSpinner::put_CharSet

This method sets the character set.

Syntax

HRESULT put_CharSet( BSTR bstr );

Parameters

bstr
Character set.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

See Also

IASCharSpinner::get_CharSet


IASCharSpinner::get_CurChar

This method gets the current character.

Syntax

HRESULT get_CurChar( short *pch );

Parameters

pch
Pointer to the current character.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

See Also

IASCharSpinner::put_CurChar


IASCharSpinner::put_CurChar

This method sets the current character.

Syntax

HRESULT put_CurChar( short ch );

Parameters

ch
Current character.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

See Also

IASCharSpinner::get_CurChar


IASCharSpinner::get_SpinMode

This method gets the spin mode.

Syntax

HRESULT get_SpinMode( short *pmode );

Parameters

pmode
Pointer to a short integer that contains the spin mode.

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

See Also

IASCharSpinner::put_SpinMode


IASCharSpinner::put_SpinMode

This method sets the spin mode.

Syntax

HRESULT put_SpinMode( short mode );

Parameters

mode
Short integer that contains the spin mode. The spin mode is one of the following values:
Mode
Value
ASFC_CHARSPIN_SEQUENTIAL | 0x1
ASFC_CHARSPIN_DIRSHIFTED | 0x2

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

See Also

IASCharSpinner::get_SpinMode


IASCharSpinner::NextChar

This method advances the position of the spin box to the next character.

Syntax

HRESULT NextChar( );

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

See Also

IASCharSpinner::PrevChar


IASCharSpinner::PrevChar

This method retracts the position of the spin box to the previous character.

Syntax

HRESULT PrevChar( );

Return Values

NOERROR indicates success. E_INVALIDARG indicates that an invalid argument has been entered.

See Also

IASCharSpinner::NextChar


IASTimer

The IASTimer interface provides methods for timing.

Method
Description
IASTimer::get_Interval | Gets the interval at which the current timer is triggered.
IASTimer::get_TimerEnabled | Gets whether or not the timer is enabled
IASTimer::put_Interval | Sets a new timing interval, and restarts the timer
IASTimer::put_TimerEnabled | Sets whether or not the timer is enabled

Remarks

The IASTimer interface, which has a global unique identifier (GUID) equal to IID_ASTIMER, extends the IASControl interface. The timer is set to fire at a specified interval. When it matures, it fires a WM_TIMER message to the event sink. The control’s identifier is contained in the low-order word of wParam, the form’s identifier in the high-order word.

See Also

HIWORD, LOWORD


IASTimer::get_Interval

This method gets the interval at which the current timer is triggered.

Syntax

HRESULT get_Interval( long *plMillis );

Parameters

plMillis
Timing interval, in milliseconds.

Return Values

E_OUTOFMEMORY
This value is returned if the system is out of memory.

See Also

IASTimer::put_Interval


IASTimer::get_TimerEnabled

This method gets whether or not the timer is enabled.

Syntax

HRESUTL get_TimerEnabled( BOOL*pfEnabled );

Parameters

pfEnabled
Pointer to a Boolean that is set to TRUE if a timer is enabled, or to FALSE if not.

Return Values

E_OUTOFMEMORY
This value is returned if the system is out of memory.

See Also

IASTimer::put_TimerEnabled


IASTimer::put_Interval

This method sets a new timing interval, and restarts the timer.

Syntax

HRESULT put_Interval( long lMillis );

Parameters

lMillis
Long integer that specifies the new timing interval, in milliseconds.

Return Values

E_OUTOFMEMORY
This value is returned if the system is out of memory.

See Also

IASTimer::get_Interval


IASTimer::put_TimerEnabled

This method sets whether or not the timer is enabled.

Syntax

HRESULT put_TimerEnabled( BOOL fEnabled );

Parameters

fEnabled
Boolean that is set to TRUE if a timer is enabled, or to FALSE if not.

Return Values

E_OUTOFMEMORY
This value is returned if the system is out of memory.

See Also

IASTimer::get_TimerEnabled


IASMemorySlider

This interface is used to manage a memory slider.

Method
Description
IASMemorySlider::put_StoreUsed | Sets the amount of the object store currently being used.
IASMemorySlider::put_RamUsed | Sets the amount of RAM currently being used.

Remarks

The IASMemorySlider interface, which has a global unique identifier (GUID) equal to IID_ASMEMORYSLIDER, extends the IASSlider interface. The memory slider has a programmatic identifier equal to APC_MemSlider.

See Also

IASProgressBar, IASSlider


IASMemorySlider::put_StoreUsed

This method sets the amount of the object store currently being used.

Syntax

HRESULT put_StoreUsed( long lStoreUsed );

Parameters

lStoreUsed
Long integer that contains the amount of RAM currently in use.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

To determine the amount of the object store currently being used, call the GetStoreInformation function to retrieve a STORE_INFORMATION structure. You can then use the put_StoreUsed method to set the value displayed by the memory slider to value obtained from the STORE_INFORMATION structure.

See Also

GetStoreInformation, STORE_INFORMATION


IASMemorySlider::put_RamUsed

This method sets the amount of RAM currently being used.

Syntax

HRESULT put_RamUsed( long lRamUsed );

Parameters

lRamUsed
Long integer that contains the amount of RAM currently in use.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

To determine the amount of RAM currently being used, call the GlobalMemoryStatus function to retrieve a MEMORYSTATUS structure. You can then use the put_RamUsed method to set the value displayed by the memory slider to value obtained from the MEMORYSTATUS structure.

See Also

GlobalMemoryStatus, MEMORYSTATUS


IASPowerListBox

This interface provides methods to manage a power list box control.

Method
Description
IASPowerListBox::Add | Adds a new item to a power list box.
IASPowerListBox::AddItemsFromResource | Load items from a menu resource file.
IASPowerListBox::CreateItem | Adds an item to the power list box and retrieves an interface that can be used to interact with the item.
IASPowerListBox::FindItem | Finds the item that matches the value of bstr.
IASPowerListBox::FindItemPartial | Finds the item that matches the first character of the Unicode string specified in bstr.
IASPowerListBox::get_Alignment | Retrieves how items are aligned.
IASPowerListBox::get_CenteredFocus | Retrieves whether or not the power list box has centered focus.
IASPowerListBox::get_Circular | Retrieves whether or not the power list box should wrap around—return to the beginning—when it reaches the end of the list.
IASPowerListBox::get_CommandPrompt | Gets the command prompt.
IASPowerListBox::get_Count | Gets the number of items in the power list box.
IASPowerListBox::get_Edit | Enables the application to access the internal edit controls used by the power list box.
IASPowerListBox::get_FocusId | Gets the identifier of the item with focus.
IASPowerListBox::get_FocusIndex | Gets the index of the item with focus.
IASPowerListBox::get_HiliteCaptionColor | Gets the highlight color of the caption.
IASPowerListBox::get_HiliteColor | Gets the highlight color of the power list box.
IASPowerListBox::get_HiliteFont | Gets the highlight font.
IASPowerListBox::get_HiliteTextColor | Gets the color used for highlighted text.
IASPowerListBox::get_ItemBorder | Retrieves whether or not the item has a border.
IASPowerListBox::get_ItemBorderColor | Retrieves the color used for item borders.
IASPowerListBox::get_ItemCaptionColor | Gets the color used for item captions.
IASPowerListBox::get_ItemHeight | Gets the height of the item.
IASPowerListBox::get_ProvideCommandDataSink | Retrieves a pointer to the sink interface used to obtain null command item captions.
IASPowerListBox::get_ReadOnly | Retrieves whether or not the power list box is read-only.
IASPowerListBox::get_ScrollArrowsVisible | Retrieves whether or not the scroll arrows are visible.
IASPowerListBox::get_ShowInteractionSymbols | Retrieves whether or not the interaction symbols are shown.
IASPowerListBox::get_Sorted | Retrieves whether or not the power list box is sorted.
IASPowerListBox::get_SortOrder | Retrieves whether the list is sorted in ascending or descending order.
IASPowerListBox::get_StatusItemsImageList | Specifies the list of status images.
IASPowerListBox::get_TitlebarUpdateMode | Retrieves a mode that indicates how a power list box updates the title bar of a form.
IASPowerListBox::get_TopVisibleId | Retrieves the identifier of the topmost visible item.
IASPowerListBox::get_TopVisibleIndex | Retrieves the index of the topmost visible item.
IASPowerListBox::InsertAt | Inserts an item at a specific index.
IASPowerListBox::Item | Retrieves a pointer to an item specified by its identifier.
IASPowerListBox::ItemAt | Retrieves a pointer to an item specified by its index.
IASPowerListBox::put_Alignment | Sets how items are aligned.
IASPowerListBox::put_CenteredFocus | Sets whether or not the power list box has centered focus.
IASPowerListBox::put_Circular | Sets whether or not the power list box should wrap around—return to the beginning—when it reaches the end of the list.
IASPowerListBox::put_CommandPrompt | Sets the command prompt.
IASPowerListBox::put_FocusId | Sets the identifier of the item with focus.
IASPowerListBox::put_FocusIndex | Sets the index of the item with focus.
IASPowerListBox::put_HiliteCaptionColor | Sets the highlight color of the caption.
IASPowerListBox::put_HiliteColor | Sets the highlight color of the power list box.
IASPowerListBox::put_HiliteFont | Sets the highlight font.
IASPowerListBox::put_HiliteTextColor | Sets the color used for highlighted text.
IASPowerListBox::put_ItemBorder | Sets whether or not the item has a border.
IASPowerListBox::put_ItemBorderColor | Sets the color used for item borders.
IASPowerListBox::put_ItemCaptionColor | Sets the color used for item captions.
IASPowerListBox::put_ItemHeight | Sets the height of the item.
IASPowerListBox::put_ProvideCommandDataSink | Specifies a pointer to the sink interface used to obtain null command item captions.
IASPowerListBox::put_ReadOnly | Sets whether or not the power list box is read-only.
IASPowerListBox::put_ScrollArrowsVisible | Sets whether or not the scroll arrows are visible.
IASPowerListBox::put_ShowInteractionSymbols | Sets whether or not the interaction symbols are shown.
IASPowerListBox::put_Sorted | Sets whether or not the power list box is sorted.
IASPowerListBox::put_SortOrder | Sets whether the list is sorted in ascending or descending order.
IASPowerListBox::put_StatusItemsImageList | Specifies the list of status images.
IASPowerListBox::put_TitlebarUpdateMode | Sets a mode that controls how a power list box updates the title bar of a form.
IASPowerListBox::put_TopVisibleId | Sets the identifier of the topmost visible item.
IASPowerListBox::put_TopVisibleIndex | Sets the index of the topmost visible item.
IASPowerListBox::Remove | Removes an item specified by its identifier.
IASPowerListBox::RemoveAll | Removes all items from the power list box.
IASPowerListBox::RemoveAt | Removes an item specified by its index.

Remarks

The IASPowerListBox interface, which has a global unique identifier (GUID) equal to IID_ASPOWERLISTBOX, extends the IASControl interface. All IASControl methods are available through the IASPowerListBox interface. The power list box control has a programmatic identifier equal to APC_PwrListBox.


IASPowerListBox::Add

This method adds a new item to a power list box.

Syntax

HRESULT Add( long lItemId, long lType, IDispatch **ppdispItem );

Parameters

lItemId
Long integer that contains the identifier of the item.
lType
Long integer that contains the item type. It is one of the following values:
ASFC_PWRLB_TYPE_COMMAND
Specifies a command.
ASFC_PWRLB_TYPE_EDIT
Specifies an edit box.
ASFC_PWRLB_TYPE_STRINGSPINNER
Specifies a string spinner.
ASFC_PWRLB_TYPE_INTSPINNER
Specifies an integer spinner.
ppdispItem
Pointer to the pointer to item’s IDispatch interface.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

The item is added to the end of the list. To interact with the item, call QueryInterface on the IDispatch interface.

It is possible to use duplicate identifiers. However, if you do so, you can no longer identify items by their identifier.

See Also

IASPowerListBox::CreateItem


IASPowerListBox::AddItemsFromResource

This method loads items from a menu resource file.

Syntax

HRESULT AddItemsFromResource ( HINSTANCE hinst, PCWSTR pszMenuName, DWORD dwMenuState );

Parameters

hinst
Handle to an instance.
pszMenuName
Pointer to the null-terminated string that contains the menu name.
dwMenuState
Specifies the state of the menu.

Return Values

An appropriate HRESULT value is returned.

Remarks

This function is additive and can be executed more than once to load multiple items.


IASPowerListBox::CreateItem

This method adds an item to the power list box and retrieves an interface that can be used to interact with the item.

Syntax

HRESULT CreateItem( IASPowerListBoxItem **ppItem, long lItemId, long lType );

Parameters

ppItem
Pointer to a pointer to an interface, such as IASPowerListBoxEdit, that can be used to interact with the item directly.
lItemId
Long integer that contains the identifier of the item.
lType
Long integer that contains the item type. It is one of the following values:
ASFC_PWRLB_TYPE_COMMAND
Specifies a command.
ASFC_PWRLB_TYPE_EDIT
Specifies an edit box.
ASFC_PWRLB_TYPE_STRINGSPINNER
Specifies a string spinner.
ASFC_PWRLB_TYPE_INTSPINNER
Specifies an integer spinner.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

Use this method if you need to add an item to a Power List box and then interact with it. By using CreateItem, you do not have to call QueryInterface to get the necessary interface.

See Also

IASPowerListBox::Add


IASPowerListBox::FindItem

This method finds the item that has a value that matches the value of bstr.

Syntax

HRESULT FindItem( BSTR bstr, long lIndexStart, long *pIndex );

Parameters

bstr
Unicode string to search for.
lIndexStart
Long integer that contains the starting index.
pIndex
Pointer to the index of the item that matches bstr.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

If this is a sorted list box, a binary search is performed; otherwise, a linear search is conducted.


IASPowerListBox::FindItemPartial

This method finds the item that matches the first character of the Unicode string specified in bstr.

Syntax

HRESULT FindItemPartial( BSTR bstr, long lIndexStart, long *pIndex );

Parameters

bstr
Unicode string to search for.
lIndexStart
Long integer that contains the starting index.
pIndex
Pointer to the index of the item that partially matches bstr.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::get_Alignment

This method retrieves how items are aligned.

Syntax

HRESULT get_Alignment ( short *pwAlign );

Parameters

pwAlign
Pointer to an unsigned 16-bit character that contains one of the following alignment flags:
ASFC_ALIGN_BOTTOM
Aligns text with the bottom of the control.
ASFC_ALIGN_CENTER
Centers text.
ASFC_ALIGN_LEFT
Aligns text to the left of the control.
ASFC_ALIGN_RIGHT
Aligns text to the right of the control.
ASFC_ALIGN_SINGLELINE
Draws text in a single line.
ASFC_ALIGN_TOP
Aligns text with the top of the control.
ASFC_ALIGN_VCENTER
Centers text vertically.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::get_CenteredFocus

This method retrieves whether or not the power list box has centered focus.

Syntax

HRESULT get_CenteredFocus ( BOOL *pfCenteredFocus );

Parameters

pfCenteredFocus
Pointer to a Boolean that is set to TRUE if centered focus is enabled, or to FALSE if not.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::get_Circular

This method retrieves whether or not the power list box should wrap around—return to the beginning—when it reaches the end of the list.

Syntax

HRESULT get_Circular ( BOOL *pfCircular );

Parameters

pfCircular
Pointer to a Boolean that is set to TRUE if the power list box should wrap, or to FALSE if not. It is TRUE by default.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::get_CommandPrompt

This method gets the command prompt.

Syntax

HRESULT get_CommandPrompt( BSTR *pbstrCommandPrompt );

Parameters

pbstrCommandPrompt
Pointer to the Unicode string to be used for a command prompt.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

The command prompt is a string that is displayed in front of command items that have rows. Only one command item can have the focus at one time.


IASPowerListBox::get_Count

This method gets the number of items in the power list box.

Syntax

HRESULT get_Count ( long *pcItems );

Parameters

pcItems
Pointer to the number of items in the power list box.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::get_Edit

This method enables the application to access the internal edit controls used by the power list box.

Syntax

HRESULT get_Edit( IDispatch **ppdispEdit );

Parameters

ppdispEdit
Pointer to a pointer to the IDispatch interface of the edit box.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::get_FocusId

This method gets the identifier of the item with focus.

Syntax

HRESULT get_FocusId( long *plFocusId );

Parameters

plFocusId
Pointer to the long integer that contains the identifier of the item with focus.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::get_FocusIndex

This method gets the index of the item with focus.

Syntax

HRESULT get_FocusIndex( long *plFocusIndex );

Parameters

plFocusIndex
Pointer to the index of the item with focus.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::get_HiliteCaptionColor

This method gets the highlight color of the caption.

Syntax

HRESULT get_HiliteCaptionColor ( OLE_COLOR *pclrHiliteCaption );

Parameters

pclrHiliteCaption
Pointer to the highlight color of the caption.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

Use the GetRValue, GetGValue, and GetBValue macros to get the color components of pclrHiliteCaption.

See Also

GetRValue, GetGValue, GetBValue


IASPowerListBox::get_HiliteColor

This method gets the highlight color of the power list box.

Syntax

HRESULT get_HiliteColor( OLE_COLOR *pclrHiliteColor );

Parameters

pclrHiliteColor
Pointer to the highlight color of the power list box.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

Use the GetRValue, GetGValue, and GetBValue macros to get the color components of pclrHiliteColor.

See Also

GetRValue, GetGValue, GetBValue


IASPowerListBox::get_HiliteFont

This method gets the highlight font.

Syntax

HRESULT get_HiliteFont( IFontDisp **ppFontDisp );

Parameters

ppFontDisp
Pointer to a pointer to the IFontDisp interface for the highlight font.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::get_HiliteTextColor

This method gets the color used for highlighted text.

Syntax

HRESULT get_HiliteTextColor( OLE_COLOR *pclrHiliteText );

Parameters

pclrHiliteText
Pointer to the color used for highlighted text.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

Use the GetRValue, GetGValue, and GetBValue macros to get the color components of pclrHiliteText.

See Also

GetRValue, GetGValue, GetBValue


IASPowerListBox::get_ItemBorder

This method retrieves whether or not the item has a border.

Syntax

HRESULT get_ItemBorder( BOOL *pfItemBorder );

Parameters

pfItemBorder
Pointer to a Boolean that is set to TRUE if the item has a border, or to FALSE if not.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::get_ItemBorderColor

This method retrieves the color used for item borders.

Syntax

HRESULT get_ItemBorderColor( OLE_COLOR *pclrItemBorder );

Parameters

pclrItemBorder
Pointer to the color used for item borders.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

Use the GetRValue, GetGValue, and GetBValue macros to get the color components of pclrItemBorder.

See Also

GetRValue, GetGValue, GetBValue


IASPowerListBox::get_ItemCaptionColor

This method gets the color used for item captions.

Syntax

HRESULT get_ItemCaptionColor( OLE_COLOR *pclrItemCaption );

Parameters

pclrItemCaption
Pointer to the color used for item captions.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

Use the GetRValue, GetGValue, and GetBValue macros to get the color components of pclrItemCaption.

See Also

GetRValue, GetGValue, GetBValue


IASPowerListBox::get_ItemHeight

This method gets the height of the item.

Syntax

HRESULT get_ItemHeight( long *plItemHeight );

Parameters

plItemHeight
Pointer to the long integer that contains the height of the item.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::get_ProvideCommandDataSink

This method retrieves a pointer to the sink interface used to obtain null command item captions.

Syntax

HRESULT get_ProvideCommandDataSink( IASProvidePowerListBoxCommandData **ppSink );

Parameters

ppSink
Pointer to the pointer to the sink interface used to obtain NULL command item captions.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::get_ReadOnly

This method retrieves whether or not the power list box is read-only.

Syntax

HRESULT get_ReadOnly( BOOL *pfReadOnly );

Parameters

pfReadOnly
Pointer to a Boolean that is set to TRUE if the power list box is read-only, or to FALSE if not.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::get_ScrollArrowsVisible

This method retrieves whether or not the scroll arrows are visible.

Syntax

HRESULT get_ScrollArrowsVisible ( BOOL *pfScrollArrowsVisible );

Parameters

pfScrollArrowsVisible
Pointer to a Boolean that is set to TRUE if scroll arrows are visible, or to FALSE if not.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::get_ShowInteractionSymbols

This method retrieves whether or not the interaction symbols are shown.

Syntax

HRESULT get_ShowInteractionSymbols ( BOOL *pfShowInteractionSymbols );

Parameters

pfShowInteractionSymbols
Pointer to a Boolean that is set to TRUE if interaction symbols are to be shown, or to FALSE if not.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::get_Sorted

This method retrieves whether or not the power list box is sorted.

Syntax

HRESULT get_Sorted( BOOL *pfSorted );

Parameters

pfSorted
Pointer to a Boolean that is set to TRUE if the items are sorted, or to FALSE if not.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::get_SortOrder

This method retrieves whether the list is sorted in ascending or descending order.

Syntax

HRESULT get_SortOrder( BOOL *pfAscending );

Parameters

pfAscending
Pointer to a Boolean that is set to TRUE if sorted in ascending order, or to FALSE if sorted in descending order.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::get_StatusItemsImageList

This method specifies the list of status images.

Syntax

HRESULT get_StatusItemsImageList( OLE_HANDLE *phImage OLE_HANDLE *phImageMask short *pcImages );

Parameters

phImage
Pointer to the handle of the image list.
phImageMask
Pointer to the handle to the image list mask. The mask specifies which images in the list are displayed.
pcImages
Pointer to the number of images in the list

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::get_TitlebarUpdateMode

This method retrieves a mode that indicates how a power list box updates the title bar of a form.

Syntax

HRESULT get_TitlebarUpdateMode( WORD *pwTitlebarUpdateMode );

Parameters

pwTitlebarUpdateMode
Pointer to a WORD that receives the mode that a power list box uses when updating the title bar of a form. The mode is any combination of the following values.
ASTUM_CAPTION
Undefined.
ASTUM_CAPTIONEDIT
Sets the caption of the title bar equal to the caption of a power list box edit item when editing that item.
ASTUM_CAPTIONMENU
Sets the caption of the title bar equal to the caption of the power list box when IfmManage::put_Menu is called.
ASTUM_EDITHIDENAV
Hides the navigational arrows control when editing a power list box item.
ASTUM_STATUS
Sets the status of the title bar equal to the status of the current item.
ASTUM_SUBCAPTION
Sets the subcaption of the title bar equal to a string, for example "2 of 7," that shows the position of the power list box

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

See Also

IASPowerListBox::put_TitlebarUpdateMode


IASPowerListBox::get_TopVisibleId

This method retrieves the identifier of the topmost visible item.

Syntax

HRESULT get_TopVisibleId( long *plTopVisibleId );

Parameters

plTopVisibleId
Pointer to the long integer that contains the identifier of the topmost visible item.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::get_TopVisibleIndex

This method retrieves the index of the topmost visible item.

Syntax

HRESULT get_TopVisibleIndex( long *plTopVisibleIndex );

Parameters

plTopVisibleIndex
Pointer to the long integer that contains the index of the topmost visible item.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::InsertAt

This method inserts an item at a specified index.

Syntax

HRESULT InsertAt ( long lIndex long lItemId long lType IDispatch **ppdispItem );

Parameters

lIndex
Long integer that contains the index for the new item.
lItemId
Long integer that contains the identifier of the item.
lType
Long integer that contains the item type. It is one of the following values:
ASFC_PWRLB_TYPE_COMMAND
Specifies a command.
ASFC_PWRLB_TYPE_EDIT
Specifies an edit box.
ASFC_PWRLB_TYPE_STRINGSPINNER
Specifies a string spinner.
ASFC_PWRLB_TYPE_INTSPINNER
Specifies an integer spinner.
ppdispItem
Pointer to the pointer to item’s IDispatch interface.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::Item

This method retrieves a pointer to an item specified by its identifier.

Syntax

HRESULT Item( long lItemId IDispatch **ppdispItem );

Parameters

lItemId
Long integer that contains the identifier of the item.
ppdispItem
Pointer to the pointer to item’s IDispatch interface.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::ItemAt

This method retrieves a pointer to an item specified by its index.

Syntax

HRESULT ItemAt( long lIndex IDispatch **ppdispItem );

Parameters

lIndex
Long integer that contains the index of the item.
ppdispItem
Pointer to a pointer to the item’s IDispatch interface.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::put_Alignment

This method sets how items are aligned.

Syntax

HRESULT put_Alignment ( short wAlign );

Parameters

pwAlign
Pointer to an unsigned 16-bit character that contains one of the following alignment flags:
ASFC_ALIGN_BOTTOM
Aligns text with the bottom of the control.
ASFC_ALIGN_CENTER
Centers text.
ASFC_ALIGN_LEFT
Aligns text to the left of the control.
ASFC_ALIGN_RIGHT
Aligns text to the right of the control.
ASFC_ALIGN_SINGLELINE
Draws text in a single line.
ASFC_ALIGN_TOP
Aligns text with the top of the control.
ASFC_ALIGN_VCENTER
Centers text vertically.
ASFC_ALIGN_WORDBREAK
Draws text with word breaks.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::put_CenteredFocus

This method sets whether or not the power list box has centered focus.

Syntax

HRESULT put_CenteredFocus ( BOOL fCenteredFocus );

Parameters

fCenteredFocus
Boolean that is set to TRUE if centered focus is enabled, or to FALSE if not.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::put_Circular

This method sets whether or not the power list box should wrap around —return to the beginning—when it reaches the end of the list.

Syntax

HRESULT put_Circular ( BOOL fCircular );

Parameters

fCircular
Boolean that is set to TRUE if power list box should wrap, or to FALSE if not. It is TRUE by default.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::put_CommandPrompt

This method sets the command prompt.

Syntax

HRESULT put_CommandPrompt( BSTR bstrCommandPrompt );

Parameters

bstrCommandPrompt
Unicode string to be used for a command prompt.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

To create command prompts than span multiple lines, set the item height to a size large enough to accommodate all needed lines. Then set bstrCommandPrompt to the desired value, using newline characters to separate the lines.

See Also

IASPowerListBox::put_ItemHeight


IASPowerListBox::put_FocusId

This method sets the identifier of the item with focus.

Syntax

HRESULT put_FocusId( long lFocusId );

Parameters

lFocusId
Long integer that contains the identifier of the item with focus.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::put_FocusIndex

This method sets the index of the item with focus.

Syntax

HRESULT put_FocusIndex( long lFocusIndex );

Parameters

lFocusIndex
Long integer that contains the index of the item with focus.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::put_HiliteCaptionColor

This method sets the highlight color of the caption.

Syntax

HRESULT put_HiliteCaptionColor ( OLE_COLOR clrHiliteCaption );

Parameters

clrHiliteCaption
Highlight color of the caption.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

Use the RGB macro to set the components of clrHiliteCaption before passing clrHiliteCaption to the method.

See Also

RGB


IASPowerListBox::put_HiliteColor

This method sets the highlight color of the power list box.

Syntax

HRESULT put_HiliteColor( OLE_COLOR clrHiliteColor );

Parameters

clrHiliteColor
Highlight color of the power list box.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

Use the RGB macro to set the components of clrHiliteColor before passing clrHiliteColor to the method.

See Also

RGB


IASPowerListBox::put_HiliteFont

This method sets the highlight font.

Syntax

HRESULT put_HiliteFont( IFontDisp *pFontDisp );

Parameters

pFontDisp
Pointer to the IFontDisp interface for the highlight font.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::put_HiliteTextColor

This method sets the color used for highlighted text.

Syntax

HRESULT put_HiliteTextColor( OLE_COLOR clrHiliteText );

Parameters

clrHiliteText
Color used for highlighted text.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

Use the RGB macro to set the components of clrHiliteText before passing clrHiliteText to the method.

See Also

RGB


IASPowerListBox::put_ItemBorder

This method sets whether or not the item has a border.

Syntax

HRESULT put_ItemBorder( BOOL fItemBorder );

Parameters

fItemBorder
Boolean that is set to TRUE if the item has a border, or to FALSE if not.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::put_ItemBorderColor

This method sets the color used for item borders.

Syntax

HRESULT put_ItemBorderColor( OLE_COLOR clrItemBorder );

Parameters

clrItemBorder
Color used for item borders.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

Use the RGB macro to set the components of clrItemBorder before passing clrItemBorder to the method.

See Also

RGB


IASPowerListBox::put_ItemCaptionColor

This method sets the color used for item captions.

Syntax

HRESULT put_ItemCaptionColor( OLE_COLOR clrItemCaption );

Parameters

clrItemCaption
Color used for item captions.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

Use the RGB macro to set the components of clrItemCaption before passing clrItemCaption to the method.

See Also

RGB


IASPowerListBox::put_ItemHeight

This method sets the height of the item.

Syntax

HRESULT put_ItemHeight( long lItemHeight );

Parameters

lItemHeight
Long integer that contains the height of the item.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::put_ProvideCommandDataSink

This method specifies a pointer to the sink interface used to obtain null command item captions.

Syntax

HRESULT put_ProvideCommandDataSink(
IASProvidePowerListBoxCommandData *pSink );

Parameters

pSink
Pointer to the sink interface used to obtain NULL command item captions.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::put_ReadOnly

This method sets whether or not the power list box is read-only.

Syntax

HRESULT put_ReadOnly( BOOL fReadOnly );

Parameters

fReadOnly
Boolean that is set to TRUE if the power list box is read-only, or to FALSE if not.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::put_ScrollArrowsVisible

This method sets whether or not the scroll arrows are visible.

Syntax

HRESULT put_ScrollArrowsVisible ( BOOL fScrollArrowsVisible );

Parameters

fScrollArrowsVisible
Boolean that is set to TRUE if scroll arrows are visible, or to FALSE if not.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::put_ShowInteractionSymbols

This method sets whether or not the interaction symbols are shown.

Syntax

HRESULT put_ShowInteractionSymbols ( BOOL fShowInteractionSymbols );

Parameters

fShowInteractionSymbols
Boolean that is set to TRUE if interaction symbols are to be shown, or to FALSE if not.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::put_Sorted

This method sets whether or not the power list box is sorted.

Syntax

HRESULT put_Sorted( BOOL fSorted );

Parameters

fSorted
Boolean that is set to TRUE if the items are sorted, or to FALSE if not.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::put_SortOrder

This method sets whether the list is sorted in ascending or descending order.

Syntax

HRESULT put_SortOrder( BOOL fAscending );

Parameters

fAscending
Boolean that is set to TRUE if sorted in ascending order, or to FALSE if sorted in descending order.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::put_StatusItemsImageList

This method specifies the list of status images.

Syntax

HRESULT put_StatusItemsImageList( OLE_HANDLE hImage,
OLE_HANDLE hImageMask, s hort cImages );

Parameters

hImage
Handle to the image list.
hImageMask
Handle to the image list mask. The mask specifies which images in the list are displayed.
cImages
Number of images in the list

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::put_TitlebarUpdateMode

This method sets a mode that controls how a power list box updates the title bar of a form.

Syntax

HRESULT put_TitlebarUpdateMode( WORD wTitlebarUpdateMode );

Parameters

wTitlebarUpdateMode
Specifies the mode that a power list box uses when updating the title bar of a form. It is any combination of the following values.
ASTUM_CAPTION
Undefined.
ASTUM_CAPTIONEDIT
Sets the caption of the title bar equal to the caption of a power list box edit item when editing that item.
ASTUM_CAPTIONMENU
Sets the caption of the title bar equal to the caption of the power list box when IfmManage::put_Menu is called.
ASTUM_EDITHIDENAV
Hides the NavArrow control when editing a power list box item.
ASTUM_STATUS
Sets the status of the title bar equal to the status of the current item.
ASTUM_SUBCAPTION
Sets the subcaption of the title bar equal to a string, for example "2 of 7," that shows the position of the power list box

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

See Also

IASPowerListBox::get_TitlebarUpdateMode


IASPowerListBox::put_TopVisibleId

This method sets the identifier of the topmost visible item.

Syntax

HRESULT put_TopVisibleId( long lTopVisibleId );

Parameters

lTopVisibleId
Long integer that contains the identifier of the topmost visible item.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::put_TopVisibleIndex

This method sets the index of the topmost visible item.

Syntax

HRESULT put_TopVisibleIndex( long lTopVisibleIndex );

Parameters

lTopVisibleIndex
Long integer that contains the index of the topmost visible item.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::Remove

This method removes an item specified by its identifier.

Syntax

HRESULT Remove( long lItemId );

Parameters

lItemId
Long integer that contains the identifier of the item to be removed.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::RemoveAll

This method removes all items from the power list box.

Syntax

HRESULT RemoveAll( void );

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBox::RemoveAt

This method removes an item specified by its index.

Syntax

HRESULT RemoveAt( long lIndex );

Parameters

lIndex
Long integer that contains the index of the item to be removed.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBoxCommand

This interface is used to manage command items in a power list box.

Remarks

The IASPowerListBoxCommand interface, which has a global unique identifier (GUID) equal to IID_ASPOWERLISTBOXCOMMAND, extends the IASPowerListBoxItem interface. It has no methods of its own, at present. It is managed with the methods inherited from the IASPowerListBoxItem interface.

See Also

IASPowerListBoxItem


IASProvidePowerListBoxCommandData

This interface defines a sink which can be implemented by the application. It allows a list box to perform a callback to get the items to be displayed.

Method
Description
IASProvidePowerListBoxCommandData::GetCaption Retrieves the caption associated with a particular command item.

Remarks

The IASProvidePowerListBoxCommandData interface, which has a global unique identifier equal to IID_ASPROVIDEPOWERLISTBOXCOMMANDDATA, extends the IUnknown interface.

The purpose of this interface is for applications such as Contacts that either have large numbers of entries, or whose entries may change frequently. To use this interface, point to it in the ProvidePowerListBoxCommandData property of the form. The power list box then invokes GetCaption when drawing a command item that has a Null caption.


IASProvidePowerListBoxCommandData::GetCaption

This method retrieves the caption associated with a particular command item.

Syntax

HRESULT GetCaption( long lIndex, long lItemId, long lItemData, BSTR *pbstrCaption );

Parameters

lIndex
Long integer that contains the index of the item.
lItemId
Long integer that contains the identifier of the item.
lItemData
Long integer that contains data associated with the item.
pbstrCaption
Pointer to the Unicode string to be displayed as a caption in the power list box.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

The IASProvidePowerListBoxCommandData::GetCaption method is called by the power list box control to obtain the display text for items with Null captions. It must be registered by calling IASPowerListBox::put_ProvideCommandDataSink. This method should return a SysAllocString BSTR because the power list box calls SysFreeString on it when drawing is complete.

See Also

IASForm


IASPowerListBoxEdit

This interface provides methods to manage a power list box edit item.

Method
Description
IASPowerListBoxEdit::get_MaxChars | Retrieves the maximum number of characters allowed for edit item.
IASPowerListBoxEdit::get_CharSet | Retrieves a string of valid characters.
IASPowerListBoxEdit::get_Text | Retrieves the text in the edit control.
IASPowerListBoxEdit::put_MaxChars | Sets the maximum number of characters allowed for the edit item.
IASPowerListBoxEdit::put_CharSet | Sets a string of valid characters.
IASPowerListBoxEdit::put_Text | Sets the text in the edit item.

Remarks

The IASPowerListBoxEdit interface, which has a global unique identifier (GUID) equal to IID_ASPOWERLISTBOXEDIT, extends the IASControl interface.


IASPowerListBoxEdit::get_MaxChars

This method retrieves the maximum number of characters allowed for the edit item.

Syntax

HRESULT get_MaxChars( short *wcchMax );

Parameters

wcchMax
Unsigned 16-bit character that contains the maximum number of characters allowed.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBoxEdit::get_CharSet

This method retrieves a string of valid characters.

Syntax

HRESULT get_CharSet( BSTR *pbstrCharSet );

Parameters

pbstrCharSet
Pointer to the Unicode string that contains the characters.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBoxEdit::get_Text

This method retrieves the text in the edit control.

Syntax

HRESULT get_Text( BSTR *pbstrText );

Parameters

pbstrText
Pointer to the Unicode string that contains the edit item’s text.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBoxEdit::put_MaxChars

This method sets the maximum number of characters allowed for the edit item.

Syntax

HRESULT put_MaxChars( short wcchMax );

Parameters

wcchMax
Maximum number of characters allowed.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBoxEdit::put_CharSet

This method sets a string of valid characters.

Syntax

HRESULT put_CharSet( BSTR bstrCharSet );

Parameters

bstrCharSet
Unicode string that contains the characters.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBoxEdit::put_Text

This method sets the text in the edit item.

Syntax

HRESULT put_Text( BSTR bstrText );

Parameters

bstrText
Unicode string that contains the edit item’s text.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBoxIntSpinner

This interface provides methods to manage an integer spinner item.

Method
Description
IASPowerListBoxIntSpinner::get_Flags | Retrieves whether or not the control wraps when it reaches the end of the list of integers.
IASPowerListBoxIntSpinner::get_Circular | Retrieves the integer spinner flags.
IASPowerListBoxIntSpinner::get_Max | Retrieves the maximum value for the integer spinner item.
IASPowerListBoxIntSpinner::get_Min | Retrieves the minimum value for the integer spinner item.
IASPowerListBoxIntSpinner::get_Step | Retrieves the step size used by the integer spinner item.
IASPowerListBoxIntSpinner::get_Units | Gets the units used by the integer spinner item.
IASPowerListBoxIntSpinner::get_Value | Gets the value currently displayed by the integer spinner item.
IASPowerListBoxIntSpinner::put_Circular | Sets whether or not the control wraps when it reaches the end of the list of integers.
IASPowerListBoxIntSpinner::put_Flags | Sets the integer spinner flags.
IASPowerListBoxIntSpinner::put_Max | Sets the maximum value for the integer spinner item.
IASPowerListBoxIntSpinner::put_Min | Sets the minimum value for the integer spinner item.
IASPowerListBoxIntSpinner::put_Step | Sets the step size used by the integer spinner item.
IASPowerListBoxIntSpinner::put_Units | Sets the units used by the integer spinner item.
IASPowerListBoxIntSpinner::put_Value | Sets the value currently displayed by the integer spinner item.

Remarks

The IASPowerListBoxIntSpinner interface, which has a global unique identifier equal to IID_ASPOWERLISTBOXINTSPINNER, extends the IASPowerListBoxItem interface.

See Also

IASPowerListBoxItem


IASPowerListBoxIntSpinner::get_Circular

This method retrieves whether or not the control wraps when it reaches the end of the list of integers.

Syntax

HRESULT get_Circular( BOOL *pfCircular );

Parameters

pfCircular
Pointer to a Boolean that is set to TRUE to enable wrapping, or to FALSE to disable it.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

If this property is enabled, the integer spinner control wraps from the last integer to the first or vice versa, depending on which direction the user is going.

Circular is defined as follows: If a user attempts to set the spinner control to a value greater than the maximum, the value is reset to the minimum. If a user attempts to set the spinner control to a value smaller than minimum, the value is reset to the maximum.


IASPowerListBoxIntSpinner::get_Flags

This method retrieves the integer spinner flags.

Syntax

HRESULT get_Flags( short *pwFlags );

Parameters

pwFlags
Pointer to the unsigned 16-bit integer that contains the following flags associated with the integer spinner item:
ASFC_PWRLB_FLAGS_DISPLAYSIGN
Forces a leading plus (+) sign.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBoxIntSpinner::get_Max

This method retrieves the maximum value for the integer spinner item.

Syntax

HRESULT get_Max( long *plMax );

Parameters

plMax
Pointer to the long integer that contains the maximum value for the integer spinner.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBoxIntSpinner::get_Min

This method retrieves the minimum value for the integer spinner item.

Syntax

HRESULT get_Min( long *plMin );

Parameters

plMin
Pointer to the long integer that contains the minimum value for the integer spinner.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBoxIntSpinner::get_Step

This method retrieves the step size used by the integer spinner item.

Syntax

HRESULT get_Step( long *plStep );

Parameters

plStep
Pointer to the long integer that contains the step size used by the integer spinner item.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBoxIntSpinner::get_Units

This method gets the units used by the integer spinner item.

Syntax

HRESULT get_Units ( BSTR *pbstrUnits );

Parameters

pbstrUnits
Pointer to the string that is displayed to indicate units, for example, “ft,” “sec,” and “%.”

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBoxIntSpinner::get_Value

This method gets the value currently displayed by the integer spinner item.

Syntax

HRESULT get_Value ( long *plValue );

Parameters

plValue
Pointer to the long integer that contains the value currently displayed.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBoxIntSpinner::put_Circular

This method sets whether or not the control wraps when it reaches the end of the list of integers.

Syntax

HRESULT put_Circular( BOOL fCircular );

Parameters

fCircular
Boolean that is set to TRUE to enable wrapping, or to FALSE to disable it.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

If this property is enabled, the integer spinner control wraps from the last integer to the first or vice versa, depending on which direction the user is going.


IASPowerListBoxIntSpinner::put_Flags

This method sets the integer spinner flags.

Syntax

HRESULT put_Flags( short wFlags );

Parameters

wFlags
Unsigned 16-bit integer that contains the following flags associated with the integer spinner item:
ASFC_PWRLB_FLAGS_DISPLAYSIGN
Forces a leading plus (+) sign.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBoxIntSpinner::put_Max

This method sets the maximum value for the integer spinner item.

Syntax

HRESULT put_Max( long lMax );

Parameters

lMax
Long integer that contains the maximum value for the integer spinner.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

If the passed value is less than the current minimum value, the minimum value is set to be the same as the new maximum value.


IASPowerListBoxIntSpinner::put_Min

This method sets the minimum value for the integer spinner item.

Syntax

HRESULT put_Min( long lMin );

Parameters

lMin
Long integer that contains the minimum value for the integer spinner.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

If the passed value is larger than the current maximum value, the maximum value is set to be the same as the new minimum value.


IASPowerListBoxIntSpinner::put_Step

This method sets the step size used by the integer spinner item.

Syntax

HRESULT put_Step( long lStep );

Parameters

lStep
Long integer that contains the step size used by the integer spinner item.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBoxIntSpinner::put_Units

This method sets the units used by the integer spinner item.

Syntax

HRESULT put_Units ( BSTR bstrUnits );

Parameters

bstrUnits
Unicode string that is displayed to indicate units, for example, “ft,” “sec,” and “%.”

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBoxIntSpinner::put_Value

This method sets the value currently displayed by the integer spinner item.

Syntax

HRESULT put_Value ( long lValue );

Parameters

lValue
Long integer that contains the value to be displayed.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory. E_INVALIDARG indicates that the value is out of range of the current maximum or minimum.


IASPowerListBoxItem

This interface is used to manage the items that have been added to a power list box.

Method
Description
IASPowerListBoxItem::get_Caption | Retrieves the caption associated with a particular item.
IASPowerListBoxItem::get_ItemData | Gets the data associated with the item.
IASPowerListBoxItem::get_ItemId | Retrieves the identifier of the item.
IASPowerListBoxItem::get_StatusItemsMask | Gets the mask used to specify which status items can be displayed.
IASPowerListBoxItem::get_Type | Retrieves the item type.
IASPowerListBoxItem::put_Caption | Sets the item caption.
IASPowerListBoxItem::put_ItemData | Sets the data associated with the item.
IASPowerListBoxItem::put_ItemId | Sets the identifier of the item.
IASPowerListBoxItem::put_StatusItemsMask | Sets the mask used to specify which status items can be displayed.

Remarks

The IASPowerListBoxItem interface, which has a global unique identifier (GUID) equal to IID_ASPOWERLISTBOXITEM, extends the IDispatch interface.


IASPowerListBoxItem::get_Caption

This method retrieves the caption associated with a particular item.

Syntax

HRESULT get_Caption( BSTR *pbstrCaption );

Parameters

pbstrCaption
Pointer to the Unicode string to be displayed as the caption.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBoxItem::get_ItemData

This method gets the data associated with the item.

Syntax

HRESULT get_ItemData( long *plData );

Parameters

plData
Pointer to the long integer that contains the data associated with the item.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBoxItem::get_ItemId

This method retrieves the identifier of the item.

Syntax

HRESULT get_ItemId( long *plItemId );

Parameters

plItemId
Pointer to the long integer that contains the identifier of the item.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBoxItem::get_StatusItemsMask

This method gets the mask used to specify which status items can be displayed.

Syntax

HRESULT get_StatusItemsMask( long *plMask );

Parameters

plMask
Pointer to the long integer that contains the mask that specifies which status items can be displayed.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBoxItem::get_Type

This method retrieves the item type.

Syntax

HRESULT get_Type( long *plType );

Parameters

plType
Pointer to the long integer that contains the item type. It is one of the following values:
ASFC_PWRLB_TYPE_COMMAND
Specifies a command.
ASFC_PWRLB_TYPE_EDIT
Specifies an edit box.
ASFC_PWRLB_TYPE_STRINGSPINNER
Specifies a string spinner.
ASFC_PWRLB_TYPE_INTSPINNER
Specifies an integer spinner.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBoxItem::put_Caption

This method sets the item caption.

Syntax

HRESULT put_Caption( BSTR bstrCaption );

Parameters

bstrCaption
Unicode string to be displayed as the caption.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBoxItem::put_ItemData

This method sets the data associated with the item.

Syntax

HRESULT put_ItemData( long lData );

Parameters

lData
Long integer that contains data associated with the item.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBoxItem::put_ItemId

This method sets the identifier of the item.

Syntax

HRESULT put_ItemId( long lItemId );

Parameters

lItemId
Long integer that contains the identifier of the item.

Return Values

An appropriate HRESULT value is returned.


IASPowerListBoxItem::put_StatusItemsMask

This method sets the mask used to specify which status items can be displayed.

Syntax

HRESULT put_StatusItemsMask( long lMask );

Parameters

lMask
Long integer that contains the mask that specifies which status items can be displayed.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBoxStringSpinner

This interface provides methods to manage a string spinner item.

Method
Description
IASPowerListBoxStringSpinner::get_Circular | Retrieves whether or not the control wraps when it reaches the end of the list of strings.
IASPowerListBoxStringSpinner::get_FocusIndex | Retrieves the index of the string with focus.
IASPowerListBoxStringSpinner::get_Items | Gets the strings used by the string spinner.
IASPowerListBoxStringSpinner::get_Value | Retrieves the string currently being displayed.
IASPowerListBoxStringSpinner::put_Circular | Sets whether or not the control wraps when it reaches the end of the list of strings.
IASPowerListBoxStringSpinner::put_FocusIndex | Sets the index of the string with focus.
IASPowerListBoxStringSpinner::put_Items | Sets the strings used by the string spinner.
IASPowerListBoxStringSpinner::put_Value | Sets the string currently being displayed.

Remarks

The IASPowerListboxStringSpinner interface, which has a global unique identifier (GUID) equal to IID_ASPOWERLISTBOXSTRINGSPINNER, extends the IASPowerListBox interface.


IASPowerListBoxStringSpinner::get_Circular

This method retrieves whether or not the control wraps when it reaches the end of the list of strings.

Syntax

HRESULT get_Circular( BOOL *pfCircular );

Parameters

pfCircular
Pointer to a Boolean that is set to TRUE to enable wrapping, or to FALSE to disable it.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

If this property is enabled, the string spinner control wraps from the last string to the first or vice versa, depending on which direction the user is going.


IASPowerListBoxStringSpinner::get_FocusIndex

This method retrieves the index of the string with focus.

Syntax

HRESULT get_FocusIndex( long *plFocusIndex );

Parameters

plFocusIndex
Pointer to the long integer that contains the index of the string with focus.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBoxStringSpinner::get_Items

This method gets the strings used by the string spinner.

Syntax

HRESULT get_Items( BSTR *pbstrItems );

Parameters

pbstrItems
Pointer to the Unicode string that contains the strings to be displayed, separated by a tab character.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBoxStringSpinner::get_Value

This method retrieves the string currently being displayed.

Syntax

HRESULT get_Value( BSTR *pbstrValue );

Parameters

pbstrValue
Pointer to the Unicode string currently being displayed.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBoxStringSpinner::put_Circular

This method sets whether or not the control wraps when it reaches the end of the list of strings.

Syntax

HRESULT put_Circular( BOOL fCircular );

Parameters

fCircular
Boolean that is set to TRUE to enable wrapping, or to FALSE to disable it.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

If this property is enabled, the string spinner control wraps from the last string to the first or vice versa, depending on which direction the user is going.


IASPowerListBoxStringSpinner::put_FocusIndex

This method sets the index of the string with focus.

Syntax

HRESULT put_FocusIndex( long lFocusIndex );

Parameters

lFocusIndex
Long integer that contains the index of the string with focus.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBoxStringSpinner::put_Items

This method sets the strings used by the string spinner.

Syntax

HRESULT put_Items( BSTR bstrItems );

Parameters

bstrItems
Unicode string that contains the strings to be displayed, separated by a tab character.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASPowerListBoxStringSpinner::put_Value

This method sets the string currently being displayed.

Syntax

HRESULT put_Value( BSTR bstrValue );

Parameters

bstrValue
Unicode string to be displayed.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASTabber

This interface provides methods to manage a tabber control.

Method
Description
IASTabber::Add | Adds a tab.
IASTabber::AddImage | Adds an image to the tabber control.
IASTabber::AddWithIndex | Adds a tab with an index value.
IASTabber::get_BorderColor | Retrieves the border color.
IASTabber::get_Circular | Retrieves whether or not the tabber should wrap to the first tab once the last tab has been reached.
IASTabber::get_Count | Retrieves the number of tabs.
IASTabber::get_DeferredNotification | Retrieves whether or not notification is enabled for the tabber.
IASTabber::get_FocusIndex | Retrieves the index of the tab with focus.
IASTabber::get_Image | Retrieves the image handle associated with a tab.
IASTabber::get_ItemData | Retrieves the data assigned to a tab.
IASTabber::get_SpeechCommandId | Retrieves the speech identifier assigned to a tab.
IASTabber::get_String | Gets the string associated with a specified tab.
IASTabber::get_TabColor | Retrieves the color used for tabs.
IASTabber::get_TabFocusBackColor | Retrieves the background color of the tab with focus.
IASTabber::get_TabFocusForeColor | Retrieves the foreground color of the tab with focus.
IASTabber::get_TabMinWidth | Retrieves the minimum width of the tab.
IASTabber::get_TabTextColor | Retrieves the tab text color.
IASTabber::get_VoiceMenu | Retrieves a voice menu for the tabber.
IASTabber::get_VoiceMenuActivateCommand | Retrieves a voice menu command.
IASTabber::InsertAt | Specifies where to insert a tab.
IASTabber::put_BorderColor | Sets the border color.
IASTabber::put_Circular | Sets the wrap capabilities of the tabber.
IASTabber::put_DeferredNotification | Sets whether or not notifications are enabled on a tabber.
IASTabber::put_FocusIndex | Sets the index of the tab with focus.
IASTabber::put_Image | Sets the image handle associated with a tab.
IASTabber::put_ItemData | Sets the data associated with a tab.
IASTabber::put_SpeechCommandId | Assigns a speech identifier to a tab.
IASTabber::put_String | Sets the string associated with a specified tab.
IASTabber::put_TabColor | Sets the color used for tabs.
IASTabber::put_TabFocusBackColor | Sets the background color of the tab with focus.
IASTabber::put_TabFocusForeColor | Sets the foreground color of the tab with focus.
IASTabber::put_TabMinWidth | Sets the minimum width of the tab.
IASTabber::put_TabTextColor | Sets the tab text color.
IASTabber::put_VoiceMenu | Sets a voice menu for the tabber.
IASTabber::put_VoiceMenuActivateCommand | Sets a voice menu command.
IASTabber::RemoveAll | Removes all tabs on the tabber.
IASTabber::RemoveAt | Removes a tab specified by its index.
IASTabber::SpeakFocusTab | Specifies which tab has focus, based on speech.

Remarks

The IASTabber interface, which has a global unique identifier (GUID) equal to IID_ASTABBER, extends the IASControl interface. The tabber control has a programmatic identifier equal to APC_Tab.


IASTabber::Add

This method adds a tab.

Syntax

HRESULT Add( BSTR bstr, long lData );

Parameters

bstr
Unicode string to be displayed on the tab.
lData
Long integer that contains data associated with the tab.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASTabber::AddImage

This method adds an image to the tabber control.

Syntax

HRESULT AddImage( OLE_HANDLE hImage, OLE_HANDLE hImageMask, long lData );

Parameters

hImage
Handle to the image.
hImageMask
Handle to the image list mask. The mask specifies which image in the list is displayed.
lData
Long integer that contains data associated with the tab.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASTabber::AddWithIndex

This method adds a tab with an index value.

Syntax

HRESULT AddWithIndex( BSTR bstr, long lData, long *lpIndex );

Parameters

bstr
Unicode string to be displayed on the tab.
lData
Long integer that contains data associated with the tab.
lpIndex
Long pointer to the index of the tab that the method adds.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASTabber::get_BorderColor

This method retrieves the border color.

Syntax

HRESULT get_BorderColor( OLE_COLOR *pclr );

Parameters

pclr
Pointer to the border color.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

Use the GetRValue, GetGValue, and GetBValue macros to get the color components of pclr.

See Also

GetRValue, GetGValue, GetBValue


IASTabber::get_Circular

This method retrieves whether or not the tabber should wrap to the first tab once the last tab has been reached.

Syntax

HRESULT get_Circular ( BOOL *pfCircular );

Parameters

pfCircular
Pointer to a Boolean that is set to TRUE if tab should wrap, or to FALSE if not.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASTabber::get_Count

This method retrieves the number of tabs.

Syntax

HRESULT get_Count( long *pcItems );

Parameters

pcItems
Pointer to the number of tabs.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASTabber::get_FocusIndex

This method retrieves the index of the tab with focus.

Syntax

HRESULT get_FocusIndex( long *plIndex );

Parameters

plIndex
Pointer to the long integer that contains the index of the tab with focus.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASTabber::get_DeferredNotification

This method retrieves whether or not notifications are enabled for the tabber.

Syntax

HRESULT get_DeferredNotification BOOL *pfDeferredNotification );

Parameters

pfDeferredNotification
Pointer to a Boolean that is set to TRUE if notifications are enabled, or to FALSE if not.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASTabber::get_Image

This method retrieves the image handle associated with a tab.

Syntax

HRESULT get_Image( long lIndex, OLE_HANDLE *phImage, OLE_HANDLE *phImageMask );

Parameters

lIndex
Long integer that contains the index of the tab.
phImage
Pointer to the handle to the available images.
phImageMask
Pointer to the handle to the image list mask. The mask specifies which images in the list can be displayed.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASTabber::get_ItemData

This method retrieves the data associated with a tab.

Syntax

HRESULT get_ItemData( long Index, long *plData );

Parameters

Index
Index of the tab.
plData
Pointer to the long integer that contains data associated with the tab.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASTabber::get_SpeechCommandId

This method retrieves the speech identifier assigned to a tab.

Syntax

HRESULT get_SpeechCommandId( long Index, long *plSpeechId );

Parameters

Index
Index of the tab.
plSpeechId
Pointer to the long integer that contains the speech identifier assigned to the tab.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASTabber::get_String

This method gets the string associated with a specified tab.

Syntax

HRESULT get_String( long lIndex, BSTR *pbstr );

Parameters

lIndex
Long integer that contains the index of the tab.
pbstr
Pointer to the Unicode string associated with the tab.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

A copy of the string is returned. The caller is responsible for freeing the memory associated with the allocated string.


IASTabber::get_TabColor

This method gets the color used for tabs.

Syntax

HRESULT get_TabColor( OLE_COLOR *pclr );

Parameters

pclr
Pointer to the color used for tabs.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

Use the GetRValue, GetGValue, and GetBValue macros to get the color components of pclr.

See Also

GetRValue, GetGValue, GetBValue


IASTabber::get_TabFocusBackColor

This method retrieves the background color of the tab with focus.

Syntax

HRESULT get_TabFocusBackColor( OLE_COLOR *pclr );

Parameters

pclr
Pointer to the background color of the tab with focus.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

Use the GetRValue, GetGValue, and GetBValue macros to get the color components of pclr.

See Also

GetRValue, GetGValue, GetBValue


IASTabber::get_TabFocusForeColor

This method retrieves the foreground color of the tab with focus.

Syntax

HRESULT get_TabFocusForeColor( OLE_COLOR *pclr );

Parameters

pclr
Pointer to the foreground color of the tab with focus.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

Use the GetRValue, GetGValue, and GetBValue macros to get the color components of pclr.

See Also

GetRValue, GetGValue, GetBValue


IASTabber::get_TabMinWidth

This method retrieves the minimum width of the tab.

Syntax

HRESULT get_TabMinWidth( long *plMinWidth );

Parameters

plMinWidth
Pointer to the long integer that contains the minimum width of the tab.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASTabber::get_TabTextColor

This method retrieves the tab text color.

Syntax

HRESULT get_TabTextColor( OLE_COLOR *pclr );

Parameters

pclr
Pointer to the color used for tab text.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

Use the GetRValue, GetGValue, and GetBValue macros to get the color components of pclr.

See Also

GetRValue, GetGValue, GetBValue


IASTabber::get_VoiceMenu

This method retrieves a voice menu for the tabber.

Syntax

HRESULT get_VoiceMenu( IVCmdMenu **ppVoiceMenu );

Parameters

ppVoiceMenu
Pointer to the pointer to the voice menu.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASTabber::get_VoiceMenuActivateCommand

This method retrieves a voice menu command.

Syntax

HRESULT get_VoiceMenuActivateCommand( BSTR *pbstrCommand );

Parameters

pbstrCommand
Pointer to the Unicode string that contains the voice menu command.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASTabber::InsertAt

This method specifies where to insert a tab.

Syntax

HRESULT InsertAt( long index, BSTR bstr, long lData );

Parameters

index
Index of the tab.
bstr
Unicode string to be displayed on the tab.
lData
Long integer that contains data associated with the tab.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASTabber::put_BorderColor

This method sets the border color.

Syntax

HRESULT put_BorderColor( OLE_COLOR clr );

Parameters

clr
Border color.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

Use the RGB macro to set the components of clr before passing clr to the method.

See Also

RGB


IASTabber::put_Circular

This method sets the wrap capabilities of the tabber.

Syntax

HRESULT put_Circular( BOOL fCircular );

Parameters

fCircular
Boolean that is set to TRUE if tabber should wrap, or to FALSE if not.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASTabber::put_DeferredNotification

This method specifies whether or not notifications are enabled on a tabber.

Syntax

HRESULT put_DeferredNotification( BOOL fDeferredNotification );

Parameters

fDeferredNotification
Boolean that is set to TRUE if notifications are enabled, or to FALSE if not.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASTabber::put_FocusIndex

This method sets the index of the tab with focus.

Syntax

HRESULT put_FocusIndex( long lIndex );

Parameters

lIndex
Long integer that contains the index of the tab with focus.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASTabber::put_Image

This method sets the image handle associated with a tab.

Syntax

HRESULT put_Image( long lIndex, OLE_HANDLE hImage,
OLE_HANDLE hImageMask );

Parameters

lIndex
Long integer that contains the index of the tab.
hImage
Handle to the available images.
hImageMask
Handle to the image list mask. The mask specifies which images in the list can be displayed.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASTabber::put_ItemData

This method sets the data associated with a tab.

Syntax

HRESULT put_ItemData( long Index, long lData );

Parameters

Index
Index of the tab.
lData
Long integer that contains the data associated with the tab.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASTabber::put_SpeechCommandId

This method assigns a speech identifier to a tab.

Syntax

HRESULT put_SpeechCommandId( long Index, long lSpeechId );

Parameters

Index
Index of the tab.
lSpeechId
Long integer that contains the speech identifier assigned to the tab.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASTabber::put_String

This method sets the string associated with a specified tab.

Syntax

HRESULT put_String( long lIndex, BSTR bstr );

Parameters

lIndex
Long integer that contains the index of the tab.
bstr
Unicode string associated with the tab.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

A copy of the string is returned. The caller is responsible for freeing the memory associated with the allocated string.


IASTabber::put_TabColor

This method sets the color used for tabs.

Syntax

HRESULT put_TabColor( OLE_COLOR clr );

Parameters

clr
Color used for tabs.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

Use the RGB macro to set the components of clr before passing clr to the method.

See Also

RGB


IASTabber::put_TabFocusBackColor

This method sets the background color of the tab with focus.

Syntax

HRESULT put_TabFocusBackColor( OLE_COLOR clr );

Parameters

clr
Background color of the tab with focus.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

Use the RGB macro to set the components of clr before passing clr to the method.

See Also

RGB


IASTabber::put_TabFocusForeColor

This method sets the foreground color of the tab with focus.

Syntax

HRESULT put_TabFocusForeColor( OLE_COLOR clr );

Parameters

clr
Foreground color of the tab with focus.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

Use the RGB macro to set the components of clr before passing clr to the method.

See Also

RGB


IASTabber::put_TabMinWidth

This method sets the minimum width of the tab.

Syntax

HRESULT put_TabMinWidth( long lMinWidth );

Parameters

lMinWidth
Long integer that contains the minimum width of the tab.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASTabber::put_TabTextColor

This method sets the tab text color.

Syntax

HRESULT put_TabTextColor( OLE_COLOR clr );

Parameters

clr
Color used for tab text.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

Use the RGB macro to set the components of clr before passing clr to the method.

See Also

RGB


IASTabber::put_VoiceMenu

This method sets a voice menu for the tabber.

Syntax

HRESULT put_VoiceMenu( IVCmdMenu *pVoiceMenu );

Parameters

pVoiceMenu
Pointer to the voice menu.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASTabber::put_VoiceMenuActivateCommand

This method sets a voice menu command.

Syntax

HRESULT put_VoiceMenuActivateCommand( BSTR bstrCommand );

Parameters

bstrCommand
Unicode string that specifies the voice menu command.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASTabber::RemoveAll

This method removes all tabs on the tabber.

Syntax

HRESULT RemoveAll( );

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASTabber::RemoveAt

This method removes a tab specified by its index.

Syntax

HRESULT RemoveAt( long index );

Parameters

index
Index of the tab to remove.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASTabber::SpeakFocusTab

This method specifies which tab has focus, based on speech.

Syntax

HRESULT SpeakFocusTab( );

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASVVI

This interface provides methods to manage a visual volume indicator (VVI) control.

Method
Description
IASVVI::get_Inverted | Retrieves whether the control is inverted or normal.
IASVVI::get_Mirrored | Retrieves whether or not the control is mirrored.
IASVVI::put_Inverted | Sets whether the control is inverted or normal.
IASVVI::put_Mirrored | Sets whether or not the control is mirrored.

Remarks

The IASVVI interface, which has a global unique identifier (GUID) equal to IID_ASVVI, extends the IASProgressBar interface. The visual volume indicator control has a programmatic identifier equal to APC_Vvi.


IASVVI::get_Inverted

This method retrieves whether the control is inverted or normal.

Syntax

HRESULT get_Inverted( BOOL *pfInverted );

Parameters

pfInverted
Pointer to a Boolean that is set to TRUE if the control is inverted, or to FALSE if the control is normal.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

Progress bars such as the visual volume indicator are usually drawn from left to right with a positive slope. The get_Inverted method indicates that the control is flipped upside-down.


IASVVI::get_Mirrored

This method retrieves whether or not the control is mirrored.

Syntax

HRESULT get_Mirrored( BOOL *pfMirrored );

Parameters

pfMirrored
Pointer to a Boolean that is set to TRUE if the control is mirrored, FALSE if not.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

Progress bars such as the visual volume indicator are usually drawn from left to right with a positive slope. The get_Mirrored method indicates that the control is drawn from right to left.


IASVVI::put_Inverted

This method sets whether the control is inverted or normal.

Syntax

HRESULT put_Inverted( BOOL fInverted );

Parameters

fInverted
Boolean that is set to TRUE if the control is inverted, or to FALSE if not.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

Progress bars such as the visual volume indicator are usually drawn from left to right with a positive slope. The put_Inverted method causes the control to be flipped upside-down.


IASVVI::put_Mirrored

This method sets whether or not the control is mirrored.

Syntax

HRESULT put_Mirrored( BOOL fMirrored );

Parameters

fMirrored
Boolean that is set to TRUE if the control is mirrored, or to FALSE if not.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.

Remarks

Progress bars such as the visual volume indicator are usually drawn from left to right with a positive slope. The put_Mirrored method causes the control to be drawn from right to left.


IASHTMLControl

This interface provides methods to manage an HTML control.

Method
Description
IASHTMLControl::get_HTML | Retrieves the current HTML string.
IASHTMLControl::get_HTMLNotifySink | Retrieves a pointer to the HTML notification sink.
IASHTMLControl::get_Style | Retrieves the style flags for the control.
IASHTMLControl::get_VisibleRect | Retrieves a RECT structure that defines the currently visible portion of the HTML document.
IASHTMLControl::HScroll | Controls horizontal scrolling.
IASHTMLControl::ImageFail | Invoked if an application is unable to load an image.
IASHTMLControl::JumpToAnchor | Jumps to an anchor elsewhere in the document.
IASHTMLControl::put_HTML | Displays an HTML formatted string.
IASHTMLControl::put_HTMLNotifySink | Receives HTML events from the control.
IASHTMLControl::put_Style | Sets the style flags for the control.
IASHTMLControl::ScrollIntoView | Scrolls an image into view.
IASHTMLControl::put_Image | Displays an image.
IASHTMLControl::VScroll | Controls vertical scrolling.

Remarks

The IASHTMLControl interface, which has a global unique identifier (GUID) equal to IID_ASHTMLCONTROL, extends the IASControl interface. All IASControl methods are available through IASHTMLControl. The HTML control has a programmatic identifier equal to APC_HTMLControl.

This interface allows an application to display HTML-formatted documents. If an IAPCSpeech interface is defined and registered with the control, text-to-speech can be used to read the document aloud.


IASHTMLControl::get_HTML

This method retrieves the current HTML string.

Syntax

HRESULT get_HTML( BSTR *pbstrHTML );

Parameters

pbstrHTML
Pointer to an HTML-formatted string.

Return Values

An appropriate HRESULT value is returned.

Remarks

If pbstrHTML is set, the contents of pbstrHTML are currently being displayed.


IASHTMLControl::get_HTMLNotifySink

This method retrieves a pointer to the HTML notification sink.

Syntax

HRESULT get_HTMLNotifySink ( IASHTMLControlNotifySink **ppNotify );

Parameters

ppNotify
Pointer to the pointer to the control’s notification sink.

Return Values

An appropriate HRESULT value is returned.

See Also

IASHTMLControlNotifySink


IASHTMLControl::get_Style

This method retrieves the style flags for the control.

Syntax

HRESULT get_Style( DWORD *pdwStyle );

Parameters

pdwStyle
Pointer to the DWORD that specifies the style of the control. It is any combination of the following flags:
ASFC_HTML_SPEAK_TITLE
Includes the title in text-to-speech (TTS) output.
ASFC_HTML_SPEAK_BODY
Includes all body text in TTS output.
ASFC_HTML_SHOW_HSCROLL
Displays horizontal scroll arrows, when appropriate.
ASFC_HTML_SHOW_VSCROLL
Displays vertical scroll arrows, when appropriate.
ASFC_HTML_SHOW_ANCHORS
Displays the anchors.

Return Values

An appropriate HRESULT value is returned.


IASHTMLControl::get_VisibleRect

This method retrieves a RECT structure that defines the currently visible portion of the HTML document.

Syntax

HRESULT get_VisibleRect ( RECT *rcVisible );

Parameters

rcVisible
RECT structure that defines the currently visible portion of the document.

Return Values

An appropriate HRESULT value is returned.

Remarks

The first two members of the rcVisible RECT structure contain the current HScroll and VScroll values, respectively. They define the upper-left corner of the visible rectangle.


IASHTMLControl::HScroll

This method controls horizontal scrolling.

Syntax

HRESULT HScroll ( WPARAM wp );

Parameters

wp
Specifies horizontal scrolling styles. The low-order word of wp is one of the following values:
SB_BOTTOM
Scrolls to the bottom or to the right side of the document.
SB_LINEDOWN
Scrolls down or right one line, or approximately 16 pixels.
SB_LINEUP
Scrolls up or left one line, or approximately 16 pixels.
SB_PAGEDOWN
Scrolls down or right one page, or the height of the control.
SB_PAGEUP
Scrolls up or left one page, or the height of the control.
SB_THUMBTRACK
Scrolls to an absolute horizontal position in the document. The high-order word of wp specifies the position.
SB_TOP
Scrolls to the top or left side of the document.

Return Values

An appropriate HRESULT value is returned.

See Also

HIWORD, LOWORD


IASHTMLControl::ImageFail

This method is invoked if an application is unable to load an image.

Syntax

HRESULT ImageFail ( DWORD dwCookie );

Parameters

dwCookie
Specifies a cookie that identifies the image. It is passed to the application through the IASHTMLControlNotifySink::InlineImage function when an image is encountered.

Return Values

An appropriate HRESULT value is returned.

Remarks

This method informs the control that it should change from displaying “is loading” to displaying “load failed.”

See Also

IASHTMLControl::put_Image, IASHTMLControlNotifySink::InlineImage


IASHTMLControl::JumpToAnchor

This method jumps to an anchor elsewhere in the document.

Syntax

HRESULT JumpToAnchor ( BSTR bstrAnchor );

Parameters

bstrAnchor
HTML-formatted string that identifies the anchor.

Return Values

An appropriate HRESULT value is returned.


IASHTMLControl::put_HTML

This method displays an HTML-formatted string.

Syntax

HRESULT put_HTML( BSTR bstrHTML );

Parameters

pbstrHTML
Pointer to an HTML-formatted string.

Return Values

An appropriate HRESULT value is returned.

Remarks

This method is similar to IASControl::put_Caption, but is used to display HTML-formatted text. When the property is changed, the control is repainted with the new text. Use IASControl::put_Caption to display a plain text string. Appropriate HTML tags are added.

See Also

IASControl::put_Caption


IASHTMLControl::put_HTMLNotifySink

This method receives HTML events from the control.

Syntax

HRESULT put_HTMLNotifySink ( IASHTMLControlNotifySink **ppNotify );

Parameters

ppNotify
Pointer to the pointer to the control’s notification sink.

Return Values

An appropriate HRESULT value is returned.

Remarks

HTML events that put_HTMLNotifySink might receive include requests to load images and HTML META tags.

See Also

IASHTMLControlNotifySink


IASHTMLControl::put_Style

This method sets style flags for the control.

Syntax

HRESULT get_Style( DWORD dwStyle );

Parameters

dwStyle
Specifies the style of the control. It is any combination of the following flags:
ASFC_HTML_SPEAK_TITLE
Includes the title in text-to-speech (TTS) output.
ASFC_HTML_SPEAK_BODY
Includes all body text in TTS output.
ASFC_HTML_SHOW_HSCROLL
Displays horizontal scroll arrows, when appropriate.
ASFC_HTML_SHOW_VSCROLL
Displays vertical scroll arrows, when appropriate.
ASFC_HTML_SHOW_ANCHORS
Displays the anchors.

Return Values

An appropriate HRESULT value is returned.


IASHTMLControl::ScrollIntoView

This method scrolls an image into view.

Syntax

HRESULT ScrollIntoView ( DWORD dwCookie );

Parameters

dwCookie
Specifies a cookie that identifies the image. It is passed to the application through the IASHTMLControlNotifySink::InlineImage function when an image is encountered.

Return Values

An appropriate HRESULT value is returned.


IASHTMLControl::put_Image

This method displays an image.

Syntax

HRESULT put_Image ( DWORD dwCookie, BOOL bOwnBitmap, long lOrigHeight, long lOrigWidth, OLE_HANDLE hBitmap );

Parameters

dwCookie
Specifies a cookie that identifies the image. It is passed to the application through the IASHTMLControlNotifySink::InlineImage function when an image is encountered.
bOwnBitmap
Boolean that is set to TRUE if the bitmap is to be destroyed after use, or to FALSE if the bitmap is to be used again.
lOrigHeight
Long integer that contains the height of the original bitmap. The displayed height may be different.
lOrigWidth
Long integer that contains the width of the original bitmap. The displayed width may be different.
hBitmap
Handle to the bitmap.

Return Values

An appropriate HRESULT value is returned.


IASHTMLControl::VScroll

This method controls vertical scrolling.

Syntax

HRESULT VScroll ( WPARAM wp );

Parameters

wp
Specifies vertical scrolling styles. The low-order word of wp is one of the following values:
SB_BOTTOM
Scrolls to the bottom or to the right side of the document.
SB_LINEDOWN
Scrolls down or right one line, or approximately 16 pixels.
SB_LINEUP
Scrolls up or left one line, or approximately 16 pixels.
SB_PAGEDOWN
Scrolls down or right one page, or the height of the control.
SB_PAGEUP
Scrolls up or left one page, or the height of the control.
SB_THUMBTRACK
Scrolls to an absolute vertical position in the document. The high-order word of wp specifies the position.
SB_TOP
Scrolls to the top or left side of the document.

Return Values

An appropriate HRESULT value is returned.

See Also

HIWORD, LOWORD


IASHTMLControlNotifySink

This interface provides methods that are used to notify applications of HTML-related events.

Method
Description
IASHTMLControlNotifySink::HotSpot | Invoked when a hot spot is encountered
IASHTMLControlNotifySink::InlineImage | Invoked when an inline image is encountered
IASHTMLControlNotifySink::Meta | Invoked when a META tag is encountered
IASHTMLControlNotifySink::PlaySound | Invoked when a sound tag is encountered.
IASHTMLControlNotifySink::Title | Invoked when a title is encountered.

Remarks

The IASHTMLControlNotifySink interface, which has a global unique identifier (GUID) equal to IID_ASHTMLCONTROLNOTIFYSINK, extends the IDispatch interface. To receive HTML events, applications must implement an event sink according to this definition, and register it with IASHTMLControl by putting a pointer to the sink in the NotifySink property.

See Also

IASHTMLControl::put_HTMLNotifySink


IASHTMLControlNotifySink::HotSpot

This method is invoked when a hot spot is encountered.

Syntax

HRESULT HotSpot( IASHTMLControl *pControl, BSTR bstrTarget, BSTR bstrData );

Parameters

pControl
Pointer to the active HTML control.
bstrTarget
HTML-formatted target string.
bstrData
HTML-formatted data string associated with the target.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASHTMLControlNotifySink::InlineImage

This method is invoked when an inline image is encountered.

Syntax

HRESULT InlineImage ( IASHTMLControl *pControl, BSTR bstrTarget,
DWORD dwCookie );

Parameters

pControl
Pointer to the active HTML control.
bstrTarget
HTML-formatted target string.
dwCookie
Specifies a cookie that identifies the image. It is passed to the application through the IASHTMLControlNotifySink::InlineImage function when an image is encountered.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASHTMLControlNotifySink::Meta

This method is invoked when a META tag is encountered.

Syntax

HRESULT Meta( IASHTMLControl *pControl, BSTR bstrHTTPEQUIV,
BSTR bstrContent );

Parameters

pControl
Pointer to the active HTML control.
bstrHTTPEQUIV
String containing the value of the HTTP-EQUIV attribute of the META tag.
bstrContent
String containing the value of the CONTENT attribute of the META tag.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.


IASHTMLControlNotifySink::PlaySound

This method is invoked when a sound tag is encountered.

Syntax

HRESULT StoreUsed( IASHTMLControl *pControl BSTR bstrTarget int iLoop );

Parameters

pControl
Pointer to the active HTML control.
bstrTarget
HTML-formatted target string.
iLoop
Number of repetitions.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IASHTMLControlNotifySink::Title

This method is invoked when a title is encountered.

Syntax

HRESULT Title( IASHTMLControl *pControl BSTR bstrTitle );

Parameters

pControl
Pointer to the active HTML control.
bstrTitle
HTML-formatted title string.

Return Values

NOERROR indicates success. E_OUTOFMEMORY indicates that the system is out of memory.


IAPCSpeech

This interface is a high level Auto PC simple speech interface.

Implement the IAPCSpeech interface in one of the following ways:

  • Call the IfmManage::get_Speech method of the Forms Manager if you want the speech notification to come through the regular class message sink or event sink.
  • Call the CreateAPCSpeech function to get the IAPCSpeech interface only if your application wants the speech notifications to be sent to the application thread directly.
Method
Description
IAPCSpeech::AddRef | Increments the reference count for an interface on a speech object.
IAPCSpeech::AddVMenuCommand | Adds commands from a resource file to a voice menu.
IAPCSpeech::AddVMenuCommandsFromResource | Adds commands to the voice menu from a resource file.
IAPCSpeech::AttribGet | Gets speech related settings.
IAPCSpeech::AttribSet | Sets or changes speech related settings.
IAPCSpeech::CreateSpkContext | Creates a new speak context, which allows an application to do Text-to-Speech (TTS) pre-text normalization.
IAPCSpeech::CreateVMenu | Creates a voice menu.
IAPCSpeech::DestroySpkContext | Destroys a speak context.
IAPCSpeech::PlaySound | Plays a canned speech sound file.
IAPCSpeech::QueryFeedbackLevel | Retrieves the feedback level for key response and for voice commands.
IAPCSpeech::QueryInterface | Retrieves a pointer to a IAPCSpeech interface.
IAPCSpeech::QuerySpeakingMode | Gets whether or not the operating system is playing a text-to-speech (TTS) phrase or prerecorded speech.
IAPCSpeech::QuerySpeechInterface | Queries for the voice command and voice text interfaces.
IAPCSpeech::Release | Decrements the reference count for the calling interface on a speech object.
IAPCSpeech::SetMsgOptions | Sets options for message notifications.
IAPCSpeech::SetSpkContextRule | Sets a context rule used to normalize a text string before sending the string to the text-to-speech (TTS) engine.
IAPCSpeech::Speak | Speaks the null-terminated string stored in pszSpeak using text-to-speech (TTS)
IAPCSpeech::SpeakEx | Speaks the null-terminated string stored in pszSpeak using text-to-speech (TTS), with more options.
IAPCSpeech::Train | Trains the application to recognize a user command, and deals with only one command at a time.
IAPCSpeech::VoiceHelpStart | Called by the shell to start voice Help.
IAPCSpeech::VoiceHelpStop | Called by the shell to stop voice Help.


IAPCSpeech::AddRef

This method increments the reference count for an interface on a speech object.

Syntax

HRESULT IAPCSpeech::AddRef( THIS );

Return Values

An appropriate HRESULT value is returned.


IAPCSpeech::AddVMenuCommand

This method adds a command to the voice menu.

Syntax

HRESULT IAPCSpeech::AddVMenuCommand( PIVCMDMENUW pMenu, LPTSTR szCmdString, UINT dwCmdID, DWORD dwFlags, DWORD dwVoiceCommand );

Parameters

pMenu
Pointer to the menu to which a command is to be added.
szCmdString
Null-terminated string that contains the command that is to be added to pMenu. The command string added to a voice menu includes three parts: command, long voice Help and short voice Help. The three parts are separated by a tab. The following table shows possible combinations.
Command
Description
cmd\tlong Help\tshort Help | Has both long and short voice Help.
cmd | There is no long voice Help, and short voice Help is the same as command.
cmd\t\tshort Help | There is no long voice Help, and short voice Help is different from command.
cmd\tlong Help\t | Has long voice Help but no short voice Help.
cmd\tlong Help | Has long voice Help, and short voice Help is the same as command.

dwCmdID
Specifies the command identifier that is to be added to the voice menu.
dwFlags
Specifies a bitmask for flags. It is one of the following values:
APCSPCH_VM_USEEXISTING
If this flag is set and the command identifier already exists in the voice menu, the command is not added.
APCSPCH_VM_NOFEEDBACK
Use this flag if the application does not want the system to provide the regular feedback to this word
dwVoiceCommand
Application developer can associate a DWORD with the voice command. When the command is recognized, this DWORD is notified in the wParam of WM_SPCH_RECOG. The lParam is the command identifier.

Return Values

An appropriate HRESULT value is returned.

Remarks

To avoid duplicating string identifiers if your application uses speech enabled controls, use the ranges shown in the following table to assign string identifiers in resource file.

String identifier
Range
Application | 0 to 0x7FFF
Speech enabled controls | 0x8000 to 0xFFFF

The string that is passed can be separated by a tab to include context-sensitive long voice Help and short voice Help strings. For more information, see VoiceHelpStart.


IAPCSpeech::AddVMenuCommandsFromResource

This method adds commands from a resource file to a voice menu.

Syntax

HRESULT IAPCSpeech::AddVMenuCommandFromResource( PIVCMDMENUW pVMenu, HINSTANCE hinst, PCWSTR pszMenuName, DWORD dwMenuState, DWORD dwFlag );

Parameters

pVMenu
Pointer to the menu to which commands are to be added.
hinst
Handle to the application instance.
pszMenuName
Pointer to the null-terminated string that contains the name of the menu.
dwMenuState
Specifies a DWORD that contains the state of the menu.
dwFlag
Specifies a DWORD that contains a flag.

Return Values

An appropriate HRESULT value is returned.

Remarks

Voice menus can be defined in a resource file. Each menu item has a string, an identifier, and a state. Create a voice menu with CreateVMenu passing in a null list of grammar identifiers. Then call AddVMenuCommandsFromResource, passing in your resource identifier and instance. The items are added to the existing menu, as shown in the following code example:

// Create a voice menu resource.
IDVM_ASEDIT MENUEX PRELOAD DISCARDABLE
BEGIN
    MENUITEM "One\tTo enter numbers, say Zero through Nine", VC_ONE,
    0, VMS_NUMBERS
    MENUITEM "Two", VC_TWO, 0, VMS_NUMBERS
    MENUITEM "Three", VC_THREE, 0, VMS_NUMBERS
    MENUITEM "Four", VC_FOUR, 0, VMS_NUMBERS
    MENUITEM "Five", VC_FIVE, 0, VMS_NUMBERS
    MENUITEM "Six", VC_SIX, 0, VMS_NUMBERS
    MENUITEM "Seven", VC_SEVEN, 0, VMS_NUMBERS
    MENUITEM "Eight", VC_EIGHT, 0, VMS_NUMBERS
    MENUITEM "Nine", VC_NINE, 0, VMS_NUMBERS
    MENUITEM "Zero", VC_ZERO, 0, VMS_NUMBERS
    MENUITEM "Review\tTo read what you have entered, say Review"
    VC_REVIEW, 0, VMS_REVIEW
    MENUITEM "Delete\tTo remove the current character, say Delete",
    VC_DELETE, 0, VMS_DELETE
    MENUITEM "Ok\tTo keep your changes, say Okay", VC_OK, 0, VMS_OK
    MENUITEM "Cancel\tTo cancel your changes, say Cancel", VC_CANCEL, 0,
    VMS_CANCEL
END
// IDVM_ASEDIT and all of the VMS_* parameters are specific to the
// application. The last flag enables the application to
// define multiple states in which the menu can be loaded. Therefore,
// one menu resource can be used to load two voice menus: one for an edit mode and one for a review mode, if both exist.

// Create an empty voice menu.
CreateVMenu(
    NULL,
    &vn,
    m_hInst,
    0,
    NULL,
    APCSPCH_VM_USEEXISTING,
    &m_pVoiceMenuCards );

// Load in an voice command from a resource.
    if (SUCCEEDED( hr))
    {
    hr = m_pSpeech->AddVMenuCommandsFromResource(
    m_pVoiceMenuCards, m_hInst,
MAKEINTRESOURCE(IDVM_CARDS), 0, APCSPCH_VM_USEEXISTING);
    }
// By loading a menu from a resource file, you can use the same voice command and corresponding identifier in several applications, even though the voice command may differ in each. For example, the word PREVIOUS can have the same identifier whether it moves you back a screen in one application and restores the former settings of another application. Loading a menu from a resource file also enables more consistent coding, and enables the voice command to behave like a keystroke rather than a custom identifier.


IAPCSpeech::AttribGet

This method gets speech related settings.

Syntax

HRESULT IAPCSpeech::AttribGet( DWORD dwAttrib, PDWORD pdwMisc );

Parameters

dwAttrib
An application passes the IVANSAC_TTSPITCH flag to get the current text-to-speech (TTS) pitch.
pdwMisc
Pointer to the DWORD that contains the desired pitch value.

Return Values

An appropriate HRESULT value is returned.

Remarks

The AttribGet and AttribSet methods are now called by the shell and the Control Panel applications. Your application should not call them.


IAPCSpeech::AttribSet

This method sets or changes speech related settings.

Syntax

HRESULT IAPCSpeech::AttribGet( DWORD dwAttrib, DWORD dwMisc );

Parameters

dwAttrib
An application passes the IVANSAC_TTSPITCH flag to get the current text-to-speech (TTS) pitch.
dwMisc
Specifies the desired pitch value.

Return Values

An appropriate HRESULT value is returned.

Remarks

The AttribGet and AttribSet methods are now called by the shell and the Control Panel applications. Your application should not call them.


IAPCSpeech::CreateSpkContext

This method creates a new speak context, which allows an application to do pre-text normalization.

Syntax

HRESULT IAPCSpeech::CreateSpkContext ( IAPCSpeech *pSpeech, DWORD dwContext, DWORD dwFlag PDWORD *pNewContext );

Parameters

pSpeech
Pointer to a speech object that contains the dwContext to be copied; used only with APCSPCH_TN_CONTEXT_COPY.
dwContext
Specifies the context identifier of the newly created context that is copied or extended. It is ignored if dwFlag is APCSPCH_TN_CONTEXT_NEW.
dwFlag
Specifies a bitmask of flags. It is one of the following values:
Flag
Value
Description
APCSPCH_TN_CONTEXT_NEW | 0x0001 | Creates a new empty context.
APCSPCH_TN_CONTEXT_COPY | 0x0002 | Creates a new context based on an existing context by copying all the rules from the existing context.
APCSPCH_TN_CONTEXT_EXTEND | 0x0003 | Extends a new context by linking it to an existing one.

pNewContext
Pointer to the identifier of the newly created context if S_OK is returned.

Return Values

S_OK indicates success.

Remarks

An application does not need to create a new speak context in order to use text-to-speech (TTS) because, by default, there is always one speak context with an identifier of 0. An application can also create additional contexts and use IAPCSpeech::SpeakEx to use the new contexts.

When APCSPCH_TN_CONTEXT_EXTEND is used, it can only extend rules of APCSPCH_TN_WORD.

A context can only be extended once.

See Also

IAPCSpeech::SetSpkContextRule


IAPCSpeech::CreateVMenu

This method creates a voice menu.

Syntax

HRESULT IAPCSpeech::CreateVMenu( PIVOICECMDW pVCmd, VCMDNAME lpName, HINSTANCE hInst, DWORD dwCmdCnt, LPVOID pCmdTable, DWORD dwFlags, PIVCMDMENUW* ppVMenu );

Parameters

pVCmd
Pointer to a voice command. This parameter should be NULL unless the application creates the voice command.
lpName
Long pointer to a unique VCMDNAME data type for each Apcspch object.
hInst
Handle to the application or dynamic link library instance.
dwCmdCnt
DWORD that indicates the total number of items in the array pointed to by pCmdTable.
pCmdTable
Pointer to an array table of resource string identifiers.
dwFlags
Bitmask of flags. Set to 0 or to APCSPCH_VM_USEEXISTING.

When APCSPCH_VM_USEEXISTING is set and the application finds that the menu already exists, it uses the menu stored in the storage file. You can still pass in the string table pointer, but it is ignored if the APCSPCH_VM_USEEXISTING flag is set and there are commands in the menu.

If a voice menu can be loaded or activated by two processes at the same time, the menu has to be created using the APCSPCH_VM_USEEXISTING flag.

If the menu is created using APCSPCH_VM_USEEXISTING flag, the calls to AddVMenuCommand must pass APCSPCH_VM_USEEXISTING.

ppVMenu
Pointer to a pointer to a voice menu.

Return Values

An appropriate HRESULT value is returned.

Remarks

The second parameter of the CreateVMenu method is the VCMDNAME structure, which contains both the application name and menu name. The application has to pass both the application name—essentially, a context name—and menu name when creating a voice menu. For example, when the edit control creates a menu, it can use the application name “EditCtrl,” and an address book DLL can use the application name “AddrBook.”

When a control or shared DLL wants to create a menu that is shared across all the instances, it should use the flag APCSPCH_VM_USEEXISTING and pass in the same application name and menu name in every instance of the control. However, if a control has a different voice menu in different instances, it should use a unique menu name. If not, the CreateVMenu fails and returns a VCMDERR_MENUEXIST error value.

The caller is responsible for releasing the menu object by calling Release. To create a default menu, pVCmd should be NULL. If the application has another voice command, it can pass it to pVCmd.

The application should call the Activate and Deactivate methods to activate or deactivate the application grammar.


IAPCSpeech::DestroySpkContext

This method destroys a speak context.

Syntax

HRESULT IAPCSpeech::DestroySpkContext ( DWORD dwContext, DWORD dwFlag );

Parameters

dwContext
Specifies the speech context.
dwFlag
Reserved; set to 0.

Return Values

An appropriate HRESULT value is returned.


IAPCSpeech::PlaySound

This method plays a prerecorded speech sound file.

Syntax

HRESULT IAPCSpeech::PlaySound ( LPCWSTR lpcwSound, HMODULE hModule, DWORD dwSound, DWORD dwReserved );

Parameters

lpcwSound
Long pointer to a string that specifies the sound file to play.
hModule
Handle of the executable file that contains the resource to be loaded.
dwSound
Specifies the flag for playing the sound.

The following values are defined:
SND_APPLICATION | SND_NODEFAULT
SND_ALIAS | SND_NOSTOP
SND_ALIAS_ID | SND_NOWAIT
SND_ASYNC | SND_PURGE
SND_FILENAME | SND_RESOURCE
SND_LOOP | SND_SYNC
SND_MEMORY

For more information about these flags, see the Windows CE PlaySound function.

dwReserved
If this parameter is nonzero, the application receives a WM_SPCH_SNDDONE message when the wave file is finished playing. If it is set to zero, no message is sent.

Return Values

An appropriate HRESULT value is returned.

Remarks

Always use this method to play prerecorded speech. Besides playing the sound file, this method also attenuates the music and disables speech recognition during playback. This method uses the same waveform (WAV) output device as the text-to-speech (TTS) engine. If TTS is playing, IAPCSpeech::PlaySound stops TTS. TTS also stops the Windows CE PlaySound function if that function is in progress. For event sounds, use the Windows CE sndPlaySound function, which uses a different WAV output device than IAPCSpeech::PlaySound and TTS.

See Also

PlaySound , sndPlaySound


IAPCSpeech::QueryFeedbackLevel

This method retrieves a description of the amount of information and detail provided in the feedback for key response and for voice commands.

Syntax

HRESULT IAPCSpeech::QueryFeedbackLevel( DWORD *pKeyFeedback, DWORD *pVoiceFeedback, DWORD *pReserved, DWORD dwFlag );-

Parameters

pKeyFeedback
Pointer to a DWORD that receives a description of the amount of information and detail provided in the feedback for key response. It is one of the following values.
APCSPCH_FB_MORE
Provides a greater amount of feedback than APCSPCH_FB_LESS, usually adding either text-to speech (TTS) feedback or prerecorded speech feedback after the speech recognition tone. This additional feedback usually consists of application-specific information or the name of the application currently in use.
APCSPCH_FB_LESS
Provides minimal feedback.
pVoiceFeedback
Pointer to a DWORD that receives a description of the amount of information and detail provided in the feedback for voice commands. It is one of the following values.
APCSPCH_FB_MORE
Provides a greater amount of feedback than APCSPCH_FB_LESS, usually adding either text-to speech (TTS) feedback or prerecorded speech feedback after the speech recognition tone. This additional feedback usually consists of application-specific information or the name of the application currently in use.
APCSPCH_FB_LESS
Provides minimal feedback.
pReserved
Reserved for future use; set to 0.
dwFlag
Reserved for future use; set to 0.

Return Values

NOERROR indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

An application does not need to call this method every time the application provides speech feedback. Instead, an application should only call this method during the initialization of the application. If the feedback level changes, the application receives a WM_SETTINGCHANGE message that has a wParam value equal to SPI_SETAPCFEEDBACK and a lParam value equal to NULL. An application should call IAPCSpeech::QueryFeedbackLevel again when the application receives this WM_SETTINGCHANGE message.

The IAPCSpeech interface always plays the feedback tone when hearing a voice command. When the application receives notification of the voice command, the application should play a text-to-speech (TTS) phrase or prerecorded speech if pVoiceFeedback is APCSPCH_FB_MORE.

For version 1.0, an application usually does not need to call this method to provide appropriate feedback information, because the shell and the form manager provide most of the feedback for the application. Additionally, the application receives a WM_SPCH_FEEDBACK message containing the feedback level in the low order word of the wParam of the message.

See Also

IfmManage, IASControl::Speak, WM_SPCH_FEEDBACK, WM_SETTINGCHANGE


IAPCSpeech::QueryInterface

This method retrieves a pointer to a IAPCSpeech interface.

Syntax

HRESULT IAPCSpeech::QueryInterface( REFIID riid, LPVOID FAR* ppvObj );

Parameters

riid
[in] Specifies the interface identifier (IID) of the interface being requested.
ppvObj
[out] Pointer to an interface pointer to the object on return. If the interface specified in riid is not supported by the object, ppvObject is set to NULL.

Return Values

An appropriate HRESULT value is returned.


IAPCSpeech::QuerySpeakingMode

This method gets whether or not the operating system is playing a text-to-speech (TTS) phrase or prerecorded speech.

Syntax

HRESULT IAPCSpeech::QuerySpeakingMode( DWORD *pdwMode );

Parameters

pdwMode
Pointer to a DWORD that indicates the current mode for speech. It is one of the following values.
0
The operating system (OS) is playing neither a TTS phrase nor prerecorded speech.
APCSPCH_SP_TTS
The OS is playing TTS.
APCSPCH_SP_WAVEFILE
The OS is playing a waveform (WAV) file containing prerecorded speech.

Return Values

NOERROR indicates success. VCMDERR_INVALIDPARAM indicates that pdwMode is not a valid write pointer.


IAPCSpeech::QuerySpeechInterface

This method queries for the voice command and voice text interfaces.

Syntax

HRESULT IAPCSpeech::QueryInterface( REFIID riid, LPVOID FAR* ppvObj );

Parameters

riid
[in] Specifies the interface identifier (IID) of the interface being requested.
ppvObj
[out] Pointer to an interface pointer to the object on return. If the interface specified in riid is not supported by the object, ppvObject is set to NULL.

Return Values

An appropriate HRESULT value is returned.

Remarks

The application can call QuerySpeechInterface to obtain the IID_IVoiceCmd, IID_IVoiceText, and other related voice command and voice text interface pointers.

The speech object registers a notification sink; therefore, it is not necessary or possible to register your own using a voice command and voice text interface pointer.


IAPCSpeech::Release

This method decrements the reference count for the calling interface on a speech object.

Syntax

HRESULT IAPCSpeech::Release( THIS );

Return Values

An appropriate HRESULT value is returned.


IAPCSpeech::SetMsgOptions

This method sets options for message notifications.

Syntax

HRESULT IAPCSpeech::SetMsgOptions ( DWORD dwFlags, DWORD dwVCmdOpt, DWORD dwVTxtOpt );

Parameters

dwFlags
Reserved; set to 0.
dwVCmdOpt
Specifies options for the voice command notifications. It is one or a both of the following values:
VCMDRF_CMDOTHER
VCMDRF_CMDSTART

dwVCmdOpt
Specifies options for the voice text notifications. It is one or a combination of the following values:
VTXTF_SPEAKSTART
VTXTF_SPEAKDONE

Return Values

An appropriate HRESULT value is returned.

Remarks

By default, the applications always receive the following speech notifications:

  • WM_SPCH_RECOG, where wParam is the DWORD associated with the command and lParam is the command identifier.
  • WM_SPCH_SNDDONE indicates that the wave file played by sndPlaySound is done.
  • WM_SPCH_NOTIFY, where wParam equals VCMDRF_ATTRIBCHANGE, VTXTF_SPEAK, or VTXT_SPEAKSTOP.

SetMsgOptions can be used to enable an application to receive in wParam the four additional WM_SPCH_NOTIFY messages set in dwVCmdOpt and dwVCmdOpt.

Once SetMsgOptions has been called with VTXTF_SPEAKSTART, VTXTF_SPEAKSTOP, or both, it cannot be called again to reset the option.

See Also

sndPlaySound


IAPCSpeech::SetSpkContextRule

This method sets a context rule used to normalize a text string before sending the string to the text-to-speech (TTS) engine.

Syntax

HRESULT IAPCSpeech::SetSpkContextRule ( DWORD dwContextID, DWORD dwFlags, LPCTSTR lpctStr1, LPCTSTR lpctStr2, LPVOID p );

Parameters

dwContextID
Specifies the identifier of the context that new rule belongs to.
dwFlags
Specifies a bitmask for flags. It is one of the following values:
APCSPCH_TN_ADDR_CTX
Used with an address context.
APCSPCH_TN_PHONE_CTX
Used with a telephone context. When text contains three numbers and a dash, it is interpreted as a phone number.
APCSPCH_TN_SPELLING_CTX
Spells out a string letter by letter.
APCSPCH_TN_WORD
Replaces or deletes a word.
lpctStr1
Long pointer to the string to be replaced.
lpctStr2
Long pointer to the string that replaces lpctStr1. If NULL, lpctStr1 is removed.
p
Reserved; set to 0.

Return Values

An appropriate HRESULT value is returned.

Remarks

The following can be used as delimiters for this method:

  • White space
  • Commas
  • Periods
  • Backslashes

In an address. numbers are usually pronounced differently. For example, 98052 would be “9-8-0-5-2,” while 5345 would be “fifty-three forty-five.” To use this special context, the application can create a text-to-speech (TTS) context and pass APCSPCH_TN_ADDR_CTX as the dwFlag in the SetSpkContextRule method.

For APCSPCH_TN_PHONE_CTX, the TTS engine pronounces the pound sign (#) as "pound," and the asterisk (*) as "star." The left brace, right brace, left bracket, right bracket, left parenthesis, right parenthesis, comma, period, caret, and space characters result in a pause in speech. The TTS engine combines multiple pauses into a single pause. The TTS engine always pronounces the number 0 as "zero." The TTS engine pronounces digits and letters individually, rather than stringing them together as large numbers or words.

If APCSPCH_TN_PHONE_CTX or APCSPCH_TN_SPELLING is set, all other flags are ignored.

APCSPCH_TN_WORD and APCSPCH_TN_ADDR_CTX can be combined.


IAPCSpeech::Speak

This method speaks the null-terminated string stored in pszSpeak using text-to-speech (TTS).

Syntax

HRESULT IAPCSpeech::Speak( WCHAR* pszSpeak, DWORD dwID );

Parameters

pszSpeak
Pointer to the null-terminated string that contains the text to be spoken. The length of the string must be less than 2 kilobytes (KB). Strings longer than 2 KB cause unexpected speech behavior.
wID
Unsigned 16-bit integer that contains the bookmark identifier. This parameter is ignored if it is 0.

Return Values

An appropriate HRESULT value is returned.

Remarks

If the parameter is NULL, speech output is stopped.

This method always uses the default speak context, which is 0.


IAPCSpeech::SpeakEx

This method speaks the null-terminated string stored in pszSpeak using text-to-speech (TTS).

Syntax

HRESULT IAPCSpeech::SpeakEx( DWORD dwContext, WCHAR *pszSpeak, DWORD dwID, DWORD dwFlag, PVOID p );

Parameters

dwContext
Specifies the context to use for text normalization while speaking phrase.
pszSpeak
Pointer to the null-terminated string that contains the text to be spoken. The length of the string must be less than 2 kilobytes (KB). Strings longer than 2 KB cause unexpected speech behavior.
dwID
Specifies the bookmark identifier. This parameter is ignored if it is 0.
dwFlag
Specifies a bitmask of flags. It is one of the following values:
0
Plays the TTS in the foreground and does not spell out words or speak individual digits. This value is the default value.
APCSPCH_SP_BACKGROUND
Plays the TTS in the background, preventing interruptions caused by normal keystrokes or by a PUSH TO TALK button.
APCSPCH_TN_SPELLING_CTX
Speaks the letters and digits in pszSpeak individually, instead of using words or using numbers larger than 9.
p
Reserved; set to 0.

Return Values

An appropriate HRESULT value is returned.

Remarks

The APCSPCH_SP_BACKGROUND flag should be used only when you are certain that you want to play the TTS in the background.


IAPCSpeech::Train

This method trains the application to recognize a user command, and deals with only one command at a time.

Syntax

HRESULT IAPCSpeech::Train( PCWSTR pszTrain, DWORD cbTrain, PCWSTR pszDisplay, DWORD cbDisplay, DWORD d1, DWORD d2 );

Parameters

pszTrain
Pointer to the phrase to train the application to recognize. Support for a list of words may be added in the future.
cbTrain
Byte count of pszTrain.
pszDisplay
Pointer to the null-terminated string that contains the phrase to display. Support for a list of words will be added in the future. This parameter is optional argument and can be NULL.
cbDisplay
Byte count of pszDisplay.
d1
Reserved; set to 0.
d2
Reserved; set to 0.

Return Values

S_FALSE indicates that training was canceled. This can occur if the user chooses ESCAPE during the training or performs an action that causes the form to lose focus, such as pressing the START button.

E_FAIL indicates that training has failed. This can occur if the user does not speak the word within the timeout period.

Remarks

This method results in a pop-up training form to help the user train the application to recognize a word or command. The method is blocked until the training is finished or canceled.


IAPCSpeech::VoiceHelpStart

This method is called by the shell to start voice Help.

Syntax

HRESULT IAPCSpeech::VoiceHelpStart( DWORD promptType );

Parameters

dwType
Specifies a DWORD that contains the type of Help to start. It is one of the following values:
APCSPCH_VH_LONGHELP
Starts long Help after the “Help” speech command is recognized.
APCSPCH_VH_SHORTHELP
Starts short Help after the “What can I say?” speech command is recognized.
APCSPCH_VH_LISTGLOBAL
Instructs Help to list the global commands.

Return Values

An appropriate HRESULT value is returned.

Remarks

The application must not call VoiceHelpStart or VoiceHelpStop.

Short Help lists all of the active speech commands by playing waveform (WAV) files that you provide. The Help system can only find the WAV file if the name of the WAV file is the same as the string used for the speech command. For example, short Help lists the volume command only if there is a file named Volume.wav in the \Windows directory. If the appropriate file does not exist, short Help does not list the command.

The command strings the application adds to the voice menu should be used to include the long and short voice Help strings, separated by tabs. The first string is the command string, the second is the long voice Help string. The third string is optional, and specifies a string to use for short voice Help instead of the command string.

The following table contains possible long and short voice Help combinations.

Command
Description
cmd\tlong Help\tshort Help | Has both long and short Help.
cmd | There is no long Help, and short Help is the same as command.
cmd\t\tshort Help | There is no long Help, and short Help is different from command.
cmd\tlong Help\t | Has long Help but no short Help.
cmd\tlong Help | Has long Help, and short Help is the same as command.


IAPCSpeech::VoiceHelpStop

This method is called by the shell to stop voice Help.

Syntax

HRESULT IAPCSpeech::VoiceHelpStop( DWORD dwReserved );

Parameters

dwReserved
Reserved; set to 0

Return Values

An appropriate HRESULT value is returned.

Remarks

The application must not call VoiceHelpStart or VoiceHelpStop.


IIRSquirt

This interface enables applications to use infrared (IR).

Method
Description
IIRSquirt::Transfer | Transfers data.
IIRSquirt::IRAvailable | Enables IR functionality.


IIRSquirt::Transfer

This method transfers data.

Syntax

HRESULT Transfer ( IfmManage *pFrmMgr, WORD wNum, CEOID *rgOID);

Parameters

pFrmMgr
Pointer to the form manager.
wNum
WORD that contains the number of object identifiers to send. To receive data, set wNum to 0.
rgOID
An array containing the object identifiers to send.

Return Values

NOERROR indicates success. STG_E_MEDIUMFULL indicates insufficient object store space.


IIRSquirt::IRAvailable

This method enables IR functionality.

Syntax

HRESULT IRAvailable ( );

Return Values

NOERROR indicates success.


IVIO_Vehicle

This interface exposes information about a vehicle.

Method
Description
IVIO_Vehicle::get_MaintenanceItems | Gets the enumeration interface that is used to access maintenance information for a vehicle.
IVIO_Vehicle::get_Metrics | Gets the enumeration interface that is used to access vehicle information.
IVIO_Vehicle::get_Devices | Gets the enumeration interface that is used to access available components that expose the IVIO_Device interface in the vehicle.


IVIO_Vehicle::get_MaintenanceItems

This method gets the enumeration interface that is used to access maintenance information for a vehicle.

Syntax

HRESULT IVIO_Vehicle::get_MaintenanceItems( IVIO_EnumMaintenanceItems **ppItems);

Parameters

ppItems
[out] Pointer to a pointer to an IVIO_EnumMaintenanceItems interface that is used to get and set maintenance information for a vehicle.

Return Values

S_OK indicates that the vehicle maintenance item enumerator was retrieved successfully. E_POINTER indicates that the ppItems pointer is invalid.

Remarks

The calling process must release the returned interface and its resources.


IVIO_Vehicle::get_Metrics

This method gets the enumeration interface that is used to access information that describes a vehicle.

Syntax

HRESULT IVIO_Vehicle::get_Metrics ( IVIO_EnumMetrics **ppMetric);

Parameters

ppMetric
[out] Pointer to a pointer to an IVIO_EnumMetrics interface that is used to get and set vehicle attributes.

Return Values

S_OK indicates that the vehicle metrics enumerator was retrieved successfully. E_POINTER indicates that the ppMetrics pointer is invalid.

Remarks

The calling process must release the returned interface and its resources.


IVIO_Vehicle::get_Devices

This method gets the enumeration interface that is used to access available components that expose the IVIO_Device interface in the vehicle.

Syntax

HRESULT IVIO_Vehicle::get_Devices ( IVIO_EnumDevices **ppDevices);

Parameters

ppDevices
[out] Pointer to the pointer to an IVIO_EnumDevices interface that is used to return the available devices for a vehicle.

Return Values

S_OK indicates that the vehicle’s device enumerator was retrieved successfully. E_POINTER indicates that the ppDevices pointer is invalid.

Remarks

The calling process must release the returned interface and its resources.


IVIO_EnumMetrics

The IVIO_EnumMetrics interface is an enumeration interface that exposes information about a vehicle.

Method
Description
IVIO_EnumMetrics::Add | Adds a new entry in the vehicle metrics collection. The new entry identifier matches the value of nItemId.
IVIO_EnumMetrics::Clone | Retrieves another enumerator that contains the same state information as the current one.
IVIO_EnumMetrics::Next | Retrieves the specified number of items in the enumeration sequence.
IVIO_EnumMetrics::Reset | Resets the enumerator back to the beginning of the collection.
IVIO_EnumMetrics::Seek | Searches for a metrics item identifier in the vehicle metrics collection.
IVIO_EnumMetrics::Set | Sets the value of the current item referenced by the enumerator.
IVIO_EnumMetrics::Skip | Skips over the specified number of items in the vehicle metrics collection.


IVIO_EnumMetrics::Add

This method adds a new entry in the vehicle metrics collection. The new entry identifier matches the value of nItemId.

Syntax

HRESULT IVIO_EnumMetrics::Add ( DWORD nItemId);

Parameters

nItemId
[in] Identifier of the vehicle metrics collection member to add. It is one of the following values:
VIOVEHICLEMETRIC_CYLINDERCOUNT
VIOVEHICLEMETRIC_DISPLACEMENT
VIOVEHICLEMETRIC_FUELDELIVERY
VIOVEHICLEMETRIC_FUELTYPE
VIOVEHICLEMETRIC_MAKE
VIOVEHICLEMETRIC_MANUFACTURER
VIOVEHICLEMETRIC_MODEL
VIOVEHICLEMETRIC_TRANSMISSION
VIOVEHICLEMETRIC_TRANSMISSION_GEARS
VIOVEHICLEMETRIC_VIN
VIOVEHICLEMETRIC_YEAR

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The vehicle item was added successfully. The enumerator is set to the position of the new metric.
S_FALSE | The item is already in the enumeration list. The enumeration position is unchanged.
E_FAIL | The application is unable to add the item to the enumeration list.

Remarks

The new entry identifier must match the metrics item identifier in nItemId.

Call the IVIO_EnumMetrics::Set method after calling this method to set an initial value for the new metric item.


IVIO_EnumMetrics::Clone

This method retrieves another enumerator that contains the same state information as the current one.

Syntax

HRESULT IVIO_EnumMetrics::Clone ( IVIO_EnumMetrics **ppEnumClone);

Parameters

ppEnumClone
[out] Pointer to a pointer to an IVIO_EnumMetrics interface.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The application cloned the enumeration interface.
E_OUTOFMEMORY | The application is out of memory.
E_UNEXPECTED | An unexpected error occurred.
E_POINTER | The ppEnumClone pointer is invalid.


IVIO_EnumMetrics::Next

This method retrieves the specified number of items in the enumeration sequence.

Syntax

HRESULT IVIO_EnumMetrics::Next ( ULONG cItems, IVIO_DataValue **rgItemsArray, ULONG *pcItemsFetched);

Parameters

cItems
[in] Number of items to retrieve.
rgItemsArray
[out] Array of IVIO_DataValue pointers where retrieved maintenance entry items are stored.
pcItemsFetched
[out] Pointer to a ULONG that contains the number of elements actually returned. If cItems is 1, this parameter can be NULL. If cItems is greater than 1, this parameter must be a valid pointer.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The application successfully retrieved the number of IVIO_DataValue interfaces specified in cItems. The value referenced by pcItemsFetched is set to cItems.
S_FALSE | The application returned fewer IVIO_DataValue interfaces than were specified in cItems. The value referenced by pcItemsFetched is set to the number of interfaces found. The members of rgItemsArray that were not set are set to NULL.
E_OUTOFMEMORY | The application is out of memory.
E_UNEXPECTED | An unexpected error occurred.
E_INVALIDARG | The value of cItems is invalid, or pcItemsFetched is NULL and cItems is greater than 1.
E_POINTER | Either the rgItemsArray pointer is invalid or the pcItemsFetched pointer is invalid.

Remarks

The application must release the interfaces returned in rgItemsArray when it is finished with them.


IVIO_EnumMetrics::Reset

This method resets the enumerator back to the beginning of the collection.

Syntax

HRESULT IVIO_EnumMetrics::Reset ( );

Return Values

S_OK indicates that the enumerator was set to the beginning of the collection. S_FALSE indicates that the enumerator was not set to the beginning of the collection.


IVIO_EnumMetrics::Seek

This method searches for a metrics item identifier in the vehicle metrics collection.

Syntax

HRESULT IVIO_EnumMetrics::Seek ( DWORD nItemId);

Parameters

nItemId
[in] Identifier of the vehicle metrics collection member to search for. It is one of the following values:
VIOVEHICLEMETRIC_CYLINDERCOUNT
VIOVEHICLEMETRIC_DISPLACEMENT
VIOVEHICLEMETRIC_FUELDELIVERY
VIOVEHICLEMETRIC_FUELTYPE
VIOVEHICLEMETRIC_MAKE
VIOVEHICLEMETRIC_MANUFACTURER
VIOVEHICLEMETRIC_MODEL
VIOVEHICLEMETRIC_TRANSMISSION
VIOVEHICLEMETRIC_TRANSMISSION_GEARS
VIOVEHICLEMETRIC_VIN
VIOVEHICLEMETRIC_YEAR

Return Values

S_OK indicates that the vehicle metrics item was retrieved successfully. The enumerator is set to the position of the specified metric. E_FAIL indicates that the application is unable to find the specified item identifier. The enumerator’s position is unchanged.

Remarks

Use the IVIO_EnumMetrics::Next and IVIO_EnumMetrics::Set methods to read and write metrics data.


IVIO_EnumMetrics::Set

This method sets the value of the current item referenced by the enumerator.

Syntax

HRESULT IVIO_EnumMetrics::Set ( LPVARIANT pValue);

Parameters

pValue
[in] Pointer to the VARIANT that contains the new value.

Use a VT_BSTR to set the following three values. A VT_BSTR is a 32-bit character string.

VIOVEHICLEMETRIC_MAKE
Specifies the make of the vehicle.
VIOVEHICLEMETRIC_MODEL
Specifies the model of the vehicle.
VIOVEHICLEMETRIC_VIN
Specifies the vehicle identification number (VIN) number.

Use a VT_UI4 to set the following values. A VT_UI4 is an unsigned long integer.

VIOVEHICLEMETRIC_YEAR
Specifies the year of the vehicle.
VIOVEHICLEMETRIC_MANUFACTURER
Specifies the manufacturer enumeration. It is one of the following values:
VIOMANUFACTURER_ALFA_LANCIA
VIOMANUFACTURER_ASTON_MARTIN
VIOMANUFACTURER_AUDI
VIOMANUFACTURER_BERTONE
VIOMANUFACTURER_BMW
VIOMANUFACTURER_CHRYSLER
VIOMANUFACTURER_DAIHATSU
VIOMANUFACTURER_DIAMOND_STAR_MOTORS
VIOMANUFACTURER_FERRARI
VIOMANUFACTURER_FORD
VIOMANUFACTURER_FUJI_HEAVY_INDUSTRIES
VIOMANUFACTURER_GM_CARS
VIOMANUFACTURER_GM_TRUCKS
VIOMANUFACTURER_GM_SATURN
VIOMANUFACTURER_HONDA
VIOMANUFACTURER_HYUNDAI
VIOMANUFACTURER_ISUZU
VIOMANUFACTURER_JAGUAR
VIOMANUFACTURER_KIA
VIOMANUFACTURER_LAMBORGHINI
VIOMANUFACTURER_LOTUS
VIOMANUFACTURER_MASERATI
VIOMANUFACTURER_MAZDA
VIOMANUFACTURER_MERCEDES_BENZ
VIOMANUFACTURER_MITSUBISHI
VIOMANUFACTURER_MITSUBISHI_AMERICA
VIOMANUFACTURER_NISSAN
VIOMANUFACTURER_OPEL
VIOMANUFACTURER_PEUGEOT
VIOMANUFACTURER_PORSCHE
VIOMANUFACTURER_RENAULT
VIOMANUFACTURER_ROLLS_ROYCE
VIOMANUFACTURER_ROVER
VIOMANUFACTURER_SAAB
VIOMANUFACTURER_SUZUKI
VIOMANUFACTURER_TOYOTA
VIOMANUFACTURER_VOLKSWAGEN
VIOMANUFACTURER_VOLVO

VIOVEHICLEMETRIC_DISPLACEMENT
Specifies the displacement of the engine in 0.1 liter increments.
VIOVEHICLEMETRIC_CYLINDERCOUNT
Specifies the number of cylinders in engine if internal combustion type.
VIOVEHICLEMETRIC_FUELTYPE
Specifies the fuel type enumeration. The following table shows possible types and their values.
Type
Value
VIOFUELTYPE_GAS | 1
VIOFUELTYPE_DIESEL | 2
VIOFUELTYPE_ELECTRIC | 3
VIOFUELTYPE_HYBRID | 4
VIOFUELTYPE_OTHER | 255

VIOVEHICLEMETRIC_FUELDELIVERY
Specifies the fuel delivery system enumeration. The following table shows possible types and their values.
Type
Value
VIOFUELDELIVERY_2_BBL_CARBURETOR | 1
VIOFUELDELIVERY_4_BBL_CARBURETOR | 2
VIOFUELDELIVERY_THROTTLE_BODY-INJECTION | 3
VIOFUELDELIVERY_PORT_INJECTION | 4
VIOFUELDELIVERY_LEAD_ACID_BATTERY | 5
VIOFUELDELIVERY_NICKEL_METAL_HYDRIDE_BATTERY | 6
VIOFUELDELIVERY_OTHER | 255

VIOVEHICLEMETRIC_TRANSMISSION
Specifies the transmission type enumeration. The following table shows possible types and their values.
Type
Value
VIOTRANSMISSION_MANUAL | 1
VIOTRANSMISSION_AUTOMATIC | 2
VIOTRANSMISSION_CONTINUOUSLY_VARIABLE | 3
VIOTRANSMISSION_OTHER | 255

VIOVEHICLEMETRIC_TRANSMISSION_GEARS
Transmission gear count. If the high bit (0x80000000) is set it means that an overdrive gear is available.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The value of the item currently referenced by the enumerator was set successfully.
S_FALSE | The enumerator is not positioned on a valid item.
E_OUTOFMEMORY | The application is out of memory.
E_POINTER | The pointer referenced by pValue is invalid.


IVIO_EnumMetrics::Skip

This method skips over the specified number of items in the vehicle metrics collection.

Syntax

HRESULT IVIO_EnumMetrics::Skip ( ULONG cItems);

Parameters

cItems
[in] Number of items to skip in the collection.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The number of elements skipped is equal to the value specified in cItems.
S_FALSE | The number of elements skipped is less than the value specified in cItems.
E_OUTOFMEMORY | The application is out of memory.
E_INVALIDARG | The value of cItems is invalid.
E_UNEXPECTED | An unexpected error occurred.


IVIO_EnumMaintenanceItems

This interface is an enumeration interface that exposes information about maintenance information for a vehicle.

Method
Description
IVIO_EnumMaintenanceItems::Add | Adds a new entry in the vehicle maintenance items collection. The new item identifier matches the value of nItemId.
IVIO_EnumMaintenanceItems::Clone | Retrieves another enumerator that contains the same state information as the current one.
IVIO_EnumMaintenanceItems::Next | Retrieves the specified number of items in the enumeration sequence.
IVIO_EnumMaintenanceItems::Reset | Resets the enumerator back to the beginning of the collection.
IVIO_EnumMaintenanceItems::Seek | Seeks to the entry in the vehicle maintenance items collection that has the specified item identifier.
IVIO_EnumMaintenanceItems::Skip | Skips over the specified number of items in the vehicle maintenance items collection.


IVIO_EnumMaintenanceItems::Add

This method adds a new entry in the vehicle maintenance items collection. The new item identifier matches the value of nItemId.

Syntax

HRESULT IVIO_EnumMaintenanceItems::Add ( DWORD nItemId);

Parameters

nItemId
[in] Identifier of the vehicle maintenance collection member to add. It is one of the following values:
VIOMAINT_BRAKE_PAD_CHANGE
VIOMAINT_CHASSIS_ALIGNMENT
VIOMAINT_COOLANT_CHANGE
VIOMAINT_ENGINE_BELT_REPLACE
VIOMAINT_ENGINE_OIL_CHANGE
VIOMAINT_ENGINE_TUNEUP
VIOMAINT_FLUID_LEVEL_CHECK
VIOMAINT_REPLACE_BATTERY
VIOMAINT_REPLACE_TIRES
VIOMAINT_ROTATE_TIRES
VIOMAINT_SPARKPLUG_CHANGE
VIOMAINT_SPARKPLUG_WIRE_CHANGE
VIOMAINT_TRANSMISSION_OIL_CHANGE

Return Values

S_OK indicates that the application added the vehicle maintenance item successfully. The enumerator is set to the position of the new item. S_FALSE indicates that the item is already in the enumeration list. The enumeration position is unchanged.

Remarks

The information specified by the item value identifiers is exposed by a VT_UNKNOWN (IUnknown*) interface. Query VT_UNKNOWN (IUnknown*) for IID_VIOEnumMaintenanceEntry to get the enumerator interface.

If a new collection entry is desired, calling the IVIO_EnumMaintenanceItems::Next method after making the call to IVIO_EnumMaintenanceItems::Add creates an IVIO_EnumMaintenanceEntry interface for the new maintenance item identifier.


IVIO_EnumMaintenanceItems::Clone

This method retrieves another enumerator that contains the same state information as the current enumerator.

Syntax

HRESULT IVIO_EnumMaintenanceItems::Clone ( IVIO_EnumMaintenanceItems **ppEnumClone);

Parameters

ppEnumClone
[out] Pointer to the pointer to an IVIO_EnumMaintenanceItems interface.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The application cloned the enumeration interface.
E_OUTOFMEMORY | The application is out of memory.
E_UNEXPECTED | An unexpected error occurred.
E_POINTER | The ppEnumClone pointer is invalid.


IVIO_EnumMaintenanceItems::Next

This method retrieves the specified number of items in the enumeration sequence.

Syntax

HRESULT IVIO_EnumMaintenanceItems::Next ( ULONG cItems, IVIO_DataValue **rgItemsArray, ULONG *pcItemsFetched);

Parameters

cItems
[in] Number of items to retrieve.
rgItemArray
[out] Array of IVIO_DataValue pointers where the retrieved maintenance entry items are stored.
pcItemsFetched
[out] Pointer to a ULONG that contains the number of elements actually returned. If cItems is 1, this parameter can be NULL. If cItems is greater than 1, this parameter must be a valid pointer.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The application successfully retrieved the number of IVIO_DataValue interfaces specified in cItems. The value referenced by pcItemsFetched is set to cItems.
S_FALSE | The application returned fewer IVIO_DataValue interfaces than were specified in cItems. The value referenced by pcItemsFetched is set to the number of interfaces. The members of rgItemArray that were not set are set to NULL.
E_OUTOFMEMORY | The application is out of memory.
E_UNEXPECTED | An unexpected error occurred.
E_INVALIDARG | The value of cItems is invalid, or pcItemsFetched is NULL and cItems is greater than 1.
E_POINTER | Either the rgItemArray pointer is invalid or the pcItemsFetched pointer is invalid.

Remarks

The application must release the interfaces returned in rgItemArray when it is finished with them.


IVIO_EnumMaintenanceItems::Reset

This method resets the enumerator back to the beginning of the collection.

Syntax

HRESULT IVIO_EnumMaintenanceItems::Reset ( );

Return Values

S_OK indicates that the enumerator was set to the beginning of the collection. S_FALSE indicates that the enumerator was not set to the beginning of the collection.


IVIO_EnumMaintenanceItems::Seek

This method seeks to the entry in the vehicle maintenance items collection that has the specified item identifier.

Syntax

HRESULT IVIO_EnumMaintenanceItems::Seek ( DWORD nItemId);

Parameters

nItemId
[in] Identifier of the vehicle maintenance collection member to seek. It is one of the following values:
VIOMAINT_BRAKE_PAD_CHANGE
VIOMAINT_CHASSIS_ALIGNMENT
VIOMAINT_COOLANT_CHANGE
VIOMAINT_ENGINE_BELT_REPLACE
VIOMAINT_ENGINE_OIL_CHANGE
VIOMAINT_ENGINE_TUNEUP
VIOMAINT_FLUID_LEVEL_CHECK
VIOMAINT_REPLACE_BATTERY
VIOMAINT_REPLACE_TIRES
VIOMAINT_ROTATE_TIRES
VIOMAINT_SPARKPLUG_CHANGE
VIOMAINT_SPARKPLUG_WIRE_CHANGE
VIOMAINT_TRANSMISSION_OIL_CHANGE

Return Values

S_OK indicates that the application retrieved the vehicle maintenance collection item successfully. The enumerator is set to the position of the specified maintenance item. S_FALSE indicates that the application was unable to find the specified maintenance collection item. The enumerator position is unchanged.

Remarks

The information specified by the item value identifiers is exposed by a VT_UNKNOWN (IUnknown*) interface. Query VT_UNKNOWN (IUnknown*) for IID_VIOEnumMaintenanceEntry to get the enumerator interface.


IVIO_EnumMaintenanceItems::Skip

This method skips over the specified number of items in the vehicle maintenance items collection.

Syntax

HRESULT IVIO_EnumMaintenanceItems::Skip ( ULONG cItems);

Parameters

cItems
[in] Number of elements to skip in the maintenance entry enumeration.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The number of elements skipped is equal to the value specified in cItems.
S_FALSE | The number of elements skipped is less than the value specified in cItems.
E_OUTOFMEMORY | The application is out of memory.
E_INVALIDARG | The value of cItems is invalid.
E_UNEXPECTED | An unexpected error occurred.


IVIO_EnumMaintenanceEntry

This interface is an enumeration interface that exposes information about maintenance entry information for a vehicle.

Method
Description
IVIO_EnumMaintenanceEntry::Clone | Retrieves another enumerator that contains the same state information as the current one.
IVIO_EnumMaintenanceEntry::Next | Retrieves the specified number of items in the enumeration sequence.
IVIO_EnumMaintenanceEntry::Reset | Resets the enumerator back to the beginning of the collection.
IVIO_EnumMaintenanceEntry::Seek | Seeks to the entry in the enumeration list that matches the maintenance entry item identifier that is passed to the method in nItemId.
IVIO_EnumMaintenanceEntry::Set | Sets the value of the current item referenced by the enumerator.
IVIO_EnumMaintenanceEntry::Skip | Skips over the specified number of items in the maintenance entry enumeration list.


IVIO_EnumMaintenanceEntry::Clone

This method retrieves another enumerator that contains the same state information as the current enumerator.

Syntax

HRESULT IVIO_EnumMaintenanceEntry::Clone ( IVIO_EnumMetrics **ppEnumClone);

Parameters

ppEnumClone
[out] Pointer to a pointer to an IVIO_EnumMaintenanceEntry interface.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The application cloned the enumeration interface.
E_OUTOFMEMORY | The application is out of memory.
E_UNEXPECTED | An unexpected error occurred.
E_POINTER | The ppEnumClone pointer is invalid.


IVIO_EnumMaintenanceEntry::Next

This method retrieves the specified number of items in the enumeration sequence.

Syntax

HRESULT IVIO_EnumMaintenanceEntry::Next ( ULONG cItems, IVIO_DataValue **rgItemsArray, ULONG *pcItemsFetched);

Parameters

cItems
[in] Number of items to retrieve.
rgItemsArray
[out] Array of IVIO_DataValue pointers where retrieved maintenance entry items are stored.
pcItemsFetched
[out] Pointer to a ULONG that contains the number of elements actually returned. If cItems is 1, this parameter can be NULL. If cItems is greater than 1, this parameter must be a valid pointer.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The application successfully retrieved the number of IVIO_DataValue interfaces specified in cItems. The value referenced by pcItemsFetched is set to cItems.
S_FALSE | The application returned fewer IVIO_DataValue interfaces than were specified in cItems. The value referenced by pcItemsFetched is set to the number of interfaces. The members of rgItemsArray that were not set are set to NULL.
E_OUTOFMEMORY | The application is out of memory.
E_UNEXPECTED | An unexpected error occurred.
E_INVALIDARG | The value of cItems is invalid, or pcItemFetched is NULL and cItems is greater than 1.
E_POINTER | Either the rgItemsArray pointer is invalid or the pcItemsFetched pointer is invalid.

Remarks

The application must release the interfaces in rgItemArray when it is done with them.


IVIO_EnumMaintenanceEntry::Reset

This method resets the enumerator back to the beginning of the collection.

Syntax

HRESULT IVIO_EnumMaintenanceEntry::Reset ( );

Return Values

S_OK indicates that the enumerator was set to the beginning of the collection. S_FALSE indicates that the enumerator was not set to the beginning of the collection.


IVIO_EnumMaintenanceEntry::Seek

This method seeks to the entry in the enumeration list that matches the maintenance entry item identifier that is passed to the method in nItemId.

Syntax

HRESULT IVIO_EnumMaintenanceEntry::Seek ( DWORD nItemId);

Parameters

nItemId
[in] Identifier of the vehicle maintenance item entry collection member to seek. It is one of the following values:
VIOMAINTENTRY_HIGH_INTERVAL
VIOMAINTENTRY_INTERVAL_TYPE
VIOMAINTENTRY_INTERVAL_UNITS
VIOMAINTENTRY_LOW_INTERVAL
VIOMAINTENTRY_NAME
VIOMAINTENTRY_SECONDARY_INTERVAL
VIOMAINTENTRY_SECONDARY_INTERVAL_TYPE
VIOMAINTENTRY_SECONDARY_INTERVAL_UNITS

Return Values

S_OK indicates that the application retrieved the vehicle maintenance entry successfully. The enumerator is set to the position of the specified maintenance entry. S_FALSE indicates that the application was unable to find the specified maintenance entry. The enumerator position is unchanged.


IVIO_EnumMaintenanceEntry::Set

This method sets the value of the current item referenced by the enumerator.

Syntax

HRESULT IVIO_EnumMaintenanceEntry::Set ( LPVARIANT pValue);

Parameters

pValue
[in] Pointer to the VARIANT that contains the new value.

Use a VT_BSTR to set the following value. A VT_BSTR is a 32-bit character string.

VIOMAINTENTRY_NAME
Specifies the name of the maintenance item.

Use a VT_UI4 to set the following values. A VT_UI4 is an unsigned long integer.

VIOMAINTENTRY_LOW_INTERVAL
Specifies the shortest maintenance interval, for example, 4,800 km (3,000 miles) for an oil change.
VIOMAINTENTRY_HIGH_INTERVAL
Specifies the longest maintenance interval, for example, 12,000 km (7,500 miles) for an oil change.
VIOMAINTENTRY_INTERVAL_TYPE
Specifies the type of interval, for example, time or mileage. It is one of the following values:
VIOMAINTINTERVALTYPE_CALENDAR_TIME
VIOMAINTINTERVALTYPE_MILEAGE
VIOMAINTINTERVALTYPE_RUNNING_TIME

VIOMAINTENTRY_INTERVAL_UNITS
Specifies the units used in the interval. It is one of the following values:
VIOMAINTINTERVALUNITS_DAYS
VIOMAINTINTERVALUNITS_HOURS
VIOMAINTINTERVALUNITS_KILOMETERS
VIOMAINTINTERVALUNITS_MILES
VIOMAINTINTERVALUNITS_MONTHS

VIOMAINTENTRY_SECONDARY_INTERVAL
Specifies the secondary interval to use, for example, three months for an oil change. An application looks for either the low interval or the secondary interval to elapse in order to give a maintenance warning.
VIOMAINTENTRY_SECONDARY_INTERVAL_TYPE
Specifies the type of secondary interval. It can be one of the values listed for VIOMAINTENTRY_INTERVAL_TYPE.
VIOMAINTENTRY_SECONDARY_INTERVAL_UNITS
Specifies the unites used for the secondary interval. It can be one of the values listed for VIOMAINTENTRY_INTERVAL_UNITS.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The value of the item currently referenced by the enumerator was set successfully.
S_FALSE | The enumerator is not positioned on a valid item.
E_OUTOFMEMORY | The application is out of memory.
E_POINTER | The pointer referenced by pValue is invalid.


IVIO_EnumMaintenanceEntry::Skip

This method skips over the specified number of items in the maintenance entry enumeration list.

Syntax

HRESULT IVIO_EnumMaintenanceEntry::Skip ( ULONG cItems);

Parameters

cItems
[in] Number of items to skip in the maintenance entry enumeration.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The number of elements skipped is equal to the value specified in cItems.
S_FALSE | The number of elements skipped is less than the value specified in cItems.
E_OUTOFMEMORY | The application is out of memory.
E_INVALIDARG | The value of cItems is invalid.
E_UNEXPECTED | An unexpected error occurred.


IVIO_EnumDevices

This interface enumerates the available components in the vehicle that expose the IVIO_Device interface.

Method
Description
IVIO_EnumDevices::Clone | Retrieves another enumerator that contains the same state information as the current enumerator.
IVIO_EnumDevices::Next | Retrieves the specified number of device class identifiers (CLSIDs) in the enumeration sequence.
IVIO_EnumDevices::Reset | Resets the enumerator back to the beginning of the collection.
IVIO_EnumDevices::Seek | Seeks to the entry in the device component collection that matches the device CLSID specified in rclsid.
IVIO_EnumDevices::Skip | Skips over the specified number of items in the vehicle device enumeration list.


IVIO_EnumDevices::Clone

This method retrieves another enumerator that contains the same state information as the current enumerator.

Syntax

HRESULT IVIO_EnumDevices::Clone ( IVIO_EnumDevices **ppEnumClone);

Parameters

ppEnumClone
[out] Pointer to a pointer to an IVIO_EnumDevices interface.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The application cloned the enumeration interface.
E_OUTOFMEMORY | The application is out of memory.
E_UNEXPECTED | An unexpected error occurred.
E_POINTER | The ppEnumClone pointer is invalid.


IVIO_EnumDevices::Next

This method retrieves the specified number of device class identifiers (CLSIDs) in the enumeration sequence.

Syntax

HRESULT IVIO_EnumDevices::Next ( ULONG cDevices, LPCLSID *rgDevicesArray, ULONG *pcDevicesFetched);

Parameters

cDevices,
[in] Number of device CLSIDs to retrieve.
rgDevicesArray
[out] Pointer to the array of CLSID pointers where retrieved device CLSIDs are stored.
pcDevicesFetched
[out] Pointer to a ULONG that contains the number of elements actually returned. If cDevices is 1, this parameter can be NULL. If cDevices is greater than 1, this parameter must be a valid pointer.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The application successfully retrieved the number of device CLSIDs specified in cDevices. The value referenced by pcDevicesFetched is set to cDevices.
S_FALSE | The application returned fewer CLSIDs than specified in cDevices. The value referenced by pcDevicesFetched is set to the number of elements returned. The members of rgDevicesArray that were not set are set to NULL.
E_OUTOFMEMORY | The application is out of memory.
E_UNEXPECTED | An unexpected error occurred.
E_INVALIDARG | The value of cDevices is invalid, or pcDevicesFetched is NULL and cDevices is greater than 1.
E_POINTER | Either the rgDevicesArray pointer is invalid or the pcDevicesFetched pointer is invalid.

Remarks

The application must free each array element using the CoTaskMemFree call.


IVIO_EnumDevices::Reset

This method resets the enumerator back to the beginning of the collection.

Syntax

HRESULT IVIO_EnumDevices::Reset ( );

Return Values

S_OK indicates that the enumerator was set to the beginning of the collection. S_FALSE indicates that the enumerator was not set to the beginning of the collection.


IVIO_EnumDevices::Seek

This method seeks to the entry in the device component collection that matches the device CLSID specified in rclsid.

Syntax

HRESULT IVIO_EnumDevices::Seek ( REFCLSID rclsid);

Parameters

rclsid
[in] CLSID to seek. It is one of the following values:
CLSID_VIO_AUX_LIGHTS
CLSID_VIO_BATTERY_VOLTAGE
CLSID_VIO_COOLANT_TEMP
CLSID_VIO_DIAGNOSTIC_CODES
CLSID_VIO_DOOR_SWITCHES
CLSID_VIO_ENGINE_LOAD
CLSID_VIO_ENGINE_RPM
CLSID_VIO_FUEL_PRESSURE
CLSID_VIO_FUEL_SYSTEM_STATUS
CLSID_VIO_FUEL_TRIM
CLSID_VIO_HEADLIGHTS
CLSID_VIO_IGNITION_SWITCH
CLSID_VIO_INTAKE_TEMP
CLSID_VIO_LATCH_CONTROL
CLSID_VIO_LOCK_STATE
CLSID_VIO_MANIFOLD_AIR_PRESSURE
CLSID_VIO_MASS_AIR_FLOW_RATE
CLSID_VIO_O2_SENSOR
CLSID_VIO_ODOMETER
CLSID_VIO_PARKING_BRAKE
CLSID_VIO_THROTTLE_POSITION
CLSID_VIO_TIMING_ADVANCE
CLSID_VIO_TRANSMISSION_GEAR
CLSID_VIO_VEHICLE_SPEED

Return Values

S_OK indicates that the application retrieved the vehicle device CLSID successfully. The enumerator is set to the position of the specified device. S_FALSE indicates that the application was unable to find the specified device CLSID. The enumerator position is unchanged.

Remarks

If S_FALSE is returned, this means that the requested component exposing the IVIO_Device interface is not available on the vehicle.


IVIO_EnumDevices::Skip

This method skips over the specified number of items in the vehicle’s device enumeration list.

Syntax

HRESULT IVIO_EnumDevices::Skip ( ULONG cDevices);

Parameters

cDevices
[in] Number of items in the device CLSID list to skip.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The number of elements skipped is equal to the value specified in cDevices.
S_FALSE | The number of elements skipped is less than the value specified in cDevices.
E_OUTOFMEMORY | The application is out of memory.
E_INVALIDARG | The value of cDevices is invalid.
E_UNEXPECTED | An unexpected error occurred.


IVIO_EnumDiagnosticItems

This interface exposes information about diagnostic data from the vehicle.

Method
Description
IVIO_EnumDiagnosticItems::Clone | Retrieves another enumerator that contains the same state information as the current one.
IVIO_EnumDiagnosticItems::Next | Retrieves the specified number of items in the enumeration sequence.
IVIO_EnumDiagnosticItems::Reset | Resets the enumerator back to the beginning of the collection.
IVIO_EnumDiagnosticItems::Skip | Skips over the specified number of items in the vehicle diagnostic items.


IVIO_EnumDiagnosticItems::Clone

This method retrieves another enumerator that contains the same state information as the current one.

Syntax

HRESULT IVIO_EnumDiagnosticItems::Clone ( IVIO_EnumDiagnosticItems **ppEnumClone);

Parameters

ppEnumClone
[out] Pointer to a pointer to an IVIO_EnumDiagnosticItems interface.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The application cloned the enumeration interface.
E_OUTOFMEMORY | The application is out of memory.
E_UNEXPECTED | An unexpected error occurred.
E_POINTER | The ppEnumClone pointer is invalid.


IVIO_EnumDiagnosticItems::Next

This method retrieves the specified number of items in the enumeration sequence.

Syntax

HRESULT IVIO_EnumDiagnosticItems::Next ( ULONG cItems, IVIO_EnumDiagnosticEntry **rgItemsArray, ULONG *pcItemsFetched);

Parameters

cItems
[in] Number of items to retrieve.
rgItemsArray
[out] Array of IVIO_EnumDiagnosticEntry pointers where retrieved diagnostic entry items are stored.
pcItemsFetched
[out] Pointer to a ULONG that contains the number of elements actually returned. If cItems is 1, this parameter can be NULL. If cItems is greater than 1, this parameter must be a valid pointer.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The application successfully retrieved the number of IVIO_EnumDiagnosticEntry interfaces specified in cItems. The value referenced by pcItemsFetched is set to cItems.
S_FALSE | The application returned fewer IVIO_EnumDiagnosticEntry interfaces than specified in Items. The value referenced by pcItemsFetched is set to the number of interfaces returned. The members of rgItemsArray that were not set are set to NULL.
E_OUTOFMEMORY | The application is out of memory.
E_UNEXPECTED | An unexpected error occurred.
E_INVALIDARG | The value of cItems is invalid, or pcItemsFetched is NULL and cItems is greater than 1.
E_POINTER | Either the rgItemsArray pointer is invalid or the pcItemsFetched pointer is invalid.

Remarks

The application must release the interfaces returned in rgItemsArray when it is done with them.


IVIO_EnumDiagnosticItems::Reset

This method resets the enumerator back to the beginning of the collection.

Syntax

HRESULT IVIO_EnumDiagnosticItems::Reset ( );

Return Values

S_OK indicates that the enumerator was set to the beginning of the collection. S_FALSE indicates that the enumerator was not set to the beginning of the collection.


IVIO_EnumDiagnosticItems::Skip

This method skips over the specified number of items in the vehicle diagnostic items.

Syntax

HRESULT IVIO_EnumDiagnosticItems::Skip ( ULONG cItems);

Parameters

cItems
[in] Number of elements in the vehicle diagnostic list to skip.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The number of elements skipped is equal to the value specified in cItems.
S_FALSE | The number of elements skipped is less than the value specified in cItems.
E_OUTOFMEMORY | The application is out of memory.
E_INVALIDARG | The value of cItems is invalid.
E_UNEXPECTED | An unexpected error occurred.


IVIO_EnumDiagnosticEntry

This interface exposes information about vehicle diagnostic data entries.

Method
Description
IVIO_EnumDiagnosticEntry::Clone | Retrieves another enumerator that contains the same state information as the current one.
IVIO_EnumDiagnosticEntry::Next | Retrieves the specified number of items in the enumeration sequence.
IVIO_EnumDiagnosticEntry::Reset | Resets the enumerator back to the beginning of the collection.
IVIO_EnumDiagnosticEntry::Seek | Seeks the entry in the diagnostic entry enumeration list with the identifier that matches the value of nItem.
IVIO_EnumDiagnosticEntry::Skip | Skips over the specified number of items in the diagnostic entry enumeration list.


IVIO_EnumDiagnosticEntry::Clone

This method retrieves another enumerator that contains the same state information as the current one.

Syntax

HRESULT IVIO_EnumDiagnosticEntry::Clone ( IVIO_EnumDiagnosticEntry **ppEnumClone);

Parameters

ppEnumClone
[out] Pointer to the pointer to an IVIO_EnumDiagnosticEntry interface.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The application cloned the enumeration interface.
E_OUTOFMEMORY | The application is out of memory.
E_UNEXPECTED | An unexpected error occurred.
E_POINTER | The ppEnumClone pointer is invalid.


IVIO_EnumDiagnosticEntry::Next

This method retrieves the specified number of items in the enumeration sequence.

Syntax

HRESULT IVIO_EnumDiagnosticEntry::Next ( ULONG cItems, IVIO_DataValue **rgItemsArray, ULONG *pcItemsFetched);

Parameters

cItems
[in] Number of items to retrieve.
rgItemsArray
[out] Array of IVIO_DataValue pointers where retrieved diagnostic entry items are stored.
pcItemsFetched
[out] Pointer to a ULONG that contains the number of elements actually returned. If cItems is 1, this parameter can be NULL. If cItems is greater than 1, this parameter must be a valid pointer.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The application successfully retrieved the number of IVIO_DataValue interfaces specified in cItems. The value referenced by pcItemsFetched is set to cItems.
S_FALSE | The application returned fewer IVIO_DataValue interfaces than specified in Items. The value referenced by pcItemsFetched is set to the number of interfaces returned. The members of rgItemsArray that were not set are set to NULL.
E_OUTOFMEMORY | The application is out of memory.
E_UNEXPECTED | An unexpected error occurred.
E_INVALIDARG | The value of cItems is invalid, or pcItemsFetched is NULL and cItems is greater than 1.
E_POINTER | Either the rgItemsArray pointer is invalid or the pcItemsFetched pointer is invalid.

Remarks

The application must release the interfaces returned in rgItemsArray when it is done with them.


IVIO_EnumDiagnosticEntry::Reset

This method resets the enumerator back to the beginning of the collection.

Syntax

HRESULT IVIO_EnumDiagnosticEntry::Reset ( );

Return Values

S_OK indicates that the enumerator was set to the beginning of the collection. S_FALSE indicates that the enumerator was not set to the beginning of the collection.


IVIO_EnumDiagnosticEntry::Seek

This method seeks the entry in the diagnostic entry enumeration list with the identifier that matches the value of nItem.

Syntax

HRESULT IVIO_EnumDiagnosticEntry::Seek ( DWORD nItem );

Parameters

nItemId
[in] Identifier of the vehicle diagnostic entry collection member to seek. It is one of the following values:
VIODIAGENTRY_LAMP_FLAG
VIODIAGENTRY_SAE_CODE
VIODIAGENTRY_SUBSYSTEM
VIODIAGENTRY_SYSTEM

Return Values

S_OK indicates that the application retrieved the diagnostic entry successfully. Enumerator is set to position of given diagnostic entry. S_FALSE indicates that the enumerator position is unchanged.

Remarks

The information specified in the item value identifiers is contained in a VT_UI4 data type, which is an unsigned long integer. The long integer contains information associated with one of the following item value identifiers:

VIODIAGENTRY_SYSTEM
Specifies the vehicle system returning the diagnostic information. It is one of the following values:
VIOTC_SYS_BODY
VIOTC_SYS_CHASSIS
VIOTC_SYS_NETWORK
VIOTC_SYS_POWERTRAIN
VIOTC_SYS_UNKNOWN

VIODIAGENTRY_SUBSYSTEM
Specifies the generic vehicle subsystem value. It can be one of the following values:

For power train subsystems:
VIOTC_AUX_EMISSION_CONTROL
VIOTC_FUEL_AIR_METERING
VIOTC_IGNITION_SYSTEM_OR_MISFIRE
VIOTC_TRANSMISSION
VIOTC_VEHSPEED_IDLE_AUXINPUTS

For chassis subsystems:
VIOTC_ANTILOCK_BRAKES
VIOTC_STEERING
VIOTC_SUSPENSION
VIOTC_TRACTION_CONTROL

For body subsystems:
VIOTC_ANTI_THEFT
VIOTC_CLIMATE_CONTROL
VIOTC_INSTRUMENT_PANEL
VIOTC_LIGHTING_CONTROL
VIOTC_MEMORY_SEATS_MIRROR
VIOTC_SUPPLEMENTAL_RESTRAINTS
VIOTC_TRIP_COMPUTER

For an unknown subsystem, use VIOTC_SUBSYSTEM_OTHER.

VIODIAGENTRY_SAE_CODE
Specifies the standard diagnostic trouble code value defined by the Society of Automotive Engineers (SAE).
VIODIAGENTRY_LAMP_FLAG
Specifies the flag to show if this diagnostic code activated a malfunction indicator lamp on the instrument panel.


IVIO_EnumDiagnosticEntry::Skip

This method skips over the specified number of items in the diagnostic entry enumeration list.

Syntax

HRESULT IVIO_EnumDiagnosticEntry::Skip ( ULONG cItems);

Parameters

cItems
[in] Number of elements in the diagnostic entry enumeration list to skip.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The number of elements skipped is equal to the value specified in cItems.
S_FALSE | The number of elements skipped is less than the value specified in cItems.
E_OUTOFMEMORY | The application is out of memory.
E_INVALIDARG | The value of cItems is invalid.
E_UNEXPECTED | An unexpected error occurred.


IVIO_DataValue

Use this interface to return data values from the enumeration interfaces to the application.

Method
Description
IVIO_DataValue::get_ItemID | Gets the item’s identifier attribute.
IVIO_DataValue::get_DataValue | Retrieves the data value for the item identified with the IVIO_DataValue::get_ItemID method.


IVIO_DataValue::get_ItemID

This method gets the item’s identifier attribute.

Syntax

HRESULT IVIO_DataValue::get_ItemID ( LPDWORD *pItemID);

Parameters

pItemID
[out] Pointer to a DWORD to store the item identifier value. It is one of the following item identifier values:

The following are IVIO_DATAVALUE properties from IVIO_EnumMetrics interface:
VIOVEHICLEMETRIC_CYLINDERCOUNT
VIOVEHICLEMETRIC_DISPLACEMENT
VIOVEHICLEMETRIC_FUELDELIVERY
VIOVEHICLEMETRIC_FUELTYPE
VIOVEHICLEMETRIC_MAKE
VIOVEHICLEMETRIC_MANUFACTURER
VIOVEHICLEMETRIC_MODEL
VIOVEHICLEMETRIC_TRANSMISSION
VIOVEHICLEMETRIC_TRANSMISSION_GEARS
VIOVEHICLEMETRIC_VIN
VIOVEHICLEMETRIC_YEAR

The following are IVIO_DATAVALUE properties from IVIO_EnumMaintenanceItems interface:
VIOMAINT_BRAKE_PAD_CHANGE
VIOMAINT_CHASSIS_ALIGNMENT
VIOMAINT_COOLANT_CHANGE
VIOMAINT_ENGINE_BELT_REPLACE
VIOMAINT_ENGINE_OIL_CHANGE
VIOMAINT_ENGINE_TUNEUP
VIOMAINT_FLUID_LEVEL_CHECK
VIOMAINT_REPLACE_BATTERY
VIOMAINT_REPLACE_TIRES
VIOMAINT_ROTATE_TIRES
VIOMAINT_SPARKPLUG_CHANGE
VIOMAINT_SPARKPLUG_WIRE_CHANGE
VIOMAINT_TRANSMISSION_OIL_CHANGE

The following are IVIO_DATAVALUE properties from IVIO_EnumMaintenanceEntry interface:
VIOMAINTENTRY_HIGH_INTERVAL
VIOMAINTENTRY_INTERVAL_TYPE
VIOMAINTENTRY_INTERVAL_UNITS
VIOMAINTENTRY_LOW_INTERVAL
VIOMAINTENTRY_NAME
VIOMAINTENTRY_SECONDARY_INTERVAL
VIOMAINTENTRY_SECONDARY_INTERVAL_TYPE
VIOMAINTENTRY_SECONDARY_INTERVAL_UNITS

The following are IVIO_DATAVALUE properties from IVIO_EnumDiagnosticEntry interface:
VIODIAGENTRY_LAMP_FLAG
VIODIAGENTRY_SAE_CODE
VIODIAGENTRY_SUBSYSTEM
VIODIAGENTRY_SYSTEM

Return Values

S_OK indicates that the item identifier was returned successfully. E_POINTER indicates that the pointer is invalid.


IVIO_DataValue::get_DataValue

This method retrieves the data value for the item identified with the IVIO_DataValue::get_ItemID method.

Syntax

HRESULT IVIO_DataValue::get_DataValue ( LPVARIANT pDataValue);

Parameters

pDataValue
[out] Pointer to a VARIANT type.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The data value was returned successfully.
E_OUTOFMEMORY | The application is out of memory.
E_POINTER | The pDataValue pointer is invalid.


IVIO_Device

Use this interface to access vehicle components. These components can be sensors that are accessed by means of the vehicle’s serial data bus, direct input from the vehicle’s wiring harness, vehicle electronic control units (ECU), or from the Auto PC device.

Method
Description
IVIO_Device::GetData | Retrieves the current data from the device.
IVIO_Device::get_AccessMode | Retrieves the current access for a requested mode.
IVIO_Device::get_Metrics | Retrieves the data that describes the format of the data being sent to and returned from the interface’s components.
IVIO_Device::get_Status | Retrieves the current availability of the device such as READY or BUSY.
IVIO_Device::SetData | Sends control information to the vehicle.
IVIO_Device::SetNotify | Provides the means to add a notification sink to a specified device. Through this sink, the device can send a notification to an application on a timed basis.
IVIO_Device::set_AccessMode | Sets the access mode—either shared or exclusive access—for the device. The mode is used a read or write mode.


IVIO_Device::GetData

This method retrieves the current data from the device.

Syntax

HRESULT IVIO_Device::GetData ( LPVARIANT pData, DWORD dwTimeOut );

Parameters

pData
[in/out] Pointer to a VARIANT that contains the data from the device. When some vehicle I/O components implement the IVIO_Device interface, the VARIANT contains information to further define the requested data. For an example of this implementation, see the CLSID_VIO_FUEL_SYSTEM_STATUS component.
dwTimeOut
[in] Specifies, in milliseconds, the amount of time to wait for a reply to the data request.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Successfully retrieved data from the device.
E_NOTIMPL | This device does not implement data reads.
E_POINTER | The pData pointer is invalid.
E_ACCESSDENIED | Access to this device is denied.
E_UNEXPECTED | An unexpected error occurred reading data from the device.

Remarks

For more information about the GetData method, see “CLSIDs for the Auto PC.”

See Also

CLSIDs for the Auto PC


IVIO_Device::get_AccessMode

This method retrieves the current access for a requested mode.

Syntax

HRESULT IVIO_Device::get_AccessMode ( DWORD dwMode, DWORD *pAccessMode );

Parameters

dwMode
[in] Specifies the type of mode that is requesting access. It is one of the following values:
VIODEVICEMODE_READ
This mode requests the device’s read access.
VIODEVICEMODE_WRITE
This mode requests the device’s write access.
pAccessMode
[out] Address to store the requested access for the requested mode. The following table shows possible values for this parameter.
Access
Value
Description
VIODEVACCESS_SHARED | 0x0000 | The device is currently shareable.
VIODEVACCESS_EXCLUSIVE | 0x8000 | The device currently has exclusive access.
VIODEVACCESS_NONE | 0xFFFF | There is no access for the requested mode.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The access mode was successfully read.
E_INVALID | The dwMode parameter was invalid.
E_POINTER | The pAccessMode pointer is invalid.
E_UNEXPECTED | An unexpected error occurred while requesting access.


IVIO_Device::get_Metrics

This method retrieves the data that describes the format of the data being sent to and returned from the interface’s components.

Syntax

HRESULT IVIO_Device::get_Metrics ( LPVIODEVICEMETRICS pVIODeviceMetrics );

Parameters

pVioDeviceMetrics
[out] Pointer to a VIODEVICEMETRICS structure, the members of which are set if the method returns successfully.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Successfully retrieved the metrics for the component.
E_POINTER | The pVioDeviceMetrics pointer is invalid.
E_UNEXPECTED | An unexpected error occurred while retrieving the metrics.


IVIO_Device::get_Status

The method retrieves the current availability of the device such as READY or BUSY.

Syntax

HRESULT IVIO_Device::get_Status ( DWORD *pStatus );

Parameters

pStatus
[out] Pointer to a DWORD that returns one of the following status values:
VIODEVSTATUS_READY
The device is ready to run.
VIODEVSTATUS_BUSY
The device is busy.
VIODEVSTATUS_UNAVAIL
The device is unavailable.
VIODEVSTATUS_SUSPENDED
The device is suspended. In other words, it is in low power operation.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Successfully retrieved the status of the device.
E_POINTER | The pStatus pointer is invalid.
E_UNEXPECTED | An unexpected error occurred while retrieving the status.


IVIO_Device::SetData

This method sends control information to the vehicle.

Syntax

HRESULT IVIO_Device::SetData ( const LPVARIANT pData, DWORD dwTimeout );

Parameters

pData
[in] Pointer to a VARIANT that contains the control information to be passed to the device component. The contents of the VARIANT vary according to which component is being used.
dwTimeOut
[out] Specifies, in milliseconds, the amount of time to wait for a reply to the control request.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Successfully sent control data to the device.
E_NOTIMPL | The device does not implement control functionality.
E_POINTER | The pData pointer is invalid.
E_ACCESSDENIED | Access to this device is denied.
E_UNEXPECTED | An unexpected error occurred while sending information to the device component.


IVIO_Device::SetNotify

This method provides the means to add a notification sink to a specified device. Through this sink, the device can send a notification to an application on a timed basis.

Syntax

HRESULT IVIO_Device::SetNotify ( const LPVARIANT pParameterData, IVIO_EventSink *pEventSink, DWORD dwFreq );

Parameters

pParameterData
[in] Pointer to a VARIANT structure that contains additional information for starting the notification. This would be the same information that a device component would require for input on a call to the GetData method.
pEventSink
[in] Pointer to an IVIO_EventSink interface. This interface’s method is called by the device at notification time. If the value is NULL, then the event sink is removed from the device component.
dwFreq
[out] Specifies, in milliseconds, the frequency at which the application should be notified by the device. This value should not be less than 500 milliseconds.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Notification sink was successfully added to the device.
E_NOTIMPL | The SetNotify method is not implemented for the device component. This may result if only write access is available on the device component.
E_POINTER | The pEventSink pointer is invalid.
E_ACCESSDENIED | A notification sink is already in place for the device component, or the device has exclusive read access.
E_UNEXPECTED | An unexpected error occurred while trying to add the notification sink to the device component.


IVIO_Device::set_AccessMode

This method sets the access mode—either shared or exclusive access—for the device. The mode is used with a read or write mode.

Syntax

HRESULT IVIO_Device::set_AccessMode( DWORD dwMode, DWORD dwAccessMode );

Parameters

[in] dwMode
Specifies the mode for which the access is to be set. It is one of the following values:
VIODEVICEMODE_READ
Sets the device’s read access.
VIODEVICEMODE_WRITE
Sets the device’s write access.
dwAccessMode
[in] Specifies the type of access requested for the device’s modes. The following table shows possible values for this parameter.
Access
Value
Description
VIODEVACCESS_SHARED | 0x0000 | Sets the device as a shareable device
VIODEVACCESS_EXCLUSIVE | 0x8000 | Sets the device as an exclusive device that cannot be shared

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The access mode was successfully set.
E_INVALID | One of the parameters is invalid.
E_ACCESSDENIED | The application was unable to change the access mode because another process or thread has already set the access.


IVIO_Ioctl

This interface enables applications to communicate directly with the VIO device driver.

Method
Description
IVIO_Ioctl::DoCommand Performs the direct communication with the device driver.


IVIO_Ioctl::DoCommand

This method performs the direct communication with the device driver.

Syntax

HRESULT IVIO_Ioctl::DoCommand( DWORD dwCommandId, const PVOID pCommandData, DWORD cb, PVOID pReply, DWORD dwOutputSize, DWORD *pReplySize );

Parameters

dwCommandId
[in] Specifies the device-driver command identifier. This information is furnished by the provider of the VIO hardware device driver.
pCommandData
[in] Pointer to a buffer that contains driver-specific data for the given command specified in dwCommandId.
cb
[in] Size of the buffer referenced by the pCommandData parameter.
pReply
[out] Pointer to a buffer that stores information returned by the device driver.
dwOutPutSize
[in] Specifies the size of the buffer referenced by the pReply parameter.
pReplySize
[out] Pointer to a DWORD value that contains the size of the data set stored in the buffer referenced by pReply.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The function was executed successfully. Reply data from the device driver is stored in the pReply buffer.
E_POINTER | Either the pCommandData, pReply, or pReplySize pointer is invalid.
E_INVALID | The value in dwCommandId is invalid for the device driver or the value given in dwOutputSize is too small for the amount of data in the reply. The correct size is stored in the value referenced by pReplySize.
E_UNEXPECTED | An unexpected error occurred in the request to the device driver.


IVIO_EventSink

This interface is used by IVIO_Device interface to notify an application.

Method
Description
IVIO_EventSink::ReceiveData Called from a component implementing the IVIO_Device interface’s SetNotify method when the notification period has elapsed.


IVIO_EventSink::ReceiveData

This method is called from a component implementing the IVIO_Device interface’s SetNotify method when the notification period has elapsed.

Syntax

HRESULT IVIO_EventSink::ReceiveData( LPVARIANT pData, LPARAM lParam );

Parameters

pData
[in] Pointer to a VARIANT record returned by the device component. The contents of the VARIANT are described in the documentation for each component.
lParam
[in] Value defined by the device component for additional information.

Return Values

S_OK indicates that the data was received successfully.

Remarks

This is the callback function used for the notification sink for the IVIO_Device interface.


IVIO_MiniDriverMgr

This interface is used to initialize the mini-drivers when the API is started.

Method
Description
IVIO_MiniDriverMgr::StartManager Starts the mini-driver manager.


IVIO_MiniDriverMgr::StartManager

This method starts the mini-driver manager.

Syntax

HRESULT IVIO_MiniDriverMgr::StartManager( PVOID *pReserved );

Parameters

pReserved
[in] Reserved.

Return Values

An appropriate HRESULT value is returned.


IVIO_MiniDriver

Use this interface to translate between the values that are expected by a specified IVIO_Device subclass and the raw information returned by the vehicle interface hardware’s device driver. This interface is created by the vendor of the vehicle interface hardware for each device subclass that is implemented in the API.

Method
Description
IVIO_MiniDriver::GetData | Corresponds to IVIO_Device::GetData.
IVIO_MiniDriver::SetData | Corresponds to IVIO_Device::SetData.
IVIO_MiniDriver::SetNotify | Begins timed notification of an API device component.
IVIO_MiniDriver::IOControl | Accesses mini-driver implementation-specific functionality.


IVIO_MiniDriver::GetData

This method corresponds to IVIO_Device::GetData.

Syntax

HRESULT IVIO_MiniDriver::GetData( IVIO_MiniDriverData *pInputData, IVIO_MiniDriverData **ppData, DWORD dwTimeout );

Parameters

pInputData
[in] Pointer to an IVIO_MiniDriverData interface that contains the input data from the device.
ppData
[out] Pointer to a pointer to an IVIO_MiniDriverData interface that contains the data from the device.
dwTimeout
[in] Specifies, in milliseconds, the amount of time to wait for a reply to the request for data.

This method retrieves the current data from the device.

Return Values

An appropriate HRESULT value is returned.


IVIO_MiniDriver::SetData

This method corresponds to IVIO_Device::SetData.

Syntax

HRESULT IVIO_MiniDriver::SetData( IVIO_MiniDriverData *pInputData, DWORD dwTimeout );

Parameters

pInputData
[in] Pointer to an IVIO_MiniDriverData interface that contains the input data from the device.
dwTimeout
[in] Specifies, in milliseconds, the amount of time to wait for the request to complete.

Return Values

An appropriate HRESULT value is returned.


IVIO_MiniDriver::SetNotify

This method begins timed notification of an API device component.

Syntax

HRESULT IVIO_MiniDriver::SetNotify( HANDLE *hNotifyEvent, IVIO_MiniDriverData *pInputData, IVIO_MiniDriverData **ppReturnedData, DWORD dwInterval );

Parameters

hNotifyEvent
[in] Handle to an event that is used by the mini-driver to notify the API that a new notification is ready from the mini-driver.
pInputData
[in] Pointer to an IVIO_MiniDriverData interface that contains the input data from the device.
ppReturnedData
[in] Pointer to a pointer to an IVIO_MiniDriverData interface that is stored when a notification is ready.
dwInterval
[in] Specifies, in milliseconds, the amount of time to send notifications to the device component.

Return Values

An appropriate HRESULT value is returned.


IVIO_MiniDriver::IOControl

This method accesses mini-driver implementation-specific functionality.

Syntax

HRESULT IVIO_MiniDriver::IOControl( DWORD dwCommandId, const PVOID pCommandData, DWORD cb, PVOID pReply, DWORD dwOutputSize, DWORD *pReplySize );

Parameters

dwCommandId
[in] Specifies the device driver-specific command identifier. This information is furnished by the vendor of the vehicle interface hardware device driver.
pCommandData
[in] Pointer to a buffer that contains driver-specific data for the specified command specified in dwCommandId.
cb
[in] Size of the buffer referenced by the pCommandData parameter.
pReply
[out] Pointer to a buffer to contain information returned by the device driver.
dwOutputSize
[in] Specifies the size of the buffer referenced by the pReply parameter.
pReplySize
[out] Pointer to a DWORD value that contains the size of the data set stored in the buffer referenced by pReply.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | The function was executed successfully. Reply data from the device driver is stored in the pReply buffer.
E_POINTER | Either the pCommandData, the pReply, or the pReplySize pointer is invalid.
E_INVALID | The value in dwCommandId is invalid for the device driver or the value given in dwOutputSize is too small for the amount of data in the reply. The correct size is stored in the value referenced by pReplySize.
E_UNEXPECTED | An unexpected error occurred in the request to the device driver.


IVIO_MiniDriverData

Use this interface to return data buffer information.

Method
Description
IVIO_MiniDriverData::get_DataBuffer | Gets the address of a data buffer.
IVIO_MiniDriverData::get_DataBufferSize | Gets the size of the data buffer.


IVIO_MiniDriverData::get_DataBuffer

This method gets the address of a data buffer.

Syntax

HRESULT IVIO_MiniDriverData::get_DataBuffer( PVOID *ppv, );

Parameters

ppv
[in] Pointer to a void pointer to the buffer that contains driver-specific data.

Return Values

An appropriate HRESULT value is returned.


IVIO_MiniDriverData::get_DataBufferSize

This method gets the size of the data buffer.

Syntax

HRESULT IVIO_MiniDriverData::get_DataBufferSize( DWORD *pcbDataBuffer, );

Parameters

pcbDataBuffer
[in] Pointer to the size of the buffer that contains driver-specific data.

Return Values

An appropriate HRESULT value is returned.


IPosNav

This interface provides methods required to utilize Auto PC related Global Positioning System (GPS) capabilities.

Method
Description
IPosNav::CloseDevice | Closes a Positioning and Navigation device
IPosNav::DeleteDeviceList | Deletes a linked list of PNDEVICE structures
IPosNav::FindDevices | Finds all connected Positioning and Navigation devices on the system
IPosNav::GetData | Gets various types of data from a Positioning and Navigation device
IPosNav::OpenDevice | Opens a Positioning and Navigation device for communication
IPosNav::SetData | Sends data to either the Positioning and Navigation device or the registry
IPosNav::StartCall | Starts a call to get data from the Positioning and Navigation device
IPosNav::StopCall | Stops a call to the Positioning and Navigation device
IPosNav::BearingToVelocity | Converts a bearing and two speeds to east, north, and up velocities
IPosNav::DegreesToRadians | Converts latitude, longitude, and altitude data from degrees to radians
IPosNav::PNTMToWintm | Converts a time in the format specified by the PNTM structure to the format specified by the Microsoft Windows CE SYSTEMTIME structure
IPosNav::RadiansToDegrees | Converts latitude, longitude, and altitude data from radians to degrees
IPosNav::VelocityToBearing | Converts east, north, and up velocity data to a bearing and two speeds.
IPosNav::WintmToPNTM | Converts a time in the format specified by the Windows CE SYSTEMTIME format to a format specified by the PNTM structure

Remarks

The IPosNav interface handles most GPS-related tasks.

The only supported Positioning and Navigation device is the GPS device.


IPosNav::CloseDevice

This method closes a Positioning and Navigation device.

Syntax

HRESULT CloseDevice( hPNDevice hPN, );

Parameters

hPN
Handle to the Positioning and Navigation device to be closed

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success
E_FAIL | An unspecified error occurred.
E_INVALIDARG | One or more arguments are invalid.
PNAPI_E_DEVICEUNAVAILABLE | The Positioning and Navigation device is unavailable; it could be unplugged or dead.
PNAPI_E_MEMFREE | The memory or resource cannot be freed.

Remarks

If this method is not called upon exiting, position and navigation API (PNAPI) resources are not deleted.

This method must wait for pending calls to finish before stopping calls to a Positioning and Navigation device. It may pause briefly before returning.

See Also

IPosNav::OpenDevice


IPosNav::DeleteDeviceList

This method deletes a linked list of PNDEVICE structures.

Syntax

HRESULT DeleteDeviceList ( pPNDEVICE pPNDeviceHead );

Parameters

pPNDeviceHead
Pointer to the first structure in the linked list.

Return Values

S_OK indicates success. If an error occurs, the appropriate HRESULT value is returned.

Remarks

After opening the selected Positioning and Navigation device, delete the linked list of PNDEVICE structures that you retrieved with the FindDevices method by calling the DeleteDeviceList method.

See Also

IPosNav::FindDevices


IPosNav::FindDevices

This method finds all connected Positioning and Navigation devices on the system.

Syntax

HRESULT FindDevices( ppPNDEVICE ppDevArray, DWORD *pdwNumDev );

Parameters

pDevArray
Pointer to an array of PNDEVICE pointers. This parameter returns the first item in a linked list of PNDEVICE structures. Destroy this list with the DeleteDeviceList method.
pdwNumDev
Pointer to the DWORD that contains the number of Positioning and Navigation devices found

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success
E_FAIL | An unspecified error occurred.
E_INVALIDARG | One or more arguments are invalid.
TYPE_E_DLLFUNCTIONNOTFOUND | The method was not defined in the specified DLL.
REGDB_E_READREGDB | A registry key could not be read.
PNAPI_E_INVALIDREGDBVALUE | There is an invalid value in the registry.
PNAPI_E_REGDBCLOSEKEY | A registry key cannot be closed.
PNAPI_E_MEMFREE | Memory or resource cannot be freed.
PNAPI_E_BADOS | There is an invalid operating system version.
E_OUTOFMEMORY | The position and navigation API (PNAPI) is out of memory.

Remarks

The IPosNav::FindDevices method returns data for Positioning and Navigation devices in an unknown status, but does not return data for non-operational devices.

See Also

IPosNav::DeleteDeviceList, IPosNav::OpenDevice


IPosNav::GetData

This method gets various types of data from a Positioning and Navigation device.

Syntax

HRESULT GetData ( hPNDevice hPN, LPVOID pBuffer, DWORD dwSize, PNData_t DataType );

Parameters

hPN
Handle to the Positioning and Navigation device to use
pBuffer
Pointer to the buffer that receives the data
dwSize
Specifies, in bytes, the size of pBuffer
DataType
Type of data to get from the Positioning and Navigation device. The following types of data can be requested.
Value
Description
Structure type
PN_DT_ACCURACY | Accuracy data | PNACCURACY
PN_DT_ALMANAC | Almanac data | PNALMANAC
PN_DT_CONFIG | Configuration data | PNCONFIG
PN_DT_DEVICE | Device profile data | PNDEVICE
PN_DT_DEVICESTATE | Device state data | PNDEVSTATE
PN_DT_POSITION | Longitude, latitude, and altitude position data | PNPOSITION
PN_DT_SETTINGS | Settings data | PNSETTINGS
PN_DT_STATION | Station data | PNSTATION
PN_DT_TIME | Time data | PNTIME
PN_DT_TM | Time data | PNTM
PN_DT_VELOCITY | Velocity data | PNVELOCITY

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success
E_FAIL | An unspecified error occurred.
E_INVALIDARG | One or more arguments are invalid.
PNAPI_E_DEVICEUNAVAILABLE | The Positioning and Navigation device is unavailable; it could be unplugged or dead.
PNAPI_E_NOCALLSTARTED | No call has been started yet.
PNAPI_E_NODATAYET | No data has been received from the Positioning and Navigation device yet.

Remarks

PNAPI enables various OEM-defined PNData_t enumerations to be passed through this method so that specific features can be made available. OEM vendors should provide details about how they have implemented their structures.

All data is received from the Positioning and Navigation device except PNCONFIG data, which is taken from the registry.

The almanac data is GPS-specific and provides system satellite position data.

See Also

IPosNav::SetData


IPosNav::OpenDevice

This method opens a Positioning and Navigation device for communication.

Syntax

HRESULT OpenDevice ( phPNDevice phPN, pPNDEVICE pDevice );

Parameters

phPN
Pointer to a Positioning and Navigation device handle. The phPNDevice type is declared as LPVOID. If successful, a valid Positioning and Navigation handle is returned.
pDevice
Pointer to the PNDEVICE structure for the device to be opened. This structure is returned by FindDevices.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success
E_FAIL | An unspecified error occurred.
E_INVALIDARG | One or more arguments are invalid.
E_OUTOFMEMORY | The position and navigation API (PNAPI) has run out of memory.
REGDB_E_READREGDB | A registry key could not be read.
PNAPI_E_REGDBCLOSEKEY | A registry key could not be closed.
PNAPI_E_LOADDLL | DLL could not be loaded.
PNAPI_E_DEVICEUNAVAILABLE | The Positioning and Navigation device is unavailable; it could be unplugged or dead.

See Also

IPosNav::FindDevices, IPosNav::CloseDevice


IPosNav::SetData

This method sends data to either the Positioning and Navigation device or the registry.

Syntax

HRESULT SetData( hPNDevice hPN, LPVOID pBuffer, DWORD dwSize, PNData_t Data_Type );

Parameters

hPN
Handle to the Positioning and Navigation device to use
pBuffer
Pointer to a buffer to hold the data. The format is determined by Data_Type.
dwSize
Specifies, in bytes, the size of pBuffer
Data_Type
The following Positioning and Navigation device data types can be set.
Value
Description
Structure type
PN_DT_ACCURACY | Accuracy data | PNACCURACY
PN_DT_ALMANAC | Almanac data | PNALMANAC
PN_DT_CONFIG | Configuration data | PNCONFIG
PN_DT_DEVICE | Device profile data | PNDEVICE
PN_DT_DEVICESTATE | Device state data | PNDEVSTATE
PN_DT_POSITION | Longitude, latitude, and altitude position data | PNPOSITION
PN_DT_SETTINGS | Settings data | PNSETTINGS
PN_DT_STATION | Station data | PNSTATION
PN_DT_TIME | Time data | PNTIME
PN_DT_TM | Time data | PNTM

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success
E_FAIL | An unspecified error occurred.
E_INVALIDARG | One or more arguments are invalid.
E_NOTIMPL | Ability to set the specified data type, such as PN_DT_VELOCITY, is not implemented.
PNAPI_E_DEVICEUNAVAILABLE | The Positioning and Navigation device is unavailable; it could be unplugged or dead.
PNAPI_E_NOACCESS | The application has insufficient permissions.

Remarks

Position and time can be set to enable the Positioning and Navigation device to find its position more quickly.

The configuration data in the PNCONFIG structure is stored in the registry by this method. The settings contained are also used to update the configuration of the Positioning and Navigation device. If any parameters do not apply to the Positioning and Navigation device, they are ignored by the position and navigation API (PNAPI).

Almanac data is GPS-specific and is received from the Positioning and Navigation device by the IPosNav::GetData method. The almanac details are stored in the registry only through the PNCONFIG structure. The almanac data should not be altered. It provides accurate GPS satellite position data. If almanac data is passed to this method, the system may acquire a GPS satellite position faster.

PNAPI enables various OEM-defined PNData_t enumerations to be passed through this method so that specific features can be made available. OEM vendors should provide details about how they have implemented their structures.

All data is received from the Positioning and Navigation device except PNCONFIG data, which is taken from the registry.

Only applications with read/write permission can use this method, except when the user wishes to change permissions.

The PNTIME structure contains an accurate time in Universal Coordinated Time (UTC), also known as Greenwich mean time (GMT).

See Also

IPosNav::GetData


IPosNav::StartCall

This method starts a call to get data from the Positioning and Navigation device.

Syntax

HRESULT StartCall ( hPNDevice hPN, PNData_t Call, DWORD dwPeriod );

Parameters

hPN
Handle to the Positioning and Navigation device to use.
Call
Type of data to retrieve from Positioning and Navigation device. All PNData_t calls valid for the GetData function can be used for Call.
dwPeriod
Specifies, in milliseconds, the time period between updates of data. If dwPeriod equals 0, only one call is made, and you do not need to stop the call with IPosNav::StopCall. If dwPeriod equals 1, the call can be made as rapidly as the device permits. If dwPeriod equals any other value, the StartCall method interprets that value as a period of time.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success
E_FAIL | An unspecified error occurred.
E_INVALIDARG | One or more arguments are invalid.
PNAPI_E_DEVICEUNAVAILABLE | The Positioning and Navigation device is unavailable; it could be unplugged or dead.
PNAPI_E_DATAUNAVAILABLE | The data is unavailable.
PNAPI_S_CALLALREADYSTARTED | A warning that indicates a call was already started.
PNAPI_S_PERIODTOOSMALL | A Positioning and Navigation device is unable to support a call period at the requested speed.

Remarks

This method instructs the device to update its associated data structures at specified intervals. Through the GetData method, a user can obtain current data from the Positioning and Navigation device’s data structures within the position and navigation API (PNAPI) as often as needed.

See Also

IPosNav::GetData, IPosNav::StopCall


IPosNav::StopCall

This method stops a call to the Positioning and Navigation device.

Syntax

HRESULT StopCall ( hPNDevice hPN, PNData_t Call );

Parameters

hPN
Handle to the Positioning and Navigation device in use.
Call
Type of data to retrieve from the Positioning and Navigation device. All PNData_t calls valid for the GetData function can be used for Call.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Success
E_FAIL | An unspecified error occurred.
E_INVALIDARG | One or more arguments are invalid.
PNAPI_E_DEVICEUNAVAILABLE | The Positioning and Navigation device is unavailable; it could be unplugged or dead.
PNAPI_E_NOCALLSTARTED | No call has been started yet.

Remarks

If a call has been started using IPosNav::StartCall with the dwPeriod set to 0, then the call does not need to be stopped with IPosNav::StopCall. A value of 0 indicates the call is made once, and then stopped.

See Also

IPosNav::StartCall


IPosNav::BearingToVelocity

This method converts a bearing and two speeds to east, north, and up velocities.

Syntax

HRESULT BearingToVelocity ( const pPNVELENU pENUVel, pPNVELBEAR pBearVel );

Parameters

pENUVel
Pointer to a PNVELENU structure that contains the velocity data
pBearVel
Pointer to a PNVELBEAR structure to store the bearing data

Return Values

S_OK indicates success. E_INVALIDARG indicates that one or more arguments are invalid.

Remarks

The horizontal speed and bearing members of the PNVELBEAR structure define a velocity vector in the plane defined by the north to south and east to west axes. This method resolves that vector into northward and eastward components. A southward velocity is represented as a negative north velocity, and an westward velocity is represented as a negative east velocity.

See Also

IPosNav::VelocityToBearing, PNVELBEAR, PNVELENU


IPosNav::DegreesToRadians

This method converts latitude and longitude data from degrees to radians.

Syntax

HRESULT DegreesToRadians ( pPNPOSLLA pLLAPos );

Parameters

pLLAPos
Pointer to a PNPOSLLA structure that contains the latitude, longitude, and altitude data. The structure is returned with the same position in radians.

Return Values

S_OK indicates success. E_INVALIDARG indicates that one or more arguments are invalid.

Remarks

If the PNPOSLLA structure contains a latitude and a longitude expressed in degrees, as indicated by a FALSE value for the PNSOLLA fRadians parameter, this method converts those values to radians by multiplying those values by pi/180. This method converts those values in place, so that the PNSOLLA structure contains latitude and longitude values expressed in radians after this method returns.

See Also

IPosNav::RadiansToDegrees, PNPOSLLA


IPosNav::PNTMToWintm

This method converts a time in the format specified by the PNTM structure to the format specified by the Windows CE SYSTEMTIME structure.

Syntax

HRESULT PNTMToWintm ( SYSTEMTIME pTime, const PNTM pNTM );

Parameters

pTime
Pointer to a structure that receives the time in the format specified by the SYSTEMTIME structure.
pNTM
Pointer to the time to be converted, in the format specified by the PNTM structure.

Return Values

S_OK indicates success. E_FAIL indicates that unspecified error occurred. E_INVALIDARG indicates one or more arguments are invalid.

See Also

IPosNav::WintmToPNTM, PNTM, SYSTEMTIME


IPosNav::RadiansToDegrees

This method converts latitude and longitude data from radians to degrees.

Syntax

HRESULT RadiansToDegrees ( pPNPOSLLA pLLAPos );

Parameters

pLLAPos
Pointer to a PNPOSLLA structure that contains latitude, longitude, and altitude data. The structure is returned with the same position in degrees.

Return Values

S_OK indicates success. E_INVALIDARG indicates one or more arguments are invalid.

Remarks

If the PNPOSLLA structure contains a latitude and a longitude expressed in radians, as indicated by a TRUE value for the PNSOLLA fRadians parameter, this method converts those values to degrees by multiplying those values by 180/pi. This method converts those values in place, so that the PNSOLLA structure contains latitude and longitude values expressed in degrees after this method returns.

See Also

IPosNav::DegreesToRadians, PNPOSLLA


IPosNav::VelocityToBearing

This method converts east, north, and up velocity data to a bearing and two speeds.

Syntax

HRESULT VelocityToBearing( pPNVELBEAR pBearVel, const pPNVELENU pENUVel );

Parameters

pBearVel
Pointer to a PNVELBEAR structure to store bearing data.
pENUVel
Pointer to a PNVELENU structure that contains velocity data.

Return Values

S_OK indicates success. E_INVALIDARG indicates one or more arguments are invalid.

See Also

IPosNav::BearingToVelocity, PNVELBEAR, PNVELENU


IPosNav::WintmToPNTM

This method converts a time in the format specified by the Windows CE SYSTEMTIME structure to the format specified by the PNTM structure.

Syntax

HRESULT WintmPNTM ( PNTM pNTM, const SYSTEMTIME pTime, );

Parameters

pNTM
Pointer to a structure that receives the time in the format specified by the PNTM structure.
pTime
Pointer to the time to be converted, in the format specified by the Windows CE SYSTEMTIME structure.

Return Values

S_OK indicates success. E_FAIL indicates that unspecified error occurred. E_INVALIDARG indicates one or more arguments are invalid.

See Also

IPosNav::PNTMToWintm


IVerifyContactSink

This interface provides methods that allow an application to modify how the address book responds to events .

Method
Description
IsContactValid Checks whether the information stored for a contact is valid.

See Also

ABDIALOGINFO


IVerifyContactSink::IsContactValid

This method checks whether the information stored for a contact is valid.

Syntax

HRESULT IsContactValid( CEOID ceoidContact, PROPID propidAddress, BSTR* pbstrExplanation);

Parameters

ceoidContact
Object identifier for the contact.
propidAddress
Property identifier that specifies the fields from the contact's address that you want to validate. It is one of the following values.
Value
Description
HHPR_OFFICE_ADDRESS_STREET | Street address for the contact's workplace.
HHPR_HOME_ADDRESS_STREET | Street address for the contact's home.

pbstrExplanation
Pointer to a Unicode string that receives an explanation of how the contact's information is invalid. The address book currently passes a NULL pointer for this parameter. If the application returns a pointer, the address book frees the memory for the BSTR.

Return Values

S_OK indicates that the information for the contact is valid. S_FALSE indicates that the information for the contact is not valid.

See Also

ABDIALOGINFO


AAM_AudioIoControl

This function routes the DeviceIoControl function to the appropriate device drivers.

Syntax

DWORD AAM_AudioIoControl ( DWORD dwFlag, DWORD dwIoControlCode, LPVOID lpInBuf, DWORD nInBufSize, LPVOID lpOutBuf, DWORD nOutBufSize, LPDWORD lpBytesReturned, LPOVERLAPPED lpOverLapped );

Parameters

dwFlag
Specifies a bitmask for flags. It is one of the following values:
AAM_FLAG_IEQ
Calls EQ-related device drivers.
AAM_FLAG_ISSD
Calls surround sound-related device drivers.
AAM_FLAG_IVOLUME
Calls volume-related device drivers.
dwIoControlCode
Specifies the control code of the operation to perform.
lpInBuf
Long pointer to a buffer that supplies input data to the DeviceIoControl function.
nInBufSize
Size of input buffer.
lpOutBuf
Long pointer to buffer that receives output data from the DeviceIoControl function.
nOutBufSize
Size of output buffer.
lpBytesReturned
Long pointer to the variable that receives output byte count.
lpOverLapped
Long pointer to an OVERLAPPED structure.

Return Values

Zero indicates success. AAM_ERR_DEVICEFAIL indicates that the device failed to respond. AAM_ERR_NOTSUPPORTED indicates that no device driver is available.

If the DeviceIoControl succeeds (returns non-zero), this function returns 0. If DeviceIoControl fails (returns zero), this function returns AAM_ERR_DEVICEFAIL.

This function returns a flag. Based on the dwFlag value, this function routes the DeviceIoControl function to the appropriate device.

See Also

DeviceIoControl, OVERLAPPED


AAM_EnableSSD

This function enables or disables surround-sound decoding.

Syntax

DWORD AAM_EnableSSD ( BOOL bEnable );

Parameters

bEnable
Boolean that is set to TRUE to enable surround-sound decoding, or to FALSE to disable it.

Return Values

Zero indicates success. AAM_ERR_DEVICEFAIL indicates that the device does not support surround-sound decoding.

Remarks

This function is a member of the surround-sound decoding API.


AAM_EQBandControl

This function controls the gain, center frequency, and bandwidth of each band.

Syntax

DWORD AAM_EQBandControl( DWORD dwIndex, DWORD dwFlags, LONG *plValue );

Parameters

dwIndex
Specifies the index of the band.
dwFlags
Specifies a bitmask for flags. It is one of the following values:
AAM_FLAG_CENTERFREQ
Get or set the center frequency; in hertz.
AAM_FLAG_BANDWIDTH
Get or set the bandwidth; in hertz.
AAM_FLAG_GAIN
Get or set the gain in decibels.

To set a property, use a bitwise OR to combine the chosen flag with AAM_FLAG_SET, and set pValue to the desired value. To get a property, use a bitwise OR to combine the chosen flag with AAM_FLAG_GET and pValue is set to the current value. To get the range, use a bitwise OR to combine the chosen flag with AAM_FLAG_RANGE, and pValue is set to the current value.

plValue
Pointer to the value of dwFlags.

When you combine the AAM_FLAG_RANGE flag with one of the flags specified in dwFlags, pValue represents the following:

  • For center frequency or bandwidth, the high-order word contains the minimum value and the low-order word contains the maximum value. If these two values are the same, then the value cannot be changed.
  • For gain, the high-order word has the maximum attenuation level and the low-order word has the maximum gain level. For example, if the gain can be adjusted from -16 to +16, the high-order word contains -16 and the low-order word contains 16.

Return Values

Zero indicates success. AAM_ERR_INVALIDPARAM indicates an invalid parameter. AAM_ERR_DEVICEFAIL indicates failure. AAM_ERR_NOTSUPPORTED indicates that the device does not support this feature.

Remarks

This function is a member of the equalization API. The equalizer only supports decibel-based gain units.

See Also

HIWORD, LOWORD


AAM_EQPreset

This function adjusts the built-in audio controls.

Syntax

DWORD AAM_EQPreset( DWORD dwFlag LONG *plValue);

Parameters

dwFlag
Specifies a bitmask fo flags. It is one of the following values:
AAM_FLAG_SET
If set, the function sets the EQ to the desired preset equalization. If not set, this function retrieves the current EQ settings.
AAM_FLAG_RANGE
To get the range of values that can be set, combine the selected flag with AAM_FLAG_RANGE. The function returns only a single value in plValue but the actual value is from -plValue to +plValue. However, a plValue of 1 indicates that the value of the property is binary and can only be activated (nonzero) and deactivated (0).
AAM_FLAG_TREBLE
Gets or sets the level of the treble control.
AAM_FLAG_BASS
Gets or sets the level of the bass control.
AAM_FLAG_LOUDNESS
Gets or sets the level of the loudness control (usually 0 or 1).
AAM_FLAG_EQBYPASS
Gets or sets the EQ bypass status. When activated, this bypasses the treble, bass, loudness and any other equalization controls except de-emphasis.
AAM_FLAG_DEEMPHASIS
Gets or sets the status of the de-emphasis filter. When activated, this provides compensation for compact discs recorded with pre-emphasis.
plValue
Pointer to a value to get or set, depending on the dwFlag setting.

Return Values

Zero indicates success. AAM_ERR_INVALIDPARAM indicates an invalid parameter. AAM_ERR_DEVICEFAIL indicates failure. AAM_ERR_NOTSUPPORTED indicates that the device does not support this feature.

Remarks

To set a property combine the selected flag with AAM_FLAG_SET and set plValue to the desired value. To get a property combine the selected flag with AAM_FLAG_GET and plValue will be set to the current value when the call returns.


AAM_FilterControl

This function allows control of the digital crossover filter parameters.

Syntax

DWORD AAM_FilterControl ( DWORD dwFlags, DWORD *plEnable, DWORD *plFreq );

Parameters

dwFlags
Specifies a bitmask of flags. It is one of the following values:
AAM_FLAG_CROSSOVER_LPF
Combine with AAM_FLAG_SET to enable, disable, and set the frequency of the low-pass filter (LPF). Combine with AAM_FLAG_RANGE to get the range of LPF frequencies that may be set.
AAM_FLAG_CROSSOVER_HPF
Combine with AAM_FLAG_SET to enable, disable, and set the frequency of the high-pass filter (HPF). Combine with AAM_FLAG_RANGE to get the range of HPF frequencies that may be set.
AAM_FLAG_CROSSOVER
Combine with AAM_FLAG_SET to enable, disable, and set the frequency of crossover frequencies (LPF and HPF). Combine with AAM_FLAG_RANGE to get the range of crossover frequencies that may be set. This flag is for use in implementations that do not support separate control of the high-pass and low-pass filter.
AAM_FLAG_GET
When combined with a filter flag, retrieves the current filter settings. The enabled status of the filter is returned in plEnable and current frequency is returned in plFreq.
AAM_FLAG_RANGE
When combined with a filter flag, retrieves the range over which the frequency can be set, and indicates whether or not the filter can be enabled or disabled. The following table shows the information returned in the plEnable parameter.
Low-order word
High-order word
Description
0 | 0 | No such filter available
Nonzero | 0 | Filter is available and can be enabled or disabled.
Nonzero | Nonzero | Filter is available and is always enabled.

The following table shows the information returned in the plFreq parameter.
Low-order word
High-order word
Description
Maximum adjustable frequency, in hertz. Minimum adjustable frequency, in hertz. Specifies the frequency range.

AAM__FLAG_SET
When combined with a filter flag, allows you to enable, disable, and set the frequency of the filter.
plEnable
Pointer to a DWORD used to return or set whether or not the filter is enabled.
plFreq
Pointer to a DWORD used to return or set the frequency.

Return Values

Zero indicates success. AAM_ERR_INVALIDPARAM indicates an invalid parameter. AAM_ERR_NOTSUPPORTED indicates a filter or action is not supported in a particular implementation. AAM_ERR_OUTOFRANGE indicates a requested frequency value was not in the valid range of the filter.

Remarks

Do not set both the AAM_FLAG_SET and AAM_FLAG_RANGE flags.


AAM_GetEQCaps

This function retrieves the capabilities of the equalizer.

Syntax

DWORD AAM_GetEQCaps( DWORD *pdwCap );

Parameters

pdwCap
Pointer to a DWORD in which the lowest byte holds the number of bands that are available. The remaining three bytes hold a combination of the following values:
AAM_FLAG_TREBLE
Support treble control.
AAM_FLAG_BASS
Support bass control.
AAM_FLAG_LOUDNESS
Support loudness control.
AAM_FLAG_EQBYPASS
Control whether the equalizer can be bypassed or not.

Return Values

Zero indicates success. AAM_ERR_INVALIDPARAM indicates an invalid parameter.

Remarks

This function is a member of the equalization API.


AAM_GetNumSources

This function returns the total number of registered audio sources.

Syntax

DWORD AAM_GetNumSources( void );

Return Values

The number of audio sources indicates success. Zero indicates no audio sources, which is usually an error.

Remarks

This function is a member of the audio source control API.


AAM_GetSourceCap

This function returns the capabilities of a specified audio source.

Syntax

DWORD AAM_GetSourceCap( IN DWORD dwIndex, OUT AAM_SRCCAP *pASC );

Parameters

dwIndex
Specifies the index of the audio source. It is one of the following flags:
Flag
Value
Description
AAM_SRC_BYID | 0x00000000 | Use the audio source identifier.
AAM_SRC_BYINDEX | 0x80000000 | Specifies the source with an index ranging from 0 to GetNumSources minus 1; in other words, use the bitwise OR to combine the index with the flag.

pASC
Pointer to an AAM_SRCCAP structure to hold the returned information.

Return Values

Zero indicates success. AAM_ERR_INVALIDPARAM indicates an invalid parameter

Remarks

This function is part of the audio source control API.

The main use of this function is to get an audio source identifier, which the application uses to select the source. An application can get the AAM_SRCCAP structure of a particular audio source and check the m_dwinfo member of that structure. If AAM_FLAG_SELECTED is set, then that audio source is active.

See Also

AAM_SRCCAP


AAM_GetSSDCaps

This function tells what type of surround-sound decoding the system supports.

Syntax

DWORD AAM_GetSSDCaps( DWORD *pdwCap );

Parameters

pdwCap
Pointer to a DWORD that contains information about what surround-sound decoding methods the system supports. The value returned is a combination of one or more of the following flags:
AAM_SSD_AC3
AAM_SSD_DOLBY
AAM_SSD_MSV1
AAM_SSD_PROLOGIC
AAM_SSD_THX

Return Values

Zero indicates success. AAM_ERR_NOTSUPPORTED indicates that the device does not have surround sound capability.


AAM_RegisterAudioCtrl

This function is called by device drivers to register the audio sources and audio control node, which is used to control the audio flow path.

Syntax

DWORD AAM_RegisterAudioCtrl( AAM_SRCCAP pSrc, BOOL bRegister );

Parameters

pSrc
Pointer to an AAM_SRCCAP structure that contains information about the audio source.
bRegister
Boolean that is set to TRUE to register the control or to FALSE to deregister it.

Return Values

Zero indicates success. AAM_ERR_ALREADYEXIST indicates that the source is already registered.

Remarks

This function is a member of the audio source control API.

If an audio source is currently selected, deregistering the audio source automatically deselects the source.

This function is used by Plug and Play audio devices to register audio sources.

If the audio source is depending on another audio control node, the node’s identifier should be put in the m_dwInfo member of the AAM_SRCCAP structure.


AAM_RegisterCallback

This function registers a callback thread to receive notification of source selection or deselection.

Syntax

DWORD AAM_RegisterCallback( DWORD idThread, BOOL bRegister );

Parameters

idThread
Identifier of the callback thread that receives the appropriate message.
bRegister
Boolean that is set to TRUE to register the callback thread, or to FALSE to deregister it.

Return Values

Zero indicates success. AAM_ERR_INVALIDPARAM indicates an invalid parameter

Remarks

This function is a member of the audio source control API.

When an audio source is selected or unselected, the system posts either a WM_AUDSRCSELECT or WM_AUDSRCUNSELECT message. When an audio source is registered or unregistered, the system posts either a WM_AUDSRCREGISTER or WM_AUDSRCUNREGISTER message. In both cases, the wParam of the message is set to the audio source identifier.


AAM_SelectSource

This function selects an audio source to be played.

Syntax

DWORD AAM_SelectSource( DWORD dwAudioSourceID );

Parameters

dwAudioSourceID
Specifies the identifier of the audio source to be played. AAM_SRC_NOSOURCE is a defined identifier that stops the current audio source.

Return Values

Zero indicates success. AAM_ERR_INVALIDPARAM indicates an invalid parameter.

Remarks

This function is a member of the audio source control API.

The source identifier can be obtained from AAM_GetSourceCap. When called, AAM_SelectSource stops the audio source that is currently playing, and loads the new source driver.

An audio application must call AAM_SelectSource to select a source prior to playing it, even if the application can load the device driver directly.

See Also

AAM_GetSourceCap


AAM_SSDControl

This function determines whether or not surround-sound decoding is enabled, and can also be used to set the type of surround-sound decoding.

Syntax

DWORD AAM_SSDControl( DWORD dwFlag LONG *plValue );

Parameters

dwFlag
Specifies information concerning surround-sound decoding. If dwFlag equals AAM_FLAG_GET | AAM_FLAG_SSD_TYPE, plValue contains the surround-sound decoding type that is currently set. If dwFlag is set to AAM_FLAG_SET, plValue is a pointer to the type of surround sound decoding to set. In this case, plValue can contain any of the values returned by AAM_GetSSDCaps.
plValue
Pointer to a long integer that contains the type of surround-sound decoding currently set. If plValue equals AAM_SSD_DISABLED, surround sound decoding is disabled.

Return Values

Zero indicates success. AAM_ERR_NOTSUPPORTED indicates failure.

Remarks

Use AAM_FLAG_GET or AAM_FLAG_SET combined with AAM_FLAG_SSD_TYPE to get or set the current SSD setting.

See Also

AAM_GetSSDCaps


AAM_VolumeControl

This function controls volume, balance, and fade.

Syntax

DWORD AAM_VolumeControl( DWORD dwFlag, LONG *plValue );

Parameters

dwFlag
Specifies a bitmask of flags. It is one of the following values:
AAM_FLAG_VOLUME
Gets or sets the master volume attenuation (0 specifies maximum gain).
AAM_FLAG_VOLUME_MASTER
Sets the master volume.
AAM_FLAG_RANGE
Gets the range of values in plValue. This option cannot be set, only retrieved.
AAM_FLAG_DBBASED
Specifies the use of decibel units rather than OEM-defined increments.
AAM_FLAG_MUTE
Gets or sets the mute status. This option is used by the system mute button.TRUE means that mute is on. The mute button mutes only background audio.
AAM_FLAG_VOLUME_SOURCE0
Indicates volume source 0, which is background music.
AAM_FLAG_VOLUME_SOURCE1
Indicates volume source 1, which is foreground text-to-speech (TTS) and event sounds.
AAM_FLAG_BALANCE
Gets or sets the attenuation of the left speakers (positive) and right (negative) speakers.
AAM_FLAG_FADE
Gets or sets the attenuation of the rear speakers (positive) and front (negative) speakers.
AAM_FLAG_CENTER
Gets or sets the attenuation level of the center speaker.
AAM_FLAG_WOOFER
Gets or sets the attenuation level of the subwoofer.

To set a property, use a bitwise OR to combine the chosen flag with AAM_FLAG_SET, and set plValue to the desired value. To get a property, use a bitwise OR the flag with AAM_FLAG_GET and plValue is set to the current value.

plValue
Pointer to a long integer.

Return Values

Zero indicates success. AAM_ERR_INVALIDPARAM indicates an invalid parameter. AAM_ERR_DEVICEFAIL indicates failure. AAM_ERR_NOTSUPPORTED indicates that the device does not support this feature.

Remarks

To get the range of values available, set the AAM_FLAG_RANGE flag. The function returns the maximum and minimum volume attenuation. The high-order word has the maximum attenuation level and the low-order word the maximum gain level. In the case of parameters like balance and fade, the minimum value may be negative. For example, if the high-order word for balance is 0 and the low-order word is 20, it means that the left speaker can be adjusted from 0 to 20, and the right speaker from 0 to -20. Fade works in a similar fashion.

See Also

HIWORD, LOWORD


CPMRegister

This function registers a critical process.

Syntax

BOOL CMPRegister ( DWORD dwProcessId, DWORD dwNotifyInterval, DWORD dwRecoverFlags, WCHAR *pCommandLine, PCPMCALLBACK pfnCPMCallBack, DWORD dwRecoverFailFlags );

Parameters

dwProcessId
[in] Specifies the process identifier.
dwNotifyInterval
[in] Specifies how often, in milliseconds, the application should notify the critical process monitor that it is still functioning.
dwRecoverFlags
[in] Specifies what kind of actions the critical process monitor should take to recover the process. It is the following flag.
CPM_RELAUNCH
The critical process needs to relaunch the process if the process is not responding.
pCommandLine
[in] Pointer to the command line Unicode string that launches the process.
pfnCPMCallBack
[in] Pointer to a callback function within the calling process.
dwRecoverFailFlags
[in] Specifies that actions should be taken if recovery failed. It is the following flag.
CPM_RELAUNCH_FAIL_OK
No action is taken.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

Only a process that is essential for the proper operation of the Auto PC should call this function. The process must call CPMNotify at a rate at least as frequent as the notification interval that the process passes to CPMRegister. The process must also define the callback function that the process registers by calling CPMRegister,

See Also

CPMNotify, CPMUnRegister, CPMCallback


CPMCallback

This function is called by the critical process monitor to provide an opportunity for the process to clean up and exit smoothly.

Syntax

void CPMCallback ( DWORD dwCommand, DWORD dwCmdInfo );

Parameters

dwCommand
[in] Specifies the command delivered to the critical process. Presently, it is only one flag, CPM_CLEANUP.
dwCmdInfo
[in] Reserved for future use; set to NULL.

Return Values

None.

Remarks

This function is a prototype for the callback function that a critical process should define and then register with the critical process monitor when the process calls CPMRegister.

See Also

CPMRegister


CPMNotify

This function notifies the critical process monitor that the process is still functioning normally.

Syntax

BOOL CPMNotify ( DWORD dwProcessID );

Parameters

dwProcessID
[in] Specifies the process identifier.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

CPMNotify must be called by the process at a rate at least as frequent as the notification interval that was registered with CPMRegister. If the critical process monitor does not receive a notification within the registered time limit, the critical process monitor assumes that the process has encountered a fault condition and takes the appropriate action, according to the monitoring option that the process registered. The only monitoring option currently available is CPM_RELAUNCH.

See Also

CPMRegister


CPMUnRegister

This function unregisters a process with the Critical Process Manager.

Syntax

BOOL CPMUnRegister ( DWORD dwProcessId );

Parameters

dwProcessId
[in] Specifies the process identifier.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

A process that registers with the critical process monitor by calling CPMRegister should call CPMUnRegister when the process is no longer critical to the proper operation of the Auto PC.

See Also

CPMRegister


InitASFormsManager

This function initializes a Forms Manager.

Syntax

HRESULT InitASFormsManager( void );

Return Values

Returns the appropriate HRESULT.

Remarks

Call this function prior to creating any forms or Forms Managers.

See Also

UnInitASFormsManager


UnInitASFormsManager

This function uninitializes a Forms Manager.

Syntax

HRESULT UnInitASFormsManager( void );

Return Values

Returns the appropriate HRESULT.

Remarks

Call this function after objects are released and prior to exiting the application.

See Also

InitASFormsManager


TunerCancelSeek

This function cancels the last seek operation that was initiated by TunerSeekStation.

Syntax

BOOL TunerCancelSeek( HANDLE hTuner );

Parameters

hTuner
[in] Handle to the current tuner, as returned by TunerOpen.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

TunerSeekStation


TunerClose

This function releases a tuner resource.

Syntax

BOOL TunerClose( HANDLE hTuner );

Parameters

hTuner
[in] Handle to the current tuner, as returned by TunerOpen.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

Call this function when the tuner is no longer needed.

See Also

TunerOpen


TunerGetBandInfo

This function returns information in a TUNERBANDINFO structure on the specified bands, such as the type of band, its encoding, its frequency range, and the frequency tuning step between valid stations.

Syntax

DWORD TunerGetBandInfo( DWORD dwDeviceidentifier, DWORD dwBands, PTUNERBANDINFO pBandInfo, DWORD dwBufSize, DWORD *pdwActualOutSize );

Parameters

dwTuner
[in] Specifies the tuner device identifier. The first tuner has an identifier of 1, the second has an identifier of 2, and so on.
dwBands
[in] Specifies the bands for which information is desired. Use a bitwise OR to combine one or more of the following flags:
BAND_AM
Specifies an AM band.
BAND_FM
Specifies an FM band.
BAND_TV
Specifies a TV band.
BAND_CB
Specifies a CB band.
BAND_USER
Specifies a user-defined band.
BAND_WEATHER
Specifies a weather band.
dwBandInfo
[out] Specifies a pointer to an array of TUNERBANDINFO structures to be filled with band information.
dwBufSize
[in] Specifies the size, in bytes, of the buffer pointed to by dwBandInfo. This should be large enough to hold the information for the number of bands requested.
pdwActualOutSize
[out] Pointer to a DWORD that contains the actual number of bytes written to the dwBandInfo buffer.

Return Values

A positive value, which is the number of bands for which information was returned, indicates success. Zero (0) indicates failure.

See Also

TUNERBANDINFO


TunerGetConfig

This function returns the configuration of a tuner.

Syntax

BOOL TunerGetConfig ( HANDLE hTuner, PTUNERCONFIG pTunerConfig );

Parameters

hTuner
[in] Handle to the current tuner, as returned by TunerOpen.
pTunerConfig
[out] Pointer to a TUNERCONFIG structure that contains the tuner configuration.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

When a tuner is opened, the system initializes and configures the device in a default state. To determine this initial configuration, an application calls TunerGetConfig, which fills a TUNERCONFIG structure with the default settings. To modify these settings, change the desired members of the TUNERCONFIG structure and then use the modified structure as a parameter in a TunerSetConfig call.

See Also

TUNERCONFIG, TunerOpen


TunerGetDevCaps

This function gets the device capabilities of a specified tuner.

Syntax

BOOL TunerGetDevCaps( DWORD dwTuner, PTUNERDEVCAPS pTunerDevCaps );

Parameters

dwTuner
[in] Specifies the tuner device identifier. The first tuner has an identifier of 1, the second has an identifier of 2, and so on.
pTunerDevCaps
[out] Pointer to a TUNERDEVCAPS structure that contains information on the device capabilities.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

Use TunerQuery to determine which tuners are available. Use TunerGetDevCaps to find out what each can do.

See Also

TUNERDEVCAPS, TunerQuery


TunerGetSignalInfo

This function retrieves information on the signal of the tuned frequency.

Syntax

BOOL TunerGetSignalInfo( HANDLE hTuner, PSIGNALINFO pSignalInfo );

Parameters

hTuner
[in] Handle to the current tuner, as returned by TunerOpen.
pSignalInfo
[out] Pointer to a SIGNALINFO structure that contains the signal information.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

SIGNALINFO, TunerOpen


TunerOpen

This function returns a handle to a tuner resource.

Syntax

HANDLE TunerOpen( DWORD dwTuneridentifier );

Parameters

dwTuneridentifier
Specifies the tuner identifier. The first tuner has an identifier of 1, the second has an identifier of 2, and so on.

Return Values

A valid tuner handle indicates success. INVALID_HANDLE_VALUE indicates failure.

Remarks

The handle returned by this function is used when calling other tuner functions. When a tuner is opened, the system initializes and configures the device in a default state. To determine this initial configuration, an application calls TunerGetConfig.

See Also

TunerClose , TunerGetConfig


TunerQuery

This function gets the version number and number of available tuner devices..

Syntax

BOOL TunerQuery( DWORD *pdwTunerAPIVer, OUT DWORD *pdwNumDevs );

Parameters

pdwTunerAPIVer
[out] Pointer to a DWORD that contains the version of the tuner API.
pdwNumDevs
[out] Pointer to a DWORD that contains the number of available tuner devices.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

This function must be called before TunerOpen in order to determine what tuners are available. Use TunerGetDevCaps to determine what the capabilities of these tuners are.

See Also

TunerGetDevCaps , TunerOpen


TunerReset

This function resets the tuner to the default driver settings.

Syntax

BOOL TunerReset( HANDLE hTuner );

Parameters

hTuner
[in] Handle to the current tuner, as returned by TunerOpen.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

TunerOpen


TunerSeekStation

This function begins seeking for a frequency with a sufficiently strong signal.

Syntax

BOOL TunerSeekStation( HANDLE hTuner, PTUNERSEEKINFO pTunerSeekInfo );

Parameters

hTuner
[in] Handle to the current tuner, as returned by TunerOpen.
pTunerSeekInfo
[in] Pointer to a TUNERSEEKINFO structure that contains information on the specified frequency search range and direction.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

The fnCallBack member of the TUNERSEEKINFO structure that you pass to this function identifies a callback function. The device driver calls the callback function to inform the application of the frequency that the seek operation has reached, using SIGNALINFO structure as one of the parameters in the callback function. You can use this information about the frequency to update the user interface (UI). Providing a pointer to this function allows the device driver to call the callback function periodically during the seek operation. The frequency at which the device driver calls the callback function depends on the device driver.

The tuner stops the seek operation when the tuner finds a station with a sufficiently strong signal.

See Also

TUNERSEEKINFO, SIGNALINFO


TunerSetConfig

This function sets the tuner configuration.

Syntax

BOOL TunerSetConfig( HANDLE hTuner, PTUNERCONFIG pTunerConfig );

Parameters

hTuner
[in] Handle to the current tuner, as returned by TunerOpen.
pTunerConfig
[in] Pointer to a TUNERCONFIG structure that contains the tuner configuration.

Return Values

TRUE indicates success. FALSE indicates failure.

See Also

TUNERCONFIG, TunerGetConfig


BatteryDrvrGetLevels

This function returns the number of levels the battery driver can return.

Syntax

LONG WINAPI BatteryDrvrGetLevels ( void );

Return Values

This function always returns 0x00020002, indicating two levels for the main battery and two levels for the backup battery.

Remarks

The return value gives the number of levels that the driver is capable of returning in the BatteryFlag and BackupBatteryFlag members of the BATTERY_STATUS structure, as used by the BatteryDrvrGetStatus function.

See Also

BatteryDrvrGetStatus


BatteryDrvrGetStatus

This function returns the status of the main and backup batteries.

Syntax

BOOL BatteryDrvrGetStatus( PBATTERY_STATUS pBatteryStatus );

Parameters

pBatteryStatus
Pointer to the BATTERY_STATUS structure that contains the battery status.

Return Values

TRUE indicates that the function successfully obtained the battery status. FALSE indicates that the function failed to obtain the battery status.

Remarks

The following table shows the values that are presently returned for members of the BATTERY_STATUS structure.

Member
Value
ACLineStatus | AC_LINE_UNKNOWN
BatteryFlag | BATTERY_FLAG_HIGH or BATTERY_FLAG_NO_BATTERY
BatteryLifePercent | BATTERY_PERCENTAGE_UNKNOWN
BatteryLifeTime | BATTERY_LIFE_UNKNOWN
BatteryFullLifeTime | BATTERY_LIFE_UNKNOWN


BatteryDrvrSupportsChangeNotification

This function returns whether the hardware can detect when batteries have been changed.

Syntax

BOOL BatteryDrvrSupportsChangeNotification( void );

Return Values

TRUE indicates that the driver can detect a change of batteries. FALSE indicates it cannot.

Remarks

Currently, this function always returns FALSE.


abClose

This function shuts down the address book.

Syntax

HRESULT abClose ( );

Return Values

NOERROR indicates success. S_FALSE indicates failure.

Remarks

The following code example shows how to use the Address Book API. The abClose function is called at the end of the example to close the address book.

AbOpen(pFrmMgr);
ABDIALOGIN abDl = {
 NULL,
 0,
 NULL,
 ABV_MAINVIEW,
 0
};
abDialog(&abDl);
WORD wNumProp = 2;
CEPROPID cepi[] = {HHPR_GIVEN_NAME, HHPR_SURNAME};
PCEPROPVAL pcepv;
abRead(abDl.ceoid, &wNumProp, cepi, &pcepv);
abClose();

See Also

abDialog, abOpen, abRead


abDialog

This function launches the Address Book view specified in the ABDIALOGINFO structure.

Syntax

HRESULT abDialog ( LPDIALOGINFO lpABInfo );

Parameters

lpABInfo
[in/out] Long pointer to an ABDIALOGINFO structure.

Return Values

One of the values described in the following table is returned.

Return Code
Value
Description
S_NO_PHONE_NUMS | 0x01000001 | Contact has no valid phone numbers.
S_USER_NO_TO_DIAL | 0x01000002 | User answered “No” to the question, “Dial specified phone number?”
S_USER_ABORTED | 0x01000003 | User cancelled the call.
S_PHONE_ABORTED | 0x01000004 | Call was cancelled because of hardware problems.
S_CARD_DELETED | 0x01000005 | User deleted the contact.

Remarks

A user cannot open the address book directly to a specified contact and delete the contact.

The following code example shows how the Address Book main form allows the user to select a contact. After the user selects a contact by pressing ENTER on the contact name on the main form, another form appears that displays all of the phone numbers for the contact. When the user selects one of the phone numbers and presses ENTER, abDialog returns the CEOID that contains the object identifier of the contact the user selected and reads the specified name and surname from the database.

AbOpen(pFrmMgr);
ABDIALOGIN abDl = {
 NULL,
 0,
 NULL,
 ABV_MAINVIEW,
 0
};
abDialog(&abDl);
WORD wNumProp = 2;
CEPROPID cepi[] = {HHPR_GIVEN_NAME, HHPR_SURNAME};
PCEPROPVAL pcepv;
abRead(abDl.ceoid, &wNumProp, cepi, &pcepv);
abClose();

See Also

ABDIALOGINFO, abClose, abOpen, abRead


abOpen

This function initializes the address book.

Syntax

HRESULT abOpen ( IfmManage *pFrmMgr, );

Parameters

pFrmMgr
[in] Pointer to the caller’s forms manager interface.

Return Values

NOERROR indicates success. S_FALSE indicates failure.

Remarks

You should initialize the name and icon of your application with the Forms Manager before calling the Address Book API.

The following code example shows how to use the Address Book API. The abOpen function is used to open the application.

AbOpen(pFrmMgr);
ABDIALOGIN abDl = {
 NULL,
 0,
 NULL,
 ABV_MAINVIEW,
 0
};
abDialog(&abDl);
WORD wNumProp = 2;
CEPROPID cepi[] = {HHPR_GIVEN_NAME, HHPR_SURNAME};
PCEPROPVAL pcepv;
abRead(abDl.ceoid, &wNumProp, cepi, &pcepv);
abClose();

See Also

abClose , abRead , abOpen


abRead

This function reads fields of the current record.

Syntax

HRESULT abRead ( CEOID ceoid, LPWORD lpwNumProp, CEPROPID *rgPropID, PCEPROPVAL *prgCEPropVal );

Parameters

ceoid
[in] Object identifier of the record or NULL for current record.
lpwNumProp
[in/out] Long pointer to the number of fields requested.
rgPropID
[in] Array of HHPR_* property identifiers that indicate the fields to read.

The following database fields are used by the Auto PC:
HHPR_ANNIVERSARY
HHPR_ASSISTANT_NAME
HHPR_ASSISTANT_TELEPHONE_NUMBER
HHPR_BIRTHDAY
HHPR_BUSINESS_FAX_NUMBER
HHPR_CAR_TELEPHONE_NUMBER
HHPR_CATEGORY
HHPR_CHILDREN_NAME
HHPR_COMPANY_NAME
HHPR_DEPARTMENT_NAME
HHPR_EMAIL1_EMAIL_ADDRESS
HHPR_EMAIL2_EMAIL_ADDRESS
HHPR_EMAIL3_EMAIL_ADDRESS
HHPR_GIVEN_NAME
HHPR_HOME_ADDRESS_CITY
HHPR_HOME_ADDRESS_COUNTRY
HHPR_HOME_ADDRESS_POSTAL_CODE
HHPR_HOME_ADDRESS_STATE
HHPR_HOME_ADDRESS_STREET
HHPR_HOME_FAX_NUMBER
HHPR_HOME_TELEPHONE_NUMBER
HHPR_HOME2_TELEPHONE_NUMBER
HHPR_MIDDLE_NAME
HHPR_MOBILE_TELEPHONE_NUMBER
HHPR_OFFICE_ADDRESS_CITY
HHPR_OFFICE_ADDRESS_COUNTRY
HHPR_OFFICE_ADDRESS_POSTAL_CODE
HHPR_OFFICE_ADDRESS_STATE
HHPR_OFFICE_ADDRESS_STREET
HHPR_OFFICE_LOCATION
HHPR_OFFICE_TELEPHONE_NUMBER
HHPR_OFFICE2_TELEPHONE_NUMBER
HHPR_PAGER_NUMBER
HHPR_SPOUSE_NAME
HHPR_SURNAME
HHPR_TITLE
HHPR_WEB_PAGE

prgCEPropVal
[out] Pointer to the PCEPROPVAL structure that receives data.

Return Values

NOERROR indicates success. S_FALSE indicates failure.

Remarks

The following code example shows how to use the Address Book API. The abRead function is used to retrieve the information from the Given Name and Surname fields of a particular record.

AbOpen(pFrmMgr);
ABDIALOGIN abDl = {
 NULL,
 0,
 NULL,
 ABV_MAINVIEW,
 0
};
abDialog(&abDl);
WORD wNumProp = 2;
CEPROPID cepi[] = {HHPR_GIVEN_NAME, HHPR_SURNAME};
PCEPROPVAL pcepv;
abRead(abDl.ceoid, &wNumProp, cepi, &pcepv);
abClose();

See Also

abClose, abOpen


abSeek

This function searches for a record in the Address Book database.

Syntax

HRESULT abSeek ( DWORD dwSeekType, DWORD dwValue, PCEOID pCEOid, LPDWORD lpdwIndex );

Parameters

dwSeekType
Specifies the type of seek operation to perform. It is one of the following flags:
CEDB_SEEK_CEOID
Seek until finding an object that has the object identifier specified in the dwValue parameter. This type of seek operation is very efficient.
CEDB_SEEK_VALUESMALLER
Seek until finding the largest value that is smaller than the specified value. If none of the records has a smaller value, the seek pointer is left at the end of the database and the function returns a zero. The dwValue parameter is a pointer to a CEPROPVAL structure, which contains the specified value.
CEDB_SEEK_VALUEFIRSTEQUAL
Seek until finding the first value that is equal to the specified value. If the seek operation fails, the seek pointer is left at the end of the database, and the function returns a zero. The dwValue parameter is a pointer to a CEPROPVAL structure, which contains the specified value.
CEDB_SEEK_VALUENEXTEQUAL
Starting from the current seek position, seek exactly one position forward in the sorted order and check if the next record is equal to the value specified in the dwValue parameter. If so, return the object identifier of this next record; otherwise, return a zero and leave the seek pointer at the end of the database. This operation can be used in conjunction with the CEDB_SEEK_VALUEFIRSTEQUAL operation to enumerate all records with an equal value.
CEDB_SEEK_VALUEGREATER
Seek until finding a value greater than or equal to the specified value. If all records are smaller, the seek pointer is left at the end of the database and the function returns zero. The dwValue parameter is a pointer to a CEPROPVAL structure, which contains the specified value.
CEDB_SEEK_BEGINNING
Starting from the beginning of the database, seek forward for the number of records specified in the dwValue parameter.
CEDB_SEEK_CURRENT
Seek backward or forward from the current position of the seek pointer for the number of records specified in the dwValue parameter. The function seeks forward if dwValue is a positive value, or backward if the value is negative. A forward seek operation is efficient.
CEDB_SEEK_END
Starting from the end of the database, seek backward for the number of records specified in the dwValue parameter.
dwValue
Specifies the value to use for the seek operation. The value of this parameter depends on the value of dwSeekType.
pCEOid
Pointer to a CEOID that receives the record object identifier.
lpdwIndex
Long pointer to a DWORD that receives the ordinal from the start of the database.

Return Values

NOERROR indicates success. S_FALSE indicates failure.


abWrite

This function writes fields to a new or existing record.

Syntax

HRESULT abWrite ( CEOID *poid, WORD wNumProp, PCEPROPVAL rgCEPropVal );

Parameters

poid
[in] Pointer to the CEOID that contains the object identifier of an existing record to modify, or NULL for a new record.
wNumProp
[in] Unsigned 16-bit value that indicates the number of fields to be written.
rgCEPropVal
[in] Specifies a CEPROPVAL array that contains the data to be written.

Return Values

NOERROR indicates success. S_FALSE indicates failure.


VIOInitialize

This function initializes the vehicle input/output (I/O) API for a process.

Syntax

HRESULT VIOInitialize (LPVOID pvReserved);

Parameters

pvReserved
Reserved; set to NULL.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | API was initialized successfully.
CLASS_E_CLASSNOTAVAILABLE | Vehicle I/O device manager is not registered.
E_ABORT | Startup of the API was aborted.

Remarks

VIOInitialize may be called multiple times by a process. However, if there are no corresponding calls to VIOUninitialize, resources in use by the process may not be freed when the process ends.


VIOUninitialize

This function uninitializes the vehicle input/output (I/O) API for a thread.

Syntax

VOID VIOUninitialize ( );

Return Values

None.

Remarks

A call to VIOUninitialize must be made for each call of VIOInitialize. If you do not call VIOUninitialize for every call to VIOInitialize, resources in use by the process may not be freed when the process ends.


VIORegisterDevice

This function enables support for a vehicle input/output (I/O) device by the vehicle I/O API.

Syntax

HRESULT VIORegisterDevice( REFCLSID rclsid, BOOL bRegister);

Parameters

rclsid
Class identifier of the vehicle I/O device.
bRegister
Boolean that is set to TRUE to register the device, or to FALSE otherwise.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Object is registered or deregistered successfully.
S_FALSE | Object is already registered or deregistered.
E_FAIL | Failed to register or deregister object.
E_OUTOFMEMORY | Application is out of memory.
E_UNEXPECTED | An unexpected error occurred.

Remarks

This function informs the vehicle I/O API of which vehicle I/O CLSIDs are available in a specified vehicle.


VIORegisterMinidriver

This function associates a vehicle input/output (I/O) mini-driver object’s class identifier (CLSID) with the vehicle I/O API device object.

Syntax

HRESULT VIORegisterMinidriver( REFCLSID rclsidDevice, REFCLSID rclsidMinidriver, BOOL bRegister );

Parameters

rclsidDevice
CLSID of the vehicle I/O API device object that the mini-driver is associated with.
rclsidMinidriver
CLSID of the vehicle I/O mini-driver object.
bRegister
Boolean that is set to TRUE to register the mini-driver, or to FALSE to deregister it.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Mini-driver is registered or deregistered successfully.
S_FALSE | Mini-driver is already registered or deregistered.
E_FAIL | Failed to register or deregister mini-driver.
E_OUTOFMEMORY | Application is out of memory.
E_UNEXPECTED | An unexpected error occurred.

Remarks

The vehicle I/O API device objects use mini-driver objects to convert vendor-specific data retrieved from a vehicle I/O device to the format specified for the API device object. This function is used to determine which mini-driver object a specified API device object uses for the conversion.


VIORegisterMinidriverManager

This function enables support for a set of vehicle I/O mini-drivers by the vehicle I/O API.

Syntax

HRESULT VIORegisterMinidriverManager( REFCLSID rclsidManager, BOOL bRegister );

Parameters

rclsidManager
Class identifier (CLSID) of the mini-driver manager object.
bRegister
Boolean that is set to TRUE to register the mini-driver manager, or to FALSE to deregister it.

Return Values

One of the values described in the following table is returned.

Value
Description
S_OK | Object is registered or deregistered successfully.
S_FALSE | Object is already registered or deregistered.
E_FAIL | Failed to register or deregister object.
E_OUTOFMEMORY | Application is out of memory.
E_UNEXPECTED | An unexpected error occurred.

Remarks

The mini-driver manager object is responsible for initializing communication with the vehicle by means of the vehicle I/O device, and any other vehicle I/O mini-driver-specific initializations necessary. The mini-driver manager object is initialized by the vehicle I/O API during VIOInitialize.


AAM_SRCCAP

This structure describes the audio source.

Syntax

typedef struct {
DWORD m_dwID;
DWORD m_dwInfo;
WCHAR[] m_szDevDrv[AAM_SRC_DEVDRV_LEN];
WCHAR[] m_szName[AAM_SRC_NAME_LEN];
DWORD m_dwMisc;
DWORD m_dwReserve1;
DWORD m_dwReserve2;
} AAM_SRCCAP;

Members

m_dwID
Audio source identifier. It is one of the following values:
AAM_SRC_TUNER
Specifies AM/FM tuner 1
AAM_SRC_TUNER2
Specifies AM/FM tuner 2
AAM_SRC_CD
Specifies the compact disc player
AAM_SRC_AUX1
Specifies auxiliary input 1
AAM_SRC_AUX2
Specifies auxiliary input 2
AAM_SRC_CDCHANGER
Specifies the compact disc changer

These seven identifiers are predefined, but OEMs can add identifiers.

m_dwInfo
Current audio source status or other information
m_szDevDrv
Null-terminated string that contains the name of the associated device driver, for example, “DSP1:”
m_szName
Null-terminated string that contains that audio source name or description
m_dwMisc
Reserved for a future extension
m_dwReserve1
Reserved
m_dwReserve2
Reserved

Remarks

An application can get the AAM_GetSourceCap of a particular audio source and check the m_dwinfo member of that structure. If AAM_FLAG_SELECTED is set, then that audio source is active.


OVERLAPPED

This structure contains data used in asynchronous I/O.

Syntax

typedef struct _OVERLAPPED {
DWORD Internal;
DWORD InternalHigh;
DWORD Offset;
DWORD OffsetHigh;
HANDLE hEvent;
} OVERLAPPED;

Members

Internal
Reserved for operating system use
InternalHigh
Reserved for operating system use
Offset
Specifies a file position at which to start the transfer. The file position is a byte offset from the start of the file.
OffsetHigh
Specifies the high word of the byte offset at which to start the transfer. This member is ignored when reading from or writing to named pipes and communications devices.
hEvent
Handle to an event set to the signaled state when the transfer has been completed.

See Also

AAM_AudioIoControl


TUNERDEVCAPS

This structure contains information about the device capabilities of a tuner.

Syntax

typedef struct _TUNERDEVCAPS {
DWORD dwMakerID;
DWORD dwDrvVer;
DWORD dwTunerCaps;
DWORD dwBands;
DWORD dwReserved1;
DWORD dwReserved2;
} TUNERDEVCAPS, *PTUNERDEVCAPS;

Members

dwMakerID
Specifies the manufacturer identifier.
dwDrvVer
Specifies the tuner device driver version. The high-order word contains the major version number, and the low-order word contains the minor version number.
dwTunerCaps
Specifies which tuner features can be configured. It is a combination of the following flags:
TC_MUTE
Specifies muting.
TC_LOCAL
Specifies local mode versus distance mode. If this flag is not specified, then distance mode is implied.
dwBands
Specifies which bands are supported. It is a combination of the following flags:
BAND_AM
Specifies an AM band.
BAND_FM
Specifies an FM band.
BAND_TV
Specifies a TV band.
BAND_CB
Specifies a CB band.
BAND_USER
Specifies a user-defined band.
dwReserved1
Reserved.
dwReserved2
Reserved.

Remarks

Use TunerQuery to determine which tuners are available. Use TunerGetDevCaps to find out what each can do.

See Also

HIWORD, LOWORD, TunerGetDevCaps, TunerQuery


TUNERBANDINFO

This structure contains information on a particular tuner band.

Syntax

typedef struct _TUNERBANDINFO {
DWORD dwBandID;
FREQUENCY RangeLow;
FREQUENCY RangeHigh;
FREQUENCY MinTuningStep;
DWORD dwBandCaps
} TUNERBANDINFO, *PTUNERBANDINFO;

Members

dwBandID
Specifies the band identifier. It is one of the following flags:
BAND_AM
Specifies an AM band.
BAND_FM
Specifies an FM band.
BAND_TV
Specifies a TV band.
BAND_WEATHER
Specifies a weather band.
BAND_CB
Specifies a CB band.
BAND_USER
Specifies a user band. Do not use.
RangeLow
Specifies a FREQUENCY structure that contains the low end of the frequency range.
RangeHigh
Specifies a FREQUENCY structure that contains the high end of the frequency range.
MinTuningStep
Specifies a FREQUENCY structure that contains the minimum tuning step.
dwBandCaps
Specifies the capabilities of a band. It is one or a combination of the following flags.
BC_STEREO
Supports stereo.
BC_RBDS
Specifies RBDS encoded.
BC_TWOWAY
Supports two-way.


FREQUENCY

This structure describes a frequency.

Syntax

typedef struct _FREQUENCY {
DWORD dwFreqValue;
DWORD dwFreqUnit;
} FREQUENCY, *PFREQUENCY;

Members

dwFreqValue
Specifies the frequency value. The units used are specified by dwFreqUnit.
dwFreqUnit
Specifies the frequency units. It is one of the following flags:
FREQ_IN_HZ
Frequency is in units of hertz.
FREQ_IN_KHZ
Frequency is in units of kilohertz.
FREQ_IN_MHZ
Frequency is in units of megahertz.
FREQ_IN_GHZ
Frequency is in units of gigahertz.


TUNERCONFIG

This structure contains information on tuner configuration.

Syntax

typedef struct _TUNERCONFIG {
DWORD dwBand;
FREQUENCY CurrentFreq;
FREQUENCY SeekStep;
FREQUENCY RangeLow;
FREQUENCY RangeHigh;
DWORD dwState;
} TUNERCONFIG, *PTUNERCONFIG;

Members

dwBand
Specifies the current band selection. It is one of the following flags:
BAND_AM
Specifies an AM band.
BAND_FM
Specifies an FM band.
BAND_TV
Specifies a TV band.
BAND_WEATHER
Specifies a weather band.
BAND_CB
Specifies a CB band.
BAND_USER
Specifies a user-defined band.
CurrentFreq
Specifies a FREQUENCY structure that contains the current frequency.
SeekStep
Specifies the step size to be used when seeking stations. For example, the standard American FM band has valid frequencies at 0.2 MHz increments, and the standard American AM band has valid frequencies at 10 KHz increments.
RangeLow
Specifies the high end of the band frequency range.
RangeHigh
Specifies the low end of the band frequency range.
dwState
Specifies the tuner state. It is one or a combination of the following flags:
STEREO_ON
Stereo is on.
LOCAL_ON
Local mode is on, versus distance mode.
MUTE_ON
Tuner muting is on.


SIGNALINFO

This structure carries information about the signal at the chosen frequency.

Syntax

typedef struct _SIGNALINFO {
BOOL fIsStation;
FREQUENCY CurrentFreq;
FIELDSTRENGTH FieldStrength;
DWORD dwMultiPath;
BOOL fStereoPresent;
DWORD dwReserved;
} SIGNALINFO, *PSIGNALINFO;

Members

fIsStation
Boolean that specifies whether the device is tuned to a valid station. TRUE means that it is a valid station.
CurrentFreq
Specifies the frequency of the station to which the radio is currently tuned.
FieldStrength
FieldStrength level information.
dwMultiPath
Specifies the multipath level information.
fStereoPresent
Boolean that specifies whether or not the signal is in stereo. TRUE indicates that the signal is in stereo; FALSE indicates that the signal is in mono.
dwReserved
Reserved DWORD.


FIELDSTRENGTH

This structure contains information on the field strength of a particular tuner and frequency.

Syntax

typedef struct _FIELDSTRENGTH {
unsigned short MaxStrength;
unsigned short CurrentStrength;
} FIELDSTRENGTH, *PFIELDSTRENGTH;

Members

MaxStrength
Specifies the maximum value of the field strength.
CurrentStrength
Specifies the current value of the field strength.


TUNERSEEKINFO

This structure contains information on the frequency range to search.

Syntax

typedef struct _TUNERSEEKINFO {
WORD wSeekOptions;
WORD wSensitivity;
FREQUENCY RangeLow;
FREQUENCY RangeHigh;
SEEK_STATUS_NOTIFY fnCallBack;
DWORD Reserved;
} TUNERSEEKINFO, *PTUNERSEEKINFO;

Members

wSeekOptions
Unsigned 16-bit integer that contains the settings of the tuner while it is in seek mode. It is one of the following values:
TUNER_SEEK_TUNEDOWN
The tuner seeks down the frequency band by repeatedly reducing the current frequency by the step size defined for the band.
TUNER_SEEK_NO_WRAPAROUND
The tuner does not wrap around to the other end of the frequency band once the tuner reaches the minimum frequency defined by RangeLow or the maximum frequency defined by RangeHigh.
TUNER_SEEK_NO_MUTE
Turns off muting while the tuner is in seek mode.
wSensitivity
Seeking sensitivity of tuner. It is one of the following values:
TUNER_SEEK_SENSITIVITY_NORMAL
Seeks normal sensitivity.
TUNER_SEEK_SENSITIVITY_HIGH
Seeks high sensitivity.
TUNER_SEEK_SENSITIVITY_LOW
Seeks low sensitivity.
RangeLow
Specifies the low end of the frequency range to search.
RangeHigh
Specifies the high end of the frequency range to search.
fnCallBack
Callback function with the following syntax:
BOOL SeekCallbackFunc( PSIGNALINFO pSigInfo)
{
……
}

This callback function can update the UI. It returns TRUE if the seek should continue, or FALSE if the seek should stop.

Reserved
Reserved.


BATTERY_STATUS

This structure contains information on the status of the Auto PC batteries.

Syntax

typedef struct tagBATTERY_STATUS{
DWORD ACLineStatus;
DWORD BatteryFlag;
DWORD BatteryLifePercent;
DWORD_t BatteryLifeTime;
DWORD BatteryFullLifeTime;
} PBATTERY_STATUS;

Members

ACLineStatue
Status of the alternating current (AC) power line. Currently, the only value supported is AC_LINE_UNKNOWN.
BatteryFlag
Indicates whether or not a battery is present. It is one of the following values:
BATTERY_FLAG_HIGH
The battery is present.
BATTERY_FLAG_NO_BATTERY
The battery is absent.
BatteryLifePercent
Percentage of full battery charge remaining. This value is equal to the amount of battery life remaining divided by the lifetime of a full battery, expressed as a percentage.. Currently, the only value supported is BATTERY_PERCENTAGE_UNKNOWN.
BatteryLifeTime
Battery life remaining, in seconds.. Currently, the only value supported is BATTERY_LIFE_UNKNOWN.
BatteryFullLifeTime
Lifetime of a full battery, in seconds. Currently, the only value supported is BATTERY_LIFE_UNKNOWN.


SRMODEINFO

This structure provides details about a speech-recognition mode supported by a particular engine.

Syntax

typedef struct { // srmi
GUID gEngineID;
TCHAR szMfgName[SRMI_NAMELEN];
TCHAR szProductName[SRMI_NAMELEN];
GUID gModeID;
TCHAR szModeName[SRMI_NAMELEN];
LANGUAGE language;
DWORD dwSequencing;
DWORD dwMaxWordsVocab;
DWORD dwMaxWordsState;
DWORD dwGrammars;
DWORD dwFeatures;
DWORD dwInterfaces;
DWORD dwEngineFeatures;
} SRMODEINFO, *PSRMODEINFO;

Members

gEngineID
Globally unique identifier (GUID) of the engine. It is possible for more than one mode to have the same engine identifier. In this case, the engine is capable of recognizing the different languages or voices of the modes.
szMfgName
Null-terminates string that contains the name of the manufacturer .
szProductName
Null-terminated string that contains the name of the product.
gModeID
Globally unique identifier (GUID) of the mode. These numbers are guaranteed to be unique, so it is not necessary to monitor and record them. In addition, because the GUID is not stored or used directly by OLE, it is not necessary to load it into the registry.
szModeName
Null-terminated string that contains the name of the recognition mode.
language
Specifies the LANGUAGE structure that contains the name of the language and dialect.
dwSequencing
Specifies the recognition scheme. It is one of the following flags:
SRSEQUENCE_CONTINUOUS
Performs continuous recognition. Given a continuous utterance with no pauses between words, the engine can recognize the words that were spoken.
SRSEQUENCE_DISCRETE
Recognizes discrete utterances. Every word must be isolated by a pause before and after the word for the engine to recognize it.
SRSEQUENCE_WORDSPOT
Performs word spotting, which means that a series of words may be spoken in a continuous utterance, but the engine recognizes only selected words or phrases.
SRSEQUENCE_CONTCFGDISCDICT
Performs continuous recognition for context-free grammars. It also supports discrete dictation.
dwMaxWordsVocab
Specifies the maximum number of words allowed in an active vocabulary at any time.
dwMaxWordsState
Specifies the maximum number of words in any state of a grammar.
dwGrammars
Specifies the types of grammar supported by the engine. It is a combination of the following flags:
SRGRAM_CFG
Specified a context-free grammar.
SRGRAM_DICTATION
Specifies a dictation grammar.
SRGRAM_LIMITEDDOMAIN
Specifies a limited-domain grammar.
dwFeatures
Specifies available features. It is a combination of the following flags:
SRFEATURE_ANYWORD
The engine can attempt to recognize any word.
SRFEATURE_GRAMLINK
The engine supports automatic links between grammars.
SRFEATURE_GRAMLIST
The grammars support recognition lists.
SRFEATURE_GRAMRECURSIVE
The engine accepts recursive, context-free grammars; without this flag, it cannot have recursive grammars.
SRFEATURE_INDEPMICROPHONE
The engine is microphone-independent, meaning that it is indifferent to background noise and microphone, and does not require retraining if the microphone changes.
SRFEATURE_INDEPSPEAKER
The engine is speaker-independent and works well without training.
SRFEATURE_IPAUNICODE
The engine supports the IPA in Unicode.
SRFEATURE_MULTILINGUAL
The engine can recognize speech in several languages at a time. This is necessary for systems that run two or more applications written for different languages.
SRFEATURE_PCOPTIMIZED
The voice is optimized to work over the computer, which provides better sound quality.
SRFEATURE_PHONEOPTIMIZED
The voice is designed to work over the telephone and uses an 8-kilohertz (kHz) sampling rate.
SRFEATURE_TRAINPHONETIC
The speaker can train the engine on a preselected set of words and thereby train all of the phonemes used for recognition. This is done in general training.
SRFEATURE_TRAINWORD
The speaker can train the engine on individual words.
SRFEATURE_WILDCARD
The engine supports wildcards in context-free grammars.
dwInterfaces
Specifies the interfaces that the engine supports. It is a combination of the following flags:
SRI_ILEXPRONOUNCE
Supports the ILexPronounce interface.
SRI_ISRATTRIBUTES
Supports the ISRAttributes interface.
SRI_ISRCENTRAL
Supports the ISRCentral interface.
SRI_ISRDIALOGS
Supports the ISRDialogs interface.
SRI_ISRGRAMCOMMON
Supports the ISRGramCommon interface.
SRI_ISRGRAMCFG
Supports the ISRGramCFG interface.
SRI_ISRGRAMDICTATION
Supports the ISRGramDictation interface.
SRI_ISRGRAMINSERTIONGUI
Supports the ISRGramInsertionGUI interface.
SRI_ISRESBASIC
Supports the ISRResBasic interface.
SRI_ISRESMERGE
Supports the ISRResMerge interface.
SRI_ISRESAUDIO
Supports the ISRResAudio interface.
SRI_ISRESCORRECTION
Supports the ISRResCorrection interface.
SRI_ISRESEVAL
Supports the ISRResEval interface.
SRI_ISRESGRAPH
Supports the ISRResGraph interface.
SRI_ISRESMEMORY
Supports the ISRResMemory interface.
SRI_ISRESMODIFYGUI
Supports the ISRResModifyGUI interface.
SRI_ISRESSPEAKER
Supports the ISRResSpeaker interface.
SRI_ISRSPEAKER
Supports the ISRSpeaker interface.
SRI_ISRESSCORES
Supports the ISRResScore interface.
dwEngineFeatures
Specifies features of a particular engine. These values are defined by the engine author. For more information about engine features, see the documentation for the engine.

In order to identify which engine is being used, an application can use the ITTSEnum interface to enumerate the engines. Its features can then be determined.

Remarks

Although an engine can support both computer optimized and phone optimized voice qualities, most support either one or the other.

Some engines support recognition from several languages at a time. For more information about recognizing multiple languages, see the description of the ISRCentral::GrammarLoad method.


SRMODEINFORANK

This structure ranks the members of the SRMODEINFO structure in the order of importance.

Syntax

typedef struct { // srmir
DWORD dwEngineID;
DWORD dwMfgName;
DWORD dwProductName;
DWORD dwModeID;
DWORD dwModeName;
DWORD dwLanguage;
DWORD dwDialect;
DWORD dwSequencing;
DWORD dwMaxWordsVocab;
DWORD dwMaxWordsState;
DWORD dwGrammars;
DWORD dwFeatures;
DWORD dwInterfaces;
DWORD dwEngineFeatures;
} SRMODEINFORANK, *PSRMODEINFORANK;

Members

dwEngineID
Specifies the relative importance of a matching engine identifier.
dwMfgName
Specifies the relative importance of the specified manufacturer name.
dwProductName
Specifies the relative importance of the specified product name.
dwModeID
Specifies the relative importance of a matching mode identifier.
dwModeName
Specifies the relative importance of the specified mode name.
dwLanguage
Specifies the relative importance of the specified language.
dwDialect
Specifies the relative importance of the specified dialect. This value is stored in the LANGUAGE structure of the SRMODEINFO structure.
dwSequencing
Specifies the relative importance of the specified sequencing type.
dwMaxWordsVocab
Specifies the relative importance of the maximum vocabulary size. Modes that do not meet or exceed the specified value are eliminated from consideration.
dwMaxWordsState
Specifies the relative importance of the maximum number of words in any state of a grammar. Modes that do not meet or exceed the specified value are eliminated from consideration.
dwGrammars
Specifies the relative importance of the requested grammars. Modes that do not support the requested grammars are eliminated from consideration.
dwFeatures
Specifies the relative importance of the requested features. Modes that lack the features requested are eliminated from consideration.
dwInterfaces
Specifies the relative importance of the requested interfaces. Modes that lack the interfaces requested are eliminated from consideration.
dwEngineFeatures
Specifies the relative importance of the requested engine features. Modes that lack the features requested are eliminated from consideration.

Remarks

Each member of the SRMODEINFORANK structure contains a priority value for the corresponding feature. Values are relative to each other — that is, a higher value indicates a higher priority, but the value itself is not meaningful.


SRPHRASE

This structure identifies a unique phrase for a grammar’s vocabulary. A phrase is an ordered collection of words.

Syntax

typedef struct { // srp
DWORD dwSize;
BYTE abWords[0];
} SRPHRASE, *PSRPHRASE;

Members

dwSize
Specifies the size of SRPHRASE plus the size of data for abWords.
abWords
Memory that contains a list of SRWORD structures, in temporal order.


SRRESWORDNODE

This structure provides information about a word node in a recognition/alternative graph generated by a speech-recognition engine.

Syntax

typedef struct { // srrwn
DWORD dwNextWordNode;
DWORD dwUpAlternateWordNode;
DWORD dwDownAlternateWordNode;
DWORD dwPreviousWordNode;
DWORD dwPhonemeNode;
QWORD qwStartTime;
QWORD qwEndTime;
DWORD dwWordScore;
WORD wVolume;
WORD wPitch;
VOICEPARTOFSPEECH pos;
DWORD dwCFGParse;
DWORD dwCue;
} SRRESWORDNODE, *PSRRESWORDNODE;

Members

dwNextWordNode
Specifies the node number of the node that follows next in time. For example, if the current node contains “Mail,” the next node would contain “To.” If the next node has several alternatives, this pointer should continue along the path that produces the highest path score at the final node. If there is nothing left in the path, this can be NULL.
dwUpAlternateWordNode
Specifies the number of an alternative node with a higher score than that of the word in this node. For example, if this node contains “Nail,” the alternative node might contain “Mail.” The alternative nodes should be ordered according to the highest word score. If there are no more alternatives, this can be NULL.
dwDownAlternateWordNode
Specifies the number of an alternative node with a lower score than that of the word in this node. For example, if this node contains “Mail,” the alternative node might contain “Nail.” The alternative nodes should be ordered according to the highest word score. If there are no more alternatives, this can be NULL.
dwPreviousWordNode
Specifies the node number of the previous node. If there are several previous nodes, this maps back along the highest path score at the final node. If there is nothing before this in the path, this can be NULL.
dwPhonemeNode
Specifies the node number of the first phoneme in the word. If an engine does not support phonemes or if such a mapping is inappropriate, this should be NULL.
qwStartTime
Time stamp, in bytes, when the audio for this node started. If the value is indeterminate, this is zero.
qwEndTime
Time stamp, in bytes, when the audio for this node ended. If the value is indeterminate, this is zero.
dwWordScore
Specifies the score for this individual word. It is valid to compare this score only against the scores of this word’s alternatives. Engines should make this value a linear probability if possible. If an engine does not know the value, this is zero.
wVolume
Unsigned 16-bit integer that contains the linear volume level of the word, from 1 to 0xFFFF. If the engine does not know the volume, this should be zero. Applications can use this information to determine emphasis or sentence type — for example, question or command — or to do transplanted prosody.
wPitch
Unsigned 16-bit integer that contains the average pitch of the word in hertz. Engines that do not have information about this value set it to zero. Applications can use this information to determine emphasis or sentence type — for example, question or command — or to do transplanted prosody.
pos
Part of speech of the word, if known, for example, noun, verb, adverb, adjective, or conjunction.
dwCFGParse
Specifies the unique identifier of the rule used to parse the word. This is the rule identifier from the SRCFGRULE structure that defines the rule in the grammar. This member is valid only for context-free grammars.

If an imported rule was used to parse the word, dwCFGParse contains the unique rule identifier from the SRCFGIMPRULE structure that defines the imported rule in the grammar. An application can use this information to determine the semantics of a word and save itself the work of parsing the tree. For example, suppose the context-free grammar contains the following rules:

1 = SEQ(Send mail to 2)

2 = ALT(Mike, Bob, Fred)

If the engine recognizes “Send mail to Bob,” the value of dwCFGParse would be 1 for “Send mail to” and 2 for “Bob.”

dwCue
Specifies a cue that the engine has recognized but cannot translate into a word string. A node with a cue may not have a word associated with it. An engine is not required to return cues so an application should not expect them, although it should take advantage of cues that are returned. This member is one of the following flags:
SRRESCUE_COMMA
A comma should go here.
SRRESCUE_DECLARATIVEBEGIN
A declarative sentence has begun. This cue must be followed by a closing SRRESCUE_DECLARATIVEEND.
SRRESCUE_DECLARATIVEEND
A declarative sentence has ended.
SRRESCUE_IMPERATIVEBEGIN
An imperative sentence has begun. This cue must be followed by a closing SRRESCUE_IMPERATIVEEND.
SRRESCUE_IMPERATIVEEND
An imperative sentence has ended.
SRRESCUE_INTERROGATIVEBEGIN
An interrogative sentence has begun. This cue must be followed by a closing SRRESCUE_INTERROGATIVEEND.
SRRESCUE_INTERROGATIVEEND
An interrogative sentence has ended.
SRRESCUE_NOISE
A noise has occurred.
SRRESCUE_PAUSE
The speaker has paused.
SRRESCUE_SENTENCEBEGIN
A sentence has begun. This cue must be followed by a closing SRRESCUE_SENTENCEEND. If the engine has identified the sentence as interrogative, declarative, or imperative, it should use the more specific SRRESCUE_INTERROGATIVEBEGIN, SRRESCUE_DECLARATIVEBEGIN, or SRRESCUE_IMPERATIVEBEGIN cues.
SRRESCUE_SENTENCEEND
A sentence has ended. If the engine has identified the sentence as interrogative, declarative, or imperative, it should use the more specific SRRESCUE_INTERROGATIVEEND, SRRESCUE_DECLARATIVEEND, or SRRESCUE_IMPERATIVEEND cues.
SRRESCUE_UM
The speaker has said a nonsense sound, such as “Um.”
SRRESCUE_WILDCARD
This is a placeholder for a wildcard word in a context-free grammar.
SRRESCUE_WORD
The node contains a word.


SRWORD

This structure identifies a unique word for a grammar’s vocabulary.

Syntax

typedef struct { // srw
DWORD dwSize;
DWORD dwWordNum;
TCHAR szWord[ ];
} SRWORD, *PSRWORD;

Members

dwSize
Specifies the size of SRWORD plus the size of szWord rounded up to the nearest multiple of 4. The dwSize member must be DWORD-aligned to work on processors that require alignment, such as MIPS® and Alpha APX™.
dwWordNum
Specifies a unique word identifier specific to this grammar. The same string can have a different word identifier in different grammars or in the same grammar if the word participates in the grammar in different ways. For example, the noun “project” and the verb “project” each would have a unique word identifier within the same grammar.

The application always specifies the word identifier when it loads a grammar. The application cannot specify a word identifier of zero because the grammar also uses a word identifier to notify the application when the corresponding word is spoken, and zero is reserved for situations when the word identifier is unknown.

szWord
Null-terminated string of variable size that contains alphabetic characters and intraword punctuation. The NULL is sufficient to indicate the end of the string.

In most European languages, szWord is a string such as “hello” or “car.” The text should not contain pronounced symbols. For example “345” is not a valid word string. The text also should not have ambiguous pronunciation. For example, instead of the string “IEEE,” use three words: “I” “triple” and “E.”

Certain languages, such as Japanese, use two characters: a phonemic set and a symbolic set. The phonemic character set should be passed in szWord. If an application is trying to associate the symbolic representation of the word, it should use dwWordNum to point to the symbolic word.

In some languages, the pronunciation cannot be easily deduced from the symbols that represent the word. For example, the same sequence of Kanji characters can be pronounced differently. In these languages, the phonetic character set appears first, followed by a backslash, followed by the commonly displayed character set. The engine should use the text before the backslash to determine the pronunciation of the word.


TTSMODEINFO

This structure provides detailed information about a text-to-speech (TTS) mode supported by a particular engine.

Syntax

typedef struct { // ttsmi
GUID gEngineID;
TCHAR szMfgName[TTSI_NAMELEN];
TCHAR szProductName[TTSI_NAMELEN];
GUID gModeID;
TCHAR szModeName[TTSI_NAMELEN];
LANGUAGE language;
TCHAR szSpeaker[TTSI_NAMELEN];
TCHAR szStyle[TTSI_STYLELEN];
WORD wGender;
WORD wAge;
DWORD dwFeatures;
DWORD dwInterfaces;
DWORD dwEngineFeatures;
} TTSMODEINFO, *PTTSMODEINFO;

Members

gEngineID
Globally unique identifier (GUID) that identifies the engine. The GUID can be generated randomly using Guidgen.exe, which is provided with the Microsoft OLE Software Development Kit (SDK). It is possible for more than one mode to have the same engine identifier. In this case, the engine is capable of speaking the different languages or voices of the modes.
szMfgName
Null-terminated string that contains the name of the manufacturer .
szProductName
Null-terminated string that contains the name of the product.
gModeID
Globally unique identifier (GUID) of the mode. These numbers are guaranteed to be unique, so it is not necessary to monitor and record them. In addition, the GUID is not stored or used directly by OLE, so it is not necessary to load it into the registry.
szModeName
Null-terminated string that contains the name of the TTS mode.
language
Specifies the LANGUAGE structure that contains the name of the language and dialect.
szSpeaker
Null-terminated string that contains the name of the voice, or NULL if the name is not important.
szStyle
Null-terminated string that indicates the personality of the voice — for example, business, casual, computer, excited, or singsong.
wGender
Specifies the gender of the voice. It is one of the following values:
GENDER_FEMALE
A female voice is used.
GENDER_MALE
A male voice is used.
GENDER_NEUTRAL
The voice used is not perceptibly male or female.
wAge
Specifies the age of the voice. It is one of the following values, with all ages being approximate:
TTSAGE_BABY
The voice is that of a 1-year-old.
TTSAGE_TODDLER
The voice is that of a 3-year-old.
TTSAGE_CHILD
The voice is that of a 6-year-old.
TTSAGE_ADOLESCENT
The voice is that of a 14-year-old.
TTSAGE_ADULT
The voice is that of someone between 20 and 60 years old.
TTSAGE_ELDERLY
The voice is that of someone over 60 years old.
dwFeatures
Specifies the TTS features that are available. It is a combination of the following flags:
TTSFEATURE_ANYWORD
The engine can attempt to read any word.
TTSFEATURE_PCOPTIMIZED
The voice is optimized to work over the computer, which provides better sound quality.
TTSFEATURE_PHONEOPTIMIZED
The voice is designed to work over the telephone and uses an 8-kilohertz (kHz) sampling rate.
TTSFEATURE_PITCH
The engine can adjust the pitch of the voice while the engine is speaking.
TTSFEATURE_SPEED
The engine can adjust the speed of the voice while the engine is speaking.
TTSFEATURE_TAGGED
The engine can interpret tagged text to control the voice.
TTSFEATURE_VISUAL
The engine can provide mouth position information for the voice.
TTSFEATURE_VOLUME
The engine can adjust the volume of the voice.
TTSFEATURE_WORDPOSITION
The engine sends notification of word position.
dwInterfaces
Specifies the interfaces supported by the engine. It is a combination of the following flags:
TTSI_ILEXPRONOUNCE
Use the ILexPronounce interface.
TTSI_ITTSATTRIBUTES
Use the ITTSAttributes interface.
TTSI_ITTSCENTRAL
Use the ITTSCentral interface.
TTSI_ITTSDIALOGS
Use the ITTSDialogs interface.
dwEngineFeatures
Specifies features of a particular engine. These values are defined by the engine author. For more information about engine features, see the documentation for the engine.

In order to identify which engine is being used, an application can use the ITTSEnum interface to enumerate the engines. Its features can then be determined.


TTSMODEINFORANK

This structure ranks the members of the TTSMODEINFO structure in order of importance.

Syntax

typedef struct { // ttsmir
DWORD dwEngineID;
DWORD dwMfgName;
DWORD dwProductName;
DWORD dwModeID;
DWORD dwModeName;
DWORD dwLanguage;
DWORD dwDialect;
DWORD dwSpeaker;
DWORD dwStyle;
DWORD dwGender;
DWORD dwAge;
DWORD dwFeatures;
DWORD dwInterfaces;
DWORD dwEngineFeatures;
} TTSMODEINFORANK, *PTTSMODEINFORANK;

Members

dwEngineID
Specifies the relative importance of a matching engine identifier.
dwMfgName
Specifies the relative importance of the specified manufacturer name.
dwProductName
Specifies the relative importance of the specified product name.
dwModeID
Specifies the relative importance of a matching mode identifier.
dwModeName
Specifies the relative importance of the specified mode name.
dwLanguage
Specifies the relative importance of the specified language.
dwDialect
Specifies the relative importance of the specified dialect. This value is stored in the LANGUAGE structure of TTSMODEINFO.
dwSpeaker
Specifies the relative importance of the requested speaker.
dwStyle
Specifies the relative importance of the requested speaking style.
dwGender
Specifies the relative importance of the requested gender.
dwAge
Specifies the relative importance of the requested age. The text-to-speech (TTS) mode that is closest to the requested age is selected.
dwFeatures
Specifies the relative importance of the requested features. Modes that lack the features requested are eliminated from consideration.
dwInterfaces
Specifies the relative importance of the requested interfaces. Modes that lack the interfaces requested are eliminated from consideration.
dwEngineFeatures
Specifies the relative importance of the requested engine features. Modes that lack the features requested are eliminated from consideration.

Remarks

Each member of the TTSMODEINFORANK structure contains a priority value for the corresponding feature. Values are relative to each other — that is, a higher value indicates a higher priority, but the value itself is not meaningful.


VCMDCOMMAND

This structure provides information about a command in a voice menu.

Syntax

typedef struct { // vccmd
DWORD dwSize;
DWORD dwFlags;
DWORD dwID;
DWORD dwCommand;
DWORD dwDescription;
DWORD dwCategory;
DWORD dwCommandText;
DWORD dwAction;
DWORD dwActionSize;
BYTE abData[];
} VCMDCOMMAND, *PVCMDCOMMAND;

Members

dwSize
Specifies the size, in bytes, of the VCMDCOMMAND structure, including the amount allocated for abData. The contents of abData must be DWORD-aligned, so round dwSize up to the nearest whole DWORD.
dwFlags
Specifies the information about the command. It is a combination of the following flags:
VCMDCMD_DISABLED_PERM
The command was disabled by using the IVCmdMenu::EnableItem method so that the voice commands cannot be recognized. The command is not compiled into the voice menu.
VCMDCMD_DISABLED_TEMP
The command was disabled by using the IVCmdMenu::SetItem method. The command is still compiled into the voice menu, so it can be re-enabled without recompilation of the menu.
VCMDCMD_VERIFY
This flag is not supported in Microsoft Windows CE for the Auto PC version 1.0.
VCMDCMD_CANTRENAME
This flag is not supported in Windows CE for the Auto PC version 1.0.
dwID
Specifies the command identifier. This member can be used to identify a command to modify, or it can be used for notifications.
dwCommand
Specifies the offset from the beginning of this structure to first character of the voice command string, which is Unicode.

Within the command string, the following characters have special meaning:

< >
Indicates the name of a list of words or phrases that can be spoken at this point in the command. For example, the command string “Send mail to <name>“ contains a list called “name.” To add phrases to the list, use the IVCmdMenu::ListSet method.
{ }
Reserved for future use.
[ ]
Reserved for future use.
dwDescription
Specifies the offset from the beginning of the structure to first character of a string that describes the action performed by the command.
dwCategory
Specifies the offset from the beginning of the structure to the first character of a string that indicates the category to which the command belongs.

Commands in a voice menu should be organized in different categories to help the user browse through lists of commands more easily. This is similar in concept to Windows menus, which organize commands under menu names such as File, Edit, View, and so on. For best results, you should use 20 or fewer categories.

dwCommandText
Specifies the offset from the beginning of the structure to the first character of the command text, which is the string that is displayed to the user when he or she requests a list of available voice commands. If this member is NULL, an application uses the text pointed to by dwCommand, which is the voice command string used in the application’s user interface.

Most applications written for European languages set this member to NULL, because the language uses only one character set. Applications written for languages that have both a phonemic and symbolic character set, such as Japanese, store the phonemic representation of the command in dwCommand and the symbolic representation—which is preferred by the user—in dwCommandText.

dwAction
Specifies the offset from the beginning of the structure to the first byte of a block of data that is sent to the application when the command is spoken.

Data passed with a command is not interpreted by voice commands; it is up to the application to determine whether the data is valid and to act upon it. Always check the validity of the data, because it is susceptible to being changed—accidentally or intentionally—by other applications, just as other applications can change an .ini file or registry file.

dwActionSize
Specifies the number of bytes required to store the block of data indicated by dwAction.
abData
Array of BYTE types that contains the command string, its description, its category, and any additional data to pass to the application along with the command. Because all of the items in abData are DWORD-aligned, the size of abData should be a multiple of 4. All strings should be null-terminated.

Remarks

Because the items indicated by offsets into abData are DWORD-aligned, the offsets specified by dwCommand, dwDescription, dwCategory, dwAction, and dwActionSize should be multiples of 4.


VCMDNAME

This structure contains strings that uniquely identify the application and state to which a voice menu belongs.

Syntax

typedef struct { // vcn
TCHAR szApplication[VCMD_APPLEN];
TCHAR szState[VCMD_STATELEN];
} VCMDNAME, *PVCMDNAME;

Members

szApplication
Null-terminated string that contains the name of the application—for example, “AM/FM Radio.” The application name must be unique among all applications registered to use voice commands on the user’s computer.
szState
Null-terminated string that contains the unique name of the application state in which the voice command set is valid. An application state usually corresponds to an active window or dialog box .


VCSITEINFO

This structure provides information about the audio device, speech-recognition mode, and other attributes of a voice command site.

Syntax

typedef struct { // vcsi
DWORD dwAutoGainEnable;
DWORD dwAwakeState;
DWORD dwThreshold;
DWORD dwDevice;
DWORD dwEnable;
TCHAR szMicrophone[VCMD_MICLEN];
TCHAR szSpeaker[VCMD_SPEAKERLEN];
GUID gModeID;
} VCSITEINFO, *PVCSITEINFO

Members

dwAutoGainEnable
Specifies a value from 0 to 100 that indicates the state of the automatic gain for the incoming audio stream to be used by the site.
dwAwakeState
Specifies the state of speech recognition. TRUE indicates that the site is awake for purposes of speech-recognition; FALSE indicates that the site is asleep.
dwThreshold
Specifies a value from 0 to 100 that indicates the recognition threshold for the speech-recognition engine to be used by the site.
dwDevice
Specifies the device identifier of the wave-in audio device to be used by the site. The device identifier can be obtained by calling the waveInGetNumDevs and waveInGetDevCaps multimedia functions.
dwEnable
Specifies whether or not speech recognition is enabled. TRUE indicates that speech recognition is enabled for the site; FALSE indicates that speech recognition is disabled.
szMicrophone
Null-terminated string that contains the name of the current microphone for the audio source to be used by the site.
szSpeaker
Null-terminated string that contains the name of the current speaker for the site.
gModeID
Globally unique identifier (GUID) for the speech-recognition mode to be used by the site. The GUID for a speech-recognition mode can be obtained by using a speech-recognition enumerator.

Remarks

An application can pass a pointer to a VCSITEINFO structure with the IVoiceCmd::Register method to set the audio device, speech-recognition mode, and other attributes of a voice-command site, even if the site is already open.


VTSITEINFO

This structure specifies an audio device, a text-to-speech (TTS) mode, and the talking speed for a voice text site, and indicates whether voice text is enabled or disabled for the voice text site.

Syntax

typedef struct { // vtsi
DWORD dwDevice;
DWORD dwEnable;
DWORD dwSpeed;
GUID gModeID;
} VTSITEINFO, *PVTSITEINFO;

Members

dwDevice
Specifies the device identifier of the WAV output audio device to be used by the site. The device identifier can be obtained by calling the waveOutGetNumDevs and waveOutGetDevCaps multimedia functions.
dwEnable
Specifies whether voice text is enabled. TRUE indicates that voice text is enabled for the site; FALSE indicates it is disabled.
dwSpeed
Specifies a baseline average talking speed, in words per minute, for the text-to-speech mode to be used by the site.
gModeID
Globally unique identifier (GUID) of the text-to-speech mode to be used by the site. The GUID for a text-to-speech mode is obtained from a text-to-speech enumerator object.

Remarks

An application can specify the address of a VTSITEINFO structure in a call to the IVoiceText::Register method to set the voice, speaking speed, and other attributes of a voice-text site, even if the site is already open. Telephony applications typically do this to ensure that the proper information is selected for the site.


ABDIALOGINFO

This structure contains information used by the Address Book API.

Syntax

typedef struct {
CEOID ceoid;
DWORD dwEnabled;
DWORD dwParam;
WORD wInitView;
WORD wFieldOrd;
WORD wCard;
BSTR bstrHelpIndexFile;
BSTR bstrHelpTopicFile;
BSTR bstrMainFormCaption;
BSTR bstrCardFormCaption;
BSTR bstrParam1;
BSTR bstrParam2;
IVerifyContactSink *pVerifyListSink;
IVerifyContactSink *pVerifySelectionSink;
} ABDIALOGINFO, *LPDIALOGINFO;

Members

ceoid
Contact object identifier. This member is read/write.
dwEnabled
Specifies which features are enabled. This read member is one or a combination of the following flags:
Flag
Value
Description
ABE_BACK | 0x0001 | Allows the user to return to the main view after changing to another view.
ABE_CARDPHONE | 0x0002 | Enables the card view for the phone tab.
ABE_CARDHOME | 0x0004 | Enables the card view for the home tab.
ABE_CARDWORK | 0x0008 | Enables the card view for the work tab.
ABE_CARDNOTES | 0x0010 | Enables the card view for the notes tab.
ABE_DELETE | 0x0020 | Notifies the Address Book that the user is allowed to delete cards.
ABE_DIAL | 0x0040 | Notifies the Address Book that the user is allowed to dial phone numbers from a card.
ABE_EDIT | 0x0080 | Notifies the Address Book that the user is allowed to edit, or create new cards.
ABE_EXITMAIN | 0x4000 | Notifies the Address Book that the user is allowed to exit the main form.
ABE_NEW | 0x0100 | Notifies the Address Book that the user is allowed to add cards.
ABE_OPTIONMENU | 0x1000 | Enables the Address Book option menu.
ABE_PRESERVEAPPFOCUS | 0x200000 | Forces the Address Book API to leave the application in the foreground and to exit the address book when the login fails.
ABE_RECEIVE | 0x0200 | Notifies the Address Book that the user is allowed to receive contact information via the infrared port.
ABE_SENDONE | 0x0400 | Notifies the Address Book that the user is allowed to send contact information via the infrared port.
ABE_SENDALL | 0x0800 | Notifies the Address Book that the user is allowed to send all contact information via the infrared port.
ABE_VOICEMENU | 0x2000 | Allows the user to interact with the Address Book through speech.
ABE_TTS | 0x8000 | Makes the user interface (UI) behave as if it were invoked with speech commands instead of the keyboard.
ABE_ALL | 0x0fff | Combination flag that enables all address book functions.
ABE_CARDALL | 0x001e | Combination flag that enables the card view for phone, home, work, and notes tabs.
ABE_EDITALL | 0x01a0 | Combination flag that allows the user to delete, edit, or create new cards.
ABE_IRALL | 0x0e00 | Combination flag that allows the user to receive, send one, or send all messages.

dwParam
Specifies a DWORD that indicates the user's actions while in the card view. It is one of the flags shown in the following table. This member must be zero if unused.
Flag
Value
Description
ABN_RECORDS_ADDED | 0x0001 | The user has added records since the Address Book API started.
ABN_RECORDS_DELETED | 0x0002 | The user has deleted records since the Address Book API started.
ABN_EXIT_USING_VOICE | 0x0004 | The user exited the Address Book API by using speech commands.
ABN_RESORT_DB | 0x0008 | The user changed database fields, affecting the sort sequence.

wInitView
Unsigned 16-bit character that indicates the initial or final view. This member is one of the following values:
Flag
Value
Description
ABV_MAINVIEW | 1 | Displays main contacts list with tabber index. Focus is set to ceoid.
ABV_LOCATE | 2 | Displays same screen as ABV_MAINVIEW unless the user has already said, “Locate.”
ABV_CARDPHONE | 3 | Displays card view at the phone tab.
ABV_CARDHOME | 4 | Displays card view at the home information tab.
ABV_CARDWORK | 5 | Displays card view at the work information tab.
ABV_CARDNOTES | 6 | Displays card view at the notes tab. This value is not currently implemented.
ABV_DIAL | 7 | Displays screen asking the user, “Dial preferred number?” If the user replies, “No,” then ABV_CARDPHONE is shown on the Auto PC display.
ABV_RECEIVE | 8 | Displays the infrared Receive form. The Auto PC is waiting for an infrared connection.
ABV_SEND | 9 | Displays the infrared Send form. The Auto PC attempts to send dwParam contacts starting at ceoid by means of infrared.

wFieldOrd
Unsigned 16-bit integer that indicates the field ordinal. This member is read/write.
wCard
Unsigned 16-bit character that indicates the default or final view. This member uses the same flags listed for the wInitView member.
bstrHelpIndexFile
Unicode string that contains the name of the Help index file. If this string or the topic is NULL, use Address Book Help.
bstrHelpTopicFile
Unicode string that contains the name of the initial Help topic file. If NULL, start at index.
bstrMainFormCaption
Unicode string that contains the main form caption to use if ABV_MAINVIEW is shown.
bstrCardFormCaption
Unicode string that contains the card form caption use if ABV_CARD* is shown.
bstrParam1
Unicode string that contains the name of the contact shown in the Dial dialog box.
bstrParam2
Unicode string that contains the location of the contact shown in the Dial dialog box.
pVerifyListSink
Reserved for future use.
pVerifySelectionSink
Pointer to a sink. If specified, this sink is called when the user makes a selection to determine if selection should be accepted.

See Also

IVerifyContactSink


APCCPLINFO

This structure provides information about a control panel application.

Syntax

typedef struct {
DWORD dwSize;
WCHAR szTTSName[32];
WCHAR szAlertName[32]
} APCCPLINFO;

Members

dwSize
DWORD that specifies the size of the structure. The control panel application must set this value.
szTTSName
Null-terminated string that contains the text-to-speech name of the control panel application. The string must contain 32 characters or less.
szAlertName
Null-terminated string that contains the alert name of the control panel application. The string must contain 32 characters or less.


LOGENTRYINFO

This structure contains information about events whose entries have been logged.

Syntax

typedef struct _LOGENTRYINFO {
DWORD LogEntry;
DWORD dwSequenceId;
FILETIME EntryTime;
DWORD dwEventClass;
BOOL bFinalEntryData;
} LOGENTRYINFO, *PLOGENTRYINFO;

Members

LogEntry
Control word used by log reading to maintain position information.
dwSequenceId
Specifies the sequence identifier.
EntryTime
Time entry was logged.
dwEventClass
Specifies subsystem and event class information.
bFinalEntryData
Boolean that is set to TRUE if there is more data to be entered, or to FALSE if none exists.


VIODEVICEMETRICS

This structure provides details about a vehicle input/output (I/O) device.

Syntax

typedef struct {
CLSID clsidDevice;
TCHAR szDeviceName[VIODEVICENAMESIZE];
DWORD grfModes;
VARIANT vRangeLow;
VARIANT vRangeHigh;
DWORD dwValueType;
DWORD dwValueUnits;
LONG lExponent;
}

Members

clsidDevice
Class identifier (CLSID) of this particular device.
szDeviceName
Null-terminated string that contains the name of the device.
grfModes
Group of flags reflecting a device’s possible access modes. It is one of the values shown in the following table.
Access mode
Value
VIODEVICEMODE_READ | 0x0001
VIODEVICEMODE_WRITE | 0x0002

vRangeLow
Lower bound of the data value. For specific values, see “CLSIDs for the Auto PC.” For example, CLSID_VIO_VEHICLE_SPEED component’s low value is 0.
vRangeHigh
Upper bound of the data value. For specific values, see “CLSIDs for the Auto PC.” For example, the CLSID_VIO_VEHICLE_SPEED component’s high value is 383.
dwValueType
Specifies the type of data value, such as distance, current, and voltage. It is one of the following flags:
Data value type
Value
VIOMEASUREMENT_STATE | 0
VIOMEASUREMENT_ONOFF | 1
VIOMEASUREMENT_PERCENTAGE | 2
VIOMEASUREMENT_ROTATIONALSPEED | 3
VIOMEASUREMENT_SPEED | 4
VIOMEASUREMENT_TEMPERATURE | 5
VIOMEASUREMENT_GAGEPESSURE | 6
VIOMEASUREMENT_ROTATION | 7
VIOMEASUREMENT_VOLTAGE | 8
VIOMEASUREMENT_ABSOLUTEPRESSURE | 9
VIOMEASUREMENT_FLOWRATE | 10
VIOMEASUREMENT_DISCRETEMASK | 11
VIOMEASUREMENT_DISTANCE | 12
VIOMEASUREMENT_COLLECTION | 13

dwValueUnits
Specifies the units in which data value is expressed, such as kilometers, volts, degrees. It is one of the following flags:
Units
Value
VIOUNITS_ENUM | 0
VIOUNITS_BINARY | 1
VIOUNITS_PERCENT | 2
VIOUNITS_RPM | 3
VIOUNITS_KILOMETERSPERHOUR | 4
VIOUNITS_CELSIUS | 5
VIOUNITS_KILOPASCALSGAGE | 6
VIOUNITS_DEGREES | 7
VIOUNITS_VOLTS | 8
VIOUNITS_KILOPASCALSABSOLUTE | 9
VIOUNITS_GRAMSPERSECOND | 10
VIOUNITS_BITMASK | 11
VIOUNITS_KILOMETERS | 12
VIOUNITS_DIAGNOSTICITEMS | 13

lExponent
Long integer that contains the exponent used to determine number of digits to the right of the decimal place.


VIODIAGNOSTICITEMSARRAY

This structure provides the data about diagnostic codes from the mini-driver.

Syntax

typedef struct {
DWORD cDiagnosticInfo;
DWORD cbDiagnosticInfo;
VIODIAGNOSTICINFO vdiItems[1];
}

Members

cDiagnosticInfo
Number of diagnostic items being returned.
cbDiagnosticInfo
Number of bytes of the diagnostic information being returned.
vdiItems
First VIODIAGNOSTICINFO structure that contains information about a diagnostic code.


VIODIAGNOSTICINFO

This structure provides the data about a single code retrieved from the vehicle.

Syntax

typedef struct {
DWORD cbFixed;
DWORD cExtraFields;
DWORD dwSystem;
DWORD dwSubsystem;
VIODIAGNOSTICFIELD vdiFields[1];
}

Members

cbFixed
Size, in bytes, of the fixed diagnostic members in the structure.
cExtraFields
Number of extra members provided for this diagnostic item.
dwSystem
Specifies the identifier of the system providing this diagnostic code. It is one of values shown in the following table.
Data value type
Value
VIOTC_SYS_UNKNOWN | 0
VIOTC_SYS_POWERTRAIN | 1
VIOTC_SYS_BODY | 2
VIOTC_SYS_CHASSIS | 3
VIOTC_SYS_NETWORK | 4

dwSubsystem
Specifies the identifier of the subsystem providing this diagnostic code. It is one of the values shown in the following table.
Data value type
Value
VIOTC_SUBSYS_UNKNOWN | 0
VIOTC_FUEL_AIR_METERING | 1
VIOTC_IGNITION_SYSTEM_OR_MISFIRE | 2
VIOTC_AUX_EMISSION_CONTROL | 3
VIOTC_VEHSPEED_IDLE_AUXINPUTS | 4
VIOTC_COMPUTER_AUX_OUTPUTS | 5
VIOTC_TRANSMISSION | 6
VIOTC_ANTILOCK_BRAKES | 32
VIOTC_TRACTION_CONTROL | 33
VIOTC_STEERING | 34
VIOTC_SUSPENSION | 35
VIOTC_SUPPLEMENTAL_RESTRAINTS | 64
VIOTC_CLIMATE_CONTROL | 65
VIOTC_INSTRUMENT_PANEL | 66
VIOTC_MEMORY_SEATS_MIRROR | 67
VIOTC_LIGHTING_CONTROL | 68
VIOTC_ANTI_THEFT | 69
VIOTC_TRIP_COMPUTER | 70
VIOTC_SUBSYSTEM_OTHER | 255

vdiFields
First VIODIAGNOSTICFIELD structure that contains extra attributes about the diagnostic code.


VIODIAGNOSTICFIELD

This structure provides an extra attribute about a diagnostic code.

Syntax

typedef struct {
DWORD cbFixed;
DWORD cbData;
DWORD vdfID;
VARTYPE vdfType;
BYTE vdfData[1];
}

Members

cbFixed
Size, in bytes, of the fixed diagnostic members in the structure.
cbData
Number of bytes in the vdfData member for this diagnostic item attribute.
vdfID
Specifies the identifier of the attribute returned from IVIO_EnumDiagnosticEntry interface. It is one of the values shown in the following table.
Data value type
Value
VIODIAGENTRY_SYSTEM | 0
VIODIAGENTRY_SUBSYSTEM | 1
VIODIAGENTRY_SAE_CODE | 2
VIODIAGENTRY_LAMP_FLAG | 3

vdfType
Type of data represented in the vdfData member.
vdfData
First byte of data for the diagnostic item attribute. Number of bytes in the array set in the cbData member.


PNACCURACY

This structure stores accuracy details about the position supplied by the Positioning and Navigation device and the time these details were last updated.

Syntax

typedef struct tagPNACCURACY{
DWORD dwStructureSize;
PNTIME tiTime;
PNDouble dHorizError;
PNDouble dVerticalError;
PNDouble dEDOP;
PNDouble dNDOP;
PNDouble dVDOP;
PNDouble dPDOP;
PNDouble dTDOP;
PNDouble dGDOP;
PNAVACCURACY acAvAccuracy;
DWORD dwPNReserved;
} PNACCURACY;

Members

dwStructureSize
Specifies the size, in bytes, of the PNACCURACY structure
TiTime
Specifies the time data was received
dHorizError
Unsupported
dVerticalError
Unsupported
dEDOP
Stores the east component of the geometric dilution of precision
dNDOP
Stores the north component of the geometric dilution of precision
dVDOP
Stores the vertical component of the geometric dilution of precision
dPDOP
Stores the position component of the geometric dilution of precision
dTDOP
Stores the time component of the geometric dilution of precision
dGDOP
Stores the geometric dilution of precision
acAvAccuracy
Stores which elements of acAvAccuracy of are valid and which are not
dwPNReserved
Reserved for future use


PNALMANAC

This structure stores Global Positioning System (GPS) almanac details.

Syntax

typedef struct tagPNALMANAC{
DWORD dwStructureSize;
PNTIME tiTime;
PNSATELLITE saSatellite[PN_NUM_SATS_c];
DWORD dwPNReserved;
} PNALMANAC;

Members

dwStructureSize
Specifies the size, in bytes, of the PNALMANAC structure
tiTime
Specifies the time data was collected by the GPS device
saSatellite
Specifies the satellite information that the GPS returns as a PNSATELLITE structure
dwPNReserved
Reserved for future use

Remarks

The index number for each PNSATELLITE structure is the pseudo-random noise (PRN) signal number or space vehicle identification (SVID) number of the satellite in question. However, as the index number goes from 0 through 31, the index number is one less than the PRN or SVID number.

The tiTime member stores the time almanac data was collected. To be precise, it is the time that the first piece of almanac information from a GPS satellite was received.


PNAVACCURACY

This structure indicates valid and invalid PNACCURACY elements.

Syntax

typedef struct tagPNAVACCURACY{
DWORD dwStructureSize;
DWORD dwAv1;
DWORD dwPNReserved;
} PNAVACCURACY;

Members

dwStructureSize
Specifies the size, in bytes, of the PNACACCURACY structure.
dwAv1
Specifies bit flags, one for each member in the corresponding PNACCURACY structure, that indicate whether an element is available. The bit flags defined for the PNAVACCURACY structure are described in the following table.
Flag
Bit
Description
PN_AAC_AHORIZERROR | 0 | Unsupported
PN_AAC_AVERTICALERROR | 1 | Unsupported
PN_AAC_EDOP | 2 | East component of the geometric dilution of precision (EDOP) is valid or invalid.
PN_AAC_NDOP | 3 | North component of the geometric dilution of precision (NDOP) is valid or invalid.
PN_AAC_VDOP | 4 | Vertical component of the geometric dilution of precision (VDOP) is valid or invalid.
PN_AAC_PDOP | 5 | Position component of the geometric dilution of precision (PDOP) is valid or invalid.
PN_AAC_TDOP | 6 | Time component of the geometric dilution of precision (TDOP) is valid or invalid.
PN_AAC_GDOP | 7 | Geometric dilution of precision (GDOP) is valid or invalid.
Reserved for future use | 8-31

dwPNReserved
Reserved for future use


PNAVDEVSTATE

This structure indicates valid and invalid DEVSTATE elements.

Syntax

typedef struct tagPNAVDEVSTATE{
DWORD dwStructureSize;
DWORD dwAv1;
DWORD wPNReserved;
} PNAVDEVSTATE;

Members

dwStructureSize
Specifies the size, in bytes, of the PNAVDEVSTATE structure.
dwAv1
Specifies bit flags, one for each element in the corresponding PNDEVSTATE structure, that indicate if an element is available. The bit flags defined for the PNAVDEVSTATE structure are described in the following table.
Flag
Bit
Description
PN_ADS_STATE | 0 | Device state is valid or invalid
Reserved for future use | 1-31

dwPNReserved
Reserved for future use


PNAVINDSTATION

This structure indicates valid and invalid PNINDSTATION.

Syntax

typedef struct tagPNAVINDSTATION{
DWORD dwStructureSize;
DWORD dwAv1;
DWORD dwPNReserved;
} PNAVINDSTATION;

Members

dwStructureSize
Specifies the size, in bytes, of the PNAVINDSTATION structure
dwAv1
Specifies bit flags, one for each element in the corresponding PNINDSTATION structure, that indicate if an element is available. The bit flags defined for the PNAVINDSTATION structure are described in the following table.
Flag
Bit
Description
PN_ASI_STATE | 0 | Station state is valid or invalid.
PN_ASI_STATIONIDNUM | 1 | Station identification number is valid or invalid.
PN_ASI_USED | 2 | The fUsed member is valid or invalid.
PN_ASI_ELEVATION | 3 | Satellite elevation is valid or invalid.
PN_ASI_SATAZIMUTH | 4 | Satellite azimuth is valid or invalid.
PN_ASI_SIGNALSTRENGTH | 5 | Signal strength is valid or invalid.
PN_ASI_COVERAGE | 6 | Unsupported
Reserved for future use | 7-31

dwPNReserved
Reserved for future use


PNAVPOSLLA

This structure indicates which of the position elements are valid. It is intended to mirror the PNPOSLLA structure.

Syntax

typedef struct tagPNAVPOSLLA{
DWORD dwStructureSize;
DWORD dwAv1;
DWORD dwPNReserved;
} PNAVPOSLLA;

Members

dwStructureSize
Specifies the size, in bytes, of the PNAVPOSLLA structure
dwAv1
Specifies bit flags, one for each element in the corresponding PNPOSLLA structure, that indicate if an element is available. The bit flags defined for the PNAVPOSLLA structure are described in the following table.
Flag
Bit
Description
PN_APL_LONG | 0 | Longitude is valid or invalid.
PN_APL_LAT | 1 | Latitude is valid or invalid.
PN_APL_ALT | 2 | Altitude is valid or invalid.
PN_APL_RADIANS | 3 | The fRadians member is valid or invalid.
Reserved for future use | 4-31

dwPNReserved
Reserved for future use


PNAVSATELLITE

This structure indicates valid and invalid PNSATELLITE elements.

Syntax

typedef struct tagPNAVSATELLITE{
DWORD dwStructureSize;
DWORD dwAv1;
DWORD dwPNReserved;
} PNAVSATELLITE;

Members

dwStructureSize
Specifies the size, in bytes, of the PNAVSATELLITE structure
dwAv1
Specifies bit flags, one for each element in the corresponding PNSATELLITE structure, that indicates if an element is available. The bit flags defined for the PNAVSATELLITE structure are described in the following table.
Flag
Bit
Description
PN_ASA_SETDATA | 0 | Unsupported
PN_ASA_PRN | 1 | Pseudo-random noise (PRN) signal number is valid or invalid.
PN_ASA_SATHEALTH | 2 | Satellite health is valid or invalid.
PN_ASA_REFWEEKNUMBER | 3 | Reference week number is valid or invalid.
PN_ASA_REFTIMEOFWEEK | 4 | Reference time of week is valid or invalid.
PN_ASA_ECCENTRICITY | 5 | Eccentricity is valid or invalid.
PN_ASA_ROOTSEMIMAJORAXIS | 6 | Square root of the semi-major axis is valid or invalid.
PN_ASA_ARGUMENTOFPERIGEE | 7 | Argument of perigee is valid or invalid.
PN_ASA_MEANANOMALYATREFTIME | 8 | Mean anomaly at reference time is valid or invalid.
PN_ASA_RIGHTASCENSIONATREFTIME | 9 | Right ascension at reference time is valid or invalid.
PN_ASA_RATERIGHTASCENSION | 10 | Rate of right ascension is valid or invalid.
PN_ASA_CORRECTTOINCLINATION | 11 | Correction to inclination is valid or invalid.
PN_ASA_AF0CLOCKCORRECT | 12 | Zeroth order clock correction is valid or invalid.
PN_ASA_AF1CLOCKCORRECT | 13 | First order clock correction is valid or invalid.
Reserved for future use | 14-31

dwPNReserved
Reserved for future use


PNAVSETTINGS

This structure indicates valid and invalid PNSETTINGS elements.

Syntax

typedef struct tagPNAVSETTINGS{
DWORD dwStructureSize;
DWORD dwAv1;
DWORD dwPNReserved;
} PNAVSETTINGS;

Members

dwStructureSize
Specifies the size, in bytes, of the PNAVSETTINGS structure
dwAv1
Specifies bit flags, one for each element in the corresponding PNSETTINGS structure, that indicate if an element is available. The bit flags defined for the PNAVSETTINGS structure are described in the following table.
Flag
Bit
Description
PN_ASE_MODE | 0 | Unsupported
PN_ASE_DGPSENABLE | 1 | Unsupported
PN_ASE_DRENABLE | 2 | Unsupported
PN_ASE_DGPSTIMEOUT | 3 | Unsupported
PN_ASE_DGPS2DENABLE | 4 | Unsupported
PN_ASE_DGPS2DTIMEOUT | 5 | Unsupported
PN_ASE_DATUM | 6 | Datum is valid or invalid.
PN_ASE_POWERSTATE | 7 | Power state is valid or invalid.
PN_ASE_ALTITUDEHOLD | 8 | Unsupported
PN_ASE_AHALTITUDE | 9 | Unsupported
PN_ASE_2DPOSMODE | 10 | Unsupported
PN_ASE_2DALTITUDE | 11 | Unsupported
PN_ASE_ENVIRONMENT | 12 | Environment is valid or invalid.
PN_ASE_ACCESS | 13 | Permissions are valid or invalid.
Reserved for future use | 14-31

dwPNReserved
Reserved for future use


PNAVSTATION

This structure indicates valid and invalid PNSTATION elements.

Syntax

typedef struct tagPNAVSTATION{
DWORD dwStructureSize;
DWORD dwAv1;
DWORD dwPNReserved;
} PNAVSTATION;

Members

dwStructureSize
Specifies the size, in bytes, of the PNAVSTATION structure
dwAv1
Specifies bit flags, one for each element in the corresponding PNSTATION structure, that indicate if an element is available. The bit flags defined for PNAVSTATION structure are described in the following table.
Flag
Bit
Description
PN_ASN_NUMAVAILABLE | 0 | Unsupported
PN_ASN_NUMUSED | 1 | Number stations used is valid or invalid.
Reserved for future use | 2-31

dwPNReserved
Reserved for future use


PNAVTM

This structure indicates valid and invalid PNTM elements.

Syntax

typedef struct tagPNAVTM
{
DWORD dwStructureSize;
DWORD dwAv1;
DWORD dwPNReserved;
} PNAVTM;

Members

dwStructureSize
Specifies the size, in bytes, of the PNAVTM structure.
dwAv1
Specifies bit flags, one for each element in the corresponding PNTM structure, that indicate whether an element is available. The bit flags defined for the PNAVTM structure are described in the following table.
Flag
Bit
Description
PN_ATM_MILLISEC | 0 | Millisecond is valid or invalid.
PN_ATM_DAY | 1 | Day is valid or invalid.
Reserved for future use | 2-31

dwPNReserved
Reserved for future use


PNAVVELENU

This structure indicates valid and invalid velocity elements.

Syntax

typedef struct tagPNAVVELENU{
DWORD dwStructureSize;
DWORD dwAv1;
DWORD dwPNReserved;
} PNAVVELENU;

Members

dwStructureSize
Specifies the size, in bytes, of the PNAVVELENU structure
dwAv1
Specifies bit flags, one for each element in the corresponding PNVELENU structure, that indicate if an element is available. The bit flags defined for the PNAVVELENU structure are described in the following table.
Flag
Bit
Description
PN_AVN_EAST | 0 | East velocity is valid or invalid.
PN_AVN_NORTH | 1 | North velocity is valid or invalid.
PN_AVN_UP | 2 | Up, or vertical, velocity is valid or invalid.
Reserved for future use | 3-31

dwPNReserved
Reserved for future use


PNCONFIG

This structure stores the data that goes into the registry as saved configuration data for this Positioning and Navigation device.

Syntax

typedef struct tagPNCONFIG{
DWORD dwStructureSize;
PNPOSITION poPositionData;
PNACCURACY acAccuracy;
PNPOSITION poStaticRefPos;
PNALMANAC alAlmanac;
PNSETTINGS seSettings;
PNBool fInitAlmanac;
PNBool fInitPosition;
PNBool fInitTime;
DWORD dwPNReserved;
} PNCONFIG;

Members

dwStructureSize
Specifies the size, in bytes, of the PNCONFIG structure.
poPositionData
Holds a GPS position and time the position was found. Only the PNPOSLLA portion of the PNPOSITION structure is used.
acAccuracy
Unsupported
poStaticRefPos
Unsupported
alAlmanac
Almanac data
seSettings
Unsupported
fInitAlmanac
Boolean that specifies if almanac is initialized when PNAPI is started. TRUE indicates that the almanac is initialized when PNAPI is started. FALSE indicates the almanac is not initialized when PNAPI is started.
fInitPosition
Boolean that specifies whether position is initialized when PNAPI is started. TRUE indicates the position is initialized when PNAPI is started. FALSE indicates the position is not initialized when PNAPI is started.
fInitTime
Boolean that specifies whether the time is initialized when PNAPI is started. TRUE indicates the time is initialized when PNAPI is started. FALSE indicates the time is not initialized when PNAPI is started.
dwPNReserved
Reserved for future use

Remarks

All latitude, and longitude position data is stored in these structures in radians. If any structure contains a tiTime member, it indicates when the data was collected.

All values in the PNCONFIG structure go to the registry. No data passes to the device.


PNDEVICE

This structure contains a Global Positioning System (GPS) device profile. In the case of multiple devices, the last element in the structure is a pointer to another PNDEVICE structure, and can be used to form a linked list of structures.

Syntax

typedef struct tagPNDEVICE{
DWORD dwStructureSize;
WCHAR szManufacturer[PN_MNFCT_SIZE_c];
WCHAR szModel[PN_MODEL_SIZE_c];
PNReceiver_t rtReceiverType;
DWORD dwUseCount;
DWORD dwQuality;
WCHAR szComPort[PN_COM_PORT_LEN_c];
WCHAR szRegRoot[PN_REG_PATH_LEN_c];
DWORD dwComPort;
DWORD dwPNReserved;
struct tagPNDEVICE* pNext;
} PNDEVICE;

Members

dwStructureSize
Specifies the size, in bytes, of the PNDEVICE structure
szManufacturer
Unsupported
szModel
Null-terminated string that contains the GPS chip manufacture and model name
rtReceiverType
Unsupported
dwUseCount
Specifies the number of applications currently using this device
dwQuality
Specifies the quality of data this device can deliver; the lower the number, the higher the quality. It is one of the following values:
100
Specifies the highest quality service. Supports all features of the position and navigation API (PNAPI).
200
Specifies the Rockwell/Trimble binary standard. Supports most PNAPI features.
300
Specifies the Garmin standard. Supports fewer features than 200.
400
Specifies the National Marine Electronics Association (NMEA) version 2.1 standard. Supports some features.
500
Specifies the NMEA version 2.0 or version 1.5 standard
600
Specifies the NMEA version 1.0 standard
700
Specifies support for basic position information, including altitude
800
Specifies the ability to give position, but not necessarily altitude
900
Specifies very basic support
szComPort
Unsupported
szRegRoot
For PNAPI internal use
pNext
Pointer to the next structure in a linked list for multiple devices
dwComPort
Specifies the COM port in numerical format
dwPNReserved
Reserved for future use


PNDEVSTATE

This structure stores the Positioning and Navigation device state and the time it last updated.

Syntax

typedef struct tagPNDEVSTATE{
DWORD dwStructureSize;
PNTIME tiTime;
PNDeviceState_t dsState;
PNAVDEVSTATE dsAvState;
DWORD dwPNReserved;
} PNDEVSTATE;

Members

dwStructureSize
Specifies the size, in bytes, of the structure
tiTime
Time of the last update
dsState
Device state
dsAvState
Indicates valid and invalid dsState elements
dwPNReserved
Reserved for future use


PNINDSTATION

This structure stores individual station details and the time each was last updated.

Syntax

typedef struct tagPNINDSTATION{
DWORD dwStructureSize;
PNTIME tiTime;
PNStationState_t ssState;
DWORD dwStationIDNum;
PNBool fUsed;
PNDouble dSatElevation;
PNDouble dSatAzimuth;
PNDouble dSignalStrength;
DWORD dwCoverage;
PNAVINDSTATION siAvIndStation;
DWORD dwPNReserved;
} PNINDSTATION;

Members

dwStructureSize
Specifies the size, in bytes, of the PNINDSTATION structure
tiTime
Unsupported
ssState
State of this station
dwStationIDNum
Specifies the pseudo-random noise (PRN) signal number, space vehicle identification (SVID) satellite number, or unique station number
fUsed
Boolean that specifies if the station is used for calculations. TRUE indicates that the station is used. FALSE indicates that the station is not used.
dSatElevation
Specfies the satellite elevation, measured in radians. Satellite elevation must be from 0 through pi/2.
dSatAzimuth
Specifies the satellite azimuth, measured in radians. Satellite azimuth must be from 0 through 2 pi.
dSignalStrength
Specifies the signal strength, in decibels
dwCoverage
Unsupported
siAvIndStation
Indicates valid and invalid PNINDSTATION elements
dwPNReserved
Reserved for future use

Remarks

For Global Positioning System (GPS) receivers, dwStationID is defined as the pseudo-random noise (PRN) signal number or space vehicle identification (SVID) satellite number. Numbers from 33 through 64 are reserved for the Wide Area Augmentation System (WAAS). Numbers from 65 through 96 are reserved for the Global Navigation Satellite System (GLONASS).


PNPOSITION

This structure stores the position and time at which this position was found.

Syntax

typedef struct tagPNPOSITION{
DWORD dwStructureSize;
PNTIME tiTime;
PNPOSLLA psPosition;
PNAVPOSLLA psAvPosition;
DWORD dwPNReserved;
} PNPOSITION;

Members

dwStructureSize
Specifies the size, in bytes, of the PNPOSITION structure
tiTime
Specifies the time the position was acquired
psPosition
Specifies the position of the vehicle containing the GPS device
psAvPosition
Specifies which PNPOSLLA elements are valid
dwPNReserved
Reserved for future use


PNPOSLLA

This structure contains position details in latitude, longitude, and altitude units.

Syntax

typedef struct tagPNPOSLLA{
PNDouble dLong;
PNDouble dLat;
PNDouble dAlt;
PNBool fRadians;
} PNPOSLLA;

Members

dLong
Specifies longitude
dLat
Specifies latitude
dAlt
Specifies height above geoid, in meters
fRadians
Boolean that is set to TRUE if the position specified by dLong and dLat is in radians, or to FALSE if it is in degrees. Position is generally described in radians throughout PNAPI unless otherwise stated.


PNSATELLITE

This structure stores individual satellite data.

Syntax

typedef struct tagPNSATELLITE{
DWORD dwStructureSize;
PNTIME tiTime;
PNBool fSetData;
DWORD dwPRN;
PNByte bSatHealth;
DWORD dwRefWeekNumber;
DWORD dwRefTimeOfWeek;
PNDouble dEccentricity;
PNDouble dRootSemiMajorAxis;
PNDouble dArgumentOfPerigee;
PNDouble dMeanAnomalyAtRefTime;
PNDouble dRightAscensionAtRefTime;
PNDouble dRateRightAscension;
PNDouble dCorrectToInclination;
PNDouble dAF0ClockCorrect;
PNDouble dAF1ClockCorrect;
PNAVSATELLITE saAvSatellite;
DWORD dwPNReserved;
} PNSATELLITE;

Members

dwStructureSize
Specifies the size, in bytes, of the structure
tiTime
Unsupported
fSetData
Unsupported
dwPRN
Specifies the satellite pseudo-random noise (PRN) signal number
bSatHealth
Health summary, expressed as a binary number
dwRefWeekNumber
Specifies the Global Positioning System (GPS) week number
dwRefTimeOfWeek
Specifies the almanac reference time
dEccentricity
Specifies the eccentricity of the orbit of the satellite. The eccentricity must be a value from 0 through 1.
dRootSemiMajorAxis
Specifies the square root of one-half the length of the major axis of the ellipse defined by the orbit of the satellite. The length of the major axis is measured in meters.
dArgumentOfPerigee
Specifies the argument of perigee of the satellite, measured in radians. The argument of the perigee must be a value from 0 through 2 pi.
dMeanAnomalyAtRefTime
Specifies the mean anomaly of the satellite at reference time, measured in radians. The mean anomaly must be a value from 0 through 2 pi.
dRightAscensionAtRefTime
Specifies the right ascension of the satellite at reference time, measured in radians. The right ascension must be a value from 0 through 2 pi.
dRateRightAscension
Specfies the rate of change in the right ascension, measured in radians per second
dCorrectToInclination
Specifies the correction to the inclination, measured in pi radians
dAF0ClockCorrect
Specifies the zeroth order clock correction, measured in seconds
dAF1ClockCorrect
Specifies the first order clock correction, measured in seconds per second
saAvSatellite
Specifies which elements are valid
dwPNReserved
Reserved for future use


PNSETTINGS

This structure stores Position and Navigation device settings that can be changed by the user.

Syntax

typedef struct tagPNSETTINGS{
DWORD dwStructureSize;
PNTIME tiTime;
PNSTATIONMODE cmMode[PN_NUM_SATS_c];
PNBool fDGPSEnable;
PNBool fDREnable;;
DWORD dwDGPSTimeOut;
PNBool fDGPS2DEnable;
DWORD dwDGPS2DTimeOut;
PNDatum_t daDatum;
PNPowerState_t pwPowerState;
PNAltHold_t ahAltitudeHold;
PNDouble dAHAltitude;
PN2DMode_t mo2DPosMode;
PNDouble d2DAltitude;
PNAccess_t asAccess;
PNEnv_t etEnvironment;
PNAVSETTINGS seAvSettings;
DWORD dwPNReserved;
} PNSETTINGS;

Members

dwStructureSize
Specifies the size, in bytes, of the structure
tiTime
Time when the data was collected
cmMode
Unsupported
fDGPSEnable
Unsupported
fDREnable
Unsupported
dwDGPSTimeOut
Unsupported
fDGPS2DEnable
Unsupported
dwDGPS2DTimeOut
Unsupported
daDatum
Geographic datum that the GPS receiver uses.
pwPowerState
Power state of device
ahAltitudeHold
Unsupported
dAHAltitude
Unsupported
mo2DPosMode
Unsupported
d2DAltitude
Unsupported
asAccess
Permissions for device
etEnvironment
Environment for this device
seAvSettings
Specifies which elements are valid
dwPNReserved
Reserved for future use


PNSTATION

This structure contains the details for all stations the Positioning and Navigation device has permissions for.

Syntax

typedef struct tagPNSTATION{
DWORD dwStructureSize;
PNTIME tiTime;
DWORD dwNumAvailable;
DWORD dwNumUsed;
PNAVSTATION snAvStation;
PNINDSTATION siStations[PN_NUM_STATIONS_c];
DWORD dwPNReserved;
} PNSTATION;

Members

dwStructureSize
Specifies the size, in bytes, of the structure
tiTime
Specifies the time the structure was last updated
dwNumAvailable
Unsupported
dwNumUsed
Specifies the number of stations tracked by the device
snAvStation
Stores which elements of PNSTATION are valid and which are not
siStations
Individual station data
dwPNReserved
Reserved for future use


PNTIME

This structure stores Positioning and Navigation device time and computer system time.

Syntax

typedef struct tagPNTIME{
PNTM tmDevice;
PNAVTM tmAvDevice;
PNTM tmLeapDiffTime;
PNAVTM tmAvLeapDiffTime;
PNTM tmComputer;
PNAVTM tmAvComputer;
} PNTIME;

Members

tmDevice
Specifies the time reported by the device
tmAvDevice
Stores which elements of tmAvDevice are valid and which are not
tmLeapDiffTime
Unsupported
tmAvLeapDiffTime
Unsupported
tmComputer
Specifies the system time on the computer
tmAvComputer
Stores which elements of tmAvComputer are valid and which are not


PNTM

This structure stores time to the millisecond.

Syntax

typedef struct tagPNTM{
DWORD dwMillisec;
DWORD dwDay;
} PNTM;

Members

dwMillisec
Specifies the number of milliseconds since start of day. This value must be from 0 through 86400000.
dwDay
Specifies the days since Jan 1, 1900


PNVELBEAR

This structure contains velocity details in the form of a bearing and two velocities.

Syntax

typedef struct tagPNVELBEAR{
PNDouble dBearing;
PNDouble dHorizSpeed;
PNDouble dVertSpeed;
} PNVELBEAR;

Members

dBearing
Range from -pi to +pi. Zero is north.
dHorizSpeed
Horizontal speed in meters per second
dVertSpeed
Vertical speed in meters per second


PNVELENU

This structure contains velocity details in the east, north, and up format.

Syntax

typedef struct tagPNVELENU{
PNDouble dEast;
PNDouble dNorth;
PNDouble dUp;
} PNVELENU;

Members

dEast
East velocity in meters per second
dNorth
North velocity in meters per second
dUp
Up velocity in meters per second

Remarks

A westward velocity is expressed as a negative east velocity and a southward velocity is expressed as a negative north velocity.


PNVELOCITY

This structure stores velocities and the time they were last updated.

Syntax

typedef struct tagPNVELOCITY{
DWORD dwStructureSize;
PNTIME tiTime;
PNVELENU vlVelocity;
PNAVVELENU vlAvVelocity;
DWORD dwPNReserved;
} PNVELOCITY;

Members

dwStructureSize
Specifies the size, in bytes, of the structure
tiTime
Time the structure was last updated
vlVelocity
The velocity of the vehicle containing the GPS device
vlAvVelocity
Indicates valid and invalid vlVelocity elements
dwPNReserved
Reserved for future use


CPL_APCINQUIRE

This message requests Auto PC specific data from a control panel application.

Syntax

CPL_APCINQUIRE (UINT) lParam1; (LPAPCCPLINFO) lParam2;

Parameters

lParam1
Unsigned integer that specifies the application number.
lParam2
Pointer to an APCCPLINFO structure that contains Auto PC-specific information about the control panel application.

See Also

APCCPLINFO


WM_APCCOMM_DIALSTATECHANGED

This message is sent internally to notify address book forms that the dialing state changed.

Parameters

wParam
Specifies the new dialing state
lParam
Specifies the result obtained from the previous dialing state.

Remarks

This message is broadcast through the application sink to forms managed by the address book application programming interface (ABAPI) by the internal telephony API (TAPI) thread.


WM_APCSYSMSG_ASSISTEVENT

This message is sent when an assist level event occurs.

Parameters

wParam
The high-order word contains the severity level for the assist event. The low-order word is reserved.
lParam
Reserved.

Remarks

This message is broadcast by a driver installed by an original equipment manufacturer (OEM).

See Also

HIWORD, LOWORD


WM_APCSYSMSG_INSTALLNOTIFY

This message is sent when an install operation begins.

Syntax

WM_APCSYSMSG_INSTALLNOTIFY wParam = 0; lParam = 0;

Remarks

ApcLoad.exe broadcasts this message at the beginning of the install operation. An application should treat this message like WM_CLOSE and exit in response to this message. An application has 5 seconds after the issuance of this message to shutdown completely.


WM_APCSYSMSG_MEDIASTATECHANGE

This message is sent when the state of a media device changes.

Parameters

wParam
The high-order word contains the media type. It is one of the following values:
Media type
Value
APC_MEDIATYPE_CD 1

The low-order word contains the notification flags. It may be a combination of the following values:
Notification flag
Value
APC_FLAG_MEDIAINSERT | 0x0001
APC_FLAG_MEDIAHASAUDIO | 0x0010
APC_FLAG_MEDIAHASDATA | 0x0020

lParam
The high-order word contains the device generating the notification. It is one of the following values:
Device generating notification
Value
APC_MEDIADEVICE_DASHCD | 0
APC_MEDIADEVICE_CHANGER1 | 1
APC_MEDIADEVICE_CHANGER2 | 2
APC_MEDIADEVICE_CHANGER3 | 3
APC_MEDIADEVICE_CHANGER4 | 4

The low-order word contains device-specific information.

See Also

HIWORD, LOWORD


WM_APCSYSMSG_MUTE

This message is sent if the audio state is changed to muted or to non-muted.

Parameters

wParam
Reserved.
lParam
Set to TRUE if the audio state is changed to muted. Set to FALSE if the audio state is changed to non-muted.


WM_APCSYSMSG_BACKUPNOTIFY

This message notifies an application that it should flush all its data and prepare for backup of the file system, object store and registry.

Parameters

wParam
Specifies the thread identifier of the Backup.exe received by an application, or 0 when posted by the application to Backup.exe.
lParam
Specifies the backup transaction identifier.

Remarks

The Backup.exe broadcasts this message at the beginning of the backup operation. Applications should flush their data to the registry, file system, or object store upon receiving this message to ensure that the data is preserved by the backup operation. Applications which have opened data files with the DENY_READ attribute set should close the files if the files should be backed up. Applications have five seconds after this message is sent to complete their save operations. Any application may request more time in units of five seconds by posting this message to the backup thread by setting wParam to 0.

If an application has a data file open, it may wish to close the file on receiving this message so the file will be backed up.


WM_APCSYSMSG_POWERSTATECHANGE

This message is sent when the power is turned off or on.

Parameters

wParam
Specifies the power notification type. It is one of the following values:
Power notification type
Value
APC_PWRNOTIFYTYPE_USER | 1
APC_PWRNOTIFYTYPE_ELECTRICAL | 2
APC_PWRNOTIFYTYPE_BACKUPBATTERY_LOW | 3

lParam
For USER and ELECTRICAL, set to TRUE if the power state is changed to ON, or to FALSE if the power state is changed to OFF.

For BATTERY_LOW, HIWORD(lParam) is FALSE if the battery is low, or TRUE if the battery is not low. LOWORD(lParam) gives the zero-based index of the battery.

Remarks

An APC_PWRNOTIFYTYPE_ELECTRICAL notification is not sent when the electrical power is removed, only when it is restored.


WM_APCSYSMSG_VOLUMECHANGED

This message is sent when the audio volume changes.

Syntax

WM_APCSYSMSG_VOLUMECHANGED wParam = Reserved; lParam = Reserved;

Remarks

This message does not currently take parameters.


WM_AUDSRCSELECT

This message is posted by the system to notify an application that an audio source has been selected. The application must implement a callback function to receive the message.

Parameters

wParam
Specifies the audio source identifier.
lParam
Set to 0.

See Also

WM_AUDSRCUNSELECT


WM_AUDSRCUNSELECT

This message is posted by the system to notify an application that an audio source has been unselected. The application must implement a callback function to receive the message.

wParam
Specifies the current audio source identifier.
lParam
Specifies the new audio source identifier.

See Also

WM_AUDSRCSELECT


WM_AUDSRCREGISTER

This message is posted by the system to notify an application that an audio source has been registered. The application must implement a callback function to receive the message.

Parameters

wParam
Specifies the audio source identifier.
lParam
Set to 0.

See Also

WM_AUDSRCUNREGISTER


WM_AUDSRCUNREGISTER

This message is posted by the system to notify an application that an audio source has been unregistered. The application must implement a callback function to receive the message.

Parameters

wParam
Specifies the current audio source identifier.
lParam
Set to 0.

See Also

WM_AUDSRCREGISTER


WM_QUERYKEYUSAGE

This message is posted by a NavArrow control to determine the keys that the sink for an application or a form can process.

Parameters

wParam
Unused.
lParam
Contains a pointer to an IQueryKeyUsage interface.

See Also

IQueryKeyUsage, IQueryKeyUsage::FlagKeysUsed


WM_SETTINGCHANGE

This message is sent when the Control Panel modifies an Auto PC setting that necessitates a notification be sent to running applications.

Syntax

WM_SETTINGCHANGE wParam = wFlag; lParam = NULL

Parameters

wParam
Specifies one of the Auto PC-specific SPI_SETAPC* values described in the following table.
Constant
Value
Description
SPI_SETAPCSHELL | 0x000100100 | Shell setting changed
SPI_SETAPCSCREENSAVER | 0x000100102 | Screen saver changed
SPI_SETAPCAUDIO | 0x000100104 | Audio changed
SPI_SETAPCLOCALE | 0x000100106 | Locale changed
SPI_SETAPCFEEDBACK | 0x000100108 | Feedback changed
SPI_SETAPCGLOBALGRAMMAR | 0x00010010a | Global grammar changed

lParam
Set to NULL.

Remarks

It is not valid to pass these values to SystemParameterInfo. Instead, they must be explicitly queried for with the appropriate registry settings.


WM_SPCH_FEEDBACK

This message notifies the application of speech feedback.

Parameters

wParam
The high order word is reserved. The low order word contains a description of the amount of information and detail currently provided in the speech feedback. It is one of the following values.
APCSPCH_FB_MORE
Provides a greater amount of feedback than APCSPCH_FB_LESS, usually adding either text-to speech (TTS) feedback or prerecorded speech feedback after the speech recognition tone. This additional feedback usually consists of application-specific information or the name of the application currently in use.
APCSPCH_FB_LESS
Provides minimal feedback.
lParam
The high order word contains the reason for the initiation of speech feedback. It is one of the following values.
SFR_WAKEUPWORD
Speech feedback started because the user issued the "Wake Up" command.
SFR_PTT
Speech feedback started because the user pressed the push-to-talk key.
SFR_READ
Speech feedback started because the user issued the "Read" command.

The low order word contains information specific to the reason in the high order word. If the high order word is SFR_WAKEUPWORD or SFR_PTT, then the low order word indicates the wake up state that existed when the event occurred. A value of 1 indicates that speech recognition was already awake when the event occurred. A value of 0 indicates that speech recognition was asleep when the event occurred.


WM_SPCH_NOTIFY

This message notifies the application of speech related activity.

Parameters

wParam
It is one of the following values, depending on the options that are specified in the CreateAPCSpeechObject call:
VCMDRF_CMDSTART
The engine detects the beginning of a phrase.
VCMDRF_CMDOTHER
If lParam is nonzero, a phrase is recognized in another grammar. If lParam is zero, a phrase is ended without being recognized.
VCMDRF_ATTRIBCHANGE
Speech attributes have changed.
VTXTF_SPEAKDONE
The engine stopped speaking.
VTXTF_SPEAKSTOP
The engine’s text-to-speech output was stopped by an application.
VTXTF_SPEAK
The engine encountered a bookmark. The lParam is the bookmark identifier.

Remarks

An application can embed “\mrk=xx\” strings inside the text to be spoken to create a bookmark. When the speech engine encounters a bookmark, a WM_SPCH_NOTIFY message with wParam equal to VTXTF_SPEAK and lParam equal to the bookmark identifier is posted to the application. The traditional Speak(string, ID) also works because the system adds “\mrk=ID\” before the string and then sends it to the engine.


WM_SPCH_RECOG

This message is sent when a phrase is recognized.

Remarks

The lParam contains the command identifier of the phrase that is recognized.

If the application called AddVMenuCommand with a user-defined DWORD, the wParam will be that DWORD. Otherwise it is zero.


WM_SPCH_SNDDONE

This message notifies the application of that a sound has finished.

wParam is always zero.

lParam is the sound ID passed into the PlaySound function.


PN3State_t

Enumerates a set of available modes

Syntax

typedef enum ePN3State_t{
PN_3S_FALSE = MIN_PNALTHOLD_T,
PN_3S_TRUE = 1,
PN_3S_OTHER = MAX_PNALTHOLD_T
}PN3State_t;

Members

PN_3S_FALSE
Off, or FALSE position
PN_3S_TRUE
On, or TRUE position
PN_3S_OTHER
Other, or indeterminate position


PNAccess_t

Enumerates permissions the Positioning and Navigation device supplies to the application

Syntax

typedef enum ePNAccess_t{
PN_AS_READWRITE = MIN_PNACCESS_T,
PN_AS_READ = MAX_PNACCESS_T
}PNAccess_t;

Members

PN_AS_READWRITE
Device has full permissions.
PN_AS_READ
Device has partial permissions, which enables the user to only receive data from the Positioning and Navigation device.


PNData_t

Enumerates the types of data used by methods such as GetData and SetData.

Syntax

typedef enum ePNData_t{
PN_DT_ALL = MIN_PNDATA_T,
PN_DT_POSITION = 1,
PN_DT_VELOCITY = 2,
PN_DT_DEVICESTATE = 3,
PN_DT_TIME = 4,
PN_DT_TM = 5,
PN_DT_ACCURACY = 6,
PN_DT_STATION = 7,
PN_DT_DEVICE = 8,
PN_DT_CONFIG = 9,
PN_DT_SETTINGS = 10,
PN_DT_ALMANAC = 14,
}PNData_t;

Members

PN_DT_ALL
All PNData_t fields
PN_DT_POSITION
Longitude, latitude, and altitude position data, in the format specified by the PNPOSLLA structure
PN_DT_VELOCITY
Velocity data, in the format specified by the PNVELOCITY structure
PN_DT_DEVICESTATE
Device state data, in the format specified by the PNDEVSTATE structure
PN_DT_TIME
Time data, in the format specified by the PNTIME structure
PN_DT_TM
Time data, in the format specified by the PNTM structure
PN_DT_ACCURACY
Accuracy data, in the format specified by the PNACCURACY structure
PN_DT_STATION
Station data, in the format specified by the PNSTATION structure
PN_DT_DEVICE
Device profile data, in the format specified by the PNDEVICE structure
PN_DT_CONFIG
Configuration data, in the format specified by the PNCONFIG structure
PN_DT_SETTINGS
Settings data, in the format specified by the PNSETTINGS structure
PN_DT_ALMANAC
Almanac data, in the format specified by the PNALMANAC structure


PNDatum_t

Enumerates the links between datum and datum code

Syntax

typedef enum ePNDatum_t{
PN_DA_WGS84 = MIN_PNDATUM_T
}PNDatum_t;

Members

PN_DA_WGS84
World Geodetic System 1984, the datum used by GPS receivers


PNDeviceState

Enumerates the possible device states

Syntax

typedef enum ePNDeviceState_t{
PN_DS_INVALIDDS = -1000,
PN_DS_NOTPRESENT= MIN_DEVICESTATE_T,
PN_DS_ERROR = 1,
PN_DS_WARNING = 2,
PN_DS_OK = 3,
PN_DS_SEARCHING = 4,
PN_DS_LEVEL1 = 5,
PN_DS_LEVEL2 = 6,
PN_DS_LEVEL3 = 7,
PN_DS_LEVEL4 = 8,
PN_DS_LEVEL5 = 9,
PN_DS_LEVEL6 = 10,
PN_DS_FOUND1SAT = 11,
PN_DS_FOUND2SATS= 12,
PN_DS_NOTIME = MAX_DEVICESTATE_T
}PNDeviceState_t;

Members

PN_DS_INVALIDDS
Invalid device state
PN_DS_NOTPRESENT
GPS device is not present, for example, it has been unplugged
PN_DS_ERROR
A GPS device error has stopped operation
PN_DS_WARNING
There is an error with the GPS device, but GPS device can still operate
PN_DS_OK
GPS device is functioning, but not searching for data
PN_DS_SEARCHING
Searching for a satellite position
PN_DS_LEVEL1
Found level 1 accuracy data
PN_DS_LEVEL2
Found level 2 accuracy data
PN_DS_LEVEL3
Found level 3 accuracy data
PN_DS_LEVEL4
Found level 4 accuracy data
PN_DS_LEVEL5
Found level 5 accuracy data
PN_DS_LEVEL6
Found level 6 accuracy data
PN_DS_FOUND1SAT
Found 1 satellite
PN_DS_FOUND2SATS
Found 2 satellites
PN_DS_NOTIME
No GPS time found


PNPowerState_t

Enumerates different power states of the Positioning and Navigation device

Syntax

typedef enum ePNPowerState_t{
PN_PW_OFF = MIN_PNPOWERSTATE_T,
PN_PW_SUSPENDED = 1,
PN_PW_STANDBY = 2,
PN_PW_LOWPOWER = 3,
PN_PW_MIDPOWER = 4,
PN_PW_FULLPOWER = MAX_PNPOWERSTATE_T
}PNPowerState_t;

Members

PN_PW_OFF
No power
PN_PW_SUSPENDED
Temporarily suspended
PN_PW_STANDBY
Standby mode
PN_PW_LOWPOWER
Low-power mode
PN_PW_MIDPOWER
Half-power mode
PN_PW_FULLPOWER
Full-power mode


PNStationState_t

Enumerates the station states

Syntax

typedef enum ePNStationState_t{
PN_CS_UNAVAILABLE = MIN_PNSTATIONSTATE_T,
PN_CS_IDLE = 1,
PN_CS_SEARCHING = 2,
PN_CS_TRACKING = MAX_PNSTATIONSTATE_T
}PNStationState_t;

Members

PN_CS_UNAVAILABLE
Unavailable
PN_CS_IDLE
Idle
PN_CS_SEARCHING
Searching for data
PN_CS_TRACKING
Finding valid data


PNEnv_t

Enumerates the predefined environments to which Positioning and Navigation devices can be set

Syntax

typedef enum ePNEnv_t{
PN_ET_STATIONARY = MIN_PNENV_T,
PN_ET_OPENROAD = 1,
PN_ET_URBANCANYON = 2,
PN_ET_FOREST = 3,
PN_ET_OPENOCEAN = 4,
PN_ET_AIRCRAFT = 5,
PN_ET_NONE = 6,
PN_ET_USER = MAX_PNENV_T
}PNEnv_t;

Members

PN_ET_STATIONARY
GPS device is not moving
PN_ET_OPENROAD
GPD device is on open road with clear view of sky
PN_ET_URBANCANYON
Device is surrounded by tall city buildings
PN_ET_FOREST
Device is in a forest or near trees
PN_ET_OPENOCEAN
Device is on the open ocean with a full view of sky
PN_ET_AIRCRAFT
Device is in an aircraft with full view of sky
PN_ET_NONE
No environment has been set. This is only returned by PNSETTINGS.
PN_ET_USER
To be determined


Audio Manager Error Values

The following table shows the errors that can be returned by audio manager functions.

Error value
Description
AAM_ERR_ALREADYEXIST | Audio source or callback already exists.
AAM_ERR_DEVICEBUSY | The device is busy.
AAM_ERR_DEVICEFAIL | The call failed.
AAM_ERR_INVALIDPARAM | Invalid parameter.
AAM_ERR_NOTFOUND | Audio source or callback not found.
AAM_ERR_NOTSUPPORTED | Function not supported.
AAM_ERR_OUTOFMEMORY | Out of memory.
AAM_ERR_OUTOFRANGE | Parameter out of range.


Forms Manager Error Values

The following table shows the errors that can be returned by Forms Manager functions.

Error value
Description
ASFC_E_BADID | Bad control or form identifier provided to a method.
ASFC_E_CTRL_CLOSED | Control has been closed.
ASFC_E_IDEXISTS | Identifier already exists.
ASFC_E_CTRL_INVALID | Control does not support all interfaces.
ASFC_E_CTRL_NOFOCUS | No current focus.
ASFC_E_CTRL_NOPARENT | Control does not have a form parent.
ASFC_E_CTRL_NOTINIT | Control has not been initialized.
ASFC_E_CTRL_NOTSTARTED | Control has not been started.
ASFC_E_CTRL_NOSUCH | Unknown control.
ASFC_E_FM_NOFMS | No Forms Managers allocated.
ASFC_E_FM_NOSUCH | No such Forms Manager exists.
ASFC_E_FORM_BADDC | A bad handle to a device context (HDC) was recognized.
ASFC_E_FORM_DRAWINACTIVE | Drawing is disabled.
ASFC_E_FORM_EMPTY | No controls on this form.
ASFC_E_NOMENU | No menu.
ASFC_E_SYSTEM | System error.
ASFC_E_VERSION | Wrong version of Asfc.dll.


Voice-Command Error Values

The following table shows the errors that can be returned by methods of the voice command objects. If no error occurs, the functions return NOERROR.

Error value
Description
VCMDERR_CANNOTMIMIC | No command was found to match the input string.
VCMDERR_CANTCREATEAUDIODEVICE | An audio source object cannot be created for speech recognition.
VCMDERR_CANTCREATEDATASTRUCTURES | The internal data structures needed to build a grammar cannot be created.
VCMDERR_CANTCREATESRENUM | A speech recognition enumerator object cannot be created.
VCMDERR_CANTCREATESTORAGE | Space cannot be created in the database for the menu.
VCMDERR_CANTINITDATASTRUCTURES | The internal data structures needed to build a grammar cannot be initialized.
VCMDERR_CANTSELECTENGINE | A speech recognition engine cannot be selected.
VCMDERR_CANTSETDEVICE | The device identifier cannot be set into the audio source object.
VCMDERR_CANTXTRACTWORDS | The unique words needed by the engine grammar object cannot be extracted.
VCMDERR_INVALIDCHAR | There is an invalid character in the voice menu.
VCMDERR_INVALIDLIST | There was an invalid list passed to IVCmdMenu::ListSet or IVCmdMenu::ListGet.
VCMDERR_INVALIDMODE | No site exists, the site does not support this attribute, or the voice command object is already registered with a site.
VCMDERR_INVALIDWINDOW | The window is invalid.
VCMDERR_MENUACTIVE | The menu is currently active and cannot be deleted.
VCMDERR_MENUDOESNOTEXIST | The requested menu does not exist in the database.
VCMDERR_MENUEXIST | The requested new or temporary menu already exists in the database.
VCMDERR_MENUOPEN | The menu exists but has not been released, so it cannot be deleted.
VCMDERR_MENUTOOCOMPLEX | The menu is too complex to use.
VCMDERR_MENUWRONGLANGUAGE | The language is not supported by the speech recognition engine.
VCMDERR_NOCACHEDATA | There is no internal cache entry for this menu.
VCMDERR_NOCOMMANDS | The menu is active, but the menu does not yet contain any commands.
VCMDERR_NOENGINE | No speech recognition engine is active.
VCMDERR_NOFINDINTERFACE | The speech recognition enumerator interface does not have a Find interface.
VCMDERR_NOGRAMMARINTERFACE | No engine grammar object is available.
VCMDERR_NOSITEINFO | Information to open this site is not available.
VCMDERR_NOTSUPPORTED | The function is not supported by the engine.
VCMDERR_OUTOFDISK | No disk space is left to write information.
VCMDERR_OUTOFMEM | There is no more memory.
VCMDERR_SRFINDFAILED | The speech recognition object could not find an appropriate mode.
VCMDERR_TOOMANYMENUS | There are too many active menus.
VCMDERR_VALUEOUTOFRANGE | The value is out of range.

In addition to the error values described in the preceding list, methods can return error values generated by lower-level component objects or calls to the Win32 API.


Voice-Text Error Values

The following table shows the errors that can be returned by methods of the voice text object. If no error occurs, the methods return the NOERROR error value.

Error value
Description
VTXTERR_INVALIDMODE | The text-to-speech mode is invalid, or the application has not been registered to use the voice text on the site.
VTXTERR_INVALIDPARAM | A parameter is invalid.
VTXTERR_INVALIDWINDOW | A window is invalid.
VTXTERR_NOTENABLED | Voice text is not enabled.
VTXTERR_NOTENOUGHDATA | The text stream has been rewound beyond the beginning or fast-forwarded past the end of the stream.
VTXTERR_NOTSUPPORTED | The dialog box is not supported by the engine.
VTXTERR_OUTOFMEM | There is not enough memory.
VTXTERR_QUEUEFULL | The playback queue is full.
VTXTERR_WAVEDEVICEBUSY | The wave device is busy.

In addition to the error values described in the preceding list, methods can return error values generated by lower-level component objects or calls to the Win32 API.


Virtual-Key Codes

The following table shows the symbolic constant names, the values to which they are defined as equivalent in the standard Windows CE key codes, and keyboard equivalents for the virtual-key codes used by Microsoft Windows CE for the Auto PC. The codes are listed in numeric order.

Virtual-Key Codes
Symbolic constant name
Defined as
Equivalent
VK_STAR | VK_F1 | Telephone keypad * key
VK_POUND | VK_F2 | Telephone keypad # key
VK_SENDCALL | VK_F3 | Telephone keypad SEND key
VK_ENDCALL | VK_F4 | Telephone keypad END key
VK_MUTE | VK_F5 | Telephone keypad MUTE key
VK_VOLUMEUP | VK_F6 | Telephone keypad Volume Up key
VK_VOLUMEDOWN | VK_F7 | Telephone keypad Volume Down key
VK_REDIAL | VK_F8 | Telephone keypad REDIAL key
VK_STORE | VK_F9 | Telephone keypad STORE key
VK_RECALL | VK_F10 | Telephone keypad RECALL key
VK_HOLD | VK_F11 | Telephone keypad HOLD key
VK_CONFERENCE | VK_F12 | Telephone keypad CONFERENCE key
VK_TRANSFER | VK_F13 | Telephone keypad TRANSFER key
VK_HOOK | VK_F14 | Telephone keypad FLASH key
VK_CALLBACK | VK_F15 | Telephone keypad CALLBACK key
VK_SPEAKER | VK_F16 | Telephone keypad SPEAKER key
VK_AUDIO | VK_F23 | The audio application start key
VK_SPEECH | VK_F24 | The push-to-talk key
VK_NUMPAD0 | VK_NUMPAD0 | Numeric keypad 0 key
VK_NUMPAD1 | VK_NUMPAD01 | Numeric keypad 1 key
VK_NUMPAD2 | VK_NUMPAD02 | Numeric keypad 2 key
VK_NUMPAD3 | VK_NUMPAD03 | Numeric keypad 3 key
VK_NUMPAD4 | VK_NUMPAD04 | Numeric keypad 4 key
VK_NUMPAD5 | VK_NUMPAD05 | Numeric keypad 5 key
VK_NUMPAD6 | VK_NUMPAD06 | Numeric keypad 6 key
VK_NUMPAD7 | VK_NUMPAD07 | Numeric keypad 7 key
VK_NUMPAD8 | VK_NUMPAD08 | Numeric keypad 8 key
VK_NUMPAD9 | VK_NUMPAD09 | Numeric keypad 9 key


CLSIDs for the Auto PC

The vehicle I/O APIs documented here are preliminary and subject to change.

This table lists the CLSIDs for the Auto PC vehicle information API.

CLSID
Description
CLSID_VIOVEHICLE | Returns information about the vehicle as a whole.
CLSID_VIO_IOCTL | Returns information about the API.
CLSID_VIO_IGNITION_SWITCH | Returns the status of the ignition switch.
CLSID_VIO_HEADLIGHTS | Returns the status of the headlight switch.
CLSID_VIO_PARKING_BRAKE | Returns the status of the parking brake.
CLSID_VIO_VEHICLE_SPEED | Returns the current vehicle speed.
CLSID_VIO_ENGINE_RPM | Returns the current crankshaft rotation rate.
CLSID_VIO_COOLANT_TEMP | Returns the engine’s coolant temperature.
CLSID_VIO_BATTERY_VOLTAGE | Returns the current battery output voltage.
CLSID_VIO_TIMING_ADVANCE | Returns the ignition spark advance.
CLSID_VIO_THROTTLE_POSITION | Returns the current throttle position as a percentage.
CLSID_VIO_INTAKE_TEMP | Returns the temperature of the air when it arrives in the engine.
CLSID_VIO_MANIFOLD_AIR_PRESSURE | Returns the absolute air pressure in the intake manifold.
CLSID_VIO_ENGINE_LOAD | Returns the engine load, which is the current airflow as a percentage of the peak airflow into the engine.
CLSID_VIO_FUEL_PRESSURE | Returns the fuel pressure relative to ambient atmospheric pressure.
CLSID_VIO_MASS_AIR_FLOW_RATE | Returns the mass flow rate of air into the engine.
CLSID_VIO_ODOMETER | Returns an odometer reading.
CLSID_VIO_TRANSMISSION_GEAR | Returns the current transmission gear position.
CLSID_VIO_FUEL_SYSTEM_STATUS | Determines if adjustments are being made to the fuel flow to the cylinders, and why.
CLSID_VIO_FUEL_TRIM | Describes the adjustment to the fuel delivery calibration.
CLSID_VIO_O2_SENSOR | Returns the voltage of the oxygen sensors in the vehicle.
CLSID_VIO_DOOR_SWITCHES | Retrieves the status of the door, liftgate, and trunk lid pin switches.
CLSID_VIO_LATCH_CONTROL | Releases a latch, such as a truck latch, gas cap, or hood.
CLSID_VIO_LOCK_STATE | Locks and unlocks power locks.
CLSID_VIO_AUX_LIGHTS | Returns the status of various lights in the vehicle.
CLSID_VIO_DIAGNOSTIC_CODES | Returns diagnostic trouble codes generated by the vehicle’s electronic control units.


CLSID_VIOVEHICLE

This CLSID returns information about the vehicle as a whole.

Name

Vehicle


CLSID_VIO_IOCTL

This CLSID returns information about the API.

Name

API


CLSID_VIO_IGNITION_SWITCH

This CLSID returns the status of the ignition switch.

Name

Ignition switch

Access

Read, shareable or exclusive

Range

Type: VT_UI4 (unsigned long)

The following table shows possible bitmask values.

Ignition switch status
Bitmask value
VIOIGNITIONSWITCH_OFF | 0x00
VIOIGNITIONSWITCH_RUN | 0x01
VIOIGNITIONSWITCH_START | 0x02
VIOIGNITIONSWITCH_ACC | 0x04

Input

None

Output

Type: | VT_UI4 (unsigned long bitmask)
Measurement: | VIOMEASUREMENT_DISCRETEMASK (bitmask)
Units: | VIOUNITS_BITMASK

Remarks

API device objects expect the following data types and sizes when sending data to and from the mini-drivers:

Mini-driver input

None

Mini-driver output

Type: | DWORD *
Size: | 4 bytes
Description: | Bitmask that contains VIOIGNITIONSWITCH_* values.

Example

HRESULT hr;
IVIO_Device *pIgnitionSwitch;
VARIANT vDeviceData;
ULONG ulSwitchStatus;
//Create an instance of the ignition switch device component and get its //IVIO_Device interface.
hr = CoCreateInstance(CLSID_VIO_IGNITION_SWITCH, NULL,
                     CLSCTX_INPROC_SERVER, IID_VIODEVICE,
                     &pIgnitionSwitch);
//Ask the device for its current status bits.
pIgnitionSwitch->GetData(&vDeviceData, 1000);
//Fetch the status bits from the VARIANT.
ulSwitchStatus = vDeviceData.ulVal;
//Release the reference to the interface.
pIgnitionSwitch->Release();


CLSID_VIO_HEADLIGHTS

This CLSID returns the status of the headlight switch.

Name

Headlight switch

Access

Read, shareable or exclusive

Range

Type: VT_UI4 (unsigned long bitmask)

The following table shows possible bitmask values.

Headlight switch status
Bitmask value
VIOHEADLIGHTS_OFF | 0x00
VIOHEADLIGHTS_PARKINGLIGHTS | 0x01
VIOHEADLIGHTS_HEADLIGHTS | 0x02
VIOHEADLIGHTS_BRIGHTHEADLIGHTS | 0x04

Input

None

Output

Type: | VT_UI4 (unsigned long)
Measurement: | VIOMEASUREMENT_DISCRETEMASK (Bitmask)
Units: | VIOUNITS_BITMASK

Remarks

API device objects expect the following data types and sizes when sending data to and from the mini-drivers:

Mini-driver input

None

Mini-driver output

Type: | DWORD *
Size: | 4 bytes
Description: | Bitmask that contains VIOHEADLIGHTS_* values.

Example

HRESULT hr;
IVIO_Device *pHeadlightSwitch;
VARIANT vDeviceData;
ULONG ulSwitchStatus;
//Create an instance of the headlight switch device component and get //its IVIO_Device interface.
hr = CoCreateInstance(CLSID_VIO_HEADLIGHTS, NULL,
                     CLSCTX_INPROC_SERVER, IID_VIODEVICE,
                     &pHeadlightSwitch);
//Ask the device for its current status bits.
pHeadlightSwitch->GetData(&vDeviceData, 1000);
//Fetch the status bits from the VARIANT.
ulSwitchStatus = vDeviceData.ulVal;
//Release the reference to the interface.
pHeadlightSwitch->Release();


CLSID_VIO_PARKING_BRAKE

This CLSID returns the status of the parking brake.

Name

Parking brake

Access

Read, shareable or exclusive

Range

Type: VT_UI4 (unsigned long bitmask)

The following table shows possible bitmask values.

Parking brake status
Bitmask value
VIOPARKINGBRAKE_OFF | 0
VIOPARKINGBRAKE_ON | 1

Input

None

Output

Type: | VT_UI4 (unsigned long bitmask)
Measurement: | VIOMEASUREMENT_DISCRETEMASK (bitmask)
Units: | VIOUNITS_BITMASK

Remarks

API device objects expect the following data types and sizes when sending data to and from the mini-drivers:

Mini-driver input

None

Mini-driver output

Type: | DWORD *
Size: | 4 bytes
Description: | Bitmask that contains VIOPARKINGBRAKE_* values.

Example

HRESULT hr;
IVIO_Device *pParkingBrake;
VARIANT vDeviceData;
BOOL bBrakeOn;
//Create an instance of the parking brake device component and get
//its IVIO_Device interface.
hr = CoCreateInstance(CLSID_VIO_PARKING_BRAKE, NULL,
                     CLSCTX_INPROC_SERVER, IID_VIODEVICE,
                     &pParkingBrake);
//Ask the device for its current status bits.
pParkingBrake->GetData(&vDeviceData, 1000);
//Fetch the status bits from the VARIANT.
bBrakeOn = (vDeviceData.ulVal != VIO_PARKINGBRAKE_OFF);
//Release the reference to the interface.
pParkingBrake->Release();


CLSID_VIO_VEHICLE_SPEED

This CLSID returns the current vehicle speed.

Name

Vehicle speed

Access

Read, shareable or exclusive

Range

Type: | VT_UI2 (unsigned short)
Low: | 0
High: | 383

Input

None

Output

Type: | VT_UI2 (unsigned short)
Measurement: | VIOMEASUREMENT_SPEED
Units: | VIOUNITS_KILOMETERSPERHOUR

Remarks

API device objects expect the following data types and sizes when sending data to and from the mini-drivers:

Mini-driver input

None

Mini-driver output

Type: | USHORT *
Size: | 2 bytes
Description: | Vehicle speed in kilometers per hour

Example

HRESULT hr;
IVIO_Device *pVehicleSpeed;
//Create the event sink - CVehicleSpeedSink is derived from //IVIO_EventSink.
IVIO_EventSink *iSpeedSink = new CVehicleSpeedSink;
//Create an instance of the vehicle speed device and get its
//IVIO_Device interface.
hr = CoCreateInstance(CLSID_VIO_VEHICLE_SPEED, NULL,
                     CLSCTX_INPROC_SERVER, IID_VIODEVICE,
                     &pVehicleSpeed);
//Set the notification sink to notify every half second.
pVehicleSpeed->SetNotify(NULL, iSpeedSink, 500);
.
.
//Turn off the notification sink.
pVehicleSpeed->SetNotify(NULL, NULL, 0);
//Release the reference to the vehicle speed device.
pVehicleSpeed->Release();
//Release the reference to the event sink.
iSpeedSink->Release();


CLSID_VIO_ENGINE_RPM

This CLSID returns the current crankshaft rotation rate.

Name

Engine RPM

Access

Read, shareable or exclusive

Range

Type: | VT_UI2 (unsigned short)
Low: | 0
High: | 16,383

Input

None

Output

Type: | VT_UI2 (unsigned short)
Measurement: | VIOMEASUREMENT_ROTATIONALSPEED
Units: | VIOUNITS_RPM

Remarks

API device objects expect the following data types and sizes when sending data to and from the mini-drivers:

Mini-driver input

None

Mini-driver output

Type: | USHORT *
Size: | 2 bytes
Description: | Engine revolutions per minute (RPM)

Example

HRESULT hr;
IVIO_Device *pEngineRPM;
//Create the event sink; CEngineRPMSink is derived from //IVIO_EventSink.
IVIO_EventSink *iRpmSink = new CEngineRPMSink;
//Create an instance of the engine RPM device and get its
//IVIO_Device interface.
hr = CoCreateInstance(CLSID_VIO_ENGINE_RPM, NULL,
                     CLSCTX_INPROC_SERVER, IID_VIODEVICE,
                     &pEngineRPM);
//Set the notification sink to notify every half second.
pEngineRPM->SetNotify(NULL, iRpmSink, 500);
.
.
. //Turn off the notification sink.
pVehicleSpeed->SetNotify(NULL, NULL, 0);
//Release the reference to the event sink.
iRpmSink->Release();
//Release the reference to the interface.
pEngineRPM->Release();


CLSID_VIO_COOLANT_TEMP

This CLSID returns the engine’s coolant temperature.

Name

Coolant temperature

Access

Read, shareable or exclusive

Range

Type: | VT_I2 (signed short integer)
Low: | –128
High: | +255

Input

None

Output

Type: | VT_I2 (signed short integer)
Measurement: | VIOMEASUREMENT_TEMPERATURE
Units: | VIOUNITS_CELSIUS

Remarks

API device objects expect the following data types and sizes when sending data to and from the mini-drivers:

Mini-driver input

None

Mini-driver output

Type: | SHORT *
Size: | 2 bytes
Description: | Coolant temperature in degrees Celsius

Example

HRESULT hr;
IVIO_Device *pCoolantTemp;
VARIANT vDeviceData;
SHORT sCoolantTemp;
//Create an instance of the coolant temperature device and get its
//IVIO_Device interface.
hr = CoCreateInstance(CLSID_VIO_COOLANT_TEMP, NULL,
                     CLSCTX_INPROC_SERVER, IID_VIODEVICE,
                     &pCoolantTemp);
//Ask the device for coolant temperature.
pCoolantTemp->GetData(&vDeviceData, 3000);
//Fetch the coolant temperature, in degrees Celsius, from the VARIANT.
sCoolantTemp = vDeviceData.iVal;
//Release the reference to the interface.
pCoolantTemp->Release();


CLSID_VIO_BATTERY_VOLTAGE

This CLSID returns the current battery output voltage.

Name

Battery voltage

Access

Read, shareable or exclusive

Range

Type: | VT_UI2 (unsigned short fixed point decimal)
Low: | 0.00
High: | 32.77

Input

None

Output

Type: | VT_UI2 (unsigned short fixed point decimal)
Measurement: | VIOMEASUREMENT_VOLTAGE
Units: | VIOUNITS_VOLTS

Remarks

API device objects expect the following data types and sizes when sending data to and from the mini-drivers:

Mini-driver input

None

Mini-driver output

Type: | SHORT *
Size: | 2 bytes
Description: | Battery voltage in 0.001 volt increments.

Example

HRESULT hr;
IVIO_Device *pBatteryVoltage;
VIODEVICEMETRICS dmBattery;
VARIANT vDeviceData;
USHORT usFixedPointVoltage;
float fFloatVoltage;
//Create an instance of the battery voltage device and get its
//IVIO_Device interface.
hr = CoCreateInstance(CLSID_VIO_BATTERY_VOLTAGE, NULL,
                     CLSCTX_INPROC_SERVER, IID_VIODEVICE,
                     &pBatteryVoltage);
//Get the metrics for the battery voltage device.
pBatteryVoltage->get_Metrics(&dmBattery);
//Ask the device for current voltage.
pBatteryVoltage->GetData(&vDeviceData, 3000);
//Fetch the battery voltage as a fixed-point value from the VARIANT.
usVoltage = vDeviceData.uiVal;
//Convert the fixed-point value to a float value.
fFloatVoltage = ((float) usVoltage) * (10 ^ dmBattery.lExponent);
//Release the reference to the interface.
pBatteryVoltage->Release();


CLSID_VIO_TIMING_ADVANCE

This CLSID returns the ignition spark advance.

Name

Ignition timing advance

Access

Read, shareable or exclusive

Range

Type: | VT_I2 (signed short fixed point decimal)
Low: | –64.0
High: | +63.5

Input

None

Output

Type: | VT_I2 (signed short fixed point decimal)
Measurement: | VIOMEASUREMENT_ROTATION
Units: | VIOUNITS_DEGREES

Remarks

API device objects expect the following data types and sizes when sending data to and from the mini-drivers:

Mini-driver input

None

Mini-driver output

Type: | SHORT *
Size: | 2 bytes
Description: | Ignition advance in 0.1 degree increments

Example

HRESULT hr;
IVIO_Device *pTiming;
VIODEVICEMETRICS dmMetrics;
VARIANT vDeviceData;
float fTiming;
//Create an instance of the ignition timing advance device and get its
//IVIO_Device interface.
hr = CoCreateInstance(CLSID_VIO_TIMING_ADVANCE, NULL,
                     CLSCTX_INPROC_SERVER, IID_VIODEVICE,
                     &pTiming);
//Get the metrics for the ignition timing advance device.
pTiming->get_Metrics(&dmMetrics);
//Ask the device for timing, given in fixed-point form.
pTiming->GetData(&vDeviceData, 3000);
//Get the timing and convert it to a float type.
fTiming = ((float) vDeviceData.iVal) * (10.0 ^ dmMetrics.lExponent);
//Release the reference to the interface.
pTiming->Release();


CLSID_VIO_THROTTLE_POSITION

This CLSID returns the current throttle position as a percentage.

Name

Throttle position

Access

Read, shareable or exclusive

Range

Type: | VT_UI2 (unsigned short fixed point decimal)
Low: | 0.0
High: | 99.2

Input

None

Output

Type: | VT_UI2 (unsigned short fixed point decimal)
Measurement: | VIOMEASUREMENT_PERCENTAGE
Units: | VIOUNITS_PERCENT

Remarks

The actual range of throttle position may not reach the high and low bounds.

API device objects expect the following data types and sizes when sending data to and from the mini-drivers:

Mini-driver input

None

Mini-driver output

Type: | USHORT *
Size: | 2 bytes
Description: | Throttle position in 0.1% increments

Example

HRESULT hr;
IVIO_Device *pThrottlePosition;
VIODEVICEMETRICS dmMetrics;
VARIANT vDeviceData;
USHORT usThrottlePct;
float fThrottlePos, fMultiplier;
//Create an instance of the throttle position device and get its
//IVIO_Device interface.
hr = CoCreateInstance(CLSID_VIO_THROTTLE_POSITION, NULL,
                     CLSCTX_INPROC_SERVER, IID_VIODEVICE,
                     &pThrottlePosition);
//Get the metrics for the throttle position device.
pThrottlePosition->get_Metrics(&dmMetrics);
//From the metrics, get the power of 10 to multiply the data value by.
fMultiplier = 10.0 ^ dmMetrics.lExponent;
//Ask the device for throttle position.
pThrottlePosition->GetData(&vDeviceData, 3000);
//Get the percentage for the fixed-point throttle position.
usThrottlePct = vDeviceData.uiVal;
//Release the reference to the interface.
pThrottlePosition->Release();


CLSID_VIO_INTAKE_TEMP

This CLSID returns the temperature of the air when it arrives in the engine.

Name

Intake air temperature

Access

Read, shareable or exclusive

Range

Type: | VT_I2 (signed short)
Low: | –128
High: | +255

Input

None

Output

Type: | VT_I2 (signed short)
Measurement: | VIOMEASUREMENT_TEMPERATURE
Units: | VIOUNITS_CELSIUS

Remarks

API device objects expect the following data types and sizes when sending data to and from the mini-drivers:

Mini-driver input

None

Mini-driver output

Type: | SHORT *
Size: | 2 bytes
Description: | Intake temperature in degrees Celsius

Example

HRESULT hr;
IVIO_Device *pIntakeTemp;
VARIANT vDeviceData;
SHORT sIntakeTemp;
float fThrottlePos, fMultiplier;
//Create an instance of the intake air temperature device and get its
//IVIO_Device interface.
hr = CoCreateInstance(CLSID_VIO_INTAKE_TEMP, NULL,
                     CLSCTX_INPROC_SERVER, IID_VIODEVICE,
                     &pIntakeTemp);
//Ask the device for intake temperature.
pIntakeTemp->GetData(&vDeviceData, 3000);
//Fetch the intake air temp, in degrees Celsius, from the VARIANT.
sIntakeTemp = vDeviceData.iVal;
//Release the reference to the interface.
pIntakeTemp->Release();


CLSID_VIO_MANIFOLD_AIR_PRESSURE

This CLSID returns the absolute air pressure in the intake manifold.

Name

Manifold air pressure

Access

Read, shareable or exclusive

Range

Type: | VT_UI2 (unsigned short integer)
Low: | 0 = vacuum
High: | 255

Input

None

Output

Type: | VT_UI2 (unsigned short integer)
Measurement: | VIOMEASUREMENT_ABSOLUTEPRESSURE
Units: | VIOUNITS_KILOPASCALSABSOLUTE

Remarks

API device objects expect the following data types and sizes when sending data to and from the mini-drivers:

Mini-driver input

None

Mini-driver output

Type: | SHORT *
Size: | 2 bytes
Description: | Absolute pressure in kilopascals

Example

HRESULT hr;
IVIO_Device *pManifoldPressure;
VARIANT vDeviceData;
USHORT usAbsolutePressure;
const SHORT c_sStdSeaLevelPressure = 101;
SHORT sVacuum;
//Create an instance of the manifold air pressure device and get its
//IVIO_Device interface.
hr = CoCreateInstance(CLSID_VIO_MANIFOLD_AIR_PRESSURE, NULL,
                     CLSCTX_INPROC_SERVER, IID_VIODEVICE,
                     &pManifoldPressure);
//Ask the device for manifold pressure.
pManifoldPressure->GetData(&vDeviceData, 3000);
//Fetch the air pressure, in kilopascals, from the VARIANT.
usAbsolutePressure = vDeviceData.uiVal;
//Calculate the amount of vacuum from standard atmospheric pressure.
sVacuum = (SHORT) usAbsolutePressure - cStdSeaLevelPressure;
//Release the reference to the interface.
pManifoldPressure->Release();


CLSID_VIO_ENGINE_LOAD

This CLSID returns the engine load, which is the current airflow as a percentage of the peak airflow into the engine.

Name

Engine load

Access

Read, shareable or exclusive

Range

Type: | VT_UI2 (unsigned short fixed point decimal)
Low: | 0.0
High: | 99.2

Input

None

Output

Type: | VT_UI2 (unsigned short fixed point decimal)
Measurement: | VIOMEASUREMENT_PERCENTAGE
Units: | VIOUNITS_PERCENT

Remarks

API device objects expect the following data types and sizes when sending data to and from the mini-drivers:

Mini-driver input

None

Mini-driver output

Type: | USHORT *
Size: | 2 bytes
Description: | Engine load in 0.1% increments

Example

HRESULT hr;
IVIO_Device *pEngineLoad;
//Create a notification sink; EngineLoadSink is derived from //IVIO_EventSink.
IVIO_EventSink *iEngineLoadSink = CEngineLoadSink;
//Create an instance of the engine load device and get its
//IVIO_Device interface.
hr = CoCreateInstance(CLSID_VIO_ENGINE_LOAD, NULL,
                     CLSCTX_INPROC_SERVER, IID_VIODEVICE,
                     &pEngineLoad);
//Set the notification sink for the engine load.
pEngineLoad->SetNofify(NULL, iEngineLoadSink, 500);
. . .
//Remove the notification sink.
pEngineLoad->SetNotify(NULL, NULL, 0);
//Release the notification sink.
iEngineLoadSink->Release();
//Release the reference to the interface.
pEngineLoad->Release();


CLSID_VIO_FUEL_PRESSURE

This CLSID returns the fuel pressure relative to the ambient atmospheric pressure.

Name

Fuel pressure

Access

Read, shareable or exclusive

Range

Type: | VT_UI2 (unsigned short integer)
Low: | 0
High: | 765

Input

None

Output

Type: | VT_UI2 (unsigned short integer)
Measurement: | VIOMEASUREMENT_GAGEPRESSURE
Units: | VIOUNITS_KILOPASCALSGAGE

Remarks

API device objects expect the following data types and sizes when sending data to and from the mini-drivers:

Mini-driver input

None

Mini-driver output

Type: | USHORT *
Size: | 2 bytes
Description: | Fuel pressure in kilopascals, relative to ambient atmospheric pressure

Example

HRESULT hr;
IVIO_Device *pFuelPressure;
VARIANT vDeviceData;
USHORT usGagePressure;
//Create an instance of the Fuel Pressure device and get its
//IVIO_Device interface.
hr = CoCreateInstance(CLSID_VIO_FUEL_PRESSURE, NULL,
                     CLSCTX_INPROC_SERVER, IID_VIODEVICE,
                     &pFuelPressure);
//Ask the device for the current fuel pressure.
pFuelPressure->GetData(&vDeviceData, 3000);
//Fetch the fuel pressure, in kilopascals, from the VARIANT.
usGagePressure = vDeviceData.uiVal;
//Release the reference to the interface.
pFuelPressure->Release();


CLSID_VIO_MASS_AIR_FLOW_RATE

This CLSID returns the mass flow rate of air into the engine.

Name

Mass air flow rate

Access

Read, shareable or exclusive

Range

Type: | VT_UI2 (unsigned short fixed point decimal)
Low: | 0.00
High: | 655.35

Input

None

Output

Type: | VT_UI2 (unsigned short fixed point decimal)
Measurement: | VIOMEASUREMENT_FLOWRATE
Units: | VIOUNITS_GRAMSPERSECOND

Remarks

API device objects expect the following data types and sizes when sending data to and from the mini-drivers:

Mini-driver input

None

Mini-driver output

Type: | USHORT *
Size: | 2 bytes
Description: | Air flow rate in 0.01 grams per second increments

Example

HRESULT hr;
IVIO_Device *pAirFlow;
VIODEVICEMETRICS dmAirFlow;
VARIANT vDeviceData;
USHORT usFlowRate;
float fFloatFlowRate;
//Create an instance of the mass air flow rate device and get its
//IVIO_Device interface.
hr = CoCreateInstance(CLSID_VIO_MASS_AIR_FLOW_RATE, NULL,
                     CLSCTX_INPROC_SERVER, IID_VIODEVICE,
                     &pAirFlow);
//Get the metrics for the air flow device.
pAirFlow->get_Metrics(&dmAirFlow);
//Ask the device for the current air flow rate.
pAirFlow->GetData(&vDeviceData, 3000);
//Fetch the air flow rate as a fixed-point value from the VARIANT.
usFloatRate = vDeviceData.uiVal;
//Convert the fixed-point value to a float value.
fFloatFlowRate = ((float) usFloatRate) * (10 ^ dmAirFlow.lExponent);
//Release the reference to the interface.
pAirFlow->Release();


CLSID_VIO_ODOMETER

This CLSID returns an odometer reading.

Name

Odometer

Access

Read, shareable or exclusive

Range

Type: | VT_UI4 (unsigned long)
Low: | 0
High: | 16,777,216 (2^24)

Input

None

Output

Type: | VT_UI4 (unsigned long)
Measurement: | VIOMEASUREMENT_DISTANCE
Units: | VIOUNITS_KILOMETERS

Remarks

This CLSID should be used for taking readings between two points in time. Do not assume it returns total mileage on the vehicle.

API device objects expect the following data types and sizes when sending data to and from the mini-drivers:

Mini-driver input

None

Mini-driver output

Type: | ULONG *
Size: | 4 bytes
Description: | Odometer reading in 1 kilometer increments

Example

HRESULT hr;
IVIO_Device *pOdometer;
//Create an event sink object; iOdometerSink is derived from //IVIO_EventSink.
IVIO_EventSink *iOdometerSink = new COdometerSink;
//Create an instance of the odometer device and get its
//IVIO_Device interface.
hr = CoCreateInstance(CLSID_VIO_ODOMETER, NULL,
                     CLSCTX_INPROC_SERVER, IID_VIODEVICE,
                     &pOdometer);
//Set the notification sink to notify every five seconds.
pOdometer->SetNotify(NULL, iOdometerSink, 5000);
. . .
//Remove the notification sink.
pOdometer->SetNotify(NULL, NULL, 0);
//Release the reference to the interface.
pOdometer->Release();
//Release the event sink object.
iOdometerSink->Release();


CLSID_VIO_TRANSMISSION_GEAR

This CLSID returns the current transmission gear position.

Name

Gear position

Access

Read, shareable or exclusive

Range

Type: VT_UI2 (unsigned short integer enumeration)

The following table shows possible enumerations.

Gears
Value
Description
VIOGEAR_NEUTRAL | 0 | Neutral gear
VIOGEAR_FIRST | 1 | Manual first gear
VIOGEAR_MAX | 253 | Manual highest gear
VIOGEAR_OVERDRIVE | 254 | Manual or generic overdrive
VIOGEAR_REVERSE | 255 | Reverse gear, automatic or manual
VIOGEAR_DRIVE | 256 | Generic drive gear
VIOGEAR_DRIVE_1 | 257 | Same as VIOGEAR_FIRST + 256
VIOGEAR_DRIVE_MAX | 509 | Same as VIOGEAR_MAX + 256
VIOGEAR_DRIVE_OVERDRIVE | 510 | Same as VIOGEAR_OVERDRIVE + 256

Input

None

Output

Type: | VT_UI2 (unsigned short integer enumeration)
Measurement: | VIOMEASUREMENT_ENUM
Units: | VIOUNITS_ENUM

Remarks

API device objects expect the following data types and sizes when sending data to and from the mini-drivers:

Mini-driver input

None

Mini-driver output

Type: | USHORT *
Size: | 2 bytes
Description: | Transmission gear as indicated by one of the VIOGEAR_* values

Example

HRESULT hr;
IVIO_Device *pTransmissionGear;
VARIANT vDeviceData;
USHORT usCurrentGear;
//Create an instance of the gear position device and get its identifier.
//IVIO_Device interface.
hr = CoCreateInstance(CLSID_VIO_TRANSMISSION_GEAR, NULL,
                     CLSCTX_INPROC_SERVER, IID_VIODEVICE,
                     &pTransmissionGear);
//Ask the device for the current gear.
//Remove the notification sink.
pTransmissionGear->GetData(&vDeviceData, 3000);
//Fetch the current gear enumeration from the VARIANT.
usCurrentGear = vDeviceData.uiVal;
//Release the reference to the interface.
pTransmissionGear->Release();


CLSID_VIO_FUEL_SYSTEM_STATUS

This CLSID determines if adjustments are being made to the fuel flow to the cylinders, and why.

Name

Fuel system status

Access

Read, shareable or exclusive

Range

Type: VT_UI4 (array of 4 bytes stored as an unsigned long)

The following table shows possible enumerations.

Fuel system status
Value
Description
VIOFUELSYSTEM_NOT_
PRESENT 		0 Fuel system x not present.
VIOFUELSYSTEM_OPENLOOP_
NOT_READY_YET 		1 The fuel system is not being regulated because the engine sensors are not yet ready.
VIOFUELSYSTEM_OPENLOOP_
DRIVING_CONDITIONS 		2 The fuel system is not being regulated by the engine sensors because of driving conditions — for example, heavy throttle is causing enrichment.
VIOFUELSYSTEM_OPENLOOP_
SYSTEM_FAULT 		3 The fuel system is not being regulated because of a system fault.
VIOFUELSYSTEM_
CLOSEDLOOP_USING_O2S 		4 The fuel system is being regulated by means of input from a oxygen sensor.
VIOFUELSYSTEM_
CLOSEDLOOP_FAULT_FROM_
O2S 		5 The fuel system is being regulated by means of input from a oxygen sensor, but there is a fault in at least one oxygen sensor.

Byte
Status
Byte 0 | Fuel system 1 status
Byte 1 | Fuel system 2 status
Byte 2 | Fuel system 3 status
Byte 3 | Fuel system 4 status

Input

None

Output

Type: | VT_UI4 (array of 4 bytes stored as an unsigned long)
Measurement: | VIOMEASUREMENT_ENUM
Units: | VIOUNITS_ENUM

Remarks

API device objects expect the following data types and sizes when sending data to and from the mini-drivers:

Mini-driver input

None

Mini-driver output

Type: | ULONG *
Size: | 4 bytes
Description: | Array of 4 VIOFUELSYSTEM_* values. Each is represented in 1 byte for each available fuel system.

Example

HRESULT hr;
IVIO_Device *pFuelSystemStatus;
VARIANT vDeviceData;
WORD wStatus_1_2;
BYTE bFuelSystemStatus;
ULONG ulStatusBytes;
//Create an instance of the fuel system status device and get its
//IVIO_Device interface.
hr = CoCreateInstance(CLSID_VIO_FUEL_SYSTEM_STATUS, NULL,
                     CLSCTX_INPROC_SERVER, IID_VIODEVICE,
                     &pFuelSystemStatus);
//Ask the device for the status of the fuel system.
pFuelSystemStatus->GetData(&vDeviceData, 3000);
//Use the HIWORD, LOWORD, HIBYTE, LOBYTE macros because different //processors may have different byte orderings. Get the status of fuel //systems 1 and 2 from the VARIANT.
wStatus_1_2 = LOWORD(vDeviceData.ulVal);
//Get the status of fuel system 1.
bFuel SystemStatus = LOBYTE(wStatus_1_2);
//Release the reference to the interface.
pFuelSystemStatus->Release();


CLSID_VIO_FUEL_TRIM

This CLSID describes the adjustment to the fuel delivery calibration.

Name

Fuel trim

Access

Read, shareable or exclusive

Range

Type: | VT_I4 (signed fixed point)
Low: | –100.0
High: | 99.2

Input

Type: | VT_UI4 (unsigned long)
Low-order word: | VIOFUELTRIM_SHORTTERM = 0, VIOFUELTRIM_LONGTERM = 1
High-order word: | Cylinder bank number (range 0-n).

Output

Type: | VT_I2 (signed fixed point)
Measurement: | VIOMEASUREMENT_PERCENTAGE
Units: | VIOUNITS_PERCENT

Remarks

Long term fuel trim is an adjustment made due to long term changes in engine function. Short term fuel trim is based on instantaneous input from the engine — for example, from the oxygen sensors. The fuel trim is returned as a percentage increase or decrease from the maximum value of fuel being delivered from the nominal rate.

API device objects expect the following data types and sizes when sending data to and from the mini-drivers:

Mini-driver input

Type: | DWORD *
Size: | 4 bytes
Low-order word: | One of the VIOFUELTRIM_* values
High-order word | Cylinder bank number

Mini-driver output

Type: | ULONG *
Size: | 4 bytes
Description: | Percentage of fuel flow adjustment in 0.01% increments

Example

HRESULT hr;
VIODEVICEMETRICS dmFuelTrim;
IVIO_Device *pFuelTrim;
VARIANT vDeviceData;
float fFuelTrimPct;
//Create an instance of the fuel trim device and get its
//IVIO_Device interface.
hr = CoCreateInstance(CLSID_VIO_FUEL_TRIM, NULL,
                     CLSCTX_INPROC_SERVER, IID_VIODEVICE,
                     &pFuelTrim);
//Get the metrics for the fixed-point precision value.
pFuelTrim->get_Metrics(&dmFuelTrim);
//Initialize the VARIANT for the input data.
VariantInit(&vDeviceData);
vDeviceData.vt = VT_UI4;
//For bank 0, set the input data for long term fuel trim.
vDeviceData.ulVal = MAKELONG((WORD) VIOFUELTRIM_LONGTERM, 0);
//Ask the device for the long term fuel trim for bank 0.
pFuelTrim->GetData(&vDeviceData, 3000);
//Convert the fixed-point percentage to a floating point value.
fFuelTrimPct = ((float) vDeviceData.lVal) * (10.0 ^ dmFuelTrim.lExponent);
//Release the reference to the interface.
pFuelTrim->Release();


CLSID_VIO_O2_SENSOR

This CLSID returns the voltage of the oxygen sensors in the vehicle.

Name

Oxygen sensor

Access

Read, shareable or exclusive

Range

Type: | VT_UI4 (unsigned long)
Low: | Low-order word: 0.000, High-order word: Number of supported banks
High: | Low-order word: 4.095, High-order word: Number of sensors per supported bank

Input

Type: | VT_UI4 (unsigned long)
Low-order word: | Sensor number
High-order word: | Cylinder bank number (range 0-n)

Output

Type: | VT_UI2 (unsigned short fixed point decimal)
Measurement: | VIOMEASUREMENT_VOLTAGE
Units: | VIOUNITS_VOLTS

Remarks

The information from this CLSID is used by the engine controller to optimize fuel flow for emissions purposes.

API device objects expect the following data types and sizes when sending data to and from the mini-drivers:

Mini-driver input

Type: | DWORD *
Size: | 4 bytes
Low-order word: | Oxygen sensor number
High-order word: | Cylinder bank number

Mini-driver output

Type: | USHORT *
Size: | 2 bytes
Low-order word: | Oxygen sensor voltage in 0.001 volt increments
High-order word: | Number of supported sensors per bank

Example

HRESULT hr;
VIODEVICEMETRICS dmO2Sensor;
IVIO_Device *pFuelTrim;
VARIANT vDeviceData;
float fO2SensorVoltage;
WORD j, k;
//Create an instance of the oxygen sensor device and get its
//IVIO_Device interface.
hr = CoCreateInstance(CLSID_VIO_O2_SENSOR, NULL,
                     CLSCTX_INPROC_SERVER, IID_VIODEVICE,
                     &pO2Sensor);
for(j = 0; j < HIWORD(dmO2Sensor.vRangeLow.ulVal); j++)
{//Iterate through each bank.
   for(k = 0; k < HIWORD(dmO2Sensor.vRangeLow.ulVal); k++)
      {//Iterate through each sensor in the bank.
      //Initialize the VARIANT for the input value.
      VariantInit(&vDeviceData);
      vDeviceData.vt = VT_UI4;
      //Set input data for the current bank and sensor.
      vDeviceData.ulVal = MAKELONG(k, j);
      //Ask the device for the O2Sensor voltage.
      pO2Sensor->GetData(&vDeviceData, 3000);
      //Convert the fixed-point percentage to a floating point value.
      fO2SensorVoltage = ((float) vDeviceData.usVal) * (10.0 ^
                         dmO2Sensor.lExponent);
      }//End for each sensor
}//End for each bank
//Release the reference to the interface.
pO2Sensor->Release();


CLSID_VIO_DOOR_SWITCHES

This CLSID retrieves the status of door, liftgate, and trunk lid pin switches.

Name

Door switches

Access

Read, shareable or exclusive

Range

Type: VT_UI4 (unsigned long bitmask)

The following table shows possible door switches and their bitmask values. If a specified bit is set to 1, it indicates that the door associated with the switch is open.

Door switch
Bitmask value
VIODOOR_LEFT_FRONT | 0x00000001
VIODOOR_LEFT_REAR | 0x00000002
VIODOOR_LEFT_REAR2 | 0x00000004
VIODOOR_LEFT_REAR3 | 0x00000008
VIODOOR_LEFT_REAR4 | 0x00000010
VIODOOR_LEFT_REAR5 | 0x00000020
VIODOOR_LEFT_REAR6 | 0x00000040
VIODOOR_LEFT_REAR7 | 0x00000080
VIODOOR_RIGHT_FRONT | 0x00000100
VIODOOR_RIGHT_REAR | 0x00000200
VIODOOR_RIGHT_REAR2 | 0x00000400
VIODOOR_RIGHT_REAR3 | 0x00000800
VIODOOR_RIGHT_REAR4 | 0x00001000
VIODOOR_RIGHT_REAR5 | 0x00002000
VIODOOR_RIGHT_REAR6 | 0x00004000
VIODOOR_RIGHT_REAR7 | 0x00008000
VIODOOR_TRUNK | 0x00010000
VIODOOR_LIFTGATE | 0x00020000
VIODOOR_REAR | 0x00040000
VIODOOR_REAR_LEFT | 0x00080000
VIODOOR_REAR_RIGHT | 0x00100000

Input

None

Output

Type: | VT_UI4 (unsigned long bitmask)
Measurement: | VIOMEASUREMENT_DISCRETEMASK
Units: | VIOUNITS_BITMASK

Remarks

API device objects expect the following data types and sizes when sending data to and from the mini-drivers:

Mini-driver input

None

Mini-driver output

Type: | DWORD *
Size: | 4 bytes
Description: | Bitmask that contains the status of door switches, as represented by VIODOOR_* values.

Example

HRESULT hr;
IVIO_Device *pDoorStatus;
VARIANT vDeviceData;
ULONG ulDoorStatus;
//Create an instance of the door status device and get its
//IVIO_Device interface.
hr = CoCreateInstance(CLSID_VIO_DOOR_STATUS, NULL,
                     CLSCTX_INPROC_SERVER, IID_VIODEVICE,
                     &pDoorStatus);
//Ask the device for its current status bits.
pDoorStatus->GetData(&vDeviceData, 1000);
//Fetch the status bits from the VARIANT.
ulDoorStatus = vDeviceData.ulVal;
//Release the reference to the interface.
pDoorStatus->Release();


CLSID_VIO_LATCH_CONTROL

This CLSID releases a latch such as a trunk latch, gas cap, or hood.

Name

Latch control

Access

Write, shareable or exclusive

Range

Type: VT_UI4 (unsigned long enumerated)

The following table shows the available latch controls and values to trigger.

Latch control
Enumeration
VIOLATCH_HOOD | 0x01
VIOLATCH_TRUNK | 0x02
VIOLATCH_GAS_CAP | 0x04

Input

Type: VT_UI4 (unsigned long bitmask)

Output

None

Remarks

For safety reasons, there should be an interlock to prevent the opening of the latches while the vehicle is able to be driven (either the parking brake is off or the ignition switch is on).

API device objects expect the following data types and sizes when sending data to and from the mini-drivers:

Mini-driver input

Type: | DWORD *
Size: | 4 bytes
Description: | Bitmask that contains the VIOLATCH_* values of latches to operate.

Mini-driver output

None

Example

HRESULT hr;
IVIO_Device *pLatchControl;
VARIANT vLatchState;
//Initialize the VARIANT.
VariantInit(&vLatchState);
hr = CoCreateInstance(CLSID_VIO_LATCH_CONTROL, NULL,
                     CLSCTX_INPROC_SERVER, IID_VIODEVICE,
                     &pLatchControl);
//Set the VARIANT to pop the gas cap switch.
vLatchState.vt = VT_UI4;
vLatchState.ulVal = VIOLATCH_GAS_CAP;
//Send the command to the vehicle.
pLatchControl->SetData(&vLatchState, 3000);
//Release the reference to the interface.
pLatchControl->Release();


CLSID_VIO_LOCK_STATE

This CLSID locks and unlocks power locks.

Note This feature is not available on most vehicles initially.

Name

Power lock state

Access

Read or write, shareable or exclusive

Range

Type: VT_UI4 (unsigned long binary value)

The following list provides the lock states and values.

Power lock state
Enumeration
VIOLOCKS_UNLOCKED | 0
VIOLOCKS_LOCKED | 1

Input

Type: | VT_UI4 (unsigned long binary)
Value: | One of the defined VIO_LOCKS_* values

Output

Type: | VT_UI4 (unsigned long binary)
Value: | One of the VIO_LOCKS_* values for current lock status

Remarks

API device objects expect the following data types and sizes when sending data to and from the mini-drivers:

Mini-driver input

Type: | DWORD *
Size: | 4 bytes
Description: | Bitmask that contains the lock state in VIOLOCKS_* form.

Mini-driver output

Type: | DWORD *
Size: | 4 bytes
Description: | Bitmask that contains the requested lock state in VIOLOCKS_* form.

Example

HRESULT hr;
IVIO_Device *pLockState;
VARIANT vLockInfo;
//Initialize the VARIANT.
VariantInit(&vLockInfo);
hr = CoCreateInstance(CLSID_VIO_LOCK_STATE, NULL,
                     CLSCTX_INPROC_SERVER, IID_VIODEVICE,
                     &pLockState);
//Set the VARIANT to lock the doors.
vLockInfo.vt = VT_UI4;
vLockInfo.ulVal = VIOLOCKS_LOCKED;
//Send the command to the vehicle.
pLatchControl->SetData(&vLatchState, 3000);
//Release the reference to the interface.
pLockState->Release();


CLSID_VIO_AUX_LIGHTS

This CLSID returns the status of various lights in the vehicle.

Name

Auxiliary light status

Access

Read, shareable or exclusive

Range

Type: VT_UI4 (unsigned long bitmask)

Bitmask Values

The following table shows possible bitmask values.

Auxiliary light
Bitmask value
Description
VIOLIGHTS_DOME | 0x0001 | Dome lighting
VIOLIGHTS_DASH | 0x0002 | Dash light — on or off only, no analog level
VIOLIGHTS_DRIVING | 0x0004 | Driving lights — separate from headlights
VIOLIGHTS_LEFT_VISOR | 0x0008 | Left visor light
VIOLIGHTS_RIGHT_VISOR | 0x0010 | Right visor light
VIOLIGHTS_LEFT_MAP | 0x0020 | Left map light
VIOLIGHTS_RIGHT_MAP | 0x0040 | Right map light
VIOLIGHTS_LEFT_REAR | 0x0080 | Left rear passenger light
VIOLIGHTS_RIGHT_REAR | 0x0100 | Right rear passenger light
VIOLIGHTS_TRUNK | 0x0200 | Trunk light

Input

None

Output

Type: | VT_UI4 (unsigned long bitmask)
Measurement: | VIOMEASUREMENT_DISCRETEMASK (Bitmask)
Units: | VIOUNITS_BITMASK

Remarks

API device objects expect the following data types and sizes when sending data to and from the mini-drivers:

Mini-driver input

None

Mini-driver output

Type: | DWORD *
Size: | 4 bytes
Description: | Bitmask that contains the state of the vehicle’s lights, in VIOLIGHTS_* values.

Example

HRESULT hr;
IVIO_Device *pLightStatus;
VARIANT vDeviceData;
ULONG ulLightStatus;
//Create an instance of the auxiliary light status device and get its
//IVIO_DEVICE interface.
hr = CoCreateInstance(CLSID_VIO_LIGHT_STATUS, NULL,
                     CLSCTX_INPROC_SERVER, IID_VIODEVICE,
                     &pLightStatus);
//Ask the device for its current status bits.
pLightStatus->GetData(&vDeviceData, 1000);
//Fetch the status bits from the VARIANT
ulLightStatus = vDeviceData.ulVal;
//Release the reference to the interface.
pLightStatus->Release();


CLSID_VIO_DIAGNOSTIC_CODES

This CLSID returns the diagnostic trouble codes generated by the vehicle’s electronic control units.

Name

Trouble codes

Access

Read, shareable or exclusive

Range

Type: VT_UNKNOWN

Input

None

Output

Type: | VT_UNKNOWN (The IUnknown interface to an object that exposes the IVIO_DiagnosticItems interface.)
Measurement: | VIOMEASUREMENT_COLLECTION
Units: | VIOUNITS_DIAGNOSTICITEMS

Remarks

API device objects expect the following data types and sizes when sending data to and from the mini-drivers:

Mini-driver input

None

Mini-driver output

Type: | LPVIODIAGNOSTICARRAY
Size: | Varies
Description: | See the description of the VIODIAGNOSTICITEMSARRAY structure.

Example

HRESULT hr;
IVIO_Device *pTroubleCodeDevice;
VARIANT vTroubleCodes;
IVIO_EnumDiagnosticItems *pTroubleCodes;
IVIO_EnumDiagnosticEntry *pThisCode[1];
IVIO_DataValue *pEntryValues[4];
DWORD j, cValues;
//Initialize the VARIANT.
VariantInit(&vTroubleCodes);
//Create an instance of the trouble code device and get its
//IVIO_DEVICE interface.
hr = CoCreateInstance(CLSID_VIO_TROUBLE_CODES, NULL,
                     CLSCTX_INPROC_SERVER, IID_VIODEVICE,
                     &pTroubleCodeDevice);
//Fetch the trouble codes from the vehicle.
pTroubleCodeDevice->GetData(&vTroubleCodes, 3000);
//Get the IUknown pointer to the collection of returned trouble codes.
if (SUCCEEDED(vTroubleCodes.punkVal->
   QueryInterface(IID_VIOEnumDiagnosticItems, (VOID **)
   &pTroubleCodes)))
{//Got the enumeration interface from the VARIANT.
   do
      {
      //Retrieve the next trouble code from the enumerator.
      hr = pTroubleCode->Next(1, pThisCode, NULL);
      if (SUCCEEDED (hr))
         {//Retrieved the next entry in the collection of returned
         //trouble codes.
         pThisCode->Next(4, pEntryValues, &cValues);
         //Process the values as needed.
         //Then release the data value created in the pThisCode->
         //Next() call.
         for (j = 0; j < cValues; j++)
   pEntryValues[j]->Release();
   //Release the diagnostic entry enumerator.
   pThisCode->Release();
         }//End if (Got the next diagnostic code item from the
         enumerator)
      }
while (hr == S_OK);
//Verify that the enumeration interface is released.
pTroubleCodes->Release();
}//End if (Got the enumeration interface from the VARIANT)
//Free up the resources in the VARIANT returned by GetData().
VariantClear(&vTroubleCodes);
//Release the reference to the interface.
pTroubleCodeDevice->Release();


Text-to-Speech Tags

Passing an ordinary text string to IVoiceText::Speak usually results in a comprehensible rendition of the phrase. However, pronunciation can be enhanced by embedding control tags in the text string. These tags control such factors as emphasis, speech, and pauses between words, resulting in speech that is more lifelike and understandable.

Control tags must have the following syntax:

  • All tags must begin and end with a backward slash (“\”), for example, \pau\.
  • Backslashes are not allowed within a control tag. If a string contains an odd number of backslashes, the result is unpredictable.
  • To add a backslash to the string itself, without having it interpreted as part of a tag, use two consecutive backward slashes (“\\”).
  • Tags are case insensitive. For example, \pau\ is equivalent to \PAU\.
  • White space is not ignored. Therefore, \pau\ is not equivalent to \pa u\.
  • Tags such as Pro that change the operation of the text-to-speech (TTS) engine are persistent from one call to the next. To apply them to a single phrase, the original state must be restored at the end of the phrase.

The engine used by the Auto PC supports the following subset of the Speech API TTS control tags. In the following entries, the tag is indicated by bold type and its options are italicized.

Note Support for control tags is engine-dependent. Different engines may support different sets of tags.


Com

This tag enables an application to embed a comment in the string to be spoken. The TTS engine ignores the embedded comment.

Syntax

\Com=string\

Example

“The following comment \Com=“This is a comment”\ is ignored by the TTS engine.”


Ctx

This tag sets the context for the text that follows. The context determines how symbols are spoken.

Syntax

\Ctx=string\

Parameters

string
This parameter can be one of the following context strings:
“Address”
Used for changing the pronunciation of numbers.
“Normal”
Normal or default speech mode.

Example

\ctx=“Address”\

Remarks

After you use the \ctx=“Address”\ tag to speak the address, add the \ctx=“Normal”\ tag at the end so that you go back to normal default, for example, \ctx=“Address”\106.9\ctx=“Normal”\.


Emp

This tag emphasizes the next word spoken. This tag must immediately precede the word.

Syntax

\Emp\

Example

“The \Emp\truth, the \Emp\whole truth, and nothing \Emp\ but the truth.”


Pau

This tag pauses speech for a specified number of milliseconds.

Syntax

\Pau=pause\

Parameters

pause
Number of milliseconds to pause.

Example

“This TTS sentence \Pau=1000\ pauses for one second.”


Pit

This tag changes the average pitch of the text-to-speech (TTS) voice.

Syntax

\Pit=new_pitch\

Parameters

new_pitch
Specifies the pitch, in hertz.

Example

“\Pit=40\This sentence starts low \Pit=400\ and finishes high.”

Remarks

The actual pitch fluctuates as the string is pronounced, but this tag sets a new average.


Rst

This tag resets all tags to the engine’s default settings.

Syntax

\Rst\


Spd

This tag sets the baseline average talking speed of the TTS output.

Syntax

\Spd=number\

Parameter

number
Specifies the baseline average talking speed, in words per minute.

Example

\Spd=120\

Remarks

The actual rate of speech fluctuates, but this tag changes the average rate.


Vol

This tag sets the average volume of the TTS output.

Syntax

\Vol=number\

Parameters

number
Specifies the baseline speaking volume. In the linear range, 0 is silence and 65,535 is maximum volume.

Example

\Vol=32768\

Remarks

The actual volume fluctuates as the phrase is spoken, but this tag changes the average volume.


Auto PC Speech Recognition Vocabulary

These vocabulary words are recognized by the speech recognition engine. In most cases, the vocabulary directly maps to the name of the command started when the word or words is said aloud. For example, a user says, “Cancel” to choose the Cancel command.

The result of the vocabulary word or phrase depends on the currently active grammar, as shown in the following tables.

Note Many of the words—but not all—in the global grammar are used in bundled applications. Because the complete global grammar is installed in Auto PC device ROM, you have a wider variety of words to include in your applications, but do not have to train the engine to recognize a word.

Auto PC Vocabulary

Word or phrase
Action
A through Z | Select characters.
Address Book | Go to Address Book.
AM | Change radio frequency band to AM.
Audio | Go to Audio..
Auto PC | Wake up Auto PC speech recognition.
Back | Go up one level.
Cancel | Cancel current action.
CD Player | Go to CD Player.
Clock | Display the clock.
Delete | Delete an item.
Dial | Dial the phone.
Directions | Go to Directions.
Disc | Select the next disc.
E-mail | Go to e-mail list in Messages.
End | Terminates the speech recognition timer.
FM | Set the radio frequency band to FM.
Go | Initiates the calculation of a route. Used in Directions.
Help | List help for words the Auto PC device is listening for.
List | Read a list.
Locate | Instructs balloon grammar to listen for user-defined voice tags and custom commands.
Loud | After “Volume,” set audio volume to Loud preset.
Messages | Go to Messages.
Mute | Mute the audio output.
News | Go to news list in Messages.
Next | Go to the next item in a list, or the next turn in Directions.
No | Select the “No” option in a system message box.
Normal | After “Volume,” set audio volume to Normal preset.
OK | Select the “OK” option in a system message box.
Pause | Pause CD playback.
Play | Start CD playback.
Preset (followed by a number or custom speech command) | Go to the preset value associated with a number key or custom speech command (such as a radio station preset)..
Previous | Go to the previous item in a list, or the previous turn in Directions.
Quiet | After “Volume,” set audio volume to Quiet preset.
Radio | Go to Radio.
Random | Play CD tracks in random order.
Read | Read an item.
Retry | Try an action again. Used with a system message box.
Select | Choose an item.
Setup | Go to Setup.
Start | Reserved for future versions. Do not use.
Traffic | Go to traffic list in Messages.
Volume | Specify audio volume preset. Used with “Loud,” “Normal,” and “Quiet.”
What can I say? | Read a list of the words Auto PC is listening for.
What time is it? | Read the current time.
Yes | Select the “Yes” option in a system message box.

Radio Grammar

Word or phrase
Action
0 through 9 | After “Preset,” go to a numbered preset.
AM or FM | Change the radio frequency band.
Next or Previous | Seek for a radio station.
Preset (followed by a number or custom speech command) | Go to the preset value associated with a number key or custom speech command (such as a radio station preset)..
Read | Read the station number and frequency.

CD Player Grammar

Word or phrase
Action
Delete | Remove the current song from the play list.
Disc | Go to a different disc.
Next or Previous | Go to a different track.
Play or Pause | Start or stop playing.
Random | Play tracks in random order.
Read | Read the disc and track number.
Stop | Stop playing.

Address Book Grammar

Word or phrase
Action
Back | Go up one level.
Dial | Call the selected number, or the preferred number for the selected contact.
Locate (and the custom speech command) | Instructs balloon grammar to listen for user-defined voice tags and custom commands.
List | Read the contact list.
Next or Previous | Go to a different contact.
Select | Choose a contact.
Read | Read contact information.

Directions Grammar

Word or phrase
Action
Go | Initiates the calculation of a route.
List | List all remaining turns.
Next or Previous | Go to a different turn.
Read | Read the current turn.

Messages Grammar

Word or phrase
Action
Back | Return to the message list.
Delete | Delete the current message.
E-mail | Go to e-mail.
List | List messages.
News | Go to news.
Next or Previous | Go to a different message.
Read | Reads the message information, including the sender of the message, the date that the message was sent, and the subject of the message.
Select | Open the selected message and reads the content of the message.
Traffic | Go to traffic.


Constraint-Based Layout and FA_* Values

For many applications, you must create a resource file and use resource type definitions to specify such elements as controls, menus, and string tables. Typically, you specify the coordinates for the dimensions and placement of a control or other resource. In addition to this method, Auto PC provides a constraint-based layout for use with controls and dialog boxes. With constraint-based layout, you only have to specify a predefined FA_* value. The Auto PC uses this value to supply the coordinates based on the control’s relationship to either the parent form or another control. The result is a flexible alternative to specifically defining the size and location of a resource.

To use constraints

  1. Specify the constraints in a resource file, and use the IfmManage::LoadFormResource interface to load the file.

    Note If you are defining a dialog box, use the DIALOGEX resource type.

  2. Create and start your form before calling LoadFormResource, so the layout engine can get a device context (DC) for the display device.


FA_* Values

The following table shows the FA_* values and how each affects alignment of controls.

Value
Description
FA_BOTTOM | Specifies that the bottom edge of the control is located at the bottom of a form.
FA_BOTTOM_CONTROL | Aligns the bottom edge of one control with the bottom edge of another control.
FA_BOTTOM_CONTROL_FRACTION | Specifies the bottom edge of a control as a percentage of the vertical bounds of another control. Use an integer to express the percentage.
FA_BOTTOM_FRACTION | Specifies the bottom edge of a control as a percentage of the bottom of its parent form. Use an integer to express the percentage.
FA_BOTTOM_OF_FORM | Aligns the bottom edge of a control with the bottom of the form.
FA_BOTTOM_OFFSET | Specifies a signed offset value to add to the bottom edge of a control.
FA_BOTTOM_TO_TOP_OF_CONTROL | Aligns the bottom edge of one control with the top edge of another control.
FA_HEIGHT_OF_CONTROL | Makes the height of one control the same as the height of another control.
FA_HORIZONTAL_CENTER | Horizontally centers a control within a form.
FA_HORIZONTAL_CENTER_OF_
CONTROL 		Specifies the horizontal center of a control on a form
FA_HORIZONTAL_OFFSET | Moves a control horizontally by a specified number of pixels.
FA_LEFT_CONTROL | Aligns one control with the left edge of another control.
FA_LEFT_CONTROL_FRACTION | Specifies one dimension of a control as a percentage of the left of another control. Use an integer to express the percentage.
FA_LEFT_FRACTION | Specifies one dimension of a control as a percentage of the left side of its parent form. Use an integer to express the percentage.
FA_LEFT_OF_FORM | Aligns the left edge of a control with the left of the form.
FA_LEFT_OFFSET | Specifies, in pixels, the amount of space to place between the left edge of a control and the edges of its parent or another control.
FA_LEFT_TO_RIGHT_OF_CONTROL | Aligns the left edge of one control with the right edge of another control.
FA_RIGHT | Specifies the horizontal position of the right edge of the control.
FA_RIGHT_CONTROL | Aligns one control with the right edge of another control.
FA_RIGHT_CONTROL_FRACTION | Specifies one dimension of a control as a percentage of the right of another control. Use an integer to express the percentage.
FA_RIGHT_FRACTION | Specifies one dimension of a control as a percentage of the right of its parent form. Use an integer to express the percentage.
FA_RIGHT_OF_FORM | Aligns the right edge of a control with the right of the form.
FA_RIGHT_OFFSET | Specifies, in pixels, the amount of space to place between the right edge of a control and the edges of its parent or another control.
FA_RIGHT_TO_LEFT_OF_CONTROL | Aligns the right edge of one control with the left edge of another control.
FA_TOP_CONTROL | Aligns one control with the top edge of another control.
FA_TOP_CONTROL_FRACTION | Specifies one dimension of a control as a percentage of the top of another control. Use an integer to express the percentage.
FA_TOP_FRACTION | Specifies one dimension of a control as a percentage of the top of its parent form. Use an integer to express the percentage.
FA_TOP_OF_CAPTION | Specifies the location of the top of the title bar.
FA_TOP_OF_FORM | Aligns the top edge of a control with the top of the form.
FA_TOP_OFFSET | Specifies, in pixels, the amount of space to place between the top of a control and the edges of its parent or another control.
FA_TOP_TO_BOTTOM_OF_CONTROL | Aligns the top edge of one control with the bottom edge of another control.
FA_VERTICAL_CENTER | Vertically centers a control within a form.
FA_VERTICAL_CENTER_OF_
CONTROL 		Specifies the exact vertical location of a control on a form
FA_VERTICAL_OFFSET | Moves a control vertically by a specified number of pixels.
FA_WIDTH_OF_CONTROL | Makes the width of one control the same as the width of another control.
ASFC_DISPID_AUTOSCALEFONT | Adjusts fonts to fit the control. If set, the font size is reduced to allow the text to fit in the control.


Control Properties

In addition to specifying location and size of controls in a resource file, you can also specify control properties. The following table shows the control properties you can specify in a resource script.

Value
Description
ASFC_DISPID_AUTOSCALEFONT | Adjusts fonts to fit the control. The value following this property specifies the minimal size allowed when reducing the font size.
ASFC_DISPID_BACKCOLOR | Sets the background color. The value following this property is a DWORD that stores the RGB color and sets the background color. Use standard RGB values.
ASFC_DISPID_FONT | Sets the font.
ASFC_DISPID_FORECOLOR | Sets the foreground color. The value following this property is a DWORD that stores the RGB color and sets the foreground color. Use standard RGB values.


Code Examples

The following code examples show you how write constraint-based layout resource scripts using FA_* values.


Specifying a Label Control

The following code example shows how to specify the placement and size of a label control.

IDF_MAIN DIALOGEX DISCARDABLE  0, 0, 0, 0   // Full display
CAPTION "My Form"
STYLE  WS_VISIBLE
BEGIN
   // Because they are specified by constraints, the position and
   // dimensions in the CONTROL statement are left as zero.

   CONTROL     "Hello", IDC_CTRL,"APC_Label",ASFC_ALIGN_LEFT,
               0,0,0,0
   BEGIN
      // Use the following constraints.
      FA_TOP_OF_FORM,      // Aligns the top edge of the control with
                           // the top edge of the form.
      FA_LEFT_OF_FORM,     // Aligns the left edge of the control with
                           // the left edge of the form.
      FA_RIGHT_OF_FORM,    // Aligns the right edge of the control with
                           // right of the form.
      FA_BOTTOM_OF_FORM    // Aligns the bottom  edge of the control
                           // with the bottom edge of the form.
   END
END

The constraints in this example define a label control that fills the form. For forms with title bars, the top of the form is directly under the title bar. If not enough constraints are specified so that each edge can be determined, the natural size of the control is considered. The natural size of a control typically consists of the dimensions a control would need to display its contents. For example, the natural size of a label control with a ASFC_ALIGN_SINGLELINE format is the width required to display the control’s full caption.

When using a control that does not have a natural size — for example, a multiline control — you must provide the constraints necessary to determine all the edges.

The following code example shows how to specify a label control using natural size.

   CONTROL         "Hello",
   IDC_CTRL,"APC_Label",ASFC_ALIGN_LEFT|ASFC_ALIGN_SINGLELINE,  0,0,0,0
   BEGIN
      // Use the following constraints.
      FA_TOP_OF_FORM,      // Align the top edge of the control with the
                           // top edge of the form.
      FA_LEFT_OF_FORM,     // Align the left edge of the control with
                           // the left edge of the form.
   END

In this example, the control’s natural size is used to specify the dimensions of the control. The net effect is that a label control is created in the upper-left corner of the form and is just large enough to display its caption, “Hello.” It is important to realize that constraints are applied at the time you call LoadFormResource and not each time a control position or caption is changed. If your application has to change the caption at runtime, add another constraint, such as FA_RIGHT_OF_FORM.

In addition to label controls, glyph, tabber and edit controls also support natural sizes. Tabber and edit controls are subject to the following rules:

  • The natural width of the tabber is the sum of the widths of its tabs.
  • The natural height of the tabber is the font height or maximum bitmap height of the tabs.
  • The natural width of the edit control is the width of the spinner item multiplied by the maximum visible characters.
  • The natural height of the edit control is the height of the spin box.

For more information about controls, see “Using Auto PC Simple Controls.”


Centering a Control

The following code example shows how to use constraints to center a control.

   CONTROL         "I’m Centered"
   IDC_CTRL,"APC_Label",ASFC_ALIGN_LEFT|ASFC_ALIGN_SINGLELINE,  0,0,0,0
   BEGIN
      // Use the following constraints.
      FA_HORIZONTAL_CENTER, FA_VERTICAL_CENTER
   END


Aligning the Edges of Controls

The following two code examples show how to use constraints to match the edge of one control to that of another. You specify the second control by its identifier. The second code example shows how to display a status line, for example, “Elapsed: 01:14:23”, consisting of two labels that use different fonts and colors.

   CONTROL "A", IDC_CTRL_A,...

   CONTROL         "Same Top As A",
   IDC_CTRL_B,"APC_Label",ASFC_ALIGN_LEFT|ASFC_ALIGN_SINGLELINE,
   0,0,0,0
   BEGIN
      // Use the following constraints to center control B
      // horizontally, with the same vertical position as control A.
      FA_HORIZONTAL_CENTER, FA_TOP_CONTROL,  IDC_CTRL_A
   END

   CONTROL "Elapsed:", IDC_CTRL_ELAPSED,"APC_Label",
      ASFC_ALIGN_LEFT|ASFC_ALIGN_SINGLELINE
   BEGIN
      FA_LEFT_OF_FORM, FA_HORIZONTAL_CENTER
      // Set the font of the control.
      ASFC_DISPID_FONT, L"Tahoma-Bold-18\0"
   END
   CONTROL         "",
   IDC_CTRL_TIME,"APC_Label",ASFC_ALIGN_LEFT|ASFC_ALIGN_SINGLELINE,
   0,0,0,0
   BEGIN
      FA_LEFT_TO_RIGHT_OF_CONTROL, IDC_CTRL_ELAPSED
   END

// The labels are aligned by setting the left edge of the
// IDC_CTRL_TIME label to the right edge of the IDC_CTRL_ELAPSED label.


Using Form Dimensions

Because display sizes differ, it is often useful to specify a position as a percentage of the dimensions of the form, as shown in the following code example.

   CONTROL "Hello", IDC_CTRL_HELLO,"APC_Label:",
   ASFC_ALIGN_LEFT|ASFC_ALIGN_SINGLELINE
   BEGIN
      FA_LEFT_OF_FORM,
      FA_RIGHT_FRACTION, 50   // Places the right edge of the control
                              // in the middle of the form.
      ...
   END


Using Offsets

After specifying constraints for the various edges, you can add or subtract pixels, for example, to leave space between two labels. The following code example shows how to use one of the offset values followed by an integer to specify the number of pixels to offset the edge.

   CONTROL "Hello", IDC_CTRL_HELLO,"APC_Label:",
      ASFC_ALIGN_LEFT|ASFC_ALIGN_SINGLELINE
   BEGIN
      ...
      FA_LEFT_OFFSET, 2   // Offset the left edge by two pixels.
      FA_RIGHT_OFFSET, 2  // Offset the right edge by two pixels.
   END

Note You could also use FA_HORIZONTAL_OFFSET, 2.


Using Constraints with the Navigational Arrows Control

You can use constraints to position the navigational arrows control, which is a control that indicates the active direction keys. For more information about the navigational arrows control, see “Using Auto PC Simple Controls.”

To position the navigational arrows control, use a CONTROL statement with a control class of “APC_NavArrows.” This process does not actually create a navigational arrows control, but binds the control to the existing one created by the form. The following code example shows how to hide the navigational arrows control if it is not needed on a form.

   CONTROL     "Nav Arrows", IDC_NAVARROWS,"APC_NavArrows",NOT
               WS_VISIBLE,
               0,0,0,0

The following code example shows how to center a navigational arrows control vertically at the right of the form.

   CONTROL     "Nav Arrows", IDC_NAVARROWS,"APC_NavArrows",
               WS_VISIBLE,
               0,0,0,0
   BEGIN
      FA_VERTICAL_CENTER, FA_RIGHT_OF_FORM
   END

Even though only two constraints were specified, the layout engine can position the control because uses it the natural size of the navigational arrows control in determining how to position it.


Specifying Control Properties

In addition to specifying constraints, you can also specify control properties using dispatch identifiers — for example, the ASFC_DISPD_FONT property, followed by a Unicode string.

Note Explicitly terminate all strings.

The following code example shows how to specify the font property of a control.

   CONTROL "Elapsed:", IDC_CTRL_ELAPSED,"APC_Label:",
         ASFC_ALIGN_LEFT|ASFC_ALIGN_SINGLELINE
   BEGIN
      FA_LEFT_OF_FORM, FA_HORIZONTAL_CENTER
      // Set the font of the control.
      ASFC_DISPID_FONT, L"Tahoma-Bold-18\0"
   CONTROL         "",
      IDC_CTRL_TIME,"APC_Label",ASFC_ALIGN_LEFT|ASFC_ALIGN_SINGLELINE,
      0,0,0,0
   BEGIN
      FA_LEFT_TO_RIGHT_OF_CONTROL, IDC_CTRL_ENABLED
   END

Properties are applied before constraints, so in the code example, the label is sized correctly because the font size is specified before the constraints.

Also notice in the code example, the leading “L” indicates a Unicode string — as in C++ — and the explicit terminator. The format of the font string “Tahoma-Bold-18\0” is the font name “Tahoma,” followed by one or more modifiers, each of which begins with a hyphen. The following table shows valid modifiers.

Modifier
Description
Bold | Indicates bold text.
Italic | Indicates italic text.
Underline | Indicates underline text.
Strikethrough | Indicates strikethrough text.
Point size | Sets the size of the text.

Note You can specify modifiers in any order, for example, “Tahoma-Bold-18” or “Tahoma-18-Bold.”


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

Reason | Remedy
Destination topic not in the selected active subset. | Set active subset to an appropriate subset or to (Entire Collection).
Link is out-of-date. | Use the index or search function instead.
Link was authored incorrectly. | Use the index or search function instead.
Problems with the MSDN installation. | Uninstall the MSDN Library and then rerun Setup.

See MSDN Library Help for more information on subsets, search, the index, and installation.