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.
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.
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
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.
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
STDAPI AccessibleObjectFromPoint( POINT ptScreen, IAccessible** ppacc, VARIANT* pvarChild);
Retrieves the address of the IAccessible interface accessible object at a specified point on the screen.
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
STDAPI AccessibleObjectFromWindow(HWND hwnd, DWORD dwId, REFIID riid, void **ppvObject);
Retrieves the address of a specified interface for a given object.
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
BOOL BlockInput(BOOL fBlock);
Blocks keyboard and mouse events from reaching the raw input thread, and therefore from all applications.
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:
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.
WINDDIAPI DWORD WINAPI CallNextDDI(HDDI hddi, DDITYPE ddiType, LPDDIPARAMS lpDdiParams);
Calls the next display device interface (DDI) hook process.
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.
STDAPI CreateStdAccessibleObject(HWND hwnd, LONG idObject, REFIID riidInterface, void **ppvObject);
Creates a default implementation of an accessible object for a given standard object.
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
BOOL WINAPI GetGUIThreadInfo(DWORD idThread, LPGUITHREADINFO lpgui);
Retrieves information about the active window or a specified graphical user interface (GUI) thread.
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.
UINT GetRoleText(DWORD dwRole, LPTSTR lpszRole, UINT cchRoleMax);
Retrieves the localized string based on a specified standard role value.
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);
UINT GetStateText(DWORD dwStateBit, LPTSTR lpszStateBit, UINT cchStateBitMax);
Retrieves the localized standard adjective string for a single standard state bit.
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);
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.
LRESULT LresultFromObject(REFIID riid, WPARAM wParam, LPUNKNOWN punk);
Generates a reference to an accessible object, in the form of an LRESULT value.
E_INVALIDARG | One or more arguments are invalid. |
E_NOINTERFACE | The punk parameter does not support the interface riid parameter. |
E_OUTOFMEMORY | Insufficient memory to store the object reference. |
E_UNEXPECTED | An unexpected error occurred. |
This function can return other values, identical to those returned by the CoMarshalInterface OLE function.
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.
void WINAPI NotifyWinEvent(DWORD event, HWND hwnd, LONG idObject, LONG idChild);
Signals the system and accessibility aids that a predefined event occurred.
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.
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.
E_INVALIDARG | One or more arguments are invalid. Most commonly, this occurs when the lResult parameter specified is not a value obtained by a call to LresultFromObject, or when lResult is a value used on a previous call to ObjectFromLresult. |
E_NOINTERFACE | The object does not support the interface specified by the riid parameter. |
E_UNEXPECTED | An unexpected error occurred. |
This function can return other values, identical to those returned by the CoUnMarshalInterface OLE function.
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.
UINT SendInput(UINT cInputs, LPINPUT pInputs, INT cbSize);
Simulates a series of mouse, keyboard, or other user input events without interruption.
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
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).
DDIHOOK_FONTS | Font enhancers. |
DDIHOOK_MAGNIFIER | Screen magnifiers. |
DDIHOOK_RECORDER | Screen readers and screen capture utilities. |
DDIHOOK_REMOTE | Remoting utilities. |
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
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.
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.
WINDDIAPI BOOL WINAPI UnhookDDIHook(HDDI hddi);
Removes a DDI hook created by a previous call to the SetDDIHook function.
See also Unhooking a DDI Hook,Setting a DDI Hook
BOOL WINAPI UnhookWinEvent(HWINEVENTHOOK hWinEventHook);
Removes an event hook created by a previous call to SetWinEventHook.
Three common errors will cause this function to fail:
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.
STDAPI WindowFromAccessibleObject(IAccessible* pacc, HWND* phwnd);
Retrieves the window handle that corresponds to a given instance of an IAccessible interface.
See also AccessibleObjectFromWindow
© 1997 Microsoft Corporation. All rights reserved. Legal Notices.