New System Functions


This section contains information about the following new system functions supported by user.exe, user32.dll, oleacc.dll, and GDI.

User.exe and user32.dll now expose the following new functions.

The oleacc.dll library provides several helper functions that allow clients to discover Active Accessibility objects based on screen coordinates or window handles. Other functions facilitate communication with objects and marshaling across process boundaries. Oleacc.dll now supports the following new functions.

The core Windows 95 components gdi32.dll and gdi.exe have been modified to provide DDI redirection through the following new functions.

AccessibleChildren

STDAPI AccessibleChildren (IAccessible* paccContainer,
    LONG iChildStart, LONG cChildren, VARIANT* rgvarChildren,
    LONG* pcObtained);

Retrieves the child ID or IDispatch interface for a range of child objects within an accessible container object.

paccContainer
Address of the container object's IAccessible interface.
iChildStart
Value specifying the zero-based index of the first child to be retrieved.
cChildren
Count of how many children to retrieve. An application can call the IAccessible::get_accChildCount method to retrieve the current count.
rgvarChildren
Base address of an array of VARIANT structures to be filled by the function. If the vt member of an element is VT_I4, then the lVal member for that element is the child object's ID. If vt is VT_DISPATCH, then the pdispVal member is the address of the child object's IDispatch interface. The vt member can also be a string if the object supports returning strings as child identifiers.
pcObtained
Address of a variable that will contain a value indicating the number of array elements filled.

The second parameter passed to this function is an index, not a child ID.

The caller must call the Release method for any IDispatch interfaces retrieved by this function and free the array when it is no longer needed.

See also VARIANT Structure, IDispatch Interface

AccessibleObjectFromEvent

STDAPI AccessibleObjectFromEvent(HWND hwnd,
    DWORD dwId, DWORD dwChildId, IAccessible** ppacc,
    VARIANT* pvarChild);

Retrieves the address of the IAccessible interface for an object that generated a given event.

hwnd
Handle to the window that generated the event.
dwId
Object ID. This value can be one of the standard object identifier constants or a custom object ID.
dwChildId
ID of the child element that triggered the event, or CHILDID_SELF if the object itself triggered the event.
ppacc
Address of a variable that will contain the address of the child object's IAccessible interface if the child is an accessible object. If not, this is the address of the IAccessible interface of the child's parent object. See the description for the pvarChild parameter for information about which interface is returned.
pvarChild
Address of a VARIANT structure that will contain information describing the call's result. The vt member will always be set to VT_I4. If the lVal member is set to zero, then the IAccessible interface pointer at ppacc belongs to the child object specified in dwChildId. Otherwise, ppacc is the address of the IAccessible interface of the child's parent object.

Clients call this function to retrieve a specific child object that generated an event. The client uses the parameters sent to its WinEventProc callback function to fill this function's parameters.

This function retrieves the lowest-level accessible object that is associated with an event. If the child that generated the event is not an accessible object (that is, does not support IAccessible), then the function returns that child's parent. The parent is assumed to support the functionality extended by the IAccessible interface on the child's behalf.

This function increases an object's reference count, and must have a corresponding call to Release. Even though an object has a reference count greater than zero, that object can still be destroyed, and clients are not guaranteed that getting properties from or calling methods on an object will succeed. This is what Microsoft® Word does with its objects when it shuts down: As with standard OLE Automation objects, Word will quit and CoDisconnect the object so that if anyone tries to access it cross-process after the quit, OLE will return an error. A reference count on a OLE Automation object does not affect the reference count in the application.

See also AccessibleObjectFromPoint, AccessibleObjectFromWindow, WinEventProc, VARIANT Structure

AccessibleObjectFromPoint

STDAPI AccessibleObjectFromPoint(
    POINT ptScreen, IAccessible** ppacc, VARIANT* pvarChild);

Retrieves the address of the IAccessible interface accessible object at a specified point on the screen.

ptScreen
Win32 POINT structure describing the point to be examined, in screen coordinates.
ppacc
Address of a variable that will contain the address of the object's IAccessible interface.
pvarChild
Address of a VARIANT structure that will contain information describing the call's result. The vt member is always VT_I4. If the lVal member is set to zero, then the IAccessible interface pointer at ppacc belongs to the child object at the specified point. Otherwise, ppacc is the address of the IAccessible interface of the child's parent object.

This function retrieves the lowest-level accessible object at a given point. If the child at the point is not an accessible object (that is, does not support IAccessible), then the function returns that child's parent. The parent is assumed to support the functionality extended by the IAccessible interface on the child's behalf.

This function increases an object's reference count, and must have a corresponding Release. Even though an object has a reference count greater than zero, that object can still be destroyed, and clients are not guaranteed that getting properties from or calling methods on an object will succeed. This is what Word does with its objects when it shuts down: As with a standard OLE Automation object, Word will quit and CoDisconnect the object so that if anyone tries to access it cross-process after the quit, OLE will return an error. A reference count on a OLE Automation object does not affect the reference count in the application.

See also AccessibleObjectFromEvent, AccessibleObjectFromWindow, WinEventProc, VARIANT Structure

AccessibleObjectFromWindow

STDAPI AccessibleObjectFromWindow(HWND hwnd, DWORD dwId,
    REFIID riid, void **ppvObject);

Retrieves the address of a specified interface for a given object.

hwnd
Handle to the window whose object interface pointer will be retrieved, or NULL to retrieve information about the mouse pointer (cursor).
dwId
Object ID. This value can be one of the standard object identifier constants or a custom object ID.
riid
Reference identifier of the interface being requested. If the requested interface is not supported, the call will fail and the function will return E_NOINTERFACE.
ppvObject
Address of a variable that will contain the address of the specified interface if the call succeeds.

Clients can call this function to retrieve addresses of an object's IAccessible, IDispatch, IEnumVARIANT, IUnknown, or other supported interface. If the requested interface is not supported, the function returns E_NOINTERFACE.

In some cases, this function might create and return a pseudo-object as a wrapper for windows that do not provide accessible objects themselves.

This function increases an object's reference count, and must have a corresponding Release. Even though an object has a reference count greater than zero, that object can still be destroyed, and clients are not guaranteed that getting properties from or calling methods on an object will succeed. This is what Word does with its objects when it shuts down: As with a standard OLE Automation object, Word will quit and CoDisconnect the object so that if anyone tries to access it cross-process after the quit, OLE will return an error. A reference count on a OLE Automation object does not affect the reference count of the application.

See also AccessibleObjectFromEvent, AccessibleObjectFromPoint, WinEventProc, IDispatch Interface

BlockInput

BOOL BlockInput(BOOL fBlock);

Blocks keyboard and mouse events from reaching the raw input thread, and therefore from all applications.

fBlock
Flag value specifying the call's purpose. If this value is TRUE, hardware input events are blocked until the function is called again by the same thread with a FALSE parameter.

This function will not interfere with the asynchronous keyboard input state table. This means that calls to the SendInput function while input is blocked will change the asynchronous keyboard input state table.

There are three situations where blocked input will become unblocked:

  1. The thread that blocked input unexpectedly exits without calling BlockInput with fBlock set to FALSE. In this case USER cleans up properly and re-enables input.
  2. The system displays the Close Program/Fault dialog box. This can occur if the thread faults or if the user presses CTRL+ALT+DELETE.
  3. The system invokes the Hard System Error modal message box.

In all cases, USER must unblock software-blocked input. Since system-critical dialog boxes are system modal, in the latter case, the thread owning the block will not resume execution until the user closes the dialog box.

CallNextDDI

WINDDIAPI DWORD WINAPI CallNextDDI(HDDI hddi,
    DDITYPE ddiType, LPDDIPARAMS lpDdiParams);

Calls the next display device interface (DDI) hook process.

hddi
Handle to the current DDI hook as received in the hddi parameter of the DDIHookProc callback function.
ddiType
DDI hook type identifier as received in the ddiType parameter of the DDIHookProc callback function.
lpDdiParams
Address of the function stack structure for this DDI function as received in the lpDdiParams parameter of the DDIHookProc callback function.

An application calls this function in the body of a DDI hook callback function to pass control on to the next DDI hook callback function, if any. If this callback procedure modified any stack structure members prior to calling CallNextDDI, the new values will remain changed for the next callback function. If the callback procedure doesn't call this function, then the DDI function halts, never reaching the display.

CreateStdAccessibleObject

STDAPI CreateStdAccessibleObject(HWND hwnd, LONG idObject,
    REFIID riidInterface, void **ppvObject);

Creates a default implementation of an accessible object for a given standard object.

hwnd
Handle to the window containing the object specified by the idObject parameter.
idObject
Object ID. This value must be one of the object identifier constants.
riidInterface
Reference identifier of the interface being requested. If the requested interface is not supported, the call will fail and the function will return E_NOINTERFACE.
ppvObject
Address of a variable that will contain the address of the specified interface if the call succeeds.

This function is used only by server applications, not clients.

All standard objects support the IAccessible, IDispatch, IEnumVARIANT and IUnknown interfaces.

See also IDispatch Interface

GetGUIThreadInfo

BOOL WINAPI GetGUIThreadInfo(DWORD idThread,
    LPGUITHREADINFO lpgui);

Retrieves information about the active window or a specified graphical user interface (GUI) thread.

idThread
Value identifying the thread for which information is being retrieved. An application can retrieve this value by calling the GetWindowThreadProcessId Win32 function. Or, if you specify NULL for this parameter, the function returns information for the foreground thread.
lpgui
Address of a GUITHREADINFO structure that will contain information describing the thread. Before making the call, the cbSize member must be initialized in the program to the size of the GUITHREADINFO structure, in bytes.

This function succeeds even if the active window is not owned by the caller's process. If the specified thread does not exist or have an input queue, the function will fail.

This function is useful for retrieving out-of-context information about a thread. The information retrieved is the same as if an application retrieved the information for itself using the Win32 functions GetFocus, GetCapture, and so on.

GetRoleText

UINT GetRoleText(DWORD dwRole,
    LPTSTR lpszRole, UINT cchRoleMax);

Retrieves the localized string based on a specified standard role value.

dwRole
Object role value for which the appropriate string will be retrieved. This value must be one of the object role constants.
lpszRole
Address of a buffer that will contain the role text string. If this parameter is NULL, the function retrieves the role string's length, not including the null character.
cchRoleMax
Size of the buffer at the address specified by lpszRole. For ANSI strings, this value is measured in bytes. For Unicode strings, this value is measured in characters.

If the lpszRole parameter is not a valid pointer, the function returns zero and sets an ERROR_INVALID_PARAMETER error value. Applications can retrieve this error value with the GetLastError Win32 function.

Calling this function with lpszRole set to NULL is analogous to querying for the length of the role text string. You can use the return value from such a call to dynamically allocate the memory needed to hold the string. The following code fragment illustrates this concept.

UINT   iRoleLength;
LPTSTR lpszRoleString;

// Find out how long the role text string is.
iRoleLength = GetRoleText(ROLE_SYSTEM_MENUITEM, NULL, 0);

// Allocate memory for the string. Add one byte to
// length we got in the previous call to make room
// for the null character.
lpszRoleString = GlobalAllocPtr(GMEM_FIXED, iRoleLength+1);

// Get the string.
GetRoleText(ROLE_SYSTEM_MENUITEM, 
            lpszRoleString, iRoleLength +1);

GetStateText

UINT GetStateText(DWORD dwStateBit,
    LPTSTR lpszStateBit, UINT cchStateBitMax);

Retrieves the localized standard adjective string for a single standard state bit.

dwStateBit
Object state value for which the appropriate state text will be retrieved. This value must be only one of the object state constants.
lpszStateBit
Address of a buffer that will contain the state text string. If this parameter is NULL, the function retrieves the role string's length, not including the null character.
cchStateBitMax
Size of the buffer at the address specified by the lpszStateBit parameter. For ANSI strings, this value is measured in bytes. For Unicode strings, this value is measured in characters.

This function accepts only one bit at a time, not a bitmask.

If the lpszRole parameter is not a valid pointer, the function returns zero and sets an ERROR_INVALID_PARAMETER error value. Applications can retrieve this error value with the GetLastError Win32 function.

Calling this function with lpszStateBit set to NULL is analogous to querying for the length of the state text string. You can use the return value from such a call to dynamically allocate the memory needed to hold the string. The following code fragment illustrates this concept.

UINT   iLength;
LPTSTR lpszString;

// Find out how long the string is.
iLength = GetStateText(STATE_SYSTEM_FOCUSED, NULL, 0);

// Allocate memory for the string. Add one byte to
// length we got in the previous call to make room
// for the null character.
lpszString = GlobalAllocPtr(GMEM_FIXED, iLength + 1);

// Get the string.
GetStateText(STATE_SYSTEM_FOCUSED, lpszString, iLength + 1);

GetWindowModuleFileName

UINT WINAPI GetWindowModuleFileName(HWND hwnd,
    LPTSTR lpszFileName, UINT cchFileNameMax)

Retrieves the full path and file name of the module associated with the given window handle.

hwnd
Handle to the window whose module file name will be retrieved.
lpszFileName
Address of a string variable that will contain the executable file's path and file name.
cchFileNameMax
Value specifying the maximum number of characters to copy into the buffer at lpszFileName.

LresultFromObject

LRESULT LresultFromObject(REFIID riid, WPARAM wParam,
    LPUNKNOWN punk);

Generates a reference to an accessible object, in the form of an LRESULT value.

riid
Reference identifier of the interface that USER will provide to the client.
wParam
Value as provided in the wParam parameter received with the associated WM_GETOBJECT message.
punk
Address of the IUnknown interface for the object whose reference is being generated.

Active Accessibility server applications use this function to retrieve a return value while processing the WM_GETOBJECT message. This function is called only by Active Accessibility server applications, not clients.

The riid parameter identifies the interface that will be provided and allows oleacc.dll to optimize marshaling between the client and the server. That is, if a given interface has already been provided for an object, oleacc.dll will optimize the process by using the existing interface rather than creating another one in shared memory.

A value returned from LresultFromObject can be passed to ObjectFromLresult only once; if it is passed subsequent times the error result will be returned from this function.

Since this function creates a weak reference (MSHLFLAGS_TABLEWEAK) to an object, the object's table is not affected.

NotifyWinEvent

void WINAPI NotifyWinEvent(DWORD event, HWND hwnd,
    LONG idObject, LONG idChild);

Signals the system and accessibility aids that a predefined event occurred.

event
Value specifying the event that occurred. This value must be one of the event constants defined in the winable.h header file.
hwnd
Handle to the window generating the event.
idObject
Value identifying the object that generated the event. This value can be one of the predefined object constants or a custom object ID value.
idChild
Value identifying the child of the object specified in idObject that is generating the event. This value is CHILDID_SELF if the object itself is generating the event.

An Active Accessibility server application calls this method to notify the system and accessibility aids that a predefined event occurred within the application. This allows accessibility aids to communicate directly with the server object using IAccessible interface methods.

There is no significant performance penalty for calling this function when no clients of the events are present. The system does not perform any thunking for context switches. Server application developers can call this method with their own events without fear of overhead.

ObjectFromLresult

STDAPI ObjectFromLresult(LRESULT lResult, REFIID riid,
    WPARAM wParam, void** ppvObject);

Retrieves a requested interface pointer for an accessible object based on a previously generated object reference.

Note: Active Accessibility servers or clients can't use this function. Only oleacc.dll can use this function, which is documented only for informational purposes.

lResult
A 32-bit value returned by a previous successful call to the LresultFromObject function.
riid
Reference identifier of the interface to be retrieved.
wParam
Additional information as provided in the associated wParam parameter of the WM_GETOBJECT message.
ppvObject
Location, in screen coordinates, of the interface pointer to return.

Returns an interface pointer to an object given a 32-bit LRESULT value returned by a previous call to LresultFromObject on the same computer. You can pass a value returned by LresultFromObject to ObjectFromLresult only once; if it is passed subsequent times, the function fails and returns an error value.

SendInput

UINT SendInput(UINT cInputs, LPINPUT pInputs, INT cbSize);

Simulates a series of mouse, keyboard, or other user input events without interruption.

cInputs
Count of INPUT structures in the array at cInputs.
pInputs
Base address of an array INPUT structures. Each element describes a single simulated event.
cbSize
Size of the INPUT structure, in bytes.

This function does not reset the keyboard's current state. Therefore, if the user has any keys pressed when you call this function, they might interfere with the events that this function generates. If you are concerned about possible interference, check the keyboard's state with the GetAsyncKeyState Win32 function and correct as necessary.

See also Simulating Input

SetDDIHook

WINDDIAPI HDDI WINAPI SetDDIHook(HDC hdcHook,
    HMODULE hModCode, LONG lPrivateData, UINT hookClass,
    DDIHOOKPROC lpfnDdiHook);

Sets a hook into the DDI stream.

Note: The callback procedure specified by the lpfnDdiHook parameter must be written into a 16-bit dynamic-link library (DLL).

hdcHook
Reserved for future use. This parameter must be NULL.
hModCode
Handle to the 16-bit DLL module containing the callback function at the address specified by the lpfnDdiHook parameter.
lPrivateData
A 32-bit value will be passed to the callback function specified by the lpfnDdiHook parameter.
hookClass
DDI hook class value. This value can be one of the following:
DDIHOOK_FONTS Font enhancers.
DDIHOOK_MAGNIFIER Screen magnifiers.
DDIHOOK_RECORDER Screen readers and screen capture utilities.
DDIHOOK_REMOTE Remoting utilities.
lpfnDdiHook
Address of a callback function that matches the return value and argument list of the DDIHookProc function declaration. The winable.h header file defines the DDIHOOKPROC data type for declaring variables that match this declaration. GDI calls this function when specific DDI functions have been called.

The hook class determines the order in which DDI callbacks are called. The actual display device is always the last called. See the winddi.h file in the INC16 directory for more information on what GDI passes to the callback function.

See also Setting a DDI Hook, Unhooking a DDI Hook

SetWinEventHook

HWINEVENTHOOK WINAPI SetWinEventHook(UINT eventMin,
    UINT eventMax, HMODULE hmodWinEventProc,
    WINEVENTPROC lpfnWinEventProc, DWORD idProcess,
    DWORD idThread, UINT dwflags);

Sets an event hook for a range of events.

eventMin
Event constant describing the lowest event value in the range. This parameter can be EVENT_MIN to indicate the lowest possible event value.
eventMax
Event constant describing the highest event value in the range. This parameter can be EVENT_MAX to indicate the highest possible event value.
hmodWinEventProc
Handle to the dynamic-link library (DLL) containing the callback function at lpfnWinEventProc, if the WINEVENT_INCONTEXT flag is specified in the dwFlags parameter. If the callback function is not located in a DLL or the WINEVENT_OUTOFCONTEXT flag is specified, this parameter is ignored.
lpfnWinEventProc
Address of a callback function that matches the return value and argument list of the WinEventProc function declaration. The winable.h header file defines the WINEVENTPROC data type for declaring variables that match the WinEventProc declaration. USER calls this function when a server posts an event that falls within the range specified by the eventMin and eventMax parameters.
idProcess
ID of the process to be monitored, or zero for all processes.
idThread
ID of the thread with which the callback function will be associated. If this parameter is zero, the hook procedure is associated with all existing threads.
dwflags
Flag values specifying one or more receiving options. This parameter can contain one or more of the following values. The default value is WINEVENT_OUTOFCONTEXT.
WINEVENT_INCONTEXT
USER sends event notifications to the callback function as they occur. In this case, the DLL containing the callback function is mapped into the address space of the process generating the event. The callback function must be in a DLL to use this option.
WINEVENT_OUTOFCONTEXT
USER sends event notifications that are queued before sending them to the callback function. Queuing is required because the callback function is not mapped into the address space of the process generating the event. Although this method is asynchronous, events are guaranteed to be in sequential order.
WINEVENT_SKIPOWNPROCESS
Prevents any threads in the caller's process from receiving their own notifications. This flag does not prevent threads from generating events.
WINEVENT_SKIPOWNTHREAD
Prevents the thread that is processing notifications from receiving any events it might have generated itself. This flag does not prevent the thread from generating events.

This function allows you to specify not only which events you want, but also the process and thread in which you want to look for those events. This is useful when you want to work only with certain applications or just the system.

If the idProcess parameter is nonzero and idThread is zero, this function will hook all threads in that process. If the idProcess parameter is zero and idThread is nonzero, this function will hook only the thread specified by idThread. If both are zero, the function will hook in all threads and processes.

To monitor a noncontiguous range of events, call this method twice, specifying the same callback function in the lpfnWinEventProc parameter each time.

The client thread calling SetWinEventHook must be a thread that has a message loop, sometimes known as a "GUI thread."

See also About the WinEventProc Callback Function.

UnhookDDIHook

WINDDIAPI BOOL WINAPI UnhookDDIHook(HDDI hddi);

Removes a DDI hook created by a previous call to the SetDDIHook function.

hddi
Handle to this DDI hook. The previous SetDDIHook function call returned this value.

See also Unhooking a DDI Hook,Setting a DDI Hook

UnhookWinEvent

BOOL WINAPI UnhookWinEvent(HWINEVENTHOOK hWinEventHook);

Removes an event hook created by a previous call to SetWinEventHook.

hWinEventHook
Handle to the event hook that was returned in the previous call to SetWinEventHook.

This function removes the event hook specified by hWinEventHook, preventing the accompanying callback function from receiving further notifications. Clients should call this function when event notification is no longer needed or if the client's thread is ending for any reason.

Ensure that you call this function from the same thread that installed the event hook. USER will not allow threads to remove event hooks that they do not own.

If WINEVENT_INCONTEXT is specified when installing this event hook, winable.h will attempt to unload the corresponding DLL from all processes that loaded it. Although unloading might not occur immediately, the callback function will not be called after UnhookWinEvent returns.

WindowFromAccessibleObject

STDAPI WindowFromAccessibleObject(IAccessible* pacc, HWND* phwnd);

Retrieves the window handle that corresponds to a given instance of an IAccessible interface.

pacc
Address of an IAccessible interface.
phwnd
Address of a variable that will contain a handle to the window that contains the specified object, if any. If this value is NULL after the call, the object was not contained within a window (like the mouse pointer).

See also AccessibleObjectFromWindow

© 1997 Microsoft Corporation. All rights reserved. Legal Notices.