/*****************************************************************************
 Name    : RetroPlatformIPC_doc.txt
 Project : RPSampleGuest
 Client  : Cloanto Corporation
 Support : http://www.retroplatform.com
 Legal   : CONFIDENTIAL TRADE SECRET PROPERTY OF CLOANTO CORPORATION
         : Copyright © Cloanto Corporation 2007-2021.
         : All rights reserved, except where licensed,
         : assigned or transferred by contract.
 Authors : os, m
 Created : 2007-08-23 10:08:25
 Updated : 2021-10-14 11:42:34
 Comment : Reference for RetroPlatformIPC.h (RP Player interprocess communication include file)
 *****************************************************************************/




****************************************************************************
 Guest-to-Host Messages
****************************************************************************

Notes about startup:
>>>
   At startup time, the guest sends initialization messages
   (terminated by RP_IPC_TO_HOST_SCREENMODE)
   so that the host can adapt the GUI based on the reported features;
   these messages include:
      RP_IPC_TO_HOST_FEATURES (describes guest features),
      RP_IPC_TO_HOST_INPUTDEVICE (enumerates available input devices)
      RP_IPC_TO_HOST_POWERLED (turns on the power LED in the GUI),
      RP_IPC_TO_HOST_DEVICES (one for each device category: tells the number of emulated devices),
      RP_IPC_TO_HOST_DEVICECONTENT (one for each device with an image file or peripheral attached),
      RP_IPC_TO_HOST_DEVICEREADWRITE (one for each device with an image file or peripheral attached - optional for non-floppy/non-hard disk which are always read-only),
      RP_IPC_TO_HOST_TURBO (tells if some of the turbo modes are activated from the start),
      RP_IPC_TO_HOST_VOLUME (reports about starting volume level),
      RP_IPC_TO_HOST_SCREENMODE (communicates the screen mode, the clipping coordinates and the guest window handle);
   note that at startup time the guest should create a borderless and hidden window
   and send its handle using a RP_IPC_TO_HOST_SCREENMODE message, which must be the last
   of the initialization messages, since it displays the guest window
   and the host "frame window" (the part of the player user interface
   with command and status icons which can be used to drag the guest window, etc.);
   in some circumstances the host may decide not to display the guest window
   when receiving the RP_IPC_TO_HOST_SCREENMODE message (e.g. in Express mode
   the guest may be immediately paused and an intro banner may be displayed;
   when the intro banner is dismissed the guest is resumed from pause mode
   and its window is displayed);
<<<
   
Message:
   RP_IPC_TO_HOST_FEATURES
Description:
   the guest uses this sequence of messages to tell the host
   about the features it supports;
   
   at startup time, the guest sends RP_IPC_TO_HOST_FEATURES to describe
   the guest features, so that the host can adapt the UI based on the
   reported features; in this context, RP_IPC_TO_HOST_FEATURES is sent
   together with the other initialization messages;

   at runtime RP_IPC_TO_HOST_FEATURES may be sent with a fresh set of
   attributes (e.g. because a new screen mode can be scaled in different ways, etc.)
   
Data sent:
   WPARAM = RP_FEATURE_* flags
Response:
   none


Message:
   RP_IPC_TO_HOST_INPUTDEVICE
Description:
   the guest sends one or more consecutive RP_IPC_TO_HOST_INPUTDEVICE messages,
   terminated by an RP_HOSTINPUT_END type device. This input device enumeration
   must be done at startup (immediately after sending the RP_IPC_TO_HOST_FEATURES
   messages and before the RP_IPC_TO_HOST_SCREENMODE message) and
   should be done whenever a device is added or removed. The first message
   of a series resets the list of input devices, which starts fresh from that first
   input device, followed by more devices until the RP_HOSTINPUT_END dummy device.
   The messages enumerate the input-type devices (RP_DEVICECATEGORY_INPUTPORT
   category) found on the host.
Data sent:
   pData = a RPDEVICEDESCRIPTION structure (see RetroPlatformIPC.h);
Response:
   none


Message:
   RP_IPC_TO_HOST_CLOSED
Description:
   this message is sent to the host when the guest is terminating;
   the RPPostMessage() function (instead of RPSendMessage()) should be used
   to send this message, since the host may wait for the guest process to terminate
   when RP_IPC_TO_HOST_CLOSED is received
Data sent:
   none
Response:
   none


Message:
   RP_IPC_TO_HOST_ACTIVATED
Description:
   the guest sends this message to the host when its window is being activated;
   this is typically sent when its window receives the WM_ACTIVATEAPP
   message with a non-zero WPARAM parameter
   (or WM_SHOWWINDOW, with non-zero WPARAM and zero LPARAM,
   i.e. at application startup)
Data sent:
   LPARAM = identifier of the thread that owns the window being deactivated
Response:
   none


Message:
   RP_IPC_TO_HOST_DEACTIVATED
Description:
   the guest sends this message to the host when its window is being deactivated;
   this is typically sent when its window receives the WM_ACTIVATEAPP
   message with a zero WPARAM parameter
Data sent:
   LPARAM = identifier of the thread that owns the window being activated
Response:
   none


Message:
   RP_IPC_TO_HOST_ENABLED
Description:
   the guest sends this message to the host when its window is being enabled
   (e.g. a WM_ENABLE message has been received with wParam set to TRUE);
   this usually occurs when closing a modal dialog (with guest's window as parent)
Data sent:
   none
Response:
   none


Message:
   RP_IPC_TO_HOST_DISABLED
Description:
   the guest sends this message to the host when its window is being disabled
   (e.g. a WM_ENABLE message has been received with wParam set to FALSE);
   this usually occurs when opening a modal dialog (with guest's window as parent)
Data sent:
   none
Response:
   none


Message:
   RP_IPC_TO_HOST_SCREENMODE
Description:
   the guest sends a RP_IPC_TO_HOST_SCREENMODE message to notify the host
   about a change in its "screen mode"
   (1x/2x/3x/4x, full screen, clipping coordinates, etc.),
   or to keep the host updated about the guest window handle
   (just before destroying its window, the guest sends this message
   with the hGuestWindow field of the RPSCREENMODE structure set to NULL);
   screen mode changes requested by the host
   (see the RP_IPC_TO_GUEST_SCREENMODE message) must not be notified,
   unless this is an asynchronous screen mode change
   (i.e. the guest returned the INVALID_HANDLE_VALUE
   response to a RP_IPC_TO_GUEST_SCREENMODE host request).

   At startup time, the guest must create
   a borderless and hidden window and send its handle
   using this message; the host will then take care
   of preparing, positioning and showing the guest window.
   RP_IPC_TO_HOST_SCREENMODE marks the end of the guest
   initialization steps.

Data sent:
   pData = a RPSCREENMODE structure
Response:
   none


Message:
   RP_IPC_TO_HOST_POWERLED
Description:
   sent to the host to change the power LED state
Data sent:
   WPARAM = power LED intensity (off 0, min 1, max decimal 100)
            in a dual-brightness LED system values 1-49 (decimal) indicate the
            "dimmed" status (Amiga "low-pass filter off")
Response:
   none


Message:
   RP_IPC_TO_HOST_DEVICES
Description:
   this message is used to notify the host about a change
   in the number of emulated devices (floppy drives, hard disks, etc.)
Data sent:
   WPARAM = device category (RP_DEVICE_* value)
   LPARAM = 32-bit bitfield representing the devices
            emulated in the specified category
            (every bit set to 1 corresponds to a mounted drive
             e.g. 0x00000005 = drive 0 and drive 2 are emulated)
Response:
   none


Message:
   RP_IPC_TO_HOST_DEVICEACTIVITY
Description:
   this message can be used to turn on or off the activity indicator
   of a specified device (a single LED on the original hardware)
   or to notify the host about the status of a joystick (multiple buttons);
   device LED indicators (e.g. the disk activity ones, not the joystick ones)
   can also be "blinked", i.e. the host will turn the
   LED on and then off again after the specified amount of time;
   being a low-priority notification with no response from the host,
   it is advised that guests send RP_IPC_TO_HOST_DEVICEACTIVITY
   using the RPPostMessage() function, instead of the RPSendMessage() function
Data sent:
   WPARAM = device category (RP_DEVICE_* value) and device number
            combined with the MAKEWORD macro;
            e.g. MAKEWORD(RP_DEVICECATEGORY_FLOPPY, 0);
            the RP_ALL_DEVICES define may be used as device number
            to turn on or off all the activity LEDs for a device category
   LPARAM = for non-joystick devices, LED status and flags are combined
            with the MAKELONG macro; e.g. MAKELONG(Status, Flags);
            the Status value can be set to 0 to turn off the activity LED,
            to -1 to turn on the activity LED,
            or to a <millisecond delay> value to turn on the activity LED
            for the specified amount of time (blink);
            the Flags value can be set
            using one or more of the RP_DEVICEACTIVITY_* defines;
            if the message references a RP_DEVICE_INPUTPORT device
            connected to a joystick, the data sent via LPARAM
            is a mask of RP_JOYSTICK_* values (no MAKELONG macro)
            reflecting all buttons that are pressed (some may be
            pressed simultaneously)
Response:
   none


Message:
   RP_IPC_TO_HOST_MOUSECAPTURE
Description:
   the guest sends this message when the mouse is captured/released
   (the mouse is "captured" when its movements are restricted to the guest window area
   and the system cursor is not visible);
   mouse capture changes requested by the host
   (see the RP_IPC_TO_GUEST_MOUSECAPTURE message) must not be notified;
   for consistency across different guests, a guest which sends RP_IPC_TO_HOST_MOUSECAPTURE
   messages should also implement a keyboard-actuated escape functionality
   (the preferred key for this purpose is included in the parameters sent from the
   host at startup time - see RPLaunchGuest() in RetroPlatformPlugin.h);
   note that in order not to interfere with the window dragging functionality,
   the mouse should not be captured when the guest window gets the focus,
   but when a mouse button event is received
Data sent:
   WPARAM = mouse capture state (RP_MOUSECAPTURE_* flags)
            four possible states are currently possible
            (i.e. the mouse can be captured or not
             and the magic mouse feature can be active or not)
Response:
   none


Message:
   RP_IPC_TO_HOST_HOSTAPIVERSION
Description:
    the guest can send a RP_IPC_TO_HOST_HOSTAPIVERSION to query the host
    about the RetroPlatform API version it implements;
    since the guest plugin already asks for a minimum version of the API
    on the host side, this message can be used to check the host API version
    and enable optional functionality
Data sent:
   none
Response:
   LRESULT = major and minor version combined with the MAKELONG macro
             (e.g. LOWORD(lr) = major version; HIWORD(lr) = minor version)


Message:
   RP_IPC_TO_HOST_HOSTVERSION
Description:
    the guest can send a RP_IPC_TO_HOST_HOSTVERSION
    to query the host about its version
Data sent:
   none
Response:
   LRESULT = major, minor and build versions combined into a single 32 bit value;
             the RP_HOSTVERSION_* macros can be used to get specific information


Message:
   RP_IPC_TO_HOST_PAUSE
Description:
   the guest sends this message to the host
   when it enters or exits pause mode;
   pause mode changes requested by the host
   (see the RP_IPC_TO_GUEST_PAUSE message) must not be notified,
   unless the guest returned the value 2 as RP_IPC_TO_GUEST_PAUSE response;
   note: when paused, the guest should release the mouse (if captured);
   during pause mode, the mouse should never be captured;
   starting with version 7.1 of the RetroPlatform API,
   the host handles every keyboard input/shortcuts,
   so the guest is not supposed to enter pause mode based on
   its own keyboard shortcuts (e.f. the <Pause> key):
   this notification message is therfore just used
   in the RP_IPC_TO_GUEST_PAUSE scenario described above
Data sent:
   WPARAM = non-zero when the guest enters pause mode
            or zero when the guest exits from pause mode
Response:
   none


Message:
   RP_IPC_TO_HOST_DEVICECONTENT
Description:
   the guest sends a RP_IPC_TO_HOST_DEVICECONTENT message
   to notify the host that an image file (e.g. a floppy disk image)
   or a peripheral (e.g. a joystick)
   has been loaded/inserted into (or ejected from) an emulated device;
   this notification does not need to (must not) be sent when the event
   has been requested by the host (see the RP_IPC_TO_GUEST_DEVICECONTENT message).
   If the host requested an unavailable device (e.g. tablet), the guest
   should send an LRESULT 0 (error) in reply to the RP_IPC_TO_GUEST_DEVICECONTENT
   message, followed by an RP_IPC_TO_HOST_DEVICECONTENT message
   indicating the actual content (empty, previous device, similar device, etc.)
   Configuration details (e.g. keyboard-joystick layout) should be preserved, so
   that the appropriate data can be sent to the host (e.g. Content set to
   "KeyboardCustom Left=0x4B Right=0x4D Up=0x48 Down=0x50 Fire=0x52"), which in
   turn may need to display it in the user interface.
   In the user interface, a device (drive) icon, perhaps with an empty state,
   may persist even for devices like empty drives (floppy, CD).
Data sent:
   pData = a RPDEVICECONTENT structure (see RetroPlatformIPC.h);
           the szContent field of the structure
           contains an empty string when the guest
           is ejecting something from the device;
           szContent examples for CD and other physical drives supported by the guest:
           - "D:\" = mount physical drive D: (full or empty, does not matter)
	   - "C:\test.iso" = mount ISO image
	   - "" = empty image drive ("image mode without image")
	   - there is no specific message to indicate "empty physical drive" (what counts is that there is an association with the physical drive)
Response:
   none


Message:
   RP_IPC_TO_HOST_DEVICEREADWRITE
Description:
   the guest sends a RP_IPC_TO_HOST_DEVICEREADWRITE message
   to notify the host about an initial status or a change in
   the read/write protection status;
   this notification is optional if the event
   was requested by the host (see the RP_IPC_TO_GUEST_DEVICEREADWRITE message);
   used for device categories RP_DEVICECATEGORY_FLOPPY, RP_DEVICECATEGORY_HD,
   RP_DEVICECATEGORY_TAPE, RP_DEVICECATEGORY_CARTRIDGE
Data sent:
   WPARAM = device category (RP_DEVICE_* value) and device number
            combined with the MAKEWORD macro;
            e.g. MAKEWORD(RP_DEVICECATEGORY_FLOPPY, 0)
   LPARAM = current device read/write status flags (RP_DEVICE_READONLY/RP_DEVICE_READWRITE)
Response:
   none


Message:
   RP_IPC_TO_HOST_TURBO
Description:
   the guest sends a RP_IPC_TO_HOST_TURBO message
   to notify the host about activation (e.g. from startup) of "turbo" (maximum speed) mode
   of some of its functionalities (e.g. floppy, CPU);
   turbo mode activations/deactivations requested by the host
   (see the RP_IPC_TO_GUEST_TURBO message) must not be notified;
Data sent:
   WPARAM = mask of functionalities affected (RP_TURBO_* flags)
   LPARAM = bits corresponding to those set in WPARAM
            (1 = turbo mode activated for the guest functionality
             0 = guest functionality reverted to normal speed)
Response:
   none


Message:
   RP_IPC_TO_HOST_PING
Description:
   this is a no-operation message and can be sent
   to check if the host is responsive and functional
Data sent:
   none
Response:
   LRESULT = non-zero value is returned


Message:
   RP_IPC_TO_HOST_VOLUME
Description:
   the guest uses the RP_IPC_TO_HOST_VOLUME message
   to notify the host about a change of its audio level;
   audio level changes requested by the host
   (see the RP_IPC_TO_GUEST_VOLUME message) must not be notified
Data sent:
   WPARAM = volume level (min/off 0, max 100)
Response:
   none


Message:
   RP_IPC_TO_HOST_ESCAPED
Description:
   this message is sent to notify the host
   that the escape key has been held down
Data sent:
   none
Response:
   none


Message:
   RP_IPC_TO_HOST_PARENT
Description:
   the guest sends this message to the host to get the handle
   of the parent for its window; the guest window must be created
   as a borderless (WS_POPUP style), hidden window,
   using the handle returned by this message as the parent window parameter
Data sent:
   none
Response:
   LRESULT = window handle (HWND) to use in a CreateWindow call


Message:
   RP_IPC_TO_HOST_DEVICESEEK
Description:
   this message can be used to notify the host about a seek operation
   of a specified device (e.g. the head of a disk drive changes position;
   to keep messages at a minimum, avoid repeat messages for the same position);
Data sent:
   WPARAM = device category (RP_DEVICE_* value) and device number
            combined with the MAKEWORD macro;
            e.g. MAKEWORD(RP_DEVICECATEGORY_FLOPPY, 0)
   LPARAM = device-dependant seek position (e.g. drive track position)
Response:
   none


Message:
   RP_IPC_TO_HOST_CLOSE
Description:
   when the user presses ALT+F4 in the guest window
   the guest should intercept such an event
   (WM_SYSCOMMAND with wParam set to SC_CLOSE),
   send this notification message to the host
   and not close its window (i.e. not call the DefWindowProc() of its window);
   the host will then open its Close Options dialog
   and will send a RP_IPC_TO_GUEST_CLOSE command to the guest
   if the user confirms the close request
Data sent:
   none
Response:
   none
   
   
Message:
   RP_IPC_TO_HOST_KEYBOARDLAYOUT
Description:
   the guest sends this message to notify the host
   about a change of the guest keyboard layout
   (e.g. Amiga SetMap/SetKeyboard)
Data sent:
   pData = platform-dependent keyboard layout data
Response:
   none


Message:
   RP_IPC_TO_HOST_RAWINPUT_EVENT
Description:
   this message is sent to forward to the host
   the RawInput mouse buttons events received by the guest
   (forwarding should be done only when the guest window is focused
   and even when the emulation is paused);
   events are forwarded when the header.dwType field
   of the RAWINPUT structure is RIM_TYPEMOUSE,
   and when data.mouse.usButtonFlags is different from 0;
   the value returned as response must be used
   instead of the original data.mouse.usButtonFlags value
   (i.e. the guest should ignore the event when 0 is returned,
   or consider a different button pressed/released,
   when the returned value differs from data.mouse.usButtonFlags);
   NOTE: guests that forward events via RP_IPC_TO_HOST_RAWINPUT_EVENT
   must set the RP_FEATURE_RAWINPUT_EVENT flag
   in the startup RP_IPC_TO_HOST_FEATURES message
Data sent:
   LPARAM = the LPARAM received with the WM_INPUT message
Response:
   RawInput RI_MOUSE_BUTTON_* flags or 0


Message:
   RP_IPC_TO_HOST_MOUSEMOVE
Description:
   the guest sends this message to forward mouse move events;
   mouse events forwarding is off by default and is enabled
   by the RP_IPC_TO_GUEST_SENDMOUSEEVENTS message;
   when mouse events are forwarded to the host,
   they are not used by the emulated system;
   the screen coordinate range is the same used for screen overlays
   (e.g. lLeft and lTop fields of the RPSCREENOVERLAY structure)
Data sent:
   LPARAM = screen coordinates combined with the MAKELONG macro (i.e. MAKELONG(x,y))
Response:
   none


Message:
   RP_IPC_TO_HOST_MOUSEBUTTON
Description:
   the guest sends this message to forward mouse button events;
   mouse events forwarding is off by default and is enabled
   by the RP_IPC_TO_GUEST_SENDMOUSEEVENTS message;
   when mouse events are forwarded to the host,
   they are not used by the emulated system;
   the screen coordinate range is the same used for screen overlays
   (e.g. lLeft and lTop fields of the RPSCREENOVERLAY structure)
Data sent:
   WPARAM = mouse buttons state
            (flags: RP_MOUSE_BUTTON_LEFT, RP_MOUSE_BUTTON_RIGHT, RP_MOUSE_BUTTON_MIDDLE)
   LPARAM = screen coordinates combined with the MAKELONG macro (i.e. MAKELONG(x,y))
Response:
   none


Message:
   RP_IPC_TO_HOST_TEXT_CURSOR_INFO
Description:
   when virtual mouse is enabled, the guest send RP_IPC_TO_HOST_TEXT_CURSOR_INFO
   messages to the host, in order to provide information about the text cursor
   and some cursor-related screen and mouse data;
   this information is not sent at every mouse move, but only when the mouse
   hovers a new character position (e.g. dwCursorColumn and/or dwCursorRow field
   is different, compared to the previously sent data), or when the mouse
   is moved outside of the text area
Data sent:
   pData = a RPTEXTCURSORINFO structure (see RetroPlatformIPC.h)
Response:
   none


Message:
   RP_IPC_TO_HOST_EXECUTE_RESULT
Description:
   this message notifies the host that a program, previously launched via
   the RP_IPC_TO_GUEST_EXECUTE message, has terminated its execution;
   this notification is only sent when one of the
   RP_EXECUTE_RETURN_EXIT_CODE and RP_EXECUTE_RETURN_OUTPUT flags is set
   in the RPEXECUTEINFO structure of the RP_IPC_TO_GUEST_EXECUTE message;
   the dwExecuteID field of the structure sent with this notification
   references the ID that the host specified in the
   RP_IPC_TO_GUEST_EXECUTE message
Data sent:
   pData = a RPEXECUTERESULT structure (see RetroPlatformIPC.h)
Response:
   none


Messages:
   RP_IPC_TO_HOST_PRIVATE_*
Description:
   these are private messages, sent by code in RPGuest.dll



****************************************************************************
 Host-to-Guest Messages
****************************************************************************

Message:
   RP_IPC_TO_GUEST_CLOSE
Description:
   sent from the host when the emulation must be terminated
   (e.g. the user has hit the close button in the host window);
   the guest should destroy its window and terminate (see Response below)
Data sent:
   none
Response:
   LRESULT = 1 if the guest can safely terminate or 0 otherwise


Message:
   RP_IPC_TO_GUEST_SCREENMODE
Description:
   this message is sent to ask the guest to activate a specified screen mode
   and clipping coordinates;
   when switching to the new screen mode, the guest can resize (reuse) its window
   or close its window and open a new one;
   if output to a secondary display is requested, and only one
   display is available, or more than two displays are available,
   it is up to the guest to gracefully choose a display
Data sent:
   pData = a RPSCREENMODE structure, with screen mode values/flags
   and clipping coordinates (the hGuestWindow field is ignored);
   as regards the clipping coordinates, the fields set to 0 means "reset"
   (no offset for lClipLeft/lClipTop, maximum size if lClipWidth/lClipHeight)
   and fields set to -1 are ignored (left unchanged); units are in pixels;
   for Amiga systems, where pixels may have different sizes, horizontal
   units are in superhires pixels (4 x lores) for Amiga modes, and
   vertical units are in interlaced pixels (2 x non-interlaced), whereas
   RTG pixels are always 1:1
Response:
   LRESULT = handle of the (new) guest window
             or NULL (the screen mode couldn't be changed)
             or INVALID_HANDLE_VALUE (the screen mode will be changed asynchronously
             and the host will soon get a RP_IPC_TO_HOST_SCREENMODE notification)


Message:
   RP_IPC_TO_GUEST_SCREENCAPTURE
Description:
   with this message the host asks the guest to save its screen bitmap(s)
   (raw and/or filtered version) to the specified file(s), in BMP format.
Data sent:
   pData = a RPSCREENCAPTURE structure with one or two full path(s) and name(s)
            (Unicode) of the file(s) to save. Note: existing files can be
            overwritten.
Response:
   LRESULT = RP_GUESTSCREENFLAGS_ if the guest successfully saved the
             bitmap(s) to the file(s) or RP_SCREENCAPTURE_ERROR otherwise


Message:
   RP_IPC_TO_GUEST_PAUSE
Description:
   the RP_IPC_TO_GUEST_PAUSE message sets the guest into pause mode
   or resumes the guest from pause mode;
   note: when paused, the guest should release the mouse (if captured) and,
   in fullwindow mode, the Windows mouse cursor should be made visible;
   during pause mode, the mouse should never be captured
Data sent:
   WPARAM = non-zero to set the guest into pause mode
            or zero to resume the guest from pause mode
Response:
   LRESULT = 0 (error), 1 (command successfully executed)
             or 2 (the command will be asynchronously executed
             and a RP_IPC_TO_HOST_PAUSE will be later sent from the guest
             to confirm execution)


Message:
   RP_IPC_TO_GUEST_DEVICECONTENT
Description:
   the host sends a RP_IPC_TO_GUEST_DEVICECONTENT message
   to load an image file or a peripheral into an emulated device
   (e.g. an ADF floppy file into a floppy drive,
   or a joystick into an input port)
   or to unload the currently loaded content from the device
Data sent:
   pData = a RPDEVICECONTENT structure (see RetroPlatformIPC.h);
           if the szContent field of the structure
           contains an empty string, or if
           btDeviceCategory == RP_DEVICECATEGORY_INPUTPORT and
           dwInputDevice == RP_INPUTDEVICE_EMPTY, the guest should
           unload the current content from the device;
Response:
   LRESULT = 1 if the guest successfully executed the command or 0 otherwise


Message:
   RP_IPC_TO_GUEST_DEVICEREADWRITE
Description:
   the host sends a RP_IPC_TO_GUEST_DEVICEREADWRITE message
   to set the read/write protection status
Data sent:
   WPARAM = device category (RP_DEVICE_* value) and device number
            combined with the MAKEWORD macro;
            e.g. MAKEWORD(RP_DEVICECATEGORY_FLOPPY, 0)
   LPARAM = current device read/write status flags (RP_DEVICE_READONLY/RP_DEVICE_READWRITE)
Response:
   LRESULT = 1 if the guest successfully executed the command or 0 otherwise (for example, because the image file itself is read-only, so that writing is not possible)


Message:
   RP_IPC_TO_GUEST_RESET
Description:
   the host sends this message to reset the guest
Data sent:
   WPARAM = a RP_RESET_* value
Response:
   LRESULT = 1 if the guest successfully executed the command or 0 otherwise


Message:
   RP_IPC_TO_GUEST_TURBO
Description:
   the host sends this message to activate or deactivate
   the turbo mode of selected guest functionalities
Data sent:
   WPARAM = mask of functionalities to change (RP_TURBO_* flags)
   LPARAM = bits corresponding to those set in WPARAM
            (1 = speedup the guest functionality
             0 = revert to normal speed emulation)
Response:
   LRESULT = 1 if the guest successfully executed the command or 0 otherwise


Message:
   RP_IPC_TO_GUEST_PING
Description:
   this is a no-operation message and can be sent
   to check if the guest is responsive and functional
Data sent:
   none
Response:
   LRESULT = non-zero value is returned


Message:
   RP_IPC_TO_GUEST_VOLUME
Description:
   the host uses the RP_IPC_TO_GUEST_VOLUME message to set
   the audio level of the guest
Data sent:
   WPARAM = volume level (min 0, max 100)
Response:
   LRESULT = 1 if the guest successfully set the volume as requested or 0 otherwise


Message:
   RP_IPC_TO_GUEST_ESCAPEKEY
Description:
   the host uses the RP_IPC_TO_GUEST_ESCAPEKEY message
   to change the escape key information
Data sent:
   WPARAM = DirectInput DIK_* identifier of the escape key
            (e.g. 1 for the Esc key - see DIK_* constants in dinput.h)
   LPARAM = milliseconds value
            (amount of time the user has to hold the above key to trigger the escape functionality)
Response:
   LRESULT = 1 if the guest successfully accepted the new settings or 0 otherwise


Message:
   RP_IPC_TO_GUEST_EVENT
Description:
   the host uses the RP_IPC_TO_GUEST_EVENT message
   to simulate keyboard, mouse, joystick, tape button press/release
   and other guest-specific events
Data sent:
   pData = (Unicode) event string.
   Keyboard events are "KEY_RAW_DOWN <x>" and "KEY_RAW_UP <x>" strings, where <x>
   is a keycode that uniquely identifies the raw key on the guest system,
   independently of higher-level layout (e.g. Amiga SetMap). On the Amiga, <x> would
   be one byte. By default, <x> is decimal. Prefix hexadecimal values with "0x".
   It is up to the host to do the appopriate mappings and request the correct raw guest
   event, taking into account host and guest layouts.
   Other events may be named as per cloanto.com/specs/ianames.
   Multiple events are space-separated (e.g. "KEY_RAW_DOWN 0x60 KEY_RAW_UP 0x60").
   The guest should stop parsing the event string and return 0,
   if an unrecognized event is ecountered.
   The guest should take care of not executing too many keyboard events
   if the keyboard buffer of the emulated system may reach its limit.
   In this case, the guest may asynchronously execute the event string
   and merge additional incoming RP_IPC_TO_GUEST_EVENT event strings
   to the waiting-to-be-executed event string (or the part of it that
   remains to be executed).
Response:
   LRESULT = 1 if the guest successfully simulated the specified events or 0 otherwise


Message:
   RP_IPC_TO_GUEST_GUESTAPIVERSION
Description:
    the host can send a RP_IPC_TO_GUEST_GUESTAPIVERSION to query the guest
    about the RetroPlatform API version it implements;
    this message can be used to check the guest API version
    and enable optional functionality
Data sent:
   none
Response:
   LRESULT = major and minor version combined with the MAKELONG macro
             (e.g. LOWORD(lr) = major version; HIWORD(lr) = minor version)


Message:
   RP_IPC_TO_GUEST_MOUSECAPTURE
Description:
   the host uses this message to ask the guest
   to capture or release the mouse (and activate/deactivate the magic mouse functionality)
Data sent:
   WPARAM = mouse capture state being requested (RP_MOUSECAPTURE_* flags)
Response:
   LRESULT = 1 if the guest successfully executed the command or 0 otherwise


Message:
   RP_IPC_TO_GUEST_SAVESTATE
Description:
   with this message the host asks the guest to save
   the emulation status to the specified file
Data sent:
   pData = (Unicode) full path and name of the file to save
Response:
   LRESULT = 1 if the guest successfully saved the status file or 0 otherwise


Message:
   RP_IPC_TO_GUEST_LOADSTATE
Description:
   with this message the host asks the guest to load
   the emulation status from the specified file
Data sent:
   pData = (Unicode) full path and name of the file to load
Response:
   LRESULT = 1 if the guest successfully loaded the status file or 0 otherwise


Message:
   RP_IPC_TO_GUEST_FLUSH
Description:
   the host sends the RP_IPC_TO_GUEST_FLUSH command to ask the guest
   to flush any change applied to the emulated media
   and update the corresponding image files
Data sent:
   none
Response:
   LRESULT = 1 if all data was flushed (the guest successfully executed the command or no flush was necessary) or 0 otherwise


Message:
   RP_IPC_TO_GUEST_QUERYSCREENMODE
Description:
   this message is used to ask the guest to send
   a RP_IPC_TO_HOST_SCREENMODE notification as soon as possible
   with updated screen mode and clipping information
Data sent:
   none
Response:
   LRESULT = 1 if the guest acknowledged the command or 0 otherwise


Message:
   RP_IPC_TO_GUEST_DEVICEACTIVITY
Description:
   this message is used to tell the guest about a device status change
   (e.g. a button pressed or released on a joystick)
Data sent:
   WPARAM = device category (RP_DEVICE_* value) and device number
            combined with the MAKEWORD macro;
            e.g. MAKEWORD(RP_DEVICECATEGORY_INPUTPORT, 1);
            the macro LOBYTE(wParam) should be used to get the category value
            and HIBYTE(wParam) should return the device number;
            the only categories used at the moment are
            RP_DEVICECATEGORY_INPUTPORT and RP_DEVICECATEGORY_MULTITAPPORT
            (device number is the input port number)
   LPARAM = if the message references a RP_DEVICECATEGORY_INPUTPORT
            or a RP_DEVICECATEGORY_MULTITAPPORT port
            in which a joystick/gamepad/joypad is plugged,
            then the data sent via LPARAM is a mask of RP_JOYSTICK_* values
            reporting all the buttons that are pressed (more than one may be
            pressed simultaneously)
Response:
   LRESULT = 1 if the guest acknowledged the command or 0 otherwise


Message:
   RP_IPC_TO_GUEST_SHOWOPTIONS
Description:
   This message is used to ask the guest to open its options/settings dialog.
   Before opening the dialog, the guest should send RP_IPC_TO_HOST_PAUSE message to pause the emulation session.
   After closing the dialog, the emulation should be resumed by sending another RP_IPC_TO_HOST_PAUSE message.
Data sent:
   None
Response:
   LRESULT = 1 if the guest acknowledged the command or 0 otherwise


Message:
   RP_IPC_TO_GUEST_SCREENOVERLAY
Description:
   This message creates a screen overlay (an image that the guest
   renders on top of the emulated system screen).
   Multiple screen overlays can be simultaneously displayed on the screen,
   and the dwIndex field of the RPSCREENOVERLAY structure determines
   their priority (overlays with higher index are displayed
   in front of overlays with lower index);
   NOTE: guests that support screen overlays must set the
   RP_FEATURE_SCREENOVERLAY flag in the startup RP_IPC_TO_HOST_FEATURES message.
Data sent:
   pData = a RPSCREENOVERLAY structure containing overlay information and image data
Response:
   LRESULT = 1, if the guest successfully executed the command, or 0 otherwise


Message:
   RP_IPC_TO_GUEST_MOVESCREENOVERLAY
Description:
   This message moves a previously defined screen overlay to a specified position.
Data sent:
   WPARAM = screen overlay index
   LPARAM = screen coordinates combined with the MAKELONG macro (i.e. MAKELONG(x,y))
Response:
   LRESULT = 1, if the guest successfully executed the command, or 0 otherwise


Message:
   RP_IPC_TO_GUEST_DELETESCREENOVERLAY
Description:
   This message deletes a previously defined screen overlay.
Data sent:
   WPARAM = screen overlay index
Response:
   LRESULT = 1, if the guest successfully executed the command, or 0 otherwise


Message:
   RP_IPC_TO_GUEST_SENDMOUSEEVENTS
Description:
   The host sends this message to ask the guest to enable/disable
   mouse events forwarding; this is typically done when the emulation is paused
   and the host wnats to handle mouse navigation of screen overlays;
   see RP_IPC_TO_HOST_MOUSEMOVE and RP_IPC_TO_HOST_MOUSEBUTTON
   for additional information.
Data sent:
   WPARAM = set to 1 to enable mouse events forwarding, or 0 to disable it
Response:
   LRESULT = 1 if the guest acknowledged the command or 0 otherwise


Message:
   RP_IPC_TO_GUEST_SHOWDEBUGGER
Description:
   This message is used to ask the guest to open its debugger dialog.
   If the dialog pauses the emulation, the guest should send a RP_IPC_TO_HOST_PAUSE message
   to notify the host about that (and when the emulation is resumed,
   at dialog-close time, a new RP_IPC_TO_HOST_PAUSE notifications should be sent).
Data sent:
   None
Response:
   LRESULT = 1 if the guest acknowledged the command or 0 otherwise


Message:
   RP_IPC_TO_GUEST_WRITESTRING
Description:
   The host sends this message to ask the guest to write a string
   (e.g. by calling an output function or by inserting the string
   in the system keyboard buffer).
Data sent:
   pData = an null-terminated string based on the emulated system character set (typically 8-bit)
Response:
   LRESULT = 1 if the guest acknowledged the command or 0 otherwise


Message:
   RP_IPC_TO_GUEST_TRIGGER_TRAP
Description:
   The host sends this message to ask the guest to execute a callback function
   where it is possible to read and/or write the memory of the emulated system.
   Based on the guest implementation and on the specified RP_TRAPF_* flags,
   the callback function may by called synchronously or asynchronously.
Callback function:
   When the function is called, its dwFlags argument contain only one of the
   RP_TRAPF_SYNC_MODE and RP_TRAPF_ASYNC_MODE flags (stating how the function has been called)
   and the lParam1 argument contains the value specified in the lCallbackParam field
   of the RPTRAPDATA structure.
   The code can read the emulated system memory (if RP_TRAPF_READ_ACCESS was specified)
   calling pfnReadMemory(dwAddress, dwSize, pdwValue, lParam1, lParam2)
   (where dwAddress is the memory address to read from,
    dwSize is the bit size of the value to read - e.g. 8 for 8-bit value,
    pdwValue is the address receiving the read result,
    lParam1 is an optional guest-specific custom value (e.g. memory bank),
    lParam2 is the lParam2 argument passed to the callback function)
   or can write memory (if RP_TRAPF_WRITE_ACCESS was specified)
   calling pfnWriteMemory(dwAddress, dwSize, dwValue, lParam1, lParam2)
   (where dwAddress is the memory address to write to,
    dwSize is the bit size of the value to write - e.g. 8 for 8-bit value,
    dwValue is the value to write to the specified address,
    lParam1 is an optional guest-specific custom value (e.g. memory bank),
    lParam2 is the lParam2 argument passed to the callback function)
Data sent:
   pData = an RPTRAPDATA structure where
           dwFlags contains a combination of RP_TRAPF_* flags,
           pfnCallback is the address of the function to be called,
           lCallbackParam is the value passed as lParam1 to the callback function
Response:
   LRESULT = RP_TRAP_UNSUPPORTED (this functionality is not supported) or
             RP_TRAP_OK_SYNC (the function was called synchronously) or
             RP_TRAP_OK_ASYNC (the function was called asynchronously) or
             RP_TRAP_SYNC_NOT_POSSIBLE (RP_TRAPF_SYNC_MODE only was requested, but it is not allowed) or
			 RP_TRAP_ASYNC_NOT_POSSIBLE (RP_TRAPF_ASYNC_MODE only was requested, but it is not allowed) or
             RP_TRAP_ERROR (an unspecified orror occurred)
          

Messages:
   RP_IPC_TO_GUEST_SET_CURSOR_POSITION
Description:
   This message is sent to ask the guest to move the text cursor
Data sent:
   WPARAM = cursor column and row combined with the MAKELONG macro;
            e.g. MAKELONG(0, 1) to set the cursor at the first column
            of the second screen row
Response:
   LRESULT = 1 if the guest acknowledged the command or 0 otherwise


Message:
   RP_IPC_TO_GUEST_EXECUTE
Description:
   The host sends this message to execute a program on the emulated system.
   In case the RP_EXECUTE_RETURN_EXIT_CODE flag or the RP_EXECUTE_RETURN_OUTPUT flag
   is set, the guest will send a RP_IPC_TO_HOST_EXECUTE_RESULT notification to the host,
   when the launched program terminates.
   The program can either be referenced via the szFile array, or its data may follow
   the RPEXECUTEINFO structure in the data of this message (in such a case,
   the dwFileDataSize and dwFileDataOffset fields are properly set to
   reach the program binary data).
Data sent:
   pData = a RPEXECUTEINFO structure, optionally followed by program binary data.
Response:
   LRESULT = 1, if the guest successfully executed the command, or 0 otherwise


Messages:
   RP_IPC_TO_GUEST_PRIVATE_*
Description:
   these are private messages, received by code in RPGuest.dll;
   they never reach the message function in guest code.
