/* 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 #endif #ifndef __CGGEOMETRY__ #include #endif #ifndef __CGERROR__ #include #endif #ifndef __CFDATE__ #include #endif #ifndef __CFMACHPORT__ #include #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 * 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_ */