515 lines
17 KiB
C
515 lines
17 KiB
C
/*
|
|
File: CGRemoteOperation.h
|
|
|
|
Contains: CoreGraphics remote operation
|
|
|
|
Version: QuickTime 7.3
|
|
|
|
Copyright: (c) 2007 (c) 2000-2001 by Apple Computer, Inc., all rights reserved.
|
|
|
|
Bugs?: For bug reports, consult the following page on
|
|
the World Wide Web:
|
|
|
|
http://developer.apple.com/bugreporter/
|
|
|
|
*/
|
|
#ifndef CGREMOTEOPERATION_H_
|
|
#define CGREMOTEOPERATION_H_
|
|
|
|
#ifndef __CGBASE__
|
|
#include <CGBase.h>
|
|
#endif
|
|
|
|
#ifndef __CGGEOMETRY__
|
|
#include <CGGeometry.h>
|
|
#endif
|
|
|
|
#ifndef __CGERROR__
|
|
#include <CGError.h>
|
|
#endif
|
|
|
|
#ifndef __CFDATE__
|
|
#include <CFDate.h>
|
|
#endif
|
|
|
|
#ifndef __CFMACHPORT__
|
|
#include <CFMachPort.h>
|
|
#endif
|
|
|
|
|
|
|
|
|
|
#if PRAGMA_ONCE
|
|
#pragma once
|
|
#endif
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
#if PRAGMA_IMPORT
|
|
#pragma import on
|
|
#endif
|
|
|
|
#if PRAGMA_ENUM_ALWAYSINT
|
|
#if defined(__fourbyteints__) && !__fourbyteints__
|
|
#define __CGREMOTEOPERATION__RESTORE_TWOBYTEINTS
|
|
#pragma fourbyteints on
|
|
#endif
|
|
#pragma enumsalwaysint on
|
|
#elif PRAGMA_ENUM_OPTIONS
|
|
#pragma option enum=int
|
|
#elif PRAGMA_ENUM_PACK
|
|
#if __option(pack_enums)
|
|
#define __CGREMOTEOPERATION__RESTORE_PACKED_ENUMS
|
|
#pragma options(!pack_enums)
|
|
#endif
|
|
#endif
|
|
|
|
typedef CGError CGEventErr;
|
|
enum {
|
|
CGEventNoErr = kCGErrorSuccess
|
|
};
|
|
|
|
|
|
/* Screen refresh or drawing notification */
|
|
/*
|
|
* Callback function pointer;
|
|
* Declare your callback function in this form. When an area of the display is
|
|
* modified or refreshed, your callback function will be invoked with a count
|
|
* of the number of rectangles in the refreshed areas, and a list of the refreshed
|
|
* rectangles. The rectangles are in global coordinates.
|
|
*
|
|
* Your function should not modify, deallocate or free memory pointed to by rectArray.
|
|
*
|
|
* The system continues to accumulate refreshed areas constantly. Whenever new
|
|
* information is available, your callback function is invoked.The list of rects
|
|
* passed to the callback function are cleared from the accumulated refreshed area
|
|
* when the callback is made.
|
|
*
|
|
* This callback may be triggered by drawing operations, window movement, and
|
|
* display reconfiguration.
|
|
*
|
|
* Bear in mind that a single rectangle may occupy multiple displays,
|
|
* either by overlapping the displays, or by residing on coincident displays
|
|
* when mirroring is active. Use the CGGetDisplaysWithRect() to determine
|
|
* the displays a rectangle occupies.
|
|
*/
|
|
typedef u_int32_t CGRectCount;
|
|
typedef CALLBACK_API_C( void , CGScreenRefreshCallback )(CGRectCount count, const CGRect *rectArray, void *userParameter);
|
|
/*
|
|
* Register a callback function to be invoked when an area of the display
|
|
* is refreshed, or modified. The function is invoked on the same thread
|
|
* of execution that is processing events within your application.
|
|
* userParameter is passed back with each invocation of the callback function.
|
|
*/
|
|
/*
|
|
* CGRegisterScreenRefreshCallback()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( void )
|
|
CGRegisterScreenRefreshCallback(
|
|
CGScreenRefreshCallback callback,
|
|
void * userParameter);
|
|
|
|
|
|
/*
|
|
* Remove a previously registered calback function.
|
|
* Both the function and the userParameter must match the registered entry to be removed.
|
|
*/
|
|
/*
|
|
* CGUnregisterScreenRefreshCallback()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( void )
|
|
CGUnregisterScreenRefreshCallback(
|
|
CGScreenRefreshCallback callback,
|
|
void * userParameter);
|
|
|
|
|
|
|
|
/*
|
|
* In some applications it may be preferable to have a seperate thread wait for screen refresh data.
|
|
* This function should be called on a thread seperate from the event processing thread.
|
|
* If screen refresh callback functions are registered, this function should not be used.
|
|
* The mechanisms are mutually exclusive.
|
|
*
|
|
* Deallocate screen refresh rects using CGReleaseScreenRefreshRects().
|
|
*
|
|
* Returns an error code if parameters are invalid or an error occurs in retrieving
|
|
* dirty screen rects from the server.
|
|
*/
|
|
/*
|
|
* CGWaitForScreenRefreshRects()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( CGEventErr )
|
|
CGWaitForScreenRefreshRects(
|
|
CGRect ** pRectArray,
|
|
CGRectCount * pCount);
|
|
|
|
|
|
/*
|
|
* Deallocate the list of rects recieved from CGWaitForScreenRefreshRects()
|
|
*/
|
|
/*
|
|
* CGReleaseScreenRefreshRects()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( void )
|
|
CGReleaseScreenRefreshRects(CGRect * rectArray);
|
|
|
|
|
|
/*
|
|
* Posting events: These functions post events into the system. Use for remote
|
|
* operation and virtualization.
|
|
*
|
|
* Note that remote operation requires a valid connection to the server, which
|
|
* must be owned by either the root/Administrator user or the logged in console
|
|
* user. This means that your application must be running as root/Administrator
|
|
* user or the logged in console user.
|
|
*/
|
|
|
|
/*
|
|
* Synthesize mouse events.
|
|
* mouseCursorPosition should be the global coordinates the mouse is at for the event.
|
|
* updateMouseCursor should be TRUE if the on-screen cursor
|
|
* should be moved to mouseCursorPosition.
|
|
*
|
|
* Based on the values entered, the appropriate mouse-down, mouse-up, mouse-move,
|
|
* or mouse-drag events are generated, by comparing the new state with the current state.
|
|
*
|
|
* The current implemementation of the event system supports a maximum of thirty-two buttons.
|
|
* The buttonCount parameter should be followed by 'buttonCount' boolean_t values
|
|
* indicating button state. The first value should reflect the state of the primary
|
|
* button on the mouse. The second value, if any, should reflect the state of the secondary
|
|
* mouse button (right), if any. A third value woule be the center button, and the remaining
|
|
* buttons would be in USB device order.
|
|
*/
|
|
typedef u_int32_t CGButtonCount;
|
|
/*
|
|
* CGPostMouseEvent()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( CGEventErr )
|
|
CGPostMouseEvent(
|
|
CGPoint mouseCursorPosition,
|
|
boolean_t updateMouseCursorPosition,
|
|
CGButtonCount buttonCount,
|
|
boolean_t mouseButtonDown,
|
|
...);
|
|
|
|
|
|
/*
|
|
* Synthesize scroll wheel events.
|
|
*
|
|
* The current implemementation of the event system supports a maximum of three wheels.
|
|
*
|
|
* The wheelCount parameter should be followed by 'wheelCount' 32 bit integer values
|
|
* indicating wheel movements. The first value should reflect the state of the primary
|
|
* wheel on the mouse. The second value, if any, should reflect the state of a secondary
|
|
* mouse wheel, if any.
|
|
*
|
|
* Wheel movement is represented by small signed integer values,
|
|
* typically in a range from -10 to +10. Large values may have unexpected results,
|
|
* depending on the application that processes the event.
|
|
*/
|
|
typedef u_int32_t CGWheelCount;
|
|
/*
|
|
* CGPostScrollWheelEvent()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( CGEventErr )
|
|
CGPostScrollWheelEvent(
|
|
CGWheelCount wheelCount,
|
|
int32_t wheel1,
|
|
...);
|
|
|
|
|
|
/*
|
|
* Synthesize keyboard events. Based on the values entered,
|
|
* the appropriate key down, key up, and flags changed events are generated.
|
|
* If keyChar is NUL (0), an apropriate value will be guessed at, based on the
|
|
* default keymapping.
|
|
*
|
|
* All keystrokes needed to generate a character must be entered, including
|
|
* SHIFT, CONTROL, OPTION, and COMMAND keys. For example, to produce a 'Z',
|
|
* the SHIFT key must be down, the 'z' key must go down, and then the SHIFT
|
|
* and 'z' key must be released:
|
|
* CGPostKeyboardEvent( (CGCharCode)0, (CGKeyCode)56, true ); // shift down
|
|
* CGPostKeyboardEvent( (CGCharCode)'Z', (CGKeyCode)6, true ); // 'z' down
|
|
* CGPostKeyboardEvent( (CGCharCode)'Z', (CGKeyCode)6, false ); // 'z' up
|
|
* CGPostKeyboardEvent( (CGCharCode)0, (CGKeyCode)56, false ); // 'shift up
|
|
*/
|
|
typedef u_int16_t CGCharCode;
|
|
typedef u_int16_t CGKeyCode;
|
|
/*
|
|
* CGPostKeyboardEvent()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( CGEventErr )
|
|
CGPostKeyboardEvent(
|
|
CGCharCode keyChar,
|
|
CGKeyCode virtualKey,
|
|
boolean_t keyDown);
|
|
|
|
|
|
/*
|
|
* Warp the mouse cursor to the desired position in global
|
|
* coordinates without generating events
|
|
*/
|
|
/*
|
|
* CGWarpMouseCursorPosition()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( CGEventErr )
|
|
CGWarpMouseCursorPosition(CGPoint newCursorPosition);
|
|
|
|
|
|
/*
|
|
* Remote operation may want to inhibit local events (events from
|
|
* the machine's keyboard and mouse). This may be done either as a
|
|
* explicit request (tracked per app) or as a short term side effect of
|
|
* posting an event.
|
|
*
|
|
* CGInhibitLocalEvents() is typically used for long term remote operation
|
|
* of a system, as in automated system testing or telecommuting applications.
|
|
* Local device state changes are discarded.
|
|
*
|
|
* Local event inhibition is turned off if the app that requested it terminates.
|
|
*/
|
|
/*
|
|
* CGInhibitLocalEvents()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( CGEventErr )
|
|
CGInhibitLocalEvents(boolean_t doInhibit);
|
|
|
|
|
|
/*
|
|
* Set the period of time in seconds that local hardware events (keyboard and mouse)
|
|
* are supressed after posting an event. Defaults to 0.25 second.
|
|
*/
|
|
/*
|
|
* CGSetLocalEventsSuppressionInterval()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( CGEventErr )
|
|
CGSetLocalEventsSuppressionInterval(CFTimeInterval seconds);
|
|
|
|
|
|
/*
|
|
* By default, the flags that indicate modifier key state (Command, Alt, Shift, etc.)
|
|
* from the system's keyboard and from other event sources are ORed together as an event is
|
|
* posted into the system, and current key and mouse button state is considered in generating new events.
|
|
* This function allows your application to enable or disable the
|
|
* merging of event state. When combining is turned off, the event state propagated in the events
|
|
* posted by your app reflect state built up only by your app. The state within your app's generated
|
|
* event will not be combined with the system's current state, so the system-wide state reflecting key
|
|
* and mouse button state will remain unchanged
|
|
*
|
|
* When called with doCombineState equal to FALSE, this function initializes local (per application)
|
|
* state tracking information to a state of all keys, modifiers, and mouse buttons up.
|
|
*
|
|
* When called with doCombineState equal to TRUE, the current global state of keys, modifiers,
|
|
* and mouse buttons are used in generating events.
|
|
*/
|
|
/*
|
|
* CGEnableEventStateCombining()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: in version 10.1 and later
|
|
*/
|
|
EXTERN_API_C( CGEventErr )
|
|
CGEnableEventStateCombining(boolean_t doCombineState);
|
|
|
|
|
|
/*
|
|
* By default the system supresses local hardware events from the keyboard and mouse during
|
|
* a short interval after a synthetic event is posted (see CGSetLocalEventsSuppressionInterval())
|
|
* and while a synthetic mouse drag (mouse movement with the left/only mouse button down).
|
|
* Some classes of applications may want to enable events from some of the local hardware.
|
|
* For example, an app may want to post only mouse events, and so may wish to permit local
|
|
* keyboard hardware events to pass through.
|
|
*
|
|
* This interface lets an app specify a state (event supression interval, or mouse drag), and
|
|
* a mask of event categories to be passed through.
|
|
*/
|
|
enum CGEventFilterMask {
|
|
kCGEventFilterMaskPermitLocalMouseEvents = 0x00000001, /* Mouse, scroll wheel */
|
|
kCGEventFilterMaskPermitLocalKeyboardEvents = 0x00000002, /* Alphanumeric keys and Command, Option, Control, Shift, AlphaLock */
|
|
kCGEventFilterMaskPermitSystemDefinedEvents = 0x00000004, /* Power key, bezel buttons, sticky keys */
|
|
kCGEventFilterMaskPermitAllEvents = kCGEventFilterMaskPermitLocalMouseEvents | kCGEventFilterMaskPermitLocalKeyboardEvents | kCGEventFilterMaskPermitSystemDefinedEvents
|
|
};
|
|
typedef enum CGEventFilterMask CGEventFilterMask;
|
|
|
|
enum CGEventSupressionState {
|
|
kCGEventSupressionStateSupressionInterval = 0,
|
|
kCGEventSupressionStateRemoteMouseDrag = 1,
|
|
kCGNumberOfEventSupressionStates = 2
|
|
};
|
|
typedef enum CGEventSupressionState CGEventSupressionState;
|
|
|
|
/*
|
|
* CGSetLocalEventsFilterDuringSupressionState()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: in version 10.1 and later
|
|
*/
|
|
EXTERN_API_C( CGEventErr )
|
|
CGSetLocalEventsFilterDuringSupressionState(
|
|
CGEventFilterMask filter,
|
|
CGEventSupressionState state);
|
|
|
|
|
|
/*
|
|
* Helper function to connect or disconnect the mouse and mouse cursor.
|
|
* CGAssociateMouseAndMouseCursorPosition(false) has the same effect
|
|
* as the following, without actually modifying the supression interval:
|
|
*
|
|
* CGSetLocalEventsSuppressionInterval(MAX_DOUBLE);
|
|
* CGWarpMouseCursorPosition(currentPosition);
|
|
*
|
|
* While disconnected, mouse move and drag events will reflect the current position of
|
|
* the mouse cursor position, which will not change with mouse movement. Use the
|
|
* <CoreGraphics/CGDirectDisplay.h> function:
|
|
*
|
|
* void CGGetLastMouseDelta( CGMouseDelta * deltaX, CGMouseDelta * deltaY );
|
|
*
|
|
* This will report mouse movement associated with the last mouse move or drag event.
|
|
*
|
|
* To update the display cursor position, use the function defined in this module:
|
|
*
|
|
* CGEventErr CGWarpMouseCursorPosition( CGPoint newCursorPosition );
|
|
*/
|
|
/*
|
|
* CGAssociateMouseAndMouseCursorPosition()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: in version 10.0 and later
|
|
*/
|
|
EXTERN_API_C( CGEventErr )
|
|
CGAssociateMouseAndMouseCursorPosition(boolean_t connected);
|
|
|
|
|
|
/*
|
|
* Some classes of applications need to detect when the window server process dies, or
|
|
* is not running. The easiest way to do this is to use a CFMachPortRef.
|
|
*
|
|
* If the CoreGraphics window server is not running, this function returns NULL.
|
|
* If the server is running, a CFMachPortRef is returned.
|
|
*
|
|
* A program can register a callback function to use a CFMachPortRef to determine
|
|
* when the CoreGraphics window server exits:
|
|
*
|
|
* static void handleWindowServerDeath( CFMachPortRef port, void *info )
|
|
* {
|
|
* printf( "Window Server port death detected!\n" );
|
|
* CFRelease( port );
|
|
* exit( 1 );
|
|
* }
|
|
*
|
|
* static void watchForServerDeath()
|
|
* {
|
|
* CFMachPortRef port;
|
|
*
|
|
* port = CGWindowServerCFMachPort();
|
|
* CFMachPortSetInvalidationCallBack( port, handleWindowServerDeath );
|
|
* }
|
|
*
|
|
* Note that when the window server exits, there may be a few seconds during which
|
|
* no window server is running, until the operating system starts a new
|
|
* window server/loginwindow pair of processes. This function will return NULL
|
|
* until a new window server is running.
|
|
*
|
|
* Multiple calls to this function may return multiple CFMachPortRefs, each referring
|
|
* to the same Mach port. Multiple callbacks registered on multiple CFMachPortRefs
|
|
* obtained in this way may fire in a nondetermanistic manner.
|
|
*
|
|
* Your program will need to run a CFRunLoop for the port death
|
|
* callback to function. A program which does not use a CFRunLoop may use
|
|
* CFMachPortIsValid(CFMachPortRef port) periodically to check if the port is valid.
|
|
*/
|
|
/*
|
|
* CGWindowServerCFMachPort()
|
|
*
|
|
* Availability:
|
|
* Non-Carbon CFM: not available
|
|
* CarbonLib: not available
|
|
* Mac OS X: in version 10.1 and later
|
|
*/
|
|
EXTERN_API_C( CFMachPortRef )
|
|
CGWindowServerCFMachPort(void);
|
|
|
|
|
|
|
|
#if PRAGMA_ENUM_ALWAYSINT
|
|
#pragma enumsalwaysint reset
|
|
#ifdef __CGREMOTEOPERATION__RESTORE_TWOBYTEINTS
|
|
#pragma fourbyteints off
|
|
#endif
|
|
#elif PRAGMA_ENUM_OPTIONS
|
|
#pragma option enum=reset
|
|
#elif defined(__CGREMOTEOPERATION__RESTORE_PACKED_ENUMS)
|
|
#pragma options(pack_enums)
|
|
#endif
|
|
|
|
#ifdef PRAGMA_IMPORT_OFF
|
|
#pragma import off
|
|
#elif PRAGMA_IMPORT
|
|
#pragma import reset
|
|
#endif
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* CGREMOTEOPERATION_H_ */
|
|
|